# PRESTOplay

> PRESTOplay is Castlabs' player SDK family for building streaming applications across Android, Apple (iOS/tvOS), web browsers, and React Native. These files cover PRESTOplay for Web. For the other SDKs, see https://players.castlabs.com/android/latest/docs/build/html/index.html (Android), https://players.castlabs.com/apple/latest/docs/index.html (Apple), and https://players.castlabs.com/react-native/1.4.1/docs/getting-started/setup (React Native).

## common-media-data

Common media data
*****************

Common Media Data standards for CDN cooperation: CMCD (CTA-5004,
player-to-server request metadata) and CMSD (CTA-5006,
server-to-player response metadata).


CMCD (Common Media Client Data)
===============================

See the CMCD specification (CTA-5004).

When CMCD is enabled, the player adds contextual playback metadata to
every media request, such as buffer level, selected bitrate, or recent
throughput. CDNs can use this metadata to prioritize requests,
prefetch the next segment, or diagnose delivery issues.


CMSD (Common Media Server Data)
===============================

See the CMSD specification (CTA-5006).

CMSD defines a standard way for media servers — origin servers and CDN
intermediaries — to return data with each media object response, such
as estimated throughput or the next object to fetch. The player
processes this data to improve delivery efficiency and the viewer's
quality of experience. Unlike CMCD, which travels from player to
server on requests, CMSD travels from server to player in HTTP
response headers.


Platform implementation guides
==============================

* PRESTOplay for web Common Media Data support


## glossary

Glossary
********

This page defines terms and abbreviations used throughout the
PRESTOplay documentation.

+----------------------------------------------------+----------------------------------------------------+
| Term                                               | Definition                                         |
|====================================================|====================================================|
| Advanced Encryption Standard (AES)                 | A symmetric encryption standard commonly used to   |
|                                                    | encrypt content.                                   |
+----------------------------------------------------+----------------------------------------------------+
| AES-128 content key                                | A symmetric key that encrypts and decrypts content |
|                                                    | using the AES algorithm with a 128-bit (16-byte)   |
|                                                    | key length, in CBC or CTR mode. Treat the content  |
|                                                    | key as the compound object "{ Key Value, ALGID }". |
+----------------------------------------------------+----------------------------------------------------+
| CBC mode                                           | An AES encryption mode. Cipher block chaining      |
|                                                    | (CBC) mode turns a block cipher into a stream      |
|                                                    | cipher.                                            |
+----------------------------------------------------+----------------------------------------------------+
| CBCS                                               | An encryption mode of the Common Encryption        |
|                                                    | standard. Uses AES CBC mode with pattern (partial) |
|                                                    | sample encryption — also called partial sample     |
|                                                    | encryption.                                        |
+----------------------------------------------------+----------------------------------------------------+
| CENC                                               | An encryption mode of the Common Encryption        |
|                                                    | standard. Uses AES CTR mode with full sample       |
|                                                    | encryption — also called full sample encryption.   |
+----------------------------------------------------+----------------------------------------------------+
| Certificate                                        | A digitally signed binary document used to grant   |
|                                                    | and revoke device and computer privileges to       |
|                                                    | perform specific operations.                       |
+----------------------------------------------------+----------------------------------------------------+
| Certificate authority (CA)                         | An entity that issues digital certificates and     |
|                                                    | provides trust in certificate chains.              |
+----------------------------------------------------+----------------------------------------------------+
| Challenge                                          | A request from a client. A challenge contains      |
|                                                    | information about the client, a list of requested  |
|                                                    | rights, and other information about the content,   |
|                                                    | including the content header and key identifier.   |
+----------------------------------------------------+----------------------------------------------------+
| Clear content                                      | A media file that isn't encrypted.                 |
+----------------------------------------------------+----------------------------------------------------+
| Client                                             | A content receiver — a device or an application.   |
+----------------------------------------------------+----------------------------------------------------+
| Common Encryption (CENC)                           | An MPEG standard that defines encryption and       |
|                                                    | container formats for protected media content,     |
|                                                    | specified in ISO/IEC 23001-7:2016.                 |
+----------------------------------------------------+----------------------------------------------------+
| Common Media Application Format (CMAF)             | A multimedia format specified in ISO/IEC           |
|                                                    | 23000-19:2018.                                     |
+----------------------------------------------------+----------------------------------------------------+
| conditional access system (CAS)                    | A system that controls subscriber access to        |
|                                                    | protected broadcast content.                       |
+----------------------------------------------------+----------------------------------------------------+
| content decryption module (CDM)                    | The client component that provides DRM             |
|                                                    | functionality, including decryption.               |
+----------------------------------------------------+----------------------------------------------------+
| Content ID (CID)                                   | The unique identifier of the content to decrypt.   |
+----------------------------------------------------+----------------------------------------------------+
| Content Key Context (CKC)                          | In FairPlay DRM, a message the Key Security Module |
|                                                    | (KSM) generates in reply to the server playback    |
|                                                    | context (SPC) message the playback app sends it.   |
|                                                    | The KSM responds to every SPC message with a       |
|                                                    | corresponding CKC message, whose payload contains  |
|                                                    | the content key the Apple device uses to decrypt   |
|                                                    | the media for playback.                            |
+----------------------------------------------------+----------------------------------------------------+
| CTR mode                                           | An AES encryption mode. Counter (CTR) mode turns a |
|                                                    | block cipher into a stream cipher.                 |
+----------------------------------------------------+----------------------------------------------------+
| Decrypt                                            | To convert encrypted content back into its         |
|                                                    | original form.                                     |
+----------------------------------------------------+----------------------------------------------------+
| Device                                             | A physical unit such as a PC, mobile phone, or     |
|                                                    | set-top box.                                       |
+----------------------------------------------------+----------------------------------------------------+
| digital rights management (DRM)                    | A technology that protects digital content by      |
|                                                    | encrypting it with a cryptographic key. Authorized |
|                                                    | recipients must acquire a license to unlock and    |
|                                                    | consume the content. FairPlay, PlayReady, and      |
|                                                    | Widevine are examples of DRM systems.              |
+----------------------------------------------------+----------------------------------------------------+
| elliptic curve cryptography (ECC)                  | A public-key cryptography approach based on the    |
|                                                    | algebraic structure of elliptic curves.            |
+----------------------------------------------------+----------------------------------------------------+
| Encrypt                                            | To programmatically disguise content to hide its   |
|                                                    | substance.                                         |
+----------------------------------------------------+----------------------------------------------------+
| Encrypted Media Extensions (EME)                   | A W3C standard for HTML interfaces that let HTML5  |
|                                                    | applications perform DRM operations.               |
+----------------------------------------------------+----------------------------------------------------+
| FairPlay Streaming (FPS)                           | A DRM technology developed by Apple, typically     |
|                                                    | used with HLS streams.                             |
+----------------------------------------------------+----------------------------------------------------+
| HTTP Live Streaming (HLS)                          | An adaptive streaming protocol introduced by       |
|                                                    | Apple. See HTTP Live Streaming on Apple Developer  |
|                                                    | and RFC 8216.                                      |
+----------------------------------------------------+----------------------------------------------------+
| Initialization vector (IV)                         | A block of bits that lets multiple instances of a  |
|                                                    | stream or block cipher produce unique streams      |
|                                                    | despite using the same encryption key.             |
+----------------------------------------------------+----------------------------------------------------+
| Key                                                | A piece of data required to unlock a packaged      |
|                                                    | media file. The key is included in a separate      |
|                                                    | license.                                           |
+----------------------------------------------------+----------------------------------------------------+
| Key identifier (KID)                               | A value that identifies the key for a protected    |
|                                                    | media file.                                        |
+----------------------------------------------------+----------------------------------------------------+
| Key rotation                                       | A technique that seamlessly changes the encryption |
|                                                    | keys of a stream at specific times.                |
+----------------------------------------------------+----------------------------------------------------+
| Key Security Module (KSM)                          | Part of FairPlay Streaming (FPS) technology that   |
|                                                    | resides in a content provider's key server. It     |
|                                                    | interprets an encrypted key request message from   |
|                                                    | an Apple device and creates an encrypted response  |
|                                                    | containing the key for the specified media, acting |
|                                                    | as the liaison between the playback app and the    |
|                                                    | Apple device: the app sends a server playback      |
|                                                    | context (SPC) message, the Apple device's          |
|                                                    | operating system parses it and generates a content |
|                                                    | key context (CKC), and the KSM encrypts and        |
|                                                    | delivers the content key to the device.            |
+----------------------------------------------------+----------------------------------------------------+
| License                                            | Data attached to protected content that describes  |
|                                                    | how the content can be used. A license is a data   |
|                                                    | structure that contains, but isn't limited to,     |
|                                                    | policies and an encrypted content key.             |
+----------------------------------------------------+----------------------------------------------------+
| License acquisition                                | The process of obtaining a license to play a       |
|                                                    | packaged media file. The client requests a license |
|                                                    | from a license acquisition URL specified in the    |
|                                                    | packaged media file.                               |
+----------------------------------------------------+----------------------------------------------------+
| License server                                     | The function in the service backend that issues    |
|                                                    | licenses.                                          |
+----------------------------------------------------+----------------------------------------------------+
| MPEG-DASH (Dynamic Adaptive Streaming over HTTP)   | An adaptive streaming protocol that's an MPEG      |
|                                                    | standard. See the MPEG-DASH specification.         |
+----------------------------------------------------+----------------------------------------------------+
| Player                                             | A client program or control that plays digital     |
|                                                    | media content streamed from a server or played     |
|                                                    | from local files. PRESTOplay is an example of a    |
|                                                    | player.                                            |
+----------------------------------------------------+----------------------------------------------------+
| PlayReady                                          | A DRM technology developed by Microsoft.           |
+----------------------------------------------------+----------------------------------------------------+
| Policy                                             | The description in a license of the actions        |
|                                                    | permitted, or the restrictions, on the content.    |
+----------------------------------------------------+----------------------------------------------------+
| Private key                                        | The secret half of a public/private key pair used  |
|                                                    | in cryptography. Private keys typically sign a     |
|                                                    | message that's verified with the corresponding     |
|                                                    | public key, or decrypt a message encrypted with    |
|                                                    | the corresponding public key.                      |
+----------------------------------------------------+----------------------------------------------------+
| Protected content                                  | Video, movie, audio, music, ebook, or executable   |
|                                                    | content that may be downloaded, streamed, or both. |
+----------------------------------------------------+----------------------------------------------------+
| PSSH box                                           | Protection System Specific Header box. An object   |
|                                                    | defined in the Common Encryption standard that     |
|                                                    | carries DRM-specific information.                  |
+----------------------------------------------------+----------------------------------------------------+
| Public key                                         | The non-secret half of a public/private key pair   |
|                                                    | used in cryptography. Public keys typically        |
|                                                    | encrypt sessions, files, and messages that are     |
|                                                    | then decrypted with the corresponding private key, |
|                                                    | or verify a digital signature created with the     |
|                                                    | corresponding private key.                         |
+----------------------------------------------------+----------------------------------------------------+
| Revocation                                         | The process of identifying clients that have       |
|                                                    | compromised security and preventing them from      |
|                                                    | getting additional licenses to decrypt protected   |
|                                                    | content.                                           |
+----------------------------------------------------+----------------------------------------------------+
| Robustness                                         | Rules that specify whether a device is             |
|                                                    | sufficiently robust to resist attacks.             |
+----------------------------------------------------+----------------------------------------------------+
| Software development kit (SDK)                     | A set of tools, libraries, and documentation for   |
|                                                    | building applications on a platform.               |
+----------------------------------------------------+----------------------------------------------------+
| Security level (SL)                                | A classification of how robust a device or         |
|                                                    | component is against attacks.                      |
+----------------------------------------------------+----------------------------------------------------+
| SL2000                                             | PlayReady security level 2000.                     |
+----------------------------------------------------+----------------------------------------------------+
| SL3000                                             | PlayReady security level 3000.                     |
+----------------------------------------------------+----------------------------------------------------+
| Server Playback Context (SPC)                      | In FairPlay DRM, a message the playback app sends  |
|                                                    | to the key server to initialize a key session.     |
+----------------------------------------------------+----------------------------------------------------+
| Stream                                             | Digital media delivered in a continuous flow       |
|                                                    | across a network.                                  |
+----------------------------------------------------+----------------------------------------------------+
| Widevine                                           | A DRM technology developed by Google.              |
+----------------------------------------------------+----------------------------------------------------+


## index

PRESTOplay documentation
************************

PRESTOplay SDK documentation. Covers the web (browser) SDK. Android,
Apple (iOS/tvOS), and React Native docs are hosted separately (links
below). Features: adaptive streaming (HLS, DASH), DRM, subtitles,
analytics, and offline playback.


Get started
===========

* PRESTOplay for Android — Android (Java/Kotlin, Gradle)

* PRESTOplay for Apple — iOS, iPadOS, and tvOS (Swift, Xcode)

* PRESTOplay for Web Apps — Browsers (JavaScript, NPM)

* PRESTOplay for React Native — React Native (TypeScript,
  cross-platform)


Core concepts
=============

* Thumbnails — Thumbnail formats, signaling, and authoring patterns

* Common media data — CMCD and CMSD standards for CDN cooperation

* Glossary — Definitions of DRM and streaming terms used throughout
  this documentation


Core concepts
^^^^^^^^^^^^^

* Thumbnails

  * What thumbnails provide

  * Stream-signaled thumbnails

  * Side-loaded thumbnail formats

  * Authoring recommendations

  * Platform implementation guides

* Common media data

  * CMCD (Common Media Client Data)

  * CMSD (Common Media Server Data)

  * Platform implementation guides

* Glossary


Platforms
^^^^^^^^^

* PRESTOplay for Android

* PRESTOplay for Apple

* PRESTOplay for Web Apps

  * Getting started

  * Components

  * License

  * Player basics

  * Player configuration

  * Player surface

  * Audio player

  * Events

  * Errors

  * DRM

  * Tracks and languages

  * Subtitles

  * Thumbnails

  * Common media data

  * Low latency and fast zapping

  * Playlist

  * Chromecast

  * AirPlay

  * Safari

  * Smart TV

  * Plugins

  * Advertising

  * Analytics

  * Migration guide

  * Docs for LLM agents

  * Changelog

* PRESTOplay for React Native


## llm-docs

Docs for LLM agents
*******************

Plain-text exports of the PRESTOplay for web documentation, for LLM
agents.

+-----------------------------------+-----------------------------------+-----------------------------------+
| Platform                          | Index                             | Full text                         |
|===================================|===================================|===================================|
| Web                               | llms.txt                          | llms-full.txt                     |
+-----------------------------------+-----------------------------------+-----------------------------------+

Both files follow the llms.txt specification.

The files don't cover PRESTOplay for Android, Apple, or React Native
yet.


## thumbnails

Thumbnails
**********

Common thumbnail reference across PRESTOplay SDKs. Covers formats,
DASH/HLS signaling, side-loaded tracks, and authoring recommendations.


What thumbnails provide
=======================

Thumbnails are time-indexed preview images that map a playback
position to an image or image region.

* In-player use case: seek-bar preview while scrubbing

* Data model: timestamp range plus image source

* Rendering model: full image (single frame) or cropped tile from a
  sprite grid


Stream-signaled thumbnails
==========================


Dynamic Adaptive Streaming over HTTP (DASH)
-------------------------------------------

In DASH, thumbnails are usually signaled as an image "AdaptationSet"
with tiled sprites.

   <AdaptationSet contentType="image" mimeType="image/jpeg" segmentAlignment="true">
     <SegmentTemplate media="$RepresentationID$/sprite_$Number$.jpg"
                      startNumber="0"
                      duration="25" />
     <Representation id="sprites" bandwidth="30552" width="1600" height="1200">
       <EssentialProperty
         schemeIdUri="http://dashif.org/guidelines/thumbnail_tile"
         value="5x5" />
     </Representation>
   </AdaptationSet>

"thumbnail_tile" declares the grid layout. In this example, each
sprite contains 25 thumbnails (5 x 5).


HTTP Live Streaming (HLS)
-------------------------

In HLS, thumbnails are signaled from the multivariant playlist with
"EXT-X-IMAGE-STREAM-INF", which points to an image media playlist.

   #EXTM3U
   #EXT-X-STREAM-INF:BANDWIDTH=200,CODECS="avc1,mp4a",RESOLUTION=960x540
   video.m3u8
   #EXT-X-IMAGE-STREAM-INF:RESOLUTION=240x135,CODECS="jpeg",BANDWIDTH=100,URI="image.m3u8"

Image playlists can reference single images or tiled images.


Side-loaded thumbnail formats
=============================

When a stream does not carry thumbnail signaling, you can side-load
one of these formats.


Web Video Text Tracks (WebVTT) index
------------------------------------

WebVTT cues map time ranges to image URLs.

   WEBVTT

   00:00:00.000 --> 00:00:09.999
   thumb1.jpg

   00:00:10.000 --> 00:00:19.999
   thumb2.jpg

Grid coordinates can be appended to each cue target.

   WEBVTT

   00:00:00.000 --> 00:00:09.999
   thumbs.jpg#xywh=0,0,320,180

   00:00:10.000 --> 00:00:19.999
   thumbs.jpg#xywh=320,0,320,180


Template-based images (single or grid)
--------------------------------------

Template URLs use an index token such as "$index$" and optional grid
metadata.

* Single-image mode: one image per index

* Grid mode: one image contains multiple thumbnails, addressed by grid
  position


Binary Image Format (BIF)
-------------------------

Some SDKs support Binary Image Format (BIF) as a compact, indexed
thumbnail container.


Authoring recommendations
=========================

* Keep thumbnail interval consistent (for example, every 5 or 10
  seconds)

* Prefer sprite grids when you need to reduce request count

* Keep grid dimensions practical for target devices

* Validate that cue timelines cover the intended seek range

* Use absolute URLs or preserve relative paths when packaging local
  WebVTT files


Platform implementation guides
==============================

* PRESTOplay for Android documentation

* PRESTOplay for Apple documentation

* PRESTOplay for web thumbnail integration

* PRESTOplay for React Native documentation


## web/advertising

Advertising
***********

PRESTOplay web SDK advertising support. Covers the built-in ads API
and plugins for Google Interactive Media Ads (IMA), Yospace,
FreeWheel, and HLS interstitials.

PRESTOplay includes integrations for Google Interactive Media Ads
(IMA), Yospace, and FreeWheel AdManager, plus support for HLS
interstitials.


Ads API
=======


Ads manager
-----------

Call "getAdsManager()" on a "Player" instance to access "IAdsManager".
Call this method after the "open()" promise resolves. From that point,
you can control the currently playing ad.


Ad events
---------

When ads are active, the player emits ad-related events. Attach ad
event listeners to the player instance:

   player.on(clpp.events.ADS_TIMELINE_CHANGED, event => {
     console.log('==> ad-timeline-changed', event.adsTimeline.getCuePoints());
   });

   player.on(clpp.events.AD_LOADED, event => {
     console.log('==> ad-loaded', event.ad);
   });

Useful ad events include:

* "clpp.events.ADS_TIMELINE_CHANGED"

* "clpp.events.AD_LOADED"

* "clpp.events.AD_BREAK_STARTED"

* "clpp.events.AD_STARTED"

* "clpp.events.AD_BUFFERING"

* "clpp.events.AD_PROGRESS"

* "clpp.events.AD_FIRST_QUARTILE"

* "clpp.events.AD_MIDPOINT"

* "clpp.events.AD_THIRD_QUARTILE"

* "clpp.events.AD_PAUSED"

* "clpp.events.AD_RESUMED"

* "clpp.events.AD_SKIPPED"

* "clpp.events.AD_CLICKED"

* "clpp.events.AD_IMPRESSION"

* "clpp.events.AD_COMPLETED"

* "clpp.events.AD_STOPPED"

* "clpp.events.AD_BREAK_STOPPED"

See Events for general event-handling patterns.


Google IMA plugin
=================

The SDK includes a Google Interactive Media Ads (IMA) plugin for
client-side ads.

To get started, add the IMA library and player styles, and import the
IMA plugin:

   import "@castlabs/prestoplay/cl.ima";

   <link rel="stylesheet" href="clpp.styles.css">
   <script src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"></script>

Pass a Video Multiple Ad Playlist (VMAP) ad tag to the player:

   player.open({
     // ...
     ima: {
       adTagUrl: '//pubads.g.doubleclick.net/...'
     }
   });

Pass a Video Ad Serving Template (VAST) ad tag to the player:

   player.open({
     // ...
     ima: {
       adTagUrl: '//pubads.g.doubleclick.net/...',
       isVast: true
     }
   });

See "ImaConfiguration" for all available configuration options.

