Document owners: Glib Glugovskiy Mariia Moskalenko
The goal of the document
Clarify and specify requirements and use cases needed to be covered by the new video player. Define approaches to the use cases and make high-level decisions on the solution for them (it can be a high-level solution approach or ADR for some).
Context
Non-functional requirements and use cases were discovered through the document analysis of the Approach Memo & Technical Discovery: React-based Video Player, exploration of the latest Open edX release (Palm) UI and back-end with feature flags for the video player and new studio on the MFE, new studio design, community feedback, project stakeholders' feedback.
Glossary
Open edX | is a service-oriented platform for authoring and delivering online learning at any scale |
edX platform | LMS and CMS services of Open edX |
Video component | Current vanila JS video player xblock that is used in edx-platform |
New video player | ReactJS implementation of the video block based on video.js library |
New Video xblock | New xblock with ReactJS frontend and Python backend (that is refactored version of Video Block), it should be backward compatible with Video Component |
New video editor | the new design with the new user experience of the live video preview |
Quality attributes and non-functional requirements
The structure can be changed during the discovery.
Priorities:
HIGH - requirements are needed for the beta-testing (for 10 courses on edx.org)
MEDIUM - requirements are needed for the launch, but not crucial for beta-testing
LOW - requirements can be added later as a plug-in or developed by community members
Quality attribute/Rules | Initial requirement from the Approach Memo & Technical Discovery: React-based Video Player | Non-functional requirement | Priority | Target Milestone | Outputs | Approach |
|---|---|---|---|---|---|---|
Compatibility | Video.js video player has to be used as a new player in Open edX as the best option due to the discovery among several options | Each feature has to be implemented using a Video.js technology. | HIGH | -- | In the video xBlock the new React.js frontend will be introduced | |
Compatibility | The player is FOSS and compatible with the Open edX platform’s software license | Each feature has to be implemented using a Video.js Library. Video.js Library was selected as the implementation for video player, it alligned with Open edX platform’s software license. | HIGH | -- | ||
Compatibility | The video player is layer upon layer upon layer of crufty compatibility code. We could probably make something a lot simpler overall if we created a new XBlock entirely and migrated video data over to it, though that would make gradual rollout/rollback more difficult | The new video player has to replace the old version completely. The new video player has to have a data migration plan (maybe some scripts which can be used for general migration cases). The migration should be seamless and ensure that no data is lost or corrupted during the transfer. The new video player has to be implemented in a way that during the upgrade to the new version of the Open edX developer will be able to test the new video player with existing videos and rollback to the new version in case of unexpected difficulties. There has to be a way to get a feedback from the community about the new video player to fix bugs and issues. | HIGH | Suggested approach for new video player installation and migration. | ||
Compatibility | Make it so that the new video player has a simple, sane data model to follow, and write a terrible shim layer to convert (up front and in one place) the layers of old terrible into the format the new system expects. | The goal is to introduce the new feature without additional effort from the end-users side.
The new video player has to work with the old video player data model so that users of the new player will not do any additional migration steps. | HIGH | Suggested approach for new video player installation and migration. | ||
Compatibility | New videos can just persist that new, sane data model, while old ones get converted as needed. | New video player has to coexist with the old version and some videos can be processed through the old version of the video player, while some of them will be processed through the old version of the video player. | HIGH | Suggested approach for new video player installation and migration. | ||
Compatibility | Most backwards compatibility is focused on not breaking content, even as we discover and implement better ways to do things. | If the user used the content (uploaded it) on the old version of the video player then the user should be able to continue working with the old version of the video player. The new video player will be available for the new content. | HIGH | Suggested approach for new video player installation and migration. | ||
Seamlessness | Ideally, this is a drop-and-replace player within the current XBlock, such that instances upgrading the version of the block would get the player across all courses with no intervention If this proves to be difficult, what would be the plan for a new XBlock + migration plan to the new block? How much more/less difficult is this? | Seamless migration to the new version of the video player from the old version. If there is no possibility for seamless migration - a migration plan has to be created. | HIGH | Suggested approach for new video player installation and migration. | ||
Compatibility | The legacy LMS frontend uses a way out-of-date version of React, so getting a new video player working within the iframe may present its own challenges. However, an upgrade of React in the legacy LMS frontend is on the Roadmap. | Video player has to be rendered in legacy LMS frontend or there has to be an option to use the old version of the video player for legacy LMS frontend. | HIGH | Suggested approach for new video player installation and migration. | ||
Extensibility | It needs to be a Javascript-based component Almost certainly, it needs an HTML5 video component base | Video player has to be based on HTML5 and use Javascript for extensions. | HIGH | Suggested approach for new video player installation and migration. Extension approaches for video.js | ||
Consistency | Consider the right home for the new video player (e.g., is it a new UI component in the Paragon design system?). If one of the goals of this project is to ensure consistent video player experience across the platform, it may make sense to live in Paragon. | A video player component has to be added to the Paragon design system. Suggest a different approach if it is impossible. Different approach: The paragon design system will use the video player, video player will not be a Paragon component. Due to requirement for player skin customizations (lower in the list). | HIGH | Suggested approach for new video player installation and migration. | ||
Compatibility | We have a lot of analytic events that get triggered from the current video player. We MUST keep these requirements as-is, or supply an ADR regarding what would change. | Current events are supported in a new video player. Add new events to the new video player (enabling / disabling captions, and changing video speed) | HIGH | Events list vith ADR. | ||
Compatibility | Features from the current video player have to be recreated with a new video player | Define all front-end, backend features that need to be recreated and tested for the new video player. | HIGH | Feature list with ADRs. | ||
Consistency | Unified video player experience across the platform (Studio, Content Libraries, LMS) | The video player has to be implemented and tested in the: https://miro.com/app/board/uXjVM-F5A9g=/?moveToWidget=3458764569420895702&cot=14 | HIGH | Features have to be divided in modules for testing and further implementation. | ||
Maintainability | Features of the old video player have to be revised and deprecated as needed Some pieces of data can just be dropped entirely, like multi-version-YT nonsense used ages ago to provide different video speeds (before YT provided this functionality natively). Multi-speed YouTube upload option We used in 2012 before YT started generating multiple speeds for you. Open questions: Is anyone using video bumpers? What features weren’t ported to the MFE, or are no longer exposed in the UI? etc | Features of the old video player have to be revised and deprecated as needed. | HIGH | Feature list with ADRs or deprication strategies. | ||
Flexibility | The player supports different video sources | The list of sources that have to be supported:
| HIGH - for already existing features LOW - for new features (ex. Vimeo) | The list of sources will be created, added to the features where the video file have to be added and played for development and testing. | ||
Accessibility | The player supports accessibility features | Player supports Existing features:
Improvements:
| HIGH - for already existing features LOW - for new features | This requirements will be covered within the additional development scope for the new video player. | ||
Securability | Ensure that the link has an expiration period and connot be used forever (or used on the other platform) | The player can support the key for the link to the video file created in AWS Cloudfront or Cloudflare | MEDIUM | Feature has to be added to the feature list. | Check existing plugins in video.js marketplace, if not custom development is required. | |
Manageability | Ability to track buffering issues that occur during video streaming Currently, the player lacks reporting on buffering issues, making them impossible to diagnose | New video player has to provide analytics and monitoring of buffering issues | MEDIUM | Buffering issues analytics feature has to be added to the backlog. Buffering issue - what do we call the issue? Who and where will see these analytics or/and monitoring reports? |
| |
Accessibility | Perform downscaling/play downscaled video to handle both high and low-bandwidth clients | Different video resolutions support
Dynamic video adjustment - dynamically adjusts the video quality based on the client's available bandwidth.
| OUT OF SCOPE | Player is compatible |
| |
User experience | The player enables video slice previews (e.g., chapters) to external sources, such as displaying video snippets directly in search engine results for enhancing user experience and facilitate content discovery | The video player have to support video chapters (example) for all video sources:
Chapters should be visible on the external sources: ? | LOW | Feature is added to the feature list. | A new feature, the development is required for configuration options in video edit mode CMS. We may also automatically populate chapters using API. | |
Interoperability | Have the player be a standalone, embeddable player for other platforms outside of Open edX/edx.org | The video player has to allow users to embed or share the video to other platforms:
| LOW | Feature has to be added to the list. Course creators should be able to share the video Course creators should be able to create a sharable video so that learners will be able to share it | ||
Interactivity | Support for additional in-video features, such as comments for better learners' engagement | The video player can support in-video comments The video player can support pop-up questions, pop-up links The video player can support measurements of how much of a video someone watched Example of inline video comments Other features or just comments to test the capability? | LOW | Features added to the feature list. | ||
Consistency | The video player should support theme / skin customization. Ideally, we’d be able to associate CSS variables from Paragon to the styles for the video player so that things like colors are consistent between the video player and the rest of the application. | Automatic customisation for the video player as a part of Open edX installation (use the same colors for the player as for the whole platform). Elements can be customised:
| LOW | Features added to the list. | ||
Localizability | Internationalization of videos by providing different language options | -- | LOW | Different language options can be added to the video block so that students will be able to choose what language they want to watch. | ||
Extensibility | Support audio player | LOW | Add audio without the video As a new xblock? Or change the type of the player?
Example of the audio xblock https://wordpress.com/support/wordpress-editor/blocks/audio-block/ | |||
User experience | Re-runs of the course have to stay as is with the new video player | Out of scope |
Features and use cases from the current Video component (in progress)
Feature | UC/UCes name | Description | Feature approach (link to ADR) |
|---|---|---|---|
FE Video x-block in Studio_add a video component (out of scope, because its a part of Studio MFE) |
|
| |
 | |||
