feat: handle chapters, block segments, time intervals, remote text tracks #207

amtins · 2024-02-13T18:13:32Z

Description

This PR adds support for blocked segments, chapters, intervals and remote text tracks.

To allow developers to create their own experience, metadata text tracks are used. This type of text track has the advantage of not being displayed on screen, however, it is possible to listen to cue change events and react to them as required.

Usage and definition

Blocked segments

Blocked segments are portions of content that must not be played for various reasons, such as legal, geo-blocking, etc. Resolves #211

// Accessing raw data
player.currentSource().mediaData.blockedSegments;

// Listen for cuechange events and get the active cue
player.textTracks().getTrackById('srgssr-blocked-segments').on('cuechange', ()=>{
        const [active] = Array
  .from(player.textTracks().getTrackById('srgssr-blocked-segments').activeCues);
  JSON.parse(active.text); // note that active can be undefined
});

Chapters

Chapters are used to define the start and end times of the various subjects comprising a media item. Resolves #204

// Accessing raw data
player.currentSource().mediaData.chapters;

// Listen for cuechange events and get the active cue
player.textTracks().getTrackById('srgssr-chapters').on('cuechange', ()=>{
        const [active] = Array.from(player.textTracks().getTrackById('srgssr-chapters').activeCues);
  JSON.parse(active.text); // note that active can be undefined
});

Intervals

Intervals allow you to define the start and end times for the credits of a media item. Resolves #212

// Accessing raw data
player.currentSource().mediaData.intervals;

// Listen for cuechange events and get the active cue
player.textTracks().getTrackById('srgssr-intervals').on('cuechange', ()=>{
        const [active] = Array.from(player.textTracks().getTrackById('srgssr-intervals').activeCues);
  JSON.parse(active.text); // note that active can be undefined
});

Changes made

expose media URN, refer to e0d5537
add remote subtitles, resolves Handle remote text tracks #203, refer to bc02149
add chapters, refer to 9997a01
add intervals, refer to 84d9ae0
add blocked segments, refer to 8ca34a8
refactor, refer to 62fa6ca

github-actions · 2024-02-13T18:14:36Z

Coverage report

St.^❔	Category	Percentage	Covered / Total
🟢	Statements	97.89% (-0.5% 🔻)	558/570
🟢	Branches	94.58% (+1.13% 🔼)	279/295
🟢	Functions	99.35% (-0.65% 🔻)	153/154
🟢	Lines	98.52% (-0.64% 🔻)	532/540

Show files with reduced coverage 🔻

St.^❔	File	Statements	Branches	Functions	Lines
🟢	`...` / srgssr.js	95.38% (-1.39% 🔻)	95.18% (+6.61% 🔼)	97.14% (-2.86% 🔻)	96.43% (-3.57% 🔻)

Test suite run success

180 tests passing in 9 suites.

Report generated by 🧪jest coverage report action from 6103f47

github-actions · 2024-02-20T18:39:35Z

PR Preview Action v1.4.7
Preview removed because the pull request was closed.
2024-02-23 17:27 UTC