The Google IMA sample
(https://github.com/castlabs/prestoplay-web-code-samples/blob/main/examples/advertising/ima.html)
plays pre-roll, mid-roll, and post-roll ads from a VMAP ad tag and
logs ad events, including the ad details available through "IAd", on
the page.


IMA SDK on smart TVs
--------------------

For smart TV-specific limitations, including skippable ads, see Smart
TV.


IMA SDK on iOS
--------------

The IMA plugin is supported on iOS in experimental mode, for the same
reasons as on smart TVs.

Custom UI controls give a better user experience than built-in video
controls on iOS.

See "ImaConfiguration" and its "disableCustomPlayback" option to
disable ads on iOS devices if you run into issues.


Yospace plugin
==============

To get started with Yospace, download the Yospace ad management SDK
from the Yospace developer site. The currently supported version is
3.9.0. Other similar versions may also work, but compatibility is not
guaranteed.

Import the Yospace SDK:

   <script src="./lib/yospace/admanagement-sdk-3.9.0.min.js"></script>

Import the Yospace plugin:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.yospace";

Enable the Yospace plugin when calling "open()" with a Yospace Central
Session Manager (CSM) uniform resource identifier (URI). This
automatically starts a Yospace session. "source.type" must be
specified:

   await player.open({
     source: {
       // Yospace CSM URI
       url: 'https://csm...',
       type: clpp.Type.HLS,
     },
     yospace: {
       enabled: true,
       streamType: clpp.yospace.StreamType.VOD
     }
   });

Set up listeners for Yospace-related events:

   player.on(clpp.events.YOSPACE_SESSION_STARTED, (e) => {
     // e.detail contains the YospaceAdManagement.Session object
   });

   player.on(clpp.events.YOSPACE_SESSION_ENDED, (e) => {
     // e.detail contains the YospaceAdManagement.Session object
   });

   await player.open({
     source: '<manifest_url>',
   });

Once the video starts playing, call "getSession()" on the plugin
instance to get the "YospaceAdManagement.Session":

   const plugin = player.getPlugin(clpp.yospace.YospacePlugin.Id);
   const session = plugin.getSession();


FreeWheel plugin (beta)
=======================

To configure the FreeWheel plugin:

Add the FreeWheel AdManager SDK and player styles, and import the
FreeWheel plugin:

   import "@castlabs/prestoplay/cl.freewheel";

   <link rel="stylesheet" href="clpp.styles.css">
   <script src="//adm.stg.fwmrm.net/libs/adm/6.37.0/AdManager.js"></script>

Add the FreeWheel customer data to the player configuration:

   const playerConfig = {
     // ...
     freewheel: {
       networkId: 42015,
       serverUrl: '//demo.v.fwmrm.net/ad/g/1',
       profileId: '42015:js_allinone_profile',
       videoAssetId: 'js_allinone_demo_video',
       pods: [
         { id: 'Preroll_1', position: 0, type: clpp.ads.PodType.PREROLL },
         { id: 'Midroll_1', position: 3, type: clpp.ads.PodType.MIDROLL },
         { id: 'Midroll_2', position: 30, type: clpp.ads.PodType.MIDROLL },
         { id: 'Postroll_1', position: 60, type: clpp.ads.PodType.POSTROLL }
       ]
     }
   };

See "FreeWheelConfiguration" for all available configuration options.

The whole code can look like this:

   <link rel="stylesheet" href="clpp.styles.css">
   <script src="//adm.stg.fwmrm.net/libs/adm/6.37.0/AdManager.js"></script>
   <video id="video" controls></video>
   <button id="playButton">Play</button>
   <script type="module">
     import { clpp } from "@castlabs/prestoplay";
     import "@castlabs/prestoplay/cl.mse";
     import "@castlabs/prestoplay/cl.freewheel";

     const player = new clpp.Player('video', ...);

     player.open({
       source: '//demo.cf.castlabs.com/media/prestomp4/presto.mp4',
       freewheel: {
         networkId: 42015,
         serverUrl: '//demo.v.fwmrm.net/ad/g/1',
         profileId: '42015:js_allinone_profile',
         videoAssetId: 'js_allinone_demo_video',
         pods: [
           { id: 'Preroll_1', position: 0, type: clpp.ads.PodType.PREROLL },
           { id: 'Midroll_1', position: 3, type: clpp.ads.PodType.MIDROLL },
           { id: 'Midroll_2', position: 30, type: clpp.ads.PodType.MIDROLL },
           { id: 'Postroll_1', position: 60, type: clpp.ads.PodType.POSTROLL }
         ]
       }
     });

     // Listen to ad events the same way as in the IMA example.

     document.getElementById('playButton').addEventListener('click', () => {
       player.play();
     });
   </script>


Broadpeak SSAI ads
==================

The Broadpeak plugin also supports server-side ad insertion (SSAI)
tracking. See Broadpeak SSAI ads on the Analytics page.


HLS interstitials
=================

Support for HLS interstitials is limited to modern browsers. To enable
this feature on Safari, set "preferNativeHlsOnSafari" to "false":

   const player = new clpp.Player('video', {
     streaming: {
       preferNativeHlsOnSafari: false,
     }
   });

You can disable this feature entirely:

   const player = new clpp.Player('video', {
     ads: {
       hls: {
         enable: false,
       },
     },
   });

See "HlsAdsConfiguration" for other configuration options.


Playback session ID
-------------------

To give decisioning servers useful context, you can enable playback
session identification:

   const player = new clpp.Player('video', {
     mse: {
       sendPlaybackSessionIdHeader: true,
     }
   });

With this in place, the player sends the "X-Playback-Session-Id" HTTP
header with every HTTP request related to primary playback, and the
"_HLS_primary_id" query parameter containing the same value with every
interstitial request.

Note:

  For this to work, your primary content server must allow the HTTP
  header "X-Playback-Session-Id" in "Access-Control-Allow-Headers".


Rendering UI
============

To render UI related to ads, listen to ad events and use the event
payload ("IAd") to get information about the currently playing ad.

   player.on(clpp.events.AD_STARTED, event => {
     const position = event.ad.getPositionInSequence();
     const count = event.ad.getSequenceLength();
     adLabel = `Ad ${position} / ${count}`;
   });

   player.on(clpp.events.AD_BREAK_STOPPED, () => {
     adLabel = null;
   });

To render a play/pause button, listen to play and pause events as well
as ad paused, resumed, and started. In all these cases the return
value of "isPaused()" may change.

   function renderPlayButton() {
     if (player.isPaused()) {
       playButton.textContent = 'Play';
     } else {
       playButton.textContent = 'Pause';
     }
   }

   player.on('play', () => {
     renderPlayButton();
   });
   player.on('pause', () => {
     renderPlayButton();
   });
   player.on(clpp.events.AD_STARTED, (e) => {
     renderPlayButton();
   });
   player.on(clpp.events.AD_PAUSED, () => {
     renderPlayButton();
   });
   player.on(clpp.events.AD_RESUMED, () => {
     renderPlayButton();
   });


Seek UI during ads
------------------

Some ad formats do not allow seeking. Use "canSeek()" on the current
ad ("IAd#canSeek") to determine whether the seek bar and any other
seek or playback rate controls should be enabled.

   function renderSeekBar(ad) {
     const seekEnabled = ad ? ad.canSeek() : true;
     seekBar.disabled = !seekEnabled;
     playbackRateSelect.disabled = !seekEnabled;
     // Hide or disable any other seek or playback rate controls accordingly.
   }

   player.on(clpp.events.AD_STARTED, event => {
     // Check and possibly disable seeking when the ad starts.
     renderSeekBar(event.ad);
   });

   player.on(clpp.events.AD_BREAK_STOPPED, () => {
     // Re-enable seek when the ad break ends.
     renderSeekBar(null);
   });


Skippable ads
-------------

Use "getSkipTimeOffset()" to determine whether an ad is skippable. It
returns the number of seconds of playback before the ad can be
skipped, or "-1" if the ad is not skippable.

To skip the current ad, call "skip()" on the ads manager.

Here's an example of rendering a skip button in the UI:

   let currentAd = null;

   player.on(clpp.events.AD_STARTED, event => {
     currentAd = event.ad;
     renderSkipButton();
   });

   player.on(clpp.events.AD_PROGRESS, () => {
     renderSkipButton();
   });

   player.on(clpp.events.AD_BREAK_STOPPED, () => {
     currentAd = null;
     skipButton.style.display = 'none';
   });

   function renderSkipButton() {
     if (!currentAd) return;
     const skipOffset = currentAd.getSkipTimeOffset();
     if (skipOffset === -1) {
       // Ad is not skippable.
       skipButton.style.display = 'none';
       return;
     }
     const remaining = skipOffset - currentAd.getPosition();
     if (remaining <= 0) {
       skipButton.textContent = 'Skip Ad';
       skipButton.disabled = false;
     } else {
       skipButton.textContent = `Skip in ${Math.ceil(remaining)}s`;
       skipButton.disabled = true;
     }
     skipButton.style.display = 'block';
   }

   skipButton.addEventListener('click', () => {
     player.getAdsManager().skip();
   });


## web/airplay

AirPlay
*******

AirPlay support for PRESTOplay web SDK. Streams HLS from Apple devices
to AirPlay receivers via "AirPlayPlugin".

See "AirPlayPlugin" for the full API.


Using the AirPlay plugin
========================

This section shows how to integrate AirPlay with a custom UI.

Import the PRESTOplay AirPlay plugin:

   import "@castlabs/prestoplay/cl.airplay";

Add an AirPlay button to your page:

   <button id="airplay" style="display: none;">AirPlay</button>

Show the button when AirPlay is available:

   const button = document.getElementById("airplay");

   player.on(clpp.events.AIRPLAY_STATUS_CHANGED, (event) => {
     if (event.canCast) {
       button.style.display = "block";
     } else {
       button.style.display = "none";
     }
   });

Open the AirPlay target picker when the button is clicked:

   button.addEventListener('click', function () {
     const plugin = player.getPlugin(clpp.airplay.AirPlayPlugin.Id);
     plugin.showCastMenu();
   });

Listen for these events to detect the start and end of an AirPlay
session:

   player.on(clpp.events.AIRPLAY_CASTING_STARTED, () => {
     // AirPlay casting session started
   });

   player.on(clpp.events.AIRPLAY_CASTING_ENDED, () => {
     // AirPlay casting session ended
   });


AirPlay with DRMtoday and upfront authorization
===============================================

If your streams are protected with DRMtoday using upfront
authorization tokens, each playback session requires a new token.
Casting to a device over AirPlay counts as a new session.

Use "setDrmCustomDataModifier" to generate a new token for each DRM
license request (each playback session):

   player.setDrmCustomDataModifier(async customData => {
     customData.authToken = await createToken();
   });


## web/analytics

Analytics
*********

PRESTOplay web SDK analytics plugins: Conviva, NPAW (Youbora),
Broadpeak, and Mux Data. Each plugin is added via an SDK import and a
player configuration key.

PRESTOplay includes analytics plugins for Conviva, NPAW, Broadpeak,
and Mux Data.


Conviva analytics
=================

The Conviva Core SDK isn't published on the public NPM registry —
Conviva provides it directly to customers. Add it to your page with a
"<script>" tag:

   <script src="path/to/conviva-core-sdk.js"></script>

Note:

  The Conviva plugin depends on the Conviva Core SDK, so the core SDK
  must be added to the page before the plugin. The minimum supported
  version for this integration is "4.0.3".

Import the PRESTOplay Conviva plugin:

   import "@castlabs/prestoplay/cl.conviva";

Provide the Conviva configuration as part of the player configuration:

   const playerConfig = {
     ...
     conviva: {
       customerKey: 'YOUR_CONVIVA_CUSTOMER_KEY',
       serviceUrl: 'https://company.testonly.conviva.com',
       viewerId: 'YOUR_USER_ID',
       enableAdInsights: false
     }
   };

The Conviva sample
(https://github.com/castlabs/prestoplay-web-code-samples/blob/main/examples/analytics/conviva.html)
shows the complete setup, including the asset name reported through
"source.name".


NPAW analytics
==============

To get started with NPAW analytics, install the NPAW SDK and NPAW
adapters.

Note:

  The legacy Youbora v6 SDK integration is still available. To use it
  instead, configure the player with a "youbora" key instead of
  "npaw". It uses a separate "YouboraConfiguration" — its options
  aren't identical to "npaw"'s.

   npm install npaw-plugin@7.3.21
   npm install npaw-plugin-adapters@7.3.21

Alternatively, to install the ES5 version of the NPAW library, run:

   npm install npaw-plugin-es5@7.3.21
   npm install npaw-plugin-adapters-es5s@7.3.21

Import the PRESTOplay Youbora plugin and the NPAW SDK:

   import {clpp} from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.dash";
   import "@castlabs/prestoplay/cl.youbora";
   import * as NpawPlugin from 'npaw-plugin';
   import * as NpawPluginAdapters from 'npaw-plugin-adapters';
   window.NpawPlugin = NpawPlugin;
   window.NpawPluginAdapters = NpawPluginAdapters;

For custom NPAW configuration, see the example below. For full
details, see the NPAW documentation.

   const playerConfig = {
     ...
     npaw: {
       accountCode: '<YOUR ACCOUNT CODE>',
       // ... other NPAW options
     }
   };

You can also pass additional NPAW options per source, in the "npaw"
key of the "Player.open" configuration.

The NPAW sample
(https://github.com/castlabs/prestoplay-web-code-samples/blob/main/examples/analytics/npaw_v7.html)
shows the complete setup with the NPAW v7 SDK, a custom "errorFilter",
and buttons that trigger recoverable and fatal errors.


Custom error and events reporting
---------------------------------

To report custom errors or events as described in the NPAW
documentation, access the underlying NPAW adapter:

   const adapter = player.getPlugin(clpp.npaw.NpawPlugin.Id)
     .getAdapter();

   // The adapter may be null if there is no active session.
   if (adapter) {
     adapter.fireError(code, message);

     // Report an error and send a /stop event to stop the current session.
     adapter.fireFatalError(code, message);

     // Fire a custom event.
     adapter.fireEvent('eventName', dimensions, values, topLevelDimensions);
   }


NPAW App Analytics
------------------

To use NPAW App Analytics with PRESTOplay, pass your NPAW plugin
instance to PRESTOplay via "setNpawPlugin". For App Analytics
configuration details, see the NPAW documentation.

Import packages:

   import {clpp} from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.dash";
   import "@castlabs/prestoplay/cl.youbora";
   import * as NpawPlugin from 'npaw-plugin';
   import * as NpawPluginAdapters from 'npaw-plugin-adapters';
   window.NpawPlugin = NpawPlugin;
   window.NpawPluginAdapters = NpawPluginAdapters;

Use the NPAW plugin:

   const player = new clpp.Player('video', {
     license: '<your_license_key>',
     viewerId: '<user_id>',
     npaw: {
       accountCode: '<YOUR ACCOUNT CODE>'
       // ... other NPAW options
     }
   });

   const appAnalyticsPlugin = new NpawPlugin('<YOUR ACCOUNT CODE>');

   player.getPlugin(clpp.npaw.NpawPlugin.Id)
     .setNpawPlugin(appAnalyticsPlugin);

   // Now you can start playback.
   player.open({
     source: 'http://example.com/Manifest.mpd',
   });

   // Start session logging.
   sessionsPlugin.appAnalytics.newSession();
   // Fire a session custom tracking event.
   sessionsPlugin.appAnalytics.fireEvent(
     'search', // Name of the event
     { // Dimensions
       terms: 'searchedTerms'
     },
     { // Values
       foundItems: 25
     });


Custom error filter
-------------------

Use the "npaw.errorFilter" config option to prevent specific errors
from being reported to the NPAW service, or to modify an error's
"code", "message", "severity", or add extra "metadata".

   const player = new clpp.Player('video', {
     license: '<your_license_key>',
     npaw: {
       accountCode: '<YOUR ACCOUNT CODE>',
       errorFilter: error => {
         // Prevent error 3003 from being reported by returning null.
         if (error.code === 3003) {
           return null;
         }

         return {
           code: `${error.code}`,
           message: error.message,
           severity: error.severity,
           // metadata: { ... }, // Must be a serializable object.
         };
       },
       // ... other NPAW options
     }
   });


Broadpeak analytics
===================

Broadpeak SmartLib integrates with PRESTOplay via NPM and script tag.
See the Broadpeak project setup documentation for Broadpeak-specific
setup details.


Install with NPM
----------------

The minimum SmartLib version supported by this integration is
"5.4.4-808048b".

Add the Broadpeak NPM registry:

   npm config set @broadpeak:registry https://delivery-platform.broadpeak.tv/js/

Install SmartLib:

   npm install @broadpeak/smartlib@5.4.4-808048b
   npm install @broadpeak/smartlib-analytics@5.4.4-808048b

For other installation methods, see the Broadpeak project setup
documentation. If your project needs a pre-transpiled bundle, use
"@broadpeak/smartlib-all-compatibility" instead.

Import the SmartLib files and the PRESTOplay Broadpeak plugin:

   import { SmartLib } from '@broadpeak/smartlib';
   import '@broadpeak/smartlib-analytics';

   import { clpp } from '@castlabs/prestoplay';
   import '@castlabs/prestoplay/cl.broadpeak';

   window.SmartLib = SmartLib; // Required by the PRESTOplay Broadpeak plugin.


Configuration
-------------

Add the Broadpeak configuration to your player. Set
"broadpeakDomainNames" to a comma-separated list of the CDN domains
that serve content through Broadpeak:

   const playerConfig = {
     ...
     broadpeak: {
       broadpeakDomainNames: 'cdn.broadpeak.example,cdn2.broadpeak.example',
     },
   };

Two special values are also accepted: "'*'" if every URL the player
loads is served through Broadpeak, or "''" if none are.

See "BroadpeakConfiguration" for all available configuration options.


Session options
~~~~~~~~~~~~~~~

Pass session options via "broadpeak.sessionOptions", using
"StreamingSessionOptions" constants as keys:

   const playerConfig = {
     ...
     broadpeak: {
       broadpeakDomainNames: '',
       sessionOptions: {
         [StreamingSessionOptions.GDPR_PREFERENCE]:
           StreamingSessionOptions.GDPR_CLEAR,
         [StreamingSessionOptions.SESSION_KEEPALIVE_FREQUENCY]: 5000,
         [StreamingSessionOptions.SESSION_PRECACHE]: false, // Defaults to false when omitted.
       },
     },
   };

See the Broadpeak documentation on session options for more
information.


Broadpeak SSAI ads
------------------

The Broadpeak plugin integrates server-side ad insertion (SSAI)
tracking into PRESTOplay, automatically handling ad tracking and
emitting client-side events.

To enable this feature, extend your Broadpeak analytics installation
with the Broadpeak ads module:

   npm install @broadpeak/smartlib-ad@5.4.4-808048b

Then enable ad tracking in the Broadpeak config with "adTracking:
true" and, optionally, pass "adParameters" to enable ad
personalization. See the Broadpeak documentation for details about
supported ad parameters.

   player.open({
     source: {
       url: 'https://stream.broadpeak.io/...',
       type: clpp.Type.DASH,
     },
     broadpeak: {
       broadpeakDomainNames: '...',
       analyticsAddress: '...',
       adTracking: true,
       adParameters: {
         deviceType: 'desktop',
         userId: 'user123',
         contentGenre: 'sports',
         // ... any additional targeting parameters
       },
     },
   });

For ad click-through to work properly, the default HTML5 video
controls ("<video controls>") must be hidden. This is typically not an
issue, since most players use custom UI controls.


Broadpeak ad events
~~~~~~~~~~~~~~~~~~~

Ad metadata is surfaced through the standard ad events described in
Advertising.

For SSAI ads in live streams, duration and ad count may not be known,
especially for ads appearing on the live edge. In that case, "IAd"
returns "-1". Handle this case gracefully when rendering UI.

   ad.getDuration() // -1 (unknown)
   ad.getSequenceLength() // -1 (unknown)


Mux Data analytics
==================

To use the Mux Data plugin with PRESTOplay, include the Mux Data
library in your project via NPM.

Note:

  The minimum Mux Data SDK version recommended by this integration is
  "4.30.0".

   npm i mux-embed@4.30.0

Import the PRESTOplay Mux Data plugin:

   import "@castlabs/prestoplay/cl.muxdata";

Provide the Mux Data configuration as part of the player
configuration:

   const playerConfig = {
     ...
     muxdata: {
       envKey: '<your_env_key>'
     }
   };

If you use a module loader to import the Mux SDK into your project,
pass the Mux SDK as part of the config:

   import mux from 'mux-embed';
   ...

   const playerConfig = {
     ...,
     muxdata: {
       muxLib: mux, // The Mux Data core SDK.
       envKey: '<your_env_key>'
     }
   }

You can also override or extend the configuration passed to the Mux
library by setting "muxOptionsOverride" to an object containing valid
Mux SDK options.

   const playerConfig = {
     ...,
     muxdata: {
       muxLib: mux, // The Mux Data core SDK.
       envKey: '<your_env_key>',
       muxOptionsOverride: { // Valid Mux Data SDK options.
         debug: false,
         data: {
           player_name: 'MyPlatform-Web-Player',
           player_version: '2.3.7',
           viewer_user_id: 'new_id',
           page_type: 'watchpage',
           sub_property_id: 'some-id',
           // ...
         },
         automaticErrorTracking: false,
         respectDoNotTrack: false,
       }
     }
   }

The Mux Data sample
(https://github.com/castlabs/prestoplay-web-code-samples/blob/main/examples/analytics/muxdata.html)
shows the complete setup, including "muxOptionsOverride" and a custom
event helper.


Custom events
-------------

To report a custom event that isn't covered by the plugin, access the
underlying Mux Data SDK "emit()" method:

   const mux = player.getPlugin('mux')

   // Emit a heartbeat event with a custom value according to the docs.
   mux.emit('hb', {
     custom_value: 'custom_value'
   })

All mandatory Mux playback events are covered by the plugin and
shouldn't be emitted manually.


## web/audio-player

Audio player
************

Audio-only playback: pass an "<audio>" element to "Player". Same
components, configuration, and playback API as video. Use an
audio-only manifest.

The "Player" accepts any "HTMLMediaElement", so an "<audio>" element
works wherever the documentation uses a "<video>" element. Install and
import the same components as for video playback — see Getting started
and Components.


Create the player
=================

Add an "<audio>" element to the page:

   <audio id="audio" controls crossorigin="anonymous"></audio>

Create the player with the "disableContainer" option:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.dash";
   import "@castlabs/prestoplay/cl.hls";

   const player = new clpp.Player("audio", {
     license: "<your_license_key>",
     viewerId: "<user_id>",
   }, { disableContainer: true });

By default, the player wraps the media element in a container "<div>"
and positions the media element absolutely inside it (see Player
surface). The container then takes its size only from its own styles.
Video layouts set that size, but with an "<audio>" element the
container collapses to zero height and hides the native audio
controls. With "disableContainer: true", the "<audio>" element stays
in the page layout as is.

Keep the container only if you need a feature that renders into it,
such as HTML subtitles, ad overlays, or HLS interstitials. In that
case, give the container an explicit height, for example:

   .clpp-container {
     height: 54px;
   }


Load audio content
==================

Load content with "Player.open", the same as for video:

   await player.open({
     source: "https://demo.cf.castlabs.com/media/HLS/Non-Muxed/unencrypted/audio/prog_index.m3u8",
   });

If the manifest also contains video, set
"streaming.disableVideoTracks" so the player discards the video tracks
and downloads only audio:

   await player.open({
     source: "https://example.com/manifest.mpd",
     streaming: {
       disableVideoTracks: true,
     },
   });

"disableVideoTracks" applies only to MSE playback, not to native
playback such as Safari HLS or Tizen, and only to streams with
separate audio and video tracks. It doesn't remove video from
multiplexed audio and video streams. In these cases, use a manifest
that contains audio-only renditions. Otherwise, the player downloads
video segments that an "<audio>" element never displays.

For HLS through MSE, raw AAC segments (".aac") and MPEG transport
stream (MPEG-TS) segments require "mux.js" on "window.muxjs":

   import * as muxjs from "mux.js";
   window.muxjs = muxjs;

See HLS through MSE for installation details.

DRM-protected audio uses the same "drm" configuration as video. See
DRM.


Build custom controls
=====================

Custom UI: omit "controls" on the "<audio>" element.

Drive the controls through "Player.play", "Player.pause",
"Player.seek", "Player.setVolume", and "Player.setMuted", and update
them from these events:

* "clpp.events.STATE_CHANGED" for the play/pause state

* "timeupdate" for the position, using "Player.getSeekRange" so the
  seek bar also covers live streams

* "volumechange" for the volume and muted state

The audio player sample
(https://github.com/castlabs/prestoplay-web-code-samples/blob/main/examples/audio/audio.html)
is a complete page with play/pause, a seek bar, elapsed time, volume,
and mute controls for an audio-only HLS stream.

To let listeners switch between audio languages or qualities, use the
"TrackManager". See Tracks and languages.


Limitations
===========

Features that render video or overlays don't apply to an "<audio>"
element:

* Picture-in-Picture and fullscreen

* Subtitles: browsers don't render text tracks on "<audio>" elements,
  and HTML subtitles require the player container

* Ad and interstitial UI, which requires the player container


## web/changelog

Changelog
*********

New features, changes, and fixes in each PRESTOplay for Web Apps
release.


6.36.0
======


New Features
------------

* Add support for switching between audio tracks that use different
  codecs.

  * Enable it by setting "config.mediaSource.codecSwitchingStrategy"
    to "clpp.CodecSwitchingStrategy.SMOOTH".

* A player plugin can now change the stream URL by returning a new URL
  from "onContentWillLoad()" lifecycle hook.

* Add "player.getEffectiveUrl()" which returns the URL the stream is
  really loaded from, i.e. after a redirect or after an analytics
  plugin changed it. Every change of this URL is announced by the new
  event "clpp.events.EFFECTIVE_URL_CHANGED".


Changes
-------

* Change "player.getCurrentSource()" and "player.getLoadedSource()" to
  always return a source with absolute URL.

* Fix issues with ABR when "initialRestrictions" configured.

* Fix text track label on iOS.

* Fix support for track restrictions on video width, height and pixel
  count. (See player configuration option "restrictions").

* Fix processing of default key IDs from MP4 in HLS.

* Fix a false positive warning about missing DRM sessions in HLS with
  Widevine and PlayReady.

* Fix playback getting stuck after a video quality switch in some DASH
  streams.

* Fix seeking over a point HLS interstitial.

* Fix seeking into an interstitial in a live stream.

* Fix subtitles being downloaded and displayed after they were turned
  off.

* Fix "clpp.ima.ImaPlugin.isSdkMissing()".

* Fix subtitles in HLS live streams with discontinuity.


6.35.0
======


**Warning**
-----------

Changes in this release might be breaking for some very specific use
cases:

If you are using configuration flags "safari.enableHlsVideoTrackInfo"
or "safari.enableMetadata" please make sure to import the HLS
component "@castlabs/prestoplay/cl.hls.js".

In the unlikely event that you are using Google Closure Compiler to
build your codebase you should now supply your own API definitions for
this SDK. You can use "cl.externs.js" from version 6.34.1 as a
starting point.


New Features
------------

* Support "text/plain" MIME type for SRT subtitles.


Changes
-------

* Add "conviva.convivaSdkLogLevel" player configuration option to
  control Conviva SDK logging.

* Fix reporting of video source width and height in MuxData analytics.

* Fix flash of the main content before IMA SDK pre-roll ads on Tizen.

* Move configuration flags "safari.enableHlsVideoTrackInfo" and
  "safari.enableMetadata" under "@castlabs/prestoplay/cl.hls.js".

* Drop config options related to stall detection "stallEnabled",
  "stallSkip", these do not have a meaningful use-case.

* Stop shipping Google Closure Compiler API definition
  "cl.externs.js".

* Fix DASH content steering pathway cloning for empty root BaseURL
  entries.

* Fix playback of clear-lead encrypted content on Chrome and Edge,
  workaround known browser issues.

* Fix issue with processing all-zeroes "default_KID" in encrypted
  video streams.

* Fix detection of E-AC3 JOC (Dolby Atmos) audio tracks in DASH
  content.

* Fix "preferSpatialAudio" player configuration for track selection.

* Add support for "urn:mpeg:mpegB:cicp:ChannelConfiguration" audio
  channel scheme.


6.34.1
======


Changes
-------

* Improve recovery in case of gaps in the buffer on LG TV (webOS).
  Note that this recovery mechanism may not fully work on devices with
  old version of MSE such as Tizen 3 or webOS 3.

* Fix freeze of multi-period DASH streams with segment timing
  discrepancies in the manifest.


6.34.0
======


New Features
------------

* Add ABR stalled segment cancellation.

  * Improved ABR performance by cancelling long running segment
    requests.

* Add SVTA error codes.

* Add support for Broadpeak session options configuration.


Changes
-------

* Ignore autoplay attribute if found on "<video>" element. Autoplay
  should be configured in player configuration.

* Fix track selection by preferred language ("preferredTextLanguage",
  "preferredAudioLanguage") on Safari (native player) in case of
  tracks with regional variants of the same language (e.g. es, es-ES,
  es-MX).

* Fix text track selection and track IDs on Safari 16.

* Sort text and audio tracks on Safari by "NAME".

* Fix "preferredTextLanguage" selection of subtitles by language on
  Safari.


6.33.0
======


New Features
------------

* Add player configuration option "forceXhr" which can be used to
  select XHR API instead of Fetch API for all network requests.


Changes
-------

* Fix an issue with "disableAudioTracks" and "disableVideoTracks" when
  content is encrypted.

* Fix an issue with releasing remotely loaded text tracks on Safari in
  HLS (native player).

* Fix bandwidth estimate calculation in situation where HTTP responses
  for media segment do not have "Content-Length".

* Fix severity of errors emitted for retried HTTP requests.


Deprecations
------------

* Events "clpp.events.DESTROYING" and "clpp.events.DESTROYED" are
  deprecated and will be removed in version 7.

* Deprecate "clpp.Player.State.UNSET", the player no longer reports
  this state.


6.32.0
======


Changes
-------

* Send "Content-Type: application/octet-stream" HTTP header with
  Widevine DRM requests.

* Optimize DASH segment handling by creating "SegmentTemplate" and
  "SegmentList" segment references on demand.

* Add "ReceiverConfiguration" to "start()" method of
  "clpp.cast.Receiver". It is now possible to configure the player
  engine used under the hood by the Chromecast Receiver SDK.

* Fix buffering issues with low-latency HLS streams.

* Reduce live delay in HLS with interstitials.

* "clpp.Player" API changes:

  * Added "open()", same as "load()".

  * Added "setPosition()", same as "seek()".

  * Added "stop()", same as "release()".

  * Added "isPlayingAd()", returns "true" if currently playing an ad.

  * Added "getCurrentSource()", same as "getLoadedSource()".

  * Added "setRate()", same as "setPlaybackRate()".

  * Added "getRate()", same as "getPlaybackRate()".

* NPAW SDK v7 is now the default analytics integration. The minimum
  recommended version is v7.3.21.

  * NPAW analytics are now configured via the "npaw" player
    configuration key. The "youbora" key is deprecated and will be
    removed in a future version.

  * The legacy Youbora v6 integration remains available by using the
    "youbora" configuration key instead of "npaw".

* Fix issues with track duplication and losing active track selection
  on iOS when IMA ads are enabled.

* Added "clpp.events.TRACKS_REMOVED" event, fired when tracks are
  removed.


Deprecations
------------

* The following "clpp.Player" API methods are now deprecated and will
  be removed in version 7:

  * "load()", use "open()" instead.

  * "seek()", use "setPosition()" instead.

  * "getLoadedSource()", use "getCurrentSource()" instead.

  * "setPlaybackRate()", use "setRate()" instead.

  * "getPlaybackRate()", use "getRate()" instead.

* The "youbora" player configuration key is deprecated. Use "npaw"
  instead.

  * "player.getPlugin('youbora')" should be replaced with
    "player.getPlugin('npaw')".


6.31.1
======


Changes
-------

* Patch issue with peer dependencies in "package.json".


6.31.0
======

Please update dependencies if you are using them:

* "npm i @broadpeak/smartlib-all-compatibility@5.4.4-808048b"

* "npm i mux.js@6"

* "npm i npaw-plugin@7.3.21"

* "npm i npaw-plugin-adapters@7.3.21"


New Features
------------

* Enable IMA on iOS.

* Add support for SSAI ad management to Broadpeak plugin.


Changes
-------

* Simplify ad management API. Ads can now be controlled by calling
  methods of "clpp.Player" such as "play()", "pause()", "setVolume()"
  and "setMuted()".

* Fix issues with controlling volume:

  * During playback of CSAI and SGAI ads (IMA, Freewheel, HLS
    interstitials).

  * On Chromecast sender.

* Update the minimum supported version of dependencies:

  * Update mux.js to 6.0.0.

  * Update Broadpeak SmartLib to 5.4.4-808048b.

  * Update NPAW SDK to v7.3.21.

* Player surface configuration option "webOSStartupPatch" is set to
  "false" by default. This shouldn't have any negative impact on
  performance or behavior.

  * For more details refer to:
    https://demo.castlabs.com/docs/surface#webos-startup-patch

* Fix issues with live HLS streams:

  * Fix playback of streams where "EXT-X-TARGETDURATION" differs
    significantly from segment durations.

  * Fix issues with streams that contain discontinuities.

* Fix corner-case issues with listing HLS audio tracks in
  "clpp.TrackManager" on iOS.

* Fix triggering of "clpp.events.AD_LOADED" for interstitial ads in
  HLS.

* Fix a crash in low-latency HLS.


Deprecations
------------

* Old APIs for management of ads are now deprecated and will be
  removed in version 7.0.0, these are methods "resume()", "pause()",
  "setVolume()", "getVolume()" on "clpp.ads.IAdsManager". Use methods
  of "clpp.Player" instead.

* The "clpp.cast.Receiver.isApiReady" API is now deprecated and will
  be removed in version 7.0.0, there is no need to call this API.

* Volume controls on Chromecast Receiver are now deprecated, the
  feature is not supported by the platform.


6.30.0
======


New Features
------------

* Trigger "clpp.events.CAST_VISIBILITY_CHANGED" event on Chromecast
  sender when Chromecast Receiver App transitions to background or
  foreground on Google TV Streamer.


Changes
-------

* Fix "disableCustomPlayback" configuration option of IMA SDK Plugin
  on webOS devices which can be used to disable the plugin.

* Fix support for VAST in IMA SDK plugin on SmartTV Devices.

  * Add "isVast" configuration option of IMA SDK Plugin for custom
    playback with single video element when using VAST ads. This
    option needs to be set to "true" in order for VAST to work on
    Smart TVs. See
    https://demo.castlabs.com/docs/advertising#ima-sdk-on-smart-tvs

* Fix sending of custom messages from Chromecast receiver to sender.

  * If you send an object
    "clpp.cast.CastProxy#addMessageListener(listener)" listener now
    receives the object instead of a serialized string version of it
    as it did previously.

* Fix ads API on Chromecast sender for ad playback on receiver.
  Specifically fix methods to pause and resume ad playback via
  "player.getAdsManager().pause()" and
  "player.getAdsManager().resume()" on sender.


6.29.0
======


New Features
------------

* Add "clpp.cast.playlist.CastPlaylist". Use this class to create and
  manage playlists in Cast. See
  https://demo.castlabs.com/docs/cast#cast-playlist for more
  information.


Changes
-------

* Fix HLS EXT-X-DATERANGE parsing when multiple tags have the same ID.
  Omitting already defined attributes is now allowed.

* Fix IMA SDK Plugin mid-roll behavior on Tizen Smart TV devices.

* Expose Google Cast "audioTrackInfo" and "roles" on "Track"'s
  "customData" property.

* Add support for multiple HLS interstitials with the same start date.


6.28.0
======


**Warning**
-----------

DRMToday onboard component now uses Widevine V2 certificate by
default. If your deployment uses a different Widevine server
certificate, you need to specify it via
"drm.customData.serverCertificate" or pass in "null" to configure the
component to fetch the certificate from the server before a license
request.

For more information, see
https://demo.castlabs.com/docs/drm#drm-with-drmtoday-onboard.


New Features
------------

* DRMToday onboard component now uses Widevine V2 certificate by
  default.

* Trigger error events for network errors that get retried.


Changes
-------

* Fix timeline calculation for certain live DASH streams with
  thumbnails.


6.27.0
======


New Features
------------

* Add support for Queuing on Chromecast.

  * For more details refer to docs
    https://demo.castlabs.com/docs/cast#queuing

* Add CMCD support (version 1).


Changes
-------

* Fix an issue with "player.getStats()" which crashes for audio-only
  streams.

* Fix support for HLS playlists with beacon URLs that do not have a
  file extension.

* Fix HLS live audio/video out-of-sync issue. The playlists are now
  aligned when there are different EXT-X-PROGRAM-DATE-TIME tags on
  first segments.

* Add polyfills for Tizen 2.3.


6.26.1
======


Changes
-------

* Request URI used in network request and response modifiers is not
  modified.

  * If the URI was specified without scheme, it stays without scheme.


6.26.0
======


New Features
------------

* Add support for audio and subtitle track language in NPAW v7 plugin.

  * The language information is sent in the ping request.

* Add support for custom label for disabled subtitles in NPAW v7
  plugin.

  * The label can be configured via "youbora.disabledSubtitlesLabel"
    config option.


Changes
-------

* Update docs of IMA Plugin stating limitations on SmartTV devices.

  * Refer to the IMA Plugin documentation for more information.

* Fix an null pointer issue which occurs when a dynamic manifest turns
  static.


6.25.2
======


Changes
-------

* Fix "EXT-X-DEFINE" support for media segment URIs in HLS.

* Fix issues with HLS interstitials mainly related to seeking.

* Fix an issue in switching between muxed and separate audio tracks in
  HLS.

* Fix an issue of IMA Plugin causing player video events not to
  propagate after an ad break on Smart TV devices.

* Fix an issue of IMA Plugin causing player not resume playback after
  mid-roll on Smart TV devices.

* Handle situation of HLS interstitials of X-PLAYOUT-LIMIT updated
  when interstitial is already bound.


6.25.1
======


New Features
------------

* Add config option "streaming.gapTolerance".

* Add support for IMA SDK Plugin on webOS devices.

  * Refer to the IMA Plugin documentation for more information.


Changes
-------

* Fix an issue with playing media playlists directly with media
  segment file extension ".m4f" in HLS.

* Fix issues with preroll sometimes not playing with IMA SDK Plugin on
  Tizen and WebOS devices.

* Fix issues with the IMA SDK plugin on Tizen where the main content
  fails to resume at the correct position after a mid-roll ad.

* Fix support for METHOD AES-128 encryption in HLS.

* Fix an issue with AirPlay on iOS when switching between DASH and HLS
  playback.

* Fix "streaming.disableAudioTracks" config option for multi-period
  streams.

* Support EXT-X-DEFINE tags anywhere in the playlist in HLS.

* Fix issues with "setDrmCustomDataModifier()" in AirPlay related to
  loading a new stream during na AirPLay session.

* Fix an issues with upper case values of "Content-Type" HTTP header
  in media segment responses in HLS.

* Fix positioning of WebVTT subtitles based on the base direction of
  text.

  * "align:start" and "align:end" in WebVTT now respect the base
    direction.


6.25.0
======

(We released 6.25.1 instead)


6.24.0
======


New Features
------------

* Improve support for HLS interstitials.

* Add support for HLS streams containing both separate and muxed audio
  tracks.


Changes
-------

* Disable console logs by default. To enable logs call
  "clpp.log.setLogLevel(clpp.log.Level.INFO);" or refer to debugging
  docs

* Fix a issue with fMP4 HLS where init segments are re-fetched
  unnecessarily.

* Fix support for "EXT-X-MEDIA" "DEFAULT" attribute in HLS.


6.23.1
======


Changes
-------

* Change default EME version on Safari with native player to
  Apple-prefixed EME. This fixes issues with playback of encrypted
  content in that setting. On Safari with MSE player the default EME
  version stays unchanged (standard EME).


6.23.0
======


New Features
------------

* Add "drmResolver" config option which can be used to provide DRM
  configuration dynamically based on data from the manifest.

* Add ability to retrieve instance of NPAW SDK "getNpawPlugin".

  * Can be used e.g. to set custom options using
    "setAnalyticsOptions", for more details refer to NPAW v7 docs.


6.22.0
======


New Features
------------

* Add "streamType" option to the Yospace plugin.

* Emit SVTA signalling metadata for HLS interstitial ads.


Changes
-------

* Fix an issue with HLS interstitials with "X-ASSET-URI" and undefined
  "X-RESUME-OFFSET".

* Make sure the IMA plugin does not play postroll ads of the previous
  source when a new sources is loaded or after the player is released
  or destroyed.

* Fix support for "CUE=PRE" and "CUE=POST" in HLS interstitials.

* Improve Chromecast performance of low latency streaming.

* Fix initialization issue with NPAW v7 plugin when using the npm
  package.


6.21.0
======


**Warning!**
------------

Changes in this release might be breaking for some very specific use
cases:

* Change the default EME API version used by the player on Apple
  devices from the Apple-prefixed EME
  ("clpp.drm.eme.EmeFactory.Apis.APPLE") to the standard EME
  ("clpp.drm.eme.EmeFactory.Apis.STANDARD"). If needed, this can be
  changed back by configuring "drm.emeApi:
  clpp.drm.eme.EmeFactory.Apis.APPLE".


New Features
------------

* Add Yospace plugin.

* Support playback of CENC-protected DASH and SMOOTH content on
  Safari.

* Add the "mse.sendPlaybackSessionIdHeader" config option which when
  enabled adds the "X-Playback-Session-Id" header to every
  playback-related HTTP request of the MSE player.

* Add support for the "_HLS_primary_id" query param for HLS
  interstitials.

* Add integration for NPAW SDK v7 (Youbora).

  * Supported version 7.3.4, for more details refer to NPAW v7 docs.

* Add support for License Acquisition URL elements "<dashif:Laurl>" in
  DASH.


Changes
-------

* Switch to using default Shaka version instead of fixed version 4.3.4
  for CC receiver.

  * CAF's version of Shaka Player now follows default.

* Fix support for License Acquisition URL elements
  "<urn:microsoft:laurl>" in Widevine-protected DASH.

* Fix an issue with ABR bandwidth estimation.

* Update least supported version of NPAW SDK v7 integration to v7.3.8.


6.20.0
======


**Warning!**
------------

Changes in this release might be breaking for some very specific use
cases:

* Disallow passing a config with the "license" attribute into
  "player.load()" and throw an error if it happens. License is
  intended to be passed into the player constructor only.


New Features
------------

* On Safari with native player improve support for timeline cues:

  * Support cues in live streams.

  * Expose client-defined attributes, i.e. attributes with the prefix
    "X-" coming from EXT-X-DATERANGE.

  * Correctly trigger "TIMELINE_CUE_ENTER" and "TIMELINE_CUE_EXIT"
    events in case of overlapping cues and cues with unknown duration.


Changes
-------

* Recognize MP3 file extension.

* Fix the payload of ad events emitted for HLS interstitial ads.

* Fix audio and subtitle track selection when casting to Chromecast
  devices.


6.19.1
======


Changes
-------

* Fix an issue with error events for HTTP error responses on Firefox
  during streaming.


6.19.0
======


New Features
------------

* Add support for CMSD (Common Media Server Data)

  * When "CMSD-Dynamic" or "CMSD-Static" header is parsed from network
    request, player now emits event "clpp.events.CMSD_EVENT".

    * For details refer to CMSD Event.

  * MSE player now also supports CMSD headers **estimatedThroughput**
    and **maxSuggestedBitrate** to drive its ABR decisions.

    * For details refer to config.abr.useCmsd.

* Add "clpp.events.TIMELINE_CUES_CHANGED" event indicating a change in
  timeline cues.

* Support EXT-X-DATERANGE augmentation in HLS.

* Add Chromecast Web Receiver methods "setContentMetadata",
  "updateContentMetadata" supporting set or merge the current content
  metadata.

* Add support for HLS interstitials.


Changes
-------

* Evict old timeline cues in live streams.

* Allow extra whitespaces in HLS playlists.

* Fix a problem with text track selection when "preferForcedSubtitles"
  is configured.

* Fix typescript typings of utility functions.

* For Low Latency streams and "lowLatencyMode" the streaming
  configuration "ignoreDrift" is now "false" by default

  * "ignoreDrift" could cause additional startup delay for some
    streams. In case you still want to disable drift detection for low
    latency streams, set "ignoreDrift" of streaming configuration.


6.18.0
======


New Features
------------

* Add startover timeline type for DASH which supports seeking back to
  the start of the stream. Enable this timeline mode by configuring
  "manifest.timeline.type: "startover"" for startover streams.

* Make Widevine key system version configurable via
  "drm.widevineVersion" to allow for the selection of experimental key
  systems such as "com.widevine.alpha.experiment".

* Support multiple HLS EXT-X-MAP tags in a playlist.

* Upgrade supported version of "youboralib" to 6.8.59. Please upgrade
  to this version (e.g. "npm i youboralib@6.8.59").

* Support EXT-X-DATERANGE tags in Live HLS Streams.


Changes
-------

* Improve DRM logs.

* Fix an issue with segment eviction in startover DASH.

* Fixed handling of same GROUP-IDs across different media types in
  HLS.

* Fix an event "clpp.events.BITRATE_CHANGED" which wasn't properly
  triggered.

* Fix session initialization in the Broadpeak plugin.

* Update DRMToday Widevine server certificate.

* Fix reporting of bitrate by Conviva Analytics Plugin.

* Fix crash in repeated calls to "load()" on Tizen 4 and 5.


Known Issues
------------

* Breaking change of latest Google Cast SDK Web Receiver version
  3.0.0137

  * Causes a regression in audio and subtitle track selection when
    casting to Chromecast devices. Tracks appear disabled during the
    casting session.

  * Affects all SDK versions.


6.17.1
======


Changes
-------

* Fix ABR bandwidth estimation between repeated calls to load.


6.17.0
======


New Features
------------

* Add support for the "EXT-X-DEFINE" tag in HLS.


Changes
-------

* Fix "clpp.Player.getTextDisplayer()" API.

* Fix docs of "clpp.Player.setMuted()" API.

* Fix handling of empty attribute values in HLS.

* Upgrade supported version of "youboralib" to 6.8.57. Please upgrade
  to this version (e.g. "npm i youboralib@6.8.57").

* Fix a corner case with HLS VOD streams in which "EXT-X-DATE-RANGE"
  tags are not being parsed when program date time is equal to the
  start of Unix epoch.

* Add support for "EventStream@presentationTimeOffset"

  * If present, "presentationTimeOffset" attribute is now used to
    calculate the presentation time of Events.


6.16.0
======


New Features
------------

* Add support for smooth codec switching in multi-codec AdaptationSet
  scenarios.

  * This support is disabled by default and can be enabled by
    configuring "config.mediaSource.codecSwitchingStrategy" to
    "clpp.CodecSwitchingStrategy.SMOOTH".

  * Smooth codec switching is only supported on platforms compatible
    with "SourceBuffer.changeType()" and is currently limited to
    sources that do not require transmuxing. It's also disabled by
    default on platforms known to have issues with
    "SourceBuffer.changeType()"; currently, this applies to Tizen 6.0
    and 6.5 though the list may be expanded in the future.

  * For more details, refer to clpp.MediaSourceConfiguration and
    clpp.CodecSwitchingStrategy.


Changes
-------

* Fix an LL-HLS issue of playback stuck on buffering after first
  segment.


6.15.0
======


New Features
------------

* Add "clpp.events.LIVE_TURNED_STATIC" event triggered when a live
  stream becomes static.


Changes
-------

* Fix an issue with some timeline cue events not being emitted for
  cues which coincide with a gap between media segments.

* Fix an issue with playback of certain multi-period MPEG-TS HLS
  streams.

* Fix support of VAST Ads of IMA SDK Plugin.

  * VAST Ads are now supported and scheduled as a pre-roll.


6.14.1
======


Changes
-------

* Improve error handling of the "load()" method.

* Fix an issue on Safari where the player might get paused after
  seeking to the very end of the video.

* Fix an issue with the player going to ENDED state early.

* Fix an issue where Tizen devices misreport AC-3 support for
  encrypted content.


6.14.0
======


New Features
------------

* Add support for MPEG-DASH trick mode Adaptation Sets (i.e. those
  marked with an EssentialProperty descriptor with URL
  "http://dashif.org/guide-lines/trickmode").

  * If such Adaptation Sets are present in the MPD, they are listed as
    separate Tracks by the clpp.TrackManager#getVideoTracks() and
    marked with the "clpp.Track.trickPlay" flag set to "true".

  * These tracks and all their renditions are available only for
    manual selection using methods from clpp.TrackManager.

  * At the moment, trick play tracks are completely ignored by ABR,
    meaning their renditions are not considered for automatic
    selection when the normal track associated with this trick play
    track is active. It is also not possible to enable ABR when the
    currently active track is a trick play track.

  * For details, refer to the clpp.Track.trickPlay documentation.

* Add support for forced subtitles.

  * For text tracks recognized as forced clpp.Track.kind is set to
    ""forced"".

  * Added config.preferForcedSubtitles to prioritize forced subtitles
    over other text track types when "config.preferredTextLanguage" is
    also provided.

  * If "config.preferredTextLanguage" is not specified, but the
    "config.preferForcedSubtitles" is set to "true" we first try to
    fallback to the language from the currently selected audio track.
    If there is no audio track, then we fallback to the language of
    the video track as a last resort.

  * We assume that the forced subtitles are a subset of the full
    subtitles for the same language, i.e., all forced subtitles events
    should be included within the corresponding full subtitles. When
    the normal subtitles are being disabled, the corresponding forced
    subtitles in the same language are enabled automatically.


Changes
-------

* Fix issues with live presentation delay when "lowLatencyMode" is
  "true".

  * Fix "suggestedPresentationDelay" config option.

  * Make sure presentation delay gets set to 0 by default in DASH.

* Fix support for "timescale" attribute of thumbnail streams in DASH.

* Add Mux Data Plugin method to send custom events using "emit" method

  * For details refer to Mux Data Analytics Docs

* Upgrade supported version of Broadpeak Plugin.

  * Minimum recommended version is now v5.0.1-4c69e21. Refer to
    Analytics Documentation for details.

* Add support for session precache to the Broadpeak plugin.

  * This fixes issues with client side ad insertion with pre-rolls.

* Fix CMSD header parsing to be case insensitive.

* Fix "clpp.SpeedUpMode" enum missing "DECODER" value.

* Update minimum recommended version of Mux Data SDK to 4.30.0

  * Refer to Mux Data Analytics Documentation for details.


6.13.0
======


New Features
------------

* Add configuration options "cl.api.TrickPlayConfiguration" to control
  the behavior of trick play.

  * "trickPlay.speedUpMode" to control the mode of trick play
    "decoder" or "seek"

  * "trickPlay.preferTrickPlayTracks" to control the default selection
    of trick play tracks

  * "setPlaybackRate" method now accept optional "speedUpMode"
    parameter clpp.Player docs.

  * For details refer to trick play configuration.


Changes
-------

* Fix an issue where specific live/IPR DASH streams get stuck
  buffering at the end of the live stream instead of properly ending.

* Fix the issue introduced in 6.11.0 that causes the player to report
  error "1007" instead of "1001" in case of a network error.

* Emit recoverable error events from player in case thumbnails fail to
  load or wrong configuration is used.

* Improve behavior of Trick Play:

  * Improve fallback to seek mode when native trick play is not
    supported by platform (negatives rates, high speed trick play
    modes).

  * Added workaround for Tizen devices, fixing situation when reverse
    rate played frames forward during trick play.


6.12.0
======


New Features
------------

* Spatial audio detection and configuration:

  * Added detection of E-AC3 JOC audio content using DD+JOC signaling.

  * Added "clpp.Track.spatialAudio" value to indicate spatial audio
    content.

  * Added "config.preferSpatialAudio" to support manual prioritization
    of spatial audio.


Changes
-------

* Fix support for CR and CRLF line endings on Safari related to
  configs "safari.enableHlsVideoTrackInfo" and
  "safari.enableMetadata".

* Fixed position attribute of the "clpp-fill" css class and made it
  "absolute"

* Fixed issue with typescript types where namespace functions were not
  exposed

* Fixed issue with ESM module dependencies where required files were
  not automatically imported

* Fixed issue of fetching extra media segment to account for possible
  positive drift

  * Added detection of positive drift (difference between manifest and
    media segment time) and fetch extra media segment only when
    needed.


6.11.0
======


New Features
------------

* Add the "clpp.install" API which is now the official API for
  installing components and adding player capabilities. Components can
  be uninstalled via "clpp.uninstall".

* Add support for TTMLv2 "tts:textShadow" style attribute.


Changes
-------

* Fix issue when parsing PlayReady PSSH data.

* Make Widevine robustness configurable on Android Chrome.

* Fixed issue when parsing directly embedded PlayReady Header Objects.

* Fix support for multiple parallel player instances.

* Stop using the DASH attribute "minBufferTime" to decide the minimum
  buffer size. Note that the existing config
  "streaming.rebufferingGoal" should be used for that purpose instead.


Deprecations
------------

* The "clpp.Player.use" and "clpp.Player.remove" API is now deprecated
  and will be removed in version 7.0.0, use "clpp.install" and
  "clpp.uninstall" instead.

* The third parameter of "clpp.persistent.fetchLicense" is now
  deprecated and will be removed in version 7.0.0, use "clpp.install"
  instead.


6.10.0
======


New Features
------------

* Add Tracks original language value from manifest

  * Extend "clpp.Track" with "clpp.Track.originalLanguage" value which
    contains the original language string as it is present in
    manifest.

  * For details refer to Track.

* Add support for the "EXT-X-PROGRAM-DATE-TIME" tag in live HLS to the
  MSE player. If the tag is present its value is now accessible via
  "player.getTimelineOffset().seekRangeStartDateTime". The timeline
  offset can be used to display wall-clock time in the UI like so:

     const offset = player.getTimelineOffset();
     if (offset) {
       // Get the wall-clock values for UI
       const position = player.getPosition() + offset.offsetDateTime;
       const start = player.getSeekRange().start + offset.offsetDateTime;
       const end = player.getSeekRange().end + offset.offsetDateTime;
     }

* Add support for fetching decryption keys from DRMtoday for
  clear-key-encrypted HLS content ("METHOD=AES-128").

* Add support for Widevine EME configuration options

  * "persistentState" can be configured via the boolean option
    "drm.customData.widevinePersistentStateRequired"

  * "distinctiveIdentifier" can be configured via the boolean option
    "drm.customData.widevineDistinctiveIdentifierRequired"


Changes
-------

* Added "PlayerSurface" option to control webOS long startup patch
  "webOSStartupPatch"

  * This patch could cause unexpected behavior for specific player
    setups.

  * For details refer to PlayerSurface Configuration.

* Fix a glitch where WebVTT XML tags were being displayed along with
  the subtitle text in case of WebVTT subtitles embedded inside of MP4
  media files.

* Fix an issue of the "HtmlCueComponent" where some subtitle cues were
  not begin displayed in case of overlaps in segmented subtitles.

* Improve support of discontinuous HLS streams.


6.9.0
=====


New Features
------------

* Add config option "streaming.ignoreManagedMediaSourceStreamingHints"
  to ignore hints generated by Managed Media Source (MMS)
  "startstreaming" and "endstreaming" events. Default "false"
  optimizes for both performance and resource management, particularly
  in varied network conditions and on constrained devices, where
  managing power consumption and network efficiency is crucial. Use
  with caution as enabling this option could lead to increased power
  usage, making the default disabled setting a safer choice for
  general use cases.


Changes
-------

* HLS fixes:

  * Fix support for URIs with missing file extensions in discontinuous
    HLS.

  * Fix sporadic crashes in discontinuous live streams which contain
    thumbnails or subtitles.

  * Fix playback of MP4 streams with large baseMediaDecodeTime values.

* Additional Meta-Data such as accessibility information are no longer
  fetched by default with the Safari Native Player implementation.
  This behavior can be re-enabled by setting "enableMetadata" to
  "true" in the Safari Configuration.

* Fixed issue with Safaris native track selection where the player
  would sometimes mark the wrong track as selected.


6.8.0
=====


New Features
------------

* Add support for Managed Media Source (MMS).

* Add support for changing initialization sections and encryption in
  discontinuous VOD HLS.

* Add config options "streaming.disableAudioTracks" and
  "streaming.disableVideoTracks" to disable audio and video of the MSE
  Player (not applicable to Safari or Tizen native playback).

* Add config option "drm.ignoreUnrecognizedInitData". If the player
  encounters init data that cannot be processed (e.g., due to a
  malformed data payload), it will not pass it to the CDM to avoid
  license requests errors. This option allows to disable this behavior
  and pass the init data even if we couldn't parse it.

* Add IMA SDK support to MSE player on Tizen devices.

  * **Warning!** There are limitations related to analytics reporting
    for IMA SDK Plugin and SmartTV devices. Refer to the IMA Plugin
    documentation for more information.

* Add Mux Data Plugin support for Bandwidth Throughput Events.


Changes
-------

* Improve handling of segment duration drift in multi-period content.

* Fix track switching in audio-only content.


6.7.0
=====


Changes
-------

* HLS related fixes:

  * Fix corner cases in the handling of segment byte ranges.

  * Improve playlist validation and support check.

  * Low latency support:

    * Fix playlist validation with respect to
      "#EXT-X-SERVER-CONTROL:PART-HOLD-BACK".

    * Fix handling of low-latency playlist segments when low-latency
      support is disabled (It is disabled by default).

* Fixed Chromecast Cast Web Sender track manager issue, restoring the
  ability to list and change text/audio tracks during casting.


6.6.1
=====


Changes
-------

* Fix methods "clpp.utils.Mp4Parser.children()",
  "clpp.utils.Mp4Parser.sampleDescription()" and
  "clpp.utils.Mp4Parser.headerSize()".

* HLS related fixes:

  * Improve MIME type detection by leveraging "#EXT-X-MAP" tags.

* Fixed issue with some Smooth Streaming playback scenarios where the
  timeline was adjusted but the wrong base media decode time was used.

* Fixed minor issue with Youbora receiving consecutive buffering ended
  events during ad playback. The state was tracked already internally
  so these events were not reported and this has not affect on the
  data exposed to Youbora. It makes the internal implementation more
  consistent though and is slightly more performant since we are
  saving some calls.


6.6.0
=====


New Features
------------

* Expose accessibility information for audio and text tracks on
  Safari. Note that in order for this feature to work "NAME"
  attributes of "#EXT-X-MEDIA" must be unique in the HLS playlist.


Changes
-------

* Upgrade supported version of Broadpeak Plugin.

  * Minimum recommended version is now v04.05.01-328cb1e. Refer to
    Analytics Documentation for details.


6.5.0
=====


New Features
------------

* Add an option for filtering of Youbora error events. Configure a
  custom error filter via the "youbora.errorFilter" config option.

* Add new configuration options of 360-degree video playback
  "clpp.VrConfiguration".

  * "vr.sensitivity" sets the mouse/touch controls sensitivity. Must
    be a positive number.

  * "vr.invertHorizontalControl" inverts the mouse/touch movement for
    horizontal axis.

  * "vr.invertVerticalControl" inverts the mouse/touch movement for
    vertical axis.


Changes
-------

* Upgrade supported version of "youboralib" to 6.8.49. Please upgrade
  to this version (e.g. "npm i youboralib@6.8.49").

* Fixed issue with parsing WV PSSH data from Version 1 PSSH boxes

* Fixed persistent license removal

* Added "enableSessionCacheForSkd" as an option to the DRM
  Configuration. We encountered issues with FairPlay in native Safari
  when SKD initialization is used. What happens is that we do received
  multiple requests for the same key request from the native engine
  and if we are not full-filling the requests, it can cause a
  decryption error. The default implementation ignores the session
  cache and will handle each "encrypted" event. In this case, there
  might be duplicated requests triggered by the player for license
  keys that were already fetched. This is done to avoid any potential
  decryption errors. Setting this option to true will enable the
  session cache also for SKD init data and avoid any redundant license
  requests. **Note** that you might encounter more 3016 decode errors
  on Safari with native playback and SKD initialization when enabling
  the session cache.

* Work around a Safari 16.5 issue where in certain cases HLS live
  streams do not start playback at current time (live edge) as they
  should, but instead they start some time in the past.

* Fix an issue with the import of Broadpeak SDK occurring when code is
  bundled with a bundler, which performs hoisting of import statements
  (such as Webpack).


6.4.1
=====


**Warning!**
------------

Changes in this release might be breaking for some very specific use
cases:

* Removed "clpp.EventBus" from the API. *It is unlikely that this will
  cause any issues, since this API is not intended to be public and is
  not relevant to player functionality.*


New Features
------------

* Add an option to enable detailed video track info and player stats
  for HLS on Safari. To enable this experimental feature configure
  "safari.enableHlsVideoTrackInfo: true".


Changes
-------

* Fix the "textStyle" config option for subtitle styles.

  * Make sure it always overrides styles embedded in TTML and WebVTT
    files and any other styles.

  * Make sure "textStyle.edgeType: "none"" config removes any existing
    text shadow from the subtitles.

* Fix handling of HDR CICP EssentialProperty schemes for DASH streams.

  * Add CICP ColourPrimaries, Transfer-Characteristics,
    MatrixCoefficients as valid EssentialProperty.

* Fix "ReferenceError" due to unavailable "MediaEncryptedEvent" on
  Safari < 12.1.


6.4.0
=====


New Features
------------

* Add track accessibility features to the public API for DASH streams
  (under "clpp.Track.accessibility").

* HTTP status codes that will not trigger the retry behaviour can now
  be configured. Previously, status codes 401 and 403 were not
  triggering the retry behaviour. This is still the default, but can
  be changed now in the AttemptParameters for requests types, and
  globally by adjusting "clpp.net.DEFAULT_FATAL_STATUS_CODES". The
  configuration is also forwarded to clpp.net.Request and can be
  adjusted per request using a RequestModifier.

* Add support for Low-Latency HLS.

  * Support for Partial Segments and Preload Hint.

  * Support for Blocking Playlist Reload.

  * Configuration by Player configuration property "lowLatencyMode",
    defaults to "false".


Changes
-------

* Fix timeline of dynamic to static transition in DASH.

* Several improvements of tracks.

  * Fix an issue in DASH where similar "AdaptationSet" tags with
    distinct "Accessibility" tags where being processed as renditions
    of the same track instead of being treated as two distinct tracks.

  * Fix a corner-case issue where tracks with the same roles but in a
    different order were being treated as two separate tracks instead
    of a single track with two different renditions.

  * Fix issues with audio track selection when "preferredAudioRole" or
    "preferredAudioLanguage" is configured.

* Warn when an unsupported version of "youboralib" is supplied to the
  "YouboraPlugin" and emit a recoverable error. Supported versions are
  6.8.12 - 6.8.25.

* Fix support for custom styling of subtitles.

* Fix "clpp.utils.obj.merge".

  * Make sure it merges attributes with values that are DOM "Element".

  * Fix documentation: "clpp.utils.obj.merge" merges from left to
    right, not the other way around.

* Improve "clpp.PlayerSurface".

  * Add "clpp-video" class to the video/media element.

  * Protect PRESTOplay class attributes from modification. This
    prevents unexpected styling issues related to the re-rendering of
    the video or container element that can easily occur when used
    with React, Vue or similar UI frameworks.

* Improve validation of arguments passed to "clpp.Player".

* Fix an issue where special kinds of live streams such as IPR
  (in-progress recording) were not correctly classified as live by
  "Player.isLive()".

* Fix error reporting for invalid or failing thumbnails (VTT, BIF).

* Improved sync byte search for TS segment start time parsing

* Update metadata "player_name" default of Mux Analytics to
  "CastLabsPlayer"

* Fix time synchronization issues during sender/receiver switch for
  Smooth Streaming live streams on Chromecast.

* Dedicated handling for Widevine server certificate requests. We are
  now logging Widevine Server Certificate requests explicitly and set
  the "licenseRequestType" of the "request" to 'certificate-request'.

* Fixed issues with handling key restrictions in different multi
  period scenarios


6.3.0
=====


**Warning!**
------------

Changes in this release might cause breaking changes for some use
cases. Please double-check your current usage of the following:

* "player.getPresentationStartTime()" - For non-live content, this
  method now returns "null", instead of the previous "0".


Changes
-------

* Fix issues with "YouboraPlugin".

  * Fix crash when Youbora configuration is not passed via
    "clpp.Player" constructor.

  * Fix an issue where Youbora plugin stopped reporting events after a
    call to "setYouboraPlugin".

  * Fix an issue with the import of "youboralib" and
    "@castlabs/prestoplay/cl.youbora" when used with a bundler which
    performs hoisting of import statements (such as Webpack).

* Improvements on FPS License management. This release includes
  several improvements related to the FairPlay License management with
  the Apple Prefixed implementation as well as the EME implementation.
  Handling of multiple license requests is improved, and we added a
  few workarounds that allow us to handle rejected payloads better and
  reduce the number of failed playback attempts which previously
  caused 3016 decode errors.

* Fixed an issue where the initials FPS license request with the EME
  implementation was incorrectly reported as a renewal request.

* Changed the behavior of "player.getPresentationStartTime()". The
  method now only returns numerical values when the stream is live and
  the calculation of presentation start time is possible; otherwise,
  it returns "null". **Note: potentially breaking change!**

* Chromecast Cast Web Sender & Web Receiver related changes:

  * Fixed time synchronization issues for DASH live streams between
    cast sender and receiver. The updates address problems related to
    seeking, switching between sender/receiver, and incorrect values
    returned from SDK during active casting.

  * Fix "player.getDuration()" return value during live stream
    casting. The function now correctly returns "Infinity", addressing
    the previous bug where "-1" was incorrectly returned. This fix
    applies to both receiver and sender sides during active casting.

  * Changed the behavior of the
    "clpp.cast.CastProxy.setContentMetadata()" method. This method now
    also accepts null, which will clear the metadata.

  * Added the "clpp.cast.CastProxy.getContentMetadata()" method.

  * In an effort to simplify the "clpp.cast.CastProxy" metadata API,
    we are deprecating the following methods: "setContentTitle()",
    "setContentImage()", "setContentArtist()",
    "setContentReleaseDate()", "clearContentMetadata()". These methods
    will still work, but they will be removed in the next release.
    Please use the "setContentMetadata()" method instead. Refer to the
    documentation for details.


6.2.8
=====


Changes
-------

* Fix clock sync fallback in DASH.

  * This fixes an issue where one failing "UTCTiming" tag cancelled
    the whole time sync. Now all "UTCTiming" tags are tried one-by-one
    until one succeeds, or if all fail, only then the time sync is
    cancelled.

  * Warn whenever a clock sync fails. Warn when no UTCTiming elements
    are found. Warn when a direct time scheme
    ("urn:mpeg:dash:utc:direct:2014") provides an invalid value.

* Fix "clpp.thumbnails.ThumbnailsPlugin.get()" method, which now
  returns the correct thumbnail at a specific position for BIF
  thumbnails.

* Change parsing process for dynamic DASH and always perform clock
  synchronization before playback. This fixes issues related to wrong
  system time. E.g. "player.getPresentationStartTime()" is now
  calculated correctly, even when system time is wrong.

* Fix the issue where "player.play()" does not trigger a
  "clpp.events.AUTOPLAY_NOT_ALLOWED" event when Safari blocks the play
  request due to the 'Stop Media with Sound' auto-play policy.

* Fix "clpp.thumbnails.Thumbnail.element()" method, which now works as
  expected even if the URL of the thumbnail image contains round
  bracket characters.

* Fix "clpp.thumbnails.ThumbnailsPlugin.get()" method, which now
  returns the correct thumbnail at a specific position for WebVTT
  thumbnails.

* Fix issue with multiple (unnecessary) license requests triggered.

* Fix the license request/response modifiers for Chromecast Receiver:

  * The "licenseRequest" modifier now correctly indicates the "POST"
    method instead of falsely reporting "GET" for the "request"
    object.

  * The "licenseResponse" modifier is now properly awaited when
    defined as async.

  * Please refer to DRM section in manual for limitations of using
    request/response modifiers in Chromecast Receiver.

* Improve error logging for "MP4_SIDX_WRONG_BOX_TYPE" code. Now there
  is an URL, byte-range, size, and a 1kB sample of the erroneous SIDX
  box provided within the "clpp.Error" optional data.

* Handle FairPlay license loading with EME implementation more
  consistently and avoid redundant license requests.


6.2.7
=====


Changes
-------

* Add "PlayerConfiguration.streaming.relativeTextTimestamp" config,
  which when set to true will force text cue times to be offset by the
  containing media segment start time.

* Add VR plugin for 360-degree video playback. See
  http://demo.castlabs.com/#/docs?q=clpp.vr.VrPlugin for more
  information.

* Fix appending "merchant" name to the DRMtoday Onboard Fairplay
  certificate URI.

* Fixed an issue with very rapid loads where the engine will not be
  released properly


6.2.6
=====

With this version we started to publish PRESTOplay to NPM. You can now
simply integrate the player and its modules my installing it as a
dependency:

   npm install @castlabs/prestoplay

**Note** that we needed to make some changes to the file names and
folder structure of the SDK. In previous releases we were using
".esm.js" and ".min.js" to differentiate CJS (UMD) and ESM modules. We
needed to change the structure slightly and use "esm" and "cjs"
folders now instead while keeping the actual file names the same.


Changes
-------

* Introduced API for changing EME implementation to use.

  * Due to that it is now possible to use MSE with encrypted content
    on Apple devices.

  * Please refer to DRM section in a manual for more info.

* Added a "streaming.preferNativeHlsOnSafari" config option to
  explicitly specify should we play HLS content using MSE or native
  playback.

  * By default, this option is set to "true".

  * Please refer to Components section in a manual for more info.

* Fix "PLAYER_ERROR_NOT_SUPPORTED_FILE" issue on Tizen for certain
  DASH streams.

* Fix startup issue for certain live streams on webOS 6.

* Improved "player.getSeekRange()" for native Safari playback.

* Simplified DRMtoday FairPlay certificate request structure

* Introduce the "PlayerConfiguration.forceWaitForTracks" flag to
  indicate that the load promise should only resolve once data is
  loaded. This allows the load promise to wait until data arrived and
  the track model is fully initialized. Note that, if at all, this is
  only required for some special cases on Safari native playback to
  make sure that tracks are resolved before load resolves. In the
  regular case the track model is already initialized when the load
  promise resolves.

* Fixed regression on default FPS license response handling. We missed
  a case where license responses should still be base64 decoded.

* Fix seekRange() values for HLS LIVE streams with MSE.

* Fixed issue with DRMtoday and FairPlay integration for multi-key
  cases where the SKD erroneously contains not only a keyId but also
  an asset id

* Added basic TTML to VTT transcoder. This allows to sideload TTML
  subtitles with native text displayer (e.g. iPhone Safari). Be aware
  that in this iteration we skip most of the styling information from
  TTML, so just text cues are transcoded.

* Added support for manually setting the Widevine Server Certificate
  in an easy way

* Added support for automatic retries in case a wrong Widevine
  Certificate was used


6.2.5
=====

* ESM files are now compatible with ECMAScript 2015.

* Improved start up time on webOS 4+ devices.

* Broadpeak plugin has been upgraded to version 4.

  * Minimum supported version is now 4.1.1-f5f806. Version 3 does not
    work anymore with current implementation.

* Fix playback of PlayReady protected content on WebOS TVs.

* Fix disabling ABR when selected track/rendition is currently active.

* Upgrade Conviva integration to latest version (v4.5.8)

* Add Verimatrix VCAS component for easy integration with Verimatrix
  DRM license servers.

* Prevent timeline discontinuity playback issues on webOS 6.

* Fix DASH alternative audio tracks unavailable for encrypted content.

* Fire tracking requests for DASH events with duration equal to 0.

* Fix HLS AES-128 encryption for streams without IVs provided in the
  playlist.

* Add support to attach custom Youbora Plugin object to Castlabs
  analytics plugin.

* Chromecast - do not fail on text stream failures.


6.2.4
=====

* Expose Youbora Adapter & Youbora Ads Adapter in
  "clpp.npaw.YouboraPlugin" via "getAdapter()" and "getAdsAdapter()"
  methods.

  * Please refer to documentation for more info.

* Fix Conviva support on Chromecast with PRESTOplay SDK for Android
  sender

* Added "config.preferredAudioCodec" to support manual prioritization
  of audio codecs

* "config.preferredVideoCodec" now accepts array of preferred codecs
  in priority order

* Fix "player.load()" not working on Tizen 4 & 5 after going to
  background and back to foreground.


6.2.3
=====

* Add support for HLS Image Media Playlist. Refer to Thumbnails
  section in manual for more info.

* Added "abr.initialRestrictions" configuration to specify
  restrictions for the first ABR switch.

* Plugin IDs unification.

* Fix issues with setting "startTime" in Safari.

* Report initialized components to Download Portal.

* Prevent multiple "/register" calls to Download Portal.

* Added "pauseWhenInBackground" configuration. When set to "true", the
  playback will be paused when the application is put into background
  and resumed once the application is back in foreground.

* Added "streaming.patchEdgeWhenMixedContent" field in player
  configuration to apply content workarounds.

* Clear text cues on seek

* Support for "SegmentTemplate.endNumber" in a DASH manifest


6.2.2
=====

* iOS - fix rare bug with going to ended state on some iOS devices.

* iOS - fix false positive online events on ConnectivityChecker.

* DRM updates:

  * Introduced "clpp.drm.InitDataTransformer" modifier to provide the
    ability to directly parse and manipulate initData and construct
    custom payloads for exchange with the CDM in use. Check the DRM
    configuration section in manual for more info and examples.

  * "clpp.drm.KeySystem" enum is now extended with "NONE" and
    "CLEAR_KEY" values for more consistent and less error prone
    handling of DrmEnvironment's key system configuration.

  * Added "sessionId" field to network request. This allows a
    request/response modifier to determine which EME session made the
    request.

  * A set of "clpp.utils.FairplayUtils" utils are now available for
    handling common FairPlay DRM tasks.

* "clpp.utils.BufferUtils" are now available for use with array
  buffers.


6.2.1
=====

* Added ability to specify Widevine and PlayReady robustness in the
  "config.drm.customData"

* Fixed subtitles not visible when the HTML text displayer not loaded
  in Safari

* Added "connectivityCheck" field in player configuration to check is
  network available.

  * When network availability status changes, player now emits
    "clpp.events.ONLINE_STATUS_CHANGED" event with "online" boolean
    property.

* Added the "config.streaming.addMissingTimelineCues" option

* TTML parser

  * Add the presentation time offset to cue timestamps

* Do not set server certificate on WebOS 3 due to a bug in WebOS'
  "MediaKeys.setServerCertificate()" implementation.


6.2.0
=====

* Player Surface improvements:

  * "clpp.Player#getSurface()" method now returns
    "clpp.IPlayerSurface".

  * "clpp.IPlayerSurface" interface is now exported.

  * "clpp.PlayerSurfaceCss" has been removed.

  * Following options from "clpp.PlayerSurfaceConfiguration" has been
    removed. Please check Migration Guide for more info.

    * "moveCssToContainer"

    * "containerTag"

    * "mediaTag"

    * "controls"

    * "css"

  * Added manual for Player Surface configuration.

* Subtitles improvements

  * SRT / VTT

    * The parser has been moved to an independent component,
      "clpp.vtt.min.js"

    * Please check "v6.2 Migration Guide" for more info.

  * TTML

    * The parser has been moved to an independent component,
      "clpp.ttml.min.js"

    * The parser is compatible with TTML v1 now

    * The parser converts pixel sizes to percentages in order to build
      responsive layouts

    * Please check "v6.2 Migration Guide" for more info.

  * The HTML text displayer

    * Following options from "clpp.PlayerConfiguration" has been
      removed.

      * "enableEnhancedSubtitleManager" (use "enableHtmlCue" instead)

* "clpp.utils.strings" fixes:

  * "durationToStirng()" renamed to "durationToString()".

  * Removed "toBase64()" and "fromBase64()". You can still use
    equivalent methods from "clpp.utils.Uint8ArrayUtils".

* DRM updates:

  * Introduced "clpp.drm.SessionContext" object for various
    interactions during DRM session. Object is passed as a 3rd
    argument to license request & response modifiers.

  * "clpp.drm.SessionContext#ldlDelay" can be used to manually set
    delay between license requests when "license-renewal" event is not
    fired by CDM. This is primarily a case for PlayReady
    implementation.

* Conviva updates:

  * Do not set "osVersion" by default for LG and Hisense TVs.

  * add "deviceMetadata" field in conviva configuration to pass any
    needed metadata by user. See "clpp.ConvivaConfiguration" doc for
    more details.

* Dropping support for IE 11

  * Due to the consistently low level of usage, our PRESTOplay team
    has decided to discontinue IE 11 support with  6.2.0 release.
    However, maintenance support for IE 11 will still be provided for
    the next 6 months (ending 1 May 2022) through our 6.1.X versions.
    Dropping support for IE 11 will also allow our team to focus more
    time on providing the best in modern playback features and
    experiences.


6.1.13
======

* Do not preconfigure DRM Engine when "source.drmProtected" is set to
  "false".

* Playback of direct MP4 files on Tizen

* Optimize audio track switching on Smart TV (prevent playback from
  freezing after track switch)


6.1.12
======

* Improve HLS with discontinuities playback when
  "#EXT-X-DISCONTINUITY-SEQUENCE" is missing.

* Add "manifest.playreadyVersion" field to force update of PlayReady
  header to specified version.

* Speed up "HtmlTextDisplayer" component on slower devices.

* Fix state reporting bug on Tizen 2.3


6.1.11
======

* Allow to configure network request parameters in DRM module by
  "clpp.DrmConfiguration.attemptParameters" configuration field.

* Use "com.microsoft.playready.recommendation" key system on Microsoft
  Edge:

  * Player tries to enforce hardware protection by default if DRMtoday
    is in use.

  * Robustness levels might be also specified in custom DRM
    environments.

  * Robustness levels for Playready are introduced in
    "clpp.drm.PlayreadyRobustnessLevel".

* Send detailed message about license & certificate request failures
  to MuxData plugin.

* Youbora - add calculation of ad visibility.

* MuxData - fix order of ad-related events.

* Conviva + Chromecast - do not start new session on sender during
  casting.

* Fixed issue with video only content and codec selection

* Fixed issue with Widevine PSSH creating from newer PlayReady PSSH
  data

* Prefer native playback capabilities in Safari

* Fixed Conviva seek event order on Tizen platforms

* Recognize the "stpp.ttml" codec for subtitles

* Add preferred audio language support for Tizen 2.x

* Fixed issue with selected audio track not being available on Tizen
  2.4


6.1.10
======

* Youbora - report DRM system in use.

* Youbora - do not start session when no intent to play.

* Conviva - add a way to set device brand and connection type. Please
  check "clpp.ConvivaConfiguration" doc for more info.

* HLS - introduced support for "#EXT-X-DISCONTINUITY" &
  "#EXT-X-DISCONTINUITY-SEQUENCE" tags.

* Fixed aborting a loading operation

* Fixed resetting a text displayer on track changed

* Add "clpp.cast.Receiver#setLoadRequestDataInterceptor()" method.
  Please check documentation for more info.

* Fixed the order of nested cues when rendering with the HtmlCue
  component

* Improved positioning logic in the htmlcue component.

  * The "display: inline" has been added to the ".clpp-text-cue" class

  * The "line-height" has been added to the ".clpp-text-cue" class

  * The "line-height" has been removed from the ".clpp-text-container"
    class

  * "position, inset, display" inline attributes have been removed
    from cue nodes

  * "visibility, direction" inline attributes have been added to cue
    wrapper nodes

* "config.preferredTextLanguage" and "config.preferredAudioLanguage"
  options accept an array of languages

* Muted the operation aborted error

* Mux Data plugin fixes:

  * More accurate Video Startup Time metrics when autoplay is on.

  * "timeupdate" events reporting.


6.1.9
=====

* Introduced CDN error fallback. Check "clpp.Player.setCdnFallback()"
  documentation for more info.

* Youbora - do not create new session when seeking beyond end of
  content on Safari.

* Fix Chromecast + Conviva integration.

* Youbora - do not call "/bufferUnderrun" twice.

* Add support for IMSC1 text based & image based subtitles.

* Add support for changing player name in Conviva configuration.

* Fix Endless loop after seek on Tizen 3

* Fix wrong video height and width using AVplay on Tizen with
  resolution below 1080p

* Prefer text streamer for tizen native playback to mitigate issues
  with subtitles


6.1.8
=====

* Fix going to background and foreground mode again on 2021 TV
  platforms.

* Fix issue with Smooth Streaming playback freezes when subtitles are
  enabled.

* Fix playback of DASH with PlayReady ContentProtection only on
  Firefox.

* Fixed removing XML tags from text cues.

* Youbora - fire "/join" request when autoplay is blocked.

* Added SMPTE-TT Embedded in ID3 for HTTP Live Streaming support

* Added support for nested SMPTE-TT tags

* clpp.tizen.TizenComponent: Normalize language code for tracks.


6.1.7
=====

* Added a new config option, i.e.
  "config.htmlcue.enableResizeObserver"

* Added support for MPEG-DASH Callback Event

  * Introduced new "clpp.TimelineCueType.DASH_CALLBACK" timeline cue
    type.

* Fix issue with Fairplay multikey playback when using DRMtoday
  Onboard.


6.1.6
=====

* Fixed an issue with seeking after DASH dynamic to static conversion.

* Fixed the initialization of the player container.

* Fixed the vertical rl mode in the html cue component

* Fix issue with subtitles selection after period transition.

* Do not play IMA ads if platform uses single video element.

* Optimize playback of Smooth Streaming content on TV platforms
  (webOS, Tizen).

* Fix playback of AES-128 encrypted content on webOS devices.

* Fix "HTMLTextDisplayer" component stalls on webOS 3.x devices.

* Update manual section about playback on older Tizen TV platforms.

* Added support for SMPTE-TT images (TTML)

* Added support for cue regions (WebVTT)

* Added support for embedded styles (WebVTT)


6.1.5
=====

* Added the "player.setDrmCustomDataModifier" to the player interface.
  The method allows modifying DRM custom data before casting to Apple
  TV.

* Added "muxdata.muxOptionsOverride" config field. This allows to
  extend and/or override the config that is passed to the Mux SDK by
  the Mux Data plugin.

* Skip displaying subtitles if dimensions of the text container are
  zero.

* Enable MSE/EME (spec version 0.1b/Aug 2012) based playback on older
  Tizen devices (version 2.X).

* Follow redirections when playing Smooth Streaming content.

* Try to load Smooth Streaming manifest from URL with "/Manifest"
  suffix if first request with original URL resulted with HTTP error.


6.1.4
=====

* Accept empty TTML segments

* Fix text track selection based on the "preferredTextLanguage" option

* Fixed cue offset when X-TIMESTAMP-MAP not defined

* Tizen Improvements:

  * Fix PlayReady protected playback on legacy Tizen devices (version
    2.x)

  * Add preliminary Widevine support

  * Improved error handling and reporting

  * Add implementation for "getDrmInfo"

  * Fix native and MSE based playback on Tizen 3.0

* Fixed rare bug with incorrect seek ranges for live streams during
  casting.

* Add Mux Data plugin

* Support timeline cues (EventStream / SCTE-35) for Chromecast
  receiver.

* Chromecast - use PlayReady for Smooth Streaming playback.

* Preserve media element mute state in subsequent load requests.


6.1.3
=====

* Fixed text track selection based on the "preferredTextLanguage"
  option

* Generate Widevine or Playready content protection elements if needed

* Added header based DRM

* Add a way to pass optional playback config when starting casting.

  * Check "clpp.cast.CastProxy#cast()" spec for more info.

* Introduced Live Edge Chasing algorithm. New configuration fields
  added. Please refer to the documentation to learn more about it.

  * "streaming.enableLiveEdgeChasing"

  * "streaming.chasingRate"

  * "streaming.startChasingAt"

  * "streaming.stopChasingAt"

  * "streaming.chaseJumpDistance"

* Chromecast metadata management.

  * Introduced "clpp.cast.CastProxy" methods to set content metadata.

  * Ability to check current metadata on receiver side by
    "clpp.cast.Receiver#getContentMetadata()" API.

  * Please refer to "clpp.cast.CastProxy" and "clpp.cast.Receiver" for
    more info.

* Conviva: Fix initial bitrate selection not reported when autoplay is
  disabled.

* Fixed triggering response modifiers on error


6.1.2
=====

* Adobe Milestone Analytics support (BETA).

* Fixes issue with offline license loading

* Guess MP4 text codec when manifest does not specify it explicitly.

* Conviva bug fixes

* Ensure that a player release can only be triggered once until
  completed The "release()" method on the player will now always
  returns the same promise until the release is completed.

* Fixed issue with manifest retry parameters on live playback


6.1.1
=====

* Fixed issue with FPS requests triggered by AppleTV devices in
  Airplay sessions

* Block rendition selected by ABR if it cannot be downloaded.

* Chromecast: do not disable text track when switching audio tracks on
  sender.

* Added support for DASH live to vod transition.

  * Added "clpp.events.MPD_TYPE_CHANGED" event to reflect this change.

* Fix PlayReady playback when PlayReady PSSH is not available.

* Add Vimond plugin

* Fix issue with AirPlay state not being consistent when starting or
  resuming an Airplay session. Please note that this seems to be a bug
  in Safari and to work around it we put the local player back into
  playing state. This will result in very short state jump into paused
  state and before the player goes back into playing state.


6.1.0
=====

* Fix playback issues with HLS audio only content on MSE.

* Fix incorrect audio TS handling on Microsoft Edge

* Persistent license.

  * Introduce "clpp.persistent.fetchLicense()" API to fetch license
    without player instance. Check manual for more info.

  * Prevent sending license request twice when Persistent Component is
    in use.

* Smooth Streaming improvements.

  * Add support for segment timescales.

  * Fix bug with non-switchable tracks on protected content.

  * Add "manifest.liveRefreshPeriod" configuration field to manually
    set how often Smooth manifest should be updated.

* Chromecast improvements.

  * Prevent "INVALID_MEDIA_SESSION_ID" rejection when trying to
    play/pause/seek content in ended state.

  * Map "defaultBandwidthEstimate" field from "clpp.AbrConfiguration"
    to CAF's "cast.framework.PlaybackConfig.initialBandwidth".

  * Add "onResumeLocal" callback as an "clpp.cast.CastProxy"'s
    optional parameter.

* Resolve load promise when Never Auto-Play set to true on Safari
  13.1.x

* FreeWheel integration (BETA).

  * PRESTOplay SDK now comes with FreeWheel ads integration. To check
    it, please add FreeWheel SDK and our FreeWheel plugin to your
    project.

* Add "clpp.AbrConfiguration#useSwitchIntervalForInitialSwitch" flag
  to prevent quick ABR switch once the estimator has enough data.

* Add "clpp.Player#resetAbr()" method for resetting ABR estimate.

* Youbora integration.

  * Always fire "/pause" event to Youbora before reporting postroll.

* Expose text displayer interface.

  * Text displayer is now in BETA state with some known issues.

* Improved multi-key handling and added support for multi-key
  deliveries for Playready


6.0.4
=====

* Added "preferredDrmSystem" option to the "clpp.DrmConfiguration" to
  enforce using specific DRM technology (i.e. force PlayReady on Edge
  Chromium).

* Introduces "TimelineCue" data structure and related events.

* Fixes for handling muxed audio+video TS-based content.

* Added "clpp.events.USER_SEEKING" & "clpp.events.USER_SEEKED" events

  * Those events are fired only during seeking initiated by calling
    "clpp.Player#seek()" method.

* Fix Conviva integration error.


6.0.3
=====

* Support for Chromecast

  * Check manual and documentation for more info

* Support for persistent licenses

* Adds "originalId" field to the "clpp.Rendition" class

  * This field contains rendition id that appeared in original
    manifest


6.0.2
=====

* Improves HLS + AES-128 support

  * Relative AES key URI

* Adds DRMtoday Onboard support

* Adds AirPlay support

* Bug fixes and improvements


6.0.1
=====

* Adds Broadpeak's SmartLib v3-3.0.4-2950 integration (plugin).

* Introduces the crypto component ("clpp.crypto.CryptoComponent")

  * The crypto component adds HLS + AES-128 playback capability to the
    player.

* Improves support of muxed audio+video TS-based contents.


6.0.0
=====

PRESTOplay SDK for browsers version 6 has been re-designed from the
ground up to build a faster, more modular, and smaller player SDK. We
focused on the core components of video playback and the underlying
media playback engine.

Since the new architecture was only possible with drastic measures, we
needed to adapt and change the previous API. Please, consult the
migration guide from our manual to upgrade from version 5.


## web/chromecast-messaging

Messaging
*********

Bidirectional custom messaging between sender and receiver. Messages
must be plain, serializable objects.

The message must be a plain object that can be serialized.


Messages from sender to receiver
================================

On the sender side, use "CastProxy.sendMessage" to send custom
messages to the receiver:

   // Sender app
   proxy.sendMessage({
     type: 'ping',
     value: '4',
   });

Listen for these messages on the receiver side with
"Receiver.addMessageListener":

   // Receiver app
   const receiver = clpp.cast.Receiver.getInstance();
   receiver.addMessageListener((message) => {
     if (message.type === 'ping') {
       // ...
     }
   });


Messages from receiver to sender
================================

On the receiver side, use "Receiver.sendMessage" to broadcast custom
messages to all connected senders:

   // Receiver app
   const receiver = clpp.cast.Receiver.getInstance();
   receiver.sendMessage({
     type: 'ping',
     text: 'pong',
   });

Pass a "senderId" to message one specific sender instead:

   // Receiver app
   const receiver = clpp.cast.Receiver.getInstance();
   receiver.sendMessage({
     type: 'response',
     data: 'some data',
   }, senderId);

Listen for messages on the sender side with
"CastProxy.addMessageListener":

   // Sender app
   proxy.addMessageListener((message) => {
     if (message.type === 'ping') {
       // ...
     }
   });


Message namespace
=================

Messages are sent over the Google Cast protocol under the namespace
"urn:x-cast:castlabs".


## web/chromecast-playlist

Cast playlist
*************

"CastPlaylist" — higher-level playlist API over the Cast queue, usable
from sender or receiver.


Initialization
==============

   const player = new clpp.Player('video');
   const castPlaylist = new clpp.cast.playlist.CastPlaylist(
     player,
     CHROMECAST_APP_ID,
     [
       { configuration: { source: '...' }, skippable: false },
       { configuration: { source: '...' }, skippable: true },
     ],
   );

The SDK forbids skipping non-skippable items in the playlist. If you
use the "skippable" property, reflect it in your sender UI.


Usage
=====

Use "CastPlaylist" methods to read the current and full playlist
state, and subscribe to change notifications:

   castPlaylist.onPlaylistItemChange(updateUI);
   castPlaylist.onPlaylistModified(updateUI);
   castPlaylist.onCastStatusChanged(updateUI);

   function updateUI() {
     const playlistItems = castPlaylist.getPlaylistItems();
     const currentIndex = castPlaylist.getCurrentIndex();
     playlistItems.forEach((item, index) => { ... });
   }


Playing
=======

Prepare the playlist:

   castPlaylist.start();

Start playback:

   castPlaylist.play();


Destroying and reusing the player
=================================

Destroy the "CastPlaylist" instance and reuse the player for a new
casting session with the "CastProxy" API:

   let castProxy = null;
   async function startNewCastProxy() {
     // Stop casting first, if active
     if (castPlaylist.isCasting()) {
       castPlaylist.toggleCast();
     }
     castPlaylist.destroy();

     // Create a new CastProxy, load, and play
     castProxy = new clpp.cast.CastProxy(player, CHROMECAST_APP_ID);
     await player.open({
       source: '...',
       type: 'application/dash+xml',
     });
     player.play();
   }


## web/chromecast-queuing

Queuing
*******

PRESTOplay exposes queue APIs on both the receiver and sender, so you
can implement custom playlist behavior based on Google Cast queuing.


Receiver queue initialization
=============================

PRESTOplay implements a basic "Queue". Initialize the queue on the
receiver side by calling "Receiver.setQueue" before
"receiver.start()", so the Cast Application Framework (CAF) has the
queue registered before it accepts sender sessions:

   const player = new clpp.Player('video');
   const receiver = clpp.cast.Receiver.getInstance();
   const queue = clpp.cast.createCastQueue();

   receiver.init(player);
   receiver.setQueue(queue);
   receiver.start();


Custom queue
============

Use "cast.createCastQueue" or extend "cast.framework.QueueBase" for
custom queue lifecycle behavior. Refer to the CAF custom queue docs
for implementation reference.

   class CustomQueue extends cast.framework.QueueBase {
     // ...
   }

   const player = new clpp.Player('video');
   const receiver = clpp.cast.Receiver.getInstance();
   const queue = new CustomQueue();

   receiver.init(player);
   receiver.setQueue(queue);
   receiver.start();


Receiver queue management
=========================

Once the queue is registered, call
"clpp.cast.Receiver.getInstance().getQueueManager()" to get the CAF
queue manager and use its APIs.


Sender integrations
===================


Web SDK sender
--------------

"CastProxy" can forward queue commands to the receiver:

* "CastProxy.queueAddItems" appends new items to the end of the queue.

   castProxy.queueAddItems([
     {
       media: {
         contentId: 'https://demo.cf.castlabs.com/media/prestodash/Manifest.mpd',
         contentType: 'application/dash+xml',
       },
     },
     {
       media: {
         contentId: 'https://demo.cf.castlabs.com/media/TOS/abr/Manifest_clean_sizes.mpd',
         contentType: 'application/dash+xml',
       },
     },
   ]);

* "CastProxy.queueNextItem" and "CastProxy.queuePreviousItem" navigate
  forward and backward through the queue.

Basic queue usage:

   const player = new clpp.Player('video', ...);
   const proxy = new clpp.cast.CastProxy(player, '<your_receiver_app_id>');

   player.open({
     source: 'https://demo.cf.castlabs.com/media/prestodash/Manifest.mpd',
     type: 'application/dash+xml',
     drmProtected: false,
   });

   // Add queue items right after the casting session starts
   player.on(clpp.events.CAST_STATUS_CHANGED, () => {
     if (proxy.isCasting()) {
       proxy.queueAddItems([
         {
           media: {
             contentId: 'https://demo.cf.castlabs.com/media/prestodash/Manifest.mpd',
             contentType: 'application/dash+xml',
           },
         },
         {
           media: {
             contentId: 'https://demo.cf.castlabs.com/media/TOS/abr/Manifest_clean_sizes.mpd',
             contentType: 'application/dash+xml',
           },
         },
       ]);
     }
   });


Generic senders via custom messages
-----------------------------------

Any sender can interact with the custom queue through CAF messages:

   const session = cast.framework.CastContext.getInstance().getCurrentSession();
   session.sendMessage('urn:x-cast:com.google.cast.media', {
     type: 'QUEUE_INSERT',
     requestId,
     mediaSessionId: session.getMediaSession().mediaSessionId,
     items: [
       {
         media: {
           contentId: 'https://demo.cf.castlabs.com/media/TOS/abr/Manifest_clean_sizes.mpd',
           contentType: 'application/dash+xml',
         },
       },
     ],
   });


## web/chromecast-receiver

Receiver app
************

Receiver component built on the Google Web Receiver SDK. Same
supported media formats as that SDK. Covers a custom web receiver app.

Load the Google Web Receiver SDK:

   <script src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>

Load the PRESTOplay SDK and its Cast component:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.cast";

Render the "cast-media-player" tag, a built-in media player provided
by the Google Cast framework with basic UI controls that you can
customize:

   <cast-media-player id="castPlayer"></cast-media-player>

Create a "Player" instance, pass it to the "Receiver", and start the
receiver. The receiver listens for commands from the sender and uses
the player to play the stream:

   const player = new clpp.Player('castPlayer', {
     license: 'your-license-key',
   });
   const receiver = clpp.cast.Receiver.getInstance();
   receiver.init(player);
   receiver.start();

Full example:

   <script src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
   <cast-media-player id="castPlayer"></cast-media-player>
   <script type="module">
     import { clpp } from "@castlabs/prestoplay";
     import "@castlabs/prestoplay/cl.cast";

     const player = new clpp.Player('castPlayer', {
       license: 'your-license-key',
     });

     const receiver = clpp.cast.Receiver.getInstance();
     receiver.init(player);
     receiver.start();

     // Handle app going to background
     document.addEventListener('visibilitychange', () => {
       if (document.hidden) {
         console.info('Receiver app went to background, shut it down.');
         receiver.stop();
       }
     });
   </script>


Running in background
=====================

On Google TV Streamer, pressing the remote's Back or Home button sends
the receiver app to the background. Shut it down at that point:

   // Receiver app
   document.addEventListener('visibilitychange', () => {
     if (document.hidden) {
       console.info('Receiver app went to background, shut it down.');
       receiver.stop();
     }
   });

Alternatively, listen for "clpp.events.CAST_VISIBILITY_CHANGED" on the
sender and implement your own behavior:

   // Sender app
   player.on(clpp.events.CAST_VISIBILITY_CHANGED, (e) => {
     if (e.visible) {
       // Receiver app is in the foreground
     } else {
       // Receiver app is in the background
     }
   });

Bring the receiver app from background to foreground by calling
"Player.play" or "Player.open".


Tracks
======

The receiver adds extra properties to the "Track" object via the
"customData" field on the "MEDIA_STATUS" message:

* For audio tracks: "audioTrackInfo" — channels, codec, and spatial
  audio information.

* For audio and text tracks: "roles" — an array of strings
  representing the track's roles, or "undefined".


Limitations of the receiver
===========================

The Chromecast Receiver SDK has limitations that keep some "Player"
APIs from working in a receiver app.


Volume control
--------------

Volume control APIs aren't available on the receiver:
"Player.setVolume", "Player.getVolume", "Player.setMuted",
"Player.isMuted", and the "mute" and "volume" configuration options
have no effect. Control volume from the sender instead by calling the
same APIs there.


Track management
----------------

Video tracks and renditions can't be listed or switched on the
receiver. These "TrackManager" APIs are no-ops:

   const tm = player.getTrackManager();
   tm.getVideoTracks(); // empty array
   tm.getVideoRendition(); // null
   tm.getVideoTrack(); // null
   tm.setVideoTrack(track); // does nothing

Audio track and subtitle management work as expected.


## web/chromecast-sender

Sender
******

Sender component built on the Google Web Sender SDK. Compatible with
PRESTOplay receiver apps; can also pair with other Web Receiver
SDK-based receivers with reduced feature support.

Load the PRESTOplay SDK and its Cast component:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.cast";

Load the Google Web Sender SDK:

   <script src="//www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

Use the "clpp.cast.onReady" callback to wait until the Cast component
and the underlying Google Web Sender SDK are ready, then use
"CastProxy" to implement casting:

   const player = new clpp.Player(...);

   clpp.cast.onReady(() => {
     const proxy = new clpp.cast.CastProxy(player, '<your_receiver_app_id>');
   });

Check whether casting is available by calling "CastProxy.canCast" and
listen for "clpp.events.CAST_STATUS_CHANGED" for changes:

   let canCast = proxy.canCast();
   player.on(clpp.events.CAST_STATUS_CHANGED, () => {
     canCast = proxy.canCast();
   });

Casting requires a Chromecast target device on the same Wi-Fi network,
a correct receiver app ID, and a published receiver app.

Basic example:

   <script src="//www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
   <video id="video"></video>
   <button id="castButton" disabled>Cast</button>
   <script type="module">
     import { clpp } from "@castlabs/prestoplay";
     import "@castlabs/prestoplay/cl.cast";

     const player = new clpp.Player('video', {
       license: 'your-license-key',
     });

     // Load and play content
     player.open({
       source: 'https://demo.cf.castlabs.com/media/prestodash/Manifest.mpd',
       muted: true,
       autoplay: true,
     });

     clpp.cast.onReady(() => {
       const proxy = new clpp.cast.CastProxy(player, '<your_receiver_app_id>');

       const castButton = document.getElementById('castButton');

       // Update button state based on cast availability
       castButton.disabled = !proxy.canCast();
       player.on(clpp.events.CAST_STATUS_CHANGED, () => {
         castButton.disabled = !proxy.canCast();
         castButton.textContent = proxy.isCasting() ? 'Stop Casting' : 'Cast';
       });

       castButton.addEventListener('click', () => {
         if (proxy.isCasting()) {
           // Stop casting
           proxy.forceDisconnect();
         } else {
           // Start casting
           proxy.cast();
         }
       });
     });
   </script>

During casting, control remote playback on the receiver app from the
sender by calling "Player" methods — the sender acts as a remote
control for the receiver.


Events
======

"Player" fires these Chromecast-related events:

* "clpp.events.CASTING_STARTED" — casting has started.

* "clpp.events.CASTING_ENDED" — casting has ended.

* "clpp.events.CAST_STATUS_CHANGED" — any cast status change (session
  started or ended, Cast API availability, receiver connection, and so
  on).


Limitations of the sender
=========================

The Chromecast Sender SDK has limitations that keep some "Player" APIs
from working while casting.


Track management
----------------

As on the receiver, video tracks and renditions can't be listed or
switched while casting. These "TrackManager" APIs aren't usable:

   const tm = player.getTrackManager();
   tm.getVideoTracks(); // empty array (DASH) or array containing only one item (HLS)
   tm.getVideoRendition(); // null (DASH) or active rendition (HLS)
   tm.getVideoTrack(); // null (DASH) or active track (HLS)
   tm.setVideoTrack(track); // does nothing

Audio track and subtitle management work as expected.


Rendering UI
============

To render a play/pause button during a casting session, listen for the
state change event, since that's when "Player.isPaused" changes.
Standard video "play" and "pause" events aren't available here because
playback happens in the receiver app:

   player.on(clpp.events.STATE_CHANGED, function () {
     renderPlayButton();
   });


## web/chromecast

Chromecast
**********

Chromecast integration for PRESTOplay web SDK, built on the Google
Cast SDK. Covers building a receiver app, enabling casting from a
sender app, both using the "cl.cast.js" component and "Player".

The sender can be Chrome, a Chromium-based browser, or other
compatible software. The receiver can be a smart TV, a speaker, a
Chromecast device, a Google TV Streamer, or another compatible device.

* Receiver app

* Sender

* Messaging

* Queuing

* Cast playlist


## web/common-media-data

Common media data
*****************

PRESTOplay Web SDK Common Media Data configuration: CMCD (CTA-5004)
request-side metadata.

Review Common media data first for the shared CMCD and CMSD
definitions and specifications.


CMCD configuration
==================

Enable CMCD by setting "cmcd.enabled" to "true" in
"CmcdConfiguration".

Simple configuration:

   player.open({
     source: '...',
     cmcd: {
       enabled: true,
       deliveryMode: 'headers', // or 'query'
       contentId: 'abcd1234',
     }
   });

* **Delivery mode** defines how the data is sent: "headers" sends it
  via HTTP headers, "query" sends it via URL query parameters.

* **Content ID** is a unique string identifying the current content,
  up to 64 characters. It stays consistent across sessions and
  devices, and is defined and updated at the discretion of the service
  provider.

Advanced configuration:

   player.open({
     source: '...',
     cmcd: {
       enabled: true,
       deliveryMode: 'headers',
       contentId: 'abcd1234',
       sessionId: 'abcdefgh-1234-abcd-1234-abcdefghijkl',
       rtpMultiplier: 5
     }
   });

* **Session ID** is a GUID identifying the current playback session.
  If omitted, an internal clpp session ID is used.

* **RTP multiplier** scales the requested throughput ("rtp") field. It
  helps prevent buffer saturation from over-delivery and supports
  fair-share delivery, so each client receives the throughput it needs
  and no more. The default is 5 — a segment encoded at 2 Mbps is
  delivered at no more than 10 Mbps.


## web/components

Components
**********

PRESTOplay web SDK component reference. Import only the components you
need.

Each component module registers itself when imported. See Getting
started for a minimal example.


Common components
=================

+-----------------------------------+--------------------------------------+-----------------------------------+
| Component                         | Import                               | Use                               |
|===================================|======================================|===================================|
| MSE                               | "@castlabs/prestoplay/cl.mse"        | Media Source Extensions (MSE)     |
|                                   |                                      | based playback. Required by DASH, |
|                                   |                                      | MSE-based HLS, Smooth Streaming,  |
|                                   |                                      | and several text workflows.       |
+-----------------------------------+--------------------------------------+-----------------------------------+
| DASH                              | "@castlabs/prestoplay/cl.dash"       | MPEG-DASH playback.               |
+-----------------------------------+--------------------------------------+-----------------------------------+
| HLS                               | "@castlabs/prestoplay/cl.hls"        | HTTP Live Streaming (HLS)         |
|                                   |                                      | playback. Use with "cl.mse" for   |
|                                   |                                      | MSE-based HLS.                    |
+-----------------------------------+--------------------------------------+-----------------------------------+
| Smooth Streaming                  | "@castlabs/prestoplay/cl.smooth"     | Smooth Streaming playback.        |
+-----------------------------------+--------------------------------------+-----------------------------------+
| VTT                               | "@castlabs/prestoplay/cl.vtt"        | WebVTT and SRT subtitles.         |
+-----------------------------------+--------------------------------------+-----------------------------------+
| TTML                              | "@castlabs/prestoplay/cl.ttml"       | TTML, SMPTE-TT, and IMSC1         |
|                                   |                                      | subtitles.                        |
+-----------------------------------+--------------------------------------+-----------------------------------+
| HTML Cue                          | "@castlabs/prestoplay/cl.htmlcue"    | HTML subtitle rendering.          |
+-----------------------------------+--------------------------------------+-----------------------------------+
| Crypto                            | "@castlabs/prestoplay/cl.crypto"     | AES-128 HLS decryption outside    |
|                                   |                                      | native Safari playback.           |
+-----------------------------------+--------------------------------------+-----------------------------------+
| Persistent licenses               | "@castlabs/prestoplay/cl.persistent" | Persistent DRM licenses.          |
+-----------------------------------+--------------------------------------+-----------------------------------+
| Cast                              | "@castlabs/prestoplay/cl.cast"       | Chromecast sender and receiver    |
|                                   |                                      | support.                          |
+-----------------------------------+--------------------------------------+-----------------------------------+
| Tizen                             | "@castlabs/prestoplay/cl.tizen"      | Native AVPlay playback on older   |
|                                   |                                      | Tizen TVs.                        |
+-----------------------------------+--------------------------------------+-----------------------------------+

Plugin and integration components are documented with their features.
See Advertising, Analytics, AirPlay, and Playlist.


DASH
====

Use "cl.mse" and "cl.dash" for DASH playback:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.dash";

   const player = new clpp.Player(...);

   player.open({
     source: 'https://provider.com/content/manifest.mpd',
     type: clpp.Type.DASH,
   });


HLS through MSE
===============

MSE-based HLS: "cl.mse" + "cl.hls". MPEG transport stream (MPEG-TS)
support requires "mux.js" on "window.muxjs".

   npm install mux.js@6.3.0

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.hls";
   import * as muxjs from "mux.js";
   window.muxjs = muxjs;

   const player = new clpp.Player(...);

   player.open({
     source: 'https://provider.com/content/master.m3u8',
     type: clpp.Type.HLS,
   });

Safari uses native HLS playback by default. See Safari for details.


Smooth Streaming
================

Use "cl.mse" and "cl.smooth" for Smooth Streaming playback:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.smooth";

   const player = new clpp.Player(...);

   player.open({
     source: 'https://provider.com/content/Manifest',
     type: clpp.Type.SMOOTH_STREAMING,
   });


AES-128 HLS
===========

AES-128 HLS decryption outside native Safari: add "cl.crypto".

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.hls";
   import "@castlabs/prestoplay/cl.crypto";

   const player = new clpp.Player(...);

   player.open({
     source: 'https://provider.com/content/master_aes_128.m3u8',
     type: clpp.Type.HLS,
   });


## web/drm-modifiers

Customizing license requests
****************************

Modifiers are callbacks on a DRM system in a custom DRM environment.
They adapt license and certificate requests/responses and init data to
a license server's requirements: dynamic auth tokens, custom payloads,
wrapped responses, custom FairPlay content IDs.


Do you need modifiers?
======================

Check whether a built-in DRM environment already covers your license
server:

* With DRMtoday, the DRMtoday environment handles authentication,
  request format, and FairPlay content IDs for you.

* If your license server only needs fixed headers, such as an API key,
  use the header-based DRM environment and pass them in
  "customData.headers".

Use modifiers when your license server needs more than that, for
example:

+----------------------------------------------------+----------------------------------------------------+
| Your license server...                             | Use                                                |
|====================================================|====================================================|
| needs a token that you fetch or refresh at request | "licenseRequest"                                   |
| time                                               |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| expects the license challenge in a custom request  | "licenseRequest"                                   |
| body                                               |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| returns the license wrapped in JSON or another     | "licenseResponse"                                  |
| format                                             |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| needs headers on the FairPlay certificate request  | "certificateRequest"                               |
+----------------------------------------------------+----------------------------------------------------+
| expects a different FairPlay content ID than the   | "extractContentId"                                 |
| default                                            |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| needs a custom FairPlay key request payload        | "transformInitData"                                |
+----------------------------------------------------+----------------------------------------------------+


How modifiers work
==================

Modifiers belong to a DRM system in a custom DRM environment. Pass
them in the "modifiers" object of "drm.DrmEnvironment#setDrmSystem":

   const environment = new clpp.drm.DrmEnvironment('myDrm');
   environment.setDrmSystem(clpp.drm.KeySystem.WIDEVINE, {
     licenseUrl: 'https://license.example.com/widevine',
     modifiers: {
       licenseRequest: (config, request, sessionContext) => { /* ... */ },
       licenseResponse: (config, response, sessionContext) => { /* ... */ },
     },
   });
   clpp.drm.registerDrmEnvironment(environment);

Each DRM system takes its own set of modifiers, so you can handle
Widevine, PlayReady, and FairPlay differently. The available modifiers
are defined in "drm.LicenseModifiers":

+-----------------------------------+-----------------------------------+-----------------------------------+
| Modifier                          | Runs                              | Receives                          |
|===================================|===================================|===================================|
| "licenseRequest"                  | Before a license request is sent. | "net.Request"                     |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "licenseResponse"                 | After a license response arrives, | "net.Response"                    |
|                                   | before the CDM gets the license.  |                                   |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "certificateRequest"              | Before a certificate request is   | "net.Request"                     |
|                                   | sent.                             |                                   |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "certificateResponse"             | After a certificate response      | "net.Response"                    |
|                                   | arrives.                          |                                   |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "extractContentId"                | When the player extracts the      | Init data                         |
|                                   | FairPlay content ID from init     |                                   |
|                                   | data.                             |                                   |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "transformInitData"               | Before init data is passed to the | "InitDataTransformerParams"       |
|                                   | CDM.                              |                                   |
+-----------------------------------+-----------------------------------+-----------------------------------+

Request and response modifiers change the request or response in
place, for example "request.headers" or "response.data". They can also
return a promise, and the player waits for it before it continues. To
pass data between modifiers of the same media session, store it in
"sessionContext.customData". See "SessionContext".


Add authentication to license requests
======================================

If your license server needs a short-lived token, fetch it in the
"licenseRequest" modifier and add it as a header. Because the modifier
returns a promise, the license request waits until the token is
available:

   environment.setDrmSystem(clpp.drm.KeySystem.WIDEVINE, {
     licenseUrl: 'https://license.example.com/widevine',
     modifiers: {
       licenseRequest: async (config, request) => {
         // Your own backend call that returns a fresh token.
         const token = await fetchLicenseToken();
         request.headers['Authorization'] = `Bearer ${token}`;
       },
     },
   });


Send a custom request and unwrap the response
=============================================

Some license servers don't accept the raw license challenge from the
CDM. For example, a server might expect the challenge as Base64 in a
JSON body and return the license as Base64 in a JSON response. Use
"licenseRequest" to build the body and "licenseResponse" to extract
the license:

   const { toStandardBase64, fromBase64 } = clpp.utils.Uint8ArrayUtils;
   const { toUtf8, fromUtf8 } = clpp.utils.strings;

   environment.setDrmSystem(clpp.drm.KeySystem.WIDEVINE, {
     licenseUrl: 'https://license.example.com/widevine',
     modifiers: {
       licenseRequest: (config, request) => {
         const body = {
           challenge: toStandardBase64(new Uint8Array(request.body)),
           contentId: 'my-content-id',
         };
         request.headers['Content-Type'] = 'application/json';
         request.body = toUtf8(JSON.stringify(body)).buffer;
       },
       licenseResponse: (config, response) => {
         const { license } = JSON.parse(fromUtf8(response.data));
         response.data = fromBase64(license).buffer;
       },
     },
   });


Use a custom FairPlay content ID
================================

For FairPlay, the player extracts a content ID from the init data and
sends it to the license server. By default, it uses the hostname part
of the HLS "#EXT-X-KEY" URI. For this tag, the content ID is
"d192ebad-5097":

   #EXT-X-KEY:METHOD=SAMPLE-AES,URI="skd://d192ebad-5097",
   KEYFORMAT="com.apple.streamingkeydelivery",KEYFORMATVERSIONS="1"

If your FairPlay Streaming (FPS) license server expects a different
value, return it from "extractContentId". This example sends only
"d192ebad":

   environment.setDrmSystem(clpp.drm.KeySystem.FAIRPLAY, {
     licenseUrl: 'https://license.example.com/fairplay',
     certificateUrl: 'https://license.example.com/fairplay.cer',
     modifiers: {
       extractContentId: (config, initData) => {
         const { extractContentId } = clpp.utils.FairplayUtils;
         const fullHostname = extractContentId(initData); // d192ebad-5097
         return fullHostname.split('-')[0]; // d192ebad
       },
     },
   });

See "drm.ContentIdExtractor".


Build a custom FairPlay key request
===================================

If changing the content ID isn't enough, "transformInitData" gives you
full control over the payload the CDM uses to generate a key request.
Use it when your license server needs a content ID from an external
source, such as your own API, or a payload format of its own.

The following example builds the FairPlay payload with a content ID
from your own video configuration. It stores the key ID in
"sessionContext.customData", so the "licenseRequest" and
"licenseResponse" modifiers can use it to talk to a license server
with a JSON API:

   // Your own data, e.g. fetched from your backend.
   const videoConfig = {
     pid: 'isdl83hfja',
     authHeaders: {
       Authorization: 'Basic aHR0cDovL2FjY2V...',
     },
   };

   const environment = new clpp.drm.DrmEnvironment('myDrmEnv');
   environment.setDrmSystem(clpp.drm.KeySystem.FAIRPLAY, {
     licenseUrl: 'https://license.example.com/fairplay',
     certificateUrl: 'https://license.example.com/fairplay.cer',
     modifiers: {
       transformInitData: ({
         initData,
         initDataType,
         drmInfo: { serverCertificate },
         sessionContext: { customData },
         emeApi,
       }) => {
         if (initDataType === 'skd' &&
             emeApi === clpp.drm.eme.EmeFactory.Apis.APPLE) {
           const { extractContentId, createFairplayPayload } =
             clpp.utils.FairplayUtils;

           customData.keyId = extractContentId(initData);
           initData = createFairplayPayload(
             initData,
             videoConfig.pid,
             serverCertificate,
           );
         }
         return initData;
       },

       licenseRequest: (config, request, { customData }) => {
         const { toUint8Array } = clpp.utils.BufferUtils;
         const { toStandardBase64 } = clpp.utils.Uint8ArrayUtils;
         const { toUtf8 } = clpp.utils.strings;

         const requestBody = {
           getFairplayLicense: {
             spcMessage: toStandardBase64(toUint8Array(request.body)),
             releasePid: videoConfig.pid,
             keyId: customData.keyId,
           },
         };
         Object.assign(request.headers, videoConfig.authHeaders);
         request.body = toUtf8(JSON.stringify(requestBody)).buffer;
       },

       licenseResponse: (config, response, { customData }) => {
         const { fromUtf8 } = clpp.utils.strings;
         const { fromBase64 } = clpp.utils.Uint8ArrayUtils;

         let licenseResponse;
         try {
           licenseResponse = JSON.parse(fromUtf8(response.data));
         } catch (e) {
           throw new Error(
             `Can't parse the license response for key ID ${customData.keyId}: ${e}`,
           );
         }

         const { ckcResponse } = licenseResponse.getFairplayLicenseResponse;
         response.data = fromBase64(ckcResponse).buffer;
       },
     },
   });
   clpp.drm.registerDrmEnvironment(environment);

The utilities in "utils.FairplayUtils", "utils.strings", and
"utils.BufferUtils" help with this processing. See
"drm.InitDataTransformer" and the EME initialization data spec.


Modifiers on Chromecast receivers
=================================

In the Chromecast receiver context, the license modifiers have limited
functionality, based on the data the Cast Application Framework (CAF)
SDK provides:

* Request modifiers don't have access to most of the request data,
  such as "licenseRequestType".

* Response modifiers have access only to the license data and headers,
  not the associated request.

* "licenseResponse" can be asynchronous, but "licenseRequest" must be
  synchronous.

See the CAF SDK reference for licenseRequestHandler, licenseHandler,
NetworkRequestInfo, and NetworkResponseInfo.


## web/drm

DRM
***

DRM configuration reference for PRESTOplay web SDK. Covers built-in
DRM environments (DRMtoday, DRMtoday Onboard, header-based, Verimatrix
VCAS Ultra), custom DRM environments, CDM configuration, and the
Encrypted Media Extensions (EME) API. License modifiers: see
drm-modifiers.

Note:

  Your website must be served over HTTPS to play DRM-protected
  content. HTTPS is not required when testing on "localhost".

See also Persistent DRM licenses for offline playback of DRM-protected
content.


DRM with DRMtoday
=================

The SDK includes a preconfigured DRMtoday environment. To use it, pass
DRM configuration under the "drm" key in the "Player.open" call. Set
the environment name to "DRMtoday". A "DRMtoday_STAGING" environment
is also available for testing.

   player.open({
     source: 'https://example.com/Manifest.mpd',
     drm: {
       env: 'DRMtoday',
       customData: {
         userId: 'purchase',
         sessionId: 'p0',
         merchant: 'six',
       }
     }
   });

Specific properties of the DRMtoday environment, set under
"drm.customData":

+-----------------------------------------+-----------------------------------+--------------------------------------+
| Property                                | Required                          | Description                          |
|=========================================|===================================|======================================|
| "userId"                                | Yes                               | The "userId" parameter sent to       |
|                                         |                                   | DRMtoday.                            |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "sessionId"                             | Yes                               | The "sessionId" parameter sent to    |
|                                         |                                   | DRMtoday.                            |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "merchant"                              | Yes                               | The merchant parameter.              |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "authToken"                             | No                                | The DRMtoday authentication token    |
|                                         |                                   | used for the license request when    |
|                                         |                                   | upfront authentication is used.      |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "assetId"                               | No                                | The asset ID of the content the      |
|                                         |                                   | license is requested for. Not        |
|                                         |                                   | required in all setups, but          |
|                                         |                                   | useful in some.                      |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "variantId"                             | No                                | The variant ID of the content the    |
|                                         |                                   | license is requested for. Not        |
|                                         |                                   | required in all setups, but          |
|                                         |                                   | useful in some.                      |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "widevineVideoRobustness"               | No                                | Widevine video robustness levels.    |
|                                         |                                   | Default: "[HW_SECURE_ALL,            |
|                                         |                                   | HW_SECURE_DECODE,                    |
|                                         |                                   | HW_SECURE_CRYPTO,                    |
|                                         |                                   | SW_SECURE_DECODE,                    |
|                                         |                                   | SW_SECURE_CRYPTO]". See              |
|                                         |                                   | "drm.WidevineRobustnessLevel".       |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "widevineAudioRobustness"               | No                                | Widevine audio robustness levels.    |
|                                         |                                   | Default: "[SW_SECURE_DECODE,         |
|                                         |                                   | SW_SECURE_CRYPTO]". See              |
|                                         |                                   | "drm.WidevineRobustnessLevel".       |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "widevineDistinctiveIdentifierRequired" | No                                | Whether a persistent distinctive     |
|                                         |                                   | identifier is required. Default:     |
|                                         |                                   | "false".                             |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "widevinePersistentStateRequired"       | No                                | Whether the ability to persist       |
|                                         |                                   | state is required. Default:          |
|                                         |                                   | "false".                             |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "playReadyVideoRobustness"              | No                                | PlayReady video robustness           |
|                                         |                                   | levels. Default: "[3000, 2000,       |
|                                         |                                   | 150]". See                           |
|                                         |                                   | "drm.PlayreadyRobustnessLevel".      |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "playReadyAudioRobustness"              | No                                | PlayReady audio robustness           |
|                                         |                                   | levels. Default: "[2000, 150]".      |
|                                         |                                   | See                                  |
|                                         |                                   | "drm.PlayreadyRobustnessLevel".      |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "serverCertificate"                     | No                                | The Widevine server certificate.     |
|                                         |                                   | DRMtoday selects the right           |
|                                         |                                   | certificate by default; use this     |
|                                         |                                   | to select one explicitly. See        |
|                                         |                                   | "drm.DrmToday.WidevineCertificates". |
+-----------------------------------------+-----------------------------------+--------------------------------------+


DRM with DRMtoday Onboard
=========================

OnBoard is the offline architecture for DRMtoday. It lets you install
a DRMtoday server on a private network — for example, on board a bus,
plane, train, or ship.

Enable OnBoard by defining an environment name and the URL of your
local DRMtoday OnBoard server. The SDK registers a new environment
automatically using the specified name and URL. We suggest the name
"DRMtodayOnBoard" to avoid a collision with other predefined
environments. You can also pass other custom data, such as a user ID
or session ID.

Specific properties of the DRMtoday OnBoard environment, set under
"drm.customData":

+-----------------------------------------+-----------------------------------+--------------------------------------+
| Property                                | Required                          | Description                          |
|=========================================|===================================|======================================|
| "baseUrl"                               | Yes                               | The base URL of the DRMtoday         |
|                                         |                                   | Onboard server.                      |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "widevineUrl"                           | No                                | Appended to the base URL to form     |
|                                         |                                   | the Widevine URL. Default:           |
|                                         |                                   | "widevine".                          |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "playreadyUrl"                          | No                                | Appended to the base URL to form     |
|                                         |                                   | the PlayReady URL. Default:          |
|                                         |                                   | "playready".                         |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "fairplayUrl"                           | No                                | Appended to the base URL to form     |
|                                         |                                   | the FairPlay URL. Default:           |
|                                         |                                   | "fairplay".                          |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "widevineVideoRobustness"               | No                                | Widevine video robustness levels.    |
|                                         |                                   | Default: "[SW_SECURE_DECODE,         |
|                                         |                                   | undefined]". See                     |
|                                         |                                   | "drm.WidevineRobustnessLevel".       |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "widevineAudioRobustness"               | No                                | Widevine audio robustness levels.    |
|                                         |                                   | Default: "[SW_SECURE_CRYPTO,         |
|                                         |                                   | undefined]". See                     |
|                                         |                                   | "drm.WidevineRobustnessLevel".       |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "widevineDistinctiveIdentifierRequired" | No                                | Whether a persistent distinctive     |
|                                         |                                   | identifier is required. Default:     |
|                                         |                                   | "false".                             |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "widevinePersistentStateRequired"       | No                                | Whether the ability to persist       |
|                                         |                                   | state is required. Default:          |
|                                         |                                   | "false".                             |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "playReadyVideoRobustness"              | No                                | PlayReady video robustness           |
|                                         |                                   | levels. Default: "undefined". See    |
|                                         |                                   | "drm.PlayreadyRobustnessLevel".      |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "playReadyAudioRobustness"              | No                                | PlayReady audio robustness           |
|                                         |                                   | levels. Default: "undefined". See    |
|                                         |                                   | "drm.PlayreadyRobustnessLevel".      |
+-----------------------------------------+-----------------------------------+--------------------------------------+
| "serverCertificate"                     | No                                | The Widevine server certificate.     |
|                                         |                                   | If unset, the SDK uses its           |
|                                         |                                   | default certificate. Set to          |
|                                         |                                   | "null" to fetch the certificate      |
|                                         |                                   | from the Widevine server, a          |
|                                         |                                   | string to use                        |
|                                         |                                   | "drm.DrmToday.WidevineCertificates", |
|                                         |                                   | or a "Uint8Array" to use it          |
|                                         |                                   | directly as the certificate.         |
+-----------------------------------------+-----------------------------------+--------------------------------------+

