MediaPlayer Component - samvera-labs/ramp GitHub Wiki

MediaPlayer component provides a player that facilitates playback of both audio and video media files in a Presentation 3.0 IIIF Manifest. It encapsulates a VideoJS instance, which is an HTML5 player framework. MediaPlayer component fetches data from central state management system using ReactJS Context providers. Therefore this component must always be encapsulated by the IIIFPlayer component.

MediaPlayer component accepts the following props;

• enableFileDownload (Boolean) : this has a default value of false and is not required. Once this is set to true it adds an button with a menu to the player's control bar to display files listed under the rendering property for the displayed Canvas and enables downloading them. This is a custom component added to the Video.js instance in Ramp.

• enablePIP (Boolean) : this has a default value of false and is not required. When this is set to true, it adds an icon to the player's control bar to enable Picture-In-Picture feature for the current player instance.

• enablePlaybackRate (Boolean) : this has a default value of false and is not required. When this is set to true, it adds an icon-button to the player's control bar which provides a menu to select a different playback speed for the media. The available speed options are 0.5x, 0.75x, 1x, 1.5x, and 2x. (supported from @samvera/ramp 3.2.0 onward)

• enableTitleLink (Boolean): this has a default value of false and is not required. When this is set to true, it adds a title bar to the video player which displays Manifest Label - Active Canvas Label with an href attribute linking to the URL in the active canvas's id. This is a custom VideoJS component added to the VideoJS instance in Ramp. (supported from @samvera/ramp 3.2.0 onward)

• withCredentials (Boolean): this has a default value of false and is not required. Once this is set to true it causes the VideoJS component to include any available Authentication and Cookie headers with XHR requests. There are special server-side CORS requirements that go along with this option – specifically, the streaming server should include an appropriate Access-Control-Allow-Credentials header, and a non-wildcard Access-Control-Allow-Origin specifying the server originating the request. (supported from @samvera/ramp 3.2.0 onward)

• language (String): this has a default value of "en" and is not required. This prop accepts a valid language code from IANA Language Subtag registry. If the given language code doesn't match with any of the existing language file with .json extension, Ramp defaults to English language. (supported from @samvera/ramp 3.3.0 onward)

• resumeCache (Object): this has a default value of { enable: false, ttlDays: 30, maxItems: 200 } and is not required. When resumeCache.enable is set to true, the player saves and restores the playback position for each Canvas using the browser's localStorage. The ttlDays property sets how many days a saved position is retained before expiring, and maxItems limits the number of Canvas positions stored using an LRU eviction strategy. When resumeCache.enable is set to false, any previously saved positions are cleared from storage. If the prop is initialized partially, Ramp applies default prop values to the rest of the properties. (support from @samvera/[email protected])

import { IIIFPlayer, MediaPlayer } from '@samvera/ramp';
import 'video.js/dist/video-js.css';
import '@samvera/ramp/dist/ramp.css';

<IIIFPlayer manifestUrl="http://example.com/manifest.json">
  <MediaPlayer enableFileDownload={true} />
</IIIFPlayer>;

This code generates the MediaPlayer component with the file download icon in the player's control bar;

When enablePIP={true} is added to the MediaPlayer component player is created with the Picture-In-Picture menu icon in the control bar;

The Video.js instance underneath the MediaPlayer component has a couple of custom Video.js components implemented in the Ramp code to add extra functionality to the player. Please read more on these custom components here.

For ease of use of the media player, hotkeys (keyboard shortcuts) are enabled for player functionalities. A hotkey is a key or a key combination on a computer keyboard when pressed at one time performs a task ¹ . List of supported hotkeys in the player are as follows;

• Space key: play/pause media playback
• M key: mute/un-mute media
• F key: toggle full-screen on/off
• Up arrow key: increase volume by 10% (full volume is equal to 100%)
• Down arrow key: decrease volume by 10%
• Left arrow key: jump 5 seconds backward from the current time in the player
• Right arrow key: jump 5 seconds forward from the current time in the player

When a given resource in a Canvas is not available to be played either due to permissions or it's general unavailability, it is generally indicated in the Canvas as an empty list of Annotation under AnnotationPage. Ramp handles this use-case by displaying a message in the player space. This message is parsed from placeholderCanvas property of the same Canvas if available, and if not Ramp sets it to a default message specified in the code.

And when AutoAdvanceToggle is turned ON, this message is accompanied with a 10 second timer which automatically loads the next Canvas in the Manifest when the time is up.

The Previous/Next buttons and the timer display was added in @samvera/ramp 3.2.0.

Forced subtitles/captions are common on movies and only provide subtitles when the characters speak a foreign or alien language, or a sign, flag, or other text in a scene is not translated in the localization and dubbing process. ²

Ramp parser can identify these type of forced subtitle/caption text-tracks in the supplementing annotations by [forced] text in the Annotation's label property. Then auto-enable the forced caption in the player even when the user has subtitles/captions turned off. This feature is enabled in Ramp from @samvera/ramp v5.0.0 onwards. Annotation for a forced subtitle/caption can look as follows in the Manifest,

"annotations": [
  {
    "id": "https://.../lunchroom_manners/canvas/1/page/2",
    "type": "AnnotationPage",
    "items": [
      {
        "id": "https://.../lunchroom_manners/canvas/1/annotation/webvtt",
        "type": "Annotation",
        "motivation": "supplementing",
        "body": {
          "id": "https://.../lunchroom_manners/lunchroom_manners.vtt",
          "type": "Text",
          "format": "text/vtt",
          "label": { "en": [ "WebVTT Transcript [forced]" ] }
        },
        "target": "https://.../lunchroom_manners/canvas/1"
      }
    ]
  }
]

Ramp uses the browser's localStorage to store user's preference for turning captions/subtitles ON/OFF. This is stored as a boolean flag with the key startCaptioned, and toggled when the user turn ON/OFF subtitles/captions in the player. Read more on saved player states here.

This value is toggled only when the user interacts with the subtitles/captions menu to turn ON/OFF subtitles/captions.

When there is a forced subtitle/caption text-track in a Canvas, Ramp auto-enables the forced text track overriding the behavior specified by this flag. This auto-enabling of the forced text-track doesn't toggle the startCaptioned flag in the localStorage.

The following short-clip shows how Ramp auto-enables a forced subtitle/caption when a captions are turned off in the user's browser localStorage.

When the resumeCache prop (read more above) is enabled, the player automatically saves the current playback position as a user watches the media. If the user navigates away mid-playback and returns to the same item at a later time, the user is presented with an option to resume playback from the saved position using this saved information.

The saved position expires after a configurable number of days and is cleared automatically when the media ends or restarted from the beginning. This feature uses the browser's localStorage and creates an entry for each Canvas that is played and saved in an array with the key playbackPositions. The array is designed as an LRU cache with a configurable max capacity. This feature is enabled in Ramp from @samvera/ramp v5.1.0 onwards.