Introduces new showcases for integrators to benefit from the inclusion of custom text tracks in the pillarbox player (see SRGSSR/pillarbox-web#207). The showcases cover the implementation of: handling blocked segments, displaying current chapters, and managing time intervals. Code examples with ample comments have been added to provide developers with technical insight on how to integrate these features.

Today, it's not possible to retrieve the identifier of the media currently being played. In some cases, however, this information may be of interest to the developer. This modification fills the gap by exposing the URN through the `mediaData` object accessible from the player current source. ```javascript // Access the media URN player.currentSource().mediaData.urn ``` - add `urn` property to `mediaComposition.getMainResources` - update `getMainResources` test case to ensure that the urn property is exposed

Resolves #203 by adding support for remote subtitles. Some SRG SSR content, such as mp4, may come with subtitles delivered as separate files, so these need to be explicitly added to the player. This also allows the developer to access remote subtitles via the `mediaData` object accessible from the `currentSource` player. ```javascript // Access the media subtitles player.currentSource().mediaData.subtitles ``` - add `subtitles` property to `mediaComposition.getMainResources` - add a function to add remote subtitles to the player from the srgssr middleware - add remote `subtitles` when resolving the resource in the setSource function - add test cases - replace the default media in the test page with an example containing multiple remote subtitles

Resolves #204 by allowing developers to access chapters directly from the player's text tracks. Chapters can be accessed in two ways. The first is raw data via the `mediaData` object from player `currentSource`. The second is via the player's `textTracks`. This last method allows to listen to the cuechange event and react as accordingly. ```javascript // Accessing raw data player.currentSource().mediaData.chapters; // Listen for cuechange events and get the active cue player.textTracks().getTrackById('srgssr-chapters').on('cuechange', ()=>{ const [active] = Array.from(player.textTracks().getTrackById('srgssr-chapters').activeCues); JSON.parse(active); // note that active can be undefined }); ``` - add the `chapters` property to `mediaComposition` - add a function to add `chapters` to the `player` - add the `chapters` when resolving the resource in the `setSource` function - add test cases - add test media containing multiple chapters

test/middleware/srgssr.spec.js

src/middleware/srgssr.js

Introduces new showcases for integrators to benefit from the inclusion of custom text tracks in the pillarbox player (see SRGSSR/pillarbox-web#207). The showcases cover the implementation of: handling blocked segments, displaying current chapters, and managing time intervals. Code examples with ample comments have been added to provide developers with technical insight on how to integrate these features.

Resolves #212 by giving developers access to intervals directly from the player's text tracks. Intervals, as defined by SRG SSR, can be used, for example, to define the position of the opening and closing credits of a media. Intervals can be accessed in several ways. The first is raw data via the mediaData object from player currentSource. The second is via the player's textTracks. This latter method allows you to listen to the cuechange event and react as required. ```javascript // Accessing raw data player.currentSource().mediaData.intervals; // Listen for cuechange events and get the active cue player.textTracks().getTrackById('srgssr-intervals').on('cuechange', ()=>{ const [active] = Array.from(player.textTracks().getTrackById('srgssr-intervals').activeCues); JSON.parse(active.text); // note that active can be undefined }); ``` - adds the intervals property to the mediaComposition - adds a function for adding intervals to the player - adds intervals when resolving the resource in the setSource function - add test cases - add a test media containing an interval

Resolves #211 by giving developers access to blocked segments directly from the player's text tracks and, preventing them from being played. Blocked segments, as defined at SRG SSR, are portions of media that must not be played for various reasons such as legal, geo-blocked etc. Blocked segments can be accessed in two ways. The first is raw data via the mediaData object from player currentSource. The second is access via the player's textTracks. This latter method allows you to listen to the cuechange event and react accordingly. ```javascript // Accessing raw data player.currentSource().mediaData.blockedSegments; // Listen for cuechange events and get the active cue player.textTracks().getTrackById('srgssr-blocked-segments').on('cuechange', ()=>{ const [active] = Array .from(player.textTracks().getTrackById('srgssr-blocked-segments').activeCues); JSON.parse(active.text); // note that active can be undefined }); ``` - adds the blockedSegments property to mediaComposition - adds a function to add blocked segments to the player - adds a function to retrieve blocked segments from the player - adds a function to retrieve the end time of a blocked segment - adds functions for passing blocked segments - adds blocked segments when resolving the resource in the setSource function - add test cases

…racks This modification removes duplicate code from functions used to add text tracks for blocked segments, chapters and intervals. - update `addBlockedSegments` - updat `addChapters` - updat `addIntervals` - add `createTextTrack`, creates a `metadata` text track with a specific ID - add `addTextTrackCue`, adds CUEs to a text track - add `addTextTracks`, consolidates the addition of different text tracks in the player to a single location

jboix

LGTM!

github-actions · 2024-02-23T17:28:38Z

🎉 This PR is included in version 1.1.0 🎉

The release is available on:

npm package (@main dist-tag)
GitHub release

Your semantic-release bot 📦🚀

Introduces new showcases for integrators to benefit from the inclusion of custom text tracks in the pillarbox player (see SRGSSR/pillarbox-web#207). The showcases cover the implementation of: handling blocked segments, displaying current chapters, and managing time intervals. Code examples with ample comments have been added to provide developers with technical insight on how to integrate these features.

amtins force-pushed the feat/tracks branch 2 times, most recently from ea4d7d8 to 06f5926 Compare February 19, 2024 17:47

amtins added this to the Custom text tracks milestone Feb 19, 2024

jboix mentioned this pull request Feb 23, 2024

chore(showcase): showcases for custom text tracks handling SRGSSR/pillarbox-web-demo#14

Merged

amtins added 3 commits February 23, 2024 15:43

amtins force-pushed the feat/tracks branch from 95d2191 to 62fa6ca Compare February 23, 2024 14:43

amtins marked this pull request as ready for review February 23, 2024 14:52

jboix reviewed Feb 23, 2024

View reviewed changes

test/middleware/srgssr.spec.js Show resolved Hide resolved

test/middleware/srgssr.spec.js Show resolved Hide resolved

src/middleware/srgssr.js Show resolved Hide resolved

amtins force-pushed the feat/tracks branch from 62fa6ca to 83e59a8 Compare February 23, 2024 16:32

amtins added 3 commits February 23, 2024 17:41

amtins force-pushed the feat/tracks branch from 83e59a8 to 6103f47 Compare February 23, 2024 16:51

jboix approved these changes Feb 23, 2024

View reviewed changes

amtins merged commit 4ff0bc8 into main Feb 23, 2024
4 checks passed

amtins deleted the feat/tracks branch February 23, 2024 17:27

github-actions bot added the released on @main label Feb 23, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: handle chapters, block segments, time intervals, remote text tracks #207

feat: handle chapters, block segments, time intervals, remote text tracks #207

amtins commented Feb 13, 2024 •

edited

Loading

github-actions bot commented Feb 13, 2024 •

edited

Loading

github-actions bot commented Feb 20, 2024 •

edited

Loading

jboix left a comment

github-actions bot commented Feb 23, 2024

feat: handle chapters, block segments, time intervals, remote text tracks #207

feat: handle chapters, block segments, time intervals, remote text tracks #207

Conversation

amtins commented Feb 13, 2024 • edited Loading

Description

Usage and definition

Blocked segments

Chapters

Intervals

Changes made

github-actions bot commented Feb 13, 2024 • edited Loading

Coverage report

Test suite run success

github-actions bot commented Feb 20, 2024 • edited Loading

jboix left a comment

Choose a reason for hiding this comment

github-actions bot commented Feb 23, 2024

amtins commented Feb 13, 2024 •

edited

Loading

github-actions bot commented Feb 13, 2024 •

edited

Loading

github-actions bot commented Feb 20, 2024 •

edited

Loading