Import the DRMtoday Onboard component:

   import "@castlabs/prestoplay/cl.onboard";

Minimal example:

   const player = new clpp.Player(...);

   player.open({
     source: 'https://example.com/Manifest.mpd',
     drm: {
       env: 'DRMtodayOnboard',
       customData: {
         baseUrl: 'offlineDRMTodayServerUrl',
       }
     }
   });

More complex example:

   const player = new clpp.Player(...);

   player.open({
     source: 'https://example.com/Manifest.mpd',
     drm: {
       env: 'DRMtodayOnboard',
       customData: {
         baseUrl: 'offlineDRMTodayServerUrl',
         widevineUrl: 'widevine',
         playreadyUrl: 'playready',
         fairplayUrl: 'fairplay',
         serverCertificate: null, // Forces fetching the certificate from the Widevine server
       }
     }
   });


DRM with header-based DRM environment
=====================================

Integrate a custom DRM service with the configurable header-based DRM
environment, available from the core module. Pass backend URLs and
custom request headers, such as the authentication header:

   player.open({
     drm: {
       env: 'HeaderDrm',
       customData: {
         widevineLicenseUrl: '...',
         widevineVideoRobustness: [
           clpp.drm.WidevineRobustnessLevel.SW_SECURE_DECODE,
           undefined
         ],
         widevineAudioRobustness: [
           clpp.drm.WidevineRobustnessLevel.SW_SECURE_CRYPTO,
           undefined
         ],
         playReadyLicenseUrl: '...',
         playReadyVideoRobustness: [
           clpp.drm.PlayreadyRobustnessLevel.SL3000
         ],
         playReadyAudioRobustness: [
           clpp.drm.PlayreadyRobustnessLevel.SL2000
         ],
         fairPlayLicenseUrl: '...',
         fairPlayCertificateUrl: '...',
         fairPlayContentIdStrategy:
           clpp.drm.HeaderDrm.ContentIdStrategy.FULL_SKD,
         serverCertificate: new Uint8Array(...),
         headers: {
           'my-auth-header': '...'
         }
       }
     }
   });