FE Studio_video editor_settings | Video sourse Superuser/Admin/Course Admin/Course Staff can:
Vimeo support .m3u8 playlist support? (from a comment on the memo) Thumbnail Thumbnail upload and delete Transcripts Authors can upload transcripts Authors can download transcripts to edit and reupload Transcripts can be added in other languages, and can be selected by video viewers for display Duration Authors can set start and end times for videos Handout License | Transcripts aren’t standardized and may be in various locations - YouTube, local storage, or in edx-val - a system that edx.org uses, but unclear if anyone in the community does What do we need to do with legacy Transcript utilities? For transcripts, vtt will also serve us well. There are plenty of ways to parse vtt and make it pretty. Migration to VTT format for transcripts (initial thoughts) | |
FE Studio_video editor_video preview | A new video player is required to include a video preview on the Video Settings page. The existing video player is (according to previous discovery) a pre-React, pre-webpack player which is not viable for our use case of having a Video Preview capability in the Video Settings Editor. | Rework the Video component so that it directly renders in the Learning MFE with no iframe The existing video player is (according to previous discovery) a pre-React, pre-webpack player which is not viable for our use case of having a Video Preview capability in the Video Settings Editor. | |
FE Studio_video editor_captioning? | Closed captioning is visible in the video player's view Display VTT captions | For subtitles, moving to vtt is probably the right path forward. It's a well documented format. | |
FE Video x-block in Studio_video preview | Rework the Video component so that it directly renders in the Learning MFE with no iframe How will this play with units that have multiple types of components? For example: text followed by a video followed by a multi-choice problem. At some point, I expect folks will want other types of components to run outside the IFrame as well. Can the Video component be reimplemented in a way that leaves the door open to a more general solution for React-based learning components? | ||
FE Video x-block in Studio_access/duplicate/move/delete (out of scope, because its a part of Studio MFE) | |||
FE LMS_see a Thumbnail | |||
FE LMS_view the video from different sources | Rework the Video component so that it directly renders in the Learning MFE with no iframe How will this play with units that have multiple types of components? For example: text followed by a video followed by a multi-choice problem. At some point, I expect folks will want other types of components to run outside the IFrame as well. Can the Video component be reimplemented in a way that leaves the door open to a more general solution for React-based learning components? | ||
FE LMS_view the video with a specific duration | |||
FE LMS_download the video | |||
FE LMS_download transcripts | |||
FE LMS_see transcripts near the video | Transcripts can be selected by video viewers for display Transcript shifts to left side for RTL languages | ||
FE LMS_download a handout | |||
FE LMS_see the video license | |||
FE Content Library_add a video component (out of scope, because its a part of Studio MFE) | |||
FE Content Library_preview the video | Rework the Video component so that it directly renders in the Learning MFE with no iframe How will this play with units that have multiple types of components? For example: text followed by a video followed by a multi-choice problem. | ||
FE Content Library_video editor_settings | The same use cases as in studio | ||
FE Content Library_video editor_preview | Rework the Video component so that it directly renders in the Learning MFE with no iframe | ||
FE_Video controls | replay speeds ?SRT captions | ||
In_video quizzes | Helper XBlock to locate CAPA problems within videos | ||
In_video quizzes | Javascript-controlled video |
Architecture notes
WIP Whiteboard with Arch diagrams: https://excalidraw.com/#room=bb5ec8f1a9402a2ef3b5,QXIMmn8cmiQV9WhcTkQc-w