MediaPlayer Component

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.

---

Props Explained

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 per Manifest using the browser's localStorage, storing the most recently active Canvas URL and playback time for each Manifest. The ttlDays property sets how many days a saved position is retained before expiring, and maxItems limits the number of Manifest entries 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/ramp@5.1.0)

---

How to use the MediaPlayer component?

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.

---

Player hotkeys

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

---

Inaccessible resource display

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 TextTracks as subtitles/captions

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. 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.

Demo.of.forced.captions.mov

This feature is enabled in Ramp from @samvera/ramp v5.0.0 onward.

---

Audio Description (AD) support

To enable text-to-speech for audio description text-tracks, Ramp uses the WebAPI's speechSynthesis feature. It is natively supported by all modern browsers.

Ramp reads and parses supplementing annotations and identifies the audio-description text-tracks by the /descriptions at the end of the Annotation id. Then, Ramp marks this text-track with kind="descriptions". Important: Ramp expects only one audio-description text-track because, the AD control in the player's controls is a toggle button.

Then Ramp builds this audio-description text-track into the <track> elements in the player. With this, VideoJS is made aware of the audio-description track and starts treating it as a text-track by doing the necessary parsing and attaching necessary events internally.

Ramp at the same time builds a custom toggle button into the player's control-bar. This is set to be turned OFF by default (on page load). When turned ON, it displays a green border at the bottom of the button similar to captions button. Important: the AD feature can be turned ON in Ramp at the same time as captions unlike in native VideoJS.

Behavior of the AD functionality is as follows:

• When player is paused and AD is toggled ON:
  • cues are read aloud when the timestamp of a cue is made current via seek/scrub user actions
  • if the user toggles OFF the AD button during speech synthesis, speech synthesis is immediately stopped
• When player is playing and AD is toggled ON:
  • player is paused when the player reaches a cue in the AD track
  • then the cue is read aloud
  • if the user toggles OFF the AD button during speech synthesis, speech synthesis is immediately stopped
  • playback is resumed once speech synthesis ends

This feature is enabled in Ramp from @samvera/ramp v5.1.0 onward.

---

Resume playback

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 playback position.

Any information in start property specified in the Manifest or information passed via startCanvasId/startCanvasTime props (read more) takes precedence over the saved playback information.

• when a starting Canvas is specified, Ramp checks if the saved playback position corresponds to the starting Canvas. If it is then, display resume modal. Otherwise load the starting Canvas into the player and do not display the resume modal
• when a starting time is specified, Ramp skips the resume modal entirely and respect the user specified start time

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 Manifest, with the information from the last played Canvas. This is saved in a bounded array with the key playbackPositions in localStorage. 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 onward.