Specific properties of the header-based DRM environment, set under
"drm.customData":

+-----------------------------------------+-----------------------------------+-----------------------------------+
| Property                                | Required                          | Description                       |
|=========================================|===================================|===================================|
| "widevineLicenseUrl"                    | Yes                               | The Widevine license URL.         |
+-----------------------------------------+-----------------------------------+-----------------------------------+
| "playReadyLicenseUrl"                   | Yes                               | The PlayReady license URL.        |
+-----------------------------------------+-----------------------------------+-----------------------------------+
| "fairPlayLicenseUrl"                    | Yes                               | The FairPlay license URL.         |
+-----------------------------------------+-----------------------------------+-----------------------------------+
| "fairPlayCertificateUrl"                | Yes                               | The FairPlay certificate URL.     |
+-----------------------------------------+-----------------------------------+-----------------------------------+
| "fairPlayContentIdStrategy"             | No                                | The FairPlay content ID           |
|                                         |                                   | extraction strategy. Default:     |
|                                         |                                   | "FULL_SKD".                       |
+-----------------------------------------+-----------------------------------+-----------------------------------+
| "headers"                               | No                                | A dictionary of custom request    |
|                                         |                                   | headers.                          |
+-----------------------------------------+-----------------------------------+-----------------------------------+
| "widevineVideoRobustness"               | No                                | Widevine video robustness levels. |
|                                         |                                   | Default: "[SW_SECURE_DECODE,      |
|                                         |                                   | undefined]". See                  |
|                                         |                                   | "drm.WidevineRobustnessLevel".    |
+-----------------------------------------+-----------------------------------+-----------------------------------+
| "widevineAudioRobustness"               | No                                | Widevine audio robustness levels. |
|                                         |                                   | Default: "[SW_SECURE_CRYPTO,      |
|                                         |                                   | undefined]". See                  |
|                                         |                                   | "drm.WidevineRobustnessLevel".    |
+-----------------------------------------+-----------------------------------+-----------------------------------+
| "widevineDistinctiveIdentifierRequired" | No                                | Whether a persistent distinctive  |
|                                         |                                   | identifier is required. Default:  |
|                                         |                                   | "false".                          |
+-----------------------------------------+-----------------------------------+-----------------------------------+
| "widevinePersistentStateRequired"       | No                                | Whether the ability to persist    |
|                                         |                                   | state is required. Default:       |
|                                         |                                   | "false".                          |
+-----------------------------------------+-----------------------------------+-----------------------------------+
| "playReadyVideoRobustness"              | No                                | PlayReady video robustness        |
|                                         |                                   | levels. Default: "[SL3000]". See  |
|                                         |                                   | "drm.PlayreadyRobustnessLevel".   |
+-----------------------------------------+-----------------------------------+-----------------------------------+
| "playReadyAudioRobustness"              | No                                | PlayReady audio robustness        |
|                                         |                                   | levels. Default: "[SL2000]". See  |
|                                         |                                   | "drm.PlayreadyRobustnessLevel".   |
+-----------------------------------------+-----------------------------------+-----------------------------------+
| "serverCertificate"                     | No                                | No server certificate is selected |
|                                         |                                   | by default. Provide the Widevine  |
|                                         |                                   | server certificate ahead of time  |
|                                         |                                   | as a "Uint8Array".                |
+-----------------------------------------+-----------------------------------+-----------------------------------+


