# About Tobira

Tobira is the free, open-source video portal for Opencast.

## General functionality

The video portal can see at least three different personas:

- lurker: users without special privileges allowed to consume media
- are there users with or without login but without creator privileges?
- they have no “my video” area
- lukers are non-creators
- creators: users who have logged in to tobira and can upload/manage videos
- can add content to their “my videos” area
- can be authorized to modify sub-realms and their content blocks
- administrators: users who are logged in and are allowed to modify all data
- can do anything creators can everywhere
- can configure Tobira

## Site structure

Tobira has several areas with user may or may not see based on their login status and the privileges they are given.

### Landing page

The landing page is what users see when they access the video portal.
This is their first impression of the video portal.
It is meant to show off

- The root [realm](#Realm-structure) element
- Behaves mostly like an ordinary realm with a few exceptions:
- CANNOT be deleted
- MUST be public
- Is pre-populated with a video block configured to contain the newest public videos (see [video types](#Video-types)) after installation

### Realm structure

The realm structure defines the pages and sub-pages of the video portal.

- It consists of the landing page and an arbitrary amount of sub-realms.
- Each realm can hold an arbitrary amount of [content blocks](#Content-blocks).
- A realm includes a navigation linking all sub-realms
- The order of subrealms in this navigation needs to be configurable by users/admins.
- The realm structure defines the URL of a given category or video.

A realm is defined by:

- MUST have a public name
- MUST have an path segment
- The path segment MUST have at least two characters

An example realm structure could look like this:

> - Home (Landing page) (`/` [`r`])
> - Biology (`bio`)
> - Computer Science (`cs`)
> - Theoretical Computer Science (`theo`)
> - App Development (`app`)
> - Hardware Development (`hw`)
> - Mathmatics (`math`)
> - Algebra (`algebra`)
> - Analysis (`analysis`)
> - Philosophy (`phil`)

Given this example, here are a few URLs for accessing specific video portal realms:

> - Home → Computer Science → Hardware Development
> - https://tobira.opencast.org/r/cs/hw
> - Home → Mathmatics → Algebra
> - https://tobira.opencast.org/r/math/algebra

#### Questions

- Do access control lists for realms exist?
- Can I block access to a realm for non authorized users?
- Student A has access to “Biology 101” but not to “Secrets of Philosophy”
- Secret “Conference of Business Things” for which you need to log in to be able to see it

### Content blocks

Without content, the realm structure is just a set of empty pages.
Content blocks define how pages look like and what content they hold.
Users can select from different [content block types](#Content-block-types) and add these to realms.

- Content blocks may hold different media
- video player
- list of videos
- text
- …
- Content blocks can be edited and configured
- Content blocks have an order

### Video pages

A video page is a realm with a video content block.
Video pages are rendered on the fly if…

- The parent realm includes an [Opencast series content block](#Opencast-series) which includes that video
- The given video identifier exists
- The user has access according to the access control list

Additional, all videos can be rendered using the _special_ root video URL `/v/<id>`. This is meant to allow for hidden videos with no context and will render no realm navigation.

A video page always lives under the intermediate path segment `v` which easily identifies that on-thy-fly rendering needs to happen. For example, given that an Opencast series block is included in the realm `/math/algebra` and the series includes a video with the identifier `video-a`, the video will be available at `/math/algebra/v/video-a` without the need of manually creating this page.

#### Optional improvement: Video page extension

_Important: This will not be available in the first version of Tobira_

Since a video page is nothing but a realm with an embedded video block, we could convert it to a full realm and have people edit and extend it with additional content blocks.

### Video and Metadata editing

On any video page, given a user has the necessary privileges, a button “Edit episode” will be shown. Clicking this button will lead the user to the edit mode.

The edit mode will allow users to

- Modify video metadata
- Set access control lists by allowing pre-defined groups
- These groups internally map to Opencast roles
- Access the Opencast video editor
- Delete episode

#### Open question

- We could also not have this page and link to the video editor directly.
- It already allows setting metadata.
- We would need a mechanism of letting Tobira know immediately that something has changed
- We would need a way of setting access control in the editor
- If we delete an episode, will it be deleted along with the [Opencast video content blocks](#Opencast-video) including the episode?

### User area

The user area allows authorized users to manage and present their own media content. The area is clearly separated from the main video portal area:

- It MUST NOT be part of the main navigation.
- Videos contained only in this area MUST NOT be found via global search

The area is split into two sub-pages:

- A [user realm](#User-realm) to present media
- A management and creator area called [“My videos”](#My-videos)

### User realm

The user realm is similar in structure and functionality to the main video portal area in that it can be structured and different [content block types](#Content-block-types) can be used to present content.

The user realm is available at `/u/<userid>` and is equivalent to the public channel on YouTube.

### My videos


The “my videos” area is meant for users to upload, manage, modify and delete their own content. The area contains a list of the users content and links a set of tools for creating, modifying and managing video content.

- The section is available at `/manage`
- The content stream covers the main part of this area.
- Initially abailable tools are:
- Opencast Studio
- Video upload

#### Open Questions

- Does the content stream contain everything a user has write access to or do these episodes have a specific marker/owner?
- Are all user recordings part of a specific series?
- Can users move content to another series?
- E.g. as a user I have write access to the “Biology 101” realm, can I create a recording and then move it from my personal space to the “Biology 101” realm?

### Upload tool

The upload tool allows users to upload media to Opencast for processing. It is available for authenticated users with certain priviledges.

- Upload
- It MUST allow users to upload a single video file
- Data SHOULD be transferred directly to Opencast
- It SHOULD allow users to upload multiple video streams
- It SHOULD allow users to upload additional attachments
- It MAY allow users to select a thumbnail
- Metadata
- It MUST allow editting DC metadata
- It SHOULD allow editting configurable matadata catalogs
- It SHOULD allow edditing metadata while files are already being uploaded

## Managing videos in Opencast and Tobira

Tobira gets all content from Opencast.
Opencast knows about two main structural elements:

- An episode contains a media package linking media from one event. The media may include several video streams (e.g. presenter and presentation) in multiple qualities and formats as well as additional attachments like preview images or presentation slides.
- A series groups multiple episodes, indicating that they all share the same connection to a topic like being from a single school course.

New recordings need to be included in Tobira by specifying the realm in which they are included. In most cases this will just be an empty realm with an [Opencast series content block](#Opencast-series) including the videos.

Adding episodes or series can happen in Opencast's or Tobira's interface.

- ___Implementation note:__ We will focus on esablishing the connection from Tobira first_

### Including Opencast content from Tobira

Given a user has write access to a specific realm, a user can include Opencast media by:

- Navigating to the target realm
- Switching to edit mode
- Selecting a content block to add:
- [Opencast video](#Opencast-video) to include a single episode embedded in that realm page
- [Opencast series](#Opencast-series) to include a list with all episodes in that realm page
- It SHOULD be possible to create an Opencast series during this process
- Configuring the content block by selecting the desired episode/series
- Saving the realm page

Example:

> - Jane wants to add the Opencast series “Algebra Basics (2021)” to “Home” → “Mathmatics” → “2021” → “Algebra”
> - In Tobira, she navigates to “Home” → “Mathmatics” → “2021”. “Algebra” does not yet exist.
> - She has the necessary privileges to edit this page and will see the button “Add sub-page” which she clicks
> - She creates and saves a new page “Algebra” to which she is redirected
> - She has the necessary privileges to edit this page and will see the button “Edit page” which she clicks
> - She clicks “Add content block”
> - She selects the block type “Opencast series”
> - She selects the Opencast series “Algebra Basics (2021)” from the drop-down
> - She saves the page.
> - The Opencast series in now connected

### Adding content from Opencast

_This is meant for later. We will implement the other data flow direction first._

Adding content from Opencast directly most likely happens for automated recordings (e.g. lecture captures). These should usually be part of a series and will as such automatically show up in Tobira if a realm includes an [Opencast series content block](#Opencast-series).

To help Opencast administrators and allow for an easier initial placement of a series in the Tobira realm tree, a realm to contain the series CAN be selected or created as part of the “Create series” wizard in the Opencast user interface.

Example:

> - John wants to automatically record the university course “Algebra Basics” and publish the recordings to Tobira.
> - He has the necessary Opencast capture agent set up
> - He navigates the Opencast admin interface's series tab and clicks “Add series”
> - He sets the title “Algebra Basics (2021)” and continues through the wizard until he hits the page “Video portal”
> - In the wizard, he selects the realm “Home” → “Mathmatics” → “2021”
> - The sub-realm “Algebra” does not yet exist
> - He clicks “Add sub-realm” and sets the title to “Algebra”
> - He clicks “Select” and finishes the wizard
> - The following entities will be created automatically:
> 1. An Opencast series
> 2. The realm “Algebra”
> 3. An Opencast series content block in the realm

#### Optional: Events

Later we MAY add a similar wizard to the “Add event” wizard to allow for directly adding single video content blocks to realms.

## Features

### Content block types

Content blocks define how a realm page looks like. We will likely add more content blocks over time when extending Tobira. These are the ones to start with.

#### Opencast video

Includes a singe episode from Opencast into the realm page. The video will be directly embedded in the realm page.

Configuration options for this block:

- Episode identifier (required)
- Optional: Download available (default: yes)
- Optional: Player to use for presentation

#### Opencast series

Includes a list of all episodes of an Opencast series similar to [Opencast's series LTI tool](https://develop.opencast.org/ltitools/index.html?subtool=series) and links to the video pages for those episodes available at `…/v/<identifier>`.

Configuration options for this block:

- Series identifier (required)
- Optional: Display mode (tiled, list; default: list)

#### Video list

Lists a number of episodes similar to the Opencast series content block but selects the videos according to a simple search pattern. Links to the video page of the realm the episodes series is included in or to the global video area otherwise.

Configuration options for this block:

- Mode (newest, search; default: newest)
- Only public (default: yes)
- Max episodes (default: 9)

#### Manual video list

Lists a number of episodes similar to the Opencast series content block but lets the user select these videos manually. Links to the video page of the realm the episodes series is included in or to the global video area otherwise.

Configuration options for this block:

- List of Opencast episode identifier

#### Text

Includes Markdown formatted text which is rendered as HTML.

Configuration options for this block:

- A text block

### Search

TODO: Describe search

## Glossary

### Video types

- Public video
- MUST be embedded in the public realm structure
- User video
- MUST be embedded in the user realm structure
- MUST NOT be embedded in the public realm structure
- Hidden video
- MUST NOT be embedded in any realm structure
- Unprotected video
- MUST have an access control list entry allowing anonymous read access
- Protected video
- MUST NOT have an access control list entry allowing anonymous read access
- MUST be embedded in the public realm structure

---

## Open questions

### Can an Opencast series be included in two realms?

This is mainly a question about ownership. Videos and video series can always be linked, but do they belong to a specific place. To explain the ownership problem, lets take a look at the following example:

- J. Doe creaes an Opencast series “Cat Videos”
- The series is now included _in some way_ in “Home” → “Biology”
- The series is also included _in some way_ in “Home” → “Chemestry”

#### If there must be exactly one owner, then:

- The series is included in “Home” → “Biology” using the Opencast series content block
- “Biology” now owns the series
- A user can go to “Home” → “Biology” → “Tabby Cat” and watch an adorable cat video
- The user is still in the realm “Biology” and can explore more video in this realm
- The series is included in “Home” → “Chemestry” using the video list content block
- A user can go to “Home” → “Chemestry” → “Tabby Cat” and watch an adorable cat video
- The user switched/was redirected to the realm “Biology” and no “Chemistry” content is listed

#### If there can be multiple owners, then:

- The series is included in “Home” → “Biology” using the Opencast series content block
- A user can go to “Home” → “Biology” → “Tabby Cat” and watch an adorable cat video
- The user is still in the realm “Biology” and can explore more video in this realm
- The series is included in “Home” → “Chemestry” using the Opencast series content block
- A user can go to “Home” → “Chemestry” → “Tabby Cat” and watch an adorable cat video
- The user is still in the realm “Chemestry” and can explore more video in this realm

#### Considerations

- __Pro multiple inclusions:__
- We are more flexible
- Users can re-use series for another area
- You don't have to find out where a series is already in use if a user wants to include it somewhere else
- Users don't get redirected somewhere else
- __Contra multiple inclusions:__
- Makes the structure and code more complex
- A featured video may appear in two realms. Which realm to link?
- Series selections may be shorter (we can filter out series which are already somewhere in use)
- If we had a single owner, a link `/v/<id>` (at the root) could be a short link the forwards to `/the/owner/realm/v/<id>`.

**Potential problems with multiple inclusions**
- Video Statistics: if a video is included in multiple realms, are statistics (watch time, clicks, likes, ...) recorded for each realm separately? Or just per video? Potentially lots of confusing behavior!
- IF we can restrict access to realms to specific roles, and IF we want videos uploaded/included in this realm to derive those access restrictions -> what happens if the same video is included somewhere else?
- When searching for the video title: how to display a video included into two realms in the search results? If only included once, clicking the video in the search result should bring you to `/biology/foo/v/<id>`, right?
- If not properly communicated, moderators could *embed* (instead of *link*) a video in some "featured" area. But then the video has an url like `/featured/v/<id>` and as soon as the video stops being featured, the URL does not work anymore.

Story A (Pro multiple inclusions):

> - A lecturer prepares a series with general information
> - How do tests work
> - How does the coding platform they use work
> - How to best contact tutors
> - The lecturer includes this series in
> - “Home” → “Computer Science” → “Computer Science 101”
> - “Home” → “Computer Science” → “Introduction to Python”

Story B (Pro single inclusion)

> - In 2021, a user navigates to “Home” → “Languages” → “2021” → “Modern English”
> - The user includes the Opencast series “Modern English”
> - In 2023, a new Opencast series “Modern English” is created
> - A user navigates to “Home” → “Languages” → “2023” → “Modern English”
> - The user includes the Opencast series “Modern English”
> - The 2021 series cannot be selected since it's already included somewhere

---

## Notes to myself (Lars)

- Mention live streaming although for tobira there is no difference to a non-live event
- Mention design options for the sys admin
- Mention file attachments (maybe I already did)
- Describe ownership
- Open question about video statistics
- Need to define this
- Mark as low-priority
- [Related Google Docs document](https://docs.google.com/document/d/1W2sJj0K0xGuh1H7mhASDfwp1b5mWraVEJbFnGfl7jzU/edit?usp=sharing)
- Löschen von Events
- Wer darf wo loschen
- Page for series?
- `/s/<id>`