DRM with Verimatrix VCAS Ultra environment
==========================================

Import the component:

   import "@castlabs/prestoplay/cl.verimatrix";

Open the stream with configuration:

   const player = new clpp.Player(...);

   player.open({
     source: 'https://your.server/encrypted-asset.mpd',
     drm: {
       env: 'VerimatrixVCAS',
       customData: {
         deviceId: "myDeviceID",
         widevineLicenseUrl: 'https://widevine.keyserver:port/',
         playReadyLicenseUrl: 'https://playready.keyserver:port/',
         fairPlayLicenseUrl: 'https://fairplay.keyserver:port/',
         fairPlayCertificateUrl: 'https://fairplay.cert/fairplay.cer'
       }
     }
   });

Specific "VerimatrixVcasConfiguration" properties of the Verimatrix
VCAS Ultra DRM environment, set under "drm.customData":

+-----------------------------------+-----------------------------------+-----------------------------------------------+
| Property                          | Required                          | Description                                   |
|===================================|===================================|===============================================|
| "deviceId"                        | Yes                               | The device's Verimatrix unique                |
|                                   |                                   | identifier (VUID).                            |
+-----------------------------------+-----------------------------------+-----------------------------------------------+
| "authenticator"                   | No                                | Optional third-party                          |
|                                   |                                   | authentication to the Subscriber              |
|                                   |                                   | Management System (SMS).                      |
+-----------------------------------+-----------------------------------+-----------------------------------------------+
| "licenseRequestVuidLocation"      | No                                | Method for passing "deviceId" and             |
|                                   |                                   | "authenticator" (if defined) to               |
|                                   |                                   | the license server. Default:                  |
|                                   |                                   | "QUERY_STRING". See                           |
|                                   |                                   | "verimatrix.Vcas.LicenseRequestVuidLocation". |
+-----------------------------------+-----------------------------------+-----------------------------------------------+
| "httpHeaderNames"                 | No                                | Custom HTTP header names for                  |
|                                   |                                   | passing "deviceId" and                        |
|                                   |                                   | "authenticator" to the license                |
|                                   |                                   | server. Used only when                        |
|                                   |                                   | "licenseRequestVuidLocation" is               |
|                                   |                                   | "HTTP_HEADER". See                            |
|                                   |                                   | "verimatrix.Vcas.LicenseRequestHttpHeader".   |
+-----------------------------------+-----------------------------------+-----------------------------------------------+
| "widevineLicenseUrl"              | Yes                               | The Widevine license server URL.              |
+-----------------------------------+-----------------------------------+-----------------------------------------------+
| "playReadyLicenseUrl"             | Yes                               | The PlayReady license server URL.             |
+-----------------------------------+-----------------------------------+-----------------------------------------------+
| "fairPlayLicenseUrl"              | Yes                               | The FairPlay license server URL.              |
+-----------------------------------+-----------------------------------+-----------------------------------------------+
| "fairPlayCertificateUrl"          | Yes                               | The FairPlay certificate URL.                 |
+-----------------------------------+-----------------------------------+-----------------------------------------------+
| "fairPlayAssetIdStrategy"         | No                                | The FairPlay asset ID acquisition             |
|                                   |                                   | strategy. Default: "KEYID". See               |
|                                   |                                   | "verimatrix.Vcas.FairPlayAssetIdStrategy".    |
+-----------------------------------+-----------------------------------+-----------------------------------------------+
| "fairPlaySiteId"                  | No                                | The unique identifier of the site             |
|                                   |                                   | the subscriber is associated                  |
|                                   |                                   | with. Used only together with                 |
|                                   |                                   | "fairPlayAssetIdStrategy" set to              |
|                                   |                                   | "CONTENTID_SITEID".                           |
+-----------------------------------+-----------------------------------+-----------------------------------------------+

Use the demo player configuration form to generate and test a
configuration for Verimatrix VCAS Ultra DRM: select "Verimatrix VCAS
Ultra" as the DRM environment and fill in the form with your data.

For more details, see "VerimatrixVcasConfiguration" and
"verimatrix.Vcas".


DRM with custom DRM environment
===============================

Create a custom DRM environment when you need full control over the
license acquisition process.

Create a "drm.DrmEnvironment" instance, configure it for the DRM
systems you need, and register it globally with
"drm.registerDrmEnvironment". For the possible DRM system
configurations, see "drm.DrmEnvironment#setDrmSystem".

A custom DRM environment can look like this:

   const environment = new clpp.drm.DrmEnvironment('myDrm');
   environment.setDrmSystem(clpp.drm.KeySystem.WIDEVINE, {
     licenseUrl: '...',
   });
   environment.setDrmSystem(clpp.drm.KeySystem.FAIRPLAY, {...});
   environment.setDrmSystem(clpp.drm.KeySystem.PLAYREADY, {...});

   clpp.drm.registerDrmEnvironment(environment);

To use a custom DRM environment, pass its name in the "Player.open"
call:

   const player = new clpp.Player(...);
   player.open({
     source: 'https://example.com/Manifest.mpd',
     drm: {
       env: 'myDrm', // the custom DRM environment name
       customData: {
         // optional data the custom DRM environment might need
       }
     }
   });


CDM configuration
=================

Depending on the device and platform, a content decryption module
(CDM) might require specific configuration to work. The
"distinctiveIdentifierRequired" and "persistentStateRequired" flags
must be "true" on some platforms and "false" on others.

Use the CDM probe page to check which CDMs and CDM configurations your
browser supports.

With a custom DRM environment, configure these flags as follows:

   const environment = new clpp.drm.DrmEnvironment('myDrm');
   environment.setDrmSystem(clpp.drm.KeySystem.WIDEVINE, {
     licenseUrl: '...',
     distinctiveIdentifierRequired: true,
     persistentStateRequired: true,
   });

   clpp.drm.registerDrmEnvironment(environment);

You can also pass them as Widevine custom data:

   player.open({
     source: 'https://example.com/Manifest.mpd',
     drm: {
       env: 'DRMtoday',
       customData: {
         userId: 'purchase',
         widevineDistinctiveIdentifierRequired: true,
         widevinePersistentStateRequired: true,
       }
     }
   });


Customizing license requests
============================

If your license server needs more than a built-in DRM environment
offers, such as a token fetched at request time, a custom request
body, a wrapped license response, or a custom FairPlay content ID, add
modifiers to a custom DRM environment. See Customizing license
requests.


Multiple DRM environments
=========================

When using multiple DRM solutions, give each DRM environment a unique
name. Reusing a name can cause unspecified behavior, especially when
multiple player instances are active at the same time.


Encrypted Media Extensions API
==============================

PRESTOplay uses the Encrypted Media Extensions (EME) API to decrypt
content. Some platforms provide different versions or implementations
of this API, and the SDK automatically selects the most suitable one.

Override this selection with the "drm.emeApi" configuration option,
passing a value from "drm.eme.EmeFactory.Apis":

   const player = new clpp.Player('video', {
     drm: {
       emeApi: clpp.drm.eme.EmeFactory.Apis.APPLE,
     },
   });


DRM providers and FairPlay
--------------------------

To use FairPlay with the MSE player on Safari alongside the default
standard EME, your DRM provider must support it. DRMtoday provides
full support for this scenario out-of-the-box.

* Persistent DRM licenses

* Customizing license requests


## web/errors

Errors
******

Error handling reference for PRESTOplay web SDK. Covers the "Error"
object shape, event vs. promise-based error handling, common browser
playback errors (CORS, SSL, mixed content, connectivity), and network
retry error data.


The Error object
================

The player triggers an error event or rejects a promise when an error
occurs. If an API call returns a promise, the promise is rejected;
otherwise, an error event is triggered. Every error is an instance of
"Error".

Errors are grouped into categories. The "Error.category" property
holds one of the following values:

   clpp.Error.Category.NETWORK   // Errors from the network stack.
   clpp.Error.Category.TEXT      // Errors parsing text streams.
   clpp.Error.Category.MEDIA     // Errors parsing or processing audio or video streams.
   clpp.Error.Category.MANIFEST  // Errors parsing the manifest.
   clpp.Error.Category.STREAMING // Errors related to streaming.
   clpp.Error.Category.DRM       // Errors related to DRM.
   clpp.Error.Category.PLAYER    // Miscellaneous errors from the player.
   clpp.Error.Category.PLUGIN    // Errors thrown by plugins.
   clpp.Error.Category.ADS       // Errors related to ads.

An error might be recoverable. The "Error.severity" property holds one
of the following values:

   // The player will try to recover from this error. If retrying continues to
   // fail, the player might still issue a FATAL error. A failing download is a
   // good example: the first failure might be reported as RECOVERABLE, but if
   // the download keeps failing, the error turns into a FATAL one.
   clpp.Error.Severity.RECOVERABLE

   // A fatal error the player can't recover from. This usually stops playback
   // and loading — release the player before you try again.
   clpp.Error.Severity.FATAL

Use the unique "Error.code" property to identify an error. The full
list of error codes is available in the API documentation. Extra data,
such as an HTTP status code, is accessible through "Error.data".


Error codes
-----------

See "Error.Code" for the full list of error codes.

A newer set of error codes conforming to a draft of the SVTA spec is
also available under "Error.svtaCode". These codes are subject to
change until the SVTA spec is finalized.


Handling errors
===============


Error event
-----------

Important:

  Attach an error listener immediately after instantiating the player.
  It's safer and simpler than attaching it later.

   player.on(clpp.events.ERROR, event => {
     const error = event.detail;
     // ...
   });


Rejected promises
-----------------

Add a catch handler to an asynchronous method:

   const source = '//demo.cf.castlabs.com/media/prestodash/Manifest.mpd';
   player.open({ source }).catch(error => {
     // ...
   });

The same pattern works with other asynchronous methods, including:

* "Player.play"

* "Player.pause"

* "Player.setPosition"

* "Player.release"

* "Player.destroy"


Common video playback errors
============================

Common causes of playback failure unrelated to the SDK: CORS, SSL,
mixed content, and connectivity issues. Each entry lists the trigger,
the console signature, and the fix.


Cross-origin resource sharing (CORS)
------------------------------------

CORS errors occur when the player's origin differs from the video's
origin (a different domain or port). Cross-origin requests are blocked
by default. The browser console reports that the request was blocked
by CORS policy.

To resolve CORS errors, configure the video server to allow the
player's origin. CORS errors commonly occur during development on
"localhost". A CORS browser extension or an HTTP proxy such as Charles
or Fiddler can work around the issue temporarily during development.
See CORS on MDN for details.


SSL issues
----------

When using HTTPS, the video server must present a valid Secure Sockets
Layer (SSL) certificate, or the request fails. The browser console
reports an error such as "net::ERR_CERT_AUTHORITY_INVALID" (Chrome) or
a similar code.

Common causes include:

* An expired SSL certificate

* A certificate not trusted by the browser

* A domain name mismatch between the certificate and the video server

* A revoked certificate

* A certificate issued by an untrusted certificate authority

Resolve SSL issues by ensuring the server presents a valid, unexpired
certificate from a trusted authority.


Mixed content errors
--------------------

A mixed content error occurs when the player is hosted on an insecure
(HTTP) page and the video is hosted on a secure (HTTPS) server, or the
other way around. Mixing HTTP and HTTPS requests, or making HTTPS
requests from a page served over HTTP, is not allowed. The browser
console reports a message such as "Mixed Content: The page was loaded
over HTTPS." See mixed content on MDN for details.

Serve the video player, videos, and other assets over HTTPS to avoid
mixed content errors. These errors are easy to miss during
development, since browsers commonly allow mixed content requests from
"localhost". As a temporary local workaround, you can allow insecure
content in Chrome for a specific site.


Connectivity problems
---------------------

A device can fail to connect to the internet, for example during a
temporary outage. The browser console reports
"net::ERR_INTERNET_DISCONNECTED" (Chrome). Check
"window.navigator.onLine" in JavaScript to detect whether the browser
is offline.


Network retry errors
====================

Some network error events describe a failed request attempt, not the
final playback result. When another attempt is available, the player
continues with another request attempt or another URI for the same
request. This commonly applies to manifest and segment requests with
multiple possible URIs, such as DASH "BaseURL", DASH "Location", or
content steering locations.

The request metadata in "error.data.request" describes the failed
attempt:

   player.on(clpp.events.ERROR, event => {
     const error = event.detail;
     const request = error.data && error.data.request;
     if (!request) {
       return;
     }

     console.log(request.uris[request.uriIndex], request.currentAttempt);
   });

"net.Request" has more details about the request. The following
properties are useful:

* "request.currentAttempt": the number of attempts started for this
  request. On the first failed attempt, this is usually "1".

* "request.maxAttempts": the maximum number of attempts allowed for
  this request.

* "request.uris": the URIs that can be attempted for the request.

* "request.uriIndex": the index in "request.uris" used by the failed
  attempt.

Other network error data can help identify the failure:

* "error.data.url": the URL that failed.

* "error.data.status": the HTTP status code, if one was received. For
  browser network failures where no HTTP response was available, this
  can be "0" or "-1".

Use this metadata together with error severity. If the player can
retry a failed network attempt, it reports the failed attempt with
"clpp.Error.Severity.RECOVERABLE". If all attempts fail, the final
error is reported with "clpp.Error.Severity.FATAL".

Control retry behavior with "net.AttemptParameters" in the "manifest"
and "streaming" keys of "PlayerConfiguration". See Player
configuration for details.


## web/events

Events
******

PRESTOplay web SDK events: forwarded HTML5 media events plus
PRESTOplay events under the "clpp.events" namespace.


HTML5 media events
==================

The player forwards standard HTML5 media events, so you can listen to
them with their regular names, such as "play", "playing", "pause",
"seeking", "seeked", "timeupdate", "volumechange", and "ended".

See the MDN media events reference for the complete list.


PRESTOplay events
=================

PRESTOplay events are exposed under the "clpp.events" namespace and
often include a structured payload. Commonly used events:

* "clpp.events.STATE_CHANGED"

* "clpp.events.AUTOPLAY_NOT_ALLOWED"

* "clpp.events.LOAD_START"

* "clpp.events.LOADEDMETADATA"

* "clpp.events.BUFFERING_STARTED" and "clpp.events.BUFFERING_ENDED"

* "clpp.events.TRACKS_ADDED"

* "clpp.events.AUDIO_TRACK_CHANGED", "clpp.events.TEXT_TRACK_CHANGED",
  and "clpp.events.VIDEO_TRACK_CHANGED"

* "clpp.events.BITRATE_CHANGED"

* "clpp.events.ERROR"

* "clpp.events.RELEASING"

See "events" for the complete list.


Add an event listener
=====================

Attach listeners immediately after creating the player, so you don't
miss any events:

   const player = new clpp.Player('video');
   player.on('<eventname>', () => {});
   player.open({ source: 'https://example.com/Manifest.mpd' });

HTML5 media event example:

   player.on('timeupdate', () => {
     console.log('Position:', player.getPosition());
   });

PRESTOplay player event example:

   player.on(clpp.events.STATE_CHANGED, (event) => {
     const detail = event.detail;
     console.log('State changed:' +
       `${detail.previousState} -> ${detail.currentState}`);
   });


Listen once
-----------

Add an event listener that gets triggered only once:

   player.one('playing', () => {
     console.log('Playback started');
   });


Remove an event listener
========================

It's important to remove event listeners when they're no longer
needed.

For an event listener registered like this:

   function onVolumeChange(event) {}
   player.on('volumechange', onVolumeChange);

Remove it when no longer needed:

   player.off('volumechange', onVolumeChange);


## web/getting-started

Getting started
***************

Setup guide for PRESTOplay web SDK (browser). Covers NPM install,
component system, player creation, and first playback.


Prerequisites
=============

* A Castlabs license key (create one at
  https://downloads.castlabs.com)


Install the SDK
===============

Install via NPM:

   npm install @castlabs/prestoplay


Set up the page
===============

Add a "<video>" element, wrapped in a container element, to your HTML
page:

   <div id="container">
     <video id="video" width="640" height="360"></video>
   </div>


Import components
=================

PRESTOplay web uses a modular component system. Import components
before creating a player. Minimum for DASH playback:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.dash";

Other components are available for additional streaming formats:

* "@castlabs/prestoplay/cl.hls" for HLS

* "@castlabs/prestoplay/cl.smooth" for Smooth Streaming

* "@castlabs/prestoplay/cl.crypto" for HLS with AES-128


Create the player and start playback
====================================

Create "Player" with license key and viewer ID, then call "open()"
with the source URL.

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.dash";
   import "@castlabs/prestoplay/clpp.styles.css";

   // Create the player
   const videoEl = document.getElementById("video");
   const containerEl = document.getElementById("container");
   const player = new clpp.Player(videoEl, {
     license: "your-license-key",
     viewerId: "your-viewer-id",
   }, { containerEl });

   // Load content and start playback
   await player.open({
     source: "https://demo.cf.castlabs.com/media/prestodash/Manifest.mpd",
     autoplay: true,
     muted: true,
   });

The "license" and "viewerId" are set once when creating the player.
The "source" is passed to "Player.open" each time you want to play
content.

The basic playback sample
(https://github.com/castlabs/prestoplay-web-code-samples/blob/main/examples/basic.html)
is a complete, runnable page that loads DASH and HLS streams. For more
runnable samples, see the PRESTOplay web code samples
(https://github.com/castlabs/prestoplay-web-code-samples) repository.

Next, see Player basics for a simple UI example and common playback
configuration options.

To load the SDK with script tags instead of a bundler, see Without a
bundler.


Debugging
=========

Enable SDK logs to diagnose playback issues:

   // Info-level logs
   clpp.log.setLogLevel(clpp.log.Level.INFO);

   // Full verbose logs
   clpp.log.setLogLevel(clpp.log.Level.DEBUG);

* Without a bundler


## web/index

PRESTOplay for Web Apps
***********************

PRESTOplay web SDK (browser). NPM package with modular component
architecture. Uses MSE and EME for adaptive streaming and DRM.


Setup
^^^^^

* Getting started

  * Prerequisites

  * Install the SDK

  * Set up the page

  * Import components

  * Create the player and start playback

  * Debugging

* Components

  * Common components

  * DASH

  * HLS through MSE

  * Smooth Streaming

  * AES-128 HLS

* License

  * Castlabs license

  * License domain lock

  * Viewer ID

  * License verification


Playback and configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^

* Player basics

  * Simple UI example

  * Playback and basic configuration

  * React integration

* Player configuration

  * Streaming configuration

  * Retry configuration

  * Low latency

  * Autoplay

* Player surface

  * Basic usage

  * Disabling the container

* Audio player

  * Create the player

  * Load audio content

  * Build custom controls

  * Limitations

* Events

  * HTML5 media events

  * PRESTOplay events

  * Add an event listener

  * Remove an event listener

* Errors

  * The Error object

  * Handling errors

  * Common video playback errors

  * Network retry errors


DRM and licensing
^^^^^^^^^^^^^^^^^

* DRM

  * DRM with DRMtoday

  * DRM with DRMtoday Onboard

  * DRM with header-based DRM environment

  * DRM with Verimatrix VCAS Ultra environment

  * DRM with custom DRM environment

  * CDM configuration

  * Customizing license requests

  * Multiple DRM environments

  * Encrypted Media Extensions API


Content features
^^^^^^^^^^^^^^^^

* Tracks and languages

  * Initial language selection

  * Switching tracks during playback

* Subtitles

  * Text parsers

  * Side-loaded remote text tracks

  * Text displayers

  * CEA-608 captions

* Thumbnails

  * Installation

  * Configuration

  * Usage

  * Preloading

  * Platform-specific notes

* Common media data

  * CMCD configuration

* Low latency and fast zapping

  * Low latency live playback

  * Fast zapping between live channels


Playlists
^^^^^^^^^

* Playlist

  * Install the plugin

  * Create a playlist

  * Add items

  * Start the playlist

  * Listen for changes

  * Code sample


Platform integrations
^^^^^^^^^^^^^^^^^^^^^

* Chromecast

  * Receiver app

  * Sender

  * Messaging

  * Queuing

  * Cast playlist

* AirPlay

  * Using the AirPlay plugin

  * AirPlay with DRMtoday and upfront authorization

* Safari

  * HLS playback

  * DASH playback

  * Native HLS playback caveats

* Smart TV

  * Polyfills

  * Memory and performance

  * Suspend and resume

  * Limitations of advertising

  * Limitations of thumbnails

  * Older Tizen TVs

* Plugins

  * Built-in plugins

  * Writing a custom plugin

  * Registering a plugin


Ads and analytics
^^^^^^^^^^^^^^^^^

* Advertising

  * Ads API

  * Google IMA plugin

  * Yospace plugin

  * FreeWheel plugin (beta)

  * Broadpeak SSAI ads

  * HLS interstitials

  * Rendering UI

* Analytics

  * Conviva analytics

  * NPAW analytics

  * Broadpeak analytics

  * Mux Data analytics


Reference
^^^^^^^^^

* Migration guide

  * Migrating from v6.1 to v6.2

* Docs for LLM agents

* Changelog


## web/license

License
*******

Castlabs license keys, domain locking, viewer IDs, and license
verification for PRESTOplay web SDK.


Castlabs license
================

A Castlabs license key is required to enable the player and unlock its
features. Get a license key.

Provide the license key and "viewerId" when creating the player:

   const player = new clpp.Player('video', {
     license: '<your_license_key>',
     viewerId: '<user_id>',
   });


License domain lock
===================

Castlabs license keys are tied to one domain or a set of domains. The
player works only when your app is served from an allowed domain.


Development
-----------

"localhost" and private network IP addresses are allowed by default
for local development and work even without a license key.


Viewer ID
=========

The viewer ID must uniquely identify the end user of your application.

Castlabs license keys require a "viewerId", so pass it together with
the license key when creating the player. Depending on your contract
with Castlabs, "viewerId" might not be required; in that case, you can
omit it.

   const player = new clpp.Player('video', {
     license: '<your_license_key>',
     viewerId: '5125412-e8809b0-689328e-0a38f476',
   });

If you don't specify "viewerId", "drm.customData.userId" is used as a
fallback:

   const player = new clpp.Player('video', {
     license: '<your_license_key>',
     drm: {
       customData: {
         userId: '5125412-e8809b0-689328e-0a38f476',
         sessionId: 'e43b0c9302d4558f39b76d2d05e5e21eb00b3b28',
       },
     },
   });


License verification
====================

License verification requires HTTPS. If verification fails, the player
reports an error during playback — listen for "clpp.events.ERROR".

If license verification fails, the player reports an error and stops
playback. Listen for "clpp.events.ERROR" and inspect the error code:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.dash";

   const player = new clpp.Player('video', {
     license: '<your_license_key>',
     viewerId: '<user_id>',
   });

   player.on(clpp.events.ERROR, (e) => {
     const error = e.detail;

     if (error.code === clpp.Error.Code.INVALID_LICENSE) {
       // The license key is invalid.
     }

     if (error.code === clpp.Error.Code.USER_ID_NOT_PROVIDED) {
       // The license requires a viewer ID, but neither `viewerId`
       // nor `drm.customData.userId` was provided.
     }
   });

   player.open({
     source: 'https://cdn.com/manifest.mpd',
   });

For the full list of error codes, see Errors.


## web/llms

Docs for LLM agents
*******************

Plain-text exports of the PRESTOplay for web documentation, for LLM
agents.

+----------------------------------------------------+----------------------------------------------------+
| File                                               | Contents                                           |
|====================================================|====================================================|
| llms.txt                                           | Index of every page, with links.                   |
+----------------------------------------------------+----------------------------------------------------+
| llms-full.txt                                      | Full text of every page, concatenated into one     |
|                                                    | file.                                              |
+----------------------------------------------------+----------------------------------------------------+

Click a link to view the file, or right-click and choose **Save link
as** to download it. Both files follow the llms.txt specification.


## web/low-latency

Low latency and fast zapping
****************************

PRESTOplay web SDK low-latency live playback. Covers lowLatencyMode
preset, streaming/ABR tuning, clock sync, live edge chasing, and fast
channel zapping via McPlaylist.

Note:

  Fast zapping between live channels relies on "McPlaylist", which is
  experimental and may change in future releases.


Low latency live playback
=========================

Enable the preset by setting "lowLatencyMode" in your
"PlayerConfiguration". The preset tightens buffering, adjusts adaptive
bitrate (ABR) thresholds, and enables low-latency manifest parsing for
DASH and HLS manifests.

   player.open({
     source: '<live_manifest>',
     lowLatencyMode: true,
   });

Start from the preset and override these values if needed to match
your packaging:

* "StreamingConfiguration" — for example, "bufferingGoal" and
  "rebufferingGoal".

* "AbrConfiguration" — use "initialRestrictions" to cap join
  resolution. A higher downgrade target ("bandwidthDowngradeTarget"
  near "0.95") and a lower upgrade target ("bandwidthUpgradeTarget")
  help avoid stalls while staying close to live.

   player.open({
     source: '<live_manifest>',
     lowLatencyMode: true,
     streaming: {
       bufferingGoal: 0.1,
       rebufferingGoal: 0.01,
       bufferBehind: 30,
     },
     abr: {
       bandwidthUpgradeTarget: 0.6,
       bandwidthDowngradeTarget: 0.95,
       initialRestrictions: {
         maxWidth: 640,
         maxHeight: 480
       }
     },
   });


Clock sync
----------

* "PlayerConfiguration"'s "suggestedPresentationDelay" is set to "0"
  by default for low-latency configuration.

* If your DASH manifest is missing a clock sync URI, supply one via
  "ManifestConfiguration"'s "manifest.dash.clockSyncUri".


Live edge chasing
-----------------

When a player drifts behind the live edge — for example, due to
network conditions or buffering — live edge chasing recovers latency
by increasing the playback rate. Configure it through
"StreamingConfiguration":

* "startChasingAt" — latency threshold (in seconds) at which chasing
  begins.

* "stopChasingAt" — latency threshold (in seconds) at which chasing
  stops.

* "chasingRate" — playback rate used while chasing; must be greater
  than 1.

* "chaseJumpDistance" — if latency exceeds this value, the player
  seeks directly to the live edge instead of gradually catching up.

   player.open({
     source: '<live_manifest>',
     lowLatencyMode: true,
     streaming: {
       enableLiveEdgeChasing: true,
       startChasingAt: 3,
       stopChasingAt: 1,
       chasingRate: 1.5,
       chaseJumpDistance: 10,
     }
   });


Fast zapping between live channels
==================================

Use the experimental "McPlaylist" to reduce zap time between live
manifests. See MC playlist for setup details. To stay aligned with
segment edges for live streams, enable "startAtSegmentBoundary" to
reduce seek time.

   const playlist = new clpp.playlist.McPlaylist({
     anchorId: 'video-anchor',
     config: {
       license: '<your_license_key>',
       viewerId: '<user_id>',
       streaming: {
         bufferingGoal: 1,
         rebufferingGoal: 1,
         startAtSegmentBoundary: true,
         ignoreDrift: true
       }
     }
   });


## web/mc-playlist

MC playlist
***********

Note:

  The multi-controller (MC) playlist API is experimental.

"McPlaylist" — experimental. Reduces zap time between live TV channels
by preloading neighboring items, each with its own player instance.


Configure for fast switching
============================

Set "streaming.rebufferingGoal" and "streaming.bufferingGoal" below
the video segment duration for fastest channel switching.

   player.open({
     source: {
       url: "https://.../index.mpd",
     },
     streaming: {
       // For 2-second segments, set both goals below 2 seconds
       rebufferingGoal: 1,
       bufferingGoal: 1,
       startAtSegmentBoundary: true,
       ignoreDrift: true,
     },
   });

For DRM-protected streams, install the "PersistentLicenseComponent"
and assign an "offlineId" to each protected stream — see Persistent
DRM licenses. Browser support for persistent licenses is limited, so
this helps only on some platforms.

   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.hls";
   import "@castlabs/prestoplay/cl.dash";
   import "@castlabs/prestoplay/cl.persistent";

   player.open({
     source: {
       url: "https://.../index.mpd",
     },
     drm: {
       env: "...",
       customData: { /* ... */ },
       offlineId: "drm-session-4fb0b23a50101171ec90656", // unique ID for local storage
     },
   });


Create the playlist
===================

Pass the Castlabs license and viewer ID through "config":

   const playlist = new clpp.playlist.McPlaylist({
     anchorId: "video-anchor",
     config: {
       license: "<your_license_key>",
       viewerId: "<user_id>",
     },
     // preloadMedia: true,
     // autoplayNext: true,
   });

* "autoplayNext" starts the next item automatically when playback
  ends. It's intended for VOD content.

* "preloadMedia" prebuffers upcoming items to reduce transition time.
  It's intended for VOD content.


Set items and navigate
======================

"setItems(configs)" and "setIndex(i)" set content. "playFirst()",
"playNext()", and "playPrev()" navigate. "hasNext()" and "hasPrev()"
report availability. "on('update', fn)" fires on state changes;
"on('error', fn)" fires on background errors such as preload failures.

   const playlist = new clpp.playlist.McPlaylist({ anchorId: "video-anchor" });

   playlist.setItems([
     {
       source: { url: "https://.../Manifest.mpd" },
       autoplay: true,
     },
     {
       source: { url: "https://.../index.mpd" },
       autoplay: true,
     },
   ]);
   playlist.setIndex(0);

   playlist.on("update", () => {
     const canPlayNext = playlist.hasNext();
     const canPlayPrev = playlist.hasPrev();
   });
   playlist.on("error", (error) => {
     console.error("Playlist error", error);
   });

   await playlist.playNext();

Each item exposes its player and preload state through
"playlist.getCurrent()", "getNext()", and "getPrev()", and the
currently active player through "playlist.getCurrentPlayer()". Call
"playlist.destroy()" to release all players when you're done with the
playlist.


## web/migration

Migration guide
***************

Migration notes for PRESTOplay web SDK version upgrades: v6.1 to v6.2.


Migrating from v6.1 to v6.2
===========================

Version 6.2 simplified the player surface configuration, moved text
parsers into independent components, and dropped Internet Explorer 11
support.


Player surface
--------------

Version 6.2 removed several player surface configuration fields from
"PlayerSurfaceConfiguration" to simplify common scenarios while
keeping the API flexible:

* "moveCssToContainer" — CSS now moves from the media element to the
  container by default. If you provide your own container element, the
  SDK doesn't move it.

* "containerTag" — the SDK always creates a "<div>". If that isn't
  suitable, provide your own container element.

* "mediaTag" — the SDK no longer creates a media element. Provide the
  media element to the player constructor, since it's the most crucial
  part of a player.

* "controls" — removed as a consequence of removing "mediaTag", since
  this property was only added during media element creation.

* "css" — to make CSS management more predictable, the SDK always uses
  classes defined in its stylesheet, consistent with other modules.
  You can still extend the stylesheet for your needs.

The SDK also exports "IPlayerSurface" to simplify DOM interactions.
See Player surface for the current API.


Subtitles
---------

* Text parsers moved to independent components. To enable one, import
  the script and register the component:

     <script src="cl.ttml.js"></script>
     <script>
       player.use(clpp.ttml.TtmlComponent);
     </script>

     <script src="cl.vtt.js"></script>
     <script>
       player.use(clpp.vtt.VttComponent);
     </script>

* The default base font size changed to 7% of the container height
  (was 5%), and the background color of TTML cues inside a region
  changed to transparent (was black). To restore the previous
  behavior:

     const config = {
       textStyle: {
         backgroundColor: "black",
         fontSizePercent: 0.05,
       },
     };

* If you use the HLS-SMPTE plugin ("clpp.hlssmpte.min.js"), register
  the TTML component first (see above).

* The TTML text parser is now compatible with TTML v1 and converts
  pixel sizes to percentages or "em" units to build responsive
  layouts. See Subtitles for details.

* "box-sizing: border-box;" was added to the ".clpp-text-cue-region"
  CSS class, and "vertical-align: top;" was removed from
  ".clpp-container".

* The "enableEnhancedSubtitleManager" option was removed from
  "PlayerConfiguration". Use "enableHtmlCue" instead.

* The native text displayer always displays cues at bottom-middle.


Internet Explorer 11 support
----------------------------

Due to consistently low usage, the PRESTOplay team discontinued
Internet Explorer 11 support with the 6.2.0 release. Maintenance
support for Internet Explorer 11 continued for six months (through 01
May 2022) via 6.1.x releases, after which the team focused development
on modern playback features and experiences.


## web/persistent-licenses

Persistent DRM licenses
***********************

Persistent DRM license reference for PRESTOplay web SDK. Covers
per-DRM-system support, storing/removing licenses with and without a
player instance, and custom session storage.

To store or load an offline session, provide an "offlineId" in the DRM
configuration. Use the asset ID or any other stable identifier. If the
player finds a stored session for that "offlineId", it loads the
session for playback. If no stored session is found, the SDK requests
the license and stores it for later use.


Support
=======

Persistent-license support depends on the DRM system, the browser, and
your DRM or license-server setup. Your integration must support
persistent-license workflows end to end.


Widevine
--------

Widevine persistent and offline licenses are no longer supported on
Chromium-based browsers.


PlayReady
---------

PlayReady persistent licenses are supported when the browser and your
license server configuration support them.


FairPlay
--------

FairPlay persistent licenses are not supported.


DRMtoday
--------

For DRMtoday, persistent-license support also depends on your License
Policy, formerly the Customer Rights Token (CRT).


Import the persistent module
============================

   import "@castlabs/prestoplay/cl.persistent";


Store a license during playback
===============================

   const player = new clpp.Player({...});

   player.on(clpp.events.DRM_SESSION_PERSISTED, function (e) {
     console.log(e);
   });

   // The license is fetched and stored on the first `load` call and
   // reused for subsequent `load` calls.
   player.open({
     source: {
       url: 'https://demo.cf.castlabs.com/media/bbb_abr/Manifest.mpd',
       type: clpp.Type.DASH
     },
     drm: {
       env: 'DRMtoday_STAGING',
       customData: {
         userId: 'purchase',
         sessionId: 'p0',
         merchant: 'six',
       },
       offlineId: 'abcxyz'
     },
     ...
   });


Store a license without a player instance
=========================================

You can also store a license without creating a player instance. Use
"persistent.fetchLicense" and pass the source — either as a string or
as a "Source" — together with the DRM configuration.

   try {
     await clpp.persistent.fetchLicense('//example.com/manifest.mpd',
       {
         env: 'DRMtoday_STAGING',
         customData: {
           userId: 'purchase',
           sessionId: 'p0',
           merchant: 'six',
         },
         offlineId: 'abcxyz'
       },
     );
     console.log('Success!');
   } catch (e) {
     console.error('Couldn\'t fetch license', e);
   }


Remove a stored license
=======================

Remove a stored license you no longer need with
"clpp.persistent.removeLicense()":

   const offlineId = 'abcxyz'

   await clpp.persistent.removeLicense(offlineId);


Session storage
===============

Loading an offline DRM session requires additional metadata. When a
license is persisted, the SDK also stores session IDs, the server
certificate, and other related data — see "persistent.SessionInfo".

PRESTOplay includes a built-in storage engine that uses the
"window.localStorage" API to store and load this session information.

To use a different storage API, such as IndexedDB, implement the
"persistent.ISessionStorage" interface and pass it to the SDK with
"clpp.persistent.useStorage()":

   /**
    * Custom storage implementation.
    */
   class MySessionStorage {
     /**
      * @param {string} offlineId
      * @param {clpp.persistent.SessionInfo} sessionInfo
      * @return {Promise}
      */
     store (offlineId, sessionInfo) {
       ...
     }

     /**
      * @param {string} offlineId
      * @return {Promise<clpp.persistent.SessionInfo>}
      */
     get (offlineId) {
       ...
     }

     /**
      * @param {string} offlineId
      * @return {Promise}
      */
     delete (offlineId) {
       ...
     }

     /**
      * @return {Promise}
      */
     clear () {
       ...
     }

     /**
      * @return {string}
      */
     getName () {
       return 'MySessionStorage'
     }
   }

   clpp.persistent.useStorage(new MySessionStorage());

   const player = new clpp.Player({...});

   ...

   player.open({
     source: {...},
     drm: {
       offlineId: 'abcxyz',
       ...
     }
   });


## web/player-basics

Player basics
*************

Player basics for PRESTOplay web SDK. Covers a minimal playback UI
(container, poster, play button) and common PlayerConfiguration
options (source, stream type, start time, volume, muted).


Simple UI example
=================

Minimal UI pattern: container div wraps the video element, poster
overlays it until playback starts, play button triggers playback.

Wrap the video element in a container with a relative position, and
pass both elements to the player constructor:

   <div class="ui-container">
     <div class="ui-poster" style="background-image: url('poster.jpg');"></div>
     <img class="ui-play-btn" src="play.png" />
     <video id="video" crossorigin="anonymous"></video>
   </div>

   const videoEl = document.getElementById('video');
   const containerEl = document.querySelector('.ui-container');
   const player = new clpp.Player(videoEl, {/* config */}, { containerEl });

   .ui-container {
     position: relative;
     width: 640px;
   }

   .ui-poster {
     position: absolute;
     inset: 0;
     z-index: 2;
     background-repeat: no-repeat;
     background-position: center;
     background-size: cover;
   }

   .ui-play-btn {
     position: absolute;
     left: 50%;
     top: 50%;
     transform: translate(-50%, -50%);
     z-index: 3;
     cursor: pointer;
   }

   .ui-container.ui-started .ui-poster,
   .ui-container.ui-started .ui-play-btn {
     display: none;
   }

Add the "ui-started" class when playback begins, and start playback
when the play button is clicked:

   player.on('playing', () => {
     document.querySelector('.ui-container').classList.add('ui-started');
   });

   document.querySelector('.ui-play-btn').addEventListener('click', () => {
     player.play();
   });


Playback and basic configuration
================================

"PlayerConfiguration" is passed to the "Player" constructor. Source
and per-load options are passed to "Player.open".


Loading content
---------------

Pass a configuration object with a "source" property:

   player.open({
     source: 'https://example.com/manifest.mpd',
   });

"source" also accepts an array of URLs. The player tries them in order
and plays the first one it can play on the current platform:

   player.open({
     source: [
       'https://example.com/manifest1.mpd',
       'https://example.com/manifest2.mpd',
       'https://example.com/master.m3u8',
     ],
   });


Supported formats
-----------------

Supported types are "clpp.Type.DASH", "clpp.Type.HLS",
"clpp.Type.SMOOTH_STREAMING", and "clpp.Type.MP4". If the format can't
be deduced from the file extension, specify it explicitly as "type":

   player.open({
     source: 'https://example.com/manifest.foo',
     type: clpp.Type.DASH,
   });


Start time, volume, and muted state
-----------------------------------

   player.open({
     source: 'https://example.com/manifest.mpd',
     startTime: 300, // start 5 minutes in, VOD only
     volume: 0.5,
     autoplay: true,
     muted: true,
   });

For live content, the player starts at the live edge by default.

See Tracks and languages for setting the initial audio and text
language.


React integration
=================

React integration: create the "Player" in a "useEffect()" hook on
mount and call "Player.destroy" in its cleanup function. Load new
content with "Player.open" when the "src" prop changes.

The React integration sample
(https://github.com/castlabs/prestoplay-web-code-samples/blob/main/examples/react/react.html)
covers:

* Creating the player on mount and destroying it on unmount

* Loading content when a prop changes

* A play/pause button driven by "clpp.events.STATE_CHANGED"

* Fullscreen on the component's container element

* A seek bar based on "Player.getSeekRange", which also supports live
  content


## web/player-configuration

Player configuration
********************

High-value "PlayerConfiguration" options are documented on their own
pages: Analytics, Advertising, and Thumbnails. This page covers
streaming/buffering, retry behavior, and autoplay. Basics (source,
format, start time, volume) are covered in Player basics; language
preferences in Tracks and languages.


Streaming configuration
=======================

"StreamingConfiguration", passed under the "streaming" key, controls
buffering and segment download behavior.

   player.open({
     source: 'https://example.com/manifest.mpd',
     streaming: {
       bufferingGoal: 20,  // seconds to buffer ahead of the playhead (default: 10)
       rebufferingGoal: 5, // minimum seconds to resume after a stall; must be <= bufferingGoal (default: 2)
       bufferBehind: 30,   // seconds of content kept behind the playhead (default: 30)
     },
   });


Retry configuration
===================

The player retries failed network requests automatically. Control
retry behavior through "AttemptParameters":

* "streaming.attemptParameters" controls retries for segment requests.

* "manifest.attemptParameters" controls retries for manifest requests.

   player.open({
     source: 'https://example.com/manifest.mpd',
     streaming: {
       attemptParameters: {
         maxAttempts: 5,    // maximum number of attempts (including the first)
         baseDelay: 1000,   // delay before the first retry, in milliseconds
         backoffFactor: 2,  // multiplier applied to the delay on each retry
         fuzzFactor: 0.5,   // randomization factor to spread retry timing
         timeout: 30000,    // per-request timeout in milliseconds; 0 = unlimited
       },
     },
     manifest: {
       attemptParameters: {
         maxAttempts: 3,
         baseDelay: 500,
         backoffFactor: 2,
         fuzzFactor: 0.5,
         timeout: 15000,
       },
     },
   });


Low latency
===========

For low latency streaming configuration, see Low latency.


Autoplay
========

"autoplay" controls whether playback starts when "Player.open"
resolves. Default: "false" (loaded and buffered, paused).

   await player.open({
     source: '//example.com/manifest1.mpd',
     autoplay: false, // default
   });

   // Content is ready but paused — start playback after the button is clicked
   playButton.addEventListener('click', () => player.play());

With "autoplay: true", the player starts playing as soon as the
content is ready, with no additional call:

   await player.open({
     source: '//example.com/manifest1.mpd',
     autoplay: true,
   });
   // Playback starts automatically when load() resolves

Use the "autoplay" configuration option rather than the HTML "<video
autoplay>" attribute. The player ignores the HTML attribute to avoid
conflicts with its own autoplay implementation.

Review the browser autoplay policy below before configuring autoplay.


Browser autoplay policy
-----------------------

Browser autoplay policy (full details in the MDN autoplay guide):

* Autoplay with sound requires prior user interaction with the page
  (click, tap, or key press).

* Muted video autoplay is generally allowed without prior interaction.

This policy applies to all programmatic attempts to start playback,
not just the "autoplay" option. Calling "Player.play" from a script —
for example on page load — is subject to the same restrictions. Only
calls triggered directly by a user gesture (click, tap, or key press)
are guaranteed to succeed.

To play a video immediately on page load, it must start out muted.

   // Playback starts immediately and muted
   await player.open({
     source: '//example.com/manifest1.mpd',
     autoplay: true,
     muted: true,
   });

   // The user can enable audio later by clicking a button
   muteButton.addEventListener('click', () => {
     player.setMuted(false);
   });

If the browser blocks autoplay, "Player.open" rejects with an error
(the same applies to "Player.play").


## web/player-surface

Player surface
**************

Player surface: the "<video>" element plus its container "<div>", used
to attach overlays (subtitles, ads). Controlled through the
"IPlayerSurface" API.

You interact with the player surface through the "IPlayerSurface" API.


Basic usage
===========

Import the default PRESTOplay styles:

   import "@castlabs/prestoplay/clpp.styles.css";

The player surface is initialized with the player by passing a video
element and its container element to the constructor:

   <div id="containerID">
     <video id="videoID"></video>
   </div>

   const videoEl = document.getElementById('videoID');
   const containerEl = document.getElementById('containerID');
   const player = new clpp.Player(videoEl, {/* config */}, { containerEl });

"containerEl" must be the direct parent of the "<video>" element and
can be any element. If you omit it, the player creates the container
"<div>" itself.


Overriding default CSS styles
-----------------------------

PRESTOplay wraps the "<video>" element in a container "<div>" with the
"clpp-container" class, and adds the "clpp-video" class to the
"<video>" element itself:

   <div class="clpp-container">
     <video id="videoID" class="clpp-video" />
   </div>

When the player creates the container, it moves the classes, inline
styles, and "width"/"height" attributes of the "<video>" element to
the container.

To override the default player surface styles, add your own stylesheet
and extend the ".clpp-container" or ".clpp-video" class.


Disabling the container
=======================

"disableContainer: true" removes the player surface container.
Trade-offs below.

Note:

  Disabling the container has these effects:

  * Subtitle components may not display subtitles correctly, or at
    all.

  * Ad components (such as Google IMA or FreeWheel) may not display
    ads and ad overlays correctly, or at all.

  * The "HtmlTextDisplayer" API does not work.

To disable the player surface container, use the "disableContainer"
option when initializing the player:

   <video id="videoID"></video>

   const videoEl = document.getElementById('videoID');
   const player = new clpp.Player(videoEl, {/* config */}, { disableContainer: true });


## web/playlist

Playlist
********

"Playlist" plugin for sequential playback of multiple media items.
Items can differ in stream format (for example, mixing HLS and DASH).
Transitions between items happen automatically when playback ends.


Install the plugin
==================

   import "@castlabs/prestoplay/cl.playlist";


Create a playlist
=================

Create a player, then attach a "Playlist" instance to it:

   const player = new clpp.Player("video", {
     license: "<your_license_key>",
     viewerId: "<user_id>",
   });
   const playlist = new clpp.Playlist(player);


Add items
=========

Add items with "Playlist.append". Each item needs a "configuration"
object with at least a "source":

   playlist.append({
     title: "Foo 1",
     configuration: {
       source: "https://demo.cf.castlabs.com/media/prestodash/Manifest.mpd",
       autoplay: true,
     },
   });
   playlist.append({
     title: "Foo 2",
     configuration: {
       source: "https://demo.cf.castlabs.com/media/prestodash/Manifest.mpd",
       autoplay: true,
     },
   });


Start the playlist
==================

Call "playlist.start()" to load the first item and register the
playlist's automatic item-switching behavior, then "player.play()" to
start playback. "start()" is synchronous and doesn't return a value —
it triggers loading without waiting for it to finish, so it isn't
awaited. The playlist switches to the next item automatically when the
current item ends.

   playlist.start();
   player.play();


Listen for changes
==================

Listen to "clpp.events.PLAYLIST_ITEM_CHANGED" and
"clpp.events.PLAYLIST_MODIFIED" to react to playlist state changes.
See "Playlist" for the full API.

   playlist.on(clpp.events.PLAYLIST_ITEM_CHANGED, () => {
     // the active item changed
   });
   playlist.on(clpp.events.PLAYLIST_MODIFIED, () => {
     // an item was added, removed, or reordered
   });


Code sample
===========

See the playlist sample
(https://github.com/castlabs/prestoplay-web-code-samples/blob/main/examples/playlist/playlist.html)
for a complete page that mixes DASH and HLS items, adds previous and
next buttons with "Playlist.previous" and "Playlist.next", and jumps
to an item with "Playlist.goTo".

* MC playlist

* SC playlist


## web/plugins

Plugins
*******

Built-in plugins for PRESTOplay web SDK, plus how to write a custom
one. Plugins implement "PlayerPlugin"; a "PlayerPluginFactory"
registers them with "Player".


Built-in plugins
================

Each plugin ships as a separate module and must be imported before
creating the player to register it.

+----------------------------------------------------+----------------------------------------------------+
| Plugin                                             | Use                                                |
|====================================================|====================================================|
| "Adobe Analytics"                                  | Reports playback metrics to Adobe Analytics via    |
|                                                    | the "s.Media" API.                                 |
+----------------------------------------------------+----------------------------------------------------+
| "AirPlay"                                          | Casts to AirPlay receivers. See AirPlay.           |
+----------------------------------------------------+----------------------------------------------------+
| "Broadpeak"                                        | Broadpeak server-side ad insertion and analytics.  |
|                                                    | See Analytics.                                     |
+----------------------------------------------------+----------------------------------------------------+
| "Conviva"                                          | Reports playback metrics to Conviva Experience     |
|                                                    | Insights. See Analytics.                           |
+----------------------------------------------------+----------------------------------------------------+
| "FreeWheel"                                        | FreeWheel ad insertion. See Advertising.           |
+----------------------------------------------------+----------------------------------------------------+
| "HLS SMPTE-TT"                                     | Processes SMPTE-TT image cues in HLS streams. See  |
|                                                    | Subtitles.                                         |
+----------------------------------------------------+----------------------------------------------------+
| "IMA"                                              | Google Interactive Media Ads (IMA) SDK             |
|                                                    | integration. See Advertising.                      |
+----------------------------------------------------+----------------------------------------------------+
| "Mux Data"                                         | Reports playback metrics to Mux Data. See          |
|                                                    | Analytics.                                         |
+----------------------------------------------------+----------------------------------------------------+
| MediaTailor                                        | AWS Elemental MediaTailor server-side ad           |
|                                                    | insertion.                                         |
+----------------------------------------------------+----------------------------------------------------+
| "NPAW / Youbora"                                   | Reports playback metrics to NPAW (Youbora). See    |
|                                                    | Analytics.                                         |
+----------------------------------------------------+----------------------------------------------------+
| "Playlist"                                         | Sequential playback of multiple media items. See   |
|                                                    | Playlist.                                          |
+----------------------------------------------------+----------------------------------------------------+
| SIMID                                              | Secure Interactive Media Interface Definition      |
|                                                    | (SIMID) support for interactive ad creatives.      |
+----------------------------------------------------+----------------------------------------------------+
| "Thumbnails"                                       | Loads and parses thumbnail previews. See           |
|                                                    | Thumbnails.                                        |
+----------------------------------------------------+----------------------------------------------------+
| "Vimond"                                           | Vimond integration. Deprecated — will be removed   |
|                                                    | in a future major version.                         |
+----------------------------------------------------+----------------------------------------------------+
| "VR"                                               | Adds 360-degree video playback support.            |
+----------------------------------------------------+----------------------------------------------------+
| "Yospace"                                          | Yospace server-side ad insertion. See Advertising. |
+----------------------------------------------------+----------------------------------------------------+


Writing a custom plugin
=======================

PRESTOplay plugins are class-based components that implement the
"PlayerPlugin" interface. The interface defines a set of callbacks and
hooks that the player calls at different points during its lifecycle.

The player calls these callbacks on each plugin instance:

+----------------------------------------------------+----------------------------------------------------+
| Callback                                           | Called                                             |
|====================================================|====================================================|
| "onPlayerCreated(player)"                          | When the "Player" instance is created. Set up      |
|                                                    | anything that lives as long as the player, such as |
|                                                    | UI.                                                |
+----------------------------------------------------+----------------------------------------------------+
| "onContentWillLoad(player, source)"                | Before content loads. Register event listeners     |
|                                                    | here. Return a URL, or a promise that resolves     |
|                                                    | with one, to replace the stream URL. If a promise  |
|                                                    | is returned, loading waits for it.                 |
+----------------------------------------------------+----------------------------------------------------+
| "onContentLoaded(player)"                          | After content loads. Content information such as   |
|                                                    | "Player.isLive" and "Player.getDuration" is        |
|                                                    | available from this point.                         |
+----------------------------------------------------+----------------------------------------------------+
| "onPlayerWillRelease(player)"                      | Before the current content is released, including  |
|                                                    | before each new "Player.open" call. Remove the     |
|                                                    | listeners registered in "onContentWillLoad".       |
+----------------------------------------------------+----------------------------------------------------+
| "onPlayerWillDestroy(player)"                      | Before the player is destroyed. Clean up           |
|                                                    | everything else.                                   |
+----------------------------------------------------+----------------------------------------------------+
| "id()"                                             | Returns the plugin ID. The plugin instance is then |
|                                                    | available through "Player.getPlugin".              |
+----------------------------------------------------+----------------------------------------------------+

The custom plugin sample
(https://github.com/castlabs/prestoplay-web-code-samples/blob/main/examples/plugins/stats_overlay.html)
implements every callback in a plugin that renders a stats overlay on
top of the video and shows when each callback runs.


Registering a plugin
====================

Register the plugin with the SDK before using it. The SDK exposes a
plugin factory "PlayerPluginFactory" interface that you implement and
provide.

A generic plugin factory that creates instances of a "MyPlugin" class
looks like this:

   /**
    * @implements {clpp.PlayerPluginFactory}
    */
   class MyPluginFactory {
     /**
      * @override
      */
     create (playerConfig) {
       return new MyPlugin();
     }
   };

Register the factory with the player using "Player.registerPlugin":

   // *Before* the player instance is created
   clpp.Player.registerPlugin(new MyPluginFactory());

   // ...

   // Now the plugin will be used with each new instance of the player.
   const player = new clpp.Player(...);


## web/safari

Safari
******

Safari-specific playback behavior for PRESTOplay web SDK. Native HLS
delegate by default; MSE delegate for DASH and optionally for HLS.


HLS playback
============

For HLS streams on Safari, PRESTOplay uses a native player delegate
that relies on Safari's built-in HLS support through the "<video>"
element. This is the default behavior and requires no extra
configuration:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.hls";

   player.open({
     source: {
       url: 'https://example.com/stream.m3u8',
       type: clpp.Type.HLS,
     },
   });

One strength of this default player is support for FairPlay-protected
MPEG-TS streams, which the MSE player can't provide due to limitations
of the browser.


Using the MSE player for HLS
----------------------------

The MSE player can also play HLS on Safari — for example, when you
need features only available through MSE-based playback. See
Components for details on the MSE module. To opt in, set
"preferNativeHlsOnSafari" to "false":

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.hls";

   player.open({
     source: {
       url: 'https://example.com/stream.m3u8',
       type: clpp.Type.HLS,
     },
     streaming: {
       preferNativeHlsOnSafari: false,
     },
   });


DASH playback
=============

For DASH streams on Safari, PRESTOplay uses the MSE player delegate,
which requires the MSE and DASH modules:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.dash";

   player.open({
     source: {
       url: 'https://example.com/stream.mpd',
       type: clpp.Type.DASH,
     },
   });


Native HLS playback caveats
===========================

Native player delegate (HLS default) playback has some caveats due to
limitations or known issues in Safari's WebKit API.


IMA on iOS and tracks UI
------------------------

On iOS, the IMA SDK runs in custom playback mode, so track objects are
recreated when an ad break ends and playback resumes on the primary
content.

Listen for "clpp.events.TRACKS_REMOVED" followed by
"clpp.events.TRACKS_ADDED" to get notified.

Because tracks are recreated, your UI must reset its state at the
start and end of each ad break. On "AD_BREAK_STARTED", hide the track
selection UI and clear any stale state. On "AD_BREAK_STOPPED", read
the current tracks from the track manager — PRESTOplay has restored
them by this point — and show the UI again:

   player.on(clpp.events.AD_BREAK_STARTED, () => {
     // Hide tracks UI
     trackSelectionUI.style.display = 'none';
     // Clear your stored tracks state
     resetTrackUI();
   });

   player.on(clpp.events.AD_BREAK_STOPPED, () => {
     // Track objects have changed — re-read data from the track manager
     // to populate your tracks state
     renderTrackUI(player.getAudioTracks(), player.getTextTracks());
     // Show tracks UI
     trackSelectionUI.style.display = '';
   });


Audio tracks on iOS
-------------------

Due to known WebKit issues (#301928, #297904) on iOS 26.4 and 26.3,
audio tracks must be formatted in a specific way to work correctly.

Set "AUTOSELECT=NO,DEFAULT=NO" and use unintelligible language codes
such as "l1", "l2", "l3" in the HLS playlist:

   #EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio/mp4a.40.2",LANGUAGE="l1",NAME="English",AUTOSELECT=NO,DEFAULT=NO,CHANNELS="2",URI="audio-en-US-mp4a.40.2.m3u8"
   #EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio/mp4a.40.2",LANGUAGE="l2",NAME="German",AUTOSELECT=NO,DEFAULT=NO,CHANNELS="2",URI="audio-de-DE-mp4a.40.2.m3u8"
   #EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio/mp4a.40.2",LANGUAGE="l3",NAME="Spanish",AUTOSELECT=NO,DEFAULT=NO,CHANNELS="2",URI="audio-es-ES-mp4a.40.2.m3u8"

Then use the "preferredAudioLanguage" configuration option to select
the default track, instead of relying on the "AUTOSELECT" and
"DEFAULT" attributes:

   player.open({
     source: '...',
     preferredAudioLanguage: ['l1'], // English
   });


Lack of metadata about tracks
-----------------------------

Safari doesn't provide full metadata for tracks in general. See
"SafariConfiguration" for options to enable richer track metadata with
the native player delegate, or switch to the MSE player delegate for
access to all playlist metadata.


Video track selection isn't supported
-------------------------------------

Safari doesn't support manual selection of video tracks or renditions
(changing quality), so these APIs aren't usable:

* "TrackManager.getVideoTracks"

* "TrackManager.setVideoTrack"

* "TrackManager.setVideoRendition"

The native player delegate handles adaptive bitrate streaming (ABR)
internally, so ABR-related configuration doesn't apply either:

* "AbrConfiguration"

* "Restrictions"

Switch to the MSE player delegate for full control over track
selection and ABR.


## web/sc-playlist

SC playlist
***********

Note:

  The single-controller (SC) playlist API is experimental.

"ScPlaylist" — experimental. Single controller drives continuous
back-to-back playback across items. Inherits from "Player"; all
"Player" methods ("on()", "off()", "getPosition()", "seek()", etc.)
work on the playlist instance.


Create the playlist
===================

Instantiate the playlist the same way you'd instantiate a "Player":

   <video id="my_video"></video>

   const playlist = new clpp.playlist.ScPlaylist("my_video", {
     license: "<your_license_key>",
     viewerId: "<user_id>",
   });


Load content
============

Load a playlist of two items with "ScPlaylist.openPlaylist". Playback
starts from the first item. Each item must have a unique "id":

   await playlist.openPlaylist(0, [
     {
       id: "ASSET1",
       source: { url: "..." },
     },
     {
       id: "ASSET2",
       source: { url: "..." },
     },
   ]);

Playback-related options such as "autoplay", "startTime", and
"streaming" must be passed either through the constructor or as
properties of the first item passed to "openPlaylist()":

   await playlist.openPlaylist(0, [
     {
       id: "ASSET1",
       source: { url: "..." },
       autoplay: true,
       playlist: {
         startTime: 120,
       },
     },
     {
       id: "ASSET2",
       source: { url: "..." },
     },
   ]);

Encrypted content is supported, but only when every item is encrypted
with the same method and key. Pass the "drm" configuration as a
property of the first item:

   await playlist.openPlaylist(0, [
     {
       id: "ASSET1",
       source: { url: "..." },
       drm: { /* ... */ },
     },
     {
       id: "ASSET2",
       source: { url: "..." },
     },
   ]);

Use "playlist.startTime" to set the position playback starts from. The
position must fall inside the first item's timeline. It defaults to
"0" and doesn't affect the timeline's duration:

   await playlist.openPlaylist(0, [
     {
       id: "ASSET1",
       source: { url: "..." },
       playlist: {
         startTime: 120, // start 120 seconds in
       },
     },
   ]);

Use "playlist.endTime" to set the position playback stops at. The
value is relative to the start of the first item and can span any
number of items. It doesn't affect the timeline's duration:

   await playlist.openPlaylist(0, [
     {
       id: "ASSET1",
       source: { url: "..." },
       playlist: {
         endTime: 600, // end at 600 seconds
       },
     },
   ]);

Append more items with "ScPlaylist.addItem":

   await playlist.addItem({
     id: "ASSET3",
     source: { url: "..." },
   });


Seeking
=======

Call "Player.seek" to seek within the currently playing item:

   // Seek to position 2 minutes inside the current item
   await playlist.seek(120);

Call "ScPlaylist.seekWith" to seek relative to the current position —
the seek can cross into a following item, or a preceding one if the
value is negative:

   // Seek 2 minutes forward, possibly into one of the next items
   await playlist.seekWith(120);

   // Seek 2 minutes backward, possibly into one of the preceding items
   await playlist.seekWith(-120);


Timeline windows
================

Call "ScPlaylist.getTimeline" to get a representation of the playlist
timeline. Each playlist item is represented by one window, and the
currently playing item is the current window:

   const timeline = playlist.getTimeline();
   // Get the index of the currently playing/selected item
   const activeIndex = timeline.getCurrentWindowIndex();
   const windows = timeline.getWindows();

   windows.forEach((win, index) => {
     win.getStart();
     win.getDuration();
     // window ID is equal to configuration.id of the corresponding playlist item
     win.getId();
   });


Timeline modes
==============

The "playlist.timeline" configuration option switches to "flat" mode.
In "flat" mode, the timelines of individual playlist items join into a
single continuous timeline:

   const playlist = new clpp.playlist.ScPlaylist("video", {
     license: "<your_license_key>",
     viewerId: "<user_id>",
     playlist: {
       timeline: "flat", // switch to flat timeline mode
     },
   });

Switching to "flat" mode changes the behavior of timeline-related
methods such as "Player.getPosition", "Player.getDuration",
"Player.getSeekRange", and "Player.seek".


Timeline cropping
=================

Use "playlist.cropTimeline" to crop the timeline according to the
values of "playlist.startTime" and "playlist.endTime". Cropping
affects the duration of the timeline.

Crop off the first 120 seconds of the first item and start playback
from the new position 0:

   await playlist.openPlaylist(0, [
     {
       id: "ASSET1",
       source: { url: "..." },
       playlist: {
         startTime: 120,
         cropTimeline: true,
       },
     },
   ]);

Crop off the last 200 seconds of the last item — that is, crop
anything past a cumulative 600 seconds from the start of the first
item:

   await playlist.openPlaylist(0, [
     {
       id: "ASSET1", // duration 400
       source: { url: "..." },
       playlist: {
         endTime: 600,
         cropTimeline: true,
       },
     },
     {
       id: "ASSET2", // duration 400
       source: { url: "..." },
     },
   ]);

Crop off the first 200 seconds of the first item and the last 200
seconds of the second (last) item:

   await playlist.openPlaylist(0, [
     {
       id: "ASSET1", // duration 400
       source: { url: "..." },
       playlist: {
         startTime: 200,
         endTime: 600,
         cropTimeline: true,
       },
     },
     {
       id: "ASSET2", // duration 400
       source: { url: "..." },
     },
   ]);


Timeline cues
=============

Listen for timeline cues defined by DASH "EventStream" events or HLS
"EXT-X-DATERANGE" tags:

   playlist.on(clpp.events.TIMELINE_CUE_ADDED, (e) => {
     // The cue appeared in the manifest
     const cue = e.detail;
   });
   playlist.on(clpp.events.TIMELINE_CUE_ENTER, (e) => {
     // Playback position entered the cue
     const cue = e.detail;
   });
   playlist.on(clpp.events.TIMELINE_CUE_EXIT, (e) => {
     // Playback position exited the cue
     const cue = e.detail;
   });

Each item's cues are parsed as soon as the item is added to the
playlist, so you get an overview of the cues of every item, not just
the currently playing one. Call "Player.getTimelineCues" for a list of
all cues across all items:

   const cues = playlist.getTimelineCues();

Each cue can be matched to the item it belongs to via the
configuration ID:

   cue.configurationId === configuration.id;

In "basic" timeline mode, cues are positioned relative to the start of
the item they belong to:

   // [ASSET1, ASSET2]
   cue.configurationID; // ASSET2
   cue.startTime === 10; // starts 10 seconds into ASSET2
   cue.endTime === 20; // ends 20 seconds into ASSET2

In "flat" timeline mode, cues are positioned relative to the start of
the first item of the playlist:

   // [ASSET1, ASSET2]
   // ASSET1 has a duration of 400 seconds
   cue.configurationID; // ASSET2
   cue.startTime === 410; // starts 10 seconds into ASSET2
   cue.endTime === 420; // ends 20 seconds into ASSET2


Stopping playback
=================

Call "ScPlaylist.release" to stop playback and reset the playlist to
its initial state:

   await playlist.release();


Events
======

The playlist emits events for the currently playing item and the
timeline. Events specific to the single-controller playlist are
prefixed "SC_PLAYLIST".


SC_PLAYLIST_TIMELINE_CHANGED
----------------------------

Triggered whenever a new window is added to the timeline, or when a
timeline window changes duration or turns static for a live stream.
Depending on your UI, this may be a good time to redraw the timeline:

   function handler() {
     const duration = playlist.getDuration();
     const position = playlist.getPosition();
     // redraw the timeline
   }
   playlist.on(clpp.events.SC_PLAYLIST_TIMELINE_CHANGED, handler);
   // playlist.off(clpp.events.SC_PLAYLIST_TIMELINE_CHANGED, handler);


SC_PLAYLIST_ITEM_CHANGED
------------------------

Triggered whenever playback transitions from one item to another. The
event's "id" property corresponds to the "id" property of the item's
configuration — another good point to redraw your UI timeline:

   function handler(event) {
     // event.id contains the `id` property of the current item (e.g. "ASSET1")
     console.log("Item changed", event.id);

     const duration = playlist.getDuration();
     const position = playlist.getPosition();
     // redraw the timeline
   }
   playlist.on(clpp.events.SC_PLAYLIST_ITEM_CHANGED, handler);
   // playlist.off(clpp.events.SC_PLAYLIST_ITEM_CHANGED, handler);


SC_PLAYLIST_ENDED
-----------------

Triggered when playback reaches the end of the playlist. The end of
the playlist is either the "endTime" configuration or, by default, the
end of the last item:

   function handler() {
     // Reached the end of the playlist
   }
   playlist.on(clpp.events.SC_PLAYLIST_ENDED, handler);
   // playlist.off(clpp.events.SC_PLAYLIST_ENDED, handler);


Content modes
=============

The playlist supports two modes of operation based on the type of
content it receives. The default is "VOD" mode, where each item is
expected to be a static video stream.

The second mode is "DVR".


DVR content mode
----------------

In "DVR" mode, every item except the last is expected to be VOD, and
the last item may be a DVR stream (a growing live stream).

While the DVR stream is live, you can't add more items to the
playlist. The DVR stream may turn static over time — at that point,
you can append another DVR stream item to the end of the playlist.

Enable "DVR" content mode with the "playlist.content" option. The
"playlist.endTime" option must also be specified — it determines the
last item and the end time of the playlist:

   const playlist = new clpp.playlist.ScPlaylist("video", {
     license: "<your_license_key>",
     viewerId: "<user_id>",
     playlist: {
       content: "DVR",
       endTime: 950, // end after 950 seconds
     },
   });

   await playlist.openPlaylist(0, [
     {
       id: "ASSET1",
       source: { url: "..." }, // VOD
     },
     {
       id: "ASSET2",
       source: { url: "..." }, // DVR
     },
   ]);

"DVR" mode adds two events on top of the basic set.


SC_PLAYLIST_LIVE_TURNED_STATIC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Triggered when a DVR item becomes static. After this, you can append
another DVR item to the playlist:

   async function handler() {
     await playlist.addItem({
       id: "ASSET3",
       source: { url: "..." }, // DVR
     });
   }
   playlist.on(clpp.events.SC_PLAYLIST_LIVE_TURNED_STATIC, handler);
   // playlist.off(clpp.events.SC_PLAYLIST_LIVE_TURNED_STATIC, handler);


LIVE_TURNED_STATIC
~~~~~~~~~~~~~~~~~~

Triggered shortly before playback reaches the end of the playlist as
defined by "playlist.endTime". At this point, the playlist stops
loading manifest updates and the timeline turns static:

   function handler() {
     // The stream became static
     playlist.isLive(); // false
   }
   playlist.on(clpp.events.LIVE_TURNED_STATIC, handler);
   // playlist.off(clpp.events.LIVE_TURNED_STATIC, handler);


## web/smart-tv

Smart TV
********

Smart TV platform guidance for PRESTOplay web SDK: Samsung Tizen, LG
webOS, Hisense VIDAA, and other MSE/EME platforms. Covers polyfills,
memory, suspend/resume, advertising limitations, thumbnails, and older
Tizen support.


Polyfills
=========

Smart TV platforms run a wide range of web engine versions. Some older
devices run engines as old as Chromium 38 or WebKit 538.2, which may
be missing features that PRESTOplay for web relies on.

Load the polyfill before any other SDK modules to ensure compatibility
across all supported devices:

   import "@castlabs/prestoplay/cjs/polyfill.min.js"

Older Tizen engines also require your app to be bundled and transpiled
to ES5 before deployment. See Getting started for SDK distribution
details.


Memory and performance
======================

Smart TV platforms vary in available memory and processing power.
Keeping resource usage low helps ensure smooth playback across all
supported devices, including older and lower-end models:

* Keep DVR windows short and manifests compact to reduce parsing and
  memory overhead.

* Keep thumbnail grids small — see Large grid images.


Suspend and resume
==================

Smart TV platforms that support multitasking can suspend your app —
for example, when the user presses the Home button, switches to
another app, or the device enters a power-saving mode. Handle these
transitions with one of the following approaches.


Automatic pause and resume
--------------------------

The simplest approach is to enable "pauseWhenInBackground" in your
player configuration. When set to "true", the SDK automatically pauses
playback when the page becomes hidden and resumes when it becomes
visible again:

   const player = new clpp.Player('video', {
     license: '<your_license_key>',
     pauseWhenInBackground: true,
   });

This relies on the standard "document.visibilitychange" event and
"document.hidden" property, both supported by Tizen and webOS.


Advanced suspend handling
-------------------------

For more complex cases — releasing DRM resources or tearing down the
player entirely on suspend, rather than just pausing — listen to
"visibilitychange" directly:

   document.addEventListener('visibilitychange', async () => {
     if (document.hidden) {
       // App moved to background — release resources
       await player.release();
     } else {
       // App returned to foreground — reload content
       await player.open({ source: currentSource });
     }
   });

Test suspend and resume on each target device. Older Tizen models may
reclaim the video decoder on suspend, so reload the player on resume
if needed. Some webOS versions terminate the app entirely, so treat
returning to foreground as a potential fresh start.


Limitations of advertising
==========================


IMA SDK
-------

The IMA plugin is supported on smart TV devices such as Samsung TV and
LG TV in experimental mode. Google doesn't officially verify support
for the IMA SDK on smart TVs. Because the platform relies on a single
video element for both content and ad playback, there are some known
limitations:

* Post-roll ads: analytics integrations report a new playback session
  after a post-roll ad finishes, because the player content must be
  reinitialized.

* Pre-roll ads on webOS: the player waits for the main content to
  reach the playing state before detaching the video element for the
  ad break, which can cause a brief flash of the main content before
  the pre-roll starts.

* Behavior may vary across smart TV models, since the IMA SDK behaves
  differently across devices — verify playback on your target devices.

* When using custom playback with a single video element and VAST
  tags, set "isVast: true" in "ImaConfiguration" to ensure VAST
  playback is selected.

Refer to "ImaConfiguration" and its "disableCustomPlayback" option to
disable ads on smart TV devices if needed.


Skippable ads
-------------

The IMA SDK doesn't support skippable ads on smart TVs and rejects any
VAST creative with a "skipoffset" attribute. Set up device-based
targeting rules on your ad server so smart TV traffic only receives
non-skippable VAST creatives.


Limitations of thumbnails
=========================


Large grid images
-----------------

Thumbnail image grids with large resolutions may not process correctly
on some smart TVs. We've observed unexpected downscaling of images
larger than approximately 10,000 × 10,000 pixels on certain Hisense
and Philips TV models. Split large image grids into multiple smaller
grids to avoid this.


Older Tizen TVs
===============

PRESTOplay for web provides both native and MSE-based playback on
older Tizen TVs.


Native playback
---------------

PRESTOplay for web wraps the available native player implementation
("AVPlay") to support feature-rich playback of DRM-protected assets.
The SDK supports native playback on Tizen versions 2.3 and 2.4.

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.tizen";

   const player = new clpp.Player('video', ...);

   player.open({
     source: {
       url: 'http://demo.cf.castlabs.com/media/tos_new/DEMO.mpd?v=2',
       type: clpp.Type.DASH,
     },
     // ...
     drm: {
       // ...
     },
   });


Subtitle streamer
~~~~~~~~~~~~~~~~~

Native playback on Tizen 2.x TVs doesn't support embedded subtitles
for MPEG-DASH streams. To address this, PRESTOplay can side-stream and
display text alongside native playback.

This works well with VOD assets; some live assets can show
synchronization issues, and Castlabs continues to improve the streamer
in this area.

Subtitle streaming is the preferred way to show text on older Tizen
devices and is enabled by default. If you need to disable it, add this
to your configuration:

   const config = {
     // ...
     tizen: {
       sideStreamText: false,
     },
   };

You need the MSE module and the component that parses the manifest
type you want to side-stream text from. For example, to side-stream a
MPEG-DASH asset with embedded subtitles:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.dash";
   import "@castlabs/prestoplay/cl.tizen";

   const player = new clpp.Player('video', ...);

   player.open({
     source: {
       url: 'http://demo.cf.castlabs.com/media/tos_new/DEMO.mpd?v=2',
       type: clpp.Type.DASH,
     },
   });


MSE/EME-based playback
----------------------

PRESTOplay for web supports MSE/EME playback for all Tizen versions
2.3 and later. Older Tizen TVs, such as 2015 and 2016 models running
versions 2.3 and 2.4, implement an older version of the EME
specification ("0.1b"), which may limit some advanced DRM features
compared to modern EME implementations. The current level of support
is enough for most common use cases.

For MSE/EME-based playback on Tizen, don't include or use the native
Tizen component:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.dash";

   const player = new clpp.Player('video', ...);

   player.open({
     source: {
       url: 'http://demo.cf.castlabs.com/media/tos_new/DEMO.mpd?v=2',
       type: clpp.Type.DASH,
     },
     // ...
     drm: {
       // ...
     },
   });


Recommendations
---------------

We recommend MSE-based playback on older Tizen platforms whenever
possible, to go beyond the native player's limitations and access the
full set of features PRESTOplay for web provides. For Smooth Streaming
content, though, native playback performs better, since patching
Smooth Streaming media segments for MSE compliance in JavaScript can
add significant overhead on older Tizen TVs with limited computing
resources.


DRM
---

According to the specifications, older Tizen TVs support PlayReady and
Widevine Modular from Tizen version 2.4 onward. Based on our tests,
PlayReady-based DRM playback provides the most reliable support, and
we haven't confirmed that Widevine works properly on those versions.
If you target older Tizen TVs, we strongly recommend PlayReady or
multi-DRM protection for your assets.


## web/subtitles

Subtitles
*********

PRESTOplay web SDK text-track support. Parsers: TTML, SMPTE-TT, IMSC1,
WebVTT, SubRip (SRT). Displayers: HTML (rich styling, consistent
cross-browser) and native (browser built-in). Also covers side-loaded
tracks and CEA-608 captions.

To render cues, install a text displayer. The HTML text displayer
("HtmlTextDisplayer") is recommended: it handles complex layouts and
styling, and keeps rendering consistent across platforms.

   import "@castlabs/prestoplay/cl.htmlcue";

Without the HTML Cue module, the player falls back to the native text
displayer based on the capabilities of the browser, which may have
varying levels of support for more complex styling and layouts.


Text parsers
============


TTML, SMPTE-TT, and IMSC1
-------------------------

The TTML module adds support for Timed Text Markup Language (TTML) and
related profiles, including SMPTE Timed Text (SMPTE-TT) and Internet
Media Subtitles and Captions 1 (IMSC1) text or image subtitles. Import
the module before creating the player:

   import "@castlabs/prestoplay/cl.ttml";


Supported features
~~~~~~~~~~~~~~~~~~

Supported attributes:

* "tt:begin"

* "tt:end"

* "tt:region"

* "tt:style"

* "ttp:cellResolution"

* "ttp:frameRate"

* "ttp:subFrameRate"

* "ttp:frameRateMultiplier"

* "ttp:tickRate"

* "tts:backgroundColor"

* "tts:color"

* "tts:direction"

* "tts:displayAlign"

* "tts:origin"

* "tts:extent"

* "tts:fontFamily"

* "tts:fontSize"

* "tts:fontWeight"

* "tts:fontStyle"

* "tts:lineHeight"

* "tts:opacity"

* "tts:padding"

* "tts:textAlign"

* "tts:textOutline"

* "tts:textShadow"

* "tts:unicodeBidi"

* "tts:writingMode"

* "tts:zIndex"

* "smpte:backgroundImage"

SMPTE-TT and IMSC1 support covers bitmap images, such as PNG images
encoded in Base64. Position the bitmap images by enclosing them in a
region.


Support for legacy manifests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A well-designed TTML manifest defines a root container and vertical
cell definitions, which let the layout adjust to different sizes, such
as fullscreen mode. Some legacy manifests use pixels instead to define
region or font size, for example:

   <?xml version="1.0" encoding="utf-8"?>
   <tt
     xmlns="http://www.w3.org/ns/ttml"
     xmlns:tts="http://www.w3.org/ns/ttml#styling" xml:lang="en">
     <head>
       <styling>
         <style xml:id="s1"
           tts:fontSize="16px"
           tts:textAlign="center"/>
       </styling>
       <layout>
         <region xml:id="r1"
           style="s1"
           tts:displayAlign="center"
           tts:extent="512px 48px"
           tts:origin="48px 512px"/>
       </layout>
     </head>
     <body>
       <div xml:lang="en">
         <p begin="00:00:00.000000" end="00:00:10.000000" region="r1">
           Lorem ipsum
         </p>
       </div>
     </body>
   </tt>

For manifests like this, provide hints to the parser:

   const playerConfig = {
     // ...
     ttml: {
       containerWidth: 640,
       containerHeight: 480,
       fontSizeRadix: 16,
     },
   };

"containerWidth" and "containerHeight" convert a region size into
percentages. In this example, the "r1" region's width becomes "80%"
and its height becomes "10%"; its x-position becomes "80%" and its
y-position becomes "10%".

"fontSizeRadix" converts a font size into "em". In this example, the
cue font size becomes "1em". The HTML displayer then adjusts the
parent font size based on the video size. See "TextStyleConfiguration"
for details. Cues sized this way are responsive.


SMPTE-TT over HLS
-----------------

HTTP Live Streaming (HLS) doesn't support SMPTE-TT natively. Harmonic
proposed an extension to the HLS specification to work around this,
described in SMPTE-TT Embedded in ID3 for HTTP Live Streaming. The
HlsSmpte plugin implements this extension. It extends the TTML parser
and works exclusively on Safari with native HLS playback — it has no
effect on the MSE-based player.

To use it:

1. Import the TTML module:

      import "@castlabs/prestoplay/cl.ttml";

2. Import the HLS-SMPTE module:

      import "@castlabs/prestoplay/cl.hlssmpte";

3. Enable the "config.hlssmpte.patchMetadataTrack" flag if recent
   Safari versions fail to create the metadata track on load. As a
   workaround, the plugin briefly switches to another audio track and
   back to force Safari to create it. This flag is opt-in rather than
   default because the workaround requires at least two audio tracks
   and causes an audible track switch.

4. Adjust "config.hlssmpte.timestampOffset" if cues are time-shifted.

5. Provide placeholder text tracks using "config.remoteTextTracks".
   Each placeholder must define "kind", "language", "mimeType", and an
   optional "label". Omit "url" — the HlsSmpte plugin injects cues
   from the metadata track. The language code must match the metadata
   track's language codes, and the MIME type must be "text/vtt".

In the example below, "url" is omitted from each placeholder because
cues are delivered through the metadata track; the placeholders are
still needed to expose the language options.

   <link rel="stylesheet" href="./clpp.styles.css">
   <video id="video" width="640" height="360" controls crossorigin="anonymous"></video>
   <script type="module">
     import { clpp } from "@castlabs/prestoplay";
     import "@castlabs/prestoplay/cl.ttml";
     import "@castlabs/prestoplay/cl.htmlcue";
     import "@castlabs/prestoplay/cl.hlssmpte";

     const player = new clpp.Player('video', { });

     player.open({
       source: '...',
       hlssmpte: {
         patchMetadataTrack: true
       },
       htmlcue: {
         stretchSmpteImage: true
       },
       remoteTextTracks: [
         {
           kind: 'subtitles',
           language: 'ara',
           mimeType: 'text/vtt',
           label: 'Arabic'
         },
         {
           kind: 'subtitles',
           language: 'eng',
           mimeType: 'text/vtt',
           label: 'English'
         }
       ]
     });
   </script>


WebVTT and SubRip
-----------------

The VTT module adds support for WebVTT subtitles and SubRip (SRT)
files. Files with the "text/srt", "application/x-subrip", or
"text/plain" MIME type are converted to WebVTT internally. Import the
module before creating the player:

   import "@castlabs/prestoplay/cl.vtt";


Supported features
~~~~~~~~~~~~~~~~~~

* Inline text formatting

* Voice spans

* Ruby characters

* Text direction

* Text alignment

* Positioning

* Size

* Regions

* Embedded styles


SubRip (SRT) subtitles
~~~~~~~~~~~~~~~~~~~~~~

SRT files are usually side-loaded next to the stream. Import the VTT
module and add the file as a remote text track with the "text/srt"
MIME type:

   import { clpp } from "@castlabs/prestoplay";
   import "@castlabs/prestoplay/cl.mse";
   import "@castlabs/prestoplay/cl.dash";
   import "@castlabs/prestoplay/cl.vtt";

   const player = new clpp.Player("video", {});

   await player.open({
     source: "https://testcontent.castlabs.com/QA/tos_1080_clear/manifest.mpd",
     remoteTextTracks: [
       {
         url: "https://demo.cf.castlabs.com/media/TOS/TOS-ml.srt",
         mimeType: "text/srt",
         kind: "subtitles",
         language: "mal",
         label: "Malayalam",
       },
     ],
     preferredTextLanguage: "mal",
   });

"preferredTextLanguage" selects the track when playback starts. To
switch tracks later, use the "TrackManager" (see Tracks and
languages).

The SRT conversion has these requirements and limitations:

* The file must be UTF-8 encoded.

* Each cue must start with a numeric identifier, followed by a
  timestamp line in the "00:00:23,000 --> 00:00:24,500" format and the
  cue text. The player drops cues without an identifier.

* The player removes HTML formatting tags such as "<i>" and "<b>" from
  the cue text, so cues render as plain text.

The SRT subtitles sample
(https://github.com/castlabs/prestoplay-web-code-samples/blob/main/examples/subtitles/srt.html)
plays a stream with side-loaded SRT subtitles.


Side-loaded remote text tracks
==============================

Use "config.remoteTextTracks" to add side-loaded ("sidecar") subtitle
files that aren't present in the manifest. Each entry follows
"RemoteTextTrack", and "mimeType" must match a format whose module is
imported, for example "text/vtt" or "text/srt" with the VTT module.

Note:

  With MSE playback, side-loaded text tracks are only supported for
  video on demand (VOD). Adding them to a live stream fails with the
  "CANNOT_ADD_EXTERNAL_TEXT_TO_LIVE_STREAM" error.

   <link rel="stylesheet" href="./clpp.styles.css">
   <video id="video" width="640" height="360" controls crossorigin="anonymous"></video>
   <script type="module">
     import { clpp } from "@castlabs/prestoplay";
     import "@castlabs/prestoplay/cl.mse";
     import "@castlabs/prestoplay/cl.vtt";
     import "@castlabs/prestoplay/cl.htmlcue";

     const player = new clpp.Player('video', { });

     player.open({
       source: '...',
       remoteTextTracks: [
         {
           url: 'https://example.com/subtitles/en.vtt',
           kind: 'subtitles',
           language: 'eng',
           mimeType: 'text/vtt',
           label: 'English'
         },
         {
           url: 'https://example.com/subtitles/es.vtt',
           kind: 'subtitles',
           language: 'spa',
           mimeType: 'text/vtt',
           label: 'Spanish'
         }
       ]
     });
   </script>


Text displayers
===============


HTML displayer
--------------

The HTML displayer renders text cues using the HTML surface, with rich
styling capabilities and consistent results across browsers. It has
strong support for rendering parsed TTML, SMPTE-TT, IMSC1, WebVTT, and
SRT cues.

To use it:

1. Add the PRESTOplay default styles to your page:

      <link rel="stylesheet" href="clpp.styles.css">

2. Import the HTML Cue module:

      import "@castlabs/prestoplay/cl.htmlcue";

The HTML text displayer is used by default once
"@castlabs/prestoplay/cl.htmlcue" is imported. Set "enableHtmlCue" to
"false" in the player configuration to change this.

   <link rel="stylesheet" href="clpp.styles.css">
   <video id="video" width="640" height="360" crossorigin="anonymous" controls></video>
   <script type="module">
     import { clpp } from "@castlabs/prestoplay";
     import "@castlabs/prestoplay/cl.mse";
     import "@castlabs/prestoplay/cl.dash";
     import "@castlabs/prestoplay/cl.ttml";
     import "@castlabs/prestoplay/cl.vtt";
     import "@castlabs/prestoplay/cl.htmlcue";

     const player = new clpp.Player('video', {});

     player.open({
       source: '//demo.cf.castlabs.com/media/prestodash/Manifest.mpd'
     });
   </script>


Styling
~~~~~~~

Styles apply in this order, from lowest to highest priority:

1. Player styles

2. Website styles

3. Embedded styles

4. Text style options

Player styles come from "clpp.styles.css" and are required — they
provide default styles for text cues and regions.

Override the default styles with your own stylesheet by extending the
".clpp-text-container", ".clpp-text-cue", or ".clpp-text-cue-region"
classes. Website styles take priority over default styles.

A text track can contain embedded styles, which take priority over
website and default styles.

Text style options, set in the player configuration or through
"player.getTextDisplayer()", take priority over embedded, website, and
default styles. Use these to let your users customize the look and
feel of subtitles. The subtitle text styling sample
(https://github.com/castlabs/prestoplay-web-code-samples/blob/main/examples/subtitles/text_style.html)
sets the font, color, background, and edge style through text style
options.


Font size
~~~~~~~~~

The HTML displayer adjusts a base font size to the container size for
responsive design. By default, the font size is 7% of the container
height. Adjust it in the player configuration:

   const playerConfig = {
     // ...
     textStyle: {
       fontSizePercent: 0.03
     }
   };


Native text displayer
---------------------


Styling
~~~~~~~

Style text cues using text style options in the player configuration:

   const playerConfig = {
     // ...
     textStyle: {
       backgroundColor: 'rgba(207, 0, 15, 0.75)',
       fontFamily: 'monospace',
       fontColor: 'blue',
       fontSize: '1.2em',
       edgeColor: 'green',
       edgeType: clpp.text.EdgeType.DROP_SHADOW
     }
   }

Or style cues on the fly through a text displayer instance:

   player.getTextDisplayer().setFontColor('blue');

Native text-cue styling has some constraints:

* It requires Edge 19 or later.

* Background color and opacity are configurable on browsers other than
  Safari (macOS/iPadOS/iOS) and Chrome (macOS).

Use the HTML displayer to style text cues consistently across all
supported browsers.


CEA-608 captions
================

PRESTOplay for web supports CEA-608 captions, the legacy
closed-captioning standard embedded directly in the video signal. The
caption parser requires "mux.js" (version 5.7.0 or later) available in
the global scope:

   import * as muxjs from "mux.js";
   window.muxjs = muxjs;

See Components for the full "mux.js" installation steps.


## web/thumbnails

Thumbnails
**********

Web thumbnails plugin. Supports DASH, HLS, single image, grid/sprite,
WebVTT, and BIF formats. Automatic mode detection and preloading.

Review Thumbnails first for shared thumbnail formats, manifest
signaling, and authoring patterns.


Installation
============

Import the thumbnails plugin:

   import "@castlabs/prestoplay/cl.thumbnails";

For DASH and HLS streams with embedded thumbnails, the plugin works
automatically with no additional configuration. For other formats,
provide a configuration object when loading content.


Configuration
=============

Thumbnail formats are distinguished by modes. The plugin can infer the
mode from the file extension and configuration fields, or you can set
it explicitly.


Single image mode
-----------------

One image file per thumbnail:

   player.open({
     thumbnails: {
       mode: 'SINGLE',
       url: 'https://example.com/thumbs/$index$.jpg',
       duration: 5,
       templateKey: '$index$'
     }
   });


Grid image mode
---------------

Multiple thumbnails in a single sprite image, reducing the number of
HTTP requests:

   player.open({
     thumbnails: {
       mode: 'GRID',
       url: 'https://example.com/$index$_7.jpg',
       duration: 10,
       gridSize: '10x10',
       templateKey: '$index$'
     }
   });


WebVTT mode
-----------

Thumbnails defined in a WebVTT file with cues containing URLs and
timing:

   player.open({
     thumbnails: {
       mode: 'WEBVTT',
       url: 'https://example.com/thumbs.vtt'
     }
   });


BIF mode
--------

Binary Image Format, commonly used for Roku devices:

   player.open({
     thumbnails: {
       mode: 'BIF',
       url: 'https://example.com/thumbs.bif'
     }
   });


Usage
=====


Basic usage
-----------

Get the thumbnails plugin from the player and retrieve a thumbnail for
a specific time:

   const thumbPlugin = player.getPlugin(clpp.thumbnails.ThumbnailsPlugin.Id);

   const thumbnail = await thumbPlugin.get(60); // Thumbnail at 60 seconds
   const thumbElement = thumbnail.element(160, 90); // Scale to 160x90 pixels
   document.getElementById('thumbnail-container').appendChild(thumbElement);

The "element()" method returns a styled "div" with the thumbnail as a
background image, handling grid positioning and scaling automatically.


Seek-bar preview
----------------

Seek-bar thumbnail preview. Calculate time from mouse position, call
"thumbPlugin.get(position)", append "thumbnail.element()" to a
container.

   const seekbar = document.getElementById('seekbar');
   const thumbContainer = document.getElementById('thumbnail-preview');
   const thumbPlugin = player.getPlugin('thumbnails');

   seekbar.addEventListener('mousemove', async (event) => {
     const rect = seekbar.getBoundingClientRect();
     const percent = (event.clientX - rect.left) / rect.width;
     const position = percent * player.getDuration();

     try {
       const thumbnail = await thumbPlugin.get(position);
       const thumbElement = thumbnail.element(160, 90);

       thumbContainer.innerHTML = '';
       thumbContainer.appendChild(thumbElement);
       thumbContainer.style.left = event.clientX + 'px';
       thumbContainer.style.display = 'block';
     } catch (error) {
       thumbContainer.style.display = 'none';
     }
   });

   seekbar.addEventListener('mouseleave', () => {
     thumbContainer.style.display = 'none';
   });

The thumbnails sample
(https://github.com/castlabs/prestoplay-web-code-samples/blob/main/examples/thumbnails/thumbnails.html)
is a runnable page with a seek-bar preview for a DASH stream.


Custom styling
--------------

For more control over rendering, access the raw image element and
thumbnail properties:

   const thumbnail = await thumbPlugin.get(position);

   await thumbnail.load();
   const img = thumbnail.raw(); // Raw HTMLImageElement

   // Thumbnail properties
   console.log(thumbnail.width);    // Width in pixels
   console.log(thumbnail.height);   // Height in pixels
   console.log(thumbnail.time);     // Start time in seconds
   console.log(thumbnail.duration); // Duration in seconds
   console.log(thumbnail.src);      // Image source URL

   // Grid-specific properties
   console.log(thumbnail.x); // X coordinate in the grid image
   console.log(thumbnail.y); // Y coordinate in the grid image


Preloading
==========

Preloading downloads thumbnails in advance. Configure as array of step
values (seconds). Steps execute sequentially, coarse to fine.

   player.open({
     thumbnails: {
       mode: 'SINGLE',
       url: 'https://example.com/$index$.jpg',
       duration: 5,
       preload: [300, 60, 5]
     }
   });

With this configuration, the plugin creates three downloaders:

1. Downloads a thumbnail every five minutes (300 seconds)

2. When the first completes, downloads one every minute

3. When the second completes, downloads one every five seconds

Each downloader pauses during video buffering to prioritize playback.
To force preloading during buffering, use the object form:

   player.open({
     thumbnails: {
       preload: [
         { step: 300, preloadWhileBuffering: true },
         60,
         5
       ]
     }
   });

Note: Preloading during buffering may compete with video segment
downloads. Use it carefully.

Preloading is automatically disabled for live content.


Platform-specific notes
=======================


Safari and HLS Image Media Playlist
-----------------------------------

HLS Image Media Playlist is not supported when using Safari's native
HLS engine. To enable support, switch to the MSE-based engine:

   const player = new clpp.Player('vid', {
     streaming: {
       preferNativeHlsOnSafari: false
     }
   });


Smart TVs and large grid images
-------------------------------

Some smart TVs may not correctly process very large grid images.
Unexpected downscaling has been observed on certain Hisense and
Philips TV models for images larger than approximately 10,000 x 10,000
pixels. Splitting the grid into multiple smaller images avoids this
issue.


## web/tracks

Tracks and languages
********************

Audio and text track/language selection for PRESTOplay web SDK.


Initial language selection
==========================

Set the initial audio and text tracks by language. Setting
"preferredTextLanguage" also enables subtitles for the session:

   player.open({
     source: 'https://example.com/manifest.mpd',
     preferredAudioLanguage: 'en',
     preferredTextLanguage: 'fr',
   });

Pass an array to define fallback languages. The player selects the
first language in the list that is available:

   player.open({
     source: 'https://example.com/manifest.mpd',
     preferredAudioLanguage: ['fr', 'en'],
     preferredTextLanguage: ['fr', 'en'],
   });


Switching tracks during playback
================================

To list or switch audio, text, and video tracks after playback starts,
use "Player.getTrackManager" to access the "TrackManager".


## web/without-a-bundler

Without a bundler
*****************

If you're loading modules via script tags instead of a bundler,
include the SDK scripts in the "<head>":

   <html>
     <head>
       <script src="node_modules/@castlabs/prestoplay/cjs/cl.core.js"></script>
       <script src="node_modules/@castlabs/prestoplay/cjs/cl.mse.js"></script>
       <script src="node_modules/@castlabs/prestoplay/cjs/cl.dash.js"></script>
     </head>
     <body>
       <div id="container">
         <video id="video" width="640" height="360"></video>
       </div>
     </body>
   </html>