# Dolby OptiView Player

> Dolby OptiView Player (formerly THEOplayer) enables you to deploy cutting-edge video playback experiences on any device. Use the basic default UI, customize your player with Open Video UI's ready-made components, or build a complete UI from scratch with the chromeless player.

# OptiView Player

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Dolby OptiView Player is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [OptiView Player Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/web.md)

[For desktop and mobile web browsers, and smart TVs like Tizen and WebOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/web.md)

## [OptiView Player Android SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/android.md)

[For smartphones, tablets and Android TVs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/android.md)

## [OptiView Player iOS & tvOS SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ios.md)

[For iPhone, iPad and Apple TV](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ios.md)

## [OptiView Player React Native SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/react-native.md)

[For cross-platform apps targeting web, Android and iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/react-native.md)

## [OptiView Player Flutter SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter.md)

[For cross-platform apps targeting web, Android and iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter.md)

## [OptiView Player Chromecast SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/chromecast.md)

[For custom Chromecast receiver apps](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/chromecast.md)

## [OptiView Player Roku SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/roku.md)

[For Roku smart TVs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/roku.md)

---

# Changelog

These are the release notes for THEOplayer 11.0.0 and higher. For older versions, see:

* [Version 10.x](https://optiview.dolby.com/docs/theoplayer/v10/changelog/)
* [Version 9.x](https://optiview.dolby.com/docs/theoplayer/v9/changelog/)
* [Version 8.x](https://optiview.dolby.com/docs/theoplayer/v8/changelog/)
* [Version 7.x](https://optiview.dolby.com/docs/theoplayer/v7/changelog/)
* [Version 5.x and 6.x](https://optiview.dolby.com/docs/theoplayer/v6/changelog/)
* [Version 2.x, 3.x and 4.x](https://optiview.dolby.com/docs/theoplayer/v4/changelog/)

## 🚀 11.14.0 (2026/10/20)

### Web

#### ✨ Features

* Added experimental `player.recreateMediaSource()` to rebuild the media pipeline in place, for example after an external ad engine used the decoder on VIZIO.
* Added the `adSystem` property to the OptiView Live Streaming (THEOlive) `Endpoint` API.

#### ⚡ Improvements

* Improved the transitions of OptiView Ads between back-to-back ad breaks with different layouts, such as from a double box to an L-shape.
* Improved the startup time of OptiView Live Streaming DRM streams on Tizen by preferring PlayReady over Widevine when `contentProtection.preferredKeySystems` is not set.
* Improved the performance of the extraction of embedded CEA-608/708 closed captions in HLS and DASH streams.
* HLS variant streams that declare `CLOSED-CAPTIONS=NONE` are no longer scanned for embedded CEA-608/708 closed captions.
* Improved the startup time of DRM-protected HLS streams whose `EXT-X-KEY` or `EXT-X-SESSION-KEY` tags carry the PSSH in a base64 `data:` URI, which is now decoded directly instead of being requested over `fetch` or `XMLHttpRequest`.
* Improved CMCD reporting for Dolby Atmos.
* Made the list of subscribed OptiView Real-time Streaming (Millicast) broadcast events configurable through `connectOptions.events` (and `TheoLiveSource.webrtc.events` for OptiView Live Streaming WebRTC sources). The player always subscribes to the events it needs (`active`, `inactive`, `stopped`, `layers`, `migrate`). Optional events such as `viewercount` and `vad` are no longer subscribed by default; add them from the application when needed, e.g. `connectOptions: { events: ['viewercount'] }`.

#### 🐛 Issues

* Fixed an issue where the player could collapse to a height of 0 when playing an OptiView Ads source. If the size of the player is not determined by its parent element (for example, when only its width is set), the player now sizes to the intrinsic size of the video that is currently playing, either the content or the ad.
* Fixed an issue where TTML `begin` and `end` time expressions on an element inside a timed parent container (e.g. a `<p>` inside a `<div begin=...>`) were resolved as absolute media times instead of relative to the parent's begin, as required by the TTML specification. Fractional offset-time expressions such as `2.5s` are now also resolved exactly instead of being truncated to whole units.
* Fixed an issue where, after a Google IMA mid-roll, the content resumed at the wrong position, equal to the last ad's duration, on iOS Safari with `allowNativeFullscreen` enabled.
* Fixed an issue where the content kept playing after a blocking ad error when `blockContentIfAdError` is enabled.
* Fixed an issue where `fatalError()` on custom server-side ad integrations would not stop playback.
* Fixed an issue where CEA-608 caption rows could overlap, for example on a small player with a large `textTrackStyle.marginBottom` or on a player wider than 16:9. Captions now move only as far as needed to stay clear of the margins, and the text only gets smaller when the rows would otherwise overlap or not fit between the margins.
* Fixed an issue where seeking to the live point of an LL-HLS stream could cause the latency manager to stop adjusting the latency.

#### ⚠ Known Limitations

* When the size of the player is not determined by its parent element, the player keeps the intrinsic size of the content during OptiView Ads ad breaks that are played through Google IMA (VAST ads), rather than sizing to the ad.

### Android

#### ✨ Features

* Added support for OptiView Live Streaming (THEOlive) distributions protected with Castlabs DRMtoday Widevine.
* Added `src` and `srcType` properties to the OptiView Live Streaming (THEOlive) `Endpoint` API.
* Added `Player.errorObject`, which returns the last error that occurred for the current source as a `THEOplayerException`.

#### ⚡ Improvements

* Improved CMCD reporting for Dolby Atmos.
* Enable adjusting playback rate for low-latency HLS streams provided through OptiView Live sources.

#### 🐛 Issues

* Fixed an issue where casting a DRM-protected source to the OptiView Streaming (THEOplayer) CAF Chromecast receiver failed. The source's DRM configuration is now also sent under the `contentProtection` key, alongside `drm`.
* Fixed an issue where switching rendering targets during playback could cause a decoding error.
* Fixed a `ClassCastException` when creating a `THEOplayerView` in Android Studio's layout editor or a Compose preview.
* Fixed an issue where `TextTrackCue.content` was malformed due to `endTime` being `Double.POSITIVE_INFINITY` for ID3 cues.

### iOS

#### ✨ Features

* Added support for OptiView Live Streaming (THEOlive) distributions protected with Castlabs DRMtoday FairPlay.
* Added `src`, `srcType`, `provider` and `adSystem` properties to the OptiView Live Streaming (THEOlive) `EndpointAPI`.
* Added `errorObject` instance property to `THEOplayer`, which returns the player error for the current source as a `THEOError`.

#### ⚡ Improvements

* Exposed the getter for `SourceLatencyConfiguration.targetOffset`.
* Errors caused by Apple's frameworks now keep Apple's original error as their `cause`, in a `GenericSwiftError`, and their message includes Apple's error domain, code and description. `GenericSwiftError.name` is now `Swift error`.
* The error `AVPlayerItem failed to play to end time.` now includes Apple's error in its message, and keeps Apple's error as its `cause`.
* A failed DRM key request is now always reported as a `ContentProtectionError`, together with a `ContentProtectionErrorEvent`. When a custom DRM integration reports an error for a certificate or license response, the error includes that response's URL, HTTP status, status text and body.
* The error `Something went wrong while trying to play the content.` now includes Apple's error in its message, and keeps Apple's error as its `cause`.
* Improved CMCD reporting for Dolby Atmos.
* The OptiView Player iOS and tvOS SDKs and their integrations are now built with Xcode 26.6 (Swift 6.3) instead of Xcode 26.3 (Swift 6.2.3). This is a build tool update only: the public API, SDK behavior and the minimum supported iOS and tvOS version (15.0) are unchanged. This change is backward compatible with apps built with Xcode 26.3.
* The stall error (`Stalled for more than 10 seconds with N errors.`) now includes the newest fatal error from Apple's error log in its message, and keeps that error as its `cause`.
* Network errors (6000) now include the URL and HTTP status of the request that failed, and Apple's error in their message, and keep Apple's error as their `cause`.
* Errors now use the most precise error code for Apple's error, instead of 5003 for most failures: a playlist that can't be parsed or isn't HLS gives 4002 (`MANIFEST_PARSE_ERROR`), a timeout gives 6001 (`NETWORK_TIMEOUT`), an HTTP or other connection error gives 6000 (`NETWORK_ERROR`), broken media data gives 5002 (`MEDIA_DECODE_ERROR`), an unsupported format gives 5000 (`MEDIA_NOT_SUPPORTED`), and a media services reset or running out of memory gives 5005 (`MEDIA_INTERNAL_ERROR`). Every 6000 error is now a `NetworkError`.
* DRM errors now use the code of the step that failed instead of 7000: 7005 for the certificate, 7004 for the content ID or the license request, 7007 for getting the license, and 7008 when the license isn't accepted. The message says which step failed, for example `Content key error: Failed to get the license.`
* `ErrorEvent.error`, `ErrorEvent.errorObject.message` and `THEOplayer.error` now contain the same, more detailed message.

#### 🐛 Issues

* Fixed a runtime warning on iOS 27 related to the orientation API.
* Fixed casting DRM-protected OptiView Live Streaming (THEOlive) channels to Chromecast CAF receiver from iOS.
* Fixed an issue where one failure could send two or more fatal `ErrorEvent`s. Only the first fatal error for a source is sent now. A network error the player recovers from no longer sets `THEOplayer.error`.
* Fixed an issue where the `ErrorEvent` for a source that failed to load had no `errorObject`. It now has one, with Apple's error as its `cause`.
* Fixed an issue where a failed FairPlay key request was reported as error 7000 without the reason. The error now includes Apple's or the DRM integration's error in its message, and keeps that error as its `cause`.
* Fixed an issue where the FairPlay certificate and license requests made by the SDK accepted a response with HTTP status 400 or higher. The request now fails right away, and the `ContentProtectionError` includes the URL, HTTP status and response.
* Fixed an issue where a playback error on the Chromecast receiver was reported with the unclear message `CC died` and without an error object. It is now reported as error 5001 (`MEDIA_LOAD_ERROR`) with a message that describes the problem, and the Cast details (idle reason and media session ID) are available in the error object's `cause`.

#### 👎 Deprecations

* `ErrorEvent.error` is deprecated, use `ErrorEvent.errorObject.message` instead.
* `ErrorEvent.errorObject` will become non-optional in a future major release.
* `THEOplayer.error` is deprecated, use `THEOplayer.errorObject?.message` instead.

### Chromecast CAF

#### ⚡ Improvements

* Improved CMCD reporting for Dolby Atmos.

### Roku

#### ✨ Features

* The MediaKind connector's session beacon error event now includes all available response details.
* Added support for program end tags for MediaKind streams, filling in previously missing program information for the previous program.

#### ⚡ Improvements

* Improved CMCD reporting for Dolby Atmos.

## 🚀 11.13.0 (2026/10/07)

### Web

#### ✨ Features

* Added `ABRConfiguration.preferredMaximumResolution`, which allows to dynamically cap the resolution selected for OptiView Real-time streams.
* Added support for using `SourceAbrConfiguration.restrictToPlayerSize` with OptiView Real-time streams.

#### ⚡ Improvements

* The player now always wraps its media elements in container elements inside the player element, instead of only for OptiView Ads sources.

  * The `theo-ads-sgai-container`, `theo-ads-sgai-content-player` and `theo-ads-sgai-ad-player` classes are still applied while an OptiView Ads source is active.
  * When using `ChromelessPlayer`, CSS or scripts that expect the `<video>` element to be a direct child of the player element (for example `.my-player > video`) should use a descendant selector instead.

* Added the `theoLive.discoveryUrl` and `theoLive.discoveryUrls` player configuration options to the public API, to override the discovery URLs that are tried before the built-in OptiView Live Streaming discovery URLs. See [our guide on discovery URLs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/theolive/discovery-urls.md) for more information.

* OptiView Live Streaming (THEOlive) channels are now discovered through the V2 discovery API first, with automatic fallback to the legacy API for channels not yet available on V2 (one extra request before playback starts). Set `theoLive.discoveryUrl` to pin the discovery API and skip the fallback. See [our guide on discovery URLs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/theolive/discovery-urls.md) for more information.

* `THEOplayer.features` now lists the features that are actually loaded, in a fixed order.

#### 🐛 Issues

* Fixed an issue where transient network errors on OptiView Live media requests were retried for less than a second before falling back to HLS. Such requests are now retried for about five seconds, and the failure count starts over after each successful request.
* Fixed `currentProgramDateTime` advancing too quickly or exposing ad timestamps during OptiView Ads interstitials. When the ad break does not replace content, `currentProgramDateTime` is `undefined` during the ad break.
* Fixed an issue where a Widevine license request rejected by EZDRM because the browser's CDM is revoked was reported as a generic `CONTENT_PROTECTION_LICENSE_ERROR` (7007). It is now reported as `CONTENT_PROTECTION_DEVICE_REVOKED` (7013), with the CDM version and EZDRM's reason in the error message and the EZDRM response body in `error.response`.
* Fixed an issue where seeking past multiple individually scheduled Google IMA VAST ad breaks would play all of them back-to-back. Only the first seeked-over ad break is played now, restoring the expected behavior from before version 11.9.0.
* Fixed an issue where a Google IMA VAST post-roll could play in the background, detached from the player controls, after seeking past multiple ad breaks of which the last one was a non-linear VAST ad.
* Fixed an issue where delayed OptiView Ads watermark responses could leave overlapping image overlays visible after seeking.
* Fixed an issue where a low-latency HLS stream stayed behind the live edge after playback was paused and resumed outside of the player, for example when the browser tab of a muted stream had been in the background, or from the picture-in-picture window.
* Fixed an issue where frozen OptiView Live playback could unnecessarily switch to HLS instead of first attempting to recover with a seek to live. Streams that stop receiving data now switch to another endpoint sooner.
* Fixed an issue where OptiView Ads would not play any ad break after the first one when ad breaks are signalled through ID3 or EMSG cues.

### Android

#### ✨ Features

* Added `InterceptableHTTPResponse.observeBody()` and `.observeChunk()` methods to inspect the HTTP response body without modifying it.
* Added `ChunkInterceptor.onEnd()`, which will be called after the last chunk of the HTTP response body has been received.

#### ⚡ Improvements

* OptiView Live Streaming (THEOlive) channels are now discovered through the V2 discovery API first, with automatic fallback to the legacy API for channels not yet available on V2 (one extra request before playback starts). Set `THEOLiveConfig.discoveryUrl` to pin the discovery API and skip the fallback. See [our guide on discovery URLs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/theolive/discovery-urls.md) for more information.
* The CMCD video codec now reports the codec that is actually decoded when a Dolby Vision stream falls back to its base layer.
* The Widevine service certificate provided by OptiView Live channel discovery will now be used when starting playback, saving the certificate request. An empty certificate from discovery no longer overrides one configured on the source.
* When provided, `KeySystemConfiguration.certificate` will now be applied as the Widevine service certificate for DRM playback.

#### 🐛 Issues

* Fixed an issue where the OptiView Ads integration did not dispatch `adimpression`, `adclicked` and `adtapped` events, and `adloaded` for VAST ads.
* Fixed an issue where a Widevine license request rejected by EZDRM because the device's CDM is revoked was reported as a generic `CONTENT_PROTECTION_LICENSE_ERROR` (7007). It is now reported as `CONTENT_PROTECTION_DEVICE_REVOKED` (7013), with the CDM version and EZDRM's reason in the error message and the license server's URL, status and response body on the `ContentProtectionException`.
* Fixed an issue where CMCD data was missing from HLS media segment requests when CMCD was reported through request headers, leaving those requests without session information.
* Fixed an issue where the player-level CMCD configuration was not forwarded to the Chromecast receiver when casting.
* Fixed an issue where TTML subtitles in fragmented MP4 (`stpp`) HLS streams were not rendered.
* Fixed the Learn more button not appearing during OptiView Ads VAST ads.

### iOS

#### ⚡ Improvements

* OptiView Live Streaming (THEOlive) channels are now discovered through the V2 discovery API first, with automatic fallback to the legacy API for channels not yet available on V2 (one extra request before playback starts). Set `THEOliveConfiguration.discoveryUrl` to pin the discovery API and skip the fallback. See [our guide on discovery URLs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/theolive/discovery-urls.md) for more information.
* OptiView Live Streaming (THEOlive) sources now use the FairPlay certificate returned by the discovery response instead of downloading it from the certificate URL. Added `certificate` to `KeySystemConfiguration` and `FairPlayDRMConfiguration` to provide the FairPlay certificate directly; when it is missing or empty, the certificate URL is still used. A non-empty certificate is used as-is, also with a custom `ContentProtectionIntegration`: its `onCertificateRequest` and `onCertificateResponse` handlers are then not called. A certificate from the discovery response takes precedence over one configured on the source.

#### 🐛 Issues

* Fixed an issue where the OptiView Live HESP fallback cooldown was not started, resulting in the player recovering on HESP instead of HLS.
* Fixed an issue in OptiView Live Streaming (THEOlive) where HLS playback would stay stalled, instead of falling back to another endpoint after 15 seconds without progress.
* Fixed an issue where setting a new HLS source containing an IMA preroll, while in PiP presentation mode, would close PiP.
* Fixed an issue where the source-level CMCD configuration was forwarded to the Chromecast receiver under a key the THEOplayer receivers do not recognise, so casting never reported CMCD for the source.

### Chromecast CAF

#### ✨ Features

* Added CMCD (Common Media Client Data) event-mode reporting to the Chromecast CAF receiver. When the sender's player or source configuration contains a `cmcd` configuration, the receiver reports its own CMCD session (platform `theoplayer-caf`), including the Dolby Vision and Dolby Atmos capability and active codec fields.

### Roku

#### ✨ Features

* Added the x-tv3-user-engagement-data header to all MediaKind client beacons, including Base64-encoded session identifiers and the current playing, paused, or buffering state.
* Added program boundary events for MediaKind streams.
* Added support for Castlabs DRMtoday Widevine configuration (merchant/userId/sessionId), including on OptiView Live sources.

#### 🐛 Issues

* Added X-LocationDetails to MediaKind DRM and beacon requests when client location details are configured, together with an MKUtils helper for encoding location details.
* Fixed issue where stall detection could fire during OptiView live fallback if endpoint selection took a long while.
* Fixed an issue where a Widevine service certificate configured in `contentProtection.widevine.certificate` (or delivered by OptiView Live discovery) made playback fail with a `setServiceCertificate` DRM error. The certificate is now handed to the Roku CDM as a hex string; base64 and hex certificates are both accepted.

## 🚀 11.12.1 (2026/09/25)

### Android

#### 🐛 Issues

* Fixed an application crash when starting playback of an OptiView Ads-enabled source.

## 🚀 11.12.0 (2026/09/22)

### Web

#### ✨ Features

* Added support for restricting OptiView Real-time Streaming playback to specific accounts through `millicast://<streamAccountId>` source domain entries and implicitly allowed OptiView delivery domains.

#### ⚡ Improvements

* The Widevine service certificate and the FairPlay certificate provided by OptiView Live channel discovery are now used when starting playback, saving the certificate request. An empty certificate from discovery no longer overrides one configured on the source.
* Improved the transition into an OptiView Ads double box ad break that directly follows another ad break, and out of one that ends right after it began.

#### 🐛 Issues

* Fixed an issue where Google DAI streams could fail to play or report server-side ad beacons when cast to Chromecast.
* Fixed ABR not switching down to a lower quality when a segment download timed out while a response interceptor was registered, which could cause playback to stall while retrying the same quality and segment indefinitely.
* Fixed an issue on iOS Safari where the native `ended` event of a Google IMA ad played in the shared video element was reported as the content's `ended` event.
* Fixed an issue where the `textTrackStyle` margins were ignored for CEA-608 captions.
* Fixed an issue where an endpoint in an OptiView Live stream that fails the player's license check could prevent the player from falling back to a different endpoint.
* Fixed `player.autoplay = true` when the page is in the background. The player now waits until the page is brought to the foreground before attempting autoplay.
* Fixed an issue where a "Cannot read properties from undefined" error was thrown when attempting to play an OptiView Real-time stream when this feature isn't enabled in the player's license. The player now correctly reports a `LICENSE_INVALID_SOURCE` error instead.
* Fixed an issue where Dolby Vision (HEVC) content did not play on Edge for Windows when `preferredKeySystems` was omitted.
* Fixed an issue where the player would fire an early `playing` event with `PlayingEvent.currentTime = Infinity` when seeking to live on a paused HLS livestream. The `playing` event now fires after the seek completes, with the resolved `currentTime`.
* Fixed an issue where an OptiView Ads double box ad break would get stuck when closely followed by an L-shape ad break.

#### 👎 Deprecations

* Deprecated `allowMixedContent` on the `PlayerConfiguration` API. Use `network.allowMixedContent` instead.

### Android

#### ✨ Features

* Added support for restricting OptiView Real-time Streaming playback to specific accounts through `millicast://<streamAccountId>` source domain entries and implicitly allowed OptiView delivery domains.

#### 🐛 Issues

* Fixed an issue where the CMCD-States payload could grow without bound when an OptiView Live channel was repeatedly falling back, causing CDN log parsing to fail. At most 20 states are now shipped per request (the oldest are dropped and the number of dropped states is reported), and reason and error strings are limited to 128 characters.
* Fixed an issue where TTML subtitle cues without their own begin attribute inside a timed `<div>` were not shown.
* Fixed an issue where ABR could select the lowest quality at startup of a DASH or HLS stream on a fast network or with a saved bandwidth estimate, when the initial request stayed open for more than 100 ms.

### iOS

#### ✨ Features

* Added support for restricting OptiView Real-time Streaming playback to specific accounts through `millicast://<streamAccountId>` source domain entries and implicitly allowed OptiView delivery domains.

#### 🐛 Issues

* Fixed an issue where Picture-in-Picture would exit after an OptiView Ads double-box ad break that was presented inside the Picture-in-Picture window.
* Fixed missing or duplicate play events when explicitly starting or resuming Google IMA advertisements, and incorrect paused state while a pre-roll is pending.
* Fixed an issue in OptiView Ads where ad audio and UI would show over the content during an `LSHAPE_CONTENT` ad break.
* Fixed an issue in OptiView Ads where an ad break starting within 5 seconds after a double-box ad break would end prematurely.
* Fixed a rare crash when destroying the player while an OptiView Ads ad break was shown in picture-in-picture.

### Roku

#### ✨ Features

* The MediaKind connector can now send the X-TV3-Forwarded header on license and beacon requests.
* CMCD states now report what triggered them: a customer API call, a player-internal decision or a media element event.

#### 🐛 Issues

* Fixed an issue with the MediaKind Connector config where `debug` was not actually optional. Also added support for the `cdns` property to be the `cdns` object from the MediaKind roll call response. Also defaulted `enableCSB` to true.

## 🚀 11.11.0 (2026/09/10)

### General

#### ✨ Features

* Added the `THEO_LIVE_DISCOVERY_ERROR` (13004) error code, which is reported when an OptiView Live channel could not be played because the discovery request failed or returned an invalid response.

### Web

#### ✨ Features

* Added Google IMA SDK for webOS and Tizen to enable beacons and UI for serverside ads on LG and Samsung TVs.
* Added CMCD v2 buffer starvation reporting (`bs`, `bsa`, `bsd`), media start delay (`msd`) and media resume delay (`com.dolby.optiview-mrd`) to make tracking rebuffering easier.

#### 🐛 Issues

* Fixed an issue where playback would fail when the selected DRM key system (e.g. Widevine) failed after selection, instead of falling back to an alternative configured key system (e.g. PlayReady).
* Fixed an issue where latency management stayed disabled for low-latency HLS streams without an explicit `latencyConfiguration` on the source, such as the LL-HLS playback of an OptiView Live channel, causing playback to never catch up with the live edge.
* Fixed an issue where playback of a low-latency HLS stream could fail with an 'attempted to download an incomplete segment' error.
* Fixed an issue where the player would keep targeting the primary channel's latency after switching to the backup channel.
* Fixed an issue where an HLS stream with a Dolby Vision enhancement layer failed to play on webOS devices without Dolby Vision support, instead of falling back to its base layer.
* Fixed an issue where the CMCD session ID (sid) was not regenerated when a new source was set, so separate playback sessions were reported as one. A new session ID is now generated each time a source is set and stays stable for that source, including OptiView Live endpoint switches, fallbacks and OptiView Ads interstitials.
* Fixed an issue where an unnecessary FairPlay license request was sent on every quality switch when playing HESP content on Safari.
* Report fatal player errors to CMCD before the first media request.

### Android

#### 💥 Breaking Changes

* The Google IMA and Google DAI integrations now require `minSdk` 24 or higher, because the Google IMA SDK 3.40.0 dependency requires it. The core THEOplayer SDK still supports `minSdk` 23. Applications that use the Google IMA or Google DAI integration must raise their `minSdk` to 24.

#### 🐛 Issues

* Fixed a stray `pause` event being dispatched when switching between two back-to-back OptiView ad breaks.
* Fixed unbounded memory growth during OptiView Live Streaming playback when the network delivers data faster than the player consumes it, which could cause `OutOfMemoryError` crashes.
* Fixed a NullPointerException that could occur when Google IMA delivered a null AdMediaInfo to the ad player.
* Fixed an issue where the player would keep targeting the primary channel's latency after switching to the backup channel.
* Fixed an issue where Google DAI live streams could fail to start with a `MANIFEST_LOAD_ERROR` after a 15 second timeout, caused by a bug in Google IMA SDK 3.39.0. The Google IMA SDK dependency was updated to 3.40.0, which requires `minSdk` 24 or higher for applications that use the Google IMA or Google DAI integration.
* The `MANIFEST_LOAD_ERROR` that is dispatched when a Google DAI stream request fails now contains the original Google IMA `AdError` as its cause.
* Report fatal player errors through CMCD when they occur before the first media request.
* Fixed missing CMCD headers and playback state reporting on HLS segment requests for OptiView Live streams since 11.8.0.

### iOS

#### 🐛 Issues

* Fixed an issue where the CMCD channel name (`theo-cn`) reported the raw distribution ID. It is now only reported once the human-readable name is known, and is left unset until then rather than falling back to the ID.
* Fixed an issue where the player would keep targeting the primary channel's latency after switching to the backup channel.
* Fixed an issue where a seek that was cancelled by AVFoundation left the player stuck in the seeking state, so `player.seeking` stayed `true` and no `seeking` or `seeked` events were dispatched for any later seek. A seek issued before a player item exists now invokes its completion handler with an error instead of never calling back.
* Fixed an issue where the CMCD-States header could grow past CDN log limits: state reason and error strings are now capped at 128 characters, and when more than 20 states are pending the oldest are dropped and their count is reported on the first shipped state.
* Report fatal player errors through CMCD when they occur before the first media request.

### tvOS

#### 🐛 Issues

* Fixed an issue where a seek that was cancelled by AVFoundation left the player stuck in the seeking state, so `player.seeking` stayed `true` and no `seeking` or `seeked` events were dispatched for any later seek. A seek issued before a player item exists now invokes its completion handler with an error instead of never calling back.
* Fixed an issue where the CMCD-States header could grow past CDN log limits: state reason and error strings are now capped at 128 characters, and when more than 20 states are pending the oldest are dropped and their count is reported on the first shipped state.

### Chromecast

#### 🐛 Issues

* Fixed an issue where sources with erroring IMAGE-STREAM URLs would fail to play on Chromecast receiver apps.

### Roku

#### ✨ Features

* Added CMCD reporting of whether the device can present Dolby Vision and decode Dolby Digital Plus (EC-3), and of the video and audio codecs which are actually being decoded.

#### ⚡ Improvements

* Added the reason a playback state was entered to the reported CMCD state, so a session that restarted because an OptiView Live channel fell back to another stream can now be told apart from one that started normally, matching the other platforms.

#### 🐛 Issues

* Fixed an issue where a fatal error could be reported in the CMCD data without its error code or message, leaving the failure unclassifiable.
* Fixed an issue where adding an unsupported integration reported an unrelated error code and no error message.
* Fixed an issue where an HLS stream mixing Dolby Vision and SDR variants could fail to play on devices whose display output is SDR.
* Report fatal player errors through CMCD before the first media request.

## 🚀 11.10.2 (2026/09/03)

### Web

#### 🐛 Issues

* Fixed an issue where an unnecessary FairPlay license request was sent on every quality switch when playing HESP content on Safari.
* Fixed an issue where an OptiView Live stream could get stuck while starting up, showing a black screen for 15 seconds before falling back to its HLS stream.
* Fixed an issue where an OptiView Live stream continued without audio after it fell back to its HLS stream.

## 🚀 11.10.1 (2026/08/28)

### Web

#### 🐛 Issues

* Fixed an issue with OptiView Ads where only the first ad of an ad pod would play when the player was in native fullscreen or native picture-in-picture on iOS Safari.

## 🚀 11.10.0 (2026/08/27)

### Web

#### ✨ Features

* Added a 'c2pametadata' player event exposing raw C2PA metadata from ISOBMFF 'uuid' boxes in HLS and DASH streams, enabled through the 'c2paMetadata' source property.
* Added support for configuring `google.ima.AdsRenderingSettings.useStyledNonLinearAds` and `useStyledLinearAds` via `player.ads.googleIma.useStyledNonLinearAds` and `player.ads.googleIma.useStyledLinearAds`. When left `undefined`, the Google IMA SDK default is used.

#### 🐛 Issues

* Fixed an issue for DASH streams with no `SegmentTimeline` where the manifest would sometimes fail to load if the `Period` duration was an exact multiple of the segment duration.
* Fixed an issue where a scheduled Google IMA VAST ad would be requested twice, causing the ad server to return an empty VAST response (IMA error 303) for the second ad break.
* Fixed an issue where the content would briefly appear and play between consecutive Google IMA ad breaks scheduled at the same time offset.

### Android

#### 🐛 Issues

* Fixed an issue where removing a caching task before its initialization completed, for example right after the cache reported INITIALISED, would mark the task as EVICTED but leave the cached Media3 files and download entry on the device.
* Fixed an issue where an expired caching task would not clean up its offline DRM license data, and where removing a caching task could remove offline DRM sessions still used by another task caching the same content.
* Fixed an issue where playback of a fully cached source could select a rendition that was not cached, causing a source error or endless waiting during offline playback.

### iOS

#### ⚡ Improvements

* Improved error reporting specifically when playback fails to play to end time. In this case the `ErrorEvent` will ensure to contain an `errorObject`.

#### 🐛 Issues

* Fixed an issue where `bytesCached` and `bytes` properties would return 0 for cached sources pre 10.12.0
* Fixed an issue where the player would not exit `lShape` layout when an ad error was thrown. Note: the issue was observed specifically for `LSHAPE_CONTENT` and not `LSHAPE_AD`.
* Fixed an issue where the player would pause without dispatching a `PauseEvent` when pressing on "Learn more" during an ad break. This would result in unexpected state management when designing a player controls UI.

### Roku

#### ✨ Features

* Updated the AEP SDK to 1.3.1. This adds in the ability to set user consent for data collection and also the ability to set custom identities.

#### 🐛 Issues

* Fixed an issue where OptiView Live analytics reported uninterrupted playback sessions as never having started. The playing state is now reported throughout a session instead of only when playback changes state, matching the other platforms.
* Fixed an issue where the CMCD measured throughput was reported as zero before any throughput had actually been measured. The field is now omitted until a real measurement is available, matching the other platforms.
* Made live stall errors not report as fatal for Mux analytics. Also fixed an issue where a live stall would be incorrectly reported on a repeated timestamp.
* Fixed an issue where fatal playback errors were reported to OptiView analytics without an error code or message.
* Fixed issue where CMCD event mode would not activate for Google IMA SSAI streams.

## 🚀 11.9.1 (2026/08/22)

### Web

#### ⚡ Improvements

* Improved the content protection error when the CDM reports an output protection (HDCP) violation: instead of error 7012 with the generic 'Unknown CDM error' message, the player now reports error 7011 (CONTENT\_PROTECTION\_OUTPUT\_RESTRICTED) explaining that the required HDCP level cannot be guaranteed, e.g. because AirPlay screen mirroring, screen recording, screen sharing or a non-HDCP display is active. The error now also exposes the CDM's `systemCode`.

#### 🐛 Issues

* Fixed an issue where playback with Google IMA could stall indefinitely when a VMAP ad break resolved to an empty VAST response (VAST error 303). The player now dispatches a non-fatal `aderror` event and resumes content playback.
* Fixed an issue where playback of PlayReady-protected Dolby Vision content could fail on Microsoft Edge on Windows.
* Fixed an issue where a content protection error on a OptiView channel triggered several endpoint fallback attempts before surfacing a generic error. Content protection errors are now treated as non-recoverable and are surfaced immediately.

## 🚀 11.9.0 (2026/08/12)

### Web

#### ✨ Features

* Added support to the OptiView Ads break manifest for `double`, `lshape_ad`, `lshape_content` and `overlay` formats as well as device type support.
* Added the `adclicked` event, for the `csai`and `google-ima` CSAI ads integrations, for Google DAI ads (SSAI) and OptiView Ads (SGAI). It is dispatched when the user clicks on an ad clickthrough element.
* Added `network.useStreamingFetch` to the `PlayerConfiguration` API to explicitly disable consuming fetch responses as streams on devices with a broken streaming fetch implementation.
* Added CMCD reporting of whether the platform can decode Dolby Vision and Dolby Digital Plus (EC-3), and of the video and audio codecs which are actually being decoded.

#### ⚡ Improvements

* Ads preloading for Google IMA now works consistently for both VMAP ad schedules and individually scheduled VAST ads. When preloading is enabled (using `AdsConfiguration.preload`), VAST midrolls are fetched 8 seconds before their scheduled start time.

#### 🐛 Issues

* Fixed an issue where completed SGAI interstitials could be re-added and emit repeated interstitial events on live streams.
* Fixed an issue where PlayReady HLS key formats specified as a `urn:uuid:` were not recognized.
* Fixed an issue where playback would fail for Google DAI sources because CMCD headers on manifest requests would trigger CORS errors. CMCD now operates in event mode only for Google DAI sources.
* Fixed an issue where an ad scheduled after a non-linear Google IMA ad would never start, because Google IMA does not fire any events after LOADED when a non-linear ad is the last ad of its ads manager.
* Fixed an issue where the player could get stuck when starting playback of a new source with a Google IMA pre-roll ad, if the previous source also had a Google IMA pre-roll ad.
* Fixed an issue where a Google IMA pre-roll ad of a new source could start loading and playing immediately after changing the source, even when autoplay was disabled and the player was paused.

### Android

#### ✨ Features

* Added support to the OptiView Ads break manifest for `double`, `lshape_ad`, `lshape_content` and `overlay` formats as well as device type support.
* Added CMCD reporting of whether the device can decode Dolby Vision and Dolby Digital Plus (EC-3), and of the codecs of the video and audio formats fed to the decoders.
* Added `TheoLive.switchToHesp()`, which allows switching an OptiView Live stream back to HESP playback after it has fallen back to another format.
* Added `Player.getCurrentSource()`, which returns the `TypedSource` that is currently being played. The source is the same as expected in the existing `CurrentSourceChangeEvent`.

#### 🐛 Issues

* Fixed an issue where the `overrideLayout` property would incorrectly override the `lshape_content` layout of an OptiView Ads ad break.
* Fixed an issue where OptiView Ads PTS breaks might not play.
* Fixed an issue where the first playback of a DRM-protected stream could fail on a device that had not played DRM-protected content before, and would keep failing when retried.

### iOS

#### ✨ Features

* Added support to the OptiView Ads break manifest for `double`, `lshape_ad`, `lshape_content` and `overlay` formats as well as device type support.
* Added `currentBandwidthEstimate` to the player's `metrics` API, reporting the estimated available bandwidth in bits per second for HESP streams.
* Added Dolby Vision and EC-3 capability reporting (`com.dolby.optiview-cap-dvc`, `com.dolby.optiview-cap-ec3`) to the CMCD session data, and active video and audio codec reporting (`com.dolby.optiview-vc`, `com.dolby.optiview-ac`) to the CMCD status data.

#### 🐛 Issues

* Fixed an issue where the player would exit fullscreen presentation mode when setting a new source.
* Fixed an issue where OptiView Ads PTS breaks might not be played.
* Fixed an issue that caused OptiView Ads to end abruptly.
* Fixed an issue where skipping OptiView Ads would cause playback failure.
* Fixed an issue where seeking into a range of an interstitial would cause playback failure.
* Fixed an issue where legacy `CachingTask`s encoded without `bytes` and `bytesCached` properties would fail to restore.

### tvOS

#### ✨ Features

* Added display criteria matching: when enabled through the new `THEOplayer.manageContentMatching` property (disabled by default), and while in fullscreen presentation mode, the player matches the display mode (frame rate and dynamic range) of the TV with the content before playback starts.
* The player will now set its preferred video format when a new source is loading. This allows tvOS to change the format on the fly when a user enables content matching in "Settings" > "Video and Audio" > "Match Content".
* Added Dolby Vision and EC-3 capability reporting (`com.dolby.optiview-cap-dvc`, `com.dolby.optiview-cap-ec3`) to the CMCD session data, and active video and audio codec reporting (`com.dolby.optiview-vc`, `com.dolby.optiview-ac`) to the CMCD status data.

#### 🐛 Issues

* Fixed an issue where the player would exit fullscreen presentation mode when setting a new source.

### Roku

#### 🐛 Issues

* Fixed an issue where the CMCD-States payload could grow unbounded during repeated playback errors. The payload now contains at most the 20 newest states, and CMCD values are serialized strictly according to the CMCD specification (CTA-5004), matching the other platforms.
* Fixed issue where streams would fail to start playback on less powerful devices.

## 🚀 11.8.1 (2026/08/05)

### Android

#### ✨ Features

* Added `DRMConfiguration.preferredKeySystems` to control the key system selection order.
* Added `SourceAbrConfiguration.preferredVideoCodecs` and `SourceAbrConfiguration.preferredAudioCodecs` to prefer specific codecs (e.g. Dolby Vision) during track selection.

#### ⚡ Improvements

* Content protection errors now name the selected key system, and a clear error is reported when none of the configured key systems are supported by the device instead of failing with an unrelated Widevine error.
* The player now prefers Dolby Vision and HEVC variants over other codecs by default on streams with a mixed-codec ladder, when the platform supports them. Set `SourceAbrConfiguration.preferredVideoCodecs` to an empty list to disable this preference.
* Playback errors during OptiView Live Streaming playback now report their own error code instead of `THEO_LIVE_UNKNOWN_ERROR`, so content protection failures can be told apart from stalls and manifest errors.
* Added the `CONTENT_PROTECTION_PROVISIONING_ERROR` and `CONTENT_PROTECTION_DEVICE_REVOKED` error codes. A Widevine provisioning failure and a revoked device are now reported with their own code instead of the generic `CONTENT_PROTECTION_ERROR`.
* Added the `MEDIA_INTERNAL_ERROR` error code. An unexpected internal failure is now reported with its own code instead of `MEDIA_DECODE_ERROR`.

#### 🐛 Issues

* Fixed an issue where playback of a DRM-protected stream with a mixed-codec ladder (e.g. HEVC and AVC) could fail on devices that lack a secure decoder for one of the codecs. The player now excludes formats that require an unavailable secure decoder from track selection, so playback continues on a supported codec.
* Fixed an issue where the first playback of a DRM-protected stream could fail on a device that had not played DRM-protected content before, and would keep failing when retried.
* Fixed an issue where a playback error could be reported with an unrelated error code, hiding what actually went wrong.
* Fixed an issue where variant streams that the device cannot decode could be selected for playback, for example when `VideoTrack.targetQualities` includes a quality with an unsupported codec. This also applies to qualities that exceed the advertised decoder capabilities, which are now only used when no other quality is supported.
* Fixed an issue where playback failed with a fatal `Decoder failed` error when a decoder could not handle the selected variant stream despite claiming support for it. The player now excludes the failing codec from track selection, so playback continues on another codec when the stream provides one.

## 🚀 11.8.0 (2026/07/31)

### Web

#### 💥 Breaking Changes

* Removed the deprecated Service Worker-based playback pipeline for HESP sources on iOS Safari. HESP playback on iOS Safari now requires the `ManagedMediaSource` API, which is available on iOS 17.1 and higher. On older iOS versions, OptiView Live Streaming (THEOlive) sources fall back to their HLS endpoint instead. The `theoplayer.sw.js` file is still shipped as an intentionally empty file so that existing build pipelines keep working, and it is safe to stop serving it.

#### ✨ Features

* Added `PlayerConfiguration.overrideAutoplayCapability` to override the player's automatic detection of the platform's autoplay capabilities. This is an advanced API that can be used on platforms where the auto-detection is known to be slow or to fail, such as lower-end smart TVs and set-top boxes.
* Added the `title` property to the `Ad` interface for the `csai` integration. The title is parsed from the VAST `<AdTitle>` element.
* Added support for `loadVideoTimeout` and `bitrate` in the `csai` ad configuration.

#### ⚡ Improvements

* Improved transitions between Google IMA ads when scheduling multiple VAST ads back-to-back using `player.ads.schedule()`.
* The player now prefers Dolby Vision and HEVC variant streams over other codecs during the initial variant stream selection for HLS streams when the platform supports them. Set `SourceAbrConfiguration.preferredVideoCodecs` to an empty list to disable this preference.

#### 🐛 Issues

* Fixed an issue where the live stream latency (`ltc`) in CMCD reports could sometimes contain an incorrect or impossibly large value. The field is now omitted when no valid latency measurement is available.
* Fixed several CMCD reporting issues: VOD sessions now correctly report stream type as `st=v`, the startup flag (`su`) is no longer incorrectly reported as `false`, and bitrate fields are no longer reported when no valid value is available.
* Fixed an issue where requesting picture-in-picture could hang indefinitely on iOS/iPadOS Safari 26+ when another player was already in picture-in-picture, causing the player state to become incorrect.
* Fixed an issue where the `adTagParameters` from the ad source configuration were not reported in the CMCD interstitial events for OptiView Ads ad breaks.
* Fixed an issue where the OptiView Ads DOUBLE/L-shape layout animation would still activate even when both the backdrop and the ad failed to load during preloading (e.g. due to a DNS blocker). The player now correctly skips the layout transition when a preload error has already been reported.
* Fixed an issue where the player did not always correctly switch back to the content after playing a Google IMA ad on iOS Safari with `allowNativeFullscreen` enabled.
* Fixed an issue for OptiView Live Streaming (THEOlive) where HESP endpoints would be attempted on platforms that cannot play HESP, such as iOS Safari without `ManagedMediaSource` support, resulting in a delayed fallback to HLS.
* Fixed an issue where captions could be rendered twice while in native picture-in-picture on Chromium-based browsers.
* Fixed an issue where playback of a DRM-protected HLS stream with a mixed-codec ladder (e.g. HEVC and AVC) failed on platforms that support only some of those codecs for encrypted playback.
* Fixed an issue where CEA-608 closed captions were not shown when playing an HLS stream with HEVC video.
* Fixed an issue where the player would not select a variant stream whose codecs are supported by the browser when using a DRM pipeline, even though those codecs worked in a clear pipeline. This enables Dolby Vision with PlayReady to play on Windows Edge, which otherwise does not support clear Dolby Vision.
* Fixed an issue where `DRMConfiguration.preferredKeySystems` entries using key system aliases such as `widevine` or `playready` were not honored for HLS streams. Previously only full key system URNs were matched.

### Android

#### ✨ Features

* OptiView Ads can now be used with any valid player license, and no longer needs to be enabled specifically for your license.

#### 🐛 Issues

* Fixed an issue where the `adTagParameters` from the ad source configuration were not reported in the CMCD interstitial events for OptiView Ads ad breaks.
* Fixed an issue where playback might stall on low-performance devices after a reboot.
* Fixed an issue where loading an OptiView Live V3 distribution without a CMCD configuration would cause a crash.

### iOS

#### ✨ Features

* OptiView Ads can now be used with any valid player license, and no longer needs to be enabled specifically for your license.

#### 🐛 Issues

* Fixed several CMCD reporting issues: the live stream latency (`ltc`) could sometimes be reported as an impossibly large value, unmeasured fields such as `ltc`, `bl` and `mtp` were incorrectly reported as zero rather than being omitted, and the buffer length reported in CMCD states was always zero.
* Fixed an issue where the `AD_BREAK_END` event was sometimes not dispatched.
* Fixed an issue where the `adTagParameters` from the ad source configuration were not reported in the CMCD interstitial events for OptiView Ads ad breaks.
* Fixed a bug on iOS 15 where playback could stall indefinitely after returning from an IMA ad.
* Fixed an issue where recovering an OptiView Live stream after a failover or restart could fail to reload the stream.

### Roku

#### ✨ Features

* Added the ability to set the ad system and provider from OptiView Live.

#### 🐛 Issues

* Fixed an issue where OptiView Live streams wouldn't autoplay after failing over to a new endpoint.
* Fixed an issue where the player would sometimes not start playing when repeatedly changing sources and calling `play()`.

## 🚀 11.7.0 (2026/07/15)

### Web

#### ✨ Features

* Added support for the HLS `SUPPLEMENTAL-CODECS` attribute.

#### 🐛 Issues

* Fixed an issue where an HESP stream playing in iOS web views could appear frozen while the current time kept progressing. The player now detects this and recovers.
* Fixed an issue where seeking immediately to the middle of an MPEG-DASH stream and then later seeking back to the start of the stream could stall the player indefinitely.
* Fixed an issue where the distributed `.js` files were referencing internal `.js.map` files through a `//# sourceMappingURL` comment, which could raise warnings when bundling with e.g. webpack. These comments have been removed.
* Fixed an issue where the `id` property of a `csai` ad contained the VAST creative ID instead. `Ad.id` now returns the ad's ID, while `Ad.creativeId` returns the creative's ID.
* Fixed an issue where a PTS break would sometimes not be played when using the OptiView Ads manifest.
* Fixed a regression that could break playback on legacy engines (such as Tizen 2.4) when using certain polyfills that define a `Symbol.iterator` getter on non-iterable objects.
* Fixed an issue where the video track would report no active quality when playing an HLS stream that duplicates its variant streams across multiple audio codec groups, such as OptiView Live streams with both a Dolby and an AAC ladder. Qualities that only reference variant streams with unsupported codecs are now marked as unavailable.
* Fixed an issue where ABR would switch to a variant stream with incompatible codecs when the network bandwidth was insufficient for all variant streams, causing an unnecessary playback interruption, e.g. leaving the Dolby Vision ladder of an HLS stream instead of selecting its lowest Dolby Vision variant stream.

### Android

#### 🐛 Issues

* Fixed an issue where the OptiView Ads manifest could fail to load.
* Fixed an issue where the `InterstitialEndEvent` was not dispatched in OptiView Ads.

### iOS

#### ✨ Features

* Added support for the `contentprotectionerror` event, which is dispatched when the DRM flow fails.

#### 🐛 Issues

* Fixed an issue where the clickthrough info could not be updated through an `SSAIIntegration`.
* Fixed an issue where the `readyState` would revert from `HAVE_ENOUGH_DATA` to `HAVE_CURRENT_DATA` when playing an MP4 stream with sideloaded VTT text tracks.

### Roku

#### 🐛 Issues

* Fixed an issue where internal observers were not removed properly when the player was destroyed, which could cause a crash when rapidly creating and destroying the player.

## 🚀 11.6.1 (2026/07/07)

### Android

#### 🐛 Issues

* Fixed an issue where a caching task would download all qualities instead of only the selected ones when the source had sideloaded text tracks.

### iOS

#### 🐛 Issues

* Fix a bug on iOS 18 where playback could stall indefinitely after returning from an IMA ad.

## 🚀 11.6.0 (2026/07/03)

### General

#### ✨ Features

* Added `externalId` to OptiView Live distribution metadata exposed by the `distributionloaded` event.

### Web

#### 🐛 Issues

* Fixed an issue where an OptiView Live stream was incorrectly flagged as offline during slow startup.
* Fixed an issue where ID3 text tracks did not initially have a `TextTrack.type` set when playing inside a `WKWebView` on iOS.
* Fixed an issue where the player would error on some specific HLS streams with TTML subtitles.
* Fixed an issue where the player would create gaps in the buffer around discontinuities in certain HLS streams, which could result in undesirable gap jumps or short freezes during playback.
* Fixed an issue where the player sometimes would play only audio after a stall when playing an HESP stream.
* Fixed an issue where the device motion controls were not working in VR on mobile Chrome browsers.
* Fixed an issue where the device motion orientation in VR was inverted on mobile Chrome browsers.
* Fixed an issue where VR videos were being rendered upside down on iPad Safari.

### Android

#### ✨ Features

* CMCD ad event reporting is now supported for all ad integrations (and no longer limited to just OptiView Ads).

#### ⚡ Improvements

* Added optional provider information to OptiView Live endpoints.

#### 🐛 Issues

* Fixed an issue where an OptiView Ads overlay stays onscreen indefinitely after it has expired.
* Fixed an issue where Double Box and L-shape layouts were incorrectly shown in Picture-in-Picture mode with OptiView Ads.
* Fixed an issue where the player would crash if OptiView Ads playback was started while in Picture-in-Picture mode.
* Fixed an issue where the ads UI could get stuck after playing two consecutive ad breaks with OptiView Ads.

### iOS

#### ✨ Features

* Added support for customData on the Ad and AdBreak protocols.

#### 🐛 Issues

* Fixed an issue where the duration of OptiView Break Manifest Ads were not respected.
* Fixed an issue where changing or clearing `player.source` while playing an HESP stream could cause the app to crash due to an internal race condition.
* Fixed an issue where transitioning between IMA prerolls would cause the PiP window to close.
* Fixed an issue where sources with multiple IMA prerolls would load trailing prerolls after the main content.
* Fixed an issue where setting a source with an IMA ad while another source with an ad is playing would cause a crash.
* Fixed an issue where scheduling IMA ads causes a momentary black screen in main content.
* Fixed an issue where ads from different systems would overlap with OptiView Ads.
* Fixed an issue in OptiView Ads where the layout would switch to single momentarily in between companion ads.
* Fixed an issue where during ad playback in PiP, the original player view continues to playback main content.
* Fixed an issue where double box and L-shape ads don't show in PiP.
* Fixed an issue where Ads would remain in double box layout after finishing.

### Roku

#### ✨ Features

* Added client-side ad beaconing for MediaKind SSAI streams.
* Added session beacons for the MediaKind connector.

#### ⚡ Improvements

* Removed automatic use of `START=Live` for live MediaKind streams. The client now can specify the live stream URL params.

#### 🐛 Issues

* Fixed an issue where during fallback on an OptiView Live stream the wrong endpoint was selected.

## 🚀 11.5.3 (2026/08/13)

### iOS

#### 🐛 Issues

* Fixed an issue where `bytesCached` and `bytes` properties would return 0 for cached sources pre 10.12.0.

## 🚀 11.5.2 (2026/08/10)

### iOS

#### 🐛 Issues

* Fixed an issue where legacy `CachingTask`s encoded without `bytes` and `bytesCached` properties would fail to restore.

## 🚀 11.5.1 (2026/07/03)

### iOS

#### 🐛 Issues

* Fixed an issue when playing cached sources where the player could switch to audio/video renditions that were not cached.

## 🚀 11.5.0 (2026/06/16)

### General

#### ⚡ Improvements

* Changed the CMCD event report MIME type to `application/cmcd` per the CTA-5004-B specification.

### Web

#### ✨ Features

* Added support for OptiView Discovery V3 distributions.
* Added support for `ignoreEmbeddedTextTrackTypes` for HESP streams.

#### ⚡ Improvements

* Improved ABR performance on HESP streams, which should result in fewer stalling and increased stable playback at higher quality.

#### 🐛 Issues

* Fixed an issue where calling `player.destroy()` while playing an ad would throw an uncaught `TypeError`.
* Fixed an issue where [ID3 metadata carried inside CMAF](https://aomediacodec.github.io/id3-emsg/) would end up in separate ID3 text tracks if the `scheme_id_uri` or `value` of the encapsulating `emsg` boxes were different. All ID3 cues will now always end up in a single ID3 text track, and the `value` of the `emsg` is ignored. This matches the existing behavior on Android and iOS.
* Fixed an issue where an HESP stream failed to load on an iOS WebView.
* Fixed an issue where `emsg` cues were never removed while playing an HESP stream.
* Fixed a regression where the "exit fullscreen" button was no longer visible when the player encounters a fatal error while playing in fullscreen mode using the legacy UI.
* Fixed an issue where the `encrypted` event was not properly dispatched when playing a DRM-protected stream.
* Fixed an issue where the player stalls for a while when switching back from ad to content with an OptiView Ads stream.

#### 👎 Deprecations

* `player.theoLive.badNetworkMode` is no longer supported. The player's ABR has been improved to quickly switch to a lower quality when the network conditions worsen, even when playing at very low latency. This API is now a no-op, and will be removed in the next major version.

### Android

#### ✨ Features

* Added `Abr.preferredMaximumResolution` to cap the maximum video resolution selected at runtime. Also `player.abr.abrStrategy` is now used for OptiView Real-time Streaming playback when `MillicastSource.connectOptions` is not set.
* Added `hlsDateRange` property to `THEOplayerConfig` to enable HLS date range parsing at the player level.

#### ⚡ Improvements

* Updated the Millicast SDK to version 2.6.0 which adds `maxWidth` and `maxHeight` constraints to viewer layer selection, allowing resolution-based filtering without selecting a specific simulcast layer.
* `THEOplayerConfig` now fully supports using Kotlin property syntax.

#### 🐛 Issues

* Fixed an issue where an ad with Double Box layout shifted the content and ad players outside the video frame.
* Fixed an issue when `CastStrategy.AUTO` had no effect on startup and a Cast device was not re-connected due to regression in Cast SDK. Cast Framework has been downgraded to the latest stable version `21.5.0`.
* Fixed an issue where a `NullPointerException` could be thrown if the player enters picture-in-picture mode when its `THEOplayerView` is not properly attached to a parent `Activity`.
* Fixed a crash when `setSource` was called on a destroyed player.

### iOS

#### 💥 Breaking Changes

* For non OptiView Live sources, a `CMCDConfiguration` or `CMCDSourceConfiguration` is now expected to enable CMCD reporting.

#### ✨ Features

* Added support for OptiView Discovery V3 distributions.
* Introduce configuring ABR strategy and maximum resolution for OptiView Real-time sources.

#### 🐛 Issues

* Fixed an issue where the startTimes of DateRangeCues are incorrect if the player applies a seek while the cues are being processed.
* Fixed an issue in OptiView Ads where no `AD_BREAK_END` error was dispatched after an interstitial error.
* Fixed an EXC\_BREAKPOINT crash in CMCDState.Builder.build() caused by NaN or infinite values in CMCD measurements during DVR seek operations.
* Fixed an issue where CMCD would be active even when not configured.
* Fixed an issue where daterange cues with identical startTimes were not processed correctly.
* Fixed an issue where OptiView Live specific CMCD status would not be reported.

### Roku

#### ✨ Features

* Added basic support for CMCD event mode reporting of DRM and ad events.
* Added in support for custom SSAI integrations and SSAI ad descriptions that use ad tag parameters.
* Added support for OptiView Live discovery v3 distributions.
* Added MediaKind connector with support for playback of DRM streams.
* Added the Capabilities API to the SDK for help getting device capabilities.

#### 🐛 Issues

* Fixed an issue with tag remover's handling of URIs that started with "data:".

## 🚀 11.4.0 (2026/06/03)

### Web

#### ✨ Features

* Added basic support for CMCD event mode reporting of DRM and ad events.
* Added `Quality.enabled` to enable or disable a quality. When a quality is disabled, it will be ignored during ABR selection or when setting `MediaTrack.targetQuality`.
* Added support for `breakManifestUrl` for OptiView Ads streams.

#### 🐛 Issues

* Fixed an issue with OptiView Ads where setting overlay positions (top/bottom/left/right) to 0 was not supported.
* Fixed an issue where the player could crash on Sky Glass/Puck when `autoplay` is set to `true`.
* Fixed an issue where using WebXR on iOS Safari was preventing VR video from being rendered inline.
* Fixed an issue where clicking the "LIVE" button on an HLS live stream would sometimes seek to the start of the DVR window instead of the live edge when using native HLS playback on macOS/iOS Safari.
* Fixed an issue on the FireTV AFTM model where playback stalls were made worse by trying to recover too fast.
* Fixed an issue where HESP streams with PlayReady DRM would repeatedly stall while playing in Edge on Windows.
* Fixed an issue where VAST ads containing both an ad pod and an ad buffet failed to play through the Google IMA integration.

#### ⚠ Known Limitations

* When starting a Chromecast session while playing a Google IMA ad break with multiple ads, the Chromecast receiver may start playing from the first ad in the ad break even if it was already played before.

### Android

#### ✨ Features

* Added basic support for CMCD event mode reporting of DRM and ad events.
* Added support for OptiView Discovery V3 distributions.
* Added support for Break Manifest in OptiView Ads.
* Added `CustomAdDescription`, allowing custom ad integrations to create custom ad descriptions that can be passed through `SourceDescription.ads`.

#### 🐛 Issues

* Fixed an issue when the player suddenly switched to the highest possible quality right after a stall while playing an HESP stream.
* Fixed an issue when player crashed if there was a cache download background task and the system required to stop it.

### iOS

#### ✨ Features

* Enabled OptiView Ads overlays to be signaled through SSE.
* Added basic support for CMCD event mode reporting of DRM and ad events.

#### ⚡ Improvements

* Improved OptiView Live Streaming (THEOlive) endpoint fallback selection logic.
* Improved fallback recovery speed for OptiView Live Streaming (THEOlive) on iOS 26.

#### 🐛 Issues

* Fixed an issue where IMA ad errors caused content playback to fail completely.
* Fixed an issue in the IMA integration where pausing ad playback did not work when scheduled via `requestAds`.
* Fixed an issue where no `error` event was sent during playback on iOS 26 with a bad network connection.
* Fixed an issue in OptiView Ads where dismissing the player would cause a crash.

### Chromecast CAF

#### 🐛 Issues

* Fixed an issue with OptiView Ads where setting overlay positions (top/bottom/left/right) to 0 was not supported.

### Roku

#### ✨ Features

* Added `currentsourcechange` event when the currently playing stream changes.
* Added ability to call `setContentId`, `setContentLength`, and `setContentGenre` on RAF via methods of the same names on `player.ads.rafProxy`. Also added the `setRafMetadata` method to `player.ads.dai` for setting the same data during DAI playback.

#### 🐛 Issues

* Fixed the order of events on startup so they emit at the correct times.

## 🚀 11.3.0 (2026/05/18)

### Web

#### ✨ Features

* Added support for OptiView Live streams with JWT token security on iOS Safari. Note that this requires a long-lived token that remains valid for the entire playback session. For short-lived tokens, we recommend [using a service worker](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/theolive/token-based-security.md#short-lived-tokens-using-service-worker).
* Added support for DRM-protected OptiView Live streams with JWT token security on macOS Safari. Note that this requires a long-lived token that remains valid for the entire playback session.

#### 🐛 Issues

* Fixed an issue where date range cues were not correctly created when playing an HLS media playlist (without multi-variant playlist) on iOS Safari.
* Fixed an issue where the player would still switch to an ad layout when seeking into the ad while the ad is not available for an OptiView Ads stream.

### Android

#### ⚡ Improvements

* Modify the Millicast SDK dependency in the OptiView Real-time Streaming integration to start accepting patch version updates (2.5.x)

#### 🐛 Issues

* Fixed an issue where `TextTrackStyle.setFont()` did not override the font family defined in the subtitle within the stream.

### iOS

#### ⚡ Improvements

* Modify the Millicast SDK dependency in `THEOplayerMillicastIntegration` to allow patch version updates (2.5.x).

### Roku

#### 🐛 Issues

* Added `adexitrequested` event to Ads API to allow applications to handle back button presses during clientside ad playback.

## 🚀 11.2.0 (2026/05/07)

### Web

#### ✨ Features

* Exposed `traffickingParametersString` for ads in `google-dai` sources.
* Added support for `#EXT-X-KEY` tags for PlayReady with CENC encryption for HLS streams.
* Added support for `replaceContent` for OptiView Ads streams.

#### 🐛 Issues

* Fixed an issue where the player would not have the correct `seekable`, `buffered` and `duration` during ad playback in a VOD OptiView Ads stream.
* Fixed an issue where the player would stutter when playing a muxed HLS stream on MacOS Safari unmuted.
* Fixed an issue where switching to an OptiView Live stream with JWT token security enabled while casting to Chromecast did not correctly pass along the JWT token to the receiver.
* Fixed an issue where the playhead would snap back during scrubbing on mobile browsers.

### Android

#### 💥 Breaking Changes

* Ads insertion metadata request will now be postponed from `setSource` call till the `play` call happens as the default `PreloadType` is `NONE`. Changing `PreloadType` to `AUTO` or `METADATA` brings the old behaviour back: `setSource` will fetch ads insertion metadata.

#### ✨ Features

* Added support for loading Google DAI metadata in a lazy manner. Use `PreloadType.NONE` to delay loading metadata until `Player.play()` is called. If `PreloadType` is `AUTO` or `METADATA` the behaviour stays unchanged: the load request will be executed as soon as `setSource` is called.

#### 🐛 Issues

* Fixed an issue where the `PLAYING` event was fired again after the end of an ad break when using OptiView Ads.

### iOS

#### ⚡ Improvements

* Updated the minimum required Google IMA SDK version to 3.31 to include the latest improvements.

#### 🐛 Issues

* Fixed an issue where subtitles were not correctly positioned when changing the player `aspectRatio` property.
* Fixed an issue where no duration change event was dispatched before an HLS live source ended.
* Fixed an issue where the player does not retain picture-in-picture mode when main content is resumed after an ad playback.
* Fixed an issue where non-fatal coreMediaError surfaced as fatal errors.

### tvOS

#### ⚡ Improvements

* Updated the minimum required Google IMA SDK version to 4.16 to include the latest improvements.

### Chromecast CAF

#### ✨ Features

* Added support for playing Axinom DRM streams on Chromecast.

#### ⚡ Improvements

* Updated all CAF Chromecast applications to use Shaka 4.15.36 by default to enable HLS-CMAF streams and improve OptiView Live playback. Also introduced an MPL-only CAF Chromecast application that does not use Shaka.

#### 🐛 Issues

* Fixed an issue with OptiView Live streams reloading after being cast.
* Fixed an issue with keyOS DRM streams where the `customdata` property was lost when casting to the Chromecast CAF app.

### Roku

#### ✨ Features

* Added in support for DRM on OptiView Live streams. Also added new configuration options for content protection.

#### 🐛 Issues

* Fixed an issue with no playback when switching between two SSAI streams.
* Fixed an issue where the Adobe analytics task node was not being properly cleaned up when the connector is destroyed. Added a param to the connector's `destroy` method to force the Adobe analytics task node to be destroyed when the connector is destroyed.

## 🚀 11.1.0 (2026/04/28)

### Web

#### ✨ Features

* Added `Player.version` as an alias for the global `THEOplayer.version`.

#### 🐛 Issues

* Fixed an issue where `player.hesp.latencies` would return `undefined` for some OptiView Live streams.
* Fixed an issue where `preferredKeySystems` was ignored when using the `keyos` pre-integration.
* Fixed an issue where the player would error or stall when playing an HLS MPEG-TS stream with a small audio-only segment before a discontinuity.
* Fixed an issue where an incorrect segment URL was being requested in a DASH live stream when the player receives an MPD update that re-adds a previously removed segment in a `<SegmentTimeline>`.

### Android

#### 🐛 Issues

* Fixed an issue where the `durationchange` event was not fired before the `ended` event when an HLS live stream ends with `#EXT-X-ENDLIST`.
* Fixed an issue where switching between two DRM-enabled HESP OptiView Live streams with identical DRM configurations could crash the player.
* Fixed an issue where Cast state events are not fired if `CastStrategy.MANUAL` is used. The issue resulted in Cast button not being shown.

### iOS

#### 💥 Breaking Changes

* As announced in the [11.0.0 release changelog](#-1100-20260416), THEOplayer iOS SDK and its integrations will now be built with Xcode 26 instead of Xcode 16.

#### 🐛 Issues

* Fixed an issue where the aspect ratio was not properly updated while playing an OptiView Real-time stream.
* Fixed an issue where `THEOliveAPI.latencies` would return `nil` for some OptiView Live streams.
* Fixed an issue where OptiView Ads triggered through ID3 would fail to load correctly.
* Fixed an issue where MP3 sources with the `audio/mpeg` mimetype were not recognized correctly.

### Chromecast CAF

#### ✨ Features

* Added `Player.version` as an alias for the global `THEOplayer.version`.

### Roku

#### 🐛 Issues

* Fixed an issue where using an array of URLs as `source.sources` would cause an error.
* Fixed an issue where the license expired text would show momentarily while renewing a license.
* Fixed issue where VMAP ads would not play.
* Made stall detection logic less prone to false positives.

## 🚀 11.0.0 (2026/04/16)

We are happy to announce the eleventh major version of THEOplayer, releasing all the improvements and developments our team has achieved since version 10.0.

THEOplayer 11.0 includes **some breaking changes per SDK**. Please review them carefully in the respective changelog for your SDK.

* The iOS SDK now supports iOS 15 and tvOS 15 and higher, dropping support for iOS/tvOS 13 and 14.
* On Android, the Google IMA integration has been updated to support version 3.39.0 of the Google IMA SDK. This requires core library desugaring to be enabled in your app.

For more info on navigating our breaking changes, take a look at our migration guides for [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/migrating-to-theoplayer-11.md), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/migrating-to-theoplayer-11.md), [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/ios/migrating-to-theoplayer-11.md) and [React Native](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/migrating-to-react-native-theoplayer-11.md).

### Web

#### 💥 Breaking Changes

* Removed `player.theoLive.preloadPublications`.

### Android

#### 💥 Breaking Changes

* All methods on `Player` and `THEOplayerView` must only be called from the main thread and are annotated with `@MainThread`. Calling these methods from a different thread will throw an `IllegalStateException`.
* The Google IMA SDK integration now requires [core library desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) to be enabled. See [our updated guide for Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/google-ima.md#updating-the-google-ima-sdk) for instructions.
* Removed `TheoLive.preloadChannels`.
* Changed `MediaTailorAdAvail.id` to return a `String` instead of an `Int`, to align with `AdBreak.id`.
* Removed `TheoAdsErrorEvent`, use `AdErrorEvent` instead.
* Removed `TheoAdsEventTypes.THEOADS_ERROR`, use `AdsEventTypes.AD_ERROR` instead.

#### ✨ Features

* Added `AdBreak.id`, to replace the (now deprecated) `AdBreak.idAsString` property.

#### ⚡ Improvements

* Updated Google IMA SDK to version 3.39.0.

#### 🐛 Issues

* Fixed `Event`, `EventListener` and `EventDispatcher` to not use raw types in their generic type parameters.
* Fixed a `NullPointerException` fired by the IMA SDK on ad request.

#### 👎 Deprecations

* Deprecated `AdBreak.idAsString`, use `AdBreak.id` instead.

### iOS

#### 💥 Breaking Changes

* The minimum supported iOS/tvOS version is now 15.0, dropping support for iOS/tvOS 13 and 14.
  * This update aligns with current Xcode tooling requirements and enables us to maintain a high standard of performance, security, and long-term support for the SDK. All devices that support iOS/tvOS 13 and 14 are capable of upgrading to iOS/tvOS 15 or later, meaning no active hardware is excluded by this change. Additionally, based on our internal analytics, fewer than 1% of end users remain on versions below iOS/tvOS 15, and those users are predominantly on older SDK versions. This change allows us to focus development efforts on modern platform capabilities while minimizing impact to production environments.

* THEOplayer iOS SDK and its integrations will be built with Xcode 26 instead of Xcode 16 in an upcoming minor 11.x version.

  * This aligns with [Apple's announcement](https://developer.apple.com/news/?id=ueeok6yw) that apps must be built with the iOS 26 & tvOS 26 SDKs starting April 28, 2026.
  * Please note that this is only an announcement, but not an immediate change for THEOplayer SDK. Please check upcoming release changelogs for more information.

* Removed deprecated `ManifestInterceptor` and `DeveloperSettings` APIs in favor of `NetworkAPI`.

* Renamed `playerMetrics` API to `metrics`.

* Changed `Ad.adBreak` type to be optional.

* Removed deprecated `MediaTrack.activeQualityBandwidth` property in favor of `MediaTrack.activeQuality.bandwidth`.

* Removed deprecated `SourceDescription.enableStreamingDVR` property.

* Errors in `CachingTaskErrorStateChangeEvent` now dispatch cache related error codes instead of `NETWORK_ERROR` code. For more details, check the `cause` property of the error.

* Removed `THEOliveAPI.preloadPublications`.

#### ✨ Features

* Starting with 11.0.0, the THEOplayer iOS SDK will be released in a public self-hosted spec repo.

  * To get the SDK from our hosted repo, simply add `source 'https://github.com/THEOplayer/cocoapods-specs'` to your `Podfile`.
  * This decision comes as a solution to [the planned read-only change to the CocoaPods public spec repo at the end of 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/).
  * For now, we will keep publishing to both sources, but we highly recommended switching to THEOplayer's spec repo. Starting with 12.0.0 later this year, we plan to stop publishing to the CocoaPods public spec repo.

#### 👎 Deprecations

* Deprecated the old Chromecast pipeline in favor of the new experimental pipeline.

  * The new Chromecast pipeline introduced in version 10.6.0 offers new features and improved performance. Over time and with more positive feedback, we are heading towards switching to the new pipeline by default.
  * The old pipeline is still enabled by default. However, we highly recommend customers switch to the new pipeline by setting `enableExperimentalPipeline` to `true` in `CastConfiguration`.
  * Starting with 12.0.0 later this year, we plan to retire the `enableExperimentalPipeline` property together with the old pipeline, making the new pipeline the default for all customers.

* Changed the return types of `player.cast` and `player.cast.airplay` to be non-optional.

### Roku

#### 💥 Breaking Changes

* Removed deprecated `bitratechange` event.

---

# Connectors for THEOplayer

## [Connectors for Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web.md)

## [Connectors for Android SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android.md)

## [Connectors for iOS & tvOS SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios.md)

## [react-nativeConnectors for React Native SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native.md)

## [Connectors for Roku](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/roku.md)

---

# THEOPlayer 🤝 Sideloaded TextTracks Samples

We provide source code of two sample applications that illustrate how to use the connector with different package managers:

* [Sample using **Cocoapods**](https://github.com/THEOplayer/iOS-Connector/blob/-/Code/Sideloaded-TextTracks-Examples/Cocoapod) (requires Cocoapods installation through terminal)

---

# @theoplayer/react-native-analytics-npaw

## 1.1.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.0.0

* Initial release.

---

# THEOplayer React Native NPAW Connector

An [NPAW](https://npaw.com/) (formerly YOUBORA) analytics connector for `@theoplayer/react-native`.

This connector is JavaScript-only and works across iOS, Android and web through the unified `react-native-theoplayer` player, using only the `npaw-plugin-react-native` plugin — no native iOS/Android modules are required.

> **Note:** This connector targets **NPAW v7+** (it depends on `npaw-plugin-react-native` `^7.3.x`).

## Installation

```sh
npm install @theoplayer/react-native-analytics-npaw
```

## Usage

### Configuring the connector

Create the connector with the `useNpaw` hook, passing a config object and initializing it once the `THEOplayer` instance is ready:

```tsx
import { LogLevel, useNpaw } from '@theoplayer/react-native-analytics-npaw';

const App = () => {
  const [npaw, initNpaw] = useNpaw({
    accountCode: 'your-account-code',
    analytics: {
      'content.title': 'Big Buck Bunny',
      'content.isLive': false,
      // Free-form custom metadata shown in the NPAW "Metadata" panel:
      'content.metadata': { genre: 'animation' },
    },
    // Optional NpawPlugin options (host, sessionRecovery, ...):
    plugin: { sessionRecovery: 'auto' },
    logLevel: LogLevel.DEBUG,
  });

  const onPlayerReady = (player: THEOplayer) => {
    initNpaw(player);
  };

  return <THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady} />;
};
```

Alternatively, construct the `NpawConnector` class directly:

```ts
import { NpawConnector } from '@theoplayer/react-native-analytics-npaw';

const connector = new NpawConnector(player, { accountCode: 'your-account-code' });
```

### Configuration

| Field         | Description                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `accountCode` | Your NPAW account code. **Required.**                                                                     |
| `analytics`   | Per-video analytics options, e.g. `content.title`, `content.isLive`, `content.metadata`, `user.name`, ... |
| `plugin`      | `NpawPlugin` options such as `host`, `sessionRecovery` and `balancerAnalyticsEnabled`.                    |
| `logLevel`    | Initial `LogLevel`.                                                                                       |

### What is tracked automatically

Once initialized, the connector registers a video adapter (and an ads adapter) against the player and reports playback automatically:

* Playback events (start, join, pause/resume, buffering, seeking, end and errors) mapped from the unified `PlayerEventType` events.
* Playhead, duration and live/VOD state, resource, rendition and bitrate.
* The active subtitle/caption track language (`getSubtitles`) and audio language (`getVideoLanguage`).
* Ads: ad breaks, ad start/join/stop, quartiles, skip, click and errors, with ad position (`pre`/`mid`/`post`), duration and skippability.

### Updating options at runtime

```ts
// Update options for the current video (e.g. late-arriving metadata):
npaw.current?.setVideoOptions({ 'content.title': 'New Title' });

// Update global analytics options:
npaw.current?.setAnalyticsOptions({ 'user.name': 'viewer-1' });

// Change the log level:
npaw.current?.setLogLevel(LogLevel.SILENT);

// Stop analytics and close all sessions:
npaw.current?.destroy();
```

See the [NPAW integration documentation](https://documentation.npaw.com/integration-docs/docs/) for the full set of plugin and analytics options.

---

# Getting started

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

OptiView Player offers a rich portfolio of video SDKs for many platforms and frameworks across desktop, mobile and TV devices.

Our dedicated guides help you get started right away.

## [OptiView Player Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md)

## [OptiView Player Android SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/getting-started.md)

## [OptiView Player iOS & tvOS SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/ios/getting-started.md)

## [OptiView Player React Native SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/getting-started.md)

## [OptiView Player Flutter SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/flutter/getting-started.md)

## [OptiView Player Chromecast SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md)

## [OptiView Player Roku SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/roku/getting-started.md)

---

# How to update an SDK?

This how-to guide describes how to update to a new version of the THEOplayer SDK.

> **Info**
>
> Starting from version 2.79.0, you can make use of License as a Configuration with Web SDK. This allows you to reuse the same library when changing your license. It also allows you to make use of our NPM modules instead of using the THEOplayer zip-file. In order to use this functionality, there is a change needed in your THEOplayer integration. You can read more about this [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/license/introduction.md).
>
> We highly recommend using this new license system due to all the advantages it brings.

## Update Web SDK

Typically, next to using [NPM](https://www.npmjs.com/package/theoplayer), you grab a CDN URL or a downloadable ZIP file through <https://portal.theoplayer.com>, which gives you access to URLs like those below:

* LIBRARY LOCATION: `https://cdn.myth.theoplayer.com/<license-key>/`
* CDN ZIP LINK: `https://portal.theoplayer.com/download/<license-key>?h=1643658986`

Configuring THEOplayer through the "Library Location" implies a **cloud-hosted (CDN)** approach. Downloading (and configuring) the ZIP (or using NPM) implies a **self-hosted (ZIP file)** approach.

![Update SDK](/pr-932/assets/images/update-sdk-5f00e7ff6ef3854952cf07f2562b3d08.png)

### 1. Cloud-hosted

Every SDK that you create through <https://portal.theoplayer.com/> is associated with a specific THEOplayer version. When you're doing cloud hosting, you're referring to THEOplayer's CDN to load the relevant JavaScript, for example `https://cdn.myth.theoplayer.com/<license-key>/THEOplayer.js`.

To change the version of this specific SDK, you use the GUI at <https://portal.theoplayer.com/> to change it to a different version, and hit the "Save & Publish" button after making your changes. Your video player will now automatically start using this new version, but do note that the CDN and browser cache might still be referring to your older version for a little while. If your browser is still not fetching the new JS libraries, try hard refreshing your browser tab first.

![Save \&amp; Publish](/pr-932/assets/images/republish-7d7f211f07d91032ae93414a82528d26.png)

### 2. Self-hosted

Alternatively, you could extract the included zip file and host the library yourself.

In this case, the steps are similar to the above steps, but you'll also need to re-download your SDK to grab the new THEOplayer files.

When you extract the ZIP file, you will see the following 'helper files':

* `theoplayer.d.js`
* `theoplayer.e.js`
* `theoplayer.p.js`

It is **important** these files are placed in the **same directory as the core library (THEOplayer.js)**.

**It is crucial to also update the libraryLocation as seen in the snippet above. Not doing will result in playback failure.**

If you're using [THEOplayer through NPM](https://www.npmjs.com/package/theoplayer), then you should replace the version of THEOplayer in your `package.json` file.

## Other SDKs

Updating the iOS SDK, Android SDK and Roku SDK is similar with regards to self-hosting the SDK.

The iOS SDK and Android SDK can also be managed through CocoaPods and Maven respectively. You cannot "cloud host" these SDKs.

---

# SDKs

Dolby OptiView Player provides a set of feature-rich video player software development kits (SDKs). Each SDK targets a set of platforms. For example, a developer integrates the iOS SDK in their iOS app.

Dolby OptiView Player offers the following SDKs. (Clicking the link takes you to the respective getting started guide.)

* HTML5/Tizen/webOS SDK

  * [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md) targets (desktop and mobile) browsers, HTML5-based smart TVs, progressive web apps, and other HTML5-based platforms.
  * [webOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/webos/getting-started.md) targets LG webOS apps.
  * [Tizen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/tizen/getting-started.md) targets Samsung Tizen apps.
  * [Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md) targets (custom) Chromecast apps.

* Android/Android TV/Fire TV SDK

  * [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/getting-started.md) targets Android, Android TV and Fire TV apps. It may also be used for other Android-based platforms.

* iOS/tvOS SDK

  * [iOS & tvOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/ios/getting-started.md) targets iOS, iPadOS and tvOS apps.

* Roku SDK

  * [Roku](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/roku/getting-started.md) targets Roku apps.

* [React Native](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/getting-started.md) SDK

Want to update an existing SDK instead? Follow [this guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/how-to-update-a-sdk.md).

> **Looking for the Legacy Android and iOS/tvOS (4.12.x) SDKs?**
>
> The legacy Android and iOS/tvOS SDKs (version 4.12.x) are no longer supported. However, you can still access their documentation through the following links:
>
> * Android/Android TV/Fire TV Legacy (4.12.x) SDK
>
>   * [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/android/getting-started) targets Android apps, and may be used for other Android-based platforms.
>   * [Android TV](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/android-tv/getting-started) targets Android TV apps.
>   * [Fire TV](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/fire-tv/getting-started) targets Fire TV apps.
>
> * iOS/tvOS Legacy (4.12.x) SDK
>
>   * [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/ios/getting-started) targets iOS and iPadOS apps.
>   * [tvOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/tvos/getting-started) targets tvOS (i.e. Apple TV) apps.

---

# OptiView Hosted Player

Dolby hosts a special version of the OptiView video player for use with customers intended to be used for `<iframe>` embedding. This version of the player is configurable with query parameters to make it easy to setup and configure without having to host the player yourself.

The player is hosted at:

```text
https://sbp.optiview.dolby.com/latest/
```

## Versioning

The hosted player is versioned and will automatically update when new releases are published. The latest version is always available at `https://sbp.optiview.dolby.com/latest/`.

For production, we recommend that you lock to a specific version, you can use the version number in the URL. Example: `https://sbp.optiview.dolby.com/11.1.0/`.

These versions of the player map directly to the [changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md). The first version available for the hosted player is `11.1.0`.

## Configuration

The following parameters can be provided used to configure the hosted player. *Note: query parameters are case sensitive!*

### Required Parameters

* `license`: a OptiView player license obtained through the dashboard. If using the hosted version of the player you should limit sources for playback, you can utilize "Source Domain" restrictions in the player portal. This will prevent viewers from stealing your license and using it for their own streams. If using streams from Dolby, you must white list the following

  * *Whitelist Page Domains*

    * `sbp.optiview.dolby.com`
    * *Note: at this time it is not possible to whitelist the end-application domain for whitelisted page domains in the license. If you wish to secure your streams by page domain, please contact Dolby to get your own license and player implementation.*

  * *Whitelist Source Domains*

    * `cdn.optiview.dolby.com`
    * `cdn.theo.live`
    * `cdn.anywhere.theo.live`
    * `cdn.tla-prd.theostream.live`
    * `discovery.theo.live`
    * `stream.anywhere.theo.live`
    * `stream.theo.live`

* `sourceType`: the type of source to configure the player to play back. Choose one of:

  * `realtime`: Real-time WebRTC playback with OptiView's real-time streaming solution (formerly Millicast)
  * `lowdelay`: Low-delay HESP/HLS playback with OptiView's live streaming solution (formerly THEOlive).
  * `live`: HLS playback with an .m3u8 manifest
  * `vod`: used for MP4 progressive download playback or for HLS/DASH non-live assets. The type is determined by the file extension.

* `source`: the source itself based on the `sourceType`. Here are some examples:

  * for `realtime`, the source looks like `accountId/streamname`. Example: `k9Mwad/multiview`.
  * for `lowdelay`, the source looks like `distributionId`. Example: `af5d8187-1af0-46af-92da-a9333719f296`. *Note: if you are using the V1 of the THEOlive API, you will need to use the channel ID instead of the distribution ID.*

### Optional Parameters

* `token`: an optional playback token for enabling stream protection. The type of token must be matched to the `sourceType`.
* `autoPlay`: *(default `false`).* A boolean whether to enable playback to automatically start when the page loads.
* `muted`: *(default `true`).* A boolean whether to start the stream playback muted or not. *Note that if `autoPlay` is set to `true`, playback will begin muted due to browser restrictions.*
* `poster`: a publicly accessible poster frame image to show when the stream is offline
* `playerColor`: *(default `4D5963`)* a hex color code value to set the play button and scrub bar. *Note that the value is an integer and should NOT contain the `#` at the beginning.*

### Optional Parameters (real-time only configurations)

The following parameters are only valid with Dolby OptiView real-time streaming and will be ignored with other `sourceTypes`.

* `minDelay`: *(default: `50`).* a small minimum playout delay set to improve performance in degraded network conditions. Specified in milliseconds. See [Documentation](https://docs-preview.optiview.dolby.com/pr-932/millicast/playback/players-sdks/web/player.md#playout-delay).
* `maxDelay`: *(default: `120`).* a small maximum playout delay set to improve performance in degraded network conditions. Specified in milliseconds.
* `maxHeight`: The maximum height resolution height (pixels) in the ABR range control to load in the given playback session. See [Documentation](https://docs-preview.optiview.dolby.com/pr-932/millicast/playback/players-sdks/web/player.md#abr-range-control). Intended to be used mutually exclusively with `maxWidth`.
* `maxWidth`: The maximum width resolution (pixels) in the ABR range control to load in the given playback session. See [Documentation](https://docs-preview.optiview.dolby.com/pr-932/millicast/playback/players-sdks/web/player.md#abr-range-control). Intended to be used mutually exclusively with `maxHeight`.

## Player Events

Basic [player events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdBreakEvent) are sent with [window post messages](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) to the parent page in case the embedding application wishes to utilize them. Events include:

* ended
* pause
* play
* playing
* resize
* volumechange

Here is an example of how to consume these messages, logging them to the console:

```javascript
<script>
  window.addEventListener("message", (event) => {
    // confirm origin for security
    if (event.origin !== "https://sbp.optiview.dolby.com") {
      return;
    }

    console.log("iframe event", event.data);
  });
</script>
```

### Configuration Examples

This is a basic example of a player that is configured in a basic way to play a real-time source:

```text
https://sbp.optiview.dolby.com/latest/?sourceType=realtime&source=k9Mwad/multiview&license=LICENSE_STRING
```

This is an example of a player that is configured to play a real-time stream with token protection and other customizations:

```text
https://sbp.optiview.dolby.com/latest/?sourceType=realtime&source=k9Mwad/multiview&autoPlay=false&muted=true&playerColor=58007a&license=LICENSE_STRING&token=TOKEN_STRING
```

This is an example to load an OptiView low-delay stream and start with automatic playback:

```text
https://sbp.optiview.dolby.com/latest/?sourceType=lowdelay&source=ar5c53uzm3si4h4zgkzrju44h&autoPlay=true&muted=true&license=LICENSE_STRING
```

This is an example to load an HLS stream and start with automatic playback:

```text
https://sbp.optiview.dolby.com/latest/?sourceType=live&source=https://stream.theo.live/europe-west/e2c4220c-3cf4-4499-ab3a-ea5e904d0406/ar5c53uzm3si4h4zgkzrju44h/stream/main.m3u8&autoPlay=true&muted=false&license=LICENSE_STRING
```

## A Complete Example

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Dolby Stream Embed</title>
    <style>
      html,
      body {
        height: 100%;
        width: 100%;
        margin: 0;
      }
      iframe {
        width: 100%;
        height: 100%;
        border: none;
      }
    </style>
  </head>
  <body>
    <iframe
      src="https://sbp.optiview.dolby.com/latest/?sourceType=realtime&source=k9Mwad/multiview&autoPlay=false&muted=true&playerColor=58007a&license=LICENSE_STRING"
      allowfullscreen
      allow="autoplay; encrypted-media"
    ></iframe>
    <script>
      window.addEventListener('message', (event) => {
        // confirm origin for security
        if (event.origin !== 'https://sbp.optiview.dolby.com') {
          return;
        }

        console.log('iframe event', event.data);
      });
    </script>
  </body>
</html>
```

---

# OptiView Player Web SDK

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Dolby OptiView Player is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md)

[Set up your first THEOplayer in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web.md)

## [🎨UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web.md)

[Choose a ready-made UI, customize with Open Video UI, or build from scratch.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web.md)

## [🛝Examples](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples.md)

[See the player in action!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples.md)

## [🔌Connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web.md)

[Integrate third-party solutions with THEOplayer using our pre-built connectors.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md)

[Find out what's new in the OptiView Player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md)

## [\*️⃣API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web)

[Discover all properties and functions of THEOplayer.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

# Getting started on Web

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Dolby OptiView Player is the universal video player solution from Dolby. The HTML5/Tizen/webOS Player SDK offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

This article is your starting point if you are using Dolby OptiView Player for the first time. It takes you through the required steps to achieve a basic manual implementation of the Player SDK on Web. The outcome of this article is the template below.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="SDK-LIBRARY-LOCATION/ui.css" />
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
    <script src="SDK-LIBRARY-LOCATION/THEOplayer.js"></script>
    <script>
      var element = document.querySelector('.theoplayer-container');
      var player = new THEOplayer.Player(element, {
        libraryLocation: 'SDK-LIBRARY-LOCATION',
        license: 'YOUR-LICENSE-STRING',
      });
      player.source = {
        sources: [
          {
            src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
            type: 'application/x-mpegurl',
          },
        ],
      };
    </script>
  </body>
</html>
```

> **Note**
>
> When copy-pasting the above code, make sure to replace the placeholders `YOUR-LICENSE-STRING` and `SDK-LIBRARY-LOCATION` with your license and library location respectively. [See below for more information.](#build-configure-and-publish-sdk)

## Prerequisites

Before we can start using THEOplayer, you'll need a few things:

1. A web server and domain name to host your code and provide access to viewers.
2. A THEOplayer SDK and license to implement the THEOplayer library and access the THEOplayer API.
3. A video stream (e.g. an `.m3u8` or `.mpd` file) to show to your viewers through the THEOplayer API.

### Installing THEOplayer Web SDK

The THEOplayer Web SDK is available on npm: <https://www.npmjs.com/package/theoplayer>. Installation can be done using your favorite package manager for Node (such as `npm` or `yarn`):

```bash
npm install theoplayer
```

You can also install a specific version instead:

```bash
npm install theoplayer@7.0.0
```

Different THEOplayer packages are available on npm with their own included features. Choose the package which best fits your requirements. In the rest of the guide we reference `SDK-LIBRARY-LOCATION` which should become the path to the installed theoplayer package in your node modules, similar to: `path/to/node_modules/theoplayer/`.

> **Custom Web SDK**
>
> We do recommend downloading the THEOplayer Web SDK through npm, but if you need a custom SDK with a different combination of features it is possible to create one on [the Portal](https://portal.theoplayer.com/login). Skip to [Create an SDK through Portal](#create-an-sdk-through-portal) for a detailed explanation.

### Getting a THEOplayer License

Creating a Web SDK on the Portal can be achieved by the following steps:

1. [Register and sign in](#register-and-sign-in)
2. [Initiate license creation](#initiate-license-creation)
3. [Build, configure and publish license](#build-configure-and-publish-license)

#### Register and sign in

You register with your GitHub or Google account through the [sign-in page](https://portal.theoplayer.com/login), or complete the [signup form](https://portal.theoplayer.com/register). You sign in with your GitHub or Google account, or with your credentials, through the sign-in page.

#### Initiate license creation

On the THEOplayer Developer Portal dashboard, click the Create button in the licenses panel, as annotated with a red arrow in the following screenshot.

![THEOplayer Developer Portal\&#39;s dashboard](/pr-932/assets/images/portal-dashboard-b6d20084c1941c5e96902bd8c3a4a92e.png)

Alternatively, you create a license through the SDKs page.

* You click the SDKs item in the side navigation panel to navigate to the overview of your existing SDKs.
* The content panel of the SDKs page presents action buttons. Click the Create button to initiate the license creation process, as highlighted in the screenshot below.

![THEOplayer Developer Portal SDK Page](/pr-932/assets/images/portal-sdk-b439507beb50e04557eefb9e763db28b.png)

#### Build, configure and publish license

Building your license involves three steps.

1. Choose platform – Select the HTML5 icon highlighted with the red circle in the following screenshot. HTML5 applications (i.e. websites, progressive web apps) use the THEOplayer Web SDK.
2. Configure license – Name the license and configure your domain whitelisting settings. The latter allows your license to only function for some websites and/or streams.
3. Review and publish – Validate your configuration and click "Publish", or go back.

![Choose platform](/pr-932/assets/images/portal-choose-platform-23ce30a0d4c2ea5364a6429c679bfb39.png)

After you complete the third step, "Review and Publish", you will get your unique LICENSE which should replace `YOUR-LICENSE-STRING` in the examples.

![License generated](/pr-932/assets/images/portal-license-86831573290e72f6ab522fba40572050.png)

### Create an SDK through Portal

> **Info**
>
> We recommend [downloading the THEOplayer SDK through npm](#installing-theoplayer-web-sdk) for most use cases. If you need an SDK with custom features, you can follow the next steps. Otherwise, skip to [Basic setup](#basic-setup).

Creating a Web SDK on the Portal can be achieved by the following steps:

1. [Register and sign in to Portal](#register-and-sign-in-to-portal)
2. [Initiate SDK creation](#initiate-sdk-creation)
3. [Build, configure and publish SDK](#build-configure-and-publish-sdk)

#### Register and sign in to Portal

You register with your GitHub or Google account through the sign-in page, or complete the signup form. You sign in with your GitHub or Google account, or with your credentials, through the sign-in page.

#### Initiate SDK creation

To create an SDK through Portal similar steps should be followed as generating a license only. On the dashboard or in the SDKs menu, also click the Create button. Important here is to make sure you are on the CUSTOM tab as this will allow creating a custom SDK with a license instead of only a license.

![THEOplayer Developer Portal\&#39;s dashboard custom](/pr-932/assets/images/portal-custom-sdk-5d9ea6fb504a6ebe49b949014e1dc9a6.png)

Alternatively, when following the steps to generate only a license there will be redirect link to the steps for creating a custom THEOplayer SDK.

![Custom SDK redirect](/pr-932/assets/images/portal-sdk-redirect-fd80f250b0a7d315392169ff414ea16e.png)

#### Build, configure and publish SDK

Building your Web SDK involves four steps.

1. Choose platform – Select the HTML5 icon highlighted with the red circle in the following screenshot. HTML5 applications (i.e. websites, progressive web apps) use the THEOplayer Web SDK.
2. Configure SDK – Name the SDK and configure your domain whitelisting settings. The latter allows you to restrict your SDK to only function on your own websites and/or streams.
3. Select features – Enable certain features (e.g. HLS advertising) and disable others (e.g. Chromecast).
4. Review and publish – Validate your configuration and click "Publish", or go back.

![Build SDK](/pr-932/assets/images/portal-build-sdk-246e4b4384d6eb310935338612b5a560.png)

After you complete the fourth step, "Review and Publish", it'll take the portal a couple of minutes to generate your unique SDK. Once you see the Ready! button, as the screenshot below highlights with the red rectangle, you know that your SDK is available.

![SDK ready](/pr-932/assets/images/portal-sdk-ready-5d3aa3e1aed98d820b77eb79e0f4523f.png)

The following sections of this guide reference `SDK-LIBRARY-LOCATION` which should be replaced with the SDK library location URL. Similarly, `YOUR-LICENSE-STRING` should be replaced with the LICENSE

## Basic setup

Now, we're ready to set up THEOplayer on your website. This guide explains how you implement THEOplayer in four steps:

1. We'll [start from a basic HTML file](#step-1-set-up-an-html-file), with no mention of THEOplayer.
2. In the [second step](#step-2-including-the-theoplayer-library), we'll explain what the THEOplayer library is and how you can include it. We'll do the same for the default THEOplayer UI.
3. In the [third step](#step-3-the-video), we'll describe how you play a video stream through THEOplayer.
4. In the [fourth step](#step-4-the-result), we'll give a final overview.

### Step 1: Set up an HTML file

When THEOplayer is used as a web video player, we will need a web page (i.e. HTML file) to embed THEOplayer and the code.

Note that a THEOplayer SDK license can only be used on whitelisted domains. You configure these domains when you create a THEOplayer license at <https://portal.theoplayer.com>.

Let's start with the following HTML file:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
  <body></body>
</html>
```

Next, we’ll include the THEOplayer SDK.

### Step 2: Including the THEOplayer library

To access the THEOplayer API and default UI, you must first include the THEOplayer library files. The JavaScript library exposes the THEOplayer API and the CSS library contains the default UI.

> **Customize your player with Open Video UI**
>
> The Web SDK includes a basic default UI. When you need a more customized player, Open Video UI provides ready-made components that you can compose and style instead of building every control from scratch. [Get started with Open Video UI for Web.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/getting-started.md)

#### THEOplayer JavaScript library

In a previous step, we downloaded the [THEOplayer npm package](#installing-theoplayer-web-sdk) or created a [custom THEOplayer SDK](#create-an-sdk-through-portal). Now we'll include it in our HTML file. There are two options for this:

* Option 1: in your HTML

  ```html
  <script src="SDK-LIBRARY-LOCATION/THEOplayer.js"></script>

  <!-- or if you only need the chromeless version (without UI) -->
  <script src="SDK-LIBRARY-LOCATION/THEOplayer.chromeless.js"></script>
  ```

  The `<script>` tag can include an external JavaScript library on a web page. In this case we use it to include the THEOplayer library.

  The `src` attribute is the URI of the THEOplayer library that you wish to use. This could be something like: `'SDK-LIBRARY-LOCATION/THEOplayer.js'`, where the URL is a link to your THEOplayer.js file.

* Option 2: in your JavaScript

  ```javascript
  import * as THEOplayer from 'theoplayer';

  // or if you only need the chromeless version (without UI):
  import * as THEOplayer from 'theoplayer/chromeless';
  ```

  > **Legacy browser support**
  >
  > Starting with THEOplayer 6.0, this will import a JavaScript module targeting modern browsers, using modern JavaScript syntax such as [`async/await`](https://caniuse.com/async-functions). If you need to support older browsers (such as older smart TVs), then you'll need to use option 1 instead as this creates a global `THEOplayer` variable that exposes the full API.

#### THEOplayer CSS library

To use the default THEOplayer UI, you need to reference the THEOplayer CSS library:

```html
<link rel="stylesheet" type="text/css" href="SDK-LIBRARY-LOCATION/ui.css" />
```

The `<link>` tag includes a CSS file on a web page. Similar to the JavaScript library, you must swap `SDK-LIBRARY-LOCATION` with your actual library location.

Next, we’ll create a THEOplayer instance and configure a video stream.

### Step 3: The video

To play a video through the THEOplayer Web SDK, you must:

1. Create a video player container element.
2. Retrieve a reference to this container through JavaScript.
3. Create a THEOplayer instance associated with that container.
4. Configure a video stream for this instance.

The snippet below implements these 4 steps:

```html
<div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
<script src="SDK-LIBRARY-LOCATION/THEOplayer.js"></script>
<script>
  // Retrieve the THEOplayer container div
  var element = document.querySelector('.theoplayer-container');

  // Create the video player
  var player = new THEOplayer.Player(element, {
    libraryLocation: 'SDK-LIBRARY-LOCATION', // references folder containing your THEOplayer library files (theoplayer.p.js, THEOplayer.js, ...)
    license: 'YOUR-LICENSE-STRING', // references your THEOplayer SDK license
  });

  // HLS
  player.source = {
    sources: [
      {
        src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8', // sets HLS source
        type: 'application/x-mpegurl', // sets type to HLS
      },
    ],
  };

  // DASH
  // player.source = {
  //   sources: [
  //     {
  //       src: '//cdn.theoplayer.com/video/cosmos/cmaf.mpd', // sets DASH source
  //       type: 'application/dash+xml', // sets type to MPEG-DASH
  //     },
  //   ],
  // };
</script>
```

Let's break down the above snippet.

#### Create video player container

This `<div>` element creates a video player container.

```html
<div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
```

* The `theoplayer-container` class is used to fetch the container through JavaScript, as demonstrated by the snippet below.
* The `video-js theoplayer-skin vjs-16-9` classes load the default THEOplayer UI. You may omit `vjs-16-9` if you don't want a 16:9 container.

Setting the size of the container

There are other approaches to setting the size of your container instead of using `vjs-16-9`. For example, you could omit the `vjs-16-9` class, and instead configure the width and height of container class through CSS.

```css
.theoplayer-container {
    width: 200px;
    height: 200px;
}
```

![screenshot from a sample minimal page with THEOplayer, showing how to use the width and height to change the size of the player](/pr-932/assets/images/container-height-percent-f3c137751a4bcaf899cbe1717cfe5363.png)

Alternatively, you set your container to be responsive to its parent node by setting `fluid: true` in your configuration, as demonstrated by the following screenshot.

```js
var player = new THEOplayer.Player(element, {
    fluid: true
    // ...other options go here
});
```

![screenshot from a sample minimal page with THEOplayer, showing how to use the playerConfig property fluid to regulate the player size](/pr-932/assets/images/container-height-fluid-8b4b6a4d519bed788ed2231a26a8b1ab.png)

There is no wrong or right. It's up to you to decide which approach is best for your use-case.

```javascript
var element = document.querySelector('.theoplayer-container');
```

#### Create THEOplayer instance

The snippet below creates a THEOplayer instance for a container with a specific [Player Configuration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerConfiguration).

```js
var player = new THEOplayer.Player(element, {
  // instantiates the video player
  libraryLocation: 'SDK-LIBRARY-LOCATION', // references folder containing your THEOplayer library files (theoplayer.p.js, THEOplayer.js, ...)
  license: 'YOUR-LICENSE-STRING', // references your THEOplayer SDK license
});
```

Similar to the JavaScript and CSS library, you must swap out `SDK-LIBRARY-LOCATION` and `YOUR-LICENSE-STRING`.

You can read more about configuring the `license` at the [License section](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/license/introduction.md).

#### Configure video stream

The snippet below configures a HLS video stream for the THEOplayer instance.

```js
player.source = {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8', // sets HLS source
      type: 'application/x-mpegurl', // sets type to HLS
    },
  ],
};
```

To configure a DASH stream instead, you must set `type` to `'application/dash+xml'` instead of `'application/x-mpegurl'`, as demonstrated by commented out code in one of the earlier snippets.

In the next step we'll put everything together.

### Step 4: The result

Use the snippet below on your web server.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="SDK-LIBRARY-LOCATION/ui.css" />
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
    <script src="SDK-LIBRARY-LOCATION/THEOplayer.js"></script>
    <script>
      var element = document.querySelector('.theoplayer-container');
      var player = new THEOplayer.Player(element, {
        libraryLocation: 'SDK-LIBRARY-LOCATION',
        license: 'YOUR-LICENSE-STRING',
      });
      player.source = {
        sources: [
          {
            src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
            type: 'application/x-mpegurl',
          },
        ],
      };
    </script>
  </body>
</html>
```

## Bundler setup

When using a [bundler](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Overview) such as [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/), [Vite](https://vitejs.dev/) or [Parcel](https://parceljs.org/) you may need some additional configuration to make your bundler copy all files needed by the THEOplayer Web SDK and set your `libraryLocation` correctly.

> **Just give me the code!**
>
> If you prefer starting from a fully working example rather than copy-pasting these snippets into your code, check out [our examples on GitHub](https://github.com/THEOplayer/samples-npm-html5-sdk)!

What is a `libraryLocation`?

The THEOplayer Web SDK uses [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) to off-load several CPU-intensive tasks to a separate worker thread. By moving these tasks off the main thread, THEOplayer ensures that your app remains fast and responsive.

The code for these workers is located in separate JavaScript files, outside the main THEOplayer library. The THEOplayer Web SDK ships with several of these files, such as:

* `THEOplayer.transmux.js`: responsible for transmuxing MPEG-TS and AAC files to fragmented MP4.
* `theoplayer.d.js`: responsible for decrypting HLS segments encrypted with full-segment AES-128 encryption.

Additionally, some of these workers leverage [WebAssembly](https://developer.mozilla.org/en-US/docs/WebAssembly) for improved performance:

* `THEOplayer.transmux.wasm`: the WebAssembly binary for transmuxing MPEG-TS and AAC files.

These files need to be hosted on your app's server, so the main THEOplayer library can locate and load them when needed. You tell THEOplayer where you put those files by setting the `libraryLocation` in your [player configuration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerConfiguration).

JavaScript bundlers work by traversing your app's dependencies through `import` or `require()` statements in your source code. As such, they can't auto-magically detect that THEOplayer needs these extra files, since they are never directly imported. You'll need to configure your bundler to *also* copy these extra files to your app's output directory.

### Webpack

Use [`copy-webpack-plugin`](https://webpack.js.org/plugins/copy-webpack-plugin/) to copy the THEOplayer files to the output directory.

webpack.config.js

```js
const CopyPlugin = require('copy-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: __dirname + '/dist',
  },
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          context: 'node_modules/theoplayer/',
          from: './*.(css|js|html|wasm)',
          info: { minimized: true },
          to: 'vendor/theoplayer/',
        },
      ],
    }),
  ],
};
```

Then, configure your library location:

src/index.js

```js
import * as THEOplayer from 'theoplayer';

var player = new THEOplayer.Player(element, {
  libraryLocation: '/vendor/theoplayer/',
  license: 'YOUR-LICENSE-STRING',
});
```

### Rollup

Use [`rollup-plugin-copy`](https://webpack.js.org/plugins/copy-webpack-plugin/) to copy the THEOplayer files to the output directory.

rollup.config.js

```js
import copy from 'rollup-plugin-copy';

export default {
  input: {
    bundle: './src/index.js',
  },
  output: {
    dir: './dist',
  },
  plugins: [
    copy({
      targets: [
        {
          src: './node_modules/theoplayer/*.(js|css|html|wasm)',
          dest: './dist/vendor/theoplayer',
        },
      ],
    }),
  ],
};
```

Then, configure your library location:

src/index.js

```js
import * as THEOplayer from 'theoplayer';

var player = new THEOplayer.Player(element, {
  libraryLocation: '/vendor/theoplayer/',
  license: 'YOUR-LICENSE-STRING',
});
```

### Vite

Use [`vite-plugin-static-copy`](https://www.npmjs.com/package/vite-plugin-static-copy) to copy the THEOplayer files to the output directory.

vite.config.js

```js
import { defineConfig } from 'vite';
import { viteStaticCopy } from 'vite-plugin-static-copy';

export default defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        {
          src: 'node_modules/theoplayer/*.(css|js|html|wasm)',
          dest: 'vendor/theoplayer/',
        },
      ],
    }),
  ],
});
```

Then, configure your library location:

src/index.js

```js
import * as THEOplayer from 'theoplayer';

var player = new THEOplayer.Player(element, {
  libraryLocation: `${import.meta.env.BASE_URL}vendor/theoplayer/`,
  license: 'YOUR-LICENSE-STRING',
});
```

### Parcel

Use [`parcel-reporter-static-files-copy`](https://www.npmjs.com/package/parcel-reporter-static-files-copy) to copy the THEOplayer files to the output directory.

.parcelrc

```json
{
  "extends": ["@parcel/config-default"],
  "reporters": ["...", "parcel-reporter-static-files-copy"]
}
```

package.json

```json
{
  "name": "my-app",
  "staticFiles": {
    "staticPath": "node_modules/theoplayer/",
    "distDir": "dist/vendor/theoplayer/"
  }
}
```

Then, configure your library location:

src/index.js

```js
import * as THEOplayer from 'theoplayer';

var player = new THEOplayer.Player(element, {
  libraryLocation: '/vendor/theoplayer/',
  license: 'YOUR-LICENSE-STRING',
});
```

## Next steps

Ready to learn more?

* Go through our [how-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web.md) to learn about [UI customization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web.md), [advertising](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/introduction.md), [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md), [casting](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/introduction.md), [analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/introduction.md) and other topics.
* Check out our [API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer).
* Try out samples from our [GitHub](https://github.com/THEOplayer).

---

# API examples

This page contains an overview of examples, demonstrating the capabilities of the THEOplayer API and custom JavaScript. With these examples, we try to explain the fundamentals of how to use our API:

* Accessing **player properties** and using **methods** (e.g. *currentTime*, *duration*, ...) ,

* Hooking to **events**,

* Inserting DOM-elements (buttons, text, ...) in the **UI**

* ...

The examples are sorted per subject, and a link can re-appear if it also relates to another subject. New examples will be added from time to time, when new use cases arise, or when new developments happen.

If you are new to THEOplayer, please read our [Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md) or our [API pages](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web).

## Properties and methods

* <http://demo.theoplayer.com/creating-bookmarks-with-js-css-theoplayer> — Demonstrates how to use basic player properties and the *play()* method to create your own bookmarks, and load those settings into your active player.

* <http://demo.theoplayer.com/keeping-track-of-currenttime-timeupdate> — Demonstrates a use case of the *currentTime*, *played* and *buffered* properties.

* [Ad block detection](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/ad-block-detection.md) — Demonstrates how to use ad block detection.

* [Advertisement tester](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/advertisement-tester.md) — Demonstrates how to schedule an advertisement.

## Events

* <http://demo.theoplayer.com/using-events-examples> — Demonstrates how to listen to player events as *playing* and *pause*, and ad events as *adbegin*.

* <http://demo.theoplayer.com/keeping-track-of-currenttime-timeupdate> — Demonstrates a use case of the *timeupdate* and *loadeddata* event.

* <http://demo.theoplayer.com/implementing-continuous-play-with-js-cookies-theoplayer> — Demonstrates how to save the playhead position and restore it, using cookies.

* [Ad block detection](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/ad-block-detection.md) — Demonstrates how to use ad block detection.

## UI

* <http://demo.theoplayer.com/adding-buttons-text-overlay-to-theoplayer> — Demonstrates how to insert a button in the control bar, overlay a container and overlay text.

* <http://demo.theoplayer.com/changing-default-player-ui-css> — Demonstrates how to change some elements (e.g. re-color progress bar, change control bar icon) of the default UI.

* <http://demo.theoplayer.com/chromeless-ui-js-html-css> — Demonstrates how to create a minimal chromeless UI.

* [Adding buttons](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/adding-buttons.md) - Demonstrates how to insert buttons which can jump back/forth in time.

* <http://demo.theoplayer.com/language-localization> - Demonstrates how to configure language localization.

* <http://demo.theoplayer.com/custom-center-controlbar> - Demonstrates how to create custom centered control bar

* <http://demo.theoplayer.com/fullscreen-social-controlbar> - Demonstrates how to create a custom social control bar which is only visible when the player is in fullscreen mode

* [Playlist and caching](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/playlist-and-caching.md) - Demonstrates how to build a playlist which can preload upcoming content

* <http://demo.theoplayer.com/player-background-image> - Demonstrates how to set a background image for the player

* <http://demo.theoplayer.com/using-custom-error-messages> - Demonstrates how to display custom error messages

---

# Getting started with Accessibility

Integrating accessibility features on the web is crucial to accommodating viewers with limitations, optimize the general viewer experience and maximize overall reach. The basis of video accessibility means that viewers with disabilities can perceive, understand, navigate, and engage with video content equally, and without obstacles or barriers. Additionally, accessibility can apply to all viewers, regardless of disability or not (i.e. situational limitations, slow internet connection, temporary disabilities, etc.). In this guide we discuss what guidelines to follow to make your content accessible, the legal bodies in place, why accessibility is important, as well as what features are available for OptiView player to make video content accessible.

## Web Content Accessibility Guidelines

*The Web Content Accessibility Guidelines (WCAG)* are created by both individuals and organizations, and are seen as the standard for accessible web content internationally. Those organizations are formally known as the Accessibility Guidelines Working Group (AG WG) which is part of the World Wide Web Consortium (W3C) Web Accessibility Initiative (WAI). The guidelines are created to help individuals and organizations across the world make their online content accessible to all viewers, including those with disabilities. Online content is seen by the WCAG as information such as text, image, video, audio, and also as any code that determines structure, UI presentation, and more. You can find the full overview of WCAG guidelines [on their website](https://www.w3.org/WAI/standards-guidelines/wcag/).

There are three levels to the WCAG: A, AA, and AAA:

* A: the basic/bare minimum accessibility functionalities
* AA: decently accessible, where most organizations tend to stand
* AAA: very accessible, top tier accessibility

What is new in WCAG? WCAG 2.1 was updated in 2018. The success criteria from WCAG 2.0 are included verbatim in WCAG 2.1, but 17 additions were included in 2.1 to address mobile accessibility, viewers with low vision and viewers with cognitive and learning disabilities. WCAG 2.0 and 2.1 are backwards compatible, or in other words, if an organization adheres to 2.1 they also adhere to 2.0.

The additions in 2.1 require online content to be adaptable, distinguishable, compatible, keyboard accessible, have functional modalities, be safe for those with seizures or physical reactions, and have ‘enough time’ capabilities. To view the technical documentation of the WCAG 2.1 and use case examples, [visit their website here](https://www.w3.org/WAI/standards-guidelines/).

WCAG 2.2 was updated in 2024. The 2.0 and 2.1 success criteria are essentially the same in 2.2, with one exception: Parsing is obsolete and removed from WCAG 2.2.

OptiView Player is a single player across all major mobile devices, platforms and browsers, and our video player solution is upgraded with accessibility capabilities to adhere to WCAG across all of them, out of the box.

## User Agent Accessibility Guidelines (UAAG)

Under the WCAG is the User Agent Accessibility Guidelines (UAAG), which encompasses web browsers, browser extensions and media players, and the UAAG targets developers. The UAAG was created to primarily provide alternative information for those who want to remain compliant with WCAG, but are using a variety of different technologies and platforms. For example, some accessibility needs are met through the browser the viewer is using, while others are better met through the media content.

UAAG is seen as relevant for the future of accessibility, especially for mobile device accessibility. Mobile devices show the need for accessibility within a combination of UI, the content and applications used. UAAG also highlights the need for more accessibility features that work seamlessly across devices, platforms, and browsers. If you would like to explore more about UAAG specifically, check out the documentation with [standards and guidelines from WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/).

## Why is WCAG important for Video?

Complying with the WCAG is crucial for all publishers of online content, particularly video content. By ignoring accessibility, you are losing a large chunk of your audience. By a large chunk, we mean 15% of the world’s population who have at least one disability. By implementing accessibility features you are including everyone, reaching more viewers and increasing your traffic and SEO rankings.

Not only is accessibility important for rankings and to those with disabilities, but it is also adds to the viewer experience and usability for non-disabled viewers as well. For example, if a viewer is in a noisy or quiet environment, or the viewer is a non-native speaker of the language used in the video, subtitles will allow them to still enjoy the video content. Keyboard accessibility can be of great use to those viewers whom may not have a mouse or have a temporary injury.

# Accessibility Features

OptiView Player integrates the following features for accessibility:

### Text Tracks

Text Tracks (i.e. video captions or subtitles) are the audio from a video, but in text form. This includes words that are spoken, who is speaking (if it isn’t clear) and important noises such as music. This can help viewers who are hearing impaired in any capacity, or those with cognitive or learning disabilities. These captions can also benefit those general viewers whom, for example, may be in a loud, or silent, viewing environment. You can seamlessly integrate this feature into your OptiView Player. For more information on integrating Text Tracks into OptiView player and the supported formats, see our [guide on text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/introduction.md).

### Text Track Style

Text track style allows for the text in video captions to be displayed in a way the text is readable. This involves adapting the text color, font, size, spacing and other text properties. This makes the audio and video captions accessible to those with low vision, dyslexia, and/or cognitive or learning disabilities. This feature also makes your content more adaptable to different devices and browsers, content translation and personal preferences for caption viewing. This feature goes hand-in-hand with Text Tracks, and can be easily integrated in your OptiView player. For more on this feature, see this section of our [guide on text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/insert-subtitles.md#subtitle-styling).

### Accessibility Roles for Tracks

The OptiView player can expose the type of text or audio track programmatically through the API via `AccessibilityRole`. These roles allow assistive technologies to recognize the purpose of each track automatically. See more in our [API Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/AccessibilityRole).

Common roles are:

* *Captions*: speech + non-speech audio cues
* *Subtitles*: translation, no non-speech audio cues
* *Audio Descriptions*: narration of visual content)
* *Sign Language*: describes a sign-language track

### Focus Style

Focus Style allows the buttons on the video player (the control bar, menu items, close buttons, etc.) to be outlined in order to make them more visible when they are clicked or hovered over. This feature makes it easier for all viewers to see and understand which buttons are in use and which one they have selected. Also while hovered over, the Tooltips feature can make it easier for users by giving them a text description of the button on the UI. For example, when hovered over the mute button, it is outlined and a readers also see the word "Mute" appear on their UI. You can change the look of the default UI with our [UI Skinning Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/ui-skinning.md) or fully customize every element of your video player with our [Open Video UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md).

### User Interface Customization

User Interface, or UI, is the aspect of the video content that the viewer engages with. For viewers with disabilities, it is important that colors have sufficient contrast with the text and its background. The contrast is not limited to captions, but also includes the text on images, buttons and icons. This feature is especially helpful for viewers with color blindness or low contrast visibility, which is common in aging viewers, as well as viewers in difficult light conditions. It is also important for the video player to have a clear layout and design, to make it as easy and accessible to all viewers as possible. You can change the look of the default UI with our [UI Skinning Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/ui-skinning.md) or fully customize every element of your video player with our [Open Video UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md).

### Keyboard Compatibility

This allows for viewers to navigate the UI (i.e. buttons, links, player functions) via the keyboard. This feature is helpful for viewers who are physically unable to use a mouse, or those viewers who are visually impaired and unable to see the player UI. To customize keyboard presses, refer to our [guide on keyboard hotkeys](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/how-to-implement-hotkeys.md).

Our universal player is focused on the mandatory guidelines, and is compliant with those guidelines set out by the WCAG 2.2, the EU Web Accessibility Directive, as well as other guidelines for regions across the world. It is also important to note that different countries and regions of the world can have different guidelines and regulations. For an extensive list of guidelines and regulations per country or region, and all of the standards and specifications related to accessibility, please visit the [WCAG website](https://www.w3.org/WAI/standards-guidelines/wcag/).

### Screen Reader Support

The OptiView player supports screen readers across different platforms including VoiceOver for Mac/iOS and Narrator for Windows. For more detail on the WCAG success criterion, refer to [SC 1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html).

### Bookmarks, Chapter Markers, and Thumbnails

The player supports thumbnails, bookmarks and chapter markers as alternative navigation aids for time-based media.

* [Reference for Bookmarks](https://optiview.dolby.com/docs/theoplayer/getting-started/sdks/web/api-examples/#properties-and-methods)
* [Reference for Chapter Markers](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/what-are-chapter-markers.md)
* [Reference for Thumbnails](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/preview-thumbnails.md)

### Other Features

There are a few other features of the OptiView player which adhere to the WCAG guidelines. Specifically:

* *orientation*: the player adapts itself out of the box to different device orientations (and advanced controls for this are also available).
* *audio controls*: Audio controls are available, including a mute button, and a pause button (also during ads); player adheres to browsers autoplay policies
* *speed*: the player speed can be customized, so fast-paced subtitles can be showed for longer times

---

# How to implement Keyboard Hotkeys

This how-to guide describes how you can implement keyboard shortcuts in THEOplayer. Hotkeys allow viewers to also control THEOplayer functionality by using their keyboard.

## TLDR:

1. Add an id attribute to the player element in your HTML.

2. **Copy, Paste** and **Link** [this script](#full-javascript-code-example) in your HTML to enable the following set of hotkeys.

## List of Hotkeys

Keyboard hotkeys are not an 'out-of-the-box' feature provided by THEOplayer. This means you'll have to insert a bit of custom code to enable this functionality.

The script below will implement the following shortcuts:

* Spacebar : Toggles between Pause and Play.
* Left Arrow: Rewinds the video. (default: 5s)
* Right Arrow: Forwards the video. (default: 5s)
* Up Arrow: Increases the volume.
* Down Arrow: Lowers the volume.
* ' F ' Key: Toggles fullscreen mode.
* ' M ' Key: Toggles audio mute.

## Step-by-step Guide

### 1. THEOplayer-wrapper

Because the hotkeys we're about to include also have default browser functionality (e.g. space bar skipping down the page), we have two options:

1. Disable default browser hotkeys and overwrite them with our custom player hotkeys.

2. Enable THEOplayer hotkeys only when the viewer's mouse is inside the player area or when the player is focused.

Start by adding an id attribute to the player element in your HTML:

```html
<div id="yourPlayerId" class="video-js theoplayer-skin"></div>
```

### 2. JavaScript

Make a new JavaScript file and include it to your project with the rest of your scripts.

First off we're going to make a variable that holds the element in which we want to check for user interaction.

```javascript
const wrapper = document.getElementById('yourPlayerId');
```

Next up are the individual functions:

### 2.1 Disabling Default browser hotkeys

#### preventStandardHotKeyActions()

With event[.preventDefault()](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) we prevent the pressed key from performing their default browser functionality.

In our case this will disable the 'keydown' event if conditions are met.

```javascript
function preventStandardHotKeyActions(event) {
  event.stopPropagation();
  event.preventDefault();
}
```

### 2.2 Pause and Play

#### togglePlay()

Switches between pausing and playing the video. This function is triggered by pressing the spacebar.

```javascript
function togglePlay() {
  if (player.paused) {
    player.play();
  } else {
    player.pause();
  }
}
```

### 2.3 Rewinding and Skipping

#### rewind()

Rewinds the video 5 seconds (default) back in time when triggered.

```javascript
function rewind() {
  player.currentTime -= 5; //Subtracts 5 seconds
}
```

#### forward()

Skips the video 5 seconds (default) forward in time when triggered.

```javascript
function forward() {
  player.currentTime += 5; //Adds 5 seconds
}
```

### 2.4 Volume Settings

#### increaseVolume()

Increases the THEOplayer's volume in 5% increments (default).

```javascript
function increaseVolume() {
  player.volume = Math.min(player.volume + 0.05, 1); //Increases volume by 5%
}
```

#### decreaseVolume():

Lowers the THEOplayer's volume in 5% increments (default).

```javascript
function decreaseVolume() {
  player.volume = Math.max(player.volume - 0.05, 1); //Lowers volume by 5%
}
```

### 2.5 Toggle Fullscreen

#### toggleFullScreen()

Checks what presentation mode THEOplayer is in and switches the presentation mode to 'fullscreen' or 'inline' accordingly.

```javascript
function toggleFullScreen() {
  if (player.presentation.currentMode === 'fullscreen') {
    player.presentation.requestMode('inline');
  } else {
    player.presentation.requestMode('fullscreen');
  }
}
```

### 2.6 Toggle Mute

#### toggleMute()

Turns THEOplayer's audio on or off.

```javascript
function toggleMute() {
  player.muted = !player.muted;
}
```

### 2.7 KeyPressed Event

#### getPressedKey()

This function gets the 'key' property of the event object that triggered it (In our case a 'keydown' event). [List of Key values](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)

Start by initiating a variable for any key's that are pressed ('pressedKey') and a variable called 'action' that's going to call one of the functions we made earlier.

Next we make a switch case where we check the event's 'key' property for the ones we want to catch (e.g. ArrowLeft, " " for space, ... etc). If there's a match, we assign the corresponding function to 'action' to call after our conditions have been met.

```javascript
function getPressedKey(event) {
  const pressedKey = event.key;
  let action;
  switch (pressedKey) {
    case ' ':
      action = togglePlay(); //Pauses or Unpauses with Space
      break;
    case 'ArrowLeft':
      action = rewind(); //Rewinds the video with the Left Arrow Key
      break;
    case 'ArrowRight':
      action = forward(); //Forwards the video with the Right Arrow Key
      break;
    case 'ArrowUp':
      action = increaseVolume(); //Increases volume with the Up Arrow Key
      break;
    case 'ArrowDown':
      action = decreaseVolume(); //Lowers volume with the Down Arrow Key
      break;
    case 'f':
      action = toggleFullScreen(); //Toggle Fullscreen mode with the 'F' Key
      break;
    case 'm':
      action = toggleMute(); //Toggle Mute with the 'M' Key
      break;
  }
  if (action && pressedKey !== 'Control' && pressedKey !== 'Alt' && pressedKey !== 'Shift') {
    action();
    preventStandardHotKeyActions(event); //Stops the default key behavior like jumping the page with space.
  }
}
```

### 2.8 Enable hotkeys with focus

#### playerFocused():

Next we will allow the use of the THEOplayer hotkeys whenever the active element on the site is an element inside the player.

Any element that the user interacts with is set to be the active element. (e.g.: pressing a button with the mouse or by selecting something with tab for example.)

The snippet below will catch when the active element changes. If this element is part of the THEOplayer, we will enable the use of player hotkeys.

```javascript
function playerFocused() {
  if (wrapper.contains(document.activeElement)) {
    document.addEventListener('keydown', getPressedKey);
  } else {
    document.removeEventListener('keydown', getPressedKey);
  }
}
```

### 2.9 Enable Hotkeys on mouseEnter

Since browsers have default hotkey functionality (like skipping down the page by pressing space), you may only want to allow the use of the hotkeys whenever the viewer is actively watching the player.

The following functions will handle that use-case.

#### mouseInPlayer()

Gets called when a viewer enters the specified wrapper area with their cursor.

Creates an eventListener for both 'keydown' events and when the viewer's mouse leaves the wrapper area we specified at the beginning.

```javascript
function mouseInPlayer() {
  //Adds listeners for the keydown event and mouse leave event
  document.addEventListener('keydown', getPressedKey);
  wrapper.addEventListener('mouseleave', mouseOutPlayer);
}
```

#### mouseOutPlayer()

Gets called when a viewer exits the wrapper area.

When the viewer has left the wrapper area, the unused eventListeners are removed.

```javascript
function mouseOutPlayer() {
  //Checks if the mouse leaves the player wrapper area
  wrapper.removeEventListener('mouseleave', mouseOutPlayer);
  document.removeEventListener('keydown', getPressedKey);
}
```

### 3.0 Enabling the Hotkeys

#### enableShortcuts()

This function lets you choose between enabling the hotkeys site-wide, or only enabling them when the viewer's mouse is inside the player or the player is focused.

When calling this function you can use:

1. `enableShortcuts();` -To enable THEOplayer hotkeys site-wide.
2. `enableShortcuts('mouseOver');` -To enable THEOplayer hotkeys when the viewer's mouse is inside the specified area.

```javascript
function enableShortcuts(method) {
  switch (method) {
    case 'mouseOver': //If the param reads 'mouseOver' shortcuts are only enabled when the mouse is inside of the player.
      wrapper.addEventListener('mouseenter', mouseInPlayer);
      break;
    case 'playerFocused': //If the param reads 'playerFocused' shortcuts are only enabled when the player is focused.
      document.addEventListener('focus', playerFocused, true);
      break;
    default:
      document.addEventListener('keydown', getPressedKey); //Else player shortcuts are always enabled.
  }
}
enableShortcuts('mouseOver');
```

***

## Full JavaScript Code Example

```javascript
const wrapper = document.getElementById('yourPlayerId');
const element = document.querySelector('.video-js');

const player = new THEOplayer.Player(element, {
  ui: {
    fluid: true,
  },
  libraryLocation: '/YourTHEOplayerLibraryLocation/',
  license: 'your-license-here',
});

player.source = {
  sources: ['https://example.mpd'],
  metadata: {
    images: [
      {
        src: 'https://thumbnail.jpg',
      },
    ],
    releaseDate: '2014-10-31',
    releaseYear: 2014,
    subtitle: 'My movie subtitle',
    title: 'My movie',
    type: 'movie',
  },
};

function togglePlay() {
  if (player.paused) {
    player.play();
  } else {
    player.pause();
  }
}

function rewind() {
  player.currentTime -= 5; //Subtracts 5 seconds
}

function forward() {
  player.currentTime += 5; //Adds 5 seconds
}

function increaseVolume() {
  player.volume = Math.min(player.volume + 0.05, 1); //Increases volume by 5%
}

function decreaseVolume() {
  player.volume = Math.max(player.volume - 0.05, 1); //Lowers volume by 5%
}

function toggleFullScreen() {
  if (player.presentation.currentMode === 'fullscreen') {
    player.presentation.requestMode('inline');
  } else {
    player.presentation.requestMode('fullscreen');
  }
}

function toggleMute() {
  player.muted = !player.muted;
}

function preventStandardHotKeyActions(event) {
  event.stopPropagation();
  event.preventDefault();
}

function getPressedKey(event) {
  const pressedKey = event.key;
  let action;
  switch (pressedKey) {
    case ' ':
      action = togglePlay(); //Pauses or Unpauses with Space
      break;
    case 'ArrowLeft':
      action = rewind(); //Rewinds the video with the Left Arrow Key
      break;
    case 'ArrowRight':
      action = forward(); //Forwards the video with the Right Arrow Key
      break;
    case 'ArrowUp':
      action = increaseVolume(); //Increases volume with the Up Arrow Key
      break;
    case 'ArrowDown':
      action = decreaseVolume(); //Lowers volume with the Down Arrow Key
      break;
    case 'f':
      action = toggleFullScreen(); //Toggle Fullscreen mode with the 'F' Key
      break;
    case 'm':
      action = toggleMute(); //Toggle Mute with the 'M' Key
      break;
  }
  if (action && pressedKey !== 'Control' && pressedKey !== 'Alt' && pressedKey !== 'Shift') {
    action();
    preventStandardHotKeyActions(event); //Stops the default key behavior like jumping the page with space.
  }
}

function playerFocused() {
  if (wrapper.contains(document.activeElement)) {
    document.addEventListener('keydown', getPressedKey);
  } else {
    document.removeEventListener('keydown', getPressedKey);
  }
}

function mouseInPlayer() {
  //Checks if the mouse is inside the player wrapper area
  document.addEventListener('keydown', getPressedKey);
  wrapper.addEventListener('mouseleave', mouseOutPlayer);
}

function mouseOutPlayer() {
  //Checks if the mouse leaves the player wrapper area
  wrapper.removeEventListener('mouseleave', mouseOutPlayer);
  document.removeEventListener('keydown', getPressedKey);
}

function enableShortcuts(method) {
  switch (method) {
    case 'mouseOver': //If the param reads 'mouseOver' shortcuts are only enabled when the mouse is inside of the player.
      wrapper.addEventListener('mouseenter', mouseInPlayer);
      break;
    case 'playerFocused': //If the param reads 'playerFocused' shortcuts are only enabled when the player is focused.
      document.addEventListener('focus', playerFocused, true);
      break;
    default:
      document.addEventListener('keydown', getPressedKey); //Else player shortcuts are always enabled.
  }
}

//enableShortcuts('mouseOver');    //Enable player shortcuts only when mouse inside the player area.
enableShortcuts(); //Always enable shortcuts.
```

## Additional Resources

* [preventDefault()](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault)

* [stopPropagation()](https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation)

* [List of Key values](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)

---

# How to embed an iframe

Embedding a video player through an `<iframe>` can be interesting for a number of reasons:

* You might want to easily embed your videos across different domains and brands.
* You want to facilitate social sharing on third-party websites through your viewers.
* You are using a service or framework which doesn't allow you to include custom JavaScript, but it does allow you to embed an `<iframe>`.

Regardless of your use-case: you can embed THEOplayer through an iframe on first-party and third-party domains.

The goal of this guide is to help you embed THEOplayer through an `<iframe>` by going through the following topics:

1. [\<iframe>](#iframe): what is an iframe?

2. [Implementation](#implementation): which THEOplayer APIs are relevant and how can I achieve my use-case?

   1. [Allowing embedding](#allowing-embedding)
   2. [Enabling fullscreen and other features](#enabling-fullscreen-and-other-features)
   3. [Deciding approaches](#deciding-approaches)
   4. [Considering limitations](#considering-limitations)
   5. [Adjusting UI and UX](#adjusting-ui-and-ux)

3. [Demo](#demo): resulting implementation and live demo

4. [Resources](#resources)

Just want to copy-paste code and view a live example? [Skip to the demo](#demo).

## \<iframe>

An iframe is an HTML tag, the [`<iframe>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) tag, which allows you to embed an HTML page (i.e. "a website") on your HTML page (i.e. "your website"). You come across iframes all the time when using the web. (*That YouTube video on that news website you just visited? That's an iframe. That Facebook or Twitter post which was embedded on that blog? That could also be an iframe. They are all HTML website pages which are embedded on another HTML website page.*)

```html
<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/GrOJkhIXifc"
  frameborder="0"
  allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen
></iframe>
```

The code snippet above represent an actual `<iframe>` tag. Adding this code snippet to the HTML of your website would embed <https://www.youtube.com/embed/GrOJkhIXifc>, which is a YouTube video. If you opened this link, you would see that it is a YouTube video which fits the entire size of your browser window.

![iframe YouTube example](/pr-932/assets/images/iframe-youtube-example-6ca52c8e328a867b3160d2e231adcd7a.png "iframe YouTube example")

As you can see, [the embedded page](https://www.youtube.com/embed/GrOJkhIXifc) is quite different from the "[real](https://www.youtube.com/watch?v=GrOJkhIXifc)" YouTube page. When you design and develop a page which should be embedded through an `<iframe>`, you optimize for this embedding use-case. Typically, your component (e.g. a video player) fills the entire browser window, and thus has a width and height of 100%. (You set the width and height of the `<iframe>` on your page, as can be seen from the above code snippet.)

We won't go into the pros and cons of using an `<iframe>` in this article. We do argue that you should try to avoid using iframes, because iframes can be [evil](https://www.blackburnlabs.com/iframe-evil/) and can cause [usability issues](https://www.ostraining.com/blog/webdesign/against-using-iframes). From our experience, most services and companies are trying to phase out iframes, and are instead embedding JavaScript code to render the same result.

## Implementation

When embedding THEOplayer through an `<iframe>` tag, you need to do a couple of things:

1. [Allow embedding](#allowing-embedding): you need to use the THEOplayer API to allow for embedding.
2. [Enable fullscreen (and other features)](#enabling-fullscreen-and-other-features): you might want to use the HTML API to allow certain features like fullscreen and autoplay.
3. [Decide approach](#deciding-approaches): you need to decide on a strategy on how to dynamically load content.
4. [Consider limitations](#considering-limitations): you need to be aware of the constraints and how to address them.
5. [Adjust UI and UX](#adjusting-ui-and-ux): you need to style your iframe tag.

### Allowing embedding

You can easily allow embedding by setting the `isEmbeddable`-flag in the THEOplayer's [`PlayerConfiguration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerConfiguration) to `true`, as demonstrated by the code snippet below.

```js
let playerConfiguration = {
  // ...
  libraryLocation: '</path-to-library>/',
  license: 'your-license-here',
  isEmbeddable: true,
  // ...
};
let player = new THEOplayer.Player(element, playerConfiguration);
```

Embedding THEOplayer through an `<iframe>` tag is disabled by default. Why?

* Your THEOplayer license (i.e. your THEOplayer Web SDK) has a set of whitelisted domains. Typically, you only whitelist domains where you deploy THEOplayer. Deploying your THEOplayer SDK on a non-whitelisted domain would result in a license error. Thus, you need to specify that a page which contains your THEOplayer Web SDK, may be embedded. You do not need to whitelist every domain which embeds your `<iframe>` tag.
* When embedding is allowed, and if third-party websites are embedding your THEOplayer video player, then those parties generate additional video views and impressions for your license. (Remember: THEOplayer charges you by the number of impressions.) Additionally, if your [iframe approach](#deciding-approaches) allows people to specify the video URL through the `<iframe>` tag, then third-parties could potentially piggyback for free on your (commercial) license if they reverse-engineer your approach.

### Enabling fullscreen and other features

If you want to allow your viewers to open your iframe in fullscreen, then you must explicitly enable the [`allowfullscreen`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowfullscreen)-attribute.

```html
<iframe src="player.html" frameborder="0" scrolling="no" width="100%" height="100%" allowfullscreen=""> </iframe>
```

On top of this, you want to configure the [`allow`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allow)-attribute and track its evolution.

```html
<iframe
  src="player.html"
  frameborder="0"
  scrolling="no"
  width="100%"
  height="100%"
  allow="accelerometer; autoplay; encrypted-media; fullscreen; gyroscope; picture-in-picture"
  allowfullscreen=""
>
</iframe>
```

Through this attribute, you can allow your iframe to access a set of [features](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy#Directives), like autoplay, Picture-in-Picture, DRM, and more.

### Deciding approaches

The previous section explains how you can make THEOplayer compatible with an `<iframe>`, but it doesn't explain the possible approaches for loading content and configurations. What do we mean with this? When you are embedding THEOplayer, you still need a mechanism to configure a stream URL and toggle settings like autoplay and mute. You don't want to create one HTML page per stream and combination of settings. Instead, you want to be able to embed one HTML page which is capable of dynamically configuring your stream and settings.

There are at least three approaches to pass along your stream URL and settings:

1. **Direct**: you pass along your stream URL and settings directly through the iframe URL and/or query parameters of the iframe URL. For example, your iframe URL could be similar to `https://cdn.theoplayer.com/demos/iframe/theoplayer.html?autoplay=false&muted=false&preload=none&src=//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8`. On your iframe page, you (*i.e. either your front-end or back-end*) would read out these four query parameters (or GET parameters), and then use those values to set up your THEOplayer instance and configure your stream URL and settings.
2. **Indirect**: you pass along an identifier through the iframe URL and/or query parameters of the iframe URL. For example, your iframe URL could be similar to `https://cdn.theoplayer.com/demos/iframe/video-123`. On your iframe page, you would read out this identifier (e.g. `video-123`), and do a call to a content management system (CMS) requesting data matching your identifier. This CMS would then return the actual stream URL and settings. You use this response to set up your THEOplayer instance and configure your stream URL and settings.
3. **Hybrid**: you pass along your stream URL indirectly or directly, and your settings directly or indirectly. For example, your iframe URL could be similar to `https://cdn.theoplayer.com/demos/iframe/video-123?autoplay=false&muted=false&preload=none`. On your iframe page, you would read out this identifier and the query parameters, and use the identifier to fetch the stream URL through a CMS, but configure your settings through the values of your query parameters.

Every approach has its trade-offs. Using a CMS is useful to avoid third-parties from loading their own streams through your iframe setup, but it does require you to spend resources on a CMS.

### Considering limitations

As hinted in the [\<iframe>](#iframe)-section, using iframes can incur some limitations. Some of those limitations can be addressed, and some of those cannot due to technological platform constraints.

* [Fullscreen might not work on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-does-fullscreen-not-behave-as-expected-on-ios.md): you can fix this.
* [Autoplay might not work](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-is-video-not-playing-automatically.md): you can fix this.
* [Chromecast does not work on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-does-chromecast-not-work-on-ios-chrome.md): you cannot address this.
* [The Visibility API does not work on IE11 and Safari](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-visibilty-api-doesnt-work-in-iframe-on-safari-and-ie11.md): you cannot address this on IE11.
* [Picture-in-Picture does not work as expected](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/picture-in-picture.md): you can address this by using native Picture-in-Picture instead, or by building a similar feature which creates a floating iframe component.

### Adjusting UI and UX

Styling the `<iframe>` element on your page, and the actual page behind the `<iframe>`, can be a challenge. Additionally, you may want to alter your user experience by implementing messaging between your page and the embed page.

1. [Styling \<iframe>](#styling-iframe)
2. [Styling embedded page](#styling-embedded-page)
3. [Communication between parent page and embedded page](#communication-between-parent-page-and-embedded-page)

#### Styling \<iframe>

Styling your `<iframe>` element is a breeze if you're using a fixed width and height: you can directly configure those through the `width` and `height` attributes as demonstrated below.

```html
<iframe src="player.html" frameborder="0" scrolling="no" width="800px" height="450px" allowfullscreen=""> </iframe>
```

However, more common is to rely on responsive styling, and not knowing your specific width and height. On top of wanting a responsive iframe, you usually want to respect the aspect ratio of your video. Basically, you want your `<iframe>` container to automatically -and appropriately- scale when the size of your browser window changes.

```html
<iframe src="player.html" frameborder="0" scrolling="no" width="100%" style="width:100%;aspect-ratio:16/9"> </iframe>
```

The above snippet demonstrates how you can achieve this.

* You want to set an `aspect-ratio` in the `style` of your `<iframe>` element. We've used `16/9` for a 16:9 aspect ratio, but you can change this to e.g. `4/3` for a 4:3 video.
* You want to disable the border around your iframe by specifying `frameborder="0"` and disable scrolling by specifying `scrolling="no"`.
* You want to maximize the width of your iframe by specifying `width="100%"`. The height will be computed automatically based on the `aspect-ratio`.

Of course, rather than using inline styling through the `style` attribute, you could also achieve the same through CSS. And, of course: this is not the only way to style your iframe element, but just one of the many ways.

#### Styling embedded page

You usually want your video player to fit the full width and height of your browser window, because it should fill the entire iframe container element.

```html
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <meta http-equiv="x-ua-compatible" content="ie=edge" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        width: 100%;
        height: 100%;
      }

      .theoplayer-container {
        width: 100%;
        height: 100%;
      }
    </style>
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin"></div>
  </body>
</html>
```

The above snippet demonstrates a way to achieve this.

* You want to remove all padding and margin, and give your document a `width` and `height` of 100%.
* You want your video player container, the `<div>` in the above snippet, to fill the entire document by setting its `width` and `height` to 100%.

#### Communication between parent page and embedded page

You may have a need for messaging between your parent page and your embedded page.

* If your video or ad break ends, you want to hide (or destroy) the iframe container on your parent page.
* If someone clicks a control button in your video player, you may want to know about this action in your parent page.

You can achieve this with cross-document messaging and the `postMessage` API. Please refer to the resources below to learn more on this:

* [Stackoverflow.com: how to communicate between iframe and the parent side](https://stackoverflow.com/questions/9153445/how-to-communicate-between-iframe-and-the-parent-site)
* [MDN: postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)
* [JavaScript.info: cross-window communication](https://javascript.info/cross-window-communication)

## Demo

The video player below this paragraph is embedded through an `<iframe>` tag.

[Embedded THEOplayer](https://cdn.theoplayer.com/demos/iframe/theoplayer.html?autoplay=false\&muted=false\&preload=none\&src=//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8)

We selected the "direct approach" by leveraging query parameters, as demonstrated by the code snippet below.

```html
<iframe
  src="https://cdn.theoplayer.com/demos/iframe/theoplayer.html?autoplay=false&muted=false&preload=none&src=//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8"
  title="Embedded THEOplayer"
  frameborder="0"
  scrolling="no"
  width="100%"
  style="width:100%;aspect-ratio:16/9"
  allow="accelerometer; autoplay; encrypted-media; fullscreen; gyroscope; picture-in-picture"
  allowfullscreen=""
>
</iframe>
```

If we had configured a different `src`-value, like `https://cdn.theoplayer.com/demos/iframe/theoplayer.html?autoplay=false&muted=false&preload=none&src=//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8`, then it would have loaded a different video. Note that unmuted autoplay may not be possible, and that you may have to [combat autoplay policies](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-combat-autoplay-policies.md).

You can see the code of the iframe HTML page at <https://cdn.theoplayer.com/demos/iframe/theoplayer.html>, or in the code snippet below.

```html
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <meta http-equiv="x-ua-compatible" content="ie=edge" />
    <link rel="stylesheet" type="text/css" href="/path/to/libraryLocation/ui.css" />
    <script src="/path/to/libraryLocation/THEOplayer.js"></script>
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        width: 100%;
        height: 100%;
      }

      .theoplayer-container {
        width: 100%;
        height: 100%;
      }
    </style>
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin"></div>
    <script>
      // https://stackoverflow.com/a/901144/588833
      // function to get URL query parameters by name
      function getParameterByName(name, url) {
        if (!url) url = window.location.href;
        name = name.replace(/[\[\]]/g, '\\$&');
        var regex = new RegExp('[?&]' + name + '(=([^&#]*)|&|#|$)'),
          results = regex.exec(url);
        if (!results) return null;
        if (!results[2]) return '';
        return decodeURIComponent(results[2].replace(/\+/g, ' '));
      }

      // initialize THEOplayer instance
      var element = document.querySelector('.theoplayer-container');
      var player = new THEOplayer.Player(element, {
        libraryLocation: '/path/to/libraryLocation/',
        license: 'your-license-here',
        ui: {
          width: '100%',
          height: '100%',
        },
        isEmbeddable: true,
      });

      // get query parameter values
      var autoplay = getParameterByName('autoplay') && getParameterByName('autoplay') == 'true';
      var muted = getParameterByName('muted') && getParameterByName('muted') == 'true';
      var preload = getParameterByName('preload');
      var src = getParameterByName('src');

      // set settings and stream URL
      player.autoplay = autoplay;
      player.muted = muted;
      player.preload = preload;
      player.src = src;
    </script>
  </body>
</html>
```

## Resources

* [Player API - PlayerConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerConfiguration)
* [iframe demo code](https://cdn.theoplayer.com/demos/iframe/theoplayer.html?autoplay=false\&muted=false\&preload=none\&src=//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8)
* [AMP](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/amp/getting-started.md) (consider translating your learning to the AMP framework)
* [MDN: iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)
* [ottball.com: lazy loading](https://ottball.com/lazy-loading-video/#embedded-players) (consider lazy loading for your iframes)

---

# How to implement a seamless transition between videos?

You may need an answer to this question if you want to play one video after the other without letting the user know the source has changed (to the user they will seem as if playing just one video). Similar questions may be:

* Is it possible to make 2 video files play one after the other without pause?
* How can I play a second video file after the first without the user notice what happened?
* How to make a forking video, one where the user can choose his/her own path?

**This result is achieved taking advantage of a HTML5 canvas element to cover the source change.** An example can be seen on [this page](http://cdn.theoplayer.com/demos/confluence/seamless-video-transition.html).

You can find the code of the page here below, opportunely commented to clarify how it works (hint: all interesting comments start with "COMMENT:" to aid the search).

Seamless video transitionExpand source

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <meta http-equiv="x-ua-compatible" content="ie=edge" />

    <title>Seamless video transition</title>
    <link
      rel="stylesheet"
      href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.5/css/bootstrap.min.css"
      integrity="sha384-AysaV+vQoT3kOAXZkl02PThvDr8HYKPZhNT5h/CXfBThSRXQ6jW5DO2ekP5ViFdi"
      crossorigin="anonymous"
    />
    <link rel="stylesheet" type="text/css" href="//cdn.theoplayer.com/dash/theoplayer/ui.css" />

    <script type="text/javascript" src="//cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>

    <style>
      canvas {
        width: 100%;
        height: 100%;
        position: absolute;
        display: none;
      }
      button {
        margin: 1em 0;
      }
    </style>
  </head>
  <body>
    <h1>Seamless video transition</h1>
    <div class="container">
      <div id="theoplayer-wrapper">
        <div class="video-js theoplayer-skin">
          <!-- COMMENT: a canvas element is set inside the THEOplayer wrapper. Initial sizes are set but will be reset when the canvas is called -->
          <canvas width="503px" height="283px"> </canvas>
        </div>
        <button id="sourcechange-btn">Change video</button>
      </div>
    </div>

    <script type="text/javascript">
      var element = document.querySelector('.video-js');

      // COMMENT: some player configuration here - interesting but nothing related to this example
      var player = new THEOplayer.Player(element, {
        ui: {
          //fluid: true
          width: '800',
          height: '450',
        },
        libraryLocation: '//cdn.theoplayer.com/dash/theoplayer/',
      });
      player.autoplay = true;
      player.source = {
        sources: '//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
      };

      //COMMENT: objective: hide the transition between 2 videos.
      // To do this, we:
      // - detect when the source must be changed
      // - save the last frame in the canvas poster that is placed on top of the player
      // - we load the new source
      // - when playback starts, the canvas is hidden

      // COMMENT: this detects the first play event and calls the function firstplay()
      player.addEventListener('sourcechange', function () {
        //console.log("A new SourceDescription has been set.");
        player.removeEventListener('playing', firstplay);
        player.addEventListener('playing', firstplay);
      });

      // COMMENT: on click we call writeToCanvas() and change the player source after a small delay (time is needed for the canvas content to be loaded)
      var button = document.querySelector('#sourcechange-btn');
      button.addEventListener('click', () => {
        writeToCanvas();
        setTimeout(function () {
          player.src =
            'https://amssamples.streaming.mediaservices.windows.net/bb34a723-f69a-4231-afba-dc850f9e3da8/ChildOfThe90s.ism/manifest(format=m3u8-aapl)';
        }, 50);
      });

      // COMMENT: canvas is hidden when the first play event is fired
      function firstplay(event) {
        var canvas = document.querySelector('canvas');
        player.removeEventListener('playing', firstplay);
        //console.log("first play event!", event);
        canvas.style.display = 'none';
      }

      // COMMENT:
      // (1) Canvas is detected, its sizes adapted to those of the player and it gets the last frame as content.
      // (2) It is displayed as block (as opposed to the initial "none")
      function writeToCanvas() {
        var canvas = document.querySelector('canvas');
        canvas.setAttribute('width', player.videoWidth + 'px');
        canvas.setAttribute('height', player.videoHeight + 'px');
        var ctx = canvas.getContext('2d');
        canvas.style.display = 'block';
        player.canvas.drawImage(ctx, 0, 0);
      }
    </script>
  </body>
</html>
```

The result on your page can also be improved implementing [cache](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Cache) for your videos.

---

# How to work around browser cache with new THEOplayer SDK libraries?

In some cases you may experience problems related to cached versions of the THEOplayer library (e.g. if you are dealing with users who are getting expired license errors even though you already deployed new SDK libraries).

Related questions may be:

* Can I implement a cachebuster on the THEOplayer library load?
* Can I force a file to be called always from the server to prevent it from being fetched from the cache?
* How can I make sure that users always get the newest version of THEOplayer libraries I deployed?

## Cache

To reduce the internet usage and increase the responsiveness of a webpage, browsers use caching.

In simple terms, it may take a while to download a file (e.g. `THEOplayer.js`). The browser will therefore keep files stored locally in its cache for a certain amount of time for later usage. After some time, the browser will remove the file and update it the next time you visit that page. By keeping it locally, the browser can use the local file instead of having to fetch a new one. This makes your page faster, but the downside is that the browser may not get the most up-to-date file.

If you really need users to use the latest library you serve or renew at the expiration date of your contract, you may still run into caching issues.

Luckily there are some ways to ensure that the browser updates the file.

## Ways to force the browser to update

### Change the file path

A good way to ensure that the file gets updated, is by changing the file path. If your file path is different, the browser will see all the files within that new directory as new files and download them again.

You could, for example, keep track of the version of THEOplayer or the deploy date by using different directories:

For example:

```html
<yoursite.com
  >/resource/file/path/5.5.0/THEOplayer.js
  <yoursite.com
    >/resource/file/path/5.5.1/THEOplayer.js <yoursite.com>/resource/file/path/31-01-2023/THEOplayer.js</yoursite.com></yoursite.com
  ></yoursite.com
>
```

### Add a variable at the end of the file

Another way to trick the browser into updating the file immediately, is by adding a variable at the end of the filename. This variable on its own, in the case of `THEOplayer.js`, won't change anything to the file.

By adding something like the version or the date, you can be sure that the browser updates the file.

For example:

```html
<yoursite.com>/resource/file/path/THEOplayer.js?d=10012023 <yoursite.com>/resource/file/path/THEOplayer.js?v=5.5.1</yoursite.com></yoursite.com>
```

**Note**: For HLS playback, the player uses worker files. These workers must be present in the `libraryLocation` set on the player configuration. You do not need to link to them in the webpage as they are dynamically called from the `libraryLocation`.

The downside of adding a variable at the end of the filename is that these worker files will not get this variable and therefore may still be cached, resulting in a `THEOplayer.js` file from a newer version, while the workers are still on the old version from the cache. In this case you may see an error from the player like the following:

`THEOplayer workers could not be loaded. please check that the worker's version matches THEOplayer's version (5.5.1)`

You can make sure that the variable is a different one for each call, thus requesting the server version of the file each time (and ignoring the cached version).

Here's an example on how to dynamically generate such a cachebuster variable in JavaScript (taken from [this original article](https://www.virendrachandak.com/techtalk/cachebuster-code-in-javascript/)):

```html
<script type="text/javascript">
  var cachebuster = Math.round(new Date().getTime() / 1000);
  document.write('<scr' + 'ipt type="text/javascript" src="external.js?cb=' + cachebuster + '"></scr' + 'ipt>');
</script>
```

## Related articles

* [How to update an SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/how-to-update-a-sdk.md)
* [License](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/license/introduction.md)
* [How to reduce data usage on mobile devices on mobile web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/reduce-data-usage.md)

---

# How to customize quality selection and labels on the default UI (MP4)

Some of our customers prefer MP4 assets over HLS/MPEG-DASH ones. One major downside to this approach is that Adaptive Bitrate Streaming (ABR) is not possible with such streams, as they don't have a playlist with multiple qualities.

To counter this, we've made it possible to pass on a list of MP4 qualities & switch between them manually, to improve the overall UX. What is nice about this piece of integration code, is that it can be tweaked and applied to customize other parts of the default UI as well!

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | N/A         | N/A     | N/A      | N/A            | N/A            |

## Customizing the quality selector and labels

This example explains how to customize quality selection & labels for MP4 assets.

##### Web SDK

First of all, we need to [set up the player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md). Then, the different MP4 qualities of the same asset need to be stated, along with the corresponding resolutions:

```js
// set your resolutions and sources
var resolutions = [
  { name: '360p', src: 'https://example.com/demos/sample-videos/low.mp4' },
  { name: '540p', src: 'https://example.com/demos/sample-videos/medium.mp4' },
  { name: '720p', src: 'https://example.com/demos/sample-videos/high.mp4' },
];
```

Now for the slightly trickier part: Removing current & adding custom menu

```js
var currentTime, wasPaused;
var settingsMenu = player.ui.getChild('ControlBar').getChild('SettingsButton').menu;

// Remove built-in quality sub menu
settingsMenu.removeMenuItem(settingsMenu.menuItems[0]);

// Create custom quality sub menu
var qualityMenuItem = settingsMenu.addSubMenuItem({
  index: 0,
});
var qualityMenuTitle = document.createElement('span');
qualityMenuTitle.className = 'theo-settings-control-menu-item-title';
qualityMenuTitle.innerHTML = 'Quality';
var qualityMenuValue = document.createElement('span');
qualityMenuValue.className = 'theo-settings-control-menu-item-value';
qualityMenuItem.el().appendChild(qualityMenuTitle);
qualityMenuItem.el().appendChild(qualityMenuValue);
qualityMenuItem.subMenu.menuHeader.el().innerHTML = 'Quality';
var qualityItems = resolutions.map(function (resolution) {
  var qualityItem = qualityMenuItem.subMenu.addMenuItem();
  qualityItem.el().innerHTML = resolution.name;
  qualityItem.on('click', function () {
    selectQuality(resolution);
  });
  return qualityItem;
});

// Getting the player/UI in the correct state
function selectQuality(resolution) {
  qualityMenuValue.innerHTML = resolution.name;
  currentTime = player.currentTime;
  wasPaused = player.paused;
  player.src = resolution.src;
  player.currentTime = currentTime;
  if (!wasPaused) {
    player.play();
  }
  var qualityItem = qualityItems[resolutions.indexOf(resolution.name)];
  qualityItems.forEach(function (item) {
    item.selected(item === qualityItem);
  });
}
selectQuality(resolutions[0]);
```

##### Android SDK

Android SDK does not have a built-in UI. It also does not support JavaScript injection. However, you can implement a similar custom quality selection menu using [Open Video UI for Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui.md) and following the same logic for Web SDK.

##### iOS SDK

iOS SDK does not have a built-in UI. It also does not support JavaScript injection. However, you can implement a similar custom quality selection menu on your custom UI following the same logic for Web SDK.

You can now select multiple qualities of the same MP4 asset!

![Customize quality selection](/pr-932/assets/images/customize-quality-selection-e65dfce41a9308baad45748bb40589d8.png "Customize quality selection")

---

# How to get frame-accurate currentTime display in the UI Control bar

This article will show you how to display a frame-accurate currentTime on your THEOplayer instance UI control bar. For more information regarding the currentTime itself, please refer to the [reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer).

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | No       | Yes            | N/A            |

## Changing the currentTime UI display

At this moment there is no official THEOplayer feature to display a frame-accurate currentTime in the UI Controlbar. The following snippets rewrite the innerHTMLText of the currentTime element.

##### Web SDK

```js
function secondsToHms(d) {
  d = Number(d);
  console.log(player.currentTime);
  var ms = d % 1;
  var h = Math.floor(d / 3600);
  var m = Math.floor((d % 3600) / 60);
  var s = Math.floor((d % 3600) % 60);

  var hDisplay = h < 10 ? '0' + h : h;
  var mDisplay = m < 10 ? '0' + m : m;
  var sDisplay = s < 10 ? '0' + s : s;
  var msDisplay = ms.toFixed(3);
  //var msDisplay = d.toPrecision() -player.currentTime.toFixed();
  return hDisplay + ':' + mDisplay + ':' + sDisplay + '.' + String(msDisplay).split('.')[1];
}

setInterval(function () {
  document.querySelector('.vjs-current-time-display').innerText = secondsToHms(player.currentTime);
}, 1);

player.addEventListener('durationchange', function (e) {
  document.querySelector('.vjs-duration').innerText = secondsToHms(Math.floor(e.duration));
});
```

##### Android & iOS SDK

This can be done through JavaScript injection: [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)

## Remarks

With the same logic, slightly modified, you could also decide to show the frame number for that second instead of the milliseconds.

## Resources

* [API reference - player properties](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer)

---

# How to play an LCEVC source with THEOplayer

This article will show you how to play an LCEVC encoded source in THEOplayer. If you are not familiar with THEOplayer, we strongly recommend reading the [getting started documentation for web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md) first.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | No          | No      | No       | No             | No             |

## Prerequisites

#### 1. Your THEOplayer SDK needs to have the 'lcevc' feature enabled.

You can quickly check using `THEOplayer.features`. The feature is only available from THEOplayer 4.0 onwards.

#### 2. You need to include V-Nova's [LCEVC Decoder for Web](https://docs.v-nova.com/v-nova/lcevc/sdk/lcevc-decoder-for-web-lcevcdecjs) on the page.

This example below uses the latest version of the LCEVCdecJS library that is maintained by V-Nova:

```js
<script type="text/javascript" src="https://unpkg.com/lcevc_dec.js@latest/dist/lcevc_dec.min.js"></script>
```

## Setting the source

After your player is correctly configured you can set your LCEVC source, but you need to also include `lcevc: true` on the SourceDescription so that the player knows how to configure the correct playback pipeline:

##### DASH example

```js
player.source = {
  sources: {
    type: 'application/dash+xml',
    src: 'path/to/your/source/master.mpd',
    lcevc: true,
  },
};
```

##### HLS example

```js
player.source = {
  sources: {
    type: 'application/x-mpegurl',
    src: 'path/to/your/source/master.m3u8',
    lcevc: true,
  },
};
```

## Remarks

LCEVC enhanced playback only works on modern browsers that support Media Source Extensions (MSE). If the platform does not support MSE (for example: Safari on iOS), the player will fall back to native playback without LCEVC enhancements.

---

# How to use THEOplayer as a JavaScript module

As of THEOplayer 6.0, THEOplayer can also be used as a [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). Instead of loading the library through a `<script>` tag in your HTML, you `import` it directly from your JavaScript code.

Using JavaScript modules has several advantages:

* It's easier to manage dependencies per file, rather than maintaining a long list of `<script>` tags and keeping them in the right order.
* If multiple JavaScript files `import` the same module, the module is only loaded once. (On the other hand, multiple `<script>` tags with the same `src` attribute will load and execute the script multiple times.)
* When you use a bundler for your web app, your bundler can more easily understand the dependencies between your files and generate a single output bundle of your entire app.

Additionally, since JavaScript modules are only supported in modern web browsers, THEOplayer can use more modern JavaScript syntax in its JavaScript module (such as [async/await](https://caniuse.com/async-functions)). This results in smaller files, which load and execute faster on your viewer's devices.

> **Note** If you need to support older browsers (such as older smart TVs), you should stick with a classic `<script>` tag. [See the getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md).

In this article, we will set up a simple web page using JavaScript modules with the THEOplayer SDK on Web. The outcome of this article is the template below.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="/path/to/ui.css" />
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
    <script type="module">
      import * as THEOplayer from '/path/to/THEOplayer.esm.js';

      let element = document.querySelector('.theoplayer-container');
      let player = new THEOplayer.Player(element, {
        libraryLocation: '/path/to/your-theoplayer-folder/',
        license: 'your_license_string',
      });

      player.source = {
        sources: [
          {
            src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
            type: 'application/x-mpegurl',
          },
        ],
      };
    </script>
  </body>
</html>
```

## Prerequisites

See [the prerequisites in our getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md#prerequisites).

## Basic setup

Now, we're ready to set up THEOplayer on your website. This guide explains how you implement THEOplayer in four steps:

1. We'll [start from a basic HTML file](#step-1-set-up-an-html-file), with no mention of THEOplayer.
2. In the [second step](#step-2-including-the-theoplayer-library), we'll explain what the THEOplayer library is and how you can include it. We'll do the same for the default THEOplayer UI.
3. In the [third step](#step-3-the-video), we'll describe how you play a video stream through THEOplayer.
4. In the [fourth step](#step-4-the-result), we'll give a final overview.

### Step 1: Set up an HTML file

When THEOplayer is used as a web video player, we will need a web page (i.e. HTML file) to embed THEOplayer and the code.

Note that a THEOplayer SDK license can only be used on whitelisted domains. You configure these domains when you create a THEOplayer Web SDK at <https://portal.theoplayer.com>.

Let's start with the following HTML file:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
  <body>
    <script type="module"></script>
  </body>
</html>
```

Pay attention to the `type="module"` attribute on the `<script>` tag. This informs the browser to execute it as a module, rather than as a classic script. This allows the code inside it to use `import` and `export` statements.

Next, we’ll include the THEOplayer SDK.

### Step 2: Including the THEOplayer library

To access the THEOplayer API and default UI, you must first include the THEOplayer library files. The JavaScript library exposes the THEOplayer API and the CSS library contains the default UI.

#### THEOplayer JavaScript library

The following line imports the THEOplayer JavaScript library, and gives you access to the THEOplayer API.

```html
<script type="module">
  import * as THEOplayer from '/path/to/THEOplayer.esm.js';
</script>
```

The path of the `import` statement is the URI of the THEOplayer library that you wish to use. This could be something like: `/path/to/THEOplayer.esm.js`, where the URL is a link to your `THEOplayer.esm.js` file.

You must swap `/path/to/` with your CDN URL. For example, if your SDK is hosted on `https://example.com/vendor/theoplayer/`, then you'd write the following import:

```js
import * as THEOplayer from 'https://example.com/vendor/theoplayer/THEOplayer.esm.js';
```

#### THEOplayer CSS library

To use the default THEOplayer UI, you need to reference the THEOplayer CSS library:

```html
<link rel="stylesheet" type="text/css" href="/path/to/ui.css" />
```

The `<link>` tag includes a CSS file on a web page. Similar to the JavaScript library, you must swap `/path/to/` with your CDN URL.

Next, we’ll create a THEOplayer instance and configure a video stream.

### Step 3: The video

To play a video through the THEOplayer Web SDK, you must:

1. Create a video player container,
2. fetch this container through JavaScript,
3. create a THEOplayer instance associated with that container,
4. and configure a video stream for this instance.

The snippet below implements these 4 steps.

```html
<div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
<script type="module">
  import * as THEOplayer from '/path/to/THEOplayer.esm.js';

  let element = document.querySelector('.theoplayer-container'); // fetch THEOplayer container div

  let player = new THEOplayer.Player(element, {
    // instantiates video player
    libraryLocation: '/path/to/your-theoplayer-folder/', // references folder containing your THEOplayer library files (theoplayer.p.js, THEOplayer.js, ...)
    license: 'your_license_string', // references your THEOplayer SDK license
  });

  // HLS
  player.source = {
    sources: [
      {
        src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8', // sets HLS source
        type: 'application/x-mpegurl', // sets type to HLS
      },
    ],
  };

  // DASH
  // player.source = {
  //     sources : [{
  //         src : '//amssamples.streaming.mediaservices.windows.net/634cd01c-6822-4630-8444-8dd6279f94c6/CaminandesLlamaDrama4K.ism/manifest(format=mpd-time-csf)', // sets DASH source
  //         type : 'application/dash+xml' // sets type to MPEG-DASH
  //     }]
  // };
</script>
```

Let's break down the above snippet.

#### Create video player container

This `<div>` element creates a video player container.

```html
<div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
```

* The `theoplayer-container` class is used to fetch the container through JavaScript, as demonstrated by the snippet below.
* The `video-js theoplayer-skin vjs-16-9` classes load the default THEOplayer UI. You may omit `vjs-16-9` if you don't want a 16:9 container.

```javascript
let element = document.querySelector('.theoplayer-container');
```

#### Create THEOplayer instance

The snippet below creates a THEOplayer instance for a container with a specific [Player Configuration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerConfiguration).

```js
let player = new THEOplayer.Player(element, {
  // instantiates video player
  libraryLocation: '/path/to/your-theoplayer-folder/', // references folder containing your THEOplayer library files (theoplayer.p.js, THEOplayer.js, ...)
  license: 'your_license_string', // references your THEOplayer SDK license
});
```

Similar to the JavaScript and CSS library, you must swap out `'/path/to/your-theoplayer-folder/'` and `'your_license_string'`.

For example, if your SDK is hosted on `https://example.com/vendor/theoplayer/` and your license string is `ABCD1234`, then you would instead configure the snippet below:

```js
var player = new THEOplayer.Player(element, {
  libraryLocation: 'https://example.com/vendor/theoplayer/',
  license: 'ABCD1234',
});
```

You can read more about configuring the `license` at the [License section](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/license/introduction.md).

#### Configure video stream

The snippet below configures a HLS video stream for the THEOplayer instance.

```js
player.source = {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8', // sets HLS source
      type: 'application/x-mpegurl', // sets type to HLS
    },
  ],
};
```

To configure a DASH stream instead, you must set `type` to `'application/dash+xml'` instead of `'application/x-mpegurl'`, as demonstrated by commented out code in one of the earlier snippets.

In the next step we'll put everything together.

### Step 4: The result

We're done! Here's the complete code again, which you can put on your web server:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="/path/to/ui.css" />
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
    <script type="module">
      import * as THEOplayer from '/path/to/THEOplayer.esm.js';

      let element = document.querySelector('.theoplayer-container');
      let player = new THEOplayer.Player(element, {
        libraryLocation: '/path/to/your-theoplayer-folder/',
        license: 'your_license_string',
      });

      player.source = {
        sources: [
          {
            src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
            type: 'application/x-mpegurl',
          },
        ],
      };
    </script>
  </body>
</html>
```

## Next steps

Ready to learn more?

* Go through our [how-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web.md) to learn about [UI customization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web.md), [advertising](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/introduction.md), [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md), [casting](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/introduction.md), [analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/introduction.md) and other topics.
* Check out our [API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer).
* Try out samples from our [GitHub](https://github.com/THEOplayer).

---

# How to use MultiView

This article will go over how to work with THEOplayer's MultiViewPlayer. As the setup is very similar to using normal THEOplayer, we strongly recommend reading the [getting started documentation for web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md) first.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | No          | No      | No       | No             | No             |

## Prerequisites

#### 1. Your THEOplayer SDK needs to have the 'multiview' feature enabled.

You can quickly check using `THEOplayer.features`. The feature is only available from THEOplayer 4.3 and onwards. This feature is included by default in the [@theoplayer/extended](https://www.npmjs.com/package/@theoplayer/extended) npm package.

#### 2. You need to have a THEOplayer license which is compatible with MultiView

This can be done through <https://portal.theoplayer.com>.

## Basic setup

To make a `MultiViewPlayer`, add the following code to your page:

```html
<div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
<script src="/path/to/THEOplayer.js"></script>
<script>
  const element = document.querySelector('.theoplayer-container'); // fetch THEOplayer container div

  const player = new THEOplayer.MultiViewPlayer(element, {
    // instantiates the MultiView player
    libraryLocation: '/path/to/your-theoplayer-folder/', // references folder containing your THEOplayer library files (THEOplayer.js, ...)
    license: 'your_license_string', // references your THEOplayer SDK license
  });
</script>
```

Now that the `MultiViewPlayer` is instantiated, you'll need to load each view separately:

```js
// set the name of the source
player.load('Star Wars', {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8', // sets HLS source
      type: 'application/x-mpegurl', // sets type to HLS
    },
  ],
});

// set the name of the source
player.load('Big Buck Bunny', {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8', // sets HLS source
      type: 'application/x-mpegurl', // sets type to HLS
    },
  ],
});
```

The `MultiViewPlayer` has a slightly different API from the general THEOplayer, so for more information we refer to the [documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/MultiViewPlayer).

---

# Migrating to THEOplayer Web SDK 11.x

This article will guide you through updating to THEOplayer Web SDK version 11 (from version 10), and the changes needed in your code.

## Update THEOplayer

Run the following command to install THEOplayer Web SDK version 11:

```bash
npm install theoplayer@11
```

If you're using the [Open Video UI for Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md) or one of [our connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web.md), make sure to update them to the latest version too to ensure proper support for THEOplayer version 11.

```bash
npm update @theoplayer/web-ui
npm update @theoplayer/conviva-connector-web
```

## Replace or remove usages of deprecated APIs

Some properties and methods that were previously deprecated have been removed from the API. Update your code to use the new APIs instead.

* Removed `preloadPublications` in THEOlive API.

---

# Getting Started on webOS

This guide will help you integrate your Dolby OptiView Player SDK on webOS.

Since webOS IDE is [no longer available](https://webostv.developer.lge.com/develop/tools/ide-introduction) as of February 2022, you will need to set up [webOS CLI](https://webostv.developer.lge.com/develop/tools/cli-installation), optionally in combination with the [webOS TV VS Code Extension](https://webostv.developer.lge.com/develop/tools/vsce-installation).

The focus of this article is using our [sample apps for webOS](https://github.com/THEOplayer/samples-webos).

You may also find the [Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md) guide useful.

## Prerequisites

1. Make sure that the [webOS CLI](https://webostv.developer.lge.com/develop/tools/cli-installation) is correctly installed on your system.
2. Validate that the CLI is correctly set up on your environment by invoking `ares` at the command line of a new terminal. If the command is recognized, you are correctly set up. If not, please go over the steps on the CLI installation guide again.
3. Optionally you can also install the official VS Code extension listed [here](https://marketplace.visualstudio.com/items?itemName=webostvsdk.webostv) to quickly connect/deploy to your devices.

# Download the starter files

* Download the starter code from [our sample repository](https://github.com/THEOplayer/samples-webos).

* The folder contains all the necessary files to quickly deploy a THEOplayer solution to a webOS device.

* The packager will use the `app` folder to build an IPK package
  * the `app` folder contains a crude solution with entry point `index.html`; the only thing left is to put your THEOplayer library files in the `libs` folder.

* The folder `example-with-UI` contains a more elaborate example,

  * To use it, optionally modify the code and run the following commands:
    ```shell
    cd example-with-ui
    npm i
    npm run build
    ```
  * Next, copy the `js` folder, the `css` folder and the `index.html` file to the app folder (overwriting the existing files).

## Setting up the physical device

### Prerequisites

1. Make sure you have created an [LG Developer Account](https://webostv.developer.lge.com/login). You will need this to login to the Developer Tools app on the physical device.
2. Download the Developer Tools app to the TV from the LG Content Store, login with your LG account and follow the instructions to set the device in developer mode (a restart is required).

### Make a connection

* In case you downloaded the webOS TV VS Code extension, you can use it to link your development environment to the physical device (from the webOS TV Devices menu on the left-hand toolbar).

* Manually set up (use the guideline provided by LG):

  1. Open terminal and enter `ares-setup-device`

     1. Choose `add`.
     2. Enter device name: tv (feel free to use another name).
     3. Enter the IP address of the LG TV (open the Developer Tools app on the device to find out).
     4. Use port `9922` for physical devices (for a simulator the port is 6622).
     5. SSH user: this should be set to `prisoner` (**important note**: do not use the proposed `root`, this will not work).
     6. Enter an optional description.
     7. Authentication: choose option `password`.
     8. Leave the actual password blank.
     9. Save.

  2. Next, you need to acquire a key from the physical device to be able to securely interact:

     1. Enter `ares-novacom -d tv --getkey` (make sure to use the device name you chose in case you changed it).
     2. You will be prompted for a key; the key will be visible in the Developer Tools app on the physical device.

## Simulator

**Important Note**: the use of a simulator is not recommended as simulators do not implement all features (e.g. DRM).

If you decide to use a simulator, follow the guide [here](https://webostv.developer.lge.com/develop/tools/simulator-installation) to install one.

# Running the app

**Note**: please visit the [LG webOS developer site](https://webostv.developer.lge.com/) to get more info on commands, tools and guidelines.

First make sure to `cd` into the root folder (this is the parent of app folder). Next, run the following commands.

### Packaging

```shell
ares-package  ./app --outdir ./
```

### Installation

Default name for the created package is *webos.theo\_1.0.0\_all.ipk*, *tv* is the device name that was given when setting up the device in the previous step.

This step will fail if there is no connection to the device, e.g. the device is offline, not on the same network.

```shell
ares-install webos.theo_1.0.0_all.ipk  -d tv
```

### Launch

App ID is by default *web.theo* (you can change this in `appinfo.json`)

```shell
ares-launch webos.theo  -d tv
```

### Debug

```shell
ares-inspect webos.theo -d tv --open
```

---

# Getting started on Tizen

This how-to guide describes how to set up a Tizen application using the Dolby OptiView Player SDK on Tizen.

You may also find the [Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md) to be useful.

## Set-up

For brevity, the set-up is split up over multiple pages:

* [Setting up Tizen Studio](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/tizen/installing-tizen-studio.md)
* [Generating a certificate](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/tizen/generating-a-certificate.md)
* [Setting up and deploying on a physical device (recommended)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/tizen/setting-up-physical.md)
* [Setting up and deploying on an emulator (less recommended)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/tizen/setting-up-emulator.md)

## Getting started with the THEOplayer Tizen reference app

### Prerequisites

* Generate a Tizen SDK build via the [THEOplayer portal](https://portal.theoplayer.com/).
* Download the [reference app project](https://github.com/THEOplayer/samples-tizen)
* Read the README to get started. There is one at the root level and one in the two examples.
* Import the project in Tizen Studio.

Go to File -> Open Projects from File System.

![](/pr-932/assets/images/import-1-8aaecab1b94a589fec742e47cd9bd394.jpg)

Select the directory, then press Finish.

![](/pr-932/assets/images/import-2-abd40c64a1537775af117e7460865ac6.jpg)

### Reference app structure structure

* **example-with-ui/**

  * Contains a Tizen project with a UI. Follow the readme for more instructions.
  * **css/**
    * CSS styles as used in the app.
  * **js/**
    * JavaScript files as used in the app. The compiled result of `src/` is put in here.
  * **src/**
    * The source code of the UI application. Change or replace as desired.
  * **libs/**
    * (Insert your THEOplayer Tizen SDK here.)
  * **index.html**
    * Entry point of application.
  * **config.xml**
    * Permissions of the app.
  * **package.json**
    * Contains the commands required to build the UI.

* **minimum-example/**

  * Contains a very minimal Tizen project example. No UI included.
  * **libs/**
    * (Insert your THEOplayer Tizen SDK here.)
  * **index.html**
    * Entry point of application.
  * **config.xml**
    * Permissions of the app.

---

# Installing the Tizen developer tools

* Check if your device meets the [Tizen developer tools prerequisites](https://docs.tizen.org/application/tizen-studio/setup/prerequisites/).
* Download the Tizen developer tools at [Tizen development tools](https://developer.tizen.org/development/tizen-studio/download). You can decide to either install the IDE or CLI, but in this guide we assume you use the IDE.
* In Tizen Studio, make sure to install the Tizen package extensions:

Go to Tools, then Package Manager

![](/pr-932/assets/images/tizen-extensions-1-832ce052ecfc2dd8d85a0d3a9b9a5b5c.jpg)

Install everything under Tizen SDK tools under Main SDK.

**Note:** Make sure to close Tizen Studio before installing, otherwise an empty warning message might show up that stops you from completing the installation.

![](/pr-932/assets/images/tizen-extensions-2-e020322a3a7e70ab03067a6c823f80fd.jpg)

Install the latest tv extensions under Extension SDK.

![](/pr-932/assets/images/tizen-extensions-3-d03d447b80a0502d74d51d1de6b5bcdf.jpg)

---

# Setting up a Tizen device for debugging

Tizen requires a certificate to launch an application on a (physical) device. Below are the steps on how to create one:

Go to Tools → Certificate Manager

![](/pr-932/assets/images/tizen-certificate-1-5dc8da6607b5532e09b09217eef7d97d.jpg)

In the Certificate Manager, click the Add (plus) button to generate a new certificate.

![](/pr-932/assets/images/tizen-certificate-2-4e3672ee2e2fa8cbdcc9d518f3b8ce6a.jpg)

Generate a Tizen Certificate.

![](/pr-932/assets/images/tizen-certificate-3-f5c7f5477ef3c33c0438c1f3be6aa5df.jpg)

Give your certificate a profile name (name is free to pick).

![](/pr-932/assets/images/tizen-certificate-4-e8aad0838f338202f6ff8872dd43bbe1.jpg)

Pick “Create a new author certificate” if you have never used one. If you already have one, then you can choose to select an existing author certificate instead.

![](/pr-932/assets/images/tizen-certificate-5-c08251931d95a82bbd050cd021acc7d5.jpg)

If you decided to create a new author certificate, you will get this screen. Fill in the fields as requested with your own. Fill in a password. You can add additional fields when opening the “More details” component.

![](/pr-932/assets/images/tizen-certificate-6-c6150763460504d017b394943dbaf60d.jpg)

Pick “Use the default Tizen distributor certificate”.

![](/pr-932/assets/images/tizen-certificate-7-81c3b7cc09f35744d96bcedf37a7e2ee.jpg)

If everything went well, a pop-up will appear indicating that the certificate profile has been created.

![](/pr-932/assets/images/tizen-certificate-8-dc745be45feb631cdeb6a54185c9194c.jpg)

Your certificate should now be available for selection.

![](/pr-932/assets/images/tizen-certificate-9-1cc2cd3b3d2d3d75e8ccd0160942aff2.jpg)

---

# Deploying a test app on a physical Tizen device

Both the physical Tizen device as the development computer must be on the same network.

## Set-up

### Tizen device

* Go to the home menu (home button) and navigate to apps. Launch it.

* Use the 123-key (or numbers) to type 12345. A menu will prompt.

* Enable Developer mode.

  * Type in the local IP-address of the laptop you want to deploy a build from. They must be on the same network.
  * Reboot Tizen device by long-pressing (about 2 seconds) the power button on the remote.

### Set-up on development device

* Go to Tizen Studio. Open Tools -> Device Manager.

* Open Remote Device Manager (the icon with a pc and a smart tv)

  * Add Tizen device via its IP-address, connect and confirm.
  * The Tizen IP-address can be found under Settings -> General -> Network -> Network Status -> IP Settings.
  * Enable connection with remote device.

## Launching on a physical Tizen device

* Ensure the connection is established. You can check this under Tools → Devices.
* In Tizen Studio, click right on the project (under Project Explorer). Pick either "Run as" or "Debug as".

---

# Deploying a test app on a Tizen emulator

We strongly recommend using a physical Tizen device. If this is not possible, using an emulator can be a back-up.

## Set up

* If you haven't done so, make sure to install the Tizen TV Emulator:
  * In Tizen Studio: Tools -> Package Manager -> Extension SDK -> TV Extensions 5.5
* Create the emulator by pressing the "Create" button and following the steps.

## Launching

* In Tizen Studio, click right on the project (under Project Explorer). Pick either:

  * Run As -> Tizen Web Simulation Application
  * Debug As -> Tizen Application

## Known limitations of emulators:

* AVPlay is unavailable.
* DRM is unavailable due to a missing Content Decryption Module (CDM).
* `manifest.json` permissions are ignored for emulators. Make sure to test on a physical device, as they are more strict.

---

# Getting started with Angular

*A brief guide on how to build a THEOplayer in an Angular environment.*

Note that this information is for a basic player in a local testing environment. Additional information may be needed for specific cases.

## Step-by-step guide:

1. Make sure you have the Angular CLI installed

```shell
npm install -g @angular/cli
```

2. If needed, create a new workspace and initial application ng new appname

3. In the root project, create a new component for the player (in this case appname)

```shell
cd appname
ng generate component theoplayer
```

4. add the THEOplayer.js files to the root project
5. In index.html add the /THEOplayer.js as a script tag and /ui.css as a stylesheet
6. In theoplayer.component.html add

```html
<div class="theoplayer-container video-js theoplayer-skin"></div>
```

7. In theoplayer.component.ts add

```typescript
import { Component, OnInit } from '@angular/core';
import * as THEOplayer from '../../../THEOplayer.js';

@Component({
  selector: 'app-theoplayer',
  templateUrl: './theoplayer.component.html',
  styleUrls: ['./theoplayer.component.css'],
})
export class TheoplayerComponent implements OnInit {
  constructor() {}

  ngOnInit() {
    this.createPlayer();
  }

  createPlayer() {
    const element = document.querySelector('.theoplayer-container');

    const player = new THEOplayer.Player(element, {
      libraryLocation: '',
    });

    player.source = {
      sources: [
        {
          src: '//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
          type: 'application/x-mpegurl', // sets type to MPEG-DASH
        },
      ],
    };
  }
}
```

Then

```typescript
import * as THEOplayer from '../../../THEOplayer.js';
```

will make sure to get everything needed from our sdk.

9. In app.component.html add the following code to display the player in the app component.

```html
<app-theoplayer></app-theoplayer>
```

10. Profit.

## Related articles

* <https://angular.io/guide/quickstart>

---

# Getting started with React

There is a sample app using THEOplayer as a React component available [on our GitHub](https://github.com/THEOplayer/samples-react-js).

## Project setup

```shell
git clone https://github.com/THEOplayer/samples-react-js.git
```

Creates a local clone of the project

```shell
npm install
```

Installs the necessary dependencies. This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app). You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).

```shell
npm start
```

Compiles and runs the app in the development mode. Open <http://localhost:3000> to view it in the browser. The page will reload if you make edits. You will also see any lint errors in the console.

## Creating and using a component

### `src/THEOplayerWrapper.js`

is an example implementation of a React Component that wraps the THEOplayer.js module. You can extend this wrapper to support whatever THEOplayer API that you want to use.

### `src/App.js`

uses the `Player` component exported by `THEOplayerWrapper.js` and specifies a source for the player to play.

## Going to Production

The THEOplayer library provided in this sample is currently targeted to the latest version and is set to run on **localhost only**

### Getting a license

To run THEOplayer in production you will need a valid THEOplayer HTML5 SDK set up to run on your domain. You can use your existing license or get one for free on [THEOportal](http://portal.theoplayer.com).

### Updating the project

You will need to update some files that reference the THEOplayer.js and THEOplayer.css files:

* `src/THEOplayerWrapper.js`, -- Please replace the URL of the `libraryLocation` to the URL or folder where your THEOplayer files (THEOplayer.js, THEOplayer.d.js, etc.) are residing.
* `src/App.js`
* `public/index.html` -- Please replace the links to the THEOplayer assets with your own URLs.

---

# Getting started with NuxtJS

This how-to guide describes how to integrate THEOplayer with NuxtJS framework.

## Instructions

1. Open your favorite IDE and then a terminal and install Vue CLI component:

```shell
npx create-nuxt-app theoplayer-nuxtjs-sample
```

2. Follow the installation process (please note these instructions assume you’ve chosen npm as a module packager)

3. Once the app is created, execute the following commands:

```shell
cd theoplayer-nuxtjs-sample
npm install
npm run dev
```

4. The default application should be served under: <http://localhost:3000/>

5. Reference the THEOplayer Web SDK by editing file `nuxt.config.js` like the following:

```js
export default {
  mode: 'spa',
  /*
   ** Headers of the page
   */
  head: {
    title: process.env.npm_package_name || '',
    meta: [
      { charset: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      {
        hid: 'description',
        name: 'description',
        content: process.env.npm_package_description || '',
      },
    ],
    link: [
      { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' },
      {
        rel: 'stylesheet',
        type: 'text/css',
        href: '//cdn.theoplayer.com/dash/theoplayer/ui.css',
      },
    ],
    script: [
      {
        type: 'text/javascript',
        src: '//cdn.theoplayer.com/dash/theoplayer/THEOplayer.js',
      },
    ],
  },
  /*
   ** Customize the progress-bar color
   */
  loading: { color: '#fff' },
  /*
   ** Global CSS
   */
  css: [],
  /*
   ** Plugins to load before mounting the App
   */
  plugins: [],
  /*
   ** Nuxt.js dev-modules
   */
  buildModules: [
    // Doc: https://github.com/nuxt-community/eslint-module
    '@nuxtjs/eslint-module',
  ],
  /*
   ** Nuxt.js modules
   */
  modules: [],
  /*
   ** Build configuration
   */
  build: {
    /*
     ** You can extend webpack config here
     */
    extend(config, ctx) {},
  },
};
```

6. Add the new component named Player.vue under this path: components/Player.vue

```html
<template>
  <div ref="theoplayer" class="theoplayer-container video-js theoplayer-skin vjs-16-9 THEOplayer"></div>
</template>

<script>
  import { mapState } from 'vuex';
  export default {
    computed: mapState({
      source: (state) => state.source,
    }),
    mounted() {
      this.playerInit();
    },
    methods: {
      playerInit() {
        const player = new window.THEOplayer.Player(this.$refs.theoplayer, {
          fluid: true,
          libraryLocation: '//cdn.theoplayer.com/dash/theoplayer/',
        });
        player.source = {
          sources: this.source,
        };
      },
    },
  };
</script>
<style>
  .THEOplayer {
    width: 50%;
    margin: 0 auto;
  }

  .video-js.vjs-16-9 {
    padding-top: 28.12%;
    width: 50%;
  }
</style>
```

7. Please note that vuex is used to pass the player source, for this purpose add index.js file under this path: store/index.js with following content:

```js
export const state = () => ({
  source: null,
});

export const mutations = {
  setSource(state, source) {
    state.source = source;
  },
};
```

8. Now, we are ready to reference the player component in the index.vue like following:

```html
<template>
  <div class="container">
    <div>
      <logo />
      <player />
      <h1 class="title">theoplayer-nuxtjs-sample</h1>
      <h2 class="subtitle">THEOplayer nuxtjs sample app</h2>
      <div class="links">
        <a href="https://nuxtjs.org/" target="_blank" class="button--green"> Documentation </a>
        <a href="https://github.com/nuxt/nuxt.js" target="_blank" class="button--grey"> GitHub </a>
      </div>
    </div>
  </div>
</template>
<script>
  import Logo from '~/components/Logo.vue';
  import Player from '~/components/Player.vue';

  export default {
    components: {
      Logo,
      Player,
    },
    created() {
      this.$store.commit('setSource', [
        {
          type: 'application/x-mpegurl',
          src: '//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
        },
      ]);
    },
  };
</script>

<style>
  .container {
    margin: 0 auto;
    min-height: 100vh;
    display: flex;
    justify-content: center;
    align-items: center;
    text-align: center;
  }

  .title {
    font-family:
      'Quicksand',
      'Source Sans Pro',
      -apple-system,
      BlinkMacSystemFont,
      'Segoe UI',
      Roboto,
      'Helvetica Neue',
      Arial,
      sans-serif;
    display: block;
    font-weight: 300;
    font-size: 100px;
    color: #35495e;
    letter-spacing: 1px;
  }

  .subtitle {
    font-weight: 300;
    font-size: 42px;
    color: #526488;
    word-spacing: 5px;
    padding-bottom: 15px;
  }

  .links {
    padding-top: 15px;
  }
</style>
```

9. This should result in a page which includes the THEOplayer component.

## Build Setup

```bash
# install dependencies
$ npm run install

# serve with hot reload at localhost:3000
$ npm run dev

# build for production and launch server
$ npm run build
$ npm run start

# generate static project
$ npm run generate
```

For detailed explanation on how things work, check out [Nuxt.js docs](https://nuxtjs.org).

---

# Getting started with VueJS

This how-to guide describes how to integrate THEOplayer with VueJS framework.

### Customize configuration

See [Configuration Reference](https://cli.vuejs.org/config/).

## A step-by-step guide:

1. Open your favorite IDE and then a terminal and install Vue CLI component:

```shell
npm install vue
```

2. If needed, create a new workspace and initial application:

```shell
vue create theoplayer-vuejs-sample
```

3. Choose your preferred configuration by choosing one of the presets from the list.

4. Once the project is created, you should see a successful message.

5. Go to root project and start application using instructions:

```shell
cd theoplayer-vuejs-sample
npm run serve
```

6. As a result you should be able to browse the default page under the following URL: <http://localhost:8080/>

7. Reference the THEOplayer files in index.html like following:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width,initial-scale=1.0" />
    <link rel="icon" href="<%= BASE_URL %>favicon.ico" />
    <title>theoplayer-vuejs-sample</title>
    <link rel="stylesheet" type="text/css" href="//cdn.theoplayer.com/dash/theoplayer/ui.css" />
  </head>

  <body>
    <noscript>
      <strong>We're sorry but theoplayer-vuejs-sample doesn't work properly without JavaScript enabled. Please enable it to continue.</strong>
    </noscript>
    <div id="app"></div>
    <script type="text/javascript" src="//cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <!-- built files will be auto injected -->
  </body>
</html>
```

8. In the src/components/ add a new file and name it Player.vue, then add the following snippet:

```html
<template>
  <div class="theoplayer-container video-js theoplayer-skin vjs-16-9 THEOplayer" ref="theoplayer"></div>
</template>

<script>
  export default {
    props: ['source'],
    mounted: function () {
      this.playerInit();
    },
    methods: {
      playerInit() {
        const player = new window.THEOplayer.Player(this.$refs.theoplayer, {
          fluid: true,
          libraryLocation: '//cdn.theoplayer.com/dash/theoplayer/',
        });
        player.source = {
          sources: this.source,
        };
      },
    },
  };
</script>
<style>
  .THEOplayer {
    width: 50%;
    margin: 0 auto;
  }

  .video-js.vjs-16-9 {
    padding-top: 28.12%;
    width: 50%;
  }
</style>
```

9. Then you can reference the Player component in different parts of the app and pass the source, for instance you can change App.vue like following:

```html
<template>
  <div id="app">
    <img alt="Vue logo" src="./assets/logo.png" />
    <Player :source="source" v-if="source" />
  </div>
</template>

<script>
  import Player from './components/Player.vue';

  export default {
    name: 'app',
    components: {
      Player,
    },
    data: function () {
      return {
        source: [
          {
            type: 'application/x-mpegurl',
            src: '//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
          },
        ],
      };
    },
  };
</script>
<style>
  #app {
    font-family: 'Avenir', Helvetica, Arial, sans-serif;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
    text-align: center;
    color: #2c3e50;
    margin-top: 60px;
  }
</style>
```

## Including THEOplayer library assets

1. Create a new folder named i.e. libs under public folder and copy the THEOplayer WebSDK files there.

2. Change the index.html to reference local files:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width,initial-scale=1.0" />
    <link rel="icon" href="<%= BASE_URL %>favicon.ico" />
    <title>theoplayer-vuejs-sample</title>
    <link rel="stylesheet" type="text/css" href="libs/THEOplayer/ui.css" />
  </head>

  <body>
    <noscript>
      <strong>We're sorry but theoplayer-vuejs-sample doesn't work properly without JavaScript enabled. Please enable it to continue.</strong>
    </noscript>
    <div id="app"></div>
    <script type="text/javascript" src="libs/THEOplayer/THEOplayer.js"></script>
    <!-- built files will be auto injected -->
  </body>
</html>
```

3. In the Player.vue modify libraryLocation like following:

```js
const player = new window.THEOplayer.Player(this.$refs.theoplayer, {
  fluid: true,
  libraryLocation: './libs/THEOplayer',
});
```

---

# Getting started with AMP

*A brief guide on how to build a THEOplayer in an AMP environment.*

Note that this information is for a basic player in a testing environment. Additional information may be needed for specific cases.

## AMP

Accelerated Mobile Pages (AMP) is an open-source HTML framework. More information about AMP is available at <https://amp.dev/>.

## Step-by-step guide:

1. Have a [valid AMP page](https://validator.ampproject.org/). *(Let's call this page A.)*
2. Prepare an embeddable page which can be served through an [`<amp-iframe>`](https://amp.dev/documentation/components/amp-iframe/?format=websites). *(Let's call this page B.)* Read more about THEOplayer and iframes [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/how-can-we-embed-iframe.md). It's your responsibility to decide the most optimal approach for your use-case. You can use <https://cdn.theoplayer.com/demos/iframe/iframe.html> as a starting point to prepare your page.
3. Upload page B to a different (sub) domain than page A in order to adhere to the [iframe origin policy](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-iframe-origin-policy.md).
4. Embed page B into page A by using an `<amp-iframe>`. It's your responsibility to decide the most optimal approach for your use-case. You can use the snippet below as an example.

```html
<!doctype html>
<html ⚡>
  <head>
    <meta charset="utf-8" />
    <title>amp-iframe</title>
    <script async src="https://cdn.ampproject.org/v0.js"></script>
    <!--  Import the amp-iframe component in the header. -->
    <script async custom-element="amp-iframe" src="https://cdn.ampproject.org/v0/amp-iframe-0.1.js"></script>
    <!-- You can use the `amp-bind` extension to dynamically change an iframe src. -->
    <script async custom-element="amp-bind" src="https://cdn.ampproject.org/v0/amp-bind-0.1.js"></script>
    <link rel="canonical" href="<% canonical %>" />
    <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1" />
    <style amp-boilerplate>
      body {
        -webkit-animation: -amp-start 8s steps(1, end) 0s 1 normal both;
        -moz-animation: -amp-start 8s steps(1, end) 0s 1 normal both;
        -ms-animation: -amp-start 8s steps(1, end) 0s 1 normal both;
        animation: -amp-start 8s steps(1, end) 0s 1 normal both;
      }
      @-webkit-keyframes -amp-start {
        from {
          visibility: hidden;
        }
        to {
          visibility: visible;
        }
      }
      @-moz-keyframes -amp-start {
        from {
          visibility: hidden;
        }
        to {
          visibility: visible;
        }
      }
      @-ms-keyframes -amp-start {
        from {
          visibility: hidden;
        }
        to {
          visibility: visible;
        }
      }
      @-o-keyframes -amp-start {
        from {
          visibility: hidden;
        }
        to {
          visibility: visible;
        }
      }
      @keyframes -amp-start {
        from {
          visibility: hidden;
        }
        to {
          visibility: visible;
        }
      }
    </style>
    <noscript
      ><style amp-boilerplate>
        body {
          -webkit-animation: none;
          -moz-animation: none;
          -ms-animation: none;
          animation: none;
        }
      </style></noscript
    >
    <style amp-custom>
      #sample-resizable-iframe div[overflow] {
        text-align: center;
        background: #f9f7f7;
        line-height: 36px;
      }
    </style>
  </head>
  <body>
    <amp-iframe
      width="500"
      height="281"
      title="THEOplayer demo"
      layout="responsive"
      sandbox="allow-scripts allow-same-origin allow-popups"
      allowfullscreen
      frameborder="0"
      src="https://cdn.theoplayer.com/demos/iframe/iframe.html"
    >
      <amp-img layout="fill" src="https://cdn.theoplayer.com/demos/iframe/pixel.png" placeholder></amp-img>
    </amp-iframe>
  </body>
</html>
```

5. Once again: upload page A to a different (sub) domain than page B in order to adhere to the [iframe origin policy](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-iframe-origin-policy.md). For example, you can put page B on <https://iframe.website.com/player.html> and page A on <https://www.website.com/a-random-video.html>

An example application of this step-by-step guide is available [here](https://f.hubspotusercontent20.net/hubfs/2163521/Demo_zone/amp-iframe-example.html).

## Alternatives

Some video players offer a **custom AMP tag**. For example, YouTube offers this through [`<amp-youtube>`](https://amp.dev/documentation/components/amp-youtube/?format=websites). Under the hood, these video players also leverage an `<iframe>`. Although custom AMP tags are primarily syntax sugar, it is arguably a more developer-friendly implementation than `<amp-iframe>`. The advantage of using `<amp-iframe>` is flexibility: you are in full control of the page you're embedding.

Feel free to [contact us](https://www.theoplayer.com/contact) if you would like to contribute to `<amp-theoplayer>`.

## Related content

* <https://amp.dev/>
* <https://amp.dev/documentation/components/amp-iframe/?format=websites>
* <https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-iframe-origin-policy.md>

---

# Getting started with WordPress

[WordPress](https://wordpress.org/) is a popular CMS. [Wikipedia](https://en.wikipedia.org/wiki/WordPress) writes that it was originally aimed at blogs, but nowadays it's leveraged for all sorts of use-cases. It's not uncommon to want to embed a video player on a WordPress website.

This guide describes one approach to integrate the THEOplayer Web SDK in an open-source WordPress.org deployment by using *Custom Code Blocks* and the *Code Editor*. As a developer, you can also opt for different approaches, as explained by <https://webdesign.tutsplus.com/tutorials/how-to-add-custom-javascript-to-your-wordpress-site--cms-34368> and <https://www.wpbeginner.com/wp-tutorials/how-to-easily-add-javascript-in-wordpress-pages-or-posts/>.

Interested in our WordPress 5+ plugin? [Reach out to us](https://www.theoplayer.com/contact) if you want to evaluate this.

## Selected approach

We use "[Custom HTML blocks](https://wordpress.com/support/wordpress-editor/blocks/custom-html-block/)" and the "[Code Editor](https://wordpress.com/support/editors/)" as our approach. Both features are accessible by default in a fresh WordPress.org 5.5 installation. This approach allows us to embed JavaScript and CSS libraries, as well as write unique JavaScript and HTML code for a specific page. Why is that relevant? When using the THEOplayer Web SDK, you use JavaScript to specify which video stream you want to configure, and typically you want to configure one (or more) unique streams per page.

### Alternatives

#### Code Embed plugin

You could use the [Code Embed plugin](https://wordpress.org/plugins/simple-embed-code/#description) because it allows you to embed unique JavaScript code per page (or post).

Other popular plugins, like [Insert Headers and Footers](https://wordpress.org/plugins/insert-headers-and-footers/), allow you to insert code which is shared across all posts and pages. This is useful for tracker scripts or pixels (like Google Analytics), but less so for video players which should only be integrated on some pages and with a unique video stream configured per page. You could consider using a plugin like "Insert Headers and Footers" to load the THEOplayer JavaScript and CSS files (i.e. the SDK files) on every page, but you typically still want to embed some unique JavaScript code per page to configure the unique video stream.

*We have no affiliation with these plugins or their creators. They were just the first applicable plugins which popped up when looking.*

#### \<iframe>

You can embed THEOplayer through an `<iframe>` instead of through JavaScript. Please refer to "[How to embed an iframe](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/how-can-we-embed-iframe.md)" for more information on setting up an iframe.

## Step-by-step guide

### 1. WordPress.org deployment

You must have a valid WordPress.org deployment. We used WordPress version 5.5 in a [local MAMP set-up](https://skillcrush.com/blog/install-wordpress-mac/) when writing this article.

### 2. THEOplayer SDK

You must have the THEOplayer Web SDK library files (`THEOplayer.js`, `ui.css`, ...), or you must know how to refer to them and the `libraryLocation`. You've read through our [Web SDK Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md), and you understand all of its content.

### 3. Locate post or page

Navigate to the page where you want to integrate the THEOplayer Web SDK.

### 4. Include THEOplayer SDK

First off, you want to include the THEOplayer CSS file and THEOplayer JavaScript file by adding the code below through a Custom HTML block.

```html
<link rel="stylesheet" type="text/css" href="/path/to/libraryLocation/ui.css" />
<script type="text/javascript" src="/path/to/libraryLocation/THEOplayer.js"></script>
```

The screenshot below shows you how to access such a "Custom HTML block". ![WordPress Custom HTML](/pr-932/assets/images/wordpress-custom-html-e361f80bf642a46a6cd838a1861b40c7.png "WordPres Custom HTML")

### 5. Create container

Create the HTML `<div>` container which should load your video player instance.

Your Custom HTML block should now be similar to the code below.

```html
<link rel="stylesheet" type="text/css" href="/path/to/libraryLocation/ui.css" />
<script type="text/javascript" src="/path/to/libraryLocation/THEOplayer.js"></script>
<div class="video-js vjs-16-9 theoplayer-container theoplayer-skin"></div>
```

You can set the CSS of this container directly in the `<div>` tags by using `<div style="height: ...">`, or you could add additional CSS to your page.

We added `vjs-16-9` to the `<div class="...` because we want THEOplayer to render in a 16:9 aspect ratio. Sometimes, the CSS and styles of your WordPress theme might clash with THEOplayer's styling. It is your responsibility to identify styling issues caused by your theme. For example, the CSS of our WordPress skin tried to meddle with the width of our container, so we manually unset it as demonstrated below.

```html
<div class="video-js vjs-16-9 theoplayer-container theoplayer-skin" style="max-width: unset;"></div>
```

### 6. Configure video

Finally, you want to create your video player instance and configure a video stream for this player instance.

You can achieve this by expanding your Custom HTML block to resemble the snippet below:

```html
<link rel="stylesheet" type="text/css" href="/path/to/libraryLocation/ui.css" />
<script type="text/javascript" src="/path/to/libraryLocation/THEOplayer.js"></script>
<div class="video-js vjs-16-9 theoplayer-container theoplayer-skin" style="max-width: unset;"></div>
<script>
  var element = document.querySelector('.theoplayer-container');
  var player = new THEOplayer.Player(element, {
    libraryLocation: '/path/to/libraryLocation/',
    license: 'your-license-here',
  });

  player.source = {
    sources: [
      {
        src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
        type: 'application/x-mpegurl',
      },
    ],
  };
</script>
```

All of this should result in a demo similar to the screenshot below. ![WordPress Demo Screenshot](/pr-932/assets/images/wordpress-demo-screenshot-66c62d8dd0af8248b95aa77aecfca088.png "WordPres Demo Screenshot")

## Note

* Steps 4-6 are similar to our [Getting Started guide for Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md) so you might want to consider checking out that article as well.

---

# How-to guides for OptiView Player Web SDK

Want to start implementing features to your SDK? Our how-to-guides will help you with all kind of integrations!

## [💰Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/introduction.md)

[14 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/introduction.md)

## [📊Analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/introduction.md)

[16 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/introduction.md)

## [Cast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/introduction.md)

## [🔐DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md)

[19 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md)

## [🔌Integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/integrations/introduction.md)

[3 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/integrations/introduction.md)

## [🎥Media tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/introduction.md)

[9 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/introduction.md)

## [\*️⃣Miscellaneous](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/introduction.md)

[13 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/introduction.md)

## [📡Network](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/network/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/network/introduction.md)

## [▶️Player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/introduction.md)

[5 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/introduction.md)

## [💬Text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/introduction.md)

[9 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/introduction.md)

## [🔑License](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/license/introduction.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/license/introduction.md)

## [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/introduction.md)

[7 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/introduction.md)

## [☁️CMCD](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cmcd/getting-started.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cmcd/getting-started.md)

## [🚦Content Steering](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/content-steering/mpeg-dash-content-steering.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/content-steering/mpeg-dash-content-steering.md)

## [🚀OptiView Live](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/theolive/getting-started.md)

[Integrate OptiView Live streaming into your web app.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/theolive/getting-started.md)

---

# Advertisements on Web

The articles in this section describe how to implement common use-cases related to advertisements. These use-cases can range from customizing the UX during advertisements, to detecting ad blockers.

Consider reading our [Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/user-guide.md) to learn more about advertising and THEOplayer's capabilities.

We recommend starting with [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/set-up-vast-and-vmap.md), as this article explains how to set up client-side advertisements.

### Table of Contents

* Client-side advertisement systems

  * [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/set-up-vast-and-vmap.md)
  * [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/google-ima.md)
  * [SpotX](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/spotx.md)
  * [FreeWheel](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/freewheel.md)

* Server-side advertisement systems

  * [Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/yospace.md)
  * [Google DAI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/google-dai.md)
  * [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ads.md)
  * [MediaTailor](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/mediatailor.md)
  * [Custom Server Side Ad Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/custom-ssai-integration.md)

* Other

  * [How to subscribe to ad events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/subscribe-to-ad-events.md)
  * [Adblock detection](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/block-detection.md)
  * [Customizing the ad overlay text](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/customizing-the-ad-overlay-text.md)
  * [How to display visual cues on the timeline to mark mid-rolls?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/visual-cues-for-mid-rolls.md)
  * [Prebid.js](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/prebidjs.md)

---

# Adblock detection on Web

The THEOplayer Ads API allows developers to detect adblockers, and react accordingly. More specifically, you can either A) specify a stream configuration that disables playback when an ad blocker is detected, and show a default error message, or either B) detect an `aderror` event and implement a custom handler.

The screenshot below illustrates the default error message.

![Ad block detection](/pr-932/assets/images/ad-blocker-detected-2021-8f2264848bf980c284f2e5744c2acd30.png "Adblock detection")

## Usage

Adblock detection is typically a challenge in browsers, which is why this feature is only applicable to the Web SDK. THEOplayer does not prevent playback by default when an ad blocker is detected.

As explained in the intro, you can either A) configure your stream configuration to prevent playback and show a default error message, or either B) implement an error event handler to implement a custom behavior.

### Stream configuration

When you set the `blockContentIfAdError` to `true` in your stream configuration (i.e. [SourceConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/SourceConfiguration#blockContentIfAdError)), then playback will be stopped, and a default error message will be shown.

The snippet below demonstrates how you could implement this `blockContentIfAdError` property in a stream configuration.

```js
player.source = {
  sources: {
    src: '//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
  },
  ads: [
    {
      sources:
        'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=',
    },
  ],
  blockContentIfAdError: true,
};
```

Through localization, you could rename the default error message, as demonstrated below.

```javascript
var player = new THEOplayer.Player(document.querySelector('.video-js'), {
  ui: {
    language: 'en',
    languages: {
      en: {
        'Starting ads was not possible. Turn off your AdBlocker and try again.': 'Disable your AdBlocker.',
      },
    },
  },
  libraryLocation: '<your-library-location>',
});
```

When you go for this approach, it's important that you validate and correctly specify the current default error message. At the time of writing, the default error message is `Starting ads was not possible. Turn off your AdBlocker and try again.`.

If you want to customize beyond renaming the default error message, then you could try to do custom DOM manipulation and custom CSS queries. However, it might be advised to leverage the `aderror` event, as explained in the next section, if you truly want to customize the behavior.

### Error event

Alternatively, you can detect an ad blocker through the `aderror` event. If you detect this event, you could implement a custom behavior, such as stopping playback (e.g. through `player.stop()`) and drawing an overlay.

The callback event may be differently formatted depending on your selected ad integration.

If you're using the [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/google-ima.md) ad integration, your callback event will have a `problemType` property that will equal `"adblock"`.

```javascript
player.ads.addEventListener('aderror', function (event) {
  // if using the Google IMA SDK, then your event looks like this:
  // {
  //  "type": "aderror",
  //  "date": "2021-03-09T18:18:03.093Z",
  //  "ad": null,
  //  "problemType": "adblock",
  //  "message": "adblock",
  //  "source": {
  //    "src": "https://pubads.g.doubleclick.net/gampad/ads?..."
  //  }
  // }
  // so, to detect an ad blocker, you can do
  if (event.problemType == 'adblock') {
    // and do something else
  }
});
```

If you're using the default ad integration, your callback event will have a `problemType` property that will equal `"network"`.

```javascript
player.ads.addEventListener('aderror', function (event) {
  // if using the default ad integration, then your event looks like this:
  // {
  //   "type": "aderror",
  //   "date": "2021-03-09T19:22:15.171Z",
  //   "ad": null,
  //   "problemType": "network",
  //   "message": "The ad source could not be loaded.",
  //   "errorCode": 100,
  //   "source": {
  //     "src": "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator="
  //   }
  // }
  // so, to detect an ad blocker, you can do
  if (event.problemType == 'network') {
    // and do something else
  }
});
```

## Resources

Below are some resources on adblock detection through the Ads API:

* API reference: [Ads API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Ads)
* Online demo: [Adblock Detection Demo](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/ad-block-detection.md)
* Advertisement guide: [Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/user-guide.md) (mentions adblock detection)

---

# Customizing the ad overlay text on Web

This guide explains how to customize the overlay text shown during an ad break. You may ask this question if you want to change the styling or override the texts shown during an ad break.

Depending on the ad integration kind you use, the steps to take differ.

## CSAI integration

The `csai` [ad integration kind](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/AdIntegrationKind) is only available on Web SDK and allows customization.

To customize the text here we will be leveraging the language localization mechanism. You can find the API we will be using [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UIConfiguration#language).

The second step is to customize the styling of texts. This can be done via CSS.

### Changing or localizing the text

In this section, we will explain how to modify the text. We will take the countdown to the content text as an example (another ad overlay text is the "Skip ad" text, if any). When considering a new text to replace the original one, it is important to take into consideration its length (which should be determined accordingly to the available space) and how it is composed.

The current example is composed of 3 parts: one text ("The content will play in"), a dynamic countdown and another text ("seconds"). For this reason, when changing the text, both text parts need addressing.

An example:

```js
var element = document.querySelector('.video-js');
const player = new THEOplayer.Player(element, {
  license: 'your_license_here',
  ui: {
    // your other UI configuration
    language: 'en',
    languages: {
      en: {
        'The content will play in': 'Here your customized text',
        seconds: 'Here your customized text',
        // any other translation or text change
      },
    },
  },
  libraryLocation: 'https://example.com/',
});
```

### Changing the styling

If you are interested in changing the aspect of the overlay or its content, you may do so applying the desired CSS properties to the concerned elements.

As mentioned, the following example is only valid for the `csai` ad integration:

```css
/* This modifies the countdown div */
.theo-ad-remaining-container {
  /* your styles here */
}

/* This modifies the skip ads div */
.theoplayer-ad-skip {
  /* your styles here */
}

/* this can also be further differentiated in 2 cases:*/

/* the countdown */
.theoplayer-ad-skip.theoplayer-ad-skip-countdown {
  /* your styles here */
}

/* the button */
.theoplayer-ad-skip.theoplayer-ad-skip-button {
  /* your styles here */
}
```

## Google IMA/DAI

With Google IMA/DAI, it is not possible to directly edit the default UI. You can pass a locale to IMA to completely localize the ad UI.

### Changing or localizing the text

It is not possible to edit the texts on the default UI on Google IMA/DAI SDKs. However, you can pass a locale to IMA to completely localize its ad UI like the following:

```javascript
var element = document.querySelector('.video-js');
const player = new THEOplayer.Player(element, {
  license: 'your_license_here',
  libraryLocation: 'https://example.com',
  ads: {
    googleIma: {
      language: 'nl',
    },
  },
});
```

You can find a list of locales supported by the IMA SDK on web [here](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/localization#locale-codes).

### Changing the styling

Currently it is not possible to customize the default UI on Google IMA/DAI SDKs on Web with the exception of toggling certain [UiElements](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima#.UiElements). This can be done like the following:

```javascript
var element = document.querySelector('.video-js');
const player = new THEOplayer.Player(element, {
  license: 'your_license_here',
  libraryLocation: 'https://example.com',
  ads: {
    googleIma: {
      uiElements: [google.ima.UiElements.AD_ATTRIBUTION, google.ima.UiElements.COUNTDOWN],
    },
  },
});
```

## Remarks

* If you customize OptiView Player with [Open Video UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md), there may be other ways to edit certain elements depending on the platform and ad integration. See the [Web SDK CSAI example](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/examples/ads.md) for reference.
* The `Why this ad?` text or the `?` (question mark) icon that may appear while using the Google IMA/DAI integration is inserted by the IMA SDK itself and is required to be displayed with any ad that was not manually selected. The icon is rendered as a VAST icon and is automatically generated by Ad Manager where required.

## Resources

* [How to change the UI language](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/change-ui-language.md)
* [Language localization](https://www.theoplayer.com/theoplayer-demo-language-localization)
* [THEOplayer advertisement tester](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/advertisement-tester.md)

---

# How to set up VAST and VMAP ads on Web

This article explains how to schedule client-side VAST and VMAP advertisements through THEOplayer.

* A VAST advertisement is a single ad break, and you can position it as a pre-roll, mid-roll or post-roll.
* A VMAP advertisement is a playlist of ad breaks, and can contain any combination of pre-rolls, mid-rolls and/or post-rolls.

Through the THEOplayer API, app developers can define which "ad integration" they want to use. Scheduling VAST and VMAP ads through all ad integrations is very similar, so consider this article as a reference guide.

The Web SDK currently supports 4 types of client-side ad integrations:

1. CSAI
2. [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/google-ima.md)
3. [SpotX](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/spotx.md)
4. [FreeWheel](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/freewheel.md)

## VAST

Setting up a client-side VAST advertisement means scheduling a VAST ad tag.

As an app developer, you associate a VAST ad tag (URL) (e.g. `https://cdn.theoplayer.com/demos/ads/vast/vast.xml`) with a time offset.

You may also schedule multiple ad tags.

Additionally, when using the default, `csai` ad integration, you can also specify after how many seconds a VAST ad may be skipped. If you are using Google IMA, the skip offset should be set inside the ad tag instead.

Let's consider the following common use-cases:

1. [Scheduling a single pre-roll](#scheduling-a-single-pre-roll)
2. [Scheduling two pre-rolls, two mid-rolls and one post-roll](#scheduling-two-pre-rolls-two-mid-rolls-and-one-post-roll)
3. [Scheduling a skippable mid-roll](#scheduling-a-skippable-mid-roll)

### Scheduling a single pre-roll

You configure an [AdDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdDescription) in the `ads` property of your [SourceConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/SourceConfiguration).

In this `AdDescription`,

* You set the value of `sources` to an object with the URL of your ad tag as its `src`.
* You set the value of `timeOffset` to `"start"` (or `00:00:00` or `0%`) to indicate that it's a pre-roll.
* Optionally, you set the `type` of that `sources` object to `"vast"`. When this isn't provided, the player will still try to figure out its `type` after making the ad request.

```js
player.source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
    },
  ],
  ads: [
    {
      sources: { src: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml', type: 'vast' },
      timeOffset: 'start',
      integration: 'csai', // When no integration is provided, the player defaults to `csai`.
    },
  ],
};
```

If you wanted to schedule a post-roll instead of a pre-roll, you set the value of `timeOffset` to `"end"`.

If you want to schedule a mid-roll instead of a pre-roll, you set the value of `timeOffset` to the `HH:MM:SS` format.

For example, to schedule an advertisement at the 15s mark, you set the value of `timeOffset` to `"00:00:15"`.

If you wanted to use Google IMA as an example, you would replace `integration: "csai"` with `integration: "google-ima"`. Before doing so, make sure you have [set up Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/google-ima.md) correctly.

### Scheduling two pre-rolls, two mid-rolls and one post-roll

Scheduling multiple VAST ads is only slightly different from scheduling a single VAST ad. Instead of passing along one ad description to your array, you pass along multiple ad descriptions to the array.

The following snippet demonstrates how you would configure two pre-rolls, two mid-rolls and one post-roll through the usage of VAST ads.

```js
player.source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
    },
  ],
  ads: [
    {
      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
      timeOffset: 'start',
    },
    {
      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
      timeOffset: 'start',
    },
    {
      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
      timeOffset: '00:00:15',
    },
    {
      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
      timeOffset: '00:00:30',
    },
    {
      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
      timeOffset: 'end',
    },
  ],
};
```

### Scheduling a skippable mid-roll

When using the `csai` ad integration, you can define when a VAST ad can be skipped through the `skipOffset` property.

However, it is recommended to leverage the `skipOffset` property in your VAST (or VMAP) file instead, and adhere to the [VAST standard](https://iabtechlab.com/standards/vast/), because this offers the widest support across ad integrations and platforms.

The following snippet demonstrates how to allow viewers to skip a mid-roll after 5 seconds.

Note that the `skipOffset` property is not supported when using other ad integrations, such as Google IMA, SpotX and FreeWheel because we are dependent on third-party APIs.

```javascript
player.source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
    },
  ],
  ads: [
    {
      sources: { src: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml', type: 'vast' },
      timeOffset: '00:00:15',
      skipOffset: '5',
    },
  ],
};
```

## VMAP

Scheduling a VMAP advertisement is similar to scheduling a VAST advertisement. However, you don't define the `timeOffset`, because the VMAP playlist defines the offsets of each ad break it contains. The time offset helps VAST ads to play at a specific timestamp. VMAP ads can define that behavior inside their manifest file, thus they should not have a timeOffset parameter. This property may not be configured for ad types other than `VAST`. Setting a `timeOffset` on a `VMAP` ad will cause your ads not to be scheduled correctly, unless you explicitly configured an `AdSource.type`, in which case `timeOffset` will be ignored. This is because the player must decide up front when to load the ad source: `VMAP` ads must be loaded immediately in order to schedule them correctly, while loading a `VAST` ad can be deferred until right before the `timeOffset` at which to play them. Therefore, if a `timeOffset` is configured without an explicit `AdSource.Type`, the player will assume that it's a `VAST` ad.

The snippet below demonstrates how to configure a VMAP advertisement.

```js
// Declare a VMAP ad source. No timeOffset here, because the VMAP itself arranges this.
player.source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
    },
  ],
  ads: [
    {
      sources: { src: 'https://cdn.theoplayer.com/demos/ads/vmap/single-pre-mid-post-no-skip.xml', type: 'vmap' },
      integration: 'csai', // When no integration is provided, the player defaults to `csai`.
    },
  ],
};
```

## Dynamic scheduling

If you've read our [Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/user-guide.md#dynamic-ad-scheduling), you might have picked up that you can also dynamically schedule VAST advertisements in THEOplayer. All previous samples in this article use static, pre-defined scheduling; you schedule the ads whenever you schedule the stream. With dynamic scheduling, you schedule ads at runtime.

You use the `Ads` interface to schedule an ad description at runtime. More specifically, you invoke the `schedule` function when your video is already playing.

Note that specifying the `timeOffset` is optional, and that this value is an absolute value. For example, let's consider that your current playhead position is at the 20 seconds mark, and that you want to schedule an ad at the 30 seconds mark. To achieve this, you would set `timeOffset: "00:00:30"`, and not `timeOffset: "00:00:10"`, because this would be 10 seconds in the past, and the ad would instantly start playing.

Invoking the following example function when the video is already playing will instantly schedule the VAST ad to be played:

```javascript
player.ads.schedule({
  sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
});
```

## Resources

* [Samples for Web SDK](https://github.com/THEOplayer/samples-html5-sdk)

---

# Yospace on Web

Yospace is a Server-Side Ad Insertion solution. THEOplayer partnered with Yospace to fully integrate their solution, allowing you to play their streams in a breeze.

A demo for the Web SDK can be found [here](https://demo.theoplayer.com/ssai).

## Usage

You need to set up [THEOplayer Yospace Connector for Web](https://github.com/THEOplayer/web-connectors/tree/main/yospace). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/yospace) section to learn all about how to integrate and use the Yospace connector on Web SDK.

## Conclusion

This partnership means that we are compatible with each other: THEOplayer has a long history with and is optimized to play Yospace streams. We regularly validate our connectors and are the first to know about changes to the Yospace infrastructure.

## Resources

* [Getting started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md)
* [Yospace website](https://www.yospace.com/)

---

# How to display visual cues on the timeline to mark mid-rolls on Web

You may ask this question if you want to let the user know when and how many mid-rolls there are during the video.

Similar questions may be:

* Can I show where my ad is during the video?
* How can I let the user know when the ads will be during the video like in YouTube?
* Can ad markers be added to the timeline?

Showing visual cues indicating the moment in which the ads will start is certainly useful. **This is not (yet) a THEOplayer standard feature, but what follows is a first step in that direction**. Please keep in mind that this solution is still in development and has to date several limitations.

## Prerequisites and limitations

* It only works for THEOplayer ad integration

* A timeOffset for each roll must be included in the AdDescription

* timeOffset values must be one of the following:

* a keyword (“start” and “end” allowed);

* a number (seconds from video beginning);

* undefined (which indicates a pre-roll).

* it has only been tested on Chrome, Firefox and Edge for Win 10 and with the standard THEOplayer UI.

## The code

Add this line to your CSS

```css
.adCue {
  width: 0.3em;
  height: 100%;
  background-color: white;
  position: absolute;
  top: 0;
}
```

Your AdDescription should look something like this

```js
player.source.ads: [
    {
        "sources": "path/to/your-pre/midroll1.xml",
            "timeOffset": value //valid values: ["start", "end", numbers]
    },
    {
        "sources": "path/to/your-pre/midroll2.xml",
            "timeOffset": value //valid values: ["start", "end", numbers]
    },
    {...}
]
```

Include (or call) this JavaScript snippet on your page:

THEOdisplayCues.js

```js
var adsPresent = !!player.source.ads;
var contentDuration = 0;
var to = [];
var checker = true;
var playedAds = [];

player.addEventListener('pause', () => {
  checker = false;
});
player.addEventListener('playing', () => {
  var adIsPlaying = player.ads.playing;
  detectTimeOffset();
  detectDuration(adIsPlaying);
  if (!checker) {
    checker = adIsPlaying;
  }
  if (checker) {
    !adIsPlaying ? drawCues() : destroyCues();
  }
});

player.addEventListener('sourcechange', function () {
  playedAds.length = 0;
});

player.ads.addEventListener('adend', (adEvent) => {
  playedAds.push(adEvent.ad.adBreak.timeOffset);
});

function drawCues() {
  var progressBar = element.querySelector('.vjs-progress-control.vjs-control');

  for (var i = 0; i < to.length; i++) {
    var timeOffset = to[i];

    if (playedAds.indexOf(timeOffset) === -1) {
      var left = (to[i] * progressBar.offsetWidth) / contentDuration;
      var div = document.createElement('div');
      div.setAttribute('to', to[i]);
      div.classList.add('adCue');
      div.style.left = left + 'px';
      progressBar.children[0].appendChild(div);
    }
  }
}

function destroyCues() {
  var cues = element.querySelectorAll('.vjs-progress-control.vjs-control .adCue');
  for (cue of cues) {
    cue.parentNode.removeChild(cue);
  }
}

function detectDuration(adIsPlaying) {
  if (!adIsPlaying) {
    contentDuration = player.duration;
    //console.log("Duration ",contentDuration)
  }
  var t = 0;
  for (var ad of player.source.ads) {
    to[t] = to[t] == 'end' ? contentDuration : to[t];
    t++;
  }
}

function detectTimeOffset() {
  if (adsPresent) {
    var t = 0;
    for (var ad of player.source.ads) {
      to[t] = ad.timeOffset == undefined ? 0 : ad.timeOffset == 'start' ? 0 : ad.timeOffset;
      t++;
    }
  }
  //console.log("TimeOffsets ",to);
}
```

---

# FreeWheel on Web

This guide explains how to set up THEOplayer in combination with FreeWheel, an advertisement vendor.

This guide expects that you are a FreeWheel client and that you have ad campaigns ready for use. Information on FreeWheel can be found at <https://freewheel.com>.

The FreeWheel integration is currently only available on the Web SDK.

## Prerequisites

There are prerequisites when using FreeWheel through THEOplayer.

1. You must enable the `freewheel` module when building your THEOplayer SDK through the [THEOplayer Development Portal](https://portal.theoplayer.com).
2. You must have access to the `FreeWheel SDK`, as explained further in this guide.

## How to integrate FreeWheel

This example explains how you do a basic implementation of FreeWheel in THEOplayer.

After setting up your basic page containing THEOplayer, you need to add the FreeWheel MRM client SDK to the page:

`<script type='text/javascript' src='https://mssl.fwmrm.net/libs/adm/6.xx.x/AdManager.js'></script>`

Next, you add a [`FreeWheelAdDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/FreeWheelAdDescription) to your source that specifies the FreeWheel tokens. An example sourceDescription could look like this:

```html
...
<!-- make sure to link to a valid version number -->
<script type="text/javascript" src="https://mssl.fwmrm.net/libs/adm/6.xx.x/AdManager.js"></script>
... player.source = { sources : [{ src : 'your.m3u8', type : 'application/x-mpegurl' }], ads: [{ integration: 'freewheel', networkId: 96749, assetId:
'DemoVideoGroup.01', profile: 'global-js', assetDuration: 22, adServerUrl: 'https://demo.v.fwmrm.net/ad/g/1', siteSectionId: 'DemoSiteGroup.01',
cuePoints: [{ adUnit: 'preroll' }] }] };
```

We configure cuePoints in this example. This is needed for some set-ups or completely optional for others. THEOplayer will create a FreeWheel temporalSlot behind the screens, which is a request to schedule an advertisement at said point. It is up to FreeWheel (and the campaign settings) to decide whether it will insert an advertisement at this requested time. Not all campaigns need it and for some campaigns the requested cuePoints might even be ignored by FreeWheel.

## Resources

The following resources provide more information:

1. [THEOplayer Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md)

2. [FreeWheelAdDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/FreeWheelAdDescription)

3. [FreeWheel website](https://freewheel.com)

---

# SpotX on Web

SpotX is a global video ad serving platform providing digital media owners with a solution that allows them to monetize their content with video advertising across desktop, mobile and connected devices.

The SpotX integration is currently only available on the Web SDK.

## Prerequisites

Your THEOplayer SDK must have the `SpotX` module enabled. You can enable this module when building your THEOplayer SDK through the [THEOplayer Development Portal](https://portal.theoplayer.com).

## Integrating SpotX

Add the SpotX ad integration when configuring the player

```javascript
player.source = {
    sources: ...,
    ads: [{
        integration: 'spotx',
        ...
    }]
}
```

the `{{SpotXAdDescription}}` object provides the following properties:

| Method            | Type             | Optional | Description                                                                                                                                                                                                                                                                                    |
| ----------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| integration       | string           | yes      | Use the value 'spotx' to use the SpotX ad integration. The SpotX integration uses Google IMA. To use Google IMA, it is required to load the SDK first. You can find the getting started of Google IMA sdk at: <https://developers.google.com/interactive-media-ads/docs/sdks/html5/quickstart> |
| id                | number or string | no       | Your SpotX id                                                                                                                                                                                                                                                                                  |
| cacheBuster       | boolean          | yes      | Add the cb parameter with a random number to the SpotX tag.                                                                                                                                                                                                                                    |
| maximumAdDuration | number or string | yes      |                                                                                                                                                                                                                                                                                                |
| custom            | SpotXData        | yes      | SpotX custom data                                                                                                                                                                                                                                                                              |
| app               | SpotXData        | yes      | SpotX app data                                                                                                                                                                                                                                                                                 |
| device            | SpotXData        | yes      | SpotX device data                                                                                                                                                                                                                                                                              |
| user              | SpotXData        | yes      | SpotX user data                                                                                                                                                                                                                                                                                |
| sources           | string           | yes      | SpotX ad tag (to directly set the SpotX source link)                                                                                                                                                                                                                                           |

Example:

```javascript
player.source = {
    sources: ...,
    ads: [{
        integration: 'spotx',
        id: 123456,
        cacheBuster: true,
        app: {
            bundle: 'com.exampleapps.example',
            name: 'My CTV App'
        },
        device: {
            ifa: '38400000-8cf0-11bd-b23e-10b96e40000d',
            ua: 'Mozilla/5.0 (iPhone; CPU iPhone OS 10_3 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) CriOS/56.0.2924.75 Mobile/14E5239e Safari/602.1',
            geo: {
                lat: -24.378528,
                lon: -128.325119
            },
            dnt: 1,
            lmt: 1,
        },
        custom: {
            category: ['category1', 'category2'],
            somekey: 'somevalue'
        },
        user: {
            yob: 1984,
            gender: 'm'
        }
    }
]};
```

---

# Google Dynamic Ad Insertion (DAI) on Web

Google Dynamic Ad Insertion (DAI) is a Server-Side Ad-Insertion solution offered by Google where THEOplayer offers playback for HLS and DASH streams.

A demo can be found at <https://demo.theoplayer.com/google-dai>.

## Prerequisites

1. Your THEOplayer SDK needs to have the `google-dai` module enabled.
2. You need to include the Google DAI JavaScript SDK as this is a dependency.

## Starting Template

The first thing you need is a valid THEOplayer setup. If you have no experience with setting up our player, we have an excellent [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md).

To get THEOplayer to work, you only need to do three things:

1. Reference the THEOplayer JavaScript library (and optionally the default CSS styles).
2. Add a container which can hold your video player with HTML.
3. Create your player through JavaScript using our [API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/Player).

A basic HTML page with a working THEOplayer could like the following:

```html
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>THEOplayer Web SDK: Getting Started</title>
        <metaname="viewport"content="width=device-width, initial-scale=1.0">
        <link rel="stylesheet" type="text/css" href='/path/to/ui.css'><!-- ads THEOplayer CSS -->
    </head>
    <body>

        <div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>

        <script type='text/javascript' src='/path/to/THEOplayer.js'></script><!-- ads THEOplayer library -->
        <script>

            var element = document.querySelector('.theoplayer-container');
            var player = new THEOplayer.Player(element);

            player.source = {
                sources : [{
                    src : 'your.m3u8',
                    type : 'application/x-mpegurl'
                }]
            };

        </script>
    </body>
</html>
```

## Integrating Google DAI

Add a Google DAI JavaScript library.

```javascript
<script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
```

Add a Google DAI ad configuration to the sources.

```javascript
const TYPES = {
  hls: 'application/vnd.apple.mpegurl',
  dash: 'application/dash+xml',
};

// example and reference tester at https://developers.google.com/interactive-media-ads/docs/sdks/html5/dai/vastinspector
const SOURCES = {
  dash: {
    vod: {
      integration: 'google-dai',
      availabilityType: 'vod',
      apiKey: null,
      contentSourceID: '<contentSourceID>',
      videoID: '<videoID>',
    },
    live: {
      integration: 'google-dai',
      availabilityType: 'live',
      apiKey: null,
      assetKey: '<assetKey>',
    },
  },
  hls: {
    vod: {
      integration: 'google-dai',
      availabilityType: 'vod',
      apiKey: null,
      contentSourceID: '<contentSourceID>',
      videoID: '<videoID>',
    },
    live: {
      integration: 'google-dai',
      availabilityType: 'live',
      apiKey: null,
      assetKey: '<assetKey>',
    },
  },
};
// Configure THEOplayer Source
const MANIFEST_TYPE = 'hls'; // 'hls' / 'dash'
const AVAILABILITY_TYPE = 'vod'; // 'vod' or 'live'

player.source = {
  sources: {
    type: TYPES[MANIFEST_TYPE],
    ssai: SOURCES[MANIFEST_TYPE][AVAILABILITY_TYPE],
  },
};
```

## Resources

* [Google DAI Pre-Integration API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/GoogleDAIConfiguration)
* [THEOplayer Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md)
* [Google DAI website](https://developers.google.com/interactive-media-ads)
* [Google DAI HTML5 Reference](https://developers.google.com/interactive-media-ads/docs/sdks/html5/dai)

---

# Prebid.js on Web

This article explains how you can connect THEOplayer with Prebid.js. Prebid.js is an open-source header bidding solution. On the client-side, you can request bids from multiple ad networks, take a winning bid and select its associated advertisement. You want to configure and play this selected advertisement in THEOplayer.

Because Prebid.js is a separate library, you can connect it with THEOplayer on any platform that supports both Prebid.js and THEOplayer.

Prebid.js allows you to request bids. This request will respond with bids through a callback function. In this callback function, you have to select a winning bid and extract the ad tag URL. You can configure this URL as THEOplayer's ad source.

## Code example

The code example below is based on the documentation offered by Prebid.org [here](https://docs.prebid.org/dev-docs/examples/instream-banner-mix.html).

The sample application at <https://cdn.theoplayer.com/demos/prebidjs.html> is an example of implementing Prebid.js on top of the THEOplayer Web SDK.

The example above schedules advertisements as pre-rolls (or mid-rolls or post-rolls). You can also dynamically schedule advertisements with the Ads API, as explained in [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/set-up-vast-and-vmap.md).

## Resources

* [What is Prebid?](https://prebid.org/product-suite/prebidjs/)
* [Prebid.js documentation](https://docs.prebid.org/)
* [Prebid.js on GitHub](https://github.com/prebid/Prebid.js)

---

# Google IMA on Web

THEOplayer offers support for Google IMA as an ad integration system. Users of Google Ad Manager (formerly known as DoubleClick for Publishers) should use this ad integration.

To schedule and track ads through Google IMA, you need to include the Google IMA SDK and indicate through the API that you want to use Google IMA as the ad integration.

You're advised to read through [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/set-up-vast-and-vmap.md) first.

To use Google IMA in the Web SDK,

1. You need to include the Google IMA SDK,
2. You need to specify `integration: "google-ima"` in your `AdDescription`.

## Include the IMA SDK

Google IMA has a dependency on the IMA SDK. Hence, this library needs to be included. The following snippet demonstrates how the IMA SDK can be included:

```html
<script type="text/javascript" src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
```

Alternatively, you can include the debug version of the IMA SDK for troubleshooting, which will provide extra logs from IMA on console:

```html
<script type="text/javascript" src="https://imasdk.googleapis.com/js/sdkloader/ima3_debug.js"></script>
```

## Specify the integration

You need to set integration to `"google-ima"`, as demonstrated by the snippet below which configures a pre-roll VAST ad.

```javascript
player.source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
    },
  ],
  ads: [
    {
      integration: 'google-ima',
      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
      timeOffset: 'start',
    },
  ],
};
```

## Limitations

* There's a known issue within the IMA HTML5 SDK where it does not work well with multiple VPAID ads in a VMAP. More specifically when the `ImaSdkSetting` `vpaidMode` is set to `enabled` and the `AdsRenderingSetting` `enablePreloading` is set to `true`, it will not manage to play all ads (these are the default configurations when using the Google IMA integration in THEOplayer). The production IMA SDK doesn't throw any error in this scenario, the [debug SDK](https://imasdk.googleapis.com/js/sdkloader/ima3_debug.js), however, prints `Vpaid Error: VPAID ad called play on video element before start was called on VPAID manager` in the console in this case. This can be resolved by either using `vpaidMode` `insecure` or by disabling preloading. Both can be achieved by specifying your preference in the [AdsConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsConfiguration).

## Remarks

* The release notes for the IMA SDK can be found on the [IMA HTML5 SDK release history](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/history) page.
* THEOplayer internally supports IMA SDK up until a certain version across different SDKs. We regularly update the internal code to stay up to date with the latest version of IMA SDK. Later versions of IMA SDK should work as expected, however there could be cases where a fix for a breaking change or a newly introduced API is required. Please reach out to us if you require support for a more recent IMA SDK since we intend to rectify this limitation.
* The limitations documented on the support and compatibility pages of the IMA SDK also apply to THEOplayer when the IMA integration is used. You can find the [support matrix of the IMA HTML5 SDK](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/compatibility) on their website.
* You can try out the snippets mentioned here on our [samples app for Web SDK](https://github.com/THEOplayer/samples-html5-sdk).

---

# How to subscribe to ad events on Web

When building a custom UI, or when logging events to an analytics service, app developers often need to be able to listen (and react) to ad events. For example, if an ad break starts, they want to draw a countdown on top of their UI. Alternatively, when an ad error occurs, they want to log this to an analytics server.

This article explains how you can programmatically subscribe to ad-related events.

## Subscribing to an event

This subsection explains how you detect ad-related events. The other subsections zoom in on particular use-cases, such as detecting the beginning and end of an ad.

If you are scheduling [client-side advertisements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/set-up-vast-and-vmap.md), then you use the `Ads` interface to detect ad events.

The `Player` API exposes an [`ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#ads) property which belongs to the [`Ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Ads) interface. Because this [`Ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Ads) interface inherits from [`EventDispatcher<AdsEventMap>`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap), you can leverage event listeners in this interface.

The ad-related events are documented in [`AdsEventMap`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap).

To subscribe to an event, you select an event from this page, use the `Ads` interface, call the `addEventListener` method, and set the event as the first parameter, and the callback as the second parameter.

For example, if you want to track the start of an ad break, you could use the following snippet:

```javascript
player.ads.addEventListener('adbreakbegin', function (event) {
  console.log(event);
});
```

The following snippet should log most events to the console.

```javascript
player.ads.addEventListener(
  [
    'adbegin',
    'adbreakbegin',
    'adbreakchange',
    'adbreakend',
    'adbuffering',
    'addad',
    'addadbreak',
    'adend',
    'aderror',
    'adfirstquartile',
    'adimpression',
    'adloaded',
    'admetadata',
    'admidpoint',
    'adskip',
    'adthirdquartile',
    'removeadbreak',
    'updatead',
    'updateadbreak',
  ],
  console.log
);
```

Note that when dealing with client-side advertisements, you have different types of integrations, as explained at [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/set-up-vast-and-vmap.md). The impact of this is that some events are not available throughout all integrations.

For example, if you schedule `https://cdn.theoplayer.com/demos/preroll.xml`, which is a single linear VAST ad, through the "Google IMA integration" [on our advertisement tester](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/advertisement-tester.md), the above snippet will trigger the following events:

> `addad`, `updateadbreak`, `updatead`, `adloaded`, `adbreakbegin`, `adbegin`, `adimpression`, `adfirstquartile`, `admidpoint`, `adthirdquartile`, `adend`, `adbreakend`, `removeadbreak`

When you do the same for the `csai` ad integration, you get the following events:

> `adloaded`,`adbreakchange`,`adbreakbegin`,`adbegin`,`adend`,`adbreakend`

## Ad begin and end

Detecting the start and stop of ad breaks and individual ad pods is a common requirement.

This use-case is an application of [Subscribing to an event](#subscribing-to-an-event), and relates to the following events:

* `adbegin`
* `adbreakbegin`
* `adbreakend`
* `adend`

For example, the following snippet would trigger the callback when an ad break begins:

```javascript
player.ads.addEventListener('adbreakbegin', function (event) {
  console.log(event);
});
```

You can swap `adbreakbegin` for the other events, or supply an array instead:

```javascript
player.ads.addEventListener(['adbegin', 'adbreakbegin', 'adbreakend', 'adend'], function (event) {
  console.log(event);
});
```

## Ad error

Ad error events might be triggered when an ad blocker is active, or when an "empty" ad is returned. As an app developer, you might want to detect and possibly react to this.

This use-case is an application of [Subscribing to an event](#subscribing-to-an-event), specifically the `aderror` event.

The following snippet would trigger the callback when an ad error occurs:

```javascript
player.ads.addEventListener('aderror', function (event) {
  console.log(event);
});
```

## Server-side ads

If you're scheduling server-side ads, you might need to use a different interface than the `Ads` interface which you use when scheduling client-side ads.

* [Google DAI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/google-dai.md): if you're using Google DAI, you can use the same API as the one for client-side ads, as described in the sections above.
* [Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/yospace.md): if you're using Yospace, you must use the Yospace interface. You can read more about detecting ad-related events with Yospace at our [Yospace documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/yospace.md).
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ads.md): if you're using Uplynk, you can use the same API as the one for client-side ads, as described in the sections above. For now, you can also use the Uplynk Ads API. You can read more about detecting ad-related events with Uplynk at our [Uplynk documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ads.md#uplynk-ads-api).

If you're building a custom server-side ad insertion solution, you might be interested in using our `TextTrack` API to detect `id3/emsg/EventStream/EXT-X-DATERANGE` cues, and the `timeupdate` event in the `Player` interface to determine the current playhead position.

## Ad block detection

Refer to the article on [ad block detection](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/block-detection.md) for more information on detecting (and responding) to ad blockers.

## Resources

* More samples are available on our GitHub repository for the [Web SDK](https://github.com/THEOplayer/samples-html5-sdk).
* [THEOplayer advertisement tester](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/advertisement-tester.md)

---

# MediaTailor on Web

[AWS Elemental MediaTailor](https://docs.aws.amazon.com/mediatailor/index.html) is a service that provides scalable ad insertion and channel assembly. It is able to serve targeted ad content to viewers and create linear streams while maintaining broadcast quality in over-the-top (OTT) video applications. It supports HLS and DASH for both VOD and live workflows.

At the moment of writing only linear ads are supported, but it is possible to expand it to non-linear and companion ads as well.

## Configuration

There are three requirements to use a MediaTailor stream with THEOplayer:

* Have a THEOplayer build with the `mediatailor` feature flag set.
* The `src` is set to the session initialization URL.
* The integration parameter is set with the value `mediatailor`.

If everything is set up correctly, THEOplayer will play the stream and send the necessary tracking beacons.

```js
const player = new THEOplayer.Player(element, {
    libraryLocation: 'path/to/theoplayer',
    license: 'your-license-here',
    ...
});

player.source = {
    sources: [
        {
            src: '<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>',
            integration: 'mediatailor'
        }
    ]
}
```

Optionally, you can pass parameters regarding e.g. session data and device type by using the `adsParams` property, as described in the [MediaTailor documentation](https://docs.aws.amazon.com/mediatailor/latest/ug/ad-reporting-client-side.html#ad-reporting-client-side-enabling).

```js
player.source = {
  sources: [
    {
      src: '...',
      integration: 'mediatailor',
      adsParams: {
        param1: 'value1', // key is not case sensitive
        param2: 'value2', // Values can contain spaces. For example, 'value 2' is an allowed value.
      },
    },
  ],
};
```

## Limitations

The scope of the MediaTailor integration for now is limited to sending the tracking beacons. This encapsulates only the events that can be sent with the default implementation of THEOplayer. For example skipping an ad is not yet supported so the events that correspond to skipping an ad will never occur.

Seeking is only disabled during an ad, no logic is in place for playing an ad if the user *seeked* past it.

---

# Custom Server Side Ad Insertion on Web

THEOplayer provides a way to integrate with third-party advertisement providers, and have them report their ads and ad-related events through the THEOplayer APIs.

## Integration ID

To make use of the custom server side ad insertion, first you need an integration ID which will identify the provided sources and ads to the specific ad provider.

## ServerSideAdIntegrationFactory

You would also need to register a [`ServerSideAdIntegrationFactory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/ServerSideAdIntegrationFactory) through [`player.ads.registerServerSideIntegration()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Ads#registerServerSideIntegration). The factory receives a [`ServerSideAdIntegrationController`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ServerSideAdIntegrationController), which can be used to create the THEOplayer `AdBreak`/`Ad` objects using the `AdBreakInit`/`AdInit` data. Additionally, it can be used to keep the player's state up-to-date such as when an ad begins or ends.

The factory must return an implementation of the [`ServerSideAdIntegrationHandler`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ServerSideAdIntegrationHandler) interface. The handler provides a few optional callbacks which allow you to set up and clear the integration as needed.

A concrete implementation can be found [in the Yospace Connector](https://github.com/THEOplayer/web-connectors/blob/main/yospace/src/integration/YospaceManager.ts).

Meanwhile, an empty implementation would look like below. Details to follow.

```js
player.ads.registerServerSideIntegration('integrationID', (controller) => {
  return {
    async setSource(source) {
      return source;
    },
    skipAd(ad) {
      controller.skipAd(ad);
    },
    async resetSource() {
      // Clean up any source-specific resources.
    },
    async destroy() {
      // Clean up any remaining resources.
    },
  };
});
```

### Setting a source

When a new source is loaded into the player the `setSource(source)` callback is triggered. It allows the integration to transform the source description, e.g. by calling an external service to replace the content URL (`TypedSource.src`), or by adding a fixed pre-roll linear ad to the list of ads (`SourceDescription.ads`).

### Skipping an ad

When an ad is requested to be skipped, `skipAd(ad)` is called. At this point the integration should call the controller's own `skipAd()` method.

### Resetting a source

Before a new source is loaded into the player, or before the player is destroyed, `resetSource()` is triggered. This allows the integration to clean up any source-specific resources, such as scheduled ads or pending HTTP requests.

### Destroying the player

When the player is destroyed, `destroy()` is called. This allows the integration to clean up any resources, such as UI elements or event listeners.

### Creating Ad objects

When the advertisement provider reports an ad, an `AdBreak` and an `Ad` object should be created using the controller's `createAdBreak(init)` and `createAd(init, adBreak)` methods respectively. For example, for a pre-roll `AdBreak` containing 2 advertisements it would be:

```js
const adBreak = controller.createAdBreak({ timeOffset: 0 });

const firstAd = controller.createAd(
  {
    type: 'linear',
    skipOffset: 5,
    id: 'first_ad_id',
    duration: 10,
    clickThrough: firstAdClickThroughUrl,
    resourceURI: firstAdResourceUrl,
  },
  adBreak
);

const secondAd = controller.createAd(
  {
    type: 'linear',
    skipOffset: 5,
    id: 'second_ad_id',
    duration: 10,
    clickThrough: secondAdClickThroughUrl,
    resourceURI: secondAdResourceUrl,
  },
  adBreak
);
```

### Playing an ad

When an ad begins playback, the integration must inform the player by calling `controller.beginAd(ad)`, this will trigger the relevant ad break and ad events.

Additionally, during the playback of the ad, calling `controller.updateAdProgress(ad, progress)` is needed to keep the player in sync with the progress.

Finally, when the playback of the ad is completed, `controller.endAd(ad)` should be called to notify about it.

## Configuring the source

To hold the configuration parameters specific to your integration, set an [`ssai`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TypedSource#ssai) configuration on a `TypedSource`, whose `integration` property equals your integration ID. The integration can then read this configuration in its `setSource()` handler.

```js
player.source = {
  sources: {
    src: 'https://example.com/stream.m3u8',
    type: 'application/x-mpegurl',
    ssai: {
      integration: 'integrationID',
      // Any other properties needed by your integration.
    },
  },
};
```

---

# Analytics on Web

Video analytics offer all sorts of insights, ranging from the behavior of your viewers, to the performance of your video players.

There are different approaches to collect these insights.

* You can use a commercial video analytics vendor (e.g. Conviva, Mux, Wicket Labs, Youbora, ...).
* You can implement a custom analytics service that you created.
* You can leverage back-end and CDN logs.

Insights are deducted from metrics. Metrics are calculated from raw video data. For example,

1. INSIGHT: "the videos on my website start faster than the industry average (e.g. 4.71s)"
2. METRIC: "because the average video startup time was 1.7s on my website last month"
3. DATA: "that I calculated by measuring the video startup time of 1 million unique video sessions on my website"

The online video streaming industry often talks about Quality of Service (QoS) and Quality of Experience (QoE). When talking about metrics, you'll often hear terms like Startup Time, Buffer Rate, Error Rate, Seek Time, Exit Before Video Start. When talking about raw data, you might hear terms like heartbeat (or ping) events, buffer events, play events, seek events and error events.

## Analytics and video players

As an application developer, you want your video player to expose an API that allows you to track video events and query video states. With this API, a developer can implement an integration with a commercial analytics service, or implement a connection with their custom analytics service.

With a video player, you want to be able to access the raw video data. A video player typically doesn't calculate metrics or insights, because it doesn't have access to historical data.

As an app developer,

1. you want to track raw video data with the assistance of your video player API,
2. do some (optional) processing at runtime,
3. and forward the (processed) data to a remote analytics service.

Then, someone on the back-end, 4. would manage & manipulate this data on this remote analytics service, 5. to convert this raw data into metrics, and the metrics into insights.

## Integrations

THEOplayer *should* be compatible with any industry-standard commercial or custom analytics service. The THEOplayer API gives application developers access to a vast number of video events.

As an app developer, you have the option to leverage one of our existing integrations with commercial analytics services, or the option to create a custom integration.

The following commercial video analytics integrations are documented. These articles explain how to leverage an out-of-the-box integration, or how to implement a connector, or how to achieve a custom implementation with a specific vendor.

* [Moat](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/moat.md)
* [Mux](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/mux.md)
* [Youbora](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/youbora.md)
* [Agama](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/agama.md)
* [Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/conviva.md)
* [Adobe Analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/adobe-analytics.md)
* [MediaMelon SmartSight](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/mediamelon-smartsight.md)
* [Wicket Labs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/wicket-labs.md)
* [Google Analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/custom-analytics-integration.md#integrating-google-analytics)
* [Tealium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/tealium.md)
* [Segment](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/segment.md)
* [AdScript](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/adscript.md)
* [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/comscore.md)
* [Gemius](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/gemius.md)
* [Nielsen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/nielsen.md)

A connector is an open-source integration that is listed on our GitHub at <https://github.com/THEOplayer>. There might be connectors on our GitHub that are missing from the list above.

Alternatively, if you are not able to locate documentation on a specific vendor, then reach out to this vendor, because they might be the maintainer of an integration related to THEOplayer.

## Creating a custom analytics integration

Head over to [Custom Analytics Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/custom-analytics-integration.md) if you want to learn more about creating your own analytics integration using the THEOplayer API.

## THEOplayer Analytics Dashboard

If you've used the THEOplayer Developer Portal - for example to create a THEOplayer SDK -, then you might have noticed that there is an analytics dashboard at <https://portal.theoplayer.com>.

This analytics dashboard is located in the "Usage" tab of your Portal account. The dashboard should resemble the screenshot below.

![THEOplayer Portal Analytics Dashboard](/pr-932/assets/images/analytics-introduction-portal-dashboard-777c17a7b2bbf13b27a40bfdc3a4d1f9.png "THEOplayer Portal Analytics Dashboard")

This dashboard allows you to track your [impressions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-is-an-impression.md) across different periods of times across different SDKs.

We don't *really* consider this dashboard as a "video analytics service". The primary purpose of this dashboard is for you to monitor your impressions, as the impressions might be related to your THEOplayer pricing model. That being said, it is a useful dashboard, as it visualizes the consumption of your videos throughout time.

---

# Moat on Web

Moat is an analytics service maintained by Oracle. THEOplayer offers a pre-integration for this solution.

## Configuration

Configure the Moat partner code on the player configuration.

```js
new THEOplayer.Player(containerElement, {
  libraryLocation: 'https://cdn.theoplayer.com/dash/theoplayer/',
  analytics: [
    {
      integration: 'moat',
      partnerCode: '<PARTNER_CODE>',
    },
  ],
});
```

When you want to make use of Moat for tracking advertisements, you should make use of the [`IMAAdDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/IMAAdDescription).

---

# Mux on Web

[Mux /data](https://mux.com/data/) is a video analytics service. Mux is currently the maintainer of the Mux-THEOplayer integration. Their documentation describes how to connect Mux to THEOplayer for each of the THEOplayer SDKs.

## Connecting Mux to THEOplayer

Mux is currently the maintainer of the Mux-THEOplayer integration for Web. Their documentation for the THEOplayer Web SDK is located at <https://docs.mux.com/guides/data/monitor-theoplayer-web>.

If you choose to [build a custom integration](https://docs.mux.com/guides/data/build-a-custom-integration), the following article from Mux describes how you can achieve this:

* JavaScript: <https://docs.mux.com/guides/data/custom-javascript-integration>

---

# Youbora (NPAW Plugin) on Web

Youbora adapter (NPAW plugin) for THEOplayer is maintained by the NPAW team and regularly kept up to date to make sure it is compatible with the latest THEOplayer version.

In order to access the links on this guide, you may need to login with your NPAW developer account.

Before you get started, for general information on NPAW plugin, please refer to [this guide](https://documentation.npaw.com/integration-docs/docs/first-steps).

## Connecting Youbora to THEOplayer

For general information on NPAW plugin for Web and how to set it up, please refer to [this guide](https://documentation.npaw.com/integration-docs/docs/js-integration-guide).

For integration with THEOplayer Web SDK, please refer to their integration guide [here](https://documentation.npaw.com/integration-docs/docs/theoplayer-js).

## Related articles

* [Customize UI during ad playback](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/customize-ui-during-ad-playback.md)
* [Why does fullscreen not behave as expected on iOS browsers?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-does-fullscreen-not-behave-as-expected-on-ios.md)
* [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/set-up-vast-and-vmap.md)

---

# Agama on Web

Agama is an analytics solution maintained by [Agama Technologies](https://www.agama.tv/). THEOplayer offers a pre-integration for this service.

## Prerequisites

Agama requires you to load the Agama library and configure it through JavaScript. Agama needs to be configured through the player configuration and through the source configuration. The following section describes how this can be done.

## Configuration

The player configuration should include the [AgamaPlayerConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AgamaPlayerConfiguration) object.

```js
var player = new THEOplayer.Player(element, {
  libraryLocation: '/path/to/your-theoplayer-folder/',
  analytics: [
    {
      integration: 'agama',
      config: 'emp_service=http://127.0.0.1:8191/report;report_interval=60;id_report_interval=240;operator_id=fooSoo',
    },
  ],
});
```

Once a player is configured, an Agama EMP client instance is created.

The player's source configuration should include the [AgamaSourceConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AgamaSourceConfiguration) object.

```js
player.source = {
    [...]
    analytics : [{
        integration : 'agama',
        asset : 'Asset Name',
        streamType : 'vod'
    }]
};
```

Once the player's source is set, a dynamic streaming session is started, and Agama EMP is ready to monitor the usage and quality of the video.

## Related resources

* [Custom Analytics Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/custom-analytics-integration.md)

---

# Conviva on Web

Conviva is an analytics service. THEOplayer offers a connector which can be initialized depending upon the customer requirements for measuring all the solutions offered by Conviva (Video Analytics & Ads Analytics).

The Conviva connector has full support for Video and Ad Analytics offered by Conviva. It is built using all public APIs of THEOplayer and Conviva, so it can be maintained and managed across teams, and any new updates or changes can easily be modified and customized as per customer requirements. (There is no dependency on the THEOplayer or Conviva library version.)

## Usage

You need to set up [THEOplayer Conviva Connector for Web](https://github.com/THEOplayer/web-connectors/tree/main/conviva). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/conviva) section to learn all about how to integrate and use the Conviva connector on Web SDK.

If you have a Yospace SSAI stream and want to report ad related events to Conviva as well, the connector documentation also describes how to [combine it with the Yospace connector](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/conviva/getting-started.md#usage-with-yospace-connector).

## Resources

* Demo page: [Conviva Analytics Test Page](https://cdn.theoplayer.com/conviva/conviva_test.html)
* [Conviva SDK Documentation](https://cdn.theoplayer.com/conviva/Conviva_Documentation_4.0.14/index.html)
* More Information about [Conviva Video Experience](https://www.conviva.com/experience-insights/)
* More Information about [Conviva Ad Insights](https://www.conviva.com/ad-insights/)

---

# Custom Analytics Integration on Web

Video analytics provide tremendous insights into your user's QoE, bring extra business intelligence and enhance decision-making. There are a wide selection of analytics systems in the current landscape (e.g. Google Analytics, Conviva, ...), often with their own focus, expertise and value.

What most video analytics systems have in common is that their insights (partly) originate from video events:

* `play` event: a user clicks the play button, or resumes playback after a pause
* `fullscreen` event: a user goes fullscreen on their device
* `quality` change event: the video quality switches from a lower resolution to a higher one
* `waiting` event: the video is stalled and unable to continue playback for some time
* ...

To access these video events, and forward them to a video analytics system, an application developer must hook into the video player API.

This guide explains the role of the THEOplayer API. Additionally, it explains how to do a custom integration with an analytics system, with Google Analytics as a sample case. This guide should be useful when THEOplayer doesn't have an existing sample integration with a specific (commercial) video analytics service, or when you want to fully control the data flow.

Keep in mind that Google Analytics is not the only analytics system out there. The APIs and concepts that we'll discuss are relevant for all analytics systems. For example, you can easily swap out the Google Analytics example with something like [Nielsen](https://www.nielsen.com/solutions/audience-measurement/) or [Youbora](https://npaw.com/) (NPAW), or even your own custom analytics back-end.

## Prerequisites

There are two prerequisites in order to continue with this guide:

1. You have a THEOplayer license. You can grab a license at <https://portal.theoplayer.com>.
2. You have some basic knowledge on how to use THEOplayer, and can navigate comfortably through [the API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web) to find relevant events.

Refer to our [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md) before advancing to the code samples.

## API

You can access the video data through the THEOplayer API. Through the API, you can subscribe to events, and attach a callback. For example, when the `ended` event is triggered (meaning: someone completely watched the video), your callback could be that when this happens, you do a request to a remote video analytics service.

Events are organized across interfaces and subinterfaces, as illustrated by the image below. For example, the player contains general video player events like `play`, `pause` and `ended`. The ads interface contains events related to advertisements, like `adbreakbegin` and `adend`.

![THEOplayer API Interfaces and Events](/pr-932/assets/images/analytics-events-185d6ab52b556af08d8300b545ae5876.png "THEOplayer API Interfaces and Events")

When creating a custom analytics implementation, you must familiarize yourself with the relevant interfaces and events. Below is an (incomplete) list of some common interfaces and their event maps.

* [Player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap): general video events, like a play, a pause, and so on.
* [Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap): to detect when an ad starts and stops.
* [AudioTrackList](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap): to detect when a new audio track is added, or when another audio track becomes active.
* [VideoTrack](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrackEventMap): to detect when another video quality becomes active.
* [TextTrackList](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap): comparable to AudioTrackList, but for subtitles, closed captions and metadata (e.g. id3, emsg, EventStream, EXT-X-DATERANGE).
* [Cast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VendorCastEventMap): to detect events related to Chromecast and AirPlay.
* [Network](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/network/introduction.md): to intercept HTTP(S) requests and responses. You should only use this API when you can't use [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers) to accomplish the same.

Note that maintaining the above list manually is unfortunately a no-go because our interfaces evolve. This means that you should research your events through our [API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web).

When doing a custom analytics integration, you should also check our [Metrics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Metrics) API, and our articles on [error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/error/introduction.md).

### Video analytics metrics and events

Let's discuss some popular metrics, and how you could track them with video player events.

Plays (or Impressions). This metric represents the amount of plays. You can calculate this event by identifying the first `playing` event after every `sourcechange` event.

Video Startup Time (or Time-to-First-Frame or Join Latency). This metric represents the time it takes your video to start. You can calculate this event by calculating the difference between the timestamps of the first `playing` and the first `play` event after every `sourcechange` event.

Seek Time (or Seek Latency). This metric represents the time it takes for your video to resume when you scrub to another position. You can calculate this event by calculating the difference between the timestamps of the `seeking` and the `seeked` event.

Watch Time. This metric represents how much time is spent watching content by your viewers. You calculate this value by tracking the `playing` event, and halting it when the `waiting`, `pause`, `ended` or `error` event occurs.

Rebuffer Ratio (or Stalls). This metric represents how often the viewer is watching the "spinner icon" versus the actual video. This metric is closely related to the Watch Time. You can calculate this event by tracking the `waiting` event, which is triggered when the video starts to stall, and the `playing` event.

Average Bitrate. This metric represents the average video quality that your viewers are watching. You can calculate this metric by tracking the `activequalitychanged` event of the active video track.

Average % Complete (or Watched Ratio). This metric represents the relative completion rate of your videos. This metric is related to the Watch Time, and related in a similar fashion. You could also use the player's `duration` to determine the length of the asset.

Exit Before Video Start. This metric represents how often your viewers aren't able to start the video, even though they had the intent to watch it. You can calculate this metric by tracking the first `play` event, and it never getting to the `playing` event.

Video Playback Failure. This metric represents how often your viewers have a problem with playback once a video starts. You can calculate this metric by tracking the `error` event after the first `playing` event.

Note that these proposed calculations are only loosely formulated to help you understand the relationship between video metrics and a video player API.

When talking about metrics, you often apply dimensions or filters to a metric. For example, when talking about the "Plays" metric (see above), the base metric would apply to all logs throughout all time. When analyzing your data, you might want to apply a filter (or dimension), such time (to consider all "Plays" for a specific period of time), asset (to research a specific asset), user (to check a specific user's activity), and so on. It is up to you (or your commercial analytics service) to associate certain dimensions with a raw video player event.

### Session management

It's important to note that THEOplayer doesn't associate a user ID or session ID with an event. (This is pretty normal, because THEOplayer is a client-side video player library. It's not aware of your "back-end" "CMS", "users" or "sessions".)

When you are implementing an analytics service, you usually want to associate a session or user with an event when forwarding the event to your remote analytics database. As an app developer, it is your responsibility to do this association.

## Integrating Google Analytics

This subsection shows you how you could connect the THEOplayer Web SDK with Google Analytics.

Google Analytics (GA) requires you to [load in the GA library](https://developers.google.com/analytics/devguides/collection/analyticsjs/) and configure it through JavaScript. This script also sets up a default tracker for your tracking ID UA-XXXXX-Y.

```html
<head>
  ... (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new
  Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-XXXXX-Y', 'auto'); ga('send', 'pageview'); ...
</head>
```

Then, you must use the THEOplayer API to "add an event listener". In an event listener, you specify which events you want to track, and what the reaction should be when such an event should be detected.

For example, with Google Analytics, we could subscribe to a list of events, and call the `ga('send')` function from the Google Analytics API to forward this event to your Google Analytics database.

```js
player.addEventListener(['durationchange', 'stalled', 'ended', 'seeking', 'seeked', 'waiting', 'playing', 'pause', 'volumechange'], function (event) {
  ga('send', {
    hitType: 'event',
    eventCategory: 'video',
    eventAction: event.type,
    eventLabel: player.src,
    eventValue: Math.floor(player.currentTime),
  });
});
```

For more advanced integrations, Google Analytics also allows you to [create multiple named trackers](https://developers.google.com/analytics/devguides/collection/analyticsjs/creating-trackers).

Of course, you control the code, so you could send custom "made up" events. A useful example would a `firstplay` event, which would map to the "first play" event for a session.

```js
var firstplay = true;
player.addEventListener('play', function (event) {
  if (firstplay) {
    ga('send', {
      hitType: 'event',
      eventCategory: 'video',
      eventAction: 'firstplay',
      eventLabel: player.src,
      eventValue: Math.floor(player.currentTime),
    });
    firstplay = false;
  }
  ga('send', {
    hitType: 'event',
    eventCategory: 'video',
    eventAction: event.type,
    eventLabel: player.src,
    eventValue: Math.floor(player.currentTime),
  });
});
```

(Keep in mind that you should reset `firstplay` to `true` when you configure another video.)

Another useful "fake" event that you could track is the "video startup time", as discussed at [How to measure time-to-first-frame?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/track-first-playing-event.md).

Remember that not every event is accessible through the `Player` interface which is accessible through the `player` property. For example, if you want to notify GA of a video quality change event, you have to subscribe to the correct video track, and leverage the `VideoTrackList` interface and the `VideoTrack` interface.

```js
player.videoTracks.addEventListener('addtrack', function (e0) {
  e0.track.addEventListener('activequalitychanged', function (e1) {
    ga('send', {
      hitType: 'event',
      eventCategory: 'video',
      eventAction: e1.type,
      eventLabel: player.src,
      eventValue: Math.floor(player.currentTime),
    });
  });
});
```

## Conclusion

A custom analytics integration gives you full control over your code, and the data you want to submit to your analytics system. This data is exposed through the THEOplayer API, and allows you to subscribe to events such as the start of an ad, or a direction change event in 360/VR playback.

Extra resources:

1. [THEOplayer API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web)
2. [THEOplayer Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md)

---

# Adobe Analytics on Web

[Adobe Streaming Media Collection Add-on](https://experienceleague.adobe.com/en/docs/media-analytics/using/media-overview) is a video analytics service, and is part of [Adobe Experience Cloud](https://business.adobe.com/products/analytics/adobe-analytics.html).

This product was formerly known as "Adobe Heartbeat".

Adobe Streaming Media Collection Add-on or older iterations of this product can be implemented on top of THEOplayer as a custom analytics integration.

Refer to the article on [building a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/custom-analytics-integration.md) for more information on how to build an integration on top of THEOplayer.

## Connecting Adobe Analytics to THEOplayer

You can use the [documentation of the Media Analytics SDK](https://experienceleague.adobe.com/en/docs/media-analytics/using/implementation/analytics-only/media-sdk/web-implementation), and you can [download the Media SDKs](https://experienceleague.adobe.com/en/docs/media-analytics/using/getting-started/download-sdks).

Alternatively, you can use the [RESTful Media Collection API](https://experienceleague.adobe.com/en/docs/media-analytics/using/implementation/analytics-only/streaming-media-apis/mc-api-overview).

For more information about how to use Adobe Analytics on other platforms, please refer to the [Adobe Streaming Media Collection Add-on overview](https://experienceleague.adobe.com/en/docs/media-analytics/using/media-overview).

---

# MediaMelon SmartSight on Web

MediaMelon SmartSight is an analytics service maintained by MediaMelon. The library is maintained by the MediaMelon team.

## Prerequisites

1. A valid THEOplayer license.
2. A MediaMelon SDK.
3. A MediaMelon Customer ID (**Note:** If you do not know your Customer ID contact MediaMelon at <support@mediamelon.com>.

## Connecting MediaMelon to THEOplayer

For the most up to date information on how to integrate MediaMelon SmartSight with THEOplayer Web SDK, please refer to their integration guide [here](https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/web).

**Step 1: Add THEOplayer and MediaMelon SDK** Include the following scripts in the web page (before `THEOplayer.js` is loaded):

```html
<script type="text/javascript" src="https://PATH_TO_SMARTSIGHT_SDK/mmsmartstreaming_theoplayer.min.js"></script>
<script type="text/javascript" src="THEOplayer.js"></script>
```

**Step 2: Register and Initialize MediaMelon SDK** Note: `<customer_id>` is your MediaMelon-assigned Customer ID. If you do not know your Customer ID, contact MediaMelon at <support@mediamelon.com>.

After the player instance has been created, create a new plugin object, register, report player Info and then initialize the plugin as shown below:

```js
var theoPlayer = new THEOplayer.Player(element, {
  libraryLocation: 'your_library_location',
  license: 'your_license_here',
});

var mmVideoAssetInfo = {
  assetName: 'ASSET_NAME',
  assetId: 'ASSET_ID',
  videoId: 'VIDEO_ID',
  contentType: 'CONTENT_TYPE',
  genre: 'GENRE',
  drmProtection: 'DRM_PROTECTION',
  episodeNumber: 'EPISODE_NUMBER',
  season: 'SEASON',
  seriesTitle: 'SERIES_TITLE',
  videoType: 'VIDEO_TYPE',
  customTags: {
    key1: 'VALUE_STRING1',
    key2: 'VALUE_STRING2',
  },
};

var theoPlugin = new mmTheoJSAdapter();
if (theoPlugin.getRegistrationStatus() === false) {
  theoPlugin.registerMMSmartStreaming('PLAYER_NAME', 'CUSTOMER_ID', 'SUBSCRIBER_ID', 'DOMAIN_NAME', 'SUBSCRIBER_TYPE', 'SUBSCRIBER_TAG');
  theoPlugin.reportPlayerInfo('PLAYER_BRAND', 'PLAYER_MODEL', 'PLAYER_VERSION');
}

theoPlugin.reportAppInfo('APP_NAME', 'APP_VERSION');
theoPlugin.setDeviceInfo('DEVICE_MARKETING_NAME');
theoPlugin.reportVideoQuality('VIDEO_QUALITY');
theoPlugin.reportDeviceId('DEVICE_ID');

var isLive = false; //Set this to true for a live stream or false for a VOD stream
// If isLive is not set here, it will be handled internally by the SDK.
theoPlugin.initialize(theoPlayer, 'STREAM_URL', mmVideoAssetInfo, isLive);

// Call this Error API to report an App Error.
theoPlugin.reportAppError('ERROR_MESSAGE', 'ERROR_CODE');
```

You can find an explanation of the parameters on the snippet above [here](https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/web/theoplayer-web-v2-1#cl-step-4-providing-content-metadata-and-custom-tags).

**Step 3: (Optional) Providing custom metadata and tags**

You can also provide custom metadata and tags as shown below in HTML/JS while setting source information. Please use the `mmVideoAssetInfo` structure to provide this information.

```javascript
player.source = {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
      type: 'application/x-mpegurl',
    },
  ],
  mmVideoAssetInfo: {
    assetName: 'Elephants Dream',
    assetId: 'ASSETID_STRING',
    videoId: 'VIDEOID_STRING',
    customTags: {
      key1: 'VALUE_STRING1',
      key2: 'VALUE_STRING2',
      key3: 'VALUE_STRING3',
    },
  },
};
```

**Step 4: (Optional) Disable Manifest Fetch**

If your workflow restricts the manifest to be accessible from both player and SDK simultaneously, then, you can disable the fetch of manifest via the `disableManifestsFetch` API:

```javascript
var player = new THEOplayer.Player(element, {
  libraryLocation: 'path_to_your_library/',
  license: 'your_license_here',
});

var theoPlugin = new mmTheoJSAdapter();
if (theoPlugin.getRegistrationStatus() === false) {
  theoPlugin.registerMMSmartStreaming('PLAYER_NAME', 'CUSTOMER_ID', 'SUBSCRIBER_ID', 'DOMAIN_NAME', 'SUBSCRIBER_TYPE', 'SUBSCRIBER_TAG');
  theoPlugin.reportPlayerInfo('PLAYER_BRAND', 'PLAYER_MODEL', 'PLAYER_VERSION');
  theoPlugin.disableManifestsFetch(true);
}

theoPlugin.initialize(theoPlayer);
```

If you now host a page with the logic described above implemented correctly, THEOplayer will start sending beacons to your MediaMelon dashboard and you should be seeing data coming in to the MediaMelon dashboard in no time.

---

# Wicket Labs on Web

[Wicket Labs](https://www.wicketlabs.com/) is an audience insights platform for video, and offers products like the "[Wicket Scoreboard](https://www.wicketlabs.com/wicket-scorecard/)".

To generate these insights, a video player emits playback events to a third-party database service (e.g. Firebase). Wicket Labs provides [guidelines](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/) on how to format these playback events. Wicket Labs then pulls the data from the selected third-party database service, and integrates it into their platform.

## Connecting Wicket Labs with THEOplayer

An integration with Wicket Labs can be integrated on top of THEOplayer.

1. As a customer of Wicket Labs, you need to verify that Wicket Labs can ingest data from your selected database solution (e.g. Firebase). *(It should be noted that Wicket Labs does not provide its own database service to store playback events. Instead, Wicket Labs plugs into your database service.)*
2. As a customer of Wicket Labs and THEOplayer, you need to emit the playback events ([as defined per Wicket Labs](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/)) to your database service. In other words, you need to hook into certain events emitted by THEOplayer, reformat them, and re-emit them to your database service.

* To facilitate the implementation of Wicket Labs \[related to THEOplayer], Wicket Labs and THEOplayer collaborate on publicly available code samples. These code samples are published as Git repositories on <https://github.com/THEOplayer>.
* Developers are free to do their custom integration of Wicket Labs and THEOplayer, or may modify the publicly available code samples.
  * Wicket Labs' article on [How to Setup Firebase for OTT Video Services](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/) is a great starting point if you're interested in customizing.

- Our article on [Custom Analytics Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/custom-analytics-integration.md) may help developers out.

THEOplayer and Wicket Labs host a GitHub repository at <https://github.com/THEOplayer/samples-wicket-labs-html5-sdk>. This repository provides a sample implementation for the THEOplayer Web SDK with Firebase as the database service.

This repository may also be useful if you're using another database service, because the repository demonstrates the correct order of hooking into the playback events related to Wicket Labs, and how to format them. In other words: if you're using another database service, you just need to emit the events to a different source.

## Related links

* github.com/THEOplayer: <https://github.com/THEOplayer/samples-wicket-labs-html5-sdk>

- wicketlabs.com: [How to Setup Firebase for OTT Video Services](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/)

---

# Tealium on Web

Tealium is a [tag management system](https://tealium.com/resource/fundamentals/what-is-tag-management/) and offers [integrations](https://tealium.com/integrations/) with [Google Analytics](https://tealium.com/integrations/google-analytics/), [Adobe Analytics](https://tealium.com/integrations/adobe-analytics/), and others.

Tealium can be implemented on top of THEOplayer as a custom analytics integration.

Refer to the article on [building a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/custom-analytics-integration.md) for more information on how to build an integration on top of THEOplayer.

## Connecting Tealium to THEOplayer

The Tealium documentation includes articles that describe:

* [How to install Tealium for JavaScript](https://docs.tealium.com/platforms/javascript/install/).
* [How to implement tracking](https://docs.tealium.com/platforms/javascript/track/), but also mentions that "video tracking often requires a custom solution coding to the specifications of the video platform API".
* [Basic video tracking](https://docs.tealium.com/platforms/getting-started-web/data-layer/definitions/basic-video-tracking/) on the data layer.
* [An introduction to the Data Layer](https://docs.tealium.com/platforms/getting-started-web/data-layer/an-introduction-to-the-data-layer/).

For other platforms, refer to the documentation at <https://docs.tealium.com/platforms/>.

---

# Segment on Web

Segment is a [Customer Data Platform](https://segment.com/docs/guides/), and offers [integrations](https://segment.com/docs/connections/destinations/catalog/index-all/) with [Google Analytics](https://segment.com/docs/connections/destinations/catalog/google-analytics/), [Adobe Analytics](https://segment.com/docs/connections/destinations/catalog/adobe-analytics/), [Youbora](https://segment.com/docs/connections/destinations/catalog/youbora/), and others.

Segment sets up "[Connections](https://segment.com/docs/connections/)" between "[Sources](https://segment.com/docs/connections/sources/)" and "[Destinations](https://segment.com/docs/connections/destinations/)".

* Sources send messages into Segment (and other tools). They have JavaScript source, an Android source, and so on.
* Destinations (like Google Analytics, Adobe Analytics, Youbora) receive messages from Segment.

Segment can be implemented on top of THEOplayer as a custom analytics integration.

Refer to the article on [building a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/custom-analytics-integration.md) for more information on how to build an integration on top of THEOplayer.

## Connecting Segment to THEOplayer

You'll (most likely) use the "[Analytics.js](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/)" source to get access to the Segment API.

Then, for each of your destinations, you want to figure out whether you can use the "Video Spec", or whether you need to do something specific for some destinations (e.g. [Youbora](https://segment.com/docs/connections/destinations/catalog/youbora/)).

Segment describes a "Video Spec" at <https://segment.com/docs/connections/spec/video/>, but this article also mentions that "not all destinations support video tracking and you should always check with the individual destination documentation to confirm".

For other platforms, refer to the documentation at <https://segment.com/docs/>.

---

# AdScript on Web

AdScript is an ad and content measurement service maintained by [Nielsen](https://www.nielsen.com/). THEOplayer offers a connector which reports playback and ad events to AdScript.

## Usage

You need to set up [THEOplayer AdScript Connector for Web](https://github.com/THEOplayer/web-connectors/tree/main/adscript). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/adscript) section to learn all about how to integrate and use the AdScript connector on Web SDK.

## Resources

* [AdScript website](https://www.nielsen.com/solutions/ad-intel/)

---

# Comscore on Web

Comscore is an analytics service which provides audience measurement and content ratings. THEOplayer offers a connector which reports playback and ad events to the Comscore Streaming Tag.

## Usage

You need to set up [THEOplayer Comscore Connector for Web](https://github.com/THEOplayer/web-connectors/tree/main/comscore). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/comscore) section to learn all about how to integrate and use the Comscore connector on Web SDK.

## Resources

* [Comscore website](https://www.comscore.com/)

---

# Gemius on Web

Gemius is an analytics service maintained by [Gemius](https://www.gemius.com/). THEOplayer offers a connector which reports playback and ad events to the Gemius Player library.

## Usage

You need to set up [THEOplayer Gemius Connector for Web](https://github.com/THEOplayer/web-connectors/tree/main/gemius). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/gemius) section to learn all about how to integrate and use the Gemius connector on Web SDK.

## Resources

* [Gemius website](https://www.gemius.com/)

---

# Nielsen on Web

Nielsen is an analytics service which provides audience measurement. THEOplayer offers a connector which reports playback and ad events to the Nielsen SDK.

## Usage

You need to set up [THEOplayer Nielsen Connector for Web](https://github.com/THEOplayer/web-connectors/tree/main/nielsen). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/nielsen) section to learn all about how to integrate and use the Nielsen connector on Web SDK.

## Resources

* [Nielsen website](https://www.nielsen.com/solutions/audience-measurement/)

---

# Chromecast on Web

In this section you will learn everything about how THEOplayer works with Chromecast.

## API

As a developer, you might need to use the THEOplayer Chromecast API to build a custom Chromecast UI and UX, or to dispatch an event to an analytics service, or for workflow purposes.

For more information, see the API reference of [`Chromecast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Chromecast), a sub-interface of [`Cast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Cast) which inherits from [`VendorCast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VendorCast).

Use the API as demonstrated below:

```javascript
// const player = new THEOplayer.Player(...)
const chromecastState = player.cast.chromecast.state;
const isCasting = player.cast.chromecast.casting; // true or false
// ...
// if (want to start Chromecast)
player.cast.chromecast.start();
// ...
// if (want to stop Chromecast)
player.cast.chromecast.stop();
// ...
if (chromecastState != 'unavailable') {
  // Chromecast is possible
  player.cast.chromecast.addEventListener('statechange', function (event) {
    switch (event.state) {
      case 'connecting':
        // show Chromecast trying-to-connect icon
        break;
      case 'available':
        // show Chromecast available icon
        break;
      case 'connected':
        // show Chromecast connected icon
        break;
      case 'unavailable':
        // hide Chromecast icon
        break;
    }
  });
}
```

## Sender Applications vs Receiver Applications

When a viewer is streaming through a Chromecast device, they are actually casting content from a sender application (e.g. an Android application) to a receiver application. A sender application informs a physical Chromecast device which receiver application it should load through an application ID.

![Casting approaches](/pr-932/assets/images/casting-approaches-45dc2983f20d11409d27d3248b57a6ef.png "Casting approaches")

By specifying the application ID, you implicitly connect it with a type of receiver application. The following three types of receiver applications are common:

| Type                                    | Maintainer             | Info                                                                                                                                                                                                                        | Benefits                                                                                                                                                                                                      | Disadvantages                                                                                                                       |
| --------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Default THEOplayer Receiver Application | THEOplayer             | This is the default receiver application THEOplayer SDKs will connect with. The app ID of this default THEOplayer receiver application is `8E80B9CE`.                                                                       | You (i.e. the developer) do not need to do anything extra on the Chromecast receiver application side. You don't need to create a Chromecast receiver, you don't need to register it at, ... - it just works. | You are limited w\.r.t. customizing the UI and integrating custom logic.                                                            |
| Custom THEOplayer Receiver Application  | Developer + THEOplayer | This is a custom receiver application you can build, and where you integrate the [THEOplayer Chromecast SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md). | You (i.e. the developer) can adjust the look and feel, and integrate custom logic.                                                                                                                            | You need to create a Chromecast receiver, register it, maintain it, ...                                                             |
| Customer Receiver Application           | Developer              | This is a custom receiver application you can build, but without using the THEOplayer Chromecast SDK.                                                                                                                       | The THEOplayer Chromecast Receiver SDK is not a dependency.                                                                                                                                                   | You are responsible for building and maintaining the receiver application, and its connection with the various sender applications. |

If you have implemented THEOplayer in your sender application, you can [enable Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/enable-chromecast-on-the-sender.md). Furthermore, you can also [specify the application ID](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/enable-chromecast-on-the-sender.md#custom-receiver-app) in your sender application.

## Whitelisting Receiver Applications

Streaming services and products often require you to whitelist domain names to allow playback. When viewers are casting content to a Chromecast receiver application, your Chromecast device will actually stream the content on a domain name. In other words: CORS and whitelisting/blacklisting policies do apply to Chromecast sessions. Ensure that you've whitelisted the domain name which hosts your Chromecast receiver application. (You can look up the domain name of your receiver application at <https://cast.google.com/publish/#/overview>.)

If you're using the Default THEOplayer Receiver Application you may whitelist `https://d3ojqkc95d8mrd.cloudfront.net/`.

## Related articles

* [Connecting from custom Sender applications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/connecting-from-custom-sender-applications.md)
* [Debugging](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/debugging.md)
* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/how-to-configure-to-a-different-stream.md)
* [Sending messages from/to Sender to/from Receiver](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/sending-messages-from-to-sender-to-from-receiver.md)
* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)
* [Enable Chromecast on the Sender](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/enable-chromecast-on-the-sender.md)

---

# Connecting from custom Sender applications on Web

In general, the following flow should be followed:

1. Set up Google Cast context with correct receiver application ID.
2. Connect to Chromecast device.
3. Set up Google Cast MediaInfo object with correct contentID and contentType.
4. Send Google Cast LoadRequest with a serialized THEOplayer SourceDescription object as a key in the customData of the LoadRequest. So something like `{sourceDescription: ${SourceDescription you want to cast}}`.

## Usage

The following web page should suffice:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Title</title>
    <script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
    <script>
      window['__onGCastApiAvailable'] = function (isAvailable) {
        if (isAvailable) {
          cast.framework.CastContext.getInstance().setOptions({
            receiverApplicationId: '$YOUR_APP_ID', // Adapt this
            autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED, // And this if you want to
          });
        }
      };
    </script>
    <script>
      function startCasting(sourceDescription) {
        var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
        var mediaInfo = new chrome.cast.media.MediaInfo(sourceDescription.sources[0].src, sourceDescription.sources[0].type);
        var request = new chrome.cast.media.LoadRequest(mediaInfo);
        request.customData = { sourceDescription: sourceDescription };
        castSession.loadMedia(request).then(
          function () {
            console.log('Load succeed');
          },
          function (errorCode) {
            console.log('Error code: ' + errorCode);
          }
        );
        var player = new cast.framework.RemotePlayer();
        var playerController = new cast.framework.RemotePlayerController(player);
        return playerController;
      }
    </script>
  </head>
  <body></body>
</html>
```

Load this in Google Chrome, connect to a Chromecast device, and then you can do the following:

```js
startCasting({
  sources: [
    {
      src: 'https://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/manifest(format=mpd-time-csf)',
      type: 'application/dash+xml',
      contentProtection: {
        widevine: {
          licenseAcquisitionURL: 'https://amssamples.keydelivery.mediaservices.windows.net/Widevine/?KID=1ab45440-532c-4399-94dc-5c5ad9584bac',
        },
      },
    },
  ],
});
```

This will start playback.

## Related articles

* [How can we track the first play(ing) event?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/track-first-playing-event.md)

* [How to start with a specific quality?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/start-with-specific-quality.md)

* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)

* [How to know whether a live stream is playing?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-know-when-livestream-is-playing.md)

* [Getting started on Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md)

---

# Debugging Chromecast on Web

This how-to guide describes how to debug a Chromecast Receiver application using the THEOplayer Web SDK.

## Step-by-step guide

1. Ensure that you are on the same network as your Chromecast device.
2. Publish a new device at <https://cast.google.com/u/1/publish/#/devices> by clicking "ADD NEW DEVICE". ![Chromecast debugging 1](/pr-932/assets/images/chromecast_debugging_1-0040e1d6eeca0a6b5501cef46a031989.png "Chromecast debugging 1")
3. Wait until the status is "Ready For Testing". ![Chromecast debugging 2](/pr-932/assets/images/chromecast_debugging_2-c399ddb9c096aab91c30293a8a9e9f50.png "Chromecast debugging 2")
4. Find out what the IP-address of your Chromecast device is. (Tip: Use the Google Home app to look this up.)
5. Go to chrome://inspect and add the IP-address (plus port 9222) of your Chromecast device.
6. Start your Chromecast session.
7. Go to chrome://inspect and wait until your Chromecast device appears in the list.
8. Press "inspect". ![Chromecast debugging 3](/pr-932/assets/images/chromecast_debugging_3-ef34a49f03eb6830f56bfdaf20a04fb5.png "Chromecast debugging 3")
9. You should now have access to the Chrome Developer Tools of your Chromecast Receiver application. If you are familiar with debugging through Chrome's Developer Tools, you can look into issues, try out new CSS styles and monitor network traffic. ![Chromecast debugging 4](/pr-932/assets/images/chromecast_debugging_4-17c946d842f3a40de725316bce17a9f7.png "Chromecast debugging 4")

## Related articles

* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)

* [Chromecast SDK Setup](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md)

* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/how-to-configure-to-a-different-stream.md)

---

# How to configure a different stream to Chromecast on Web

Some streaming setups require you to cast a different stream to a Chromecast Receiver device than the one playing on a Chromecast Receiver device. For example, if you're playing HLS + FairPlay DRM on your iOS application, you need to cast a different source with DASH + Widevine DRM to your Chromecast application, because Chromecast applications aren't able to support FairPlay.

You can achieve this use case with the ChromecastConnection API.

## ChromecastConnection API

The ChromecastConnection API allows you to implement callbacks related to Chromecast playback. To achieve the described use case you can use the `onStart` (i.e. the start of a Chromecast session) to set a new stream, and `onStop` (i.e. the end of a Chromecast session) to (re)set your previous stream.

You may also be interested in `onJoin` (i.e. joining an existing Chromecast session with a new device) or `onLeave` (i.e. leaving an existing Chromecast session on a device).

The snippet below has two [sources](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/SourceDescription):

1. `senderSource` is intended for playback on your sender device (i.e. your browser)
2. `chromecastSource` is intended for playback on your Chromecast application

The [`ChromecastConnectionCallback`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ChromecastConnectionCallback) interface is used to:

1. Set the `chromecastSource` when Chromecast playback starts through the `onStart` callback.
2. Revert to the `senderSource` when Chromecast playback stops through the `onStop` callback.

```js
var senderSource = {
  sources: {
    src: 'https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
    type: 'application/x-mpegurl',
  },
};
var chromecastSource = {
  sources: {
    src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
    type: 'application/x-mpegurl',
  },
};
player.source = senderSource;
player.cast.chromecast.connectionCallback = {
  onStart: function (source) {
    return chromecastSource;
  },
  onStop: function (source) {
    return senderSource;
  },
  onJoin: function (source) {
    return source;
  },
  onLeave: function (source) {
    return source;
  },
};
```

The `onJoin` and `onLeave` implementations in the above snippet adhere to the default behavior.

---

# Sending messages from/to Sender to/from Receiver on Web

This article will explain how to send data to an active receiver and how to respond on the receiver.

## Send data to the receiver

The Google Cast SDK has a global object that everyone can access. This global object is also being used by THEOplayer. The general idea is to retrieve the current active cast session and send a message on a specific namespace.

```js
// Retrieve the current cast session
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
// Send message on defined namespace channel
castSession.sendMessage('namespace', 'message');
```

Reference:

* <https://developers.google.com/cast/docs/reference/chrome/cast.framework.CastSession>
* <https://developers.google.com/cast/docs/reference/chrome/cast.framework.CastSession#sendMessage>

## Receive data from the receiver

The general idea is to retrieve the current active cast session and add an event listener on the specific namespace.

```js
// Retrieve the current cast session
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
// Add an event listener to the defined namespace channel
castSession.addMessageListener('namespace', (namespace, message) => {
  console.log(namespace, message);
});
```

Reference:

* <https://developers.google.com/cast/docs/reference/chrome/cast.framework.CastSession#addMessageListener>

## Receive data on the receiver

*This example is for receiver version 2.*

The general idea is to retrieve the receiver manager and add a message listener for the specific namespace. **This needs to be done before a THEOplayer instance is created. THEOplayer will call the start method of the receiverManager on initialization.**

```js
// Retrieve the cast receiver manager
var castReceiverManager = cast.receiver.CastReceiverManager.getInstance();
// Retrieve the message bus from the cast receiver manager
var messageBus = castReceiverManager.getCastMessageBus('namespace');
// Add message listener to the message bus
messageBus.onMessage = function (event) {
  console.log(event);
};
```

Reference:

* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus>
* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus#onMessage>
* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus.Event>

## Send data from the receiver

*This example is for receiver version 2.*

There are multiple possibilities to send data from the receiver:

1. When a message is received on the receiver, you can answer the sender

2. Broadcast to all connected senders

```js
// 1.
messageBus.onMessage = function (event) {
  messageBus.send(event.senderId, 'message');
};
// 2.
messageBus.broadcast('message');
```

Reference:

* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus#broadcast>
* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus#send>

## Related articles

* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)

* [Chromecast SDK Setup](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md)

* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/how-to-configure-to-a-different-stream.md)

* [Connecting from custom Sender applications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/connecting-from-custom-sender-applications.md)

---

# Pass subtitle selection on to Chromecast on Web

Currently, it is intended behavior that when you start casting the player to a Chromecast device the subtitle selection setting isn't carried over. A new player is generated with the `SourceConfiguration` of the sender, but not any adjustments.

You can work around the default behavior by adding event listeners to the player.

The code adds an event on textTracks `change`. Whenever the subtitles change, this event is called and stores the current active textTrack in `currentTextTrack` by iterating over the textTracks array and checking whether `.mode` is `showing`. Once a Chromecast session is created, the code will check if the ID of the textTracks in the new player corresponds with the ID of the stored currentTextTrack. If so, it will activate that textTrack.

## Solution

Here is how you pass the current active subtitle track to the Chromecast session:

```js
var currentTextTrack;

player.textTracks.addEventListener('change', function () {
  for (var t in player.textTracks) {
    if (player.textTracks[t].mode === 'showing') {
      currentTextTrack = player.textTracks[t];
    }
  }
});

player.cast.chromecast.addEventListener('statechange', (event) => {
  if (event.state === 'connected') {
    player.addEventListener('playing', function () {
      for (var tt in player.textTracks) {
        if (player.textTracks[tt].id === currentTextTrack.id) {
          player.textTracks[tt].mode = 'showing';
        }
      }
    });
  }
});
```

---

# Enable Chromecast on the Sender on Web

This article explains how to enable the Chromecast Sender capabilities. This article also documents how you can connect with a custom Chromecast Receiver application.

## Prerequisites

1. The Chromecast feature needs to be enabled for your THEOplayer SDK. (THEOplayer is built in a modular fashion, and this feature might be disabled for your SDK.)
2. You need to import the Chromecast Sender SDK.
3. Your Sender device needs to be on the same Wi-Fi network as your Chromecast Receiver device.

## Import Chromecast Sender SDK

To allow Chromecast playback you need to include Google's Chromecast Sender SDK, which is a JavaScript file. The JavaScript snippet below illustrates how you include this Sender SDK. You can read more about it at <https://developers.google.com/cast/docs/web_sender>.

```javascript
<script type="text/javascript" src="//www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
```

Once this SDK is imported, OptiView Player will automatically add the Chromecast casting capability to your player (if you've enabled the Chromecast feature for your OptiView Player SDK). OptiView Player will use its default Chromecast receiver application if you do not specify an `appID` value on the configuration.

## Connect with custom Chromecast Receiver application

The THEOplayer SDK on your Sender application connects with THEO Chromecast Receiver application by default, but you can connect it to a custom Chromecast Receiver application instead. The default Dolby OptiView Chromecast Receiver application has OptiView Player functionality, but uses Shaka for media playback. If you want to use Google's legacy Media Player Library (MPL) for playback, you will need to use either a custom application or connect to Dolby OptiView's MPL Receiver application, using the `appID` value of `44BAE7D1`. Note that the MPL receiver does not support HLS-CMAF streams.

If you have your own Receiver app, then you adjust the [PlayerConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/CastConfiguration) to connect with a specific `appID` as demonstrated below.

```javascript
let customChromecastReceiverAppID = '8E80B9CE';
let player = new THEOplayer.Player(element, {
  libraryLocation: '...',
  license: '...',
  cast: {
    chromecast: {
      appID: customChromecastReceiverAppID,
    },
  },
});
```

If you do not specify an `appID` value, the player will cast to the default OptiView Player Chromecast application. This is a Receiver application that has OptiView Player functionality integrated into it, but uses the Shaka player for media playback. If you require a Receiver application that uses Google's legacy Media Player Library (MPL), there is a Receiver application with OptiView Player functionality that uses MPL. Its `appID` is `44BAE7D1`. Note that the MPL receiver does not support HLS-CMAF streams.

---

# AirPlay on Web

[AirPlay](https://www.apple.com/airplay/) is a casting technology developed by Apple. AirPlay allows viewers to mirror their videos between AirPlay-enabled sender and receiver devices.

* iPhones, iPads and MacBooks are possible AirPlay-enabled sender devices.
* Apple TVs or AirPlay–enabled smart TVs are possible AirPlay-enabled receiver devices.

THEOplayer offers support for AirPlay on AirPlay-enabled devices through its Web SDK and iOS SDK.

## How to enable AirPlay

Ensure that an AirPlay-enabled receiver device is connected to your network, because you might not see an AirPlay icon otherwise. Additionally, note that AirPlay is only supported by Apple on a limited set of devices and browsers. For example, you cannot do AirPlay on a Chrome browser on a macOS device, even though it's an Apple device.

AirPlay is a THEOplayer feature. Ensure that the `airplay` feature is enabled when you build a THEOplayer SDK through the [THEOplayer Developer Platform](https://portal.theoplayer.com/), as demonstrated by the screenshot below. Alternatively, if you are using a THEOplayer SDK from npm, make sure that the package flavor you picked has the `airplay` feature in it.

![Enable Airplay](/pr-932/assets/images/portal-airplay-enabled-1f34336e6078b5eff14cdbfcd3695480.png)

If the `airplay` feature is enabled, the default THEOplayer UI should render the AirPlay icon in the control bar, as demonstrated by the screenshot below. Viewers can click this AirPlay icon and select an AirPlay receiver device to initiate (and stop) the AirPlay session.

![AirPlay demo](/pr-932/assets/images/airplay-demo-theoplayer-b38aaa6ad2b2495f333a4316151d5ac4.png)

If you have a custom ([chromeless](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md)) THEOplayer UI, you need to build your own AirPlay UI and UX. You can use the THEOplayer AirPlay API to help achieve this, as discussed in the next section.

## API

As a developer, you might need to use the THEOplayer AirPlay API to build a custom AirPlay UI and UX, or to dispatch an event to an analytics service, or for workflow purposes.

For more information, see the API reference of [`AirPlay`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AirPlay), a sub-interface of [`Cast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Cast) which inherits from [`VendorCast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VendorCast).

Use the API as demonstrated below:

```javascript
// const player = new THEOplayer.Player(...)
const airPlayState = player.cast.airplay.state;
const isCasting = player.cast.airlay.casting; // true or false
// ...
// if (want to start AirPlay)
player.cast.airplay.start();
// ...
// if (want to stop AirPlay)
player.cast.airplay.stop();
// ...
if (airPlayState == 'available') {
  // airplay is possible
  player.cast.airplay.addEventListener('statechange', function (event) {
    switch (event.state) {
      case 'available':
        // show AirPlay available icon
        break;
      case 'connected':
        // show AirPlay connected icon
        break;
    }
  });
}
```

Note that the `connected` and `available` state are the only two states offered for AirPlay, because Safari only exposes limited information.

## Remarks

* [Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/introduction.md) and AirPlay are comparable technologies.

---

# DRM on Web

THEOplayer supports FairPlay, PlayReady and Widevine by default. To use these DRM systems, you will need to pass a DRM configuration along with the `source` object. We are partnered with many multi-DRM vendors to make it as easy as possible to get your DRM streams running.

## Integrations

These DRM vendors can be used through an integration. An integration is not part of the SDK: it is added on top of it as a [custom DRM integration](#custom-integration). Ready-made integrations for many vendors are available in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration). Vendors which don't require custom license or certificate requests can be used with a plain key system configuration instead.

* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/arris-titanium.md)
* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/axinom.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/buydrm-keyos.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/castlabs-drmtoday.md)
* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/comcast.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/doverunner.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/ezdrm.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/nagra-conax-contego.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/verimatrix-multirights.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vualto-vudrm.md)

## Pre-integrations

THEOplayer is also pre-integrated with a number of commercial multi-DRM vendors. These pre-integrations are part of the SDK itself: you select the vendor and pass its parameters, and the SDK takes care of the vendor's license and certificate requests. When integrating DRM for the first time or updating your integration, an integration is preferred over a pre-integration.

* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/arris-titanium.md)
* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/axinom.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/buydrm-keyos.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/castlabs-drmtoday.md)
* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/comcast.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/nagra-conax-contego.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/uplynk.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/verimatrix-multirights.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vimond.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vualto-vudrm.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/xstream.md)

## Other guides

* [Clear Key](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/clear-key.md): how to play a Clear Key protected stream.
* [Multi-key HLS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/multikey-hls.md): how to serve one HLS stream to all key systems.

## Custom configuration

Developers can use the generic DRM-functionalities in case in-house DRM-solutions are used, or services from DRM-vendors for which no integration is available.

To configure DRM on the Web SDK, developers can set a [DRMConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/DRMConfiguration) as the [contentProtection](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TypedSource#contentProtection) of a [TypedSource](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TypedSource).

```js
if (HLS) {
  let drmConfiguration = {
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: '<CERTIFICATE_URL>',
      // "certificate": "<CERTIFICATE_AS_STRING_OR_UInt8Array>",
      // "headers": {"<KEY>": "<VALUE>"},
      // "useCredentials": <true||false>
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (MPEG - DASH) {
  let drmConfiguration = {
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
      // "headers": {"<KEY>": "<VALUE>"},
      // "useCredentials": <true||false>
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
      // "headers": {"<KEY>": "<VALUE>"},
      // "useCredentials": <true||false>
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Custom integration

Developers can make their own custom DRM integration for any DRM vendor. This can be done by making use of the [DRM integration API repository](https://github.com/THEOplayer/samples-drm-integration).

A complete guide on how to create a new integration, and some example integrations can be found in the provided repository.

---

# Arris Titanium on Web

This article describes how to configure Arris Titanium DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Arris Titanium integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/titaniumdrm).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'titanium',
    accountName: '<ACCOUNT_NAME>',
    customerName: '<CUSTOMER_NAME>',
    friendlyName: '<FRIENDLY_NAME>',
    portalId: '<PORTAL_ID>',
    authToken: '<AXINOM_TOKEN>',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: '<CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'titanium',
    accountName: '<ACCOUNT_NAME>',
    customerName: '<CUSTOMER_NAME>',
    friendlyName: '<FRIENDLY_NAME>',
    portalId: '<PORTAL_ID>',
    authToken: '<AXINOM_TOKEN>',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Resources

* <https://www.arris.com/products/titanium-cas/>
* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/nagra-conax-contego.md)

---

# Axinom on Web

This article describes how to configure Axinom DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Axinom integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/axinomdrm).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'axinom',
    token: '<AXINOM_TOKEN>',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: '<CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'axinom',
    token: '<AXINOM_TOKEN>',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Resources

* <https://www.axinom.com/products/drm>

## Related articles

* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/comcast.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vualto-vudrm.md)

---

# BuyDRM KeyOS on Web

This article describes how to configure BuyDRM KeyOS DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The BuyDRM KeyOS integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/keyos).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

Pass your BuyDRM token as `customdata`, and tell THEOplayer that you are using KeyOS. The token is the Authentication XML generated from the BuyDRM platform.

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'keyos',
    customdata: '<CUSTOMDATA>',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: '<CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'keyos',
    customdata: '<CUSTOMDATA>',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Resources

* <https://test.buydrm.com/sites/default/files/pdf/webinar/050217_DeployingKeyOSMulti-DRM_withTHEOPLayer_Webinar.pdf>
* [KeyOS BuyDRM](https://www.buydrm.com/keyosplayer)
* [DRMConfiguration API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/DRMConfiguration)

---

# castLabs DRMToday on Web

This article describes how to configure castLabs DRMToday with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The castLabs DRMToday integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/castlabs).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'drmtoday',
    merchant: '<MERCHANT>',
    sessionId: '<SESSION_ID>',
    token: '<TOKEN>',
    userId: '<USER_ID>',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: '<CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'drmtoday',
    merchant: '<MERCHANT>',
    sessionId: '<SESSION_ID>',
    token: '<TOKEN>',
    userId: '<USER_ID>',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Resources

* <https://castlabs.com/drmtoday/>

---

# Comcast on Web

This article describes how to configure Comcast DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the Chromecast SDK.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Comcast integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/comcastdrm).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'comcast',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: '<CERTIFICATE_URL>',
      token: '<TOKEN>',
      releasePid: '<RELEASEPID>',
      accountId: '<ACCOUNT_ID>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Resources

* <https://docs.theplatform.com/help/ent-license-web-services-api-reference>
* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/nagra-conax-contego.md)

---

# EZDRM on Web

This article describes how to configure [EZDRM](https://www.ezdrm.com/) with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The EZDRM integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/ezdrm).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'ezdrm',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: '<CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'ezdrm',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Resources

* [EZDRM documentation](https://www.ezdrm.com/documentation)
* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vualto-vudrm.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vimond.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/verimatrix-multirights.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/doverunner.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/nagra-conax-contego.md)

---

# Intertrust ExpressPlay on Web

This article describes how to configure Intertrust ExpressPlay DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'expressplay',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: '<CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'expressplay',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Resources

* [Verimatrix ExpressPlay DRM and THEOplayer](https://www.verimatrix.com/partners/theoplayer/)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/nagra-conax-contego.md)

---

# Irdeto on Web

This article describes how to configure Irdeto DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Irdeto integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/irdetocontrol).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
    let drmConfiguration = {
        "integration": "irdeto",
        "crmId": "<CRM_ID>",
        "accountId": "<ACCOUNT_ID>",
        "contentId": "<CONTENT_ID>",
        "keyId": "<KEY_ID>",
        "applicationId": "<APPLICATION_ID>"
        "fairplay": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_FAIRPLAY>",
            "certificateURL": "<CERTIFICATE_URL>"
        }
    };
    player.source = {
        "sources": {
            "src": "<HLS_STREAM_URL>",
            "type": "application/x-mpegurl",
            "contentProtection": drmConfiguration
        }
    }
} else if (DASH) {
    let drmConfiguration = {
        "integration": "irdeto",
        "crmId": "<CRM_ID>",
        "accountId": "<ACCOUNT_ID>",
        "contentId": "<CONTENT_ID>",
        "keyId": "<KEY_ID>",
        "applicationId": "<APPLICATION_ID>",
        "playready": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_PLAYREADY>"
        },
        "widevine": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_WIDEVINE>"
        }
    };
    player.source = {
        "sources": {
            "src": "<DASH_STREAM_URL>",
            "type": "application/dash+xml",
            "contentProtection": drmConfiguration
        }
    }
}
```

## Resources

* <https://irdeto.com/video-entertainment/multi-drm-and-rights-management/>

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/nagra-conax-contego.md)

---

# Microsoft Azure on Web

> **Warning**
>
> Azure Media Services has been retired since June 30th, 2024.

This article describes how to configure Microsoft Azure DRM with THEOplayer. Head to [Azure Media Services 3rd Party Player Samples - THEOplayer](https://github.com/Azure-Samples/media-services-3rdparty-player-samples/tree/master/docs/THEOplayer) for an implementation reference sample.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Microsoft Azure integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/azuredrm).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'azure',
    token: 'AZURE_TOKEN>',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: '<CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'azure',
    token: '<AZURE_TOKEN>',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Resources

* <https://azure.microsoft.com/nl-nl/services/media-services/content-protection/>

## Related articles

* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/comcast.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vualto-vudrm.md)
* [Azure Media Services - THEOplayer Implementation Sample](https://github.com/Azure-Samples/media-services-3rdparty-player-samples/tree/master/docs/THEOplayer)

---

# Nagra Conax Contego on Web

This article describes how to configure [Conax](https://dtv.nagra.com/scalable-service-protection) DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Nagra Conax Contego integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/nagradrm).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
  if (CLASSIC_MODEL) {
    let drmConfiguration = {
      integration: 'conax',
      token: '<CONAX_TOKEN>',
      deviceId: '<DEVICE_ID>',
      fairplay: {
        licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
        certificateURL: '<CERTIFICATE_URL>',
      },
    };
    player.source = {
      sources: {
        src: '<HLS_STREAM_URL>',
        type: 'application/x-mpegurl',
        contentProtection: drmConfiguration,
      },
    };
  } else if (UPFRONT_MODEL) {
    let drmConfiguration = {
      integration: 'conax',
      fairplay: {
        licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
        certificateURL: '<CERTIFICATE_URL>',
      },
      headers: {
        PreAuthorization: '<CONAX_PREAUTHORIZATION_TOKEN>',
      },
    };
    player.source = {
      sources: {
        src: '<HLS_STREAM_URL>',
        type: 'application/x-mpegurl',
        contentProtection: drmConfiguration,
      },
    };
  } else {
    // player throws an Invalid Conax configuration error
  }
} else if (DASH) {
  let drmConfiguration = {
    integration: 'conax',
    token: '<CONAX_TOKEN>',
    deviceId: '<DEVICE_ID>',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/microsoft-azure.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/uplynk.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/verimatrix-multirights.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vimond.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vualto-vudrm.md)

---

# Verimatrix MultiRights on Web

This article describes how to configure Verimatrix MultiRights with THEOplayer. [MultiRights](https://www.verimatrix.com/solutions/multirights-ott) is a multi-DRM solution by [Verimatrix](https://www.verimatrix.com/).

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Verimatrix Core integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/verimatrixcoredrm).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'verimatrix',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: '<CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'verimatrix',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Resources

* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/comcast.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vualto-vudrm.md)

---

# Vimond on Web

This article describes how to configure Vimond DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'vimond',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: '<CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'vimond',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Resources

* [Vimond](https://www.vimond.com/)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/nagra-conax-contego.md)

---

# Vualto VuDRM on Web

This article describes how to configure Vualto VuDRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Vualto VuDRM integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/vudrm).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
    let drmConfiguration = {
        "integration": "vudrm",
        "token": "<TOKEN>",
        "fairplay": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_FAIRPLAY>",
            "certificateURL": "<CERTIFICATE_URL>"
        }
    };
    player.source = {
        "sources": {
            "src": "<HLS_STREAM_URL>",
            "type": "application/x-mpegurl",
            "contentProtection": drmConfiguration
        }
    }
} else if (DASH) {
    let drmConfiguration = {
        "integration": "vudrm",
        "token": "<TOKEN>"
        "playready": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_PLAYREADY>"
        },
        "widevine": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_WIDEVINE>"
        }
    };
    player.source = {
        "sources": {
            "src": "<DASH_STREAM_URL>",
            "type": "application/dash+xml",
            "contentProtection": drmConfiguration
        }
    }
}
```

## Resources

* <https://www.vualto.com/products/vudrm-drm/>
* <https://github.com/Vualto/vuplay-theoplayer>

## Related articles

* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/comcast.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vualto-vudrm.md)

---

# Uplynk on Web

This article describes how to configure Uplynk DRM with THEOplayer.

**Important:** Uplynk customers should configure DRM through the [THEOplayer Uplynk integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/preplay.md). More specifically, to configure DRM, developers should use the [`contentProtected`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/preplay.md) flag. (The Uplynk integration provides a pre-integration with Uplynk's Preplay, Ping and Asset Info services, exposes additional APIs, and enhances your UI and UX.)

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'uplynk',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: '<CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'uplynk',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Resources

* [Content Protection (Uplynk)](https://docs.uplynk.com/docs/content-protection)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/nagra-conax-contego.md)

---

# Xstream on Web

This article describes how to configure Xstream DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'xstream',
    streamId: '<STREAM_ID>',
    ticketAcquisitionURL: '<TICKET_ACQUISITION_URL>',
    /*"fairplay": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_FAIRPLAY>",
            "certificateURL": "<CERTIFICATE_URL>"
        }*/
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'xstream',
    streamId: '<STREAM_ID>',
    ticketAcquisitionURL: '<TICKET_ACQUISITION_URL>',
    /*"playready": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_PLAYREADY>"
        },
        "widevine": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_WIDEVINE>"
        }*/
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

## Related articles

* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/comcast.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vualto-vudrm.md)

---

# Clear Key on Web

This article provides a simple example of how to use Clear Key with THEOplayer.

Usually, DRM systems require you to specify a `licenseAcquisitionURL` and additional optional data (e.g.: certificate, credentials, headers). Clear Key does not need a DRM provider. You can provide the key(s) directly to the player (hence "clear" key) through the `keys` property in its `LicenseAcquisitionDescription` (in fact, this property is only available for Clear Key). Alternatively, you can have the player fetch the keys from a `licenseAcquisitionURL`, which returns a JSON object containing the same keys.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

Please check also our related [API documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ClearkeyKeySystemConfiguration) on how to set these.

## Code example

With keys:

```js
player.source = {
  sources: {
    src: 'your-manifest-URL',
    useCredentials: false,
    contentProtection: {
      clearkey: {
        keys: [
          {
            id: 'id',
            value: 'value',
          },
        ],
      },
    },
  },
};
```

With a license URL:

```js
player.source = {
  sources: {
    src: 'https://storage.googleapis.com/shaka-demo-assets/angel-one-clearkey/dash.mpd',
    useCredentials: false,
    contentProtection: {
      clearkey: {
        licenseAcquisitionURL: 'https://cwip-shaka-proxy.appspot.com/clearkey?_u3wDe7erb7v8Lqt8A3QDQ=ABEiM0RVZneImaq7zN3u_w',
      },
    },
  },
};
```

## Resources

* [API Reference - ClearkeyDecryptionKey](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ClearkeyDecryptionKey)
* [Generate MPEG DASH content encrypted with MPEG CENC ClearKey](https://github.com/Dash-Industry-Forum/dash.js/wiki/Generate-MPEG-DASH-content-encrypted-with-MPEG-CENC-ClearKey): DASH IF on GitHub
* [Clear Key license format](https://w3c.github.io/encrypted-media/#clear-key-license-format): W3C - Encrypted Media Extensions

---

# DoveRunner on Web

This article describes how to configure [DoveRunner Multi-DRM](https://doverunner.com/docs/content-security/multi-drm/) with THEOplayer. This content is based on DoveRunner's documentation.

**Note**: The details in the guide apply for DoveRunner (formerly known as "PallyCon"). While most details, API hostnames and variables have been updated to reflect DoveRunner, certain configurations such as the `pallycon-customdata-v2` HTTP request header will still apply.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the Chromecast SDK.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Code example

```js
if (HLS) {
    const certificateUrl = "<CERTIFICATE_URL>";

    // a response interceptor for the certificate URL might be required.
    player.network.addResponseInterceptor(function(response) {
        if(response.url == certificateUrl) {
            const rawResponse = response.body;
            const responseText = String.fromCharCode.apply(null, new Uint8Array(rawResponse));
            const raw = window.atob(responseText);
            const rawLength = raw.length;
            let certificate = new Uint8Array(new ArrayBuffer(rawLength));

            for(let i = 0; i < rawLength; i++)
                certificate[i] = raw.charCodeAt(i);
            response.respondWith({body: certificate})
        }
    });

    const drmConfiguration = {
        "fairplay": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_FAIRPLAY>",
            "certificateURL": certificateUrl,
            "headers": {
                "<CUSTOM_HEADER_NAME>" : "<CUSTOM_HEADER_VALUE>" // e.g. 'pallycon-customdata-v2': 'eyJkYXRhIjoibWJLV1NjSUNIU25WMjZQWFB4cGlDQUJVbnZsOGxCOWRNZDhHZ3dhbjZqRDFwNFZoQk51VlhQY2RMaG9nNTNYbngyTjFaalwvQ3BxZ3RUS2k5Rzd3MUZ3PT0iLCJzaXRlX2lkIjoiREVNTyIsImRybV90eXBlIjoiUGxheVJlYWR5In0='
            }
        }
    };
    player.source = {
        "sources": {
            "src": "<HLS_STREAM_URL>",
            "type": "application/x-mpegurl",
            "contentProtection": drmConfiguration
        }
    }
} else if (DASH) {
    const drmConfiguration = {
        "playready": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_PLAYREADY>",
            "headers": {
                "<CUSTOM_HEADER_NAME>" : "<CUSTOM_HEADER_VALUE>"
            }
        },
        "widevine": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_WIDEVINE>",
            "headers": {
                "<CUSTOM_HEADER_NAME>" : "<CUSTOM_HEADER_VALUE>"
            }
        }
    };
    player.source = {
        "sources": {
            "src": "<DASH_STREAM_URL>",
            "type": "application/dash+xml",
            "contentProtection": drmConfiguration
        }
    }
}"
```

## Resources

* <https://doverunner.com/docs/content-security/multi-drm/>
* <https://doverunner.com/docs/content-security/multi-drm/clients/html5-player/>

## Related articles

* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vualto-vudrm.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/vimond.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/verimatrix-multirights.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/nagra-conax-contego.md)

---

# Multi-key HLS on Web

There are multiple DRM key systems on the market to choose from. The most popular ones are Google Widevine, Microsoft PlayReady and Apple FairPlay. Under the hood, all these systems encrypt the media samples using the AES-128 encryption algorithm. AES-128 is a standardized block-cipher that allows for multiple ways of choosing the blocks. Widevine and PlayReady both use `CTR` and FairPlay uses `CBC`. Therefore, it was possible to share segments between Widevine and PlayReady protected streams, but not with FairPlay protected stream. However, support has been added for Widevine and PlayReady with AES-128 in `CBC` mode. Hence, it is now possible to create HLS streams compatible with all these key systems. Where you previously had to encode the stream twice, this is no longer needed.

A multi-key HLS stream will play in all web platforms that support MSE and either Widevine, PlayReady or FairPlay.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md) for more general information.

## The HLS playlist

A multi-key HLS playlist could look like this:

```text
#EXTM3U
#EXT-X-TARGETDURATION:6
#EXT-X-VERSION:5
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-KEY:METHOD=SAMPLE-AES,KEYFORMAT="urn:uuid:edef8ba9-79d6-4ace-a3c8-27dcd51d21ed",KEYFORMATVERSIONS="1",URI="WIDEVINE_INIT_DATA_URL"
#EXT-X-KEY:METHOD=SAMPLE-AES,KEYFORMAT="com.microsoft.playready",KEYFORMATVERSIONS="1",URI="PLAYREADY_INIT_DATA_URL"
#EXT-X-KEY:METHOD=SAMPLE-AES,KEYFORMAT="com.apple.streamingkeydelivery",KEYFORMATVERSIONS="1",URI="FAIRPLAY_INIT_DATA_URL"
#EXT-X-MAP:URI="init.mp4"
#EXTINF:6,
1.mp4
#EXTINF:6,
2.mp4
#EXTINF:6,
3.mp4
#EXTINF:6,
4.mp4
#EXTINF:6,
5.mp4
#EXT-X-ENDLIST
```

There is an `#EXT-X-KEY` tag for all the key systems which all have method `SAMPLE-AES`. The `KEYFORMAT` specifies the key system:

* `urn:uuid:edef8ba9-79d6-4ace-a3c8-27dcd51d21ed` for Widevine
* `com.microsoft.playready` for PlayReady
* `com.apple.streamingkeydelivery` for FairPlay

The `URI` is either a data URI containing the initialization data, or a URI pointing to the initialization data. For more information, please check out the specifications for [Widevine](https://www.academia.edu/36030972/Widevine_DRM_for_HLS), [PlayReady](https://docs.microsoft.com/en-us/playready/packaging/mp4-based-formats-supported-by-playready-clients?tabs=case4) and [FairPlay](https://developer.apple.com/streaming/fps/).

## Configuring THEOplayer

A corresponding player configuration looks like:

```javascript
player.source = {
  sources: [
    {
      src: 'https://yourdomain.com/playlist.m3u8',
      type: 'application/x-mpegurl',
      contentProtection: {
        widevine: {
          licenseAcquisitionURL: 'https://widevine-server.com/license',
        },
        playready: {
          licenseAcquisitionURL: 'https://playready-server.com/license',
        },
        fairplay: {
          certificateURL: 'https://fairplay-server.com/certificate',
          licenseAcquisitionURL: 'https://fairplay-server.com/license',
        },
      },
    },
  ],
};
```

---

# Integrations on Web

In this section, you can figure out how THEOplayer integrates with various partners.

## Related articles

* [IRIS.TV](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/integrations/iris-tv.md)
* [Protect streams with Wowza SecureToken version 2](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/integrations/wowza-streaming-engine/secure-token.md)
* [Deliver Low-Latency HLS live streams with Wowza Streaming Engine](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/integrations/wowza-streaming-engine/low-latency-hls.md)

---

# IRIS.TV on Web

[Iris.TV](https://www.iris.tv/) is a recommendation engine. When hooking THEOplayer to the Iris.TV SDK, a UI is overlaid over the player UI, which can be used to navigate through recommendations.

This guide describes how to do a [custom Iris.TV integration](https://iristv.atlassian.net/wiki/spaces/API/pages/38567965/Custom+Adaptive+Plug-in+Integrations) in THEOplayer.

## Prerequisites

1. You have a THEOplayer license and library. If you don't have THEOplayer yet, you can start your free trial [here](https://portal.theoplayer.com/), or contact your account manager.
2. You have a working THEOplayer setup. See "[Getting started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md)".

## Include the Iris.TV SDK

Include the Iris.TV JavaScript library right before where you include the THEOplayer library:

```html
<script type="text/javascript" src="https://ovp.iris.tv/libs/adaptive/iris.adaptive.js"></script>
```

## Include the custom integration

Include the script tag referencing the file with the custom integration code right after where you include the THEOplayer library:

```html
<script type="text/javascript" src="https://cdn.theoplayer.com/demos/iristv/THEOplayer.iristv.js"></script>
```

You can also add extra styling on top of the Iris.TV UI:

```html
<link rel="stylesheet" type="text/css" href="https://cdn.theoplayer.com/demos/iristv/THEOplayer.iristv.css" />
```

## Initialize THEOplayerIrisTv

To start displaying the Iris.TV UI, call `THEOplayerIrisTv()` (from `THEOplayer.iristv.js`), and pass along the THEOplayer instance and your Iris.TV configuration. For example:

```js
const irisOptions = {
  client_token: '51afa098ah',
  platform_id: '5798d994ef995e0d18000176',
};

THEOplayerIrisTv(player, irisOptions);
```

## Sample application

A live demo can be viewed at <https://cdn.theoplayer.com/demos/iristv/iristv.html>.

## Resources

* [Iris.TV documentation: THEO adaptive plugin](https://iristv.atlassian.net/wiki/spaces/API/pages/263258113/THEO+Adaptive+Plugin)
* [Iris.TV documentation: Custom adaptive plugin](https://iristv.atlassian.net/wiki/spaces/API/pages/38567965/Custom+Adaptive+Plugin)

---

# Wowza Streaming Engine on Web

[Wowza Streaming Engine™](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/) is a media server for live and on-demand streaming. THEOplayer can play back its streams, and integrates with a number of its features.

---

# Wowza Streaming Engine SecureToken version 2 on Web

Wowza Streaming Engine™ offers a SecureToken version 2 module, which provides playback protection through a security token that is exchanged between the server and its clients. The SecureToken is a challenge/response system that helps to protect content against spoofing threats. Each connection is protected by a random key and a password (shared secret).

An important aspect when generating the hash is that the client web server should generate the hash when it generates the client webpage. The **client webpage should not** use JavaScript code to generate the hash, as the code is visible in the webpage source and would pose a potential security risk. As a result, the implementation below is based on a Node/Express application to generate the hash.

## Prerequisites

1. You have a THEOplayer license. If you are not using THEOplayer yet, you can start your free trial [here](https://portal.theoplayer.com/).

2. You are a Wowza Streaming Engine client and are integrated with their streaming infrastructure. Information on Wowza Streaming Engine can be found [here](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/), and information on how to protect your streams using SecureToken can be found [here](https://www.wowza.com/docs/how-to-protect-streaming-using-securetoken-in-wowza-streaming-engine).

3. For the purposes of this example, we created a VOD application (this example would also work for live applications) in the Wowza Streaming Engine manager, configured with the following settings in the **Playback Security** tab:

   * SecureToken: **Protect all protocols using hash (SecureToken version 2)**
   * Shared Secret: **53a0a16b7cde230b**
   * Hash Algorithm: **SHA-256**
   * Include client IP address in hash generation: **Ticked (yes)**
   * Hash Query Parameter Prefix: **wowzatoken**
   * Client Restrictions: **No client restrictions**

   The application was saved and restarted.

## Server-side hash generation code

The below code makes reference to the above configuration settings specified in the Wowza Streaming Engine manager.

```js
var express = require('express');
var app = express();

var crypto = require('crypto');
var address = require('address');

// add CORS headers
app.use('/generate-hash', function (req, res, next) {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept');
  next();
});

const path = require('path');
const port = 3000;

/****************** START OF CONFIGURATION ******************/

// your hash algorithm: 256, 384 OR 512
const hashAlgorithm = '256';

// your shared Secret
const sharedSecret = '53a0a16b7cde230b';

// the content path to the streaming asset and is the part of the URL that starts with the application name
// (excluding the '/' that precedes the application name) and continues through to the end of the stream name or file name.
// Be sure to exclude all HTTP request keywords after the stream name or file name (for example, /manifest.m3u8, /media.ts, /Manifest, /manifest.f4v, and so on)
const contentPath = 'vod/mp4:sample.mp4';

// your token prefix custom parameter
const tokenPrefix = 'wowzatoken';

// your random custom parameter (optional - leave as empty string if none)
const customParameter = 'myrandomcustomparameter';

// include client IP address in hash generation (yes/no)?
const includeClientIPAddress = 'yes';

//const now = new Date();
//const startTime = Math.round(now.getTime() / 1000);
const startTime = '0';
//const validity = 1000; // validity in seconds

//const endTime = Math.round(now.getTime() / 1000) + validity;
const endTime = '0';

/****************** END OF CONFIGURATION ******************/

var params = [];

// create an array with the parameters
if (includeClientIPAddress == 'yes') {
  address(function (err, addrs) {
    params.push(addrs.ip);
  });
}

params.push(
  tokenPrefix + 'startTime=' + startTime,
  tokenPrefix + 'endTime=' + endTime,
  tokenPrefix + 'customParameter=' + customParameter,
  sharedSecret
);

// params should be sorted alphabetically before constructing the hash string
params.sort();

// construct the hash string
var hashString = contentPath + '?';

for (var i = 0; i < params.length; i++) {
  if (i + 1 == params.length) {
    hashString = hashString + params[i];
  } else {
    hashString = hashString + params[i] + '&';
  }
}

// the hash generated at the client should be a URL-safe Base64-encoded string.
app.get('/generate-hash', function (req, res, next) {
  var hash = crypto
    .createHash('sha' + hashAlgorithm)
    .update(hashString, 'utf8')
    .digest('base64');

  // URL-safe Base64 encoding replaces the '+' character with the '-' character and the '/' character with the '_' character.
  hash = hash.replace(/\+/g, '-');
  hash = hash.replace(/\//g, '_');

  console.log(hashString);

  res.send(hash);
});

// Listen for requests
app.get('/', function (req, res) {
  res.sendFile(path.join(__dirname + '/index.html'));
});

app.listen(port);
```

Save this JavaScript file as wowzasecuretoken.js and then run it with `node wowzasecuretoken.js`

## Client-side hash generation code

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Web SDK: Getting Started</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="path/to/theoplayer/ui.css" />
    <!-- adds THEOplayer CSS -->
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin"></div>
    <script type="text/javascript" src="path/to/thoeplayer/THEOplayer.js"></script>
    <!-- adds THEOplayer library -->
    <script>
      // Initialize player function once the hash has been retrieved
      var initPlayer = function (hash) {
        console.log(hash);
        // Replace http://192.168.1.34:1935/vod/mp4:sample.mp4/playlist.m3u8 with your stream manifest
        var hlsUrl =
          'http://192.168.1.34:1935/vod/mp4:sample.mp4/playlist.m3u8?' +
          'wowzatokenstartTime=0&' +
          'wowzatokenendTime=0&' +
          'wowzatokencustomParameter=myrandomcustomparameter&' +
          'wowzatokenhash=' +
          hash;

        console.log(hlsUrl);

        var element = document.querySelector('.video-js');
        var player = new THEOplayer.Player(element, {
          libraryLocation: 'path/to/theoplayer',
          license: 'your-license-here',
        });

        player.src = hlsUrl;
      };

      // Ajax request for the hash to the node/express app
      var requestHash = function (url) {
        var req = new XMLHttpRequest();
        req.open('GET', url, true);
        req.onreadystatechange = function () {
          if (req.readyState === 4) {
            var response = req.responseText;
            if (req.status === 200) {
              initPlayer(response);
            } else {
              console.log('Could not get hash');
            }
          }
        };
        req.onerror = function () {
          console.log('Could not get hash');
        };
        req.send();
      };

      // Start the request to your node/express server. Be sure to replace http://127.0.0.1:3000 with your node IP address and port
      var serverHashUrl = 'http://127.0.0.1:3000/generate-hash';
      requestHash(serverHashUrl);
    </script>
  </body>
</html>
```

Save this HTML file as `index.html` and then view it in your browser window.

## Resources

* [Getting started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md)
* [Getting Started with Wowza Streaming Engine](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/)
* [Protect your streams using SecureToken in Wowza Streaming Engine](https://www.wowza.com/docs/how-to-protect-streaming-using-securetoken-in-wowza-streaming-engine)

---

# Deliver Low-Latency HLS live streams with Wowza Streaming Engine on Web

Wowza Streaming Engine™ media server software can deliver Low-Latency HLS (LL-HLS) live streams, which THEOplayer can play back on every platform.

Low-Latency HLS streams conform to [Apple's protocol extension to the HLS specification](https://developer.apple.com/documentation/http-live-streaming/enabling-low-latency-http-live-streaming-hls).

## Prerequisites

There are three prerequisites in order to continue with this guide:

1. In order to generate LL-HLS streams, you must first get a SSL certificate to secure your port and configure the port for HTTPS playback. LL-HLS playback does not work without an SSL secured port. For information on how to do this, refer to [How to Get an SSL Certificate from Wowza's Streamlock Service](https://www.wowza.com/docs/how-to-get-ssl-certificates-from-the-streamlock-service).

2. This guide expects that you have a THEOplayer license. If you are not using THEOplayer yet, you can start your free trial [here](https://portal.theoplayer.com/).

3. This guide expects that you are a Wowza Streaming Engine client and that you are integrated with their streaming infrastructure. Information on Wowza Streaming Engine can be found [here](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/). Be sure to have Wowza Streaming Engine media server software version 4.7.8 or higher.

**Please Note:** Wowza occasionally update their documentation, which can be accessed [here](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine).

## Configure a live application to deliver LL-HLS streams

You can use the default **live** application that installs with Wowza Streaming Engine or create and use a new **Live** or **Live HTTP Origin** application. Use the **Live** application type for sending streams from Wowza Streaming Engine to clients or Wowza Streaming Engine edges. Use the **Live HTTP Origin** application type to connect to a CDN edge, such as the Fastly CDN, that can pull streams from the Wowza Streaming Engine origin application.

The following steps use the default **live** application to enable LL-HLS live streaming by editing the **Application.xml** and **VHost.xml** configuration files.

**Please Note:** If you're trying to use the CMAF packetizer to deliver LL-HLS and HLS or MPEG-DASH streams, you must use two separate live applications: one configured specifically for LL-HLS and another for CMAF-packetized HLS and MPEG-DASH.

### Enable LL-HLS in Wowza Streaming Engine XML

The following steps enable transmuxing for CMAF packetization for LL-HLS delivery.

1. Navigate to **\[install-dir]/conf/live** or **\[install-dir]/conf/\[custom live application]** and open the **Application.xml** file in a text editor.
2. Add **cmafstreamingpacketizer** to the **LiveStreamPacketizers** property. You can add it to the prepopulated comma-separated list, or it can be the only packetizer specified. The XML looks like this:

```xml
<Streams>
    ...
    <LiveStreamPacketizers>cmafstreamingpacketizer</LiveStreamPacketizers>
    ...
</Streams>
```

**Please Note:** If you enable **cupertinostreamingpacketizer** and **cmafstreamingpacketizer**, Wowza Streaming Engine generates both MPEG-TS segments (using **cupertinostreamingpacketizer**) and fMP4 segments (using **cmafstreamingpacketizer**).

3. Add the **cmafLLEnableLowLatency** property to the **LiveStreamPacketizer** container element and set it to true.

```xml
<LiveStreamPacketizer>
    <Properties>
        <Property>
            <Name>cmafLLEnableLowLatency</Name>
            <Value>true</Value>
            <Type>Boolean</Type>
        </Property>
    </Properties>
</LiveStreamPacketizer>
```

4. For the **HTTPStreamers** property, make sure HLS (**cupertinostreaming**) is specified. The XML looks like this:

```xml
<HTTPStreamers>cupertinostreaming</HTTPStreamers>
```

5. Go to **\[install-dir]/conf/** and open the **VHost.xml** file in a text editor.

6. Add the `AllowHttp2` property to the `<SSLConfig>` container element in the `<HostPort>` you configured for SSL/TLS and set it to true.

```xml
<SSLConfig>
    ...
    <AllowHttp2>true</AllowHttp2>
    ...
</SSLConfig>
```

7. Save your changes.

Your live application is now configured to deliver LL-HLS streams.

### Configure optional low latency partial segment properties and media playlist property

Configuring the following properties is optional as Wowza Streaming Engine will use the property's default value for any of the properties that you do not configure. You can configure the optional LL-HLS properties by editing the **Application.xml** file for your LL-HLS live stream application. For information about configuring custom (optional) properties, see [Add custom properties](https://www.wowza.com/docs/add-a-custom-property#add-custom-properties).

#### Low latency CMAF property reference

You can configure any of these optional **LiveStreamPacketizer** properties for the LL-HLS segments and video and audio partial segments (chunks) in the **Application/LiveStreamPacketizer/Properties** container element.

**Please Note:** If partial segments are too small, servers can become overloaded with frequent media playlist requests and cause playback to be less reliable.

| Name                                                                                                                                                          | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **cmafLLChunkingScheme**                                                                                                                                      | String  | Specifies the chunking scheme for low latency CMAF-packetized streams. Valid values are **byFrame** or **byDuration**. The default is **byDuration**. If the value is **byDuration**, packetization is configured using the **cmafLLChunkDurationTargetAudio** and **cmafLLChunkDurationTargetVideo** properties. If the value is **byFrame**, packetization is configured using the **cmafLLChunkFrameCountTargetAudio** and **cmafLLChunkFrameCountTargetVideo** properties. |
| **cmafLLChunkDurationTargetAudio**                                                                                                                            | Integer | Specifies, in milliseconds, the target duration of each low latency CMAF **audio** chunk. The default is **1000** and is recommended. The duration cannot exceed the [cmafSegmentDurationTarget](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine#cmafsegmentdurationtarget) value. This property is only available if **cmafLLChunkingScheme** is **byDuration**.                                                           |
| **cmafLLChunkDurationTargetVideo**                                                                                                                            | Integer | Specifies, in milliseconds, the target duration of each low latency CMAF **video** chunk. The default is **1000** and is recommended. The duration cannot exceed the [cmafSegmentDurationTarget](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine#cmafsegmentdurationtarget) value. This property is only available if **cmafLLChunkingScheme** is **byDuration**.                                                           |
| **cmafLLChunkFrameCountTargetAudio**                                                                                                                          | Integer | Specifies the target number of audio frames to include in each low latency CMAF audio chunk. The default is **47** and is recommended. This property is only enabled if **cmafLLChunkingScheme** is **byFrame**.                                                                                                                                                                                                                                                               |
| **cmafLLChunkFrameCountTargetAudio**                                                                                                                          | Integer | Specifies the target number of audio frames to include in each low latency CMAF audio chunk. The default is **30** and is recommended. This property is only enabled if **cmafLLChunkingScheme** is **byFrame**.                                                                                                                                                                                                                                                               |
| **[cmafSegmentDurationTarget](https://www.wowza.com/docs/configure-cmaf-packetization-in-wowza-streaming-engine#cmaf-live-packetization-property-reference)** | Integer | Specifies, in milliseconds, the duration of the fMP4 segments in the stream. The default is **6000** (6 seconds) and is recommended. This property is configurable from the **CMAFStreamingPacketizer** properties section in Wowza Streaming Engine Manager.                                                                                                                                                                                                                  |

#### Advanced LL-HLS property reference

For advanced tuning, you can configure the following optional **HTTPStreamer** property in the **Application/HTTPStreamer/Properties** container element.

| Name                                    | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cupertinoPartHoldBack (4.8.0 and later) | Double | Specifies, in floating-point seconds, the server-recommended minimum distance from the live edge at which clients should begin to play or seek in a LL-HLS stream (the PART-HOLD-BACK attribute in media playlists). If you do not configure this property, Wowza Streaming Engine uses the default value, which is recommended. The default value is calculated as three times the maximum value of PART-TARGET out of all of a stream's variant media playlists. **Please Note:** PART-TARGET is an attribute of the EXT-X-PART-INF tag in media playlists and is based on the target values set with the **cmafLLChunkDurationTargetVideo** and **cmafLLChunkDurationTargetAudio** properties or the **cmafLLChunkFrameCountTargetVideo** and **cmafLLChunkFrameCountTargetAudio** properties. Wowza Streaming Engine will adjust the PART-HOLD-BACK value to be equal to the maximum value of PART-TARGET (across all variant media playlists) if you set this property to less than a partial segment duration. |

#### Transcoding considerations for LL-HLS

To bypass encoding streams with Transcoder, source streams should meet the following encoding recommendations. Otherwise, transcoding is recommended. Although a small amount of latency is introduced with transcoding, if your source stream does not meet the encoding recommendations, transcoding will ultimately improve reliability of LL-HLS streaming.

##### Encoding recommendations

* CMAF-supported codecs (required)

| Video          | Audio                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - H.264, H.265 | - AAC, AAC-LC, HE-AAC (AAC+ or aacPlus),<br />- HE-AACv2 (enhanced AAC+, aacPlus v2) - Dolby Digital 5.1 Surround Sound (AC-3) and Dolby Digital Plus (Enhanced AC-3 or E-AC-3) |

* GOP size: 1 or 2 seconds
* Closed GOPs
* H.264 and H.265 byte streams contain metadata about the GOP structure
* Constant frame rate video

A stream configured for transcoding and LL-HLS delivery cannot use **Passthrough** for the **Video Codec** of a stream rendition but not other renditions of the same stream. If you use **Passthrough** to pass a video source through to output without making any changes for any **Video Codec** in a stream's renditions, all of the video codecs must be set to **Passthrough**.

Stream name groups (NGRP) are not supported with LL-HLS. To group multiple stream renditions for LL-HLS, you need to create a SMIL file in accordance with CMAF HLS. See [Set up adaptive bitrate CMAF streaming](https://www.wowza.com/docs/create-adaptive-bitrate-cmaf-streams-using-wowza-streaming-engine#set-up-adaptive-bitrate-cmaf-streaming) for how to do this.

#### Scale LL-HLS with a CDN

Optionally, with your own CDN account, you can scale LL-HLS delivery by connecting a Wowza Streaming Engine **Live HTTP Origin** application to a CDN edge that can pull streams from the Wowza Streaming Engine origin application, such as the Fastly CDN.

To connect the **Live HTTP Origin** application to your CDN, provide the IP address or hostname of the Wowza Streaming Engine origin server in your CDN configuration. Also in your CDN configuration, enable connecting to the origin server over SSL/TLS using the port you configured for SSL/TLS in the Wowza Streaming Engine origin (default port 443).

#### Test stream playback

After your live application is configured to deliver an LL-HLS stream, complete the stream setup by connecting a source encoder or IP camera to Wowza Streaming Engine and publishing the live source stream to the server. When the camera or encoder is connected and the live stream is active, test LL-HLS playback using a supported test player.

To test LL-HLS live streams when only **cmafstreamingpacketizer** is enabled, specify the stream playback URL using one of the following formats:

**Single bitrate** https\://\[address]/\[application]/\[application-instance]/\[stream-name]/playlist.m3u8

If **cmafstreamingpacketizer** and **cupertinostreamingpacketizer** are enabled, specify the stream playback URL using one of the following formats:

**Single bitrate** https\://\[address]/\[application]/\[application-instance]/\[stream-name]/playlist\_sfm4s.m3u8

Where:

**\[address]** is the IP address or domain and port (default port 443) **\[application]** is the application name **\[application-instance]** is the name of the application instance (if omitted, defaults to ***definst***) **\[stream-name]** is the stream name So, for example, if only **cmafstreamingpacketizer** is enabled, the playlist URL for an adaptive bitrate LL-HLS stream that uses the address **example.com**, the default **live** application, and the default stream name **myStream** is:

<https://example.com/live/smil:myStream.smil/playlist.m3u8>

If **cmafstreamingpacketizer** and **cupertinostreamingpacketizer** are both enabled, the adaptive bitrate LL-HLS playlist URL for the same example is:

<https://example.com/live/smil:myStream.smil/playlist_sfm4s.m3u8>

and the playback URL for the Cupertino HLS stream is either:

<https://example.com/live/smil:myStream.smil/playlist.m3u8>

or

<https://example.com/live/smil:myStream.smil/playlist_sfts.m3u8>

where **\_sfts** indicates that the media playlist contains .ts segments.

## Configure THEOplayer to play your LL-HLS stream

1. Set up a basic HTML file and include the THEOplayer library. See "[Getting started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md)".
2. Specify the LL-HLS stream generated above as the `src` of your source configuration.
3. Set `lowLatency` to `true` on that source.

```js
player.source = {
  sources: [
    {
      src: 'https://5d6e17f1ca731.streamlock.net/LowLatencyBBB/myStream/playlist.m3u8',
      type: 'application/x-mpegurl',
      lowLatency: true,
    },
  ],
};
```

## Resources

* [Getting Started with Wowza Streaming Engine](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/)
* [Deliver Apple Low-Latency HLS live streams using Wowza Streaming Engine](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine)

---

# Media tracks on Web

The articles in this section describe how to implement common use-cases related to audio and video tracks, such as switching between audio languages, or selecting a specific video quality.

The MediaTrack API, and its AudioTrack and VideoTrack sub-APIs, allow you to programmatically enable and disable audio tracks, inspect the available video qualities, override the ABR algorithm and more.

## Related articles

* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/enable-disable-audio-tracks.md)
* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-audio-tracks.md)
* [How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-audio-track-changes.md)
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/select-video-track-quality.md)
* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-video-track-qualities.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-video-track-quality-changes.md)
* [How to reduce data usage on mobile devices](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/reduce-data-usage.md)
* [How to start with a specific quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/start-with-specific-quality.md)

---

# How to programmatically enable or disable audio tracks on Web

This article describes how you can use the AudioTrack API, a sub-API of the MediaTrack API, to enable or disable audio tracks. Implementing this functionality is a common use-case for developers who want to build their own UI to toggle audio languages on and off.

Once you have programmatically selected a track, you can set its `enabled` property (or method) to `true` or `false`. Because only one audio track can play at a time, enabling an audio track automatically disables all other audio tracks. Note that this does not apply to text tracks: multiple text tracks can be active at the same time.

## Usage

The Web SDK exposes the audio tracks through [`player.audioTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#audiotracks), which contains [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrack) objects with an [`enabled`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrack#enabled) property.

```js
// enable a specific audio track
player.audioTracks[indexOfRequestedAudioTrack].enabled = true;
```

## Related articles

* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-audio-tracks.md)
* [How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-audio-track-changes.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md)

---

# How to programmatically detect audio tracks on Web

This article describes how you can use the AudioTrack API, a sub-API of the MediaTrack API, to detect audio tracks. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available audio languages.

## Usage

Listen for the [`addtrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap#addtrack) event on [`player.audioTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#audiotracks) to detect every [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrack) that is added to the player.

```js
function handleAddTrackEvent(addTrackEvent) {
  const audioTrack = addTrackEvent.track;
}
player.audioTracks.addEventListener('addtrack', handleAddTrackEvent);
```

## Related articles

* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/enable-disable-audio-tracks.md)
* [How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-audio-track-changes.md)
* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-video-track-qualities.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md)

---

# How to programmatically select a video track quality on Web

This article describes how you can use the VideoTrack API, a sub-API of the MediaTrack API, to select a video track quality. If you select a specific quality, you overrule the ABR algorithm.

Implementing this functionality is a common use-case for developers who want to build their own UI to toggle a specific video quality.

## Usage

Set the [`targetQuality`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrack#targetquality) property of a [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrack) to a single quality, to an array of qualities, or to `null`.

```js
const videoTrack = player.videoTracks[0];

// enable a specific video track quality
videoTrack.targetQuality = videoTrack.qualities[indexOfRequestedVideoTrackQuality];

// do ABR on a set of qualities
videoTrack.targetQuality = [videoTrack.qualities[indexOfRequestedVideoTrackQuality1], videoTrack.qualities[indexOfRequestedVideoTrackQuality2]];

// set to default ABR algorithm
videoTrack.targetQuality = null;
```

## Related articles

* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-video-track-qualities.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-video-track-quality-changes.md)
* [How to reduce data usage on mobile devices](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/reduce-data-usage.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md)

---

# How to programmatically detect video track qualities on Web

This article describes how you can use the VideoTrack API, a sub-API of the MediaTrack API, to detect video track qualities. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available video track qualities.

## Usage

The [`qualities`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrack#qualities) of a video track are available as soon as the track is added to [`player.videoTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#videotracks).

```js
function handleAddTrackEvent(addTrackEvent) {
  const videoTrackQualities = addTrackEvent.track.qualities;
}
player.videoTracks.addEventListener('addtrack', handleAddTrackEvent);
```

## Related articles

* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/select-video-track-quality.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-video-track-quality-changes.md)
* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-audio-tracks.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md)

---

# How to start with a specific quality on Web

This article describes how you can start playback with a specific quality. Developers typically want their HLS or MPEG-DASH stream to start with a specific rendition of the manifest to speed up the time-to-first-frame, to serve a better quality to the customer, or to serve a different quality on different platforms.

## Usage

When the `addtrack` event is dispatched, THEOplayer has not started buffering yet, so you can still adjust the [`targetQuality`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrack#targetquality). This property allows you to specify a set of qualities that THEOplayer can use for ABR selection. THEOplayer has to select the given quality if only one quality is provided. You reset the ABR selection by setting `targetQuality` to `null`.

```js
const player = new THEOplayer.Player(element, playerConfig);
player.videoTracks.addEventListener('addtrack', function () {
  player.videoTracks[0].targetQuality = player.videoTracks[0].qualities[0]; // start with a specific quality
  player.addEventListener('progress', attachABRResetLogic);
});

function attachABRResetLogic() {
  if (player.buffered.length > 0) {
    // switch to normal ABR when THEOplayer buffered beyond 10 seconds
    if (player.buffered.end(player.buffered.length - 1) > 10) {
      player.videoTracks[0].targetQuality = null;
      player.removeEventListener('progress', attachABRResetLogic);
    }
  }
}

player.source = {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
    },
  ],
};
```

> **Note**
>
> This is not possible on iOS (and with DRM streams in macOS Safari), because playback control on the Apple HLS playback pipeline is very limited.

## Related articles

* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/select-video-track-quality.md)
* [How to reduce data usage on mobile devices](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/reduce-data-usage.md)

---

# How to reduce data usage on mobile devices on Web

Customers who leverage THEOplayer's preloading capabilities (`preload = "auto"`), or who provide very high qualities, sometimes receive complaints about data usage on mobile devices. You can combat this by leveraging the ABR API and the MediaTrack API, as described in the steps below.

## 1. Lower the target buffer

The target buffer is the amount of seconds which the player buffers ahead of the current playback position. The standard buffer time is 20 seconds. Setting a lower number (e.g. 6 seconds) allows you to download less information in front of the playhead position. This value is also used when preloading content.

To set the target buffer length in seconds, use the [`targetBuffer`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ABRConfiguration#targetbuffer) property of the [ABR API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ABRConfiguration):

```js
player.abr.targetBuffer = 6;
```

If necessary to have a different target buffer length for mobile, add a check like this:

```js
if (THEOplayer.videojs.browser.IS_ANDROID || THEOplayer.videojs.browser.IS_IOS) {
  player.abr.targetBuffer = 8;
}
```

This snippet leverages THEOplayer's Video.js component.

## 2. Manage preloading

Preloading is a powerful feature when trying to reduce the join time. It is more effective in some situations than others, and managing it correctly helps you reduce the data usage:

* preloading a live stream may entail appending information in the buffer that will never be played, if the user waits long enough before clicking "Play";
* in those situations when a user is not yet likely to be playing a stream (e.g. the player is not yet in view), preloading may also mean downloading information that the user will not consume.

So, based on your use case, you might decide whether to enable preloading.

```js
player.preload = 'auto'; // "metadata" is also a valid value
```

## 3. Choose the renditions considered for ABR

On mobile devices, THEOplayer by default takes into account the player size for ABR: this lets it avoid selecting renditions too big to be appreciated on the current device, thus avoiding wasting data.

Leveraging the target quality of the MediaTrack API, you can refine the rendition choice further and indicate yourself to the player which qualities should be considered for ABR. For example, you could configure that THEOplayer should only do ABR on the lowest 3 qualities of a stream containing 5.

You can also configure the [`restrictToPlayerSize`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/SourceAbrConfiguration#restrictToPlayerSize) property of the source's ABR configuration to replicate the mobile behavior on laptop and desktop browsers.

See [how to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/select-video-track-quality.md) to learn how to set the [`targetQuality`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrack#targetquality) of a video track.

## Conclusion

There are several actions that can be taken to drastically reduce data usage on mobile devices, both in the player and at other levels. As far as the player is concerned, by leveraging its API as described you can filter different use cases and handle several aspects related to media download for each use case. This enables you to manage the precise behavior in each case and optimize data usage.

## Related articles

* [How to start with a specific quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/start-with-specific-quality.md)
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/select-video-track-quality.md)
* [Preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/preloading.md)

---

# How to programmatically detect video track quality changes on Web

This article describes how you can use the VideoTrack API, a sub-API of the MediaTrack API, to detect video track quality changes. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the video track quality that is currently active.

## Usage

Listen for the [`activequalitychanged`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrackEventMap#activequalitychanged) event of a [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrack).

```js
// detect video tracks being added to the player
player.videoTracks.addEventListener('addtrack', function (addTrackEvent) {
  // detect quality changes of a track
  addTrackEvent.track.addEventListener('activequalitychanged', function (event) {
    console.log('activequalitychanged event detected!', event);
  });
});
```

## Related articles

* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-video-track-qualities.md)
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/select-video-track-quality.md)
* [How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-audio-track-changes.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md)

---

# How to programmatically detect audio track changes on Web

This article describes how you can use the AudioTrack API to detect audio track changes. An audio track "change" is triggered by enabling (or disabling) an audio track.

Implementing this functionality is a common use-case for developers who want to build their own UI, and annotate the audio track that is currently active.

## Usage

The implementation of the Web SDK applies to all web-based platforms, including Tizen and webOS.

The Web SDK exposes the AudioTrack API through [`player.audioTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#audiotracks). This `audioTracks` property is a [`MediaTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrackList) that inherits from the [`TrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackList). This `TrackList` dispatches the events from the [`TrackListEventMap`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap). This `TrackListEventMap` contains the [`change`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap#change) event, as well as the `addtrack` and `removetrack` event.

The code below allows you to detect audio track changes.

```js
player.audioTracks.addEventListener('change', function (event) {
  const track = event.track;
  console.log(track, track.label, track.language, track.enabled);
});
```

The properties of a media `track` (e.g. `enabled`, `language`) are described in [the `MediaTrack` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrack).

## Related articles

Are you reading this article because you are interested in audio tracks? Continue reading below.

* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-audio-tracks.md)
* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/enable-disable-audio-tracks.md)

Are you reading this article because you are implementing a custom UI? Then you will find the following articles interesting:

* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md)
* [How to detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-video-track-quality-changes.md)
* [How to detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-text-track-changes.md)

---

# Miscellaneous on Web

In this section, you can find guides on how to use many of the player features that are not addressed in the other sections of this documentation.

## [📄️Related content](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/related-content.md)

[The related content feature adds a component to the default UI which enables viewers to navigate to related content.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/related-content.md)

## [📄️Social sharing](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/social-sharing.md)

[The social sharing feature adds a component to the default UI which enables viewers to share the page across media,](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/social-sharing.md)

## [📄️Up next](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/up-next.md)

[The up next feature adds a component to the default UI which enables viewers to navigate to the upcoming asset,](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/up-next.md)

## [📄️VR and 360°](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/vr.md)

[360-degree video is a type of video where every angle from a single viewpoint is recorded and can be played back.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/vr.md)

## [📄️Web Audio](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/web-audio.md)

[THEOplayer integrates with the Web Audio API,](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/web-audio.md)

## [📄️Clipping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/clipping.md)

[THEOplayer supports playing only a selected part of a video-on-demand stream, rather than playing it from start to finish.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/clipping.md)

## [📄️Picture-in-Picture](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/picture-in-picture.md)

[The Web SDK supports in-app Picture-in-Picture. Out-of-app Picture-in-Picture is not supported.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/picture-in-picture.md)

## [📄️HLS date ranges](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/hls-date-range.md)

[Enabling date ranges](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/hls-date-range.md)

## [📄️Preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/preloading.md)

[Usage](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/preloading.md)

## [📄️C2PA metadata](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/c2pa-metadata.md)

[C2PA (Coalition for Content Provenance and Authenticity) defines a standard for cryptographically signed provenance metadata,](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/c2pa-metadata.md)

## [🗃Context menu](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/context-menu/introduction.md)

[3 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/context-menu/introduction.md)

## [⚠️Error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/error/introduction.md)

[3 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/error/introduction.md)

---

# Related content on Web

The related content feature adds a component to the default UI which enables viewers to navigate to related content. You configure the related content through the related content API.

![Related content](/pr-932/assets/images/related-content-3e4e890814aa918323d0bf9fee9fb216.png "Related content")

Since it is a feature of the default UI, related content is only available on the Web SDK. Make sure your Web SDK includes the `relatedcontent` feature.

## Usage

Assign a list of related sources to [`player.related.sources`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/RelatedContent#sources), and show them whenever you want, for example when playback ends.

```js
player.related.sources = [
  {
    image: '//cdn.theoplayer.com/video/vr/poster.jpg',
    title: 'Experience true 360/VR in THEOplayer',
    duration: '2:14',
    link: '//demo.theoplayer.com/vr-and-360',
  },
  {
    image: '//cdn.theoplayer.com/video/sintel/poster.jpg',
    title: 'Optimally present your content with chapter markers',
    duration: '1:30',
    link: '//demo.theoplayer.com/chapters',
  },
  {
    image: '//cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
    title: 'THEOplayer: Advertisements Tester (VAST, VPAID, VMAP)',
    duration: '9:57',
    link: '//demo.theoplayer.com/vast-vpaid-vmap',
  },
];

player.addEventListener('ended', function () {
  if (!player.related.showing) {
    setTimeout(function () {
      player.related.show();
    }, 1000);
  }
});
```

## Remarks

The related content API is limited to showing a maximum of 15 tiles. By default, it shows only 6, even if more sources are added to the player. To show more than 6 sources, add the CSS below to make the grid scrollable.

```css
.theo-related-grid {
  height: 100% !important;
  overflow-y: scroll !important;
}

.theo-related-grid-tile {
  display: block !important;
}
```

## Resources

* [Related content API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/RelatedContent)
* [Online demo](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/related-content.md)

---

# Social sharing on Web

The social sharing feature adds a component to the default UI which enables viewers to share the page across media, for example through X (formerly Twitter) and Facebook. The social sharing API allows you to configure the URLs and (social) channels.

![Social sharing](/pr-932/assets/images/social-sharing-92115ada8662968068768f40ccf41832.png "Social sharing")

Since it is a feature of the default UI, social sharing is only available on the Web SDK. Make sure your Web SDK includes the `social` feature.

## Usage

```js
player.social.url = 'https://demo.theoplayer.com/social-sharing';
player.social.items = [
  {
    label: 'Facebook',
    icon: 'https://example.com/facebook.png',
    src: 'https://www.facebook.com/sharer/sharer.php?u=<URL>',
  },
  {
    label: 'X',
    icon: 'https://example.com/x.png',
    src: 'https://x.com/intent/tweet?url=<URL>',
  },
  {
    label: 'Reddit',
    icon: 'https://example.com/reddit.png',
    src: 'https://www.reddit.com/submit?url=<URL>',
  },
  {
    label: 'Direct link',
    src: 'https://demo.theoplayer.com/social-sharing',
  },
  {
    label: 'Embed',
    text: '<iframe width="640" height="360" src="https://demo.theoplayer.com/social-sharing" frameborder="0" allowfullscreen>\n</iframe>',
  },
];
```

## Resources

* [Social sharing API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/SocialSharing)
* [Online demo](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/social-sharing.md)

---

# Up next on Web

The up next feature adds a component to the default UI which enables viewers to navigate to the upcoming asset, and also loads this asset automatically. This can be useful if you want to increase the engagement and consumption of your users.

![Up next](/pr-932/assets/images/up-next-b95f9436365130312d8f0070857eceaa.png "Up next")

The up next feature loads new web pages (rather than just changing the video source), so it is only available on the Web SDK. Make sure your Web SDK includes the `upnext` feature.

## Usage

The snippet below demonstrates how you configure the up next API.

```js
player.upnext.source = {
  image: '//cdn.theoplayer.com/video/vr/poster.jpg',
  title: '360/VR in THEOplayer',
  duration: '2:14',
  link: '//demo.theoplayer.com/vr-and-360',
};
player.upnext.bar.offset = 106;
```

## Resources

* [Up next API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/Player#upnext)
* [Online demo](https://www.theoplayer.com/theoplayer-demo-up-next)

---

# VR and 360° video on Web

360-degree video is a type of video where every angle from a single viewpoint is recorded and can be played back. It offers a great sense of immersion for panoramic imagery or simulation purposes. The input should be a video source in an equirectangular format, and the output is a container where viewers can navigate around the scene.

Next to spherical or 360° video playback, THEOplayer also offers integration with VR devices through a stereoscopic view, dubbed "stereo mode".

VR is only available on the Web SDK. Make sure your Web SDK includes the `vr` feature.

## Initialization

The Web SDK uses the [WebXR API](https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API) for virtual reality playback. For platforms that do not natively support WebXR, you can add the [WebXR polyfill](https://github.com/immersive-web/webxr-polyfill) to your web page.

> **Bug in official polyfill**
>
> The official polyfill has a bug in its rendering, see [issue 167](https://github.com/immersive-web/webxr-polyfill/issues/167). Our team has already [proposed and submitted a fix](https://github.com/immersive-web/webxr-polyfill/pull/168), but this fix has not yet been published in a new release of the polyfill.
>
> In the meantime, you can use a patched build from our CDN. We highly recommend you to download and host this build on your own web server, since it will no longer be available once the official polyfill has been fixed.

Add the polyfill to your page:

```html
<script src="//cdn.theoplayer.com/webxr/webxr-polyfill-patched.js"></script>
```

And enable it:

```js
const POLYFILL_CONFIG = {
  allowCardboardOnDesktop: true,
};
new WebXRPolyfill(POLYFILL_CONFIG);
```

To indicate that your stream contains 360° content, pass a valid `VRConfiguration` as `vr` property when setting `player.source`.

```js
const element = document.querySelector('.theoplayer');
const player = new THEOplayer.Player(element, {
  fluid: true,
});

player.vr.useDeviceMotionControls = true;

player.source = {
  sources: {
    type: 'application/x-mpegurl',
    src: 'https://example.com/example-stream.m3u8',
  },
  vr: {
    360: true,
  },
};
```

## Manipulating the viewing direction

Below you can find an example querying the VR viewing direction and one setting the viewing direction.

```js
/* reading the current position */
const currentViewingDirection = player.vr.direction; // e.g. {pitch: 0, yaw: 0, roll: 0}

/* setting the position */
player.vr.direction = { pitch: 0, yaw: 180, roll: 0 };

/* example of how you can update only one direction property */
const newViewingDirection = player.vr.direction; /* e.g. {pitch: 0, yaw: 30, roll: 0} */
newViewingDirection.pitch = 180; /* {pitch: 180, yaw: 30, roll: 0} */
player.vr.direction = newViewingDirection;
```

## Setting the stereo mode

The snippet below enables stereo mode by setting the `stereoMode` property to `horizontal` or `vertical`.

```js
player.source = {
  sources: [
    {
      src: 'https://example.com/example-stream.m3u8',
      type: 'application/x-mpegurl',
    },
  ],
  vr: {
    360: true,
    stereoMode: 'horizontal', // or 'vertical'
  },
};
```

Note that the device must have the automatic rotation feature enabled for stereo mode to work.

## Listening to VR related events

The following code sample listens to the `stereochange` and `directionchange` events thrown by THEOplayer.

```js
player.vr.addEventListener('stereochange', () => {
  const isStereoEnabled = player.vr.stereo; // (boolean)
  // do something with it
});

player.vr.addEventListener('directionchange', () => {
  const { yaw, roll, pitch } = player.vr.direction; // (object)
  // do something with it
});
```

## Requesting permissions

Since iOS 13, access to device orientation and motion data is disabled by default. You need to request the necessary permission, triggered by a user action.

```js
function requestPermissions() {
  DeviceMotionEvent.requestPermission()
    .then((response) => {
      if (response == 'granted') {
        window.addEventListener('devicemotion', (e) => {
          console.log('Device motion permissions granted');
        });
      }
    })
    .catch(console.error);
  DeviceOrientationEvent.requestPermission()
    .then((response) => {
      if (response == 'granted') {
        window.addEventListener('deviceorientation', (e) => {
          console.log('Device orientation permissions granted');
        });
      }
    })
    .catch(console.error);
}
```

## Resources

* [VR API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VR)
* [Online demo](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/vr.md)

---

# Web Audio on Web

THEOplayer integrates with the [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API), which allows you to do some quite nifty stuff with the player's audio output. If you are unfamiliar with the ideas behind the Web Audio API, Mozilla has an excellent [introduction to the basic concepts](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API). This guide helps you set up a demo just like the one in our [demo zone](https://demo.theoplayer.com/web-audio-api).

The Web Audio API is only available on the Web SDK. Make sure your Web SDK includes the `webaudio` feature.

## A very basic Web Audio graph

The first step in working with Web Audio is to create an `AudioContext`. Once you have one, you can create an `AudioNode` which contains the player's audio output, and connect it to the context's destination.

```js
const AudioContext = window.AudioContext || window.webkitAudioContext;
const audioCtx = new AudioContext();

const sourceNode = player.audio.createAudioSourceNode(audioCtx);

// Without this connection, the player's audio is piped into the graph but not connected to any output,
// resulting in no sound from your speakers or headphones.
sourceNode.connect(audioCtx.destination);
```

## Playing with the audio gain

A first useful thing we could do is play with the gain, i.e. manipulate the player volume through the Web Audio API.

```js
const AudioContext = window.AudioContext || window.webkitAudioContext;
const audioCtx = new AudioContext();
const sourceNode = player.audio.createAudioSourceNode(audioCtx);
const gainNode = audioCtx.createGain();
sourceNode.connect(gainNode);
gainNode.connect(audioCtx.destination);
```

This sets up a gain filter on top of the player audio output, which you can manipulate using the `gainNode.gain.value` property. As an example, you could set up a callback which monitors mouse movement:

```js
document.onmousemove = function (e) {
  gainNode.gain.value = (screen.height - e.screenY) / screen.height;
};
```

The gain is adjusted to the ratio of the distance of the mouse pointer position from the bottom of the screen and the screen height. The farther you move the mouse pointer down, the quieter the output of the video becomes, and the opposite effect when you move the mouse pointer up.

## Playing with stereo panning

Similarly, you can play with the stereo panning of the player audio output through the `pan.value` property of a `StereoPanner` node.

```js
const AudioContext = window.AudioContext || window.webkitAudioContext;
const audioCtx = new AudioContext();
const sourceNode = player.audio.createAudioSourceNode(audioCtx);
const pannerNode = audioCtx.createStereoPanner();
sourceNode.connect(pannerNode);
pannerNode.connect(audioCtx.destination);

document.onmousemove = function (e) {
  pannerNode.pan.value = (2 * e.screenX) / screen.width - 1;
};
```

Moving the pointer left and right changes the stereo panning of the player audio, with balanced audio at the exact middle of the screen.

## Combining both

The Web Audio API allows you to pipe the output of one node as input for another node (in most cases). This way, you can combine the two tricks above: modifying the volume by moving the mouse pointer up and down, and modifying the panning by moving the mouse left and right.

```js
const AudioContext = window.AudioContext || window.webkitAudioContext;
const audioCtx = new AudioContext();
const sourceNode = player.audio.createAudioSourceNode(audioCtx);
const gainNode = audioCtx.createGain();
const pannerNode = audioCtx.createStereoPanner();
sourceNode.connect(pannerNode);
pannerNode.connect(gainNode);
gainNode.connect(audioCtx.destination);

document.onmousemove = function (e) {
  gainNode.gain.value = (screen.height - e.screenY) / screen.height;
  pannerNode.pan.value = (2 * e.screenX) / screen.width - 1;
};
```

## Manipulating two players at once

Assume that you have two players set up, bound to the variables `player1` and `player2`. You can set up exactly the same audio pipeline for both players, and reroute their audio to a single output.

```js
const sourceNode1 = player1.audio.createAudioSourceNode(audioCtx);
const gainNode1 = audioCtx.createGain();
const pannerNode1 = audioCtx.createStereoPanner();
sourceNode1.connect(pannerNode1);
pannerNode1.connect(gainNode1);
gainNode1.connect(audioCtx.destination);

const sourceNode2 = player2.audio.createAudioSourceNode(audioCtx);
const gainNode2 = audioCtx.createGain();
const pannerNode2 = audioCtx.createStereoPanner();
sourceNode2.connect(pannerNode2);
pannerNode2.connect(gainNode2);
gainNode2.connect(audioCtx.destination);
```

From there, you can do the inverse for the second player's audio: moving the mouse pointer up decreases the volume for the second player, and the panning is inverted as well.

```js
document.onmousemove = function (e) {
  gainNode1.gain.value = (screen.height - e.screenY) / screen.height;
  pannerNode1.pan.value = (2 * e.screenX) / screen.width - 1;
  gainNode2.gain.value = e.screenY / screen.height;
  pannerNode2.pan.value = 1 - (2 * e.screenX) / screen.width;
};
```

## Resources

* [Basic guide to the Web Audio API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/basic-guide-web-audio-api.md)
* [MDN - Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)
* [Online demo](https://demo.theoplayer.com/web-audio-api)

---

# Clipping on Web

THEOplayer supports playing only a selected part of a video-on-demand stream, rather than playing it from start to finish. This can be used for example to watch a single game-changing event from a sports match, highlight an important part of a long video presentation, or skip straight to the best part of a music video.

## Usage

The clip API helps you configure a clip within your content, through a `startTime` and an `endTime`, expressed in seconds. These properties are optional, and you don't need to specify both. For example, you can set just `startTime = 30` to have the video start at 30 seconds and play the rest of the video normally.

The following example shows a video clipped to start at 30 seconds and end at 60 seconds.

```js
player.source = {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
      type: 'application/x-mpegurl',
    },
  ],
};

// The clipping is applied in an event listener to make sure it isn't called before the source is set
player.addEventListener('durationchange', function () {
  player.clip.startTime = 30;
  player.clip.endTime = 60;
});
```

## Remarks

* The event listener in the code sample is not strictly necessary, but it ensures that the clipping is applied after the source is set. If your source has not been set, or is being set but the process is not complete, clipping does not have any effect.

## Resources

* [Clip API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Clip)
* [Frame accurate clipping in HLS](https://www.theoplayer.com/blog/frame-accurate-clipping-in-hls)

---

# Picture-in-Picture on Web

The Picture-in-Picture (PiP) feature allows you to create a floating player. This is commonly used to let the video remain playing on screen even if:

* The user scrolls to another section of the page (causing the original player to no longer be visible).
* The user sends the application to the background.
* The user opens a new page within the same application.

THEOplayer distinguishes two flavors of Picture-in-Picture:

* With **in-app** Picture-in-Picture, the visibility of the PiP window is contained to the inside of the app. In other words, it goes to background and foreground together with the application.
* With **out-of-app** Picture-in-Picture, the visibility of the PiP window is not contained to the inside of the app. It can remain visible while the user navigates to other views, pages or apps.

Picture-in-Picture is a presentation mode of the player. As such, you can listen for a `presentationmodechange` event, or read the player's presentation mode, to find out what the presentation mode is at a given moment or to detect a change.

The Web SDK supports in-app Picture-in-Picture. Out-of-app Picture-in-Picture is not supported.

## Usage

Picture-in-Picture is enabled as soon as the player configuration contains a `pip` configuration, so there is no need for any additional code to enable it.

![Picture-in-Picture](/pr-932/assets/images/picture-in-picture-778462f302e24a4b44a176d0fa345cd1.png "Picture-in-Picture")

The PiP configuration has three properties:

* `position`: (optional, possible values: `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"`)<br />The corner in which the player should be shown while in PiP mode. Defaults to the bottom right corner.

* `visibility`: (optional, a number from 0 to 1)<br />The maximum percentage of the original player position that should be visible to enable PiP automatically. If not configured, PiP can only be turned on by setting [presentationMode](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/PresentationMode) to `"picture-in-picture"`.

* `retainPresentationModeOnSourceChange`: (optional, `true` or `false`)<br />If set to `true`, the previous [presentationMode](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/PresentationMode) is retained even as the source changes. It is set to `false` by default.

```js
const playerConfig = {
  /* ... */
  pip: {
    visibility: 0.7,
    position: 'bottom-left',
    retainPresentationModeOnSourceChange: true,
  },
};
```

## Remarks

* Support for native Picture-in-Picture (i.e. where the player is draggable) is experimental. While support is widely adopted, the feature is most notably not supported by Firefox.

## Resources

* [PiPConfiguration API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PiPConfiguration)
* [PlayerConfiguration API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerConfiguration)
* [PresentationMode API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/PresentationMode)
* [Online demo](https://demo.theoplayer.com/picture-in-picture): start the video and scroll down on the page to see PiP in action.

---

# HLS date ranges on Web

The `#EXT-X-DATERANGE` tag associates a date range (i.e. a range of time defined by a starting and ending date) with a set of attribute/value pairs. It is a way of providing timed metadata in an HLS manifest. A possible use case is defining timed metadata for interstitial regions such as advertisements, but it can be used for any timed metadata needed by your stream.

Date ranges are not parsed by default. To enable them, set `hlsDateRange` to `true`, either on the player configuration (for all sources) or on an individual source.

Once enabled, the player exposes the date ranges as cues on a metadata text track, which you can consume through the text tracks API.

## Enabling date ranges

```js
// in the player configuration
const element = document.querySelector('.theoplayer-container');

const player = new THEOplayer.Player(element, {
  libraryLocation: libraryLocation,
  license: 'your-license-here',
  hlsDateRange: true,
});

// or in the source description
player.source = {
  sources: {
    src: 'https://example.com/example-stream.m3u8',
    type: 'application/x-mpegurl',
    hlsDateRange: true,
  },
};
```

## Reading date range cues

Date ranges are exposed as cues on a metadata text track. Listen for the metadata track being added, and for its cues, to interact with the date range attributes.

```js
player.textTracks.addEventListener('addtrack', (event) => {
  const track = event.track;
  if (track.kind !== 'metadata') {
    return;
  }
  // By default, metadata tracks are disabled and do not expose cues
  track.mode = 'hidden';
  track.addEventListener('entercue', (enterCueEvent) => {
    console.log('Date range started', enterCueEvent.cue.content);
  });
  track.addEventListener('exitcue', (exitCueEvent) => {
    console.log('Date range ended', exitCueEvent.cue.content);
  });
});
```

See "[How to detect active text track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-active-text-track-cues.md)" for more information.

## Resources

* [HLS specification: EXT-X-DATERANGE](https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.2.7)

---

# Preloading on Web

The aim of preloading is to improve the user experience by loading parts of the video before the play button is hit, when the user is likely to play the video.

Choosing to preload your video content reduces the start-up time of your videos. It also makes some data regarding the current source (video duration, timeline thumbnails, etc.) available before the user initiates playback. On the other hand, when the video is less likely to be played, or when it is less beneficial (live video, autoplay), you can configure the player to not preload it and save bandwidth.

## Preloading settings

| Value      | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none`     | Do not preload anything. After setting the source, the player does not load the manifest nor any media files until the play method is invoked on the player.                                                                                                                                                                                                                           |
| `metadata` | Preload the metadata of the video. After setting the source, the player automatically loads the manifest file and waits for loading media files until the play method is invoked on the player. For static videos (e.g. MP4 files), this translates to preloading data from the start of the video in order to acquire e.g. the video's width and height and the initial video frames. |
| `auto`     | Preload enough data to allow for smooth initial playback. After setting the source, the player loads both the manifest files and enough media files until a sufficient playback buffer has been obtained.                                                                                                                                                                              |

## Usage

In this example, we are preloading metadata only.

```js
player.preload = 'metadata';
```

## Remarks

* THEOplayer always prefers downloading data for the currently playing video over downloading data for a preloading video. Only when the currently playing video has enough data to play to the end of the video, does the player start preloading other videos.
* When preloading the first segment(s) (preload `auto`), the first frame of the video is shown under the big play button, if there is no poster.

## Resources

* [What are the benefits of preloading?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-are-the-benefits-of-preloading.md)
* [PreloadType API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/PreloadType)
* [HTML specification](https://html.spec.whatwg.org/multipage/media.html#attr-media-preload)
* [Online demo](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/preload.md)

---

# C2PA metadata on Web

[C2PA](https://c2pa.org/) (Coalition for Content Provenance and Authenticity) defines a standard for cryptographically signed provenance metadata, allowing viewers to verify the origin and integrity of media content. Live streams signed according to the [C2PA specification](https://spec.c2pa.org/) carry this metadata inside the stream itself:

* **ISOBMFF `uuid` boxes** (usertype `d8fec3d6-1b0e-483c-9297-5828877ec481`) in fMP4/CMAF segments:

  * the initialization segment carries the C2PA manifest store (purpose `manifest`),
  * each media segment can carry per-segment integrity data such as Merkle tree data (purpose `merkle`).

* **`emsg` (event message) boxes** in media segments, carrying timed metadata.

THEOplayer exposes this metadata to your application for both HLS and MPEG-DASH streams, so you can validate it with a C2PA-compatible library of your choice.

> **Note**
>
> THEOplayer does **not** validate C2PA signatures, evaluate trust lists, or make any trust decisions. It only exposes the raw metadata to your application.

> **Note**
>
> C2PA `uuid` box extraction is only available for fMP4/CMAF content played through THEOplayer's own HLS and MPEG-DASH pipelines (using Media Source Extensions). No `c2pametadata` events are dispatched for native HLS playback (e.g. on Safari with `useNativePlayback`), MPEG-TS content, or HESP/THEOlive streams.

## Enabling C2PA metadata extraction

C2PA `uuid` box extraction is disabled by default and must be enabled per source with the `c2paMetadata` source property. C2PA presence is not advertised in the HLS or DASH manifest, so the player cannot detect it up front — enable it explicitly when you intend to validate the stream:

```js
player.source = {
  sources: [
    {
      src: 'https://example.com/signed-stream/master.m3u8',
      c2paMetadata: true,
    },
  ],
};
```

## Listening for C2PA `uuid` box metadata

Whenever the player appends a segment containing a C2PA `uuid` box, it fires a `c2pametadata` event with the raw box contents:

```js
player.addEventListener('c2pametadata', (event) => {
  console.log(event.purpose); // 'manifest' (initialization segment) or 'merkle' (media segment)
  console.log(event.segmentType); // 'initialization' or 'media'
  console.log(event.mediaType); // 'video' or 'audio': the type of media track in which the box was found
  console.log(event.startTime, event.endTime); // segment time range, or undefined for initialization segments
  console.log(event.data); // Uint8Array with the raw box payload (e.g. a JUMBF-serialized C2PA manifest store)

  // Forward the raw data to a C2PA-compatible validation library of your choice.
  myC2paValidator.addSegmentData(event.purpose, event.data);
});
```

For initialization segments, `startTime` and `endTime` are `undefined`. For media segments, the segment's time range is available in `startTime` and `endTime`.

When audio and video are carried in separate tracks, each track is a separate C2PA-signed stream with its own manifest and Merkle data. Use `event.mediaType` to associate each event with the correct track, for example to validate the audio and video streams independently.

The player dispatches every C2PA `uuid` box it encounters, without deduplication. Your application may receive events with identical contents more than once, for example when the same initialization segment is buffered again after a quality switch or a seek. Deduplicate in your application if needed.

## Listening for C2PA `emsg` metadata

Timed C2PA metadata carried in `emsg` boxes is exposed through the player's generic [metadata text track](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-active-text-track-cues.md) support. The player creates a metadata text track of type `emsg`, and each `emsg` box becomes a cue with the raw message data as its content:

```js
player.textTracks.addEventListener('addtrack', (event) => {
  const track = event.track;
  if (track.kind === 'metadata' && track.type === 'emsg') {
    track.mode = 'hidden';
    track.addEventListener('addcue', (event) => {
      const cue = event.cue;
      console.log(cue.schemeIDURI); // e.g. 'https://c2pa.org/streaming'
      console.log(cue.startTime, cue.endTime);
      console.log(cue.content); // Uint8Array with the raw emsg message data
    });
  }
});
```

## Validating the metadata

The exposed data is the raw, unmodified payload from the stream. To verify the provenance of the content, pass it to a C2PA-compatible library (for example, [c2pa-js](https://github.com/contentauth/c2pa-js)) together with the downloaded segment data, and apply your own trust policy to the validation result.

---

# Context menu on Web

The default UI of the Web SDK shows a THEOplayer context menu when the viewer right-clicks the player. This section explains how to change or remove it.

* [How to disable the right click](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/context-menu/disable-right-click.md)
* [How to change the context menu](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/context-menu/change-context-menu.md)

---

# How to disable the right click on Web

There are two ways to disable the right-click menu on the player.

## Disable the context menu feature

By default, the `contextmenu` feature is included in the Web SDK. If you build your SDK with this feature disabled, your player does not have a context menu.

## Add a CSS rule to your page

If you do not want to rebuild your player, you can add the following CSS rule after including THEOplayer's `ui.css`. You can add this rule in a `<style>` element (see below) or in an external stylesheet.

```html
<link rel="stylesheet" type="text/css" href="/path/to/ui.css" />

<style>
  .theo-context-menu {
    display: none;
  }
</style>
```

---

# How to change the context menu on Web

You may want to change the logo in the context menu, change the default text, or add some items. The snippet below does exactly that.

```js
function customizeContextMenu(container) {
  const contextMenu = container.querySelector('.theo-context-menu');

  // change context menu text
  const contextMenuFirstItem = contextMenu.querySelector('.theo-context-version');
  contextMenuFirstItem.innerText = 'Brand X';

  // change mini logo
  const contextLogo = contextMenu.querySelector('.theo-0logo');
  contextLogo.style.backgroundImage = "url('https://example.com/logo.png')";
  contextLogo.style.backgroundSize = 'cover';
  contextLogo.querySelector('svg').style.visibility = 'hidden';

  // add a line
  const contextMenuSecondItem = document.createElement('li');
  contextMenuSecondItem.innerText = '24/07/2018';
  contextMenu.appendChild(contextMenuSecondItem);
}

const element = document.querySelector('.video-container');
const player = new THEOplayer.Player(element, playerConfig);
customizeContextMenu(element);
```

Note that `customizeContextMenu` is called immediately after initializing a THEOplayer instance.

The context menu can also be removed altogether, since it is one of the feature flags you can toggle when building your Web SDK. To verify whether the feature is enabled, you can execute the query below.

```js
const contextMenuEnabled = THEOplayer.features.indexOf('contextmenu') > -1;
```

## Related articles

* [How to disable the right click](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/context-menu/disable-right-click.md)

---

# Errors on Web

We live in an imperfect world, and sometimes things go wrong. A viewer might not be able to watch a video stream for a variety of reasons. Some example reasons are:

* The video stream is unavailable,
* The video stream is not supported on the selected platform,
* The THEOplayer license is incorrectly configured.

**When an issue occurs, an error should be triggered**.

When a fatal playback issue occurs, THEOplayer exposes information about the error through the THEOplayer API. This allows you to detect errors: as a developer, you can use an event handler to catch (and handle) `error` events. This feature (i.e. being able to intercept errors and act on it) may be mandatory to you to achieve a use-case:

* You want to log the error on an analytics stack,
* You want to show your own error message to the viewer,
* ...

THEOplayer associates error codes with errors to categorize types of issues. As a developer, these error codes may help you to log an error on an analytics stack, or may help you to generate a custom error message towards your viewer.

When a fatal playback issue occurs, THEOplayer's default UI overlays an error message on top of the video player. This error message indicates to the viewer that playback is unsuccessful.

## Related resources

* [How to do error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/error/error-handling.md): this article explains how you use event listeners to intercept the `error` event.
* [Error codes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/error/error-codes.md): this article explains what error codes are, and why they are useful.

---

# How to do error handling on Web

As a developer, you could be interested in error handling for any of the following reasons:

* You want to render human-friendly error messages inside the video player. Reading this error message,

  * the user can either remediate the issue by themselves (e.g. by refreshing the page, by checking again in some time, ...),
  * or contact a support service with this error code.

* You want to send error-data to an analytics service. (And this service helps you to identify frequent issues.)

* You want to self-remediate the issue. For example, if a stream is unavailable, you want to retry to load the stream, or load a different stream.

* ...

THEOplayer exposes different types of errors, and you can interact with them in two ways:

1. Through an event listener, and attaching an event handler to this listener.
2. Through a getter, which holds data when an error has occurred.

The sections below describe the "top-level", "generic", "player" `error` event. This event is fatal and prevents playback. There are also other `error` events, for example the one dispatched by the Chromecast API. You handle those `error` events in the same fashion.

## Event listener

Subscribe to the [`error`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#error) event of the player, and attach a callback function which implements the error handling.

```js
player.addEventListener('error', function (errorEvent) {
  console.log(errorEvent.errorObject);
});
```

Other interfaces dispatch their own `error` event, for example the [`error`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ChromecastEventMap#error) event of the Chromecast API. You handle those in the same fashion.

## Getter

You can query an occurred "generic player error" through the [`errorObject`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#errorObject) property of the player.

```js
player.addEventListener('error', function () {
  console.log(player.errorObject);
});
```

Note that other types of errors are not available through this approach.

## Types of errors

"[Which error related events does the player expose](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/which-error-related-events-does-player-expose.md)" lists which types of errors there are. Note that generally speaking only the "generic error event" is fatal. Other events, like the "Chromecast error event" and the "ad error event", are considered non-fatal because some type of playback can still continue.

"[Error codes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/error/error-codes.md)" lists which error codes are available for the "generic error event".

## Remarks

* We encourage you to use event listeners to handle errors. The data in this event can be processed (e.g. stringified) and transferred (e.g. sent to an analytics service).
* You could render your own error messages inside the video player. The demo at <http://demo.theoplayer.com/using-custom-error-messages> offers some help on this.

---

# Error codes on Web

THEOplayer has different types of error events. One of those error events is the "generic player error event". This error event indicates a fatal error, and can be intercepted through the player.

This error event exposes an "error code" to explain the occurred error. An error code may be more interesting to track than a verbose error message. For example, if you are logging errors through an analytics service, it could be useful to filter them by their error code.

An error code is a number (e.g. 2001), and it belongs to a category. The format of an error code is "\[category]\[sub-code]". For example, error "2001" belongs to category 2, and has sub-code 001. If the error is a generic sub-code for its category, then the sub-code is `000`. In other words, error `11000` is the "catch-all" for category `11`.

## Categories

Each error code belongs to an error category. At the time of writing, there are 11 categories.

1. Configuration error: the integrator misconfigured the player.
2. License error: the player license is no longer valid, incorrect or not provided.
3. Source invalid: the source is not valid, or cannot be played on the current platform.
4. Manifest load error: the manifest cannot be loaded or parsed.
5. Media not supported: the media cannot be played on the current platform.
6. Network error: the network timed out, or is not available.
7. Content protection error: anything DRM related. Key system is not supported, invalid license, license expired, key missing, output restricted...
8. Subtitle load error: the subtitles cannot be loaded or parsed...
9. VR not supported: VR is not available on the current platform, VR presentation cannot be switched.
10. Ad blocker detected: an ad has been blocked (or the third party CSAI library was not loaded).
11. Fullscreen error: switching to fullscreen is not possible (note: this may be the case when fullscreen was not triggered by user interaction).

Refer to "[How to do error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/error/error-handling.md)" to learn how to detect the "generic player error event".

## Requesting categories and codes

You can programmatically request the list of available error categories through `THEOplayer.ErrorCategory`, as illustrated by the screenshot below.

![ErrorCategory](/pr-932/assets/images/error-code-ErrorCategory-6f53a43777395769d34029b30d5ecade.png "ErrorCategory")

You can also request the category of an error code through `THEOplayer.ErrorCategory.fromCode(<errorCode>)`. Meaning: `THEOplayer.ErrorCategory.fromCode(11000)` returns `11`.

Similarly, you can request the list of all available error codes through `THEOplayer.ErrorCode`, as illustrated by the screenshot below.

![ErrorCode](/pr-932/assets/images/error-code-ErrorCode-198ffee2db62e071b0f3be03b5e2d95d.png "ErrorCode")

## API references

* [`ErrorCategory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/enums/ErrorCategory)
* [`ErrorCategory.fromCode()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/functions/ErrorCategory.fromCode)
* [`ErrorCode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/enums/ErrorCode)

---

# Network on Web

THEOplayer makes a number of network requests, and receives responses, while it is loading and playing a stream. The Network API allows you to intercept those requests and responses, so you can inspect them, modify them, redirect them, or respond with your own data.

Common use cases are adding authentication headers or query parameters to segment requests, redirecting requests to another CDN, or rewriting a manifest before the player parses it.

The Web SDK exposes this API through [`player.network`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Network).

On iOS and iPadOS browsers, the Network API can only be used to intercept and alter DRM-related requests and responses.

## Detecting a lost connection

To detect that the player lost its connection, listen for the [`manifesterror`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#manifesterror) and [`segmenterror`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#segmenterror) events, which are dispatched when the player fails to load the manifest or a segment. The [`manifestupdate`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#manifestupdate) event indicates that the player successfully loaded the manifest again, so the connection is back:

```js
player.addEventListener('manifesterror', handleConnectionLost);
player.addEventListener('segmenterror', handleConnectionLost);
player.addEventListener('manifestupdate', handleConnectionRestored);
```

Event listeners can be removed similarly:

```js
player.removeEventListener('manifesterror', handleConnectionLost);
```

## Related articles

* [How to add and remove request and response interceptors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/network/request-response-interceptors.md)
* [Why does the Network API not work on iOS devices?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-does-network-api-not-work-on-ios-devices.md)

---

# How to add and remove request and response interceptors on Web

A *request interceptor* runs before the player opens the connection, so it can change properties of the request such as its URL, method, headers or body. It can also respond to the request immediately, without contacting the server.

A *response interceptor* runs before the player consumes the response, so it can change the status, the headers or the body of the response.

Interceptors are kept in a stack: the interceptor which was added last is the first one to intercept.

## Prerequisites

This guide assumes that you already have a THEOplayer instance in your page. If not, start with our [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md).

## Adding and removing request interceptors

A [`RequestInterceptor`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/RequestInterceptor) receives the intercepted request, and can modify it with the [`redirect`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/InterceptableRequest#redirect) or [`respondWith`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/InterceptableRequest#respondWith) method.

```js
const interceptor = (request) => {
  if (request.type === 'manifest') {
    request.redirect({
      url: 'https://cdn.theoplayer.com/video/elephants-dream/448/chunklist_w370587926_b688000_vo_slen_t64TWFpbg==.m3u8',
      method: 'GET',
      headers: {
        'Content-Type': 'application/x-mpegurl',
      },
    });
  }
};
```

The code sample above intercepts manifest requests made by the player, and redirects them to the given URL. If properties of the given [`RequestInit`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/RequestInit) object are missing, the API uses the values of the original request.

Instead of redirecting the request, you can also respond to it yourself:

```js
const interceptor = (request) => {
  if (request.type === 'manifest') {
    request.respondWith({
      body: '#EXTM3U\n#EXTINF:6,\nhttps://cdn.theoplayer.com/video/elephants-dream/448/media_w370587926_b688000_vo_slen_t64TWFpbg==_0.ts\n#EXT-X-ENDLIST',
      status: 200,
      statusText: 'OK',
    });
  }
};
```

The code sample above intercepts manifest requests made by the player, and responds with a manifest which contains a single segment.

Add the interceptor to the player as follows:

```js
player.network.addRequestInterceptor(interceptor);
```

Interceptors can be removed similarly:

```js
player.network.removeRequestInterceptor(interceptor);
```

## Adding and removing response interceptors

A [`ResponseInterceptor`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/ResponseInterceptor) receives the intercepted response, and can modify it with the [`respondWith`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/InterceptableResponse#respondWith) method, which accepts a [`ResponseInit`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ResponseInit) object.

```js
const interceptor = (response) => {
  response.respondWith({
    body: '#EXTM3U\n#EXTINF:6,\nhttps://cdn.theoplayer.com/video/elephants-dream/448/media_w370587926_b688000_vo_slen_t64TWFpbg==_0.ts\n#EXT-X-ENDLIST',
    status: 200,
    statusText: 'OK',
  });
};
```

The code sample above intercepts responses received by the player, and responds with a manifest which contains a single segment.

Add the interceptor to the player as follows:

```js
player.network.addResponseInterceptor(interceptor);
```

Interceptors can be removed similarly:

```js
player.network.removeResponseInterceptor(interceptor);
```

## Waiting for asynchronous work

The `waitUntil` method allows you to run asynchronous work before the request or the response is closed. It throws an error if the request or the response was already closed by the same interceptor.

It accepts a done callback, a function which returns a promise, or a promise.

### Done callback

When you pass a done callback, the request or the response is only closed once you call `done`. Failing to call it means that the request or the response is never delivered.

```js
const interceptor = (request) => {
  request.waitUntil((done) => {
    setTimeout(() => {
      request.redirect({
        url: 'https://cdn.theoplayer.com/video/elephants-dream/448/chunklist_w370587926_b688000_vo_slen_t64TWFpbg==.m3u8',
        method: 'GET',
        headers: modifyRequestHeaders(request.headers),
      });
      done();
    }, 100);
  });
};
```

The code sample above waits for 100 milliseconds, redirects to another URL, and then closes the request.

### Function which returns a promise

When you pass a function which returns a promise, the request or the response is only closed once that promise resolves.

```js
const interceptor = (request) => {
  request.waitUntil(() =>
    delay(100).then(() => {
      request.redirect({
        url: 'https://cdn.theoplayer.com/video/elephants-dream/448/chunklist_w370587926_b688000_vo_slen_t64TWFpbg==.m3u8',
        method: 'GET',
        headers: modifyRequestHeaders(request.headers),
      });
    })
  );
};
```

### Promise

You can also pass a promise directly. The request or the response is closed once that promise resolves.

```js
const interceptor = (request) => {
  const promise = delay(100).then(() => {
    request.redirect({
      url: 'https://cdn.theoplayer.com/video/elephants-dream/448/chunklist_w370587926_b688000_vo_slen_t64TWFpbg==.m3u8',
      method: 'GET',
      headers: modifyRequestHeaders(request.headers),
    });
  });
  request.waitUntil(promise);
};
```

## HTTP errors

If the status code is set to a code between 200 and 299, the player treats the response as successful. In any other case, the player reports an HTTP error.

An interceptor can turn an HTTP error into a successful response, and vice versa.

## Related articles

* [Network introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/network/introduction.md)
* [Why does the Network API not work on iOS devices?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-does-network-api-not-work-on-ios-devices.md)

---

# Player on Web

The Player API is the top-level API. This API exposes:

* basic functions to manipulate video playback, such as start and pause;
* properties to check states and values, such as the playhead position;
* events to track changes.

## Events

As a developer, you can programmatically attach event listeners to different APIs. Event listeners are often used to implement a custom UI, or to implement a custom analytics integration.

The THEOplayer API exposes many events across different interfaces, as can be seen in the graphic below. Furthermore, most events exist in all SDKs (Web, iOS-based, Android-based and Roku).

![THEOplayer API Interfaces and Events](/pr-932/assets/images/analytics-events-185d6ab52b556af08d8300b545ae5876.png "THEOplayer API Interfaces and Events")

On Web, event listeners are for example used to [build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md), or to [implement a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/custom-analytics-integration.md).

The table below gives an overview of a subset of the available events per interface in the THEOplayer Web SDK.

| Interface                                                                                                                                    | Event                                                                                                                                                            | Description                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| [Player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap)                          | [canplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#canplay)                                     | Fired when the player can resume playback of the media data.                                                                                  |
| Player                                                                                                                                       | [canplaythrough](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#canplaythrough)                       | Fired when the player can resume playback of the media data and buffering is unlikely.                                                        |
| Player                                                                                                                                       | [contentprotectionerror](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#contentprotectionerror)       | Fired when an error related to content protection occurs.                                                                                     |
| Player                                                                                                                                       | [contentprotectionsuccess](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#contentprotectionsuccess)   | Fired when the key is usable for decryption.                                                                                                  |
| Player                                                                                                                                       | [currentsourcechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#currentsourcechange)             | Fired when the current source, which is chosen from ChromelessPlayer.source.sources, changes.                                                 |
| Player                                                                                                                                       | [destroy](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#destroy)                                     | Fired when the the player is destroyed.                                                                                                       |
| Player                                                                                                                                       | [dimensionchange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#dimensionchange)                     | Fired when the dimensions of the HTML element changes.                                                                                        |
| Player                                                                                                                                       | [durationchange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#durationchange)                       | Fired when ChromelessPlayer.duration changes.                                                                                                 |
| Player                                                                                                                                       | [emptied](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#emptied)                                     | Fired when the player's source is cleared.                                                                                                    |
| Player                                                                                                                                       | [encrypted](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#encrypted)                                 | Fired when the player encounters key system initialization data in the media data.                                                            |
| Player                                                                                                                                       | [ended](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#ended)                                         | Fired when playback has stopped because the end of the media resource was reached.                                                            |
| Player                                                                                                                                       | [error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#error)                                         | Fired when an error occurs.                                                                                                                   |
| Player                                                                                                                                       | [loadeddata](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#loadeddata)                               | Fired when the player can render the media data at the current playback position for the first time.                                          |
| Player                                                                                                                                       | [loadedmetadata](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#loadedmetadata)                       | Fired when the player determines the duration and dimensions of the media resource.                                                           |
| Player                                                                                                                                       | [loadstart](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#loadstart)                                 | Fired when the player starts loading the manifest.                                                                                            |
| Player                                                                                                                                       | [manifestupdate](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#manifestupdate)                       | Fired when the manifest is updated.                                                                                                           |
| Player                                                                                                                                       | [pause](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#pause)                                         | Fired when ChromelessPlayer.paused changes to true.                                                                                           |
| Player                                                                                                                                       | [play](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#play)                                           | Fired when ChromelessPlayer.paused changes to false.                                                                                          |
| Player                                                                                                                                       | [playing](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#playing)                                     | Fired when playback is ready to start after having been paused or delayed due to lack of media data.                                          |
| Player                                                                                                                                       | [progress](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#progress)                                   | Fired when the player loaded media data.                                                                                                      |
| Player                                                                                                                                       | [ratechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#ratechange)                               | Fired when ChromelessPlayer.playbackRate changes.                                                                                             |
| Player                                                                                                                                       | [readystatechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#readystatechange)                   | Fired when ChromelessPlayer.readyState changes.                                                                                               |
| Player                                                                                                                                       | [representationchange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#representationchange)           | Fired when the current representation changes.                                                                                                |
| Player                                                                                                                                       | [resize](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#resize)                                       | Fired when either ChromelessPlayer.videoWidth or ChromelessPlayer.videoHeight changes.                                                        |
| Player                                                                                                                                       | [seeked](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#seeked)                                       | Fired when ChromelessPlayer.seeking changes to false after the current playback position was changed.                                         |
| Player                                                                                                                                       | [seeking](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#seeking)                                     | Fired when ChromelessPlayer.seeking changes to true, and the player has started seeking to a new position.                                    |
| Player                                                                                                                                       | [segmentnotfound](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#segmentnotfound)                     | Fired when a segment can not be found.                                                                                                        |
| Player                                                                                                                                       | [sourcechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#sourcechange)                           | Fired when ChromelessPlayer.source changes.                                                                                                   |
| Player                                                                                                                                       | [timeupdate](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#timeupdate)                               | Fired when the current playback position changed as part of normal playback or in an especially interesting way, for example discontinuously. |
| Player                                                                                                                                       | [volumechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#volumechange)                           | Fired when ChromelessPlayer.volume changes.                                                                                                   |
| Player                                                                                                                                       | [waiting](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#waiting)                                     | Fired when playback has stopped because the next frame is not available, but the player expects that frame to become available in due course. |
| Player                                                                                                                                       | [currentTime](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#currenttime)                              | The current playback position of the media, in seconds.                                                                                       |
| Player                                                                                                                                       | [currentProgramDateTime](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#currentprogramdatetime)        | The current playback position of the media, as a timestamp.                                                                                   |
| Player                                                                                                                                       | [muted](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#muted)                                          | Whether audio is muted.                                                                                                                       |
| Player                                                                                                                                       | [...](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer)                                                  | ...                                                                                                                                           |
| [Ads (Client-Side)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap)                  | [adbegin](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#adbegin)                                        | Fired when an ad begins.                                                                                                                      |
| Ads (Client-Side)                                                                                                                            | [adbreakbegin](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#adbreakbegin)                              | Fired when an ad break begins.                                                                                                                |
| Ads (Client-Side)                                                                                                                            | [adbreakchange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#adbreakchange)                            | Fired when an ad break changes.                                                                                                               |
| Ads (Client-Side)                                                                                                                            | [adbreakend](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#adbreakend)                                  | Fired when an ad break ends.                                                                                                                  |
| Ads (Client-Side)                                                                                                                            | [adbuffering](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#adbuffering)                                | Fired when the ad has stalled playback to buffer.                                                                                             |
| Ads (Client-Side)                                                                                                                            | [addad](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#addad)                                            | Fired when an ad is added.                                                                                                                    |
| Ads (Client-Side)                                                                                                                            | [addadbreak](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#addadbreak)                                  | Fired when an ad break is added.                                                                                                              |
| Ads (Client-Side)                                                                                                                            | [adend](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#adend)                                            | Fired when an ad ends.                                                                                                                        |
| Ads (Client-Side)                                                                                                                            | [aderror](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#aderror)                                        | Fired when an ad errors.                                                                                                                      |
| Ads (Client-Side)                                                                                                                            | [adfirstquartile](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#adfirstquartile)                        | Fired when an ad reaches the first quartile.                                                                                                  |
| Ads (Client-Side)                                                                                                                            | [adimpression](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#adimpression)                              | Fired when an ad counts as an impression.                                                                                                     |
| Ads (Client-Side)                                                                                                                            | [adloaded](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#adloaded)                                      | Fired when an ad is loaded.                                                                                                                   |
| Ads (Client-Side)                                                                                                                            | [admetadata](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#admetadata)                                  | Fired when an ads list is loaded.                                                                                                             |
| Ads (Client-Side)                                                                                                                            | [admidpoint](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#admidpoint)                                  | Fired when an ad reaches the mid point.                                                                                                       |
| Ads (Client-Side)                                                                                                                            | [adskip](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#adskip)                                          | Fired when an ad is skipped.                                                                                                                  |
| Ads (Client-Side)                                                                                                                            | [adthirdquartile](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#adthirdquartile)                        | Fired when an ad reaches the third quartile.                                                                                                  |
| Ads (Client-Side)                                                                                                                            | [removeadbreak](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#removeadbreak)                            | Fired when an ad break is removed.                                                                                                            |
| Ads (Client-Side)                                                                                                                            | [updatead](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#updatead)                                      | Fired when an ad is updated.                                                                                                                  |
| Ads (Client-Side)                                                                                                                            | [updateadbreak](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsEventMap#updateadbreak)                            | Fired when an AdBreak is updated.                                                                                                             |
| [Vendor Cast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VendorCastEventMap)                 | [statechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VendorCastEventMap#statechange)                         | Fired when the state changes.                                                                                                                 |
| [Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ChromecastEventMap)                  | [error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ChromecastEventMap#error)                                     | Fired when an error occurs while casting or trying to cast.                                                                                   |
| [Track List](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap)                   | [addtrack](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap#addtrack)                                | Fired when a track is added.                                                                                                                  |
| Track List                                                                                                                                   | [change](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap#change)                                    | Fired when a track is activated or deactivated.                                                                                               |
| Track List                                                                                                                                   | [removetrack](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap#removetrack)                          | Fired when a track is removed.                                                                                                                |
| [Track](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackEventMap)                            | [change](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackEventMap#change)                                        | Fired when a media track's enabled or a text track's changes.                                                                                 |
| Track                                                                                                                                        | [update](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackEventMap#update)                                        | Fired when the track updates.                                                                                                                 |
| [Media Track](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrackEventMap)                 | [activequalitychanged](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrackEventMap#activequalitychanged)       | Fired when the media track's active quality changes.                                                                                          |
| Media Track                                                                                                                                  | [qualityunavailable](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrackEventMap#qualityunavailable)           | Fired when a quality of the track becomes unavailable.                                                                                        |
| Media Track                                                                                                                                  | [targetqualitychanged](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrackEventMap#targetqualitychanged)       | Fired when the media track's target quality changes.                                                                                          |
| [Text Track](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap)                   | [addcue](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap#addcue)                                    | Fired when a cue is added to the track.                                                                                                       |
| Text Track                                                                                                                                   | [cuechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap#cuechange)                              | Fired when a cue of the track changes.                                                                                                        |
| Text Track                                                                                                                                   | [entercue](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap#entercue)                                | Fired when a cue of the track enters.                                                                                                         |
| Text Track                                                                                                                                   | [error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap#error)                                      | Fired when an error occurred while loading or parsing the track.                                                                              |
| Text Track                                                                                                                                   | [exitcue](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap#exitcue)                                  | Fired when a cue of the track exits.                                                                                                          |
| Text Track                                                                                                                                   | [readystatechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap#readystatechange)                | Fired when the text track's changes.                                                                                                          |
| Text Track                                                                                                                                   | [removecue](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap#removecue)                              | Fired when a cue of the track is removed.                                                                                                     |
| Text Track                                                                                                                                   | [typechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap#typechange)                            | Fired when the text track's changes.                                                                                                          |
| [Text Track Cue](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackCueEventMap)            | [enter](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackCueEventMap#enter)                                   | Fired when the cue is entered.                                                                                                                |
| Text Track Cue                                                                                                                               | [exit](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackCueEventMap#exit)                                     | Fired when the cue is exited.                                                                                                                 |
| Text Track Cue                                                                                                                               | [update](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackCueEventMap#update)                                 | Fired when the cue is updated.                                                                                                                |
| [Presentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PresentationEventMap)              | [error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PresentationEventMap#error)                                   | Fired when an error occurs.                                                                                                                   |
| Presentation                                                                                                                                 | [presentationmodechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PresentationEventMap#presentationmodechange) | Fired when the presentation mode changes.                                                                                                     |
| [VR](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VREventMap)                                  | [directionchange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VREventMap#directionchange)                         | Fired when the VR.direction changes.                                                                                                          |
| VR                                                                                                                                           | [error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VREventMap#error)                                             | Fired when an error occurs.                                                                                                                   |
| VR                                                                                                                                           | [statechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VREventMap#statechange)                                 | Fired when the VR.state changes.                                                                                                              |
| VR                                                                                                                                           | [stereochange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VREventMap#stereochange)                               | Fired when the VR.stereo changes.                                                                                                             |
| [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkEventMap)                          | [assetinforesponse](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkEventMap#assetinforesponse)                 | Fired when an asset info response is received.                                                                                                |
| Uplynk                                                                                                                                       | [pingerror](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkEventMap#pingerror)                                 | Fired when an error or invalid response is received from the Ping API.                                                                        |
| Uplynk                                                                                                                                       | [pingresponse](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkEventMap#pingresponse)                           | Fired when a Ping response is received.                                                                                                       |
| Uplynk                                                                                                                                       | [preplayresponse](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkEventMap#preplayresponse)                     | Fired when a Preplay response is received.                                                                                                    |
| Uplynk                                                                                                                                       | [ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Uplynk#ads)                                                     | The Uplynk SSAI API.                                                                                                                          |
| Uplynk                                                                                                                                       | [assets](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Uplynk#assets)                                               | List of Uplynk assets.                                                                                                                        |
| [Uplynk Ad Break List](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdBreakListEventMap) | [addadbreak](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdBreakListEventMap#addadbreak)                    | Fired when the ad break is added.                                                                                                             |
| Uplynk Ad Break List                                                                                                                         | [removeadbreak](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdBreakListEventMap#removeadbreak)              | Fired when the ad break is removed.                                                                                                           |
| [Uplynk Ad Break](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdBreakEventMap)          | [adbreakbegin](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdBreakEventMap#adbreakbegin)                    | Fired when the ad break begins.                                                                                                               |
| Uplynk Ad Break                                                                                                                              | [adbreakend](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdBreakEventMap#adbreakend)                        | Fired when the ad break ends.                                                                                                                 |
| Uplynk Ad Break                                                                                                                              | [adbreakskip](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdBreakEventMap#adbreakskip)                      | Fired when the ad break is skipped.                                                                                                           |
| Uplynk Ad Break                                                                                                                              | [updateadbreak](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdBreakEventMap#updateadbreak)                  | Fired when the ad break is updated.                                                                                                           |
| [Uplynk Ad](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdEventMap)                     | [adbegin](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdEventMap#adbegin)                                   | Fired when an ad begins.                                                                                                                      |
| Uplynk Ad                                                                                                                                    | [adcomplete](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdEventMap#adcomplete)                             | Fired when the ad is completed.                                                                                                               |
| Uplynk Ad                                                                                                                                    | [adend](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdEventMap#adend)                                       | Fired when the ad ends.                                                                                                                       |
| Uplynk Ad                                                                                                                                    | [adfirstquartile](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdEventMap#adfirstquartile)                   | Fired when the ad reaches the first quartile.                                                                                                 |
| Uplynk Ad                                                                                                                                    | [admidpoint](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdEventMap#admidpoint)                             | Fired when the ad reaches the mid point.                                                                                                      |
| Uplynk Ad                                                                                                                                    | [adthirdquartile](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkAdEventMap#adthirdquartile)                   | Fired when the ad reaches the third quartile.                                                                                                 |

Our APIs are continuously evolving, and so is our list of events. Refer to [the Web SDK API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web) to go through the latest set of events.

## Related articles

* [How do you know when a stream or an advertisement is playing?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/detect-stream-or-ad-playing.md)
* [How to measure the time-to-first-frame](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/measure-time-to-first-frame.md)
* [How to track the first play(ing) event](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/track-first-playing-event.md)
* [How to track player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/track-player-states.md)

---

# How do you know when a stream or an advertisement is playing on Web?

This guide explains how to determine programmatically when the player is playing, and whether it is playing a stream or a client-side advertisement. This is useful when you want different behavior, or a different UI, for content and for advertisements.

The `playing` event tells you when content or an advertisement starts playing. Its event handler is the right place to check whether an advertisement is playing.

This approach only works for client-side advertisements, not for server-side advertisements.

## Usage

The Web SDK exposes whether an advertisement is playing through [`player.ads.playing`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Ads#playing).

```js
player.addEventListener('playing', (event) => {
  const adIsPlaying = player.ads.playing;
  console.log('PLAYING', adIsPlaying ? 'Advertisement' : 'Content', event);
});
```

## Related articles

* [How to track the first play(ing) event](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/track-first-playing-event.md)

---

# How to measure the time-to-first-frame on Web

The time-to-first-frame, also known as the start-up time, is the time between the moment where playback is requested and the moment where the first frame is rendered.

To measure it, measure the time between the `play` event and the `playing` event.

## Usage

```js
let playEventRegisteredAt;

function playEventHandler() {
  player.removeEventListener('play', playEventHandler);
  playEventRegisteredAt = Date.now();
}

function playingEventHandler() {
  player.removeEventListener('playing', playingEventHandler);
  const timeToFirstFrame = Date.now() - playEventRegisteredAt;
  console.log('Time-to-first-frame:', timeToFirstFrame);
}

player.addEventListener('play', playEventHandler);
player.addEventListener('playing', playingEventHandler);
```

---

# How to track the first play(ing) event on Web

Sometimes you want to know when a new stream starts playing for the first time, for example to forward a `firstplay` event to an analytics back-end. THEOplayer does not expose such an event, but you can implement it yourself, which gives you more control over its logic.

The implementation below listens for the first `playing` event after every source change. If the viewer pauses and resumes the stream, the event is not dispatched again. If the viewer switches to another stream, it is dispatched once more.

You can swap out the `playing` event for a `play` event, or for any other event for that matter.

## Usage

```js
function firstPlayingHandler(event) {
  player.removeEventListener('playing', firstPlayingHandler);
  console.log('First playing event!', event);
}

player.addEventListener('sourcechange', () => {
  player.removeEventListener('playing', firstPlayingHandler);
  player.addEventListener('playing', firstPlayingHandler);
});
```

Instead of `sourcechange`, you can also listen for `loadedmetadata`, which is dispatched once the player has loaded the metadata of the new stream.

## Related articles

* [How do you know when a stream or an advertisement is playing?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/detect-stream-or-ad-playing.md)

---

# How to track player states on Web

A video player has states. As a developer, you should understand these states, as each state grants you access to different data, and might imply a re-render of your UI. For example, if your video player is in the "Paused" state, you want to show a play-button instead of a pause-button.

The objective of this guide is to define some video player states, and how to track the transition between states.

Although there's no official list of video player states, we'll define 11 states for learning purposes. These 11 states are visualized in the state diagram below.

![Video Player States](/pr-932/assets/images/player-video-player-states-4f4f37f92d4b03a2c750ce7fe03d0a5a.png "Video Player States")

The table below provides the definitions of these 11 states.

| State                            | Description                                                                                                                                                                                                                                                                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A: Empty                         | A state where the player is created, but has no information or data retained on the source which is to be played. The player is idle and not undertaking any interaction with the system.                                                                                                                                                         |
| B: Initialized                   | A state where the player knows the source which is to be played, but no media data is loaded. The player is idle and not undertaking any interaction with the system.                                                                                                                                                                             |
| C: Playing - HAVE\_NOTHING       | A state where the player wants to start playing a source, but has no media data available. The player is actively loading media data in order to initiate playback.                                                                                                                                                                               |
| D: Paused - HAVE\_NOTHING        | A state where the player wants to fill its buffer without playing, but has no media data available. The player is actively loading media data in order to fill its buffer.                                                                                                                                                                        |
| E: Playing - HAVE\_METADATA      | A state where the player wants to start playing a source, but only metadata is available and the entire buffer is still empty. The player knows which tracks and qualities are available. The player is actively loading media data in order to initiate playback.                                                                                |
| F: Paused - HAVE\_METADATA       | A state where the player wants to fill its buffer without playing, but only metadata is available and the entire buffer is still empty. The player knows which tracks and qualities are available. The player is actively loading media data in order to fill its buffer.                                                                         |
| G: Playing - HAVE\_CURRENT\_DATA | A state where the player wants to start playing a source and has media data in its buffer for the current timestamp, but this data is insufficient to start playback and guarantee a smooth viewer experience. The player is actively loading media data in order to initiate playback.                                                           |
| H: Paused - HAVE\_CURRENT\_DATA  | A state where the player wants to fill its buffer without playing and has media data in the buffer for the current timestamp, but this data is insufficient to start playback and guarantee a smooth viewer experience. The player is actively loading media data in order to fill its buffer.                                                    |
| I: Playing                       | A state where the player is actively rendering out media data. The current timestamp is progressing at the speed of the current playback rate and media buffer data is being consumed and loaded in parallel. timeupdate events will be dispatched regularly during playback and progress events will be dispatched as additional data is loaded. |
| J: Paused                        | A state where the player has sufficient media data in its buffer in order to guarantee a smooth viewer experience when playback is started, but it is in a paused state. The player is not consuming any media data, but might be loading additional media data to grow its buffer in the background.                                             |
| K: Error                         | A state where the player has observed a fatal, non recoverable error. The player cannot continue playback and needs to be initialized again in order to restart playback. A player can get into this state from any state other than the Empty-state.                                                                                             |

The table below explains what triggers each of the 26 transitions between states, and what video player events are related.

| Transition | Triggers                                                                                                   | Events                                                                                                                                                    |
| ---------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1          | `new THEOplayer.Player`                                                                                    |                                                                                                                                                           |
| 2          | `player.source = X`                                                                                        | `sourcechange`, `currentsourcechange`                                                                                                                     |
| 3          | `player.play()`                                                                                            | `play`, `loadstart`                                                                                                                                       |
| 4          | `player.load()`                                                                                            | `loadstart`                                                                                                                                               |
| 5          | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 6          | `player.play()`                                                                                            | `play`                                                                                                                                                    |
| 7          | The stream manifest being loaded                                                                           | `readystatechange`, `loadedmetadata`, `durationchange`                                                                                                    |
| 8          | The stream manifest being loaded                                                                           | `readystatechange`, `loadedmetadata`, `durationchange`                                                                                                    |
| 9          | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 10         | `player.play()`                                                                                            | `play`                                                                                                                                                    |
| 11         | Stream media data is loaded                                                                                | `readystatechange`, `loadeddata`, `progress`, `canplay`                                                                                                   |
| 12         | Stream media data is loaded                                                                                | `readystatechange`, `loadeddata`, `progress`, `canplay`                                                                                                   |
| 13         | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 14         | `player.play()`                                                                                            | `play`                                                                                                                                                    |
| 15         | Sufficient media data is loaded to start playback fluently.                                                | `progress`, `canplaythrough`, `readystatechange`, `playing`<br />*A `seeked` event can be dispatched if the entrance of this state was caused by a seek.* |
| 16         | Sufficient media data is loaded to start playback fluently.                                                | `canplaythrough`, `readystatechange`<br />*A `seeked` event can be dispatched if the entrance of this state was caused by a seek.*                        |
| 17         | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 18         | `player.play()`                                                                                            | `play`, `playing`                                                                                                                                         |
| 19         | `player.currentTime = X` and there is some media data at the target time, but not enough to play fluently. | `seeking`, `readystatechange`                                                                                                                             |
| 20         | The player buffer is not being filled enough, causing a stall.                                             | `waiting`, `readystatechange`                                                                                                                             |
| 21         | `player.currentTime = X` and there is no media data at the target time.                                    | `seeking`, `readystatechange`                                                                                                                             |
| 22         | Playback has ended.                                                                                        | `ended`, `readystatechange`                                                                                                                               |
| 23         | `player.currentTime = X` and there is some media data at the target time, but not enough to play fluently. | `seeking`, `readystatechange`                                                                                                                             |
| 24         | `player.currentTime = X` and there is no media data at the target time.                                    | `seeking`, `readystatechange`                                                                                                                             |
| 25         | An error occurred.                                                                                         | `error`                                                                                                                                                   |
| 26         | `player.source = null`                                                                                     | `emptied`                                                                                                                                                 |

## Implementation

The code samples below demonstrate how you track some of the 18 events related to the state transitions.

* `sourcechange`
* `currentsourcechange`
* `play`
* `loadstart`
* `pause`
* `readystatechange`
* `loadedmetadata`
* `durationchange`
* `loadeddata`
* `progress`
* `canplay`
* `canplaythrough`
* `playing`
* `waiting`
* `seeking`
* `ended`
* `error`
* `emptied`

All 18 events are dispatched by the `Player` interface.

The snippet below demonstrates how you can track some of the related events through the Web SDK. All other events can be tracked similarly. You can find the event names in [the `PlayerEventMap` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap), and the properties of the player in [the `ChromelessPlayer` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer). This approach is valid for all web-based platforms, including Tizen and webOS.

```js
player.addEventListener('sourcechange', (event) => {
  console.log(event);
});
// ...
player.addEventListener('ended', (event) => {
  console.log(event);
});
```

---

# Text tracks on Web

The articles in this section describe how to implement common use-cases related to text tracks, subtitles, closed captions and metadata. These use-cases can range from programmatically detecting new metadata, to side-loading subtitles.

THEOplayer supports

* subtitle and closed caption formats like WebVTT, CEA-608, DVB Subs and TTML;
* metadata formats like ID3, emsg, EventStream and `EXT-X-DATERANGE`.

The TextTrack API allows you to programmatically switch between text tracks, detect events related to text tracks (e.g. a new active cue) and more.

## Related articles

* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/change-visible-captions.md)
* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-text-tracks.md)
* [How to programmatically detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-text-track-changes.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/enable-disable-text-tracks.md)
* [How to detect active text track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-active-text-track-cues.md)
* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/insert-subtitles.md)
* [How to implement preview thumbnails](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/preview-thumbnails.md)
* [How to track ID3 cues/tags](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/track-id3-cues.md)

---

# How to dynamically change the visible captions on Web

This article describes how you can dynamically change the currently selected subtitle or closed captions language, or how you can set a default language.

This article assumes that you are using text tracks that are loaded with the manifest. If you add the text track separately, you can also mark it as the default track when you configure your source.

The examples below match tracks on their `language` property, which contains the ISO language code of the track. If that is not sufficient for your use case, for example when a stream contains multiple tracks with the same language, you can match on the track's `label` instead, which contains the human-readable name shown in your UI.

## Usage

The function below disables all text tracks which are currently active, and then enables the text track with the requested language.

```js
function setLanguage(player, language) {
  // Disable all text tracks that are currently active
  player.textTracks
    .filter(function (track) {
      return track.mode !== 'disabled';
    })
    .forEach(function (track) {
      track.mode = 'disabled';
    });
  // Enable the text track for a specific language
  const requestedTrack = player.textTracks.find(function (track) {
    return track.language === language;
  });
  if (requestedTrack) {
    requestedTrack.mode = 'showing';
  }
}
```

## Related articles

* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-text-tracks.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/enable-disable-text-tracks.md)
* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/insert-subtitles.md)

---

# How to programmatically detect text tracks on Web

This article describes how you can use the TextTrack API to detect text tracks, which can be subtitles, closed captions or metadata. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available subtitle languages.

## Usage

Listen for the [`addtrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap#addtrack) event on [`player.textTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#texttracks) to detect every [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrack) that is added to the player.

```js
function handleAddTrackEvent(addTrackEvent) {
  const textTrack = addTrackEvent.track;
}
player.textTracks.addEventListener('addtrack', handleAddTrackEvent);
```

## Related articles

* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/enable-disable-text-tracks.md)
* [How to programmatically detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-text-track-changes.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md)

---

# How to programmatically enable or disable text tracks on Web

This article describes how you can use the TextTrack API to enable or disable subtitles, closed captions or metadata. Implementing this functionality is a common use-case for developers who want to build their own UI to toggle subtitles.

It is advised to disable the text tracks which you do not want to display, in order to avoid issues with overlapping text.

## Usage

Set the [`mode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrack#mode) of a [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrack).

```js
// disable all text tracks
player.textTracks.forEach(function (track) {
  track.mode = 'disabled';
});
// enable a specific text track
player.textTracks[indexOfRequestedTextTrack].mode = 'showing';
```

## Related articles

* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/change-visible-captions.md)
* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-text-tracks.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md)

---

# How to insert subtitles on Web

This article describes how you can side-load subtitles or closed captions, i.e. how you can add text tracks which are not part of your HLS or MPEG-DASH manifest.

Every source description has a text tracks property, which accepts an array of side-loaded text tracks. All valid tracks are available for playback as long as the player's source is not set again.

Text track descriptions can also be used for other purposes, e.g. for including preview thumbnails and chapters.

## Usage

Each text track is described by a [`TextTrackDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackDescription).

```js
player.source = {
  sources: [
    {
      src: '//path/to/your-manifest.m3u8',
      type: 'application/x-mpegurl',
    },
  ],
  textTracks: [
    {
      default: true, // optional
      kind: 'subtitles', // optional
      label: 'English subs', // optional - this appears in your UI
      src: 'path/to/your-subs-track1.vtt',
      srclang: 'en',
    },
  ],
};
```

## Subtitle styling

To style your subtitles, look into the player's [`textTrackStyle`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackStyle) property.

## Related articles

* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/change-visible-captions.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/enable-disable-text-tracks.md)
* [How to implement preview thumbnails](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/preview-thumbnails.md)

---

# How to implement preview thumbnails on Web

This article describes how you can enable preview thumbnails, which THEOplayer implements through the TextTrack API. The thumbnails are loaded as a separate text track, by side-loading them as a text track in your source description.

A demo of the preview thumbnails on the THEOplayer Web SDK is available at [preview thumbnails](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/preview-thumbnails.md).

## Usage

```js
player.source = {
  sources: {
    type: 'application/x-mpegurl',
    src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8',
  },
  textTracks: [
    {
      default: true,
      src: 'https://cdn.theoplayer.com/dash/theoplayer/thumbnails/big_buck_bunny_thumbnails.vtt',
      label: 'thumbnails',
      kind: 'metadata',
    },
  ],
};
```

If you use the [Open Video UI for Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md) or [THEOplayer's default UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web.md), the thumbnails are shown automatically when hovering or scrubbing the seek bar.

## Related articles

* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/insert-subtitles.md)

---

# How to track ID3 cues and tags on Web

[ID3](https://en.wikipedia.org/wiki/ID3) is a type of metadata which can be inserted in HTTP live streams. Once an ID3 cue is inserted, it is added to a THEOplayer text track.

Developers commonly track ID3 cues because they want to introduce a certain behavior depending on the metadata contained by the ID3 cues, for example:

* to schedule advertisements dynamically by using information passed on by the ID3 metadata;
* to overlay certain text on top of the player (e.g. the score of a football match).

The demo at <https://demo.theoplayer.com/audio-id3-metadata> demonstrates a usage of ID3 metadata. Just before the song changes, an `enter` event is dispatched. The song information (title, album, etc.) is contained within this `enter` event, and can be used to update the UI.

This article describes how you can listen for timed metadata events, and how you can track the `enter` event.

## Listening for timed metadata events

Listen for the [`cuechange`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap#cuechange) event of a [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrack).

```js
player.textTracks.addEventListener('addtrack', function (addTrackEvent) {
  const track = addTrackEvent.track;
  if (track.kind !== 'metadata') {
    return;
  }

  track.addEventListener('cuechange', function (cueChangeEvent) {
    // here you can access the cues of the track, and display the metadata to the outside
  });
});
```

## Tracking the enter event

The `enter` event, which is part of the TextTrack API, maps to the moment in time when the ID3 cue becomes relevant.

Listen for the [`entercue`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap#entercue) event of the track, which is fired for every cue of that track that becomes active. The entered cue is available as [`event.cue`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEnterCueEvent#cue).

```js
player.textTracks.addEventListener('addtrack', function (addTrackEvent) {
  const track = addTrackEvent.track;
  if (track.kind !== 'metadata') {
    return;
  }

  track.addEventListener('entercue', function (enterCueEvent) {
    // log entercue event
    console.log(enterCueEvent);
  });
});
```

Alternatively, you can listen for the [`enter`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackCueEventMap#enter) event on each individual cue. Note that you have to add a listener to every cue, including the cues that are added to the track later on.

```js
function enterListener(event) {
  // log enter event
  console.log(event);
}
function handleTrackCreation(addTrackEvent) {
  const track = addTrackEvent.track;
  if (track.kind !== 'metadata') {
    return;
  }

  track.cues.forEach(function (cue) {
    cue.addEventListener('enter', enterListener);
  });

  // detect cues being added to the track
  track.addEventListener('addcue', function (addCueEvent) {
    // detect a cue being shown from a track
    addCueEvent.cue.addEventListener('enter', enterListener);
  });
}
player.textTracks.addEventListener('addtrack', handleTrackCreation);
```

## Resources

* <https://demo.theoplayer.com/audio-id3-metadata>: a demo which illustrates the use of ID3 in production.
* <http://id3.org/>: ID3.org home page.
* <https://en.wikipedia.org/wiki/ID3>: Wikipedia - ID3.
* <https://dev.w3.org/html5/html-sourcing-inband-tracks/>: Sourcing In-band Media Resource Tracks from Media Containers into HTML.

## Related articles

* [How to detect active text track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-active-text-track-cues.md)
* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-text-tracks.md)

---

# How to programmatically detect text track changes on Web

This article describes how you can use the TextTrack API to detect text track changes. A text track "change" is triggered by enabling (or disabling) a subtitle or closed captions track.

Implementing this functionality is a common use-case for developers who want to build their own UI, and annotate the subtitle (or closed captions) track that is currently active.

## Usage

The implementation of the Web SDK applies to all web-based platforms, including Tizen and webOS.

The Web SDK exposes the TextTrack API through [`player.textTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#texttracks). This `textTracks` property is a [`TextTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTracksList) that inherits from the [`TrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackList). This `TrackList` dispatches the events from the [`TrackListEventMap`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap). This `TrackListEventMap` contains the [`change`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap#change) event, as well as the `addtrack` and `removetrack` event.

The code below allows you to detect text track changes.

```js
player.textTracks.addEventListener('change', function (event) {
  const track = event.track;
  const isEnabled = track.mode === 'showing';
  console.log(track, track.label, track.kind, track.type, isEnabled);
});
```

The properties of a text `track` (e.g. `mode`, `kind`) are described in [the `TextTrack` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrack).

## Related articles

Are you reading this article because you are interested in subtitles and closed captions? Continue reading below.

* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-text-tracks.md)
* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/change-visible-captions.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/enable-disable-text-tracks.md)
* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/insert-subtitles.md)

Refer to [how to track ID3 cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/track-id3-cues.md) if you are interested in timed metadata (ID3, emsg, EventStream, `EXT-X-DATERANGE`, ...).

Are you reading this article because you are implementing a custom UI? Then you will find the following articles interesting:

* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md)
* [How to detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-video-track-quality-changes.md)
* [How to detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-audio-track-changes.md)

---

# How to detect active text track cues on Web

This article describes how you can use the TextTrack API to detect the active text track cues, by subscribing to the `enter` and `exit` events of a cue, or to the `cuechange` event of a text track.

Implementing this functionality can be a use-case for developers who want to build their own UI, and insert and style their subtitles with maximum freedom. Alternatively, you may need to access the active cues for analytics purposes, or to render them outside of the video player.

Another common use-case is to detect the active text track cue of timed metadata. This article also discusses this use-case.

## Implementation for subtitles and closed captions

Note that this section focuses on detecting active cues for subtitles and closed captions. Go to the section on ["implementation for timed metadata"](#implementation-for-timed-metadata) if you rather want to track timed metadata like ID3, emsg, `EXT-X-DATERANGE` and EventStream.

The Web SDK exposes the TextTrack API through [`player.textTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#texttracks). This `textTracks` property is a [`TextTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTracksList) that inherits from the [`TrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackList). This `TrackList` dispatches the events from the [`TrackListEventMap`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap). This `TrackListEventMap` contains the [`addtrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TrackListEventMap#change) event, as well as the `change` and `removetrack` event.

In the callback of your `addtrack` event, you want to track the [`addcue`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap#addcue) event through the [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrack) interface. Then, in the callback of your `addcue` event, you want to track the [`enter`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackCueEventMap#enter) and [`exit`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackCueEventMap#exit) events through the [`TextTrackCue`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackCue) interface. The `enter` event is dispatched when a cue becomes active and the `exit` event is dispatched when a cue becomes inactive. You can fetch the actual content in the callback of your `enter` event through its [`content`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackCue#content) property.

Alternatively, in the callback of your `addtrack` event, you could track the [`cuechange`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackEventMap#cuechange) event through the `TextTrack` interface. Then, in the callback of your `cuechange` event, you want to iterate over the active cues. For each active cue, you could also query its `content` property.

The code below allows you to detect the active text track cues.

```js
player.textTracks.addEventListener('addtrack', function (addTrackEvent) {
  const track = addTrackEvent.track;
  track.addEventListener('addcue', function (addCueEvent) {
    const cue = addCueEvent.cue;
    cue.addEventListener('enter', function (enterEvent) {
      console.log(enterEvent, enterEvent.cue.content);
    });
    cue.addEventListener('exit', console.log);
  });
  track.addEventListener('cuechange', function (cueChangeEvent) {
    const cues = cueChangeEvent.track.activeCues;
    for (let i = 0; i < cues.length; i++) {
      console.log('cuechange active cue', i, cues[i]);
    }
  });
});
// ...
// player.source = ...
```

You should invoke these event handlers before you configure your stream, because the player might have already dispatched the event before you were able to subscribe to it.

## Implementation for timed metadata

The implementation for timed metadata is identical to the one for subtitles and closed captions, except for three things.

1. You do not necessarily use the `enter` event. For cues that span a period of time, for example `EXT-X-DATERANGE` cues, you might want to perform your action when the cue ends, so on the `exit` event instead.

2. You might need to set the `mode` of the relevant text track to `hidden`, as documented in [how to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/enable-disable-text-tracks.md). Some types of timed metadata, for example `EXT-X-DATERANGE` and EventStream, are `disabled` by default. You should add a condition to your `addtrack` callback to decide whether you want to set your track to `hidden`.

3. You should set [`hlsDateRange`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerConfiguration#hlsDateRange) to `true` in your player configuration or stream configuration, if you want to detect `EXT-X-DATERANGE` tags in an HLS stream.

The article on [how to track ID3 cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/track-id3-cues.md) might be useful to learn more about detecting ID3 tags specifically.

## Related articles

* [How to programmatically detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-text-track-changes.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/enable-disable-text-tracks.md)
* [How to track ID3 cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/track-id3-cues.md)

---

# License on Web

A THEOplayer license is required to use THEOplayer. The licensing schema was previously based on the built-in license from the SDK build, but THEOplayer now allows you to update the license without rebuilding or re-integrating the player SDK.

This article explains how to configure the license at runtime.

## Passing the license through the player configuration

This can be done in two ways:

* Pass a license string for the player by setting it on the `license` property:

```js
const player = new THEOplayer.Player(element, {
  libraryLocation: '/path/to/your-theoplayer-folder/',
  license: 'your_license',
});
```

* Pass a valid URL that can be used to fetch the license for the player by setting it on the `licenseUrl` property:

```js
const player = new THEOplayer.Player(element, {
  libraryLocation: '/path/to/your-theoplayer-folder/',
  licenseUrl: 'your_license_url',
});
```

If the player is configured with either `license` or `licenseUrl`, the player will first validate the `license` string. If the license is either undefined or expired, the player will attempt to request the `licenseUrl` instead. If no `licenseUrl` is defined, then a default license URL will be used. If neither of these options is provided, the player will default to the built-in license in the SDK if it was built on THEOportal. If the player is [from npm](https://www.npmjs.com/package/theoplayer), it will throw a license error.

If no valid license can be found, the player will throw a license error.

## FAQ

### Why do I have to configure a license?

In order to provide THEOplayer insights if a stream can be played, it needs to have access to an active license. You can choose to either configure this license, or configure a URL where this license can be retrieved. We recommend everyone to configure an active license or a license URL.

### How do I avoid introducing any dependencies on THEOplayer servers?

There are two important aspects which can introduce a dependency on THEOplayer servers:

1. **Loading a THEOplayer SDK from the THEOplayer CDN.** This issue is only relevant for the Web SDK. In order to avoid this dependency, we recommend to self-host your THEOplayer SDK. The easiest approach is to load the player through npm, or download the player SDK as a zip file from the developer portal. More information on how to self-host your player can be found in "[Self-hosting THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/self-hosting-theoplayer.md)".
2. **Loading a THEOplayer license from the THEOplayer license system.** In order to avoid this dependency, it is important to always keep your license up to date, either by configuring an updated license or by configuring your own license URL. When your THEOplayer license expires, a new player instance will actively check against THEOplayer's license system if there is an updated license available. This system should however only serve as a fallback for applications which cannot be updated.

### Should I pass a license string or a license URL?

We recommend our customers to use the license string whenever possible.

In special cases it is possible to use the license URL instead. Use cases include contractual or legal (for example privacy) requirements. For more information, please contact <support@theoplayer.com>.

If the player is configured with both a license string and a license URL, it will first try to validate the license string. If the license string is either not configured or expired, the player will attempt to request the license URL instead. If no license URL is defined, then a default license URL will be used. If no valid license can be found, the player will throw a license error.

### Should I update my application upon license renewal?

Yes. After renewing your license, you should make sure to include the new THEOplayer license in your next app update.

### What happens if I don't timely update the license in my application?

The player will attempt to update the license up to 72 hours before expiration. For this, the player will request a new license either from the configured license URL, or as a fallback (when there is no license URL configured) from `validate.theoplayer.com`. Either way, if the request is successful, the player will store the license locally. We highly recommend you to self-host the license using the license URL in the player configuration.

For self-hosting, the license file with the latest license string for your application should be hosted. The full URL to this file should then be configured as the license URL in the player configuration.

### Will I still be able to play offline content with my THEOplayer SDK if my license expires?

When your license expires, THEOplayer will attempt to load an updated license. If an updated license is available, offline playback will still function. If no valid license is available, and no license server can be reached (due to the client being offline), the player will throw an error and stop playback. For this reason, it is important to always keep your license up to date.

### What should I do to protect my license?

The THEOplayer license you get from THEOportal is already an obfuscated string. If you want to protect your license, you need to make sure to configure your [page and source domains](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/page-and-source-domains.md) to guarantee that your license string cannot be used anywhere other than the specified pages and/or with those source domains.

---

# Introduction

THEOplayer and Uplynk are partners in the streaming industry. [Uplynk](https://www.uplynk.com/) offers services like encoding, transcoding, server-side ad-insertion, a CDN and more.

> **Verizon Media / Edgio**
>
> Uplynk is formerly known as **Verizon Media** and **Edgio**. We are moving away from any Verizon Media references in our API. These are now marked as deprecated and should be replaced by the Uplynk API.

Uplynk offers services which can enhance the API, UI and UX of video players and applications. The most popular services are called *Preplay*, *Ping* and *Asset Info*. THEOplayer integrates these services so that developers and viewers can benefit from them.

For example,

* Viewers can skip over ads;
* Viewers can see when an ad is playing (and stopping);
* Developers can define the behavior when viewers try to seek over an ad;
* Developers can query metadata to render a playlist in their application.

A live demo of THEOplayer's integration of Uplynk is available [here](https://cdn.theoplayer.com/demos/verizon-media/index.html).

![UplynkDemo](/pr-932/assets/images/VerizonMediaDemo-57db7aa1e91a449a9a1d708b999251d5.png "Uplynk Demo")

For more information on the integration and available APIs, continue your read on the pages below.

## [📄️Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/preplay.md)

[This article explains how to leverage the Uplynk Preplay API through THEOplayer. This API allows developers to pre-integrate with Uplynk's Preplay service.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/preplay.md)

## [📄️Uplynk Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ads.md)

[Uplynk offers support for server-side ad-insertion (SSAI).](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ads.md)

## [📄️Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ping.md)

[This article explains how to use Uplynk's Ping API.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ping.md)

## [📄️Uplynk configuration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/configuration.md)

[This article explains what is possible with an Uplynk configuration when setting up a THEOplayer instance.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/configuration.md)

## [📄️Uplynk interface](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/interface.md)

[This article explains how developers can hook into the Uplynk interface. This interface allows developers to query the available assets and ads in an Uplynk stream, its properties, and subscribe to its events.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/interface.md)

## [📄️What are the Uplynk challenges](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-are-the-uplynk-challenges.md)

[The purpose of this article is to group common challenges application developers might encounter when using Uplynk (formerly known as Verizon Media, Edgecast or Edgio) as the back-end.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-are-the-uplynk-challenges.md)

Sample Git projects are available on the following links:

* Web: <https://github.com/THEOplayer/samples-html5-sdk/tree/master/reference-apps/verizon-media-app>
* Android: <https://github.com/THEOplayer/samples-android-sdk/tree/master/Verizon-Media>
* iOS: <https://github.com/THEOplayer/samples-ios-sdk/tree/master/Verizon-Media>
* Roku: <https://github.com/THEOplayer/samples-roku-sdk/tree/master/verizon-app>

---

# Preplay

This article explains how to leverage the Uplynk Preplay API through THEOplayer. This API allows developers to pre-integrate with Uplynk's Preplay service.

Uplynk users can use an API (i.e. `Preplay`) to generate a streaming playlist given one or more assets or advertisements. The Uplynk back-end stitches the content together and allows for server-side ad-insertion (SSAI) when applicable. This document describes how THEOplayer users should configure their source to leverage this Preplay service.

Assumptions:

* THEOplayer assumes the availability of the Preplay API and Uplynk content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
* THEOplayer assumes that developers who are interested in this feature have a basic understanding of the Preplay API. Uplynk documents this service in the [API docs](https://api-docs.uplynk.com/#Develop/Preplayv2.htm).
* THEOplayer assumes that developers provide correct asset identifiers, as well as the proper content protection level.

## Stream Configuration (without ads)

The examples below demonstrate how to configure a stream through the Uplynk pre-integration.

```js
player.source = {
  sources: [
    {
      integration: 'uplynk',
      id: '<your_uplynk_asset_id>',
      preplayParameters: {}, // Optional, defaults to an empty object. These will be added as query parameters to the Preplay API call.
      assetType: 'asset', // Optional, defaults to 'asset'. Can also be 'channel' or 'event', following the Uplynk semantics, where 'asset' is On-demand content.
      contentProtected: false, // Optional, defaults to false.
    },
  ],
};

// Source example for an external id (with optional properties omitted)
player.source = {
  sources: [
    {
      integration: 'uplynk',
      id: {
        userId: '<your_uplynk_user_id>',
        externalId: '<your_uplynk_external_id>',
      },
    },
  ],
};

// Source example for a regular asset id with e.g. 'delay' parameter and 'sig' token parameter (with optional properties omitted)
player.source = {
  sources: [
    {
      integration: 'uplynk',
      id: '<your_uplynk_asset_id>',
      preplayParameters: {
        delay: '7200',
        rays: 'dcba',
        sig: '2ff94739b021912712adafeccd6fa291f11eef0648c3b18b30224b84e0590b4f',
      },
    },
  ],
};
```

The snippet above gives a quick overview of the structure of an Uplynk-specific source, also known as an [UplynkSource](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkSource). More information on certain properties:

* `id`: The ID field identifies the asset. Instead of a single string, developers can also specify an array of asset IDs as strings, which will be stitched into a continuous stream. The same goes for the `externalId` property in case an external ID is used in the source.

* `preplayParameters`: The `preplayParameters` object should have string-key-string-value combinations, which will be used as query parameters for the Preplay API call. Nested objects are not supported.

* `contentProtected`: Boolean value which will internally set any necessary content-protection information. No content-protection details have to be specified by the customer.

* **A Preplay request must include all parameters defined within the playback request, hence these parameters must be included in the THEOplayer source**. This request must also include a digital signature if the 'Require a token for playback' option is enabled in the back-end on the corresponding live channel. (See also : [Signing a Playback URL Tutorial](https://api-docs.uplynk.com/#Tutorials/Signed-Playback-URL-Tutorial.htm))

* Uplynk specific documentation on the available playback URL query parameters can be found on the Uplynk documentation site under [Customizing Playback via Parameters](https://api-docs.uplynk.com/#Setup/Customizing-Playback.htm).

* Some parameters can be excluded from the digital signature calculation. These parameters may enable certain use cases (e.g. DVR) and would for this reason be excluded from the digital signature.

## Stream Configuration (with ads)

The examples below demonstrate how to configure a stream with server-side ads through an [UplynkSource](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkSource).

```js
player.source = {
    sources: [{
        integration: 'uplynk',
        id: [
            '<your_uplynk_content_first_part>',
            '<your_uplynk_ad_break_1>',
            '<your_uplynk_content_middle_part>',
            '<your_uplynk_ad_break_2>',
            '<your_uplynk_content_last_part>'
        ],
        preplayParameters: {
            // Parameters here should specify the necessary ad parameters for the Preplay API
            ad.param1: 'param_val1',
            ad.param2: 'param_val2'
        },
    }]
}
```

More information on certain properties:

* `preplayParameters`: The `preplayParameters` object should have string-key-string-value combinations, which will be used as query parameters for the Preplay API call. Nested objects are not supported.

* **A Preplay request must include all parameters defined within the [playback request](https://api-docs.uplynk.com/#Setup/Playback-URLs.htm#LiveChannelPURLs), hence these parameters must be included in the THEOplayer source**. This request must also include a digital signature if the 'Require a token for playback' option is enabled in the back-end on the corresponding live channel. (See also : [Signing a Playback URL Tutorial](https://api-docs.uplynk.com/#Tutorials/Signed-Playback-URL-Tutorial.htm))

  > Note the confusion that the provided link only mentions signing the **playback URL**, even though we are describing using tokens for the call to the Preplay API. However, this process is also valid for signing the `preplayParameters`.

* Uplynk specific documentation on the available playback URL query parameters can be found on the Uplynk documentation site under [Customizing Playback via Parameters](https://api-docs.uplynk.com/#Setup/Customizing-Playback.htm).

* Some parameters can be excluded from the digital signature calculation. These parameters may enable certain use cases (e.g. DVR) and would for this reason be excluded from the digital signature.

## Preplay Response

THEOplayer automatically interprets the response returned by the Preplay service. However, if a developer wants to perform their own logic with the Preplay API response, then they can intercept the `preplayresponse` event.

```js
const listener = (event) => {
  console.log('Do something with the raw response of the Preplay API call', event.response);
};

player.uplynk.addEventListener('preplayresponse', listener);
```

## Using Tokens

Uplynk users often leverage URL signatures (i.e. tokens) to further secure their content -- on top of AES-128 encryption or studio DRM. A token is (typically) generated on back-end using an API key and a set of parameters, as described on [Signing a Playback URL Tutorial](https://api-docs.uplynk.com/#Tutorials/Signed-Playback-URL-Tutorial.htm).

> Note the confusion that the provided link only mentions signing the **playback URL**, even though we are describing using tokens for the call to the Preplay API. However, this process is also valid for signing the `preplayParameters`.

This set of parameters should also be passed along to the `preplayParameters` in an [UplynkSource](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkSource). If you do not configure the `preplayParameters` correctly in relation to your signature parameters, then the Preplay request made by THEOplayer will most likely return an invalid Preplay response, preventing THEOplayer from setting up your stream.

Let's consider a set-up where an Uplynk customer uses both URL signatures and multi-DRM. [When you do DRM, you must specify the `rmt` and `manifest` parameter](https://api-docs.uplynk.com/#Develop/Preplayv2.htm?Highlight=rmt), **or** you can set `allowrmt` to `1` instead. We recommend using the latter, as demonstrated in our Node.js reference project at [GitHub](https://github.com/THEOplayer/theoplayer-verizon-media-node-js).

So, let's say you want to generate a signature on your back-end that is compatible with HLS + FairPlay, MPEG-DASH + Widevine and MPEG-DASH + PlayReady, then it could look like the snippet below using `allowrmt`.

```js
let params = {
  v: '2',
  tc: '1',
  exp: 36000,
  rn: 12345,
  ct: 'a',
  cid: '<your_uplynk_asset_id>',
  allowrmt: 1,
};
let query = Object.keys(params)
  .map((key) => key + '=' + params[key])
  .join('&');
let sig = CryptoJS.HmacSHA256(query, '<your_api_secret>').toString();
params['sig'] = sig;
```

Now you want to communicate this entire `params` object to your client-side, and set it as the value for `preplayParameters`:

```js
player.source = {
  sources: {
    integration: 'uplynk',
    id: '<your_uplynk_asset_id>',
    preplayParameters: params,
    assetType: 'asset',
    contentProtected: true,
  },
};
```

When there's a mismatch between signature parameters and Preplay parameters, the Preplay response usually returns `Invalid token signature` and playback is not possible.

Having difficulties figuring out tokens, DRM and THEOplayer? Check out the Node.js reference project at [GitHub](https://github.com/THEOplayer/theoplayer-verizon-media-node-js).

# Related articles

* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ads.md)
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ping.md)

---

# Uplynk Ads

Uplynk offers support for [server-side ad-insertion](https://docs.uplynk.com/docs/ads) (SSAI).

This article explains how to use the Uplynk Ads API exposed by THEOplayer to hook into these SSAI advertisements. Additionally, this API allows developers to manipulate the ad-related UX and UI.

## Global Configuration

The examples below demonstrate how to pass along global configuration for the Uplynk ads. These settings can be overwritten.

##### Web SDK

```js
var player = new THEOplayer.Player(element, {
  uplynk: {
    defaultSkipOffset: 2, // Ad breaks added by SSAI are by default skippable after two seconds. Optional and defaults to unskippable.
    onSeekOverAd: 'play-last', // When seeking over ad breaks, this configuration decides how to snapback and play any missed ad breaks.
    // Possible values are currently 'play-none', 'play-last' and 'play-all' where 'play-none' is the default.
  },
  // ... Other configuration goes here
});
```

## Uplynk Ads API

> **Deprecation**
>
> You can use the regular `player.ads` API for subscribing to Uplynk ad breaks, as described on [How to subscribe to ad events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/subscribe-to-ad-events.md). The implementation below can be expected to be removed in the future.

Specifying a source which contains server-side ads configured through the Uplynk pre-integration will have the player expose an Ads API specific to Uplynk, i.e. on the `player.uplynk.ads` API:

* `player.uplynk.ads.adBreaks`: Specifies all ad breaks that are currently in the stream by using SSAI through Preplay.
* `player.uplynk.ads.currentAdBreak`: If applicable, returns the ad break that is currently being played.
* `player.uplynk.ads.currentAds`: If applicable, returns a list of the current ads being played.
* `player.uplynk.ads.skip()`: If there is an ad break playing, and it is skippable, skip the ad break to the next content (or next seek point in case of snapback).

Calling the `player.uplynk.ads.skip()` function on a live stream will not have any effect.

In addition, event listeners are available to listen to new ad breaks:

* For adbreaks, the following events are defined:

  * *adbreakbegin*
  * *adbreakend*
  * *adbreakskip*
  * *addadbreak*
  * *removeadbreak*

* For ads, the following events are defined:

  * *adbegin*
  * *adchange*
  * *adend*
  * *adfirstquartile*
  * *admidpoint*
  * *adthirdquartile*
  * *adcomplete*

```js
// Sample source snippet

player.uplynk.ads.adBreaks.addEventListener('addadbreak', (event) => {
  // do something with event.adBreak as it is an ad break added through SSAI, an example:
  const adBreak = event.adBreak;
  if (adBreak.duration <= 15) {
    adBreak.skipOffset = -1; // Do not allow skipping of short ad breaks
  } else if (adBreak.duration > 60) {
    adBreak.skipOffset = 10; // Allow skipping of long ad breaks after ten seconds
  } else {
    adBreak.skipOffset = 0; // For all other ad breaks, allow immediate skipping
  }
  // subscribe to additional events
  event.adBreak.addEventListener('adbreakbegin', console.log);
  event.adBreak.addEventListener('adbreakend', console.log);
  for (var i = 0; i < event.adBreak.ads.length; i++) {
    event.adBreak.ads[i].addEventListener('adbegin', console.log);
    event.adBreak.ads[i].addEventListener('adend', console.log);
  }
});
```

## Related articles

* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/preplay.md)
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ping.md)

---

# Ping

This article explains how to use Uplynk's Ping API.

The Ping API by Uplynk allows users of their CMS to receive updates about SSAI on running live-streams or provide better playback position beaconing for Video on demand. The Ping API is used together with the Preplay API because the latter provides a session to be used with the Ping API.

This pre-integration allows the integrator to specify a source for Preplay as integrated in other tickets (RDMP-287), and enable or disable certain features of the Ping API. The player will then perform these Ping calls internally, without the integrator having to write their own Ping client. The response of Ping calls will be exposed for external handling if necessary. The updates about SSAI received through the Ping API will be reflected in the player API, where information about SSAI through the Verizon Media Platform is already present.

**Version 3 of the Ping API will be implemented.**

**Playhead Position** When Ping mentions time (and time mentioned below) relative compared to 0, the 0-point will be the start of playback. This might be a mismatch with the normal `player.currentTime`. Instead, this will be comparable with the time passed since `player.played.start(0)`.

**Feature Assumptions** We assume the SSAI information returned through the Ping API to be of a certain format, which we compile from examples and our own testing. The documentation does not define the structure of this payload very well and only states that it is "like the object returned in Preplay requests", though the formats are not a one-on-one match.

This feature currently excludes client-side ad tracking and VPAID support.

**Assumptions**

* THEOplayer assumes the availability of the Ping API and Uplynk content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
* THEOplayer assumes application developers have a notion of the Ping API, namely any extra parameters to be appended to the requests to Uplynk (e.g. for correct ad insertion). Uplynk documents this service in the [API docs](https://api-docs.uplynk.com/#Develop/Pingv3.htm).
* THEOplayer assumes application developers provide proper ID's of the Assets they want to play back, as well as the proper content protection level.

## Configuring Ping

The player allows specification of the desired features of the Ping API as listed [in the official Ping API documentation](https://api-docs.uplynk.com/#Develop/Pingv3.htm#Features).

By default, the ping API is disabled for all sessions. To enable it, the `ad.cping=1` parameter must be added to your preplay request. If you attempt to call the API without passing in the `ad.cping` parameter, you can throw off the server's ability to make ad event calls correctly.

In addition to enabling the API, you must also notify the server of the features you want to support for this viewing session. To specify which features you'd like to enable, you add the `ad.pingf={some value}` parameter to the playback token. The value of the parameter is detailed in the official Ping Documentation.

Sample playback URL with `cping`:

`https://content.uplynk.com/preplay/cc829785506f46dda4c605abdf65392b.json?ad=adserver&ad.cping=1&ad.pingf=3`

In the THEOplayer API, these features can simply be activated through the `ping` property in the source configuration:

```js
player.source = {
    sources: [{
        integration: 'uplynk',
        ...,
        ping: {
            linearAdData: true,
            adImpressions: false,
            freeWheelVideoViews: false
        },
        ...
    }]
}
```

## Ping requests

When the Ping API is enabled, THEOplayer will call the Ping URL located at:

```text
{prefix}/session/ping/{sessionID}.json?v=3&pt={currentTime}&ev={event}&ft={freeWheelTime}
```

Where:

* `{prefix}`: the prefix URL from the Preplay response.

* `{sessionID}`: the session ID from the Preplay response.

* `{currentTime}`: mandatory parameter. This is the current player time in seconds.

* `{event}`: the current Ping event. An event should only be passed when playback starts or when a viewer seeks to a new position. Valid values are:

  * **start**: Pass this event, along `withpt=0`, when the player starts playback. This lets the server know where playback starts and allows the server to fire start events as needed.
  * **seek**: Pass this event when a viewer seeks. This resets the timeline to prevent inadvertently firing events for skipped ads.

* `{freeWheelTime}`: indicates the playback position, in seconds, right before a viewer seeks to a different position in the timeline. This property is mandatory when the freeWheelVideoViews is used.

## Ping Response

When performed correctly, a Ping request will return a JSON response. THEOplayer will interpret this response according to the following principles:

* `next_time`: a new beacon will be scheduled when the player's currentTime passes this value. In case the value is -1, no further beacons will be scheduled.

* `currentBreakEnd`: will be used to update the end time of an ongoing ad-break in case the breakEnd was previously unknown. (Note Verizon Media by default requests 240s of ads in case the break length is unknown and will return all ads in the Ping response.)

* `ads`: will be interpreted in order to display markers in the timeline as well as expose ad information through the player.verizonMedia.ads property.

  * `ads.breaks.timeOffset` will be used in order to determine the start time of the ad break (in seconds).

  * `ads.breaks.ads` will be looped in order to extract the ad information to be exposed in the Uplynk Ad on the THEO API:

    * `ad.duration` will serve as duration in the ad (in seconds)
    * `ad.mimeType` will serve as mimeType in the ad
    * `ad.apiFramework` will serve as apiFramework in the ad
    * `ad.companions` will serve as companions in the ad
    * `ad.creative` will serve as creative in the ad
    * `ad.width` will serve as width in the ad
    * `ad.height` will serve as height in the ad
    * `ad.events` will serve as events in the ad
    * `ad.fw_parameters` will serve as freeWheelParameters in the ad

  * `ads.breaks.breakEnd` will be used in order to determine the end of the ad break. Note that this property is optional, and the duration of an ad break can be unknown and updated at a later point.

  * `ads.breaks.duration` will be ignored by the player.

  For all ads and breaks added, `adbreakbegin`, `adbreakend`, `adbegin` and `adend` events will be dispatched. Additionally, when `breakEnd` gets updated, an `updateadbreak` event will be dispatched.

* extensions: Will be ignored by THEOplayer.

* error: Errors will be reported back through the THEOplayer API.

The raw ping response can be retrieved by adding an event listener for the `pingresponse` event on the `player.uplynk` property.

| Event        | Description                             | Event object                                                            |
| ------------ | --------------------------------------- | ----------------------------------------------------------------------- |
| pingresponse | Fired when a Ping response is received. | event.response will contain the raw JSON response from the Ping server. |

```js
player.uplynk.addEventListener('pingresponse', function (event) {
  console.log(event.response); // Will print the raw Ping response.
});
```

## Related articles

* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/preplay.md)
* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ads.md)

---

# Uplynk configuration

This article explains what is possible with an Uplynk configuration when setting up a THEOplayer instance.

## Features

Developers can set an Uplynk configuration when creating their video player instance. Through this configuration, developers can set some UX and UI preferences related to the Uplynk integration.

* `defaultSkipOffset`: specifies when an ad break can be skipped. The default value is `-1`, which means that the ad break cannot be skipped.

* `onSeekOverAd`: specifies what should happen when viewers try to seek over an ad. By default, no ad are played when seeking over ads. As an alternative, you can

  1. only play the last ad break (before the requested playhead position), or
  2. play all ad breaks (before the requested playhead position).

* `ui`

  * `adBreakMarkers`: specifies that a (red) ad break marker should be rendered in the scrub bar. (Enabled by default.)
  * `assetMarkers`: specifies that a (black) asset marker should be rendered in the scrub bar. (Enabled by default.)
  * `adNotification`: specifies that a count-down timer must be rendered when an ad is playing. (Enabled by default.)
  * `contentNotification`: specifies that a count-down timer to the next asset must be rendered when the viewer is close to the transition of another asset of a multi-asset stream. (Enabled by default.)

You can toggle this features on [our demo page](https://cdn.theoplayer.com/demos/verizon-media/index.html). *(Note: technically, this demo doesn't use `defaultSkipOffset` to configure the skip offset. Instead, this demo uses `player.uplynk.ads.adBreaks[<element>].skipOffset` to adjust this dynamically at run-time.)*

![UplynkDemo](/pr-932/assets/images/VerizonMediaConfiguration-e6131ae47761b09919322b8c26ee3d15.png "Uplynk Configuration")

The examples below demonstrate how to use an Uplynk configuration per platform.

```js
const player = new THEOplayer.Player(element, {
    libraryLocation: '...',
    uplynk: { // optional
        onSeekOverAd: 'play-all', // default to 'play-none'. Other values: 'play-all' and 'play-last'
        ui: {
            contentNotification: true, // optional; defaults to true
            adNotification: true, // optional; defaults to true
            assetMarkers: true, // optional; defaults to true
            adBreakMarkers: true, // optional; defaults to true
        },
        defaultSkipOffset: 5 // ad break can be skipped after 5 seconds. (defaults to -1)
    },
    ...
});
```

Refer to the [UplynkConfiguration API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UplynkConfiguration) for more information.

# Related articles

* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ads.md): this article zooms in on `defaultSkipOffset` and \`\`onSeekOverAd\`.
* [Uplynk - Introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/introduction.md): this article links to sample Git projects which implement an `UplynkConfiguration`.

---

# Uplynk interface

This article explains how developers can hook into the Uplynk interface. This interface allows developers to query the available assets and ads in an Uplynk stream, its properties, and subscribe to its events.

## Using the Uplynk interface

The `Uplynk` interface is exposed through your THEOplayer instance (e.g.: `player.uplynk` for the Web SDK). Through this interface,

* You can retrieve information (e.g. start and stop time) on the available assets (because THEOplayer extracts this information from its integration with the Asset Info and Preplay service offered by Uplynk).
  * You can also subscribe `addasset` and `removeasset` events, which can be useful when you need to be informed when the assets become available.

* You can intercept Preplay, Asset Info and Ping responses (because THEOplayer integrates with these services offered by Uplynk).

* You can retrieve information on the available advertisements (because THEOplayer extracts this information from its integration with the Preplay and Ping service offered by Uplynk).

  * You can also subscribe to `addadbreak`, `addad`, `removeadbreak`, ... events, which can be useful if you want to know when which state is applicable (e.g. to overlay a custom advertisement countdown-timer).
  * You can also adjust the ad skip offset of an ad break.

If you're looking for more information on how to query the available advertisements and how to subscribe to ad events, then refer to [Uplynk Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ads.md).

The examples below provide a basic demonstration of how to use the `Uplynk` interface. The GitHub projects linked at [Uplynk - Introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/introduction.md) provide more code samples.

```js
const player = new THEOplayer.Player(element, {...});
// uplynk events
[
    'preplayresponse',
    'pingresponse',
    'assetinforesponse'
].forEach(function(e) {
    player.uplynk.addEventListener(e, console.log);
});
// uplynk.assets events
[
    'addasset',
    'removeasset'
].forEach(function(e) {
    player.uplynk.assets.addEventListener(e, console.log);
});
// uplynk.ads events
[
    'addadbreak',
    'removeadbreak'
].forEach(function(e) {
    player.uplynk.ads.adBreaks.addEventListener(e, function (e1) {
        if (e1.type === "addadbreak") {
            // uplynk.ads.adBreak[i] events
            [
                'adbreakbegin',
                'adbreakend',
                'adbreakskip',
                'updateadbreak'
            ].forEach(function(e) {
                e1.adBreak.addEventListener(e, console.log);
                // uplynk.as.adBreak.ads[i] events
                for (let i = 0; i < e1.adBreak.ads.length; i++) {
                    [
                        'adbegin',
                        'adend',
                        'adfirstquartile',
                        'admidpoint',
                        'adthirdquartile',
                        'adcomplete'
                    ].forEach(function(e) {
                        e1.adBreak.ads[i].addEventListener(e, console.log);
                    });
                }
            });
        }
    });
});
```

Refer to the [Uplynk API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Uplynk) for more information. Additionally, reviewing [the player configuration in the demo app](https://github.com/THEOplayer/samples-html5-sdk/blob/master/reference-apps/verizon-media-app/src/player.js) helps to understand the `Uplynk` interface.

## Related articles

* [Uplynk - Introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/introduction.md): this article links to sample Git projects which query (and subscribe to) the various properties and events offered by the `Uplynk` interface.
* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/preplay.md): this article explains how you can use the Uplynk interface to intercept Preplay responses.
* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ads.md): this article offers more information on the `ads` parts of the Uplynk interface.
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ping.md): this article explains how you can use the Uplynk interface to intercept Ping responses.

---

# Getting started with CMCD on Web

Media player clients can transmit useful information to Content Delivery Networks (CDNs) with each object request. This implementation is planned to fully support Common Media Client Data (CMCD) as defined in [CTA-5004-B](https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html), published in April 2026.

CMCD supports two modes of transmission:

* **Request mode**: CMCD data is sent as HTTP headers or query parameters on manifest and media segment requests.
* **Event mode** (available since v11.4.0): CMCD events are POSTed to configured HTTP endpoints.

## Request Mode

For request mode, use the [CMCD connector for Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/cmcd/getting-started.md).

## Event Mode

Event mode allows posting CMCD events to configured HTTP endpoints.

> **Info**
>
> Event mode is supported starting from version 11.4.0.

### Player-level configuration

```javascript
const player = new THEOplayer.Player(element, {
  cmcd: {
    externalSessionId: 'YOUR-EXTERNAL-SESSION-ID', // optional
    userId: 'YOUR-USER-ID', // optional
    eventEndpoints: [{ url: 'https://example.com/cmcd-event-endpoint' }],
  },
});
```

### Source-level configuration

```javascript
player.source = {
  sources: [{ src: 'https://example.com/stream.m3u8' }],
  cmcd: {
    externalSessionId: 'YOUR-EXTERNAL-SESSION-ID', // optional
    sessionId: 'YOUR-SESSION-ID', // optional
    userId: 'YOUR-USER-ID', // optional
    eventEndpoints: [{ url: 'https://example.com/cmcd-event-other-endpoint' }],
  },
};
```

### Merging behavior

* Source-level values take precedence for `externalSessionId` and `userId`.
* `eventEndpoints` from both levels are **merged** (both player and source endpoints receive events).

> **Warning**
>
> Event mode reporting currently only supports DRM and ad events.

---

# MPEG-DASH Content Steering

This guide shows you how to use MPEG-DASH Content Steering in the THEOplayer Web SDK.

MPEG-DASH Content Steering is a server-driven mechanism that allows content providers to dynamically control CDN selection across large groups of clients. While players can independently respond to local network conditions and switch between CDNs, Content Steering enables centralized decision-making at scale. By communicating with a steering server, the player receives a prioritized list of CDN endpoints that reflects real-time information about CDN performance, capacity, and cost across your entire user base. This allows you to proactively route traffic away from overloaded or underperforming CDNs, balance load across multiple providers, or implement cost optimization strategies—all without requiring player-side logic or client updates.

## Enabling/Disabling Content Steering

By default, Content Steering in MPEG-DASH is enabled, however, it can be explicitly enabled or disabled using a flag in your `SourceDescription`.

You can also override the `clientRequirement="false"` property in the MPEG-DASH manifest to enable Content Steering for a specific playback session by explicitly setting it to `true`.

```javascript
player.source = {
  sources: {
    src: 'https://your-dash-source-with-content-steering.mpd',
    dash: {
      contentSteering: true, // Default is true; set to false to disable.
    },
  },
};
```

## Events for Content Steering

THEOplayer provides events to monitor the Content Steering process. For more details, check the [API documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web#ContentSteeringStartEvent).

```javascript
player.addEventListener('contentsteeringstart', console.log);
player.addEventListener('contentsteeringstop', console.log);
player.addEventListener('contentsteeringlocationchange', console.log);
player.addEventListener('contentsteeringupdate', console.log);
player.addEventListener('contentsteeringerror', console.log);
```

## Known Limitations

* `PATHWAY-CLONE` from the Content Steering server response is not supported yet.
* Extended HTTP GET request parametrization instructions are not supported yet. You can add custom parameters to Content Steering requests by using a `RequestInterceptor` to intercept and modify network requests with the type `content-steering`.
* Targeting a specific set of clients as part of a ServiceDescription element is not supported.

## More information

* [DASH-IF: Content Steering for DASH](https://www.etsi.org/deliver/etsi_ts/103900_103999/103998/01.01.01_60/ts_103998v010101p.pdf)

---

# Getting started

## Usage

1. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md) to set up THEOplayer in your web app or website.
2. Add an OptiView Live source to your player's source.

### Add an OptiView Live source

After setting up your THEOplayer on your web page, set its source to a `SourceDescription` containing a `THEOliveSource`. You'll need an OptiView Live channel ID:

```javascript
const player = new THEOplayer.Player(element, configuration);
player.source = {
  sources: {
    type: 'theolive',
    src: 'your-channel-id',
  },
};
```

### Add configuration

Optionally, you can provide additional configuration to the player, specific for OptiView Live streams. To configure these settings, add a `theolive` property to the player configuration. For an exhaustive list of these options, please visit the [documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TheoLiveConfiguration).

```javascript
var player = new THEOplayer.Player(element, {
  license: 'your-license',
  // This is needed for fallback to work properly
  retryConfiguration: {
    maxRetries: 6,
  },
  theoLive: {
    externalSessionId: 'my-external-session-id',
    fallbackEnabled: true,
  },
});
```

## More information

* [API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TheoLiveSource)

---

# Basic Playback Guide

After following our [Getting Started on Web guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/theolive/getting-started.md) or the [Player Setup](#player-setup) section below, you will be ready to programmatically perform common playback actions. These include increasing/decreasing the volume, playing/pausing the stream, enabling full screen, and selecting quality layers.

## Player Setup

To get started with OptiView Live playback using THEOplayer, you must first initialize your player with reference to your OptiView Live channel as the source.

Here is an example of initializing a THEOplayer instance for OptiView Live:

```javascript
const player = new THEOplayer.Player(element, configuration);
player.source = {
  sources: {
    type: 'theolive',
    src: 'your-channel-id',
  },
};
```

Once done, your player variable will reference the returned THEOplayer instance and have access to all of its [properties and methods](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/Player).

## Adjust Volume

To adjust the volume of your stream during playback, you can set the [`volume`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/Player#volume) property to a floating point number in the range of `0.0` (0%) minimum and `1.0` (100%) maximum.

The following code sets the player's volume to 60%:

```javascript
// the stream's volume will now be 60%
player.volume = 0.6;
```

## Play/Pause Stream

To play or pause your stream, you can use the [play](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/Player#play) and [pause](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/Player#pause) methods available on your player variable.

To pause your stream:

```javascript
player.pause();
```

To play your stream:

```javascript
player.play();
```

## Enable Full Screen

To make your stream take up the full screen of the device it is being viewed upon, you must use the [`requestMode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Presentation#requestMode) method available on the [`presentation`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/Player#presentation) property of your player variable.

Before doing so, check that the player supports other presentation modes (besides the default `'inline'`) for the device which the stream is viewed on by using the [`supportsMode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Presentation#supportsMode) method on the presentation property.

Both the `requestMode` and `supportsMode` methods require a [`PresentationMode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/PresentationMode) parameter that can accept the following arguments:

* `inline`: The player is shown in its original location on the page. (default presentation mode)
* `fullscreen`: The player fills the entire screen.
* `picture-in-picture`: The player is shown on top of the page (see PiPConfiguration for more options).
* `native-picture-in-picture`: (Experimental) The player requests out-of-app picture-in-picture mode. Not supported on Firefox.

Check if fullscreen is supported with the following code:

```javascript
// returns a boolean value of true or false
player.presentation.supportsMode('fullscreen');
```

If the `supportsMode` method returns true for the presentation mode you passed into it, then you can move on to the steps below.

To make the current stream take up the full screen, pass a presentation mode of `'fullscreen'` to the `requestMode` method with the following code:

```javascript
// stream will take up the full screen which it is being viewed on
player.presentation.requestMode('fullscreen');
```

To confirm that the change has occurred, check the [`currentMode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Presentation#currentMode) property to ensure it now returns `'fullscreen'` as its value:

```javascript
// should return a value of 'fullscreen' to the console
console.log('this is the current presentation mode being used -->', player.presentation.currentMode);
```

## Select Quality Layer

To select a specific quality layer during the playing of your stream, you must set the [`targetQuality`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrack#targetQuality) property which is accessible on the [`videoTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/Player#videoTracks) property of your player variable.

The `videoTracks` property leverages the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MediaTrack).

To see what qualities you have available, use the following code:

```javascript
// put all available quality layers in an array and log them to the console
const qualities = player.videoTracks[0].qualities;
console.log('this is an array containing all available qualities --> ', qualities);
```

Once you know what options you have available, you can set the stream to be a specific quality by doing the following:

```javascript
// set a specific quality layer by using its index in the qualities array
player.videoTracks[0].targetQuality = qualities[indexOfDesiredQualityLayer];
```

## Tracking Streaming Protocols

In OptiView Live, an [`Endpoint`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Endpoint) can contain sources for multiple streaming protocols. For instance, it can be configured to load a WebRTC source for real time streaming but load a HLS source to allow seeking into a DVR window. Another use case is one where HESP is used as the primary streaming protocol, but the player could fall back to a HLS source if the platform doesn't support HESP playback.

To track switches between the possible streaming protocols, you can listen for the `currentsourcechange` event. The `currentSource` property in the payload shows which source is being used under the hood.

```javascript
player.addEventListener('currentsourcechange', console.log);
```

## More information

* [API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/Player)

---

# Airplay

OptiView Live streams have support for Airplay. However, a limitation for now is that the latency is higher while casting (about 12 seconds). Configuring it is exactly the same as for other streams you would play with THEOplayer. The instructions are described in the [Airplay guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/airplay/introduction.md).

---

# Chromecast

OptiView Live streams have support for Chromecast. However, a limitation for now is that the latency is higher while casting (about 12 seconds). Configuring it is exactly the same as for other streams you would play with THEOplayer. The instructions are described in the [Chromecast guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/enable-chromecast-on-the-sender.md).

---

# Metadata

Metadata that travels through your OptiView Live stream — whether [pushed via the API or embedded as SEI](https://docs-preview.optiview.dolby.com/pr-932/theolive/channel/metadata-insertion.md) — surfaces on the player as cues on a text track. The general approach is the same in every case:

1. Listen for `addtrack` on `player.textTracks` so you find out when a new metadata track shows up.
2. Subscribe to a cue event on that track.
3. Inspect the cue to make sure it carries the metadata you care about.
4. Read the payload from `cue.content`.

The properties you match on, the cue event you subscribe to, and the shape of `cue.content` all depend on which kind of metadata is being delivered.

## User-data-unregistered SEI and API push

UDU SEI and API-pushed payloads surface as ID3 `PRIV` frames inside an ID3 v2.4 tag embedded in an `emsg` box, carried by the CMAF segments of the stream.

* The owner identifier of the `PRIV` frame will be set to: `optiview.live:meta:<your-uuid>`
* The frame's private data will contain your metadata as raw binary data.

(See [section 4.27 of the ID3 v2.4 Native Frames specification](https://id3.org/id3v2.4.0-frames) and [ID3 in CMAF](https://aomediacodec.github.io/id3-emsg/) for more details.)

The OptiView Player Web SDK exposes these ID3 frames on a text track with [`TextTrack.type`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrack#type) equal to `'id3'`. Listen for the cue event that matches when you want to react:

* `addcue` fires as soon as a cue becomes available on the track, before playback reaches it — useful when you want to prefetch data or update application state ahead of time.
* `entercue` fires when playback enters the cue — useful when you want to act in sync with the video, for example to render an overlay at the moment the cue was inserted.

The ID3 frame will be contained in `cue.content` as a [ID3PrivateFrame](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ID3PrivateFrame) with `ownerIdentifier` equal to `optiview.live:meta:<your-uuid>`.

> **Important**
>
> Make sure to always check the frame's `id` and `ownerIdentifier` before using it, to avoid processing unrelated ID3 frames.

Suppose your UUID is `11111111-1111-1111-1111-111111111111`:

```javascript
player.textTracks.addEventListener('addtrack', function trackListener(event) {
  const track = event.track;
  if (track.type === 'id3') {
    // ID3 track was added. Listen for incoming ID3 cues.
    track.addEventListener('addcue' /* or 'entercue' */, (e) => {
      const frame = e.cue.content;
      if (frame.id === 'PRIV' && frame.ownerIdentifier === 'optiview.live:meta:11111111-1111-1111-1111-111111111111') {
        console.log('metadata', frame.data);
      }
    });
    track.removeEventListener('typechange', trackListener);
  } else if (track.type === '') {
    // Track type is not yet known. Check again when it becomes known.
    track.addEventListener('typechange', trackListener);
  } else {
    // Track type is known, but is not ID3. Stop listening.
    track.removeEventListener('typechange', trackListener);
  }
});
```

Here the `frame.data` carries the binary payload exactly as it was sent — your application is responsible for parsing it (for example UTF-8 JSON, protobuf, or your own format).

Using third-party players

When using a third-party player SDK, please refer to their respective documentation on how to retrieve ID3 from the stream.

For example, with [Shaka Player](https://github.com/shaka-project/shaka-player), you can listen for the [`metadata` event](https://shaka-player-demo.appspot.com/docs/api/shaka.Player.html#.event:MetadataEvent):

```javascript
player.addEventListener('metadata', (event) => {
  if (event.metadataType === 'org.id3') {
    const frame = event.payload; // see https://shaka-player-demo.appspot.com/docs/api/shaka.extern.html#.MetadataFrame
    if (frame.key === 'PRIV' && frame.description === 'optiview.live:meta:11111111-1111-1111-1111-111111111111') {
      console.log('metadata', frame.data);
    }
  }
});
```

With [hls.js](https://github.com/video-dev/hls.js/), you can listen for the `FRAG_PARSING_METADATA` event. However, hls.js doesn't come with a built-in ID3 parser, so you'll need to parse the ID3 tag manually:

```javascript
hls.on(Hls.Events.FRAG_PARSING_METADATA, (event, data) => {
  for (const sample of data.samples) {
    if (sample.type === Hls.MetadataSchema.emsg) {
      const tag = sample.data;
      // TODO Parse ID3 tag and look for ID3 PRIV frame with correct owner identifier
    }
  }
});
```

## Source timecode

When the video you ingest carries SMPTE timecode in its picture timing SEI, the Low-Latency HLS and HLS (CMAF) output passes it on as ID3 timed metadata, so players can read the timecode of every frame without parsing the video bitstream. No channel configuration is needed. Channels whose source carries no timecode get no timecode events, and HLS (MPEG-TS) output does not carry them.

Timecode events travel the same way as the metadata above: an ID3 v2.4 tag in an `emsg` box with scheme `https://aomedia.org/emsg/ID3`, carried by the CMAF segments of the stream. The tag holds a `TXXX` (user defined text) frame:

* The description of the `TXXX` frame is `optiview.live:timecode`.
* Its value is the timecode as `HH:MM:SS:FF`, for example `10:00:00:12`. A drop-frame timecode has `;` before the frames instead: `10:00:00;12`.

(See [section 4.2.6 of the ID3 v2.4 Native Frames specification](https://id3.org/id3v2.4.0-frames) for the `TXXX` frame.)

### Where the events sit

There is one timecode event per segment and per partial segment. The event sits on the frame of that segment or partial segment that is presented first, and its `emsg` box declares a duration of exactly one frame. OptiView Player starts the cue at that frame's presentation time and keeps it active until the next timecode cue starts.

A segment and its first partial segment open on the same frame, so they carry the same event, with the same `emsg` id. If your player reports it twice, the two cues are identical.

### Timecode of any other frame

Only the first-presented frame of each segment or partial segment carries an event. To find the timecode of any other frame:

1. Take the latest timecode event that starts at or before the presentation time of the frame.
2. Count the frames presented since that event: multiply the time between the start of the event and the presentation time of the frame by the frame rate, which the multivariant playlist declares for each rendition as `FRAME-RATE`.
3. Add that many frames to the timecode of the event, counting with the frame rate rounded to a whole number (30 for 29.97 fps). For a drop-frame timecode, skip the frame numbers that drop-frame timecode leaves out: frames `00` and `01` at the start of every minute except every tenth minute at 29.97 fps, and frames `00` to `03` at 59.94 fps.

This assumes the rendition has the frame rate of the source. Every frame carries the timecode of the source frame it was encoded from, so on a rendition with a lower frame rate than the source, such as a 30 fps rendition of a 60 fps source, count at the frame rate of the source instead.

A jump in the source timecode, for example when the source switches to another timecode generator, only shows from the next segment or partial segment on. Until then, counting on from the previous event continues the old sequence.

### Reading the timecode with the Web SDK

Timecode events surface on the same `'id3'` text track as the metadata above, as [ID3Cue](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ID3Cue)s whose `content` is an [ID3UserDefinedText](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/ID3UserDefinedText) frame with `id` equal to `'TXXX'` and `description` equal to `'optiview.live:timecode'`. The frame's `text` holds the timecode.

`entercue` fires when the frame carrying the timecode is presented, and `exitcue` when the next timecode cue starts. Add these listeners where the `'id3'` track is found in the example above:

```javascript
// By default, metadata tracks are disabled and do not fire cue events
track.mode = 'hidden';
track.addEventListener('entercue', (e) => {
  const frame = e.cue.content;
  if (frame.id === 'TXXX' && frame.description === 'optiview.live:timecode') {
    console.log('timecode', frame.text);
  }
});
track.addEventListener('exitcue', (e) => {
  const frame = e.cue.content;
  if (frame.id === 'TXXX' && frame.description === 'optiview.live:timecode') {
    console.log('timecode ended', frame.text);
  }
});
```

## Picture timing SEI

Picture timing SEI cues surface on a text track with [`TextTrack.id`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrack#id) equal to `'timecode'`. Each cue is anchored to a frame, so `entercue` is usually the most useful event: it fires when playback reaches the cue, letting you react in sync with the video.

```javascript
player.textTracks.addEventListener('addtrack', (event) => {
  const track = event.track;
  if (track.id === 'timecode') {
    track.mode = 'showing'; // Setting the mode to showing will enable the entercue events
    track.addEventListener('entercue', onTimeCode);
  }
});
```

The cue `content` is a structured `TimeCode` object:

```typescript
export interface TimeCode {
  readonly hours: number;
  readonly minutes: number;
  readonly seconds: number;
  readonly frames: number;
}
```

A handler can then turn that timecode into whatever action your app needs:

```javascript
const onTimeCode = (event) => {
  const timeCode = event.cue.content;
  // Insert other code here
};
```

A full example could be as follows: you distribute sports matches and want to display an overlay on the player when the score changes. Every time a score change happens, you add a picture timing SEI message to the stream and store in your backend that this time corresponds with this score. (You could also just add the timing message to all frames if this is easier, but this requires more processing both server and player side.) This information can then be retrieved by the application running on the device of a viewer. You then add the event listener and listen for the `entercue` events. In the listener you check whether the `TimeCode` corresponds with a score change event you recorded earlier and if so, display an overlay over the player.

---

# Discovery URLs

Before the player can play an OptiView Live channel, it sends a discovery request to find the stream details of that channel (such as its manifest URLs and token security settings). OptiView Live channels are served by one of three discovery API versions:

| API version | Channels                                          |
| ----------- | ------------------------------------------------- |
| V1 (legacy) | Channels created with the legacy THEOlive API.    |
| V2          | Distributions created with the OptiView Live API. |
| V3          | Distributions served by the newest discovery API. |

The player does not know in advance which API version serves your channel. If you do not configure a discovery URL, the player tries its built-in discovery URLs one by one, in this order:

1. V2
2. V1 (legacy)
3. V3

The player stops at the first discovery URL that returns the channel. If your channel is not served by V2, the earlier requests fail before the right one succeeds. These failed requests add a small delay before playback starts, and they show up as `404` responses in the network tab of your browser or in a network proxy. The `404` responses are expected and do not mean that playback failed.

## Why configure a discovery URL

When you configure the discovery URL that serves your channel, the player sends its first discovery request to that URL. This removes the failed requests and the extra startup delay.

Configured discovery URLs do not replace the built-in discovery URLs. The player tries them first, and continues with the built-in discovery URLs (V2, V1, V3) if the configured ones do not return the channel. A wrong discovery URL therefore costs one extra request, but it does not break playback.

On platforms that support both `discoveryUrl` and `discoveryUrls`, the player tries `discoveryUrl` first, then each URL of `discoveryUrls` in the order of the list, and then the built-in discovery URLs.

## Which discovery URL to use

The player derives the API version from the path of the discovery URL, so use the URL exactly as listed for your platform, including the trailing `/`. The URL for V1 channels is different on Web than on the other platforms.

| API version | Web                                             | Android, iOS, Roku                              |
| ----------- | ----------------------------------------------- | ----------------------------------------------- |
| V2          | `https://discovery.theo.live/v2/distributions/` | `https://discovery.theo.live/v2/distributions/` |
| V1 (legacy) | `https://discovery.theo.live/`                  | `https://discovery.theo.live/v2/publications/`  |
| V3          | `https://discovery.theo.live/v3/`               | `https://discovery.theo.live/v3/`               |

React Native and Flutter apps pass the discovery URL to the underlying Web, Android or iOS SDK, so the same rules apply per platform.

> **Find the API version of your channel**
>
> Play your channel without a discovery URL and open the network tab of your browser (or a network proxy for a native app). The discovery request that returns `200` shows the discovery URL that serves your channel. For example, a request to `https://discovery.theo.live/v2/distributions/<your-channel-id>` means that your channel is served by V2.

## Configure the discovery URL

Set the discovery URL in the `theoLive` property of the player configuration. For example, for a channel served by V2:

```javascript
const player = new THEOplayer.Player(element, {
  libraryLocation: '/path/to/theoplayer/',
  license: 'your-license',
  theoLive: {
    discoveryUrl: 'https://discovery.theo.live/v2/distributions/',
  },
});
```

If your channels are served by different API versions, list the discovery URLs in the order you want the player to try them:

```javascript
const player = new THEOplayer.Player(element, {
  libraryLocation: '/path/to/theoplayer/',
  license: 'your-license',
  theoLive: {
    discoveryUrls: ['https://discovery.theo.live/v2/distributions/', 'https://discovery.theo.live/'],
  },
});
```

On Web, the player ignores a trailing `channels/` or `distributions/` segment in the discovery URL. This means that `https://discovery.theo.live/v2/` and `https://discovery.theo.live/v2/distributions/` are the same V2 discovery URL. A URL without a version segment, such as `https://discovery.theo.live/`, is a V1 discovery URL.

## Configuration reference

All properties of [`TheoLiveConfiguration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TheoLiveConfiguration) are optional.

| Property            | Type       | Description                                                                                                                                                                                                                     |
| ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `discoveryUrl`      | `string`   | A discovery URL that the player tries before the built-in discovery URLs. Takes precedence over `discoveryUrls`.                                                                                                                |
| `discoveryUrls`     | `string[]` | A list of discovery URLs that the player tries in order, after `discoveryUrl` and before the built-in discovery URLs.                                                                                                           |
| `discoveryHeader`   | `string`   | A value that the player sends in the `x-theolive-discovery` HTTP header of every discovery request. Only use this if a discovery URL that you configured expects this header, for example your own proxy in front of discovery. |
| `fallbackEnabled`   | `boolean`  | Whether the player plays the fallback stream when a V1 channel has a fallback configured. Defaults to `true`.                                                                                                                   |
| `externalSessionId` | `string`   | Deprecated. An ID used to report usage analytics. Use `cmcd.externalSessionId` in the player configuration instead.                                                                                                             |

The default discovery order V2, V1, V3 applies from THEOplayer 11.13.0. Earlier versions try V1 first.

---

# Token based security

OptiView Live offers the option to enable JWT token security on a distribution (formerly referred to as an alias) level. This can be interesting if you only want valid users to access your stream. Read more about the feature and configuring it on your channels on the [token based security guide](https://docs-preview.optiview.dolby.com/pr-932/theolive/distribution/security/token-based-security.md).

This page will demonstrate how to configure the Web SDK for playback of channels with token based security enabled.

## Setting up the Web SDK for OptiView Live

Refer to the [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/theolive/getting-started.md) for the prerequisite steps in getting the Web SDK up and running for OptiView Live playback.

## Configuring the player to pass the token

Use the `player.theoLive.authToken` API to have the player pass your JWT token along with all HTTP requests it makes while playing your OptiView Live distribution:

```javascript
const token = getToken(); // Generate or request your token, for more information check the token based security guide linked above.
player.theoLive.authToken = token;
```

This will ensure the player includes the correct `Authorization` HTTP request header on all subsequent requests.

## Dealing with token expiry and rotation

If your tokens are short-lived, you want to make sure to update the token being passed to the player and requests before it expires, to allow playback to continue beyond expiry. This can be done by simply updating the `authToken` property. For example, one could check on an interval that makes sense for your token lifespan whether the token is about to expire and update when necessary, for example:

```javascript
let token;

// Helper function to check whether your token will expire within one minute from now
function tokenWillExpireSoon() {
  const payload = JSON.parse(atob(token.split('.')[1]));
  const exp = payload.exp; // in seconds
  const now = Math.floor(Date.now() / 1000); // current time in seconds
  return exp - now <= 60;
}

function maybeUpdateToken() {
  if (!token || tokenWillExpireSoon(token)) {
    token = getToken(); // Generate or request your token, for more information check the token based security guide linked above.
    player.theoLive.authToken = token;
  }
}

maybeUpdateToken();
setInterval(maybeUpdateToken, 30000); // Check every 30 seconds
```

## Clearing the token

If the token isn't needed anymore, e.g. when switching to an unprotected distribution or a non-OptiView Live source altogether, the header can be simply removed as follows:

```javascript
player.theoLive.authToken = undefined;
```

## Known limitations

### Safari on iOS <17

Apple devices running an iOS version lower than 17.1 do not support [MSE](https://developer.mozilla.org/en-US/docs/Web/API/Media_Source_Extensions_API), therefore the player must fall back to Safari's built-in HLS support. Since the player is no longer making the HTTP requests by itself, it cannot automatically append the necessary `Authorization` header.

To continue using token based security on those devices, we recommend either switching to long-lived tokens, or using a service worker to intercept the HTTP requests and append the header in your code.

#### Long-lived tokens

For JWT tokens that are valid for the entire duration of a typical playback session, you can continue using the `authToken` API as normal. When the player uses Safari's native HLS support, it will automatically append the token as a *query parameter* to the URL, and the OptiView Live backend will use that instead of the `Authorization` header to authenticate the viewer.

Note that the player **cannot change** the query parameter on the stream without interrupting playback. Hence, the token must not expire before the end of the playback session.

> **Note**
>
> Long-lived tokens are supported as of version 11.3.0 of the OptiView Player Web SDK.

#### Short-lived tokens using service worker

For JWT tokens with a short validity duration, you will need to register a service worker that intercepts the HTTP requests made by Safari's native HLS playback and append the necessary `Authorization` header.

This requires the player to make all HTTP requests with [CORS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/cors/introduction.md) enabled. Make sure to set [the `crossOrigin` property](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TypedSource#crossOrigin) on your OptiView Live source:

```javascript
player.source = {
  sources: {
    type: 'theolive',
    src: 'your-channel-id',
    crossOrigin: 'anonymous',
  },
};
```

A code snippet for the service worker code is shared below.

> **Note**
>
> Service worker registration is only possible in a secure environment (`https://`) or on `localhost`. There can also only be one service worker active, so if your environment or application already has a service worker active, you will need to include the additional functionality in that service worker.

iOS Safari service worker

```javascript
self.addEventListener('install', () => {
  console.log('Service worker installed!');
  self.skipWaiting();
});

self.addEventListener('activate', (event) => {
  console.log('Service Worker activated');
  // Claim clients so the service worker is in effect immediately
  event.waitUntil(self.clients.claim());
});

// Intercept the fetch event and add in your JWT
self.addEventListener('fetch', (event) => {
  try {
    const url = new URL(event.request.url);
    if (!url.origin.endsWith('theo.live')) {
      // Requests not made by the player for playback of the OptiView Live distribution should not be modified.
      return;
    }
    const token = getToken(); // Generate or request your token. For more information, check the token based security guide linked above.
    // Clone the request and add the JWT header
    const modifiedHeaders = new Headers(event.request.headers);
    modifiedHeaders.set('Authorization', `Bearer ${token}`);
    const modifiedRequest = new Request(event.request, {
      headers: modifiedHeaders,
    });
    return event.respondWith(fetch(modifiedRequest));
  } catch (error) {
    console.error('Error in fetch handler:', error);
    return event.respondWith(new Response('Service Worker Error', { status: 500 }));
  }
});
```

> **Note**
>
> In order for the service worker to be able to intercept requests made from the player library, its scope must include the player SDK files. That means the player and service worker must be hosted on the same path or the player must be hosted in a subfolder of the path where the service worker is hosted.

To register this service worker in to your code, you can attach it this way.

Register service worker

```javascript
async function registerServiceWorker() {
  if (!('serviceWorker' in navigator)) {
    console.error('Service worker not supported!');
    return;
  }
  const serviceWorkerScope = '/service/worker/path'; // Replace with your own path to the service worker location.
  const serviceWorkerPath = '${root}/service-worker.js'; // Replace with the filename of your service worker.

  // We recommend unregistering actively before (re-)registering as we've seen issues where hard reloads could cause issues if the service worker wasn't unregistered.
  const oldRegistration = await navigator.serviceWorker.getRegistration(serviceWorkerPath);
  await oldRegistration?.unregister();

  try {
    const registration = await navigator.serviceWorker.register(serviceWorkerPath, {
      scope: serviceWorkerScope,
    });
    if (registration.active) console.log('Service worker registered!');
  } catch (err) {
    console.error('Could not register service worker!', err);
  }
}

// Initialise the service worker some time early in the process.
if (!(window.MediaSource || window.ManagedMediaSource)) {
  registerServiceWorker();
}
```

The snippet above assumes the existence of a function `getToken()` that generates a JSON Web Token (JWT) and signs it using the default HMAC SHA-256 algorithm. [(Refer to docs on jwt.io)](https://jwt.io/introduction). In pseudocode:

```javascript
const getToken = async () => {
  const YOUR_JWT_SIGNING_KEY = 'YOUR-SIGNING-KEY-GOES-HERE';
  const payload = {
    exp: Math.floor(Date.now() / 1000) + 300, // 5 minutes
  };

  return await sign(payload, YOUR_JWT_SIGNING_KEY);
};
```

You can use an existing library like [Jose](https://github.com/panva/jose), or you can use our example implementation:

JWT `sign` function

```js
const base64UrlEncode = (str) => {
  return btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
};

const utf8ToUint8Array = (str) => {
  return new TextEncoder().encode(str);
};

const sign = async (payload, secret) => {
  const header = { alg: 'HS256', typ: 'JWT' };

  const encodedHeader = base64UrlEncode(JSON.stringify(header));
  const encodedPayload = base64UrlEncode(JSON.stringify(payload));

  const data = `${encodedHeader}.${encodedPayload}`;
  const secretBytes = utf8ToUint8Array(secret);

  const key = await crypto.subtle.importKey('raw', secretBytes, { name: 'HMAC', hash: { name: 'SHA-256' } }, false, ['sign']);

  const signature = await crypto.subtle.sign({ name: 'HMAC' }, key, utf8ToUint8Array(data));

  const signatureStr = String.fromCharCode(...new Uint8Array(signature));

  return `${data}.${base64UrlEncode(signatureStr)}`;
};
```

> **Info**
>
> You can validate the token generated by inspecting it using the JWT decoder on [JWT.io](https://jwt.io/). The header and payload will be decoded immediately. If you provide your HMAC key, you can validate that the signature is also valid.

> **Note**
>
> If you are using a bundler such as Vite or Rollup etc, you will need to ensure that your service worker also gets copied to your output directory and is `registered` from the correct path.

### FairPlay-protected DRM streams on Safari

Currently, the OptiView Player Web SDK always uses Safari's built-in HLS support for FairPlay-protected DRM streams. As such, the same limitations apply as for [Safari versions without MSE](#safari-on-ios-17).

### Chromecast and AirPlay

When the player casts an OptiView Live stream to a remote receiver (such as Chromecast or AirPlay), it is no longer in control of the HTTP requests for that stream. As such, it cannot append the necessary `Authorization` header by itself, similar to [when using Safari's native HLS playback](#safari-on-ios-17).

We recommend using [long-lived tokens](#long-lived-tokens) to support remote playback. The player will automatically append the token as a query parameter to the URL when starting the remote session.

---

# Migrating from deprecated THEOlive player to THEOplayer on Web

The goal of this guide is to help you migrate from the deprecated [theolive player](https://www.npmjs.com/package/@theolive/player) to the recommended [THEOplayer](https://www.npmjs.com/package/theoplayer). If you haven't integrated with any player, please follow the [recommended](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/theolive/getting-started.md) guide instead of this one.

## Dependencies

First remove the old player dependency:

```text
npm uninstall @theolive/player
```

And replace with theoplayer using:

```text
npm install theoplayer
```

## Setting up a player

Player creation is quite similar, instead of

```javascript
const player = new THEOLive.Player(element);
```

Create the player like this:

```javascript
var player = new THEOplayer.Player(element, {
  license: 'your-license',
  // This is needed for fallback to work properly
  retryConfiguration: {
    maxRetries: 6,
  },
  theoLive: {
    // these are optional
    externalSessionId: 'my-external-session-id',
    fallbackEnabled: true,
  },
});
```

Note that you now need a license, either use the THEOplayer license you had before, or use the one provided in the [OptiView Live dashboard](https://dashboard.optiview.dolby.com) when creating a channel.

## Loading a channel

After setting up your THEOplayer on your web page, we will set the source to a channel. The old way was calling loadChannel on the player.

```javascript
player.loadChannel('<your-channel-id>').catch(console.error);
```

With THEOplayer you just set a [SourceDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TheoLiveSource).

```javascript
player.source = {
  sources: {
    type: 'theolive',
    src: 'your-channel-id',
  },
};
```

## Calling methods and listening to events

Most of the old functionality is right there on THEOplayer and can be found in the [THEOplayer docs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer). For OptiView Live specific API, check out [player.theolive](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TheoLiveApi).

## More information

* [API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TheoLiveSource)

---

# UI on Web

Choose the approach that fits your requirements:

* Use Open Video UI when you want a custom experience without building common player components yourself.
* Use the chromeless player when you want to start with no UI and build every control and interaction from scratch.
* Use the basic default UI when its ready-made controls meet your needs and one is available.

| Approach      | Starting point                 | Flexibility | Development effort |
| ------------- | ------------------------------ | ----------- | ------------------ |
| Open Video UI | Ready-made, modular components | High        | Moderate           |
| Chromeless    | Player API without a UI        | Complete    | Highest            |
| Default UI    | Complete basic player UI       | Basic       | Lowest             |

Building a chromeless UI means using the OptiView Player API and your own application code without a ready-made UI. You are responsible for adding every control, such as a play button, and connecting it to the player API, such as `player.play()`. This approach gives you total control over the UI and UX, but requires an understanding of video playback and the OptiView Player API.

## Choose your UI approach

The Web SDK supports three approaches, depending on how much you want to customize:

## [🧩Open Video UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md)

[Compose and style ready-made components for a custom, branded experience.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md)

## [🛠️Chromeless](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless.md)

[Start with no UI and implement every control and interaction yourself.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless.md)

## [▶️Default UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/default-ui.md)

[Start quickly with the basic, responsive controls included with the Web SDK.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/default-ui.md)

---

# Open Video UI for Web

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Open Video UI is the OptiView Player customization toolkit. It provides open-source, out-of-the-box components that you can compose and style to create a player UI that matches your product and brand.

Open Video UI has dedicated libraries for each supported platform, so your customized player feels native in your app. These pages explain how to get started and tailor the components to your requirements.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/getting-started.md)

[Start building your UI in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/guides)

[Learn how to integrate our rich set of features into your own UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/guides)

## [🛝Examples](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/examples)

[Find inspiration for your UI from our live demos!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/examples)

## [🗃React](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react.md)

[7 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/changelog.md)

[Find out what's new in Open Video UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/changelog.md)

## [\*️⃣API reference](https://theoplayer.github.io/web-ui/api/)

[Discover all components provided by Open Video UI for Web.](https://theoplayer.github.io/web-ui/api/)

## [![](/pr-932/img/github.svg)![](/pr-932/img/github_dark.svg)GitHub](https://github.com/THEOplayer/web-ui/)

[Browse the source code or report issues on GitHub.](https://github.com/THEOplayer/web-ui/)

---

# Getting started

## Installation

1. This project requires the THEOplayer Web SDK to be installed.

   ```sh
   npm install theoplayer
   ```

   You can also install a different variant of the THEOplayer npm package if you don't need all features, as long as it's aliased as `theoplayer`.

   ```sh
   npm install theoplayer@npm:@theoplayer/basic-hls
   ```

2. Install the Open Video UI for Web.
   ```sh
   npm install @theoplayer/web-ui
   ```

3. Add `@theoplayer/web-ui` to your app:

   * Option 1: in your HTML.
     ```html
     <script src="/path/to/node_modules/theoplayer/THEOplayer.chromeless.js"></script>
     <script src="/path/to/node_modules/@theoplayer/web-ui/dist/THEOplayerUI.js"></script>
     ```

   * Option 2: in your JavaScript.

     ```js
     import { DefaultUI } from '@theoplayer/web-ui';
     ```

     Open Video UI will import THEOplayer from `theoplayer/chromeless` and [Lit](https://lit.dev/) from `lit`. If you're using a bundler such as Webpack or Rollup, these dependencies should automatically get bundled with your web app. Alternatively, you can use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to let the browser resolve it:

     ```html
     <script type="importmap">
         {
             "imports": {
                 "theoplayer/chromeless": "/path/to/node_modules/theoplayer/THEOplayer.chromeless.esm.js",
                 "lit": "/path/to/node_modules/lit/index.js",
                 "lit/decorators.js": "/path/to/node_modules/lit/decorators.js",
                 "lit/directives/": "/path/to/node_modules/lit/directives/"
             }
         }
     </script>
     <!-- Import maps polyfill for browsers without import maps support (e.g. Safari 16.3) -->
     <script async src="https://ga.jspm.io/npm:es-module-shims@2.6.2/dist/es-module-shims.js" crossorigin="anonymous"></script>
     <script type="module" src="/path/to/my_app.js"></script>
     ```

## Usage

### Default UI

`<theoplayer-default-ui>` provides a fully-featured video player experience with minimal setup, and allows for small customizations such as changing colors or fonts.

* Option 1: in your HTML.
  ```html
  <theoplayer-default-ui
      configuration='{"libraryLocation":"/path/to/node_modules/theoplayer/","license":"your_theoplayer_license_goes_here"}'
      source='{"sources":{"src":"https://example.com/stream.m3u8"}}'
  ></theoplayer-default-ui>
  <script>
      // Optionally, access the underlying THEOplayer player instance
      const ui = document.querySelector('theoplayer-default-ui');
      ui.player.addEventListener('playing', () => console.log('THEOplayer is now playing'));
  </script>
  ```
* Option 2: in your JavaScript.
  ```js
  import { DefaultUI } from '@theoplayer/web-ui';
  const ui = new DefaultUI({
      libraryLocation: '/path/to/node_modules/theoplayer/',
      license: 'your_theoplayer_license_goes_here'
  });
  // Set a source for the player to play
  ui.source = {
      sources: {
          src: 'https://example.com/stream.m3u8'
      }
  };
  // Optionally, access the underlying THEOplayer player instance
  ui.player.addEventListener('playing', () => console.log('THEOplayer is now playing'));
  ```

See [this page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/examples/default-ui.md) for a complete example.

### Custom UI

If you want to fully customize your video player layout, you can use a `<theoplayer-ui>` instead.

```html
<theoplayer-ui
    configuration='{"libraryLocation":"/path/to/node_modules/theoplayer/","license":"your_theoplayer_license_goes_here"}'
    source='{"sources":{"src":"https://example.com/stream.m3u8"}}'
>
    <!-- Choose your own layout using the provided components (or your own!) -->
    <theoplayer-control-bar>
        <theoplayer-time-range></theoplayer-time-range>
    </theoplayer-control-bar>
    <theoplayer-control-bar>
        <theoplayer-play-button></theoplayer-play-button>
        <theoplayer-mute-button></theoplayer-mute-button>
        <theoplayer-volume-range></theoplayer-volume-range>
    </theoplayer-control-bar>
</theoplayer-ui>
```

See [this page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/examples/custom-ui.md) for a complete example.

### Legacy browser support

By default, Open Video UI for Web targets modern browsers that support modern JavaScript syntax (such as [async/await](https://caniuse.com/async-functions)) and native [Custom Elements](https://caniuse.com/custom-elementsv1). This keeps the download size small, so your viewers can spend less time waiting for your page to load and start watching their video faster.

On older browsers (such as Internet Explorer 11 and older smart TVs), you need to load a different version of the Open Video UI that uses older JavaScript syntax. You also need to load additional polyfills for missing features such as `Promise`, `Symbol.iterator` or Custom Elements:

* For ES2015 features like `Promise` and `Symbol.iterator`, we recommend [the Cloudflare mirror of Polyfill.io](https://cdnjs.cloudflare.com/polyfill/).

* For Custom Elements, we recommend loading our polyfill bundle from `@theoplayer/web-ui/polyfills`. Alternatively, you can load the [Web Components Polyfills](https://github.com/webcomponents/polyfills) along with [Lit's `polyfill-support` module](https://lit.dev/docs/v2/tools/requirements/#polyfills).

* Option 1: in your HTML. This uses [differential serving](https://css-tricks.com/differential-serving/) so modern browsers will load the modern build (with `type="module"`), while legacy browsers will load the legacy build (with `nomodule`).

  ```html
  <!-- Modern browsers -->
  <script type="importmap">
      {
          "imports": {
              "theoplayer/chromeless": "/path/to/node_modules/theoplayer/THEOplayer.chromeless.esm.js",
              "lit": "/path/to/node_modules/lit/index.js",
              "lit/decorators.js": "/path/to/node_modules/lit/decorators.js",
              "lit/directives/": "/path/to/node_modules/lit/directives/"
          }
      }
  </script>
  <!-- Import maps polyfill for browsers without import maps support (e.g. Safari 16.3) -->
  <script async src="https://ga.jspm.io/npm:es-module-shims@2.6.2/dist/es-module-shims.js" crossorigin="anonymous"></script>
  <script type="module" src="/path/to/node_modules/@theoplayer/web-ui/dist/THEOplayerUI.mjs"></script>
  <!-- Legacy browsers -->
  <script nomodule src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=es2015%2CglobalThis%2CReflect"></script>
  <script nomodule src="/path/to/node_modules/theoplayer/THEOplayer.chromeless.js"></script>
  <script nomodule src="/path/to/node_modules/@theoplayer/web-ui/dist/THEOplayerUI.polyfills.js"></script>
  <script nomodule src="/path/to/node_modules/@theoplayer/web-ui/dist/THEOplayerUI.es5.js"></script>
  ```

* Option 2: in your JavaScript. This will load the legacy build on both modern and legacy browsers, which is suboptimal. Instead, we recommend configuring your bundler to produce a modern and legacy build of your entire web app, and to import the appropriate version of Open Video UI for each build flavor.

  ```js
  import '@theoplayer/web-ui/polyfills';
  import { DefaultUI } from '@theoplayer/web-ui/es5'; // note the "/es5" suffix
  ```

---

# Making a custom UI

Although the default UI was designed to support a variety of usage scenarios, you may still run into a case that it doesn't handle very well. Perhaps you want to move some buttons around, or add like and dislike buttons to the control bar, or perhaps integrate a text chat component inside your player. In these situations, you may want to build a custom player UI to create a truly unique experience for your viewers.

In this guide, you will build a custom player from scratch, starting from a basic player and gradually adding more features. Finally, we will look at some more complete examples of custom players, which you can use as reference for your own UI.

## A basic player

We'll start by making the most basic player possible: one with just a play button.

```html
<theoplayer-ui
    configuration='{"libraryLocation":"/path/to/node_modules/theoplayer/","license":"your_theoplayer_license_goes_here"}'
    source='{"sources":{"src":"https://example.com/stream.m3u8"}}'
>
    <theoplayer-play-button slot="centered-chrome"></theoplayer-play-button>
</theoplayer-ui>
```

The `<theoplayer-ui>` element is the main container of our custom UI. It handles creating and managing the underlying THEOplayer instance, using the `configuration` and `source` attributes set on the element.

It also provides a skeleton layout for plugging in our playback controls, using [slots](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_templates_and_slots#adding_flexibility_with_slots) such as `"top-chrome"` or `"centered-chrome"`. We place a `<theoplayer-play-button>` in the `"centered-chrome"` slot, so it will appear in the center of our player.

![Screenshot](/pr-932/assets/images/custom-ui-basic-3ae76115ff4424c1b7a6f79007843701.png)

Note that by default, the UI hides its controls when the user becomes inactive (i.e. does not interact with the player). If we want the play button to always remain visible, we can add a `no-auto-hide` attribute to it:

```html
<theoplayer-play-button slot="centered-chrome" no-auto-hide></theoplayer-play-button>
```

We can add more components so the user can mute or seek the player, or go fullscreen.

```html
<theoplayer-ui configuration="..." source="...">
    <theoplayer-play-button slot="centered-chrome"></theoplayer-play-button>
    <theoplayer-loading-indicator slot="centered-loading" no-auto-hide></theoplayer-loading-indicator>
    <theoplayer-control-bar>
        <theoplayer-time-range></theoplayer-time-range>
    </theoplayer-control-bar>
    <theoplayer-control-bar>
        <theoplayer-mute-button></theoplayer-mute-button>
        <theoplayer-time-display show-duration></theoplayer-time-display>
        <span style="flex-grow: 1"></span>
        <theoplayer-fullscreen-button></theoplayer-fullscreen-button>
    </theoplayer-control-bar>
</theoplayer-ui>
```

* `<theoplayer-loading-indicator>` is a circular loading spinner that is automatically shown when the player is waiting for more data. It is placed in the `"centered-loading"` slot, which appears in the center of the player but behind the `"centered-chrome"` elements. The `no-auto-hide` attribute ensures that it is visible even when all other controls are hidden.
* `<theoplayer-control-bar>` is a horizontal container for playback controls. It's not required that all controls are inside a `<theoplayer-control-bar>`, you can use any element such as a `<div>` or a `<section>`. This element does not have a `slot` attribute, so it is placed in the "default slot", at the bottom of the player.
* `<theoplayer-time-range>` is a seek bar, showing the player's current position in the video, and allowing the user to seek to a different time.
* `<theoplayer-mute-button>` is a button to mute or unmute the player's audio.
* `<theoplayer-time-display>` is a text showing the player's current position in hours, minutes and seconds. By adding the `show-duration` attribute, the text will also show the player's total video duration.
* `<theoplayer-fullscreen-button>` is a button to make the player take up the entire screen.
* The `<span>` with `flex-grow: 1` acts as a "spacer": it will stretch to fill the remaining space left by the other controls inside the `<theoplayer-control-bar>`. This works because `<theoplayer-control-bar>` is a flexbox container, i.e. it has `display: inline-flex`. The result is that the `<theoplayer-fullscreen-button>` will be aligned to the right side of the player.

![Screenshot](/pr-932/assets/images/custom-ui-seekbar-6b279b099c28754aa634a6a181b8c949.png)

## A mobile-ready player

All components are designed to work great on all device types. However, sometimes you may want to make certain buttons a little bigger on mobile, or move them around a bit to make them easier to reach with the touch of a finger instead of the click of a mouse cursor.

`<theoplayer-ui>` adds a `mobile` attribute to itself when it detects that the user is on a mobile device. You can use this attribute in your own CSS to change the size of all controls:

```css
/* Make controls bigger */
theoplayer-ui[mobile] {
    --theoplayer-control-height: 32px;
}
```

You can also use it to control the visibility of certain controls. To avoid having a CSS rule for each individual component, you can use a custom class or an attribute on those components instead:

```css
/* Hide mobile-hidden elements on mobile, and mobile-only elements on desktop */
theoplayer-ui[mobile] [mobile-hidden],
theoplayer-ui:not([mobile]) [mobile-only] {
    display: none !important;
}
```

```html
<theoplayer-ui configuration="..." source="...">
    <!-- This centered play button will only be shown on mobile -->
    <theoplayer-play-button slot="centered-chrome" mobile-only></theoplayer-play-button>
    <theoplayer-loading-indicator slot="centered-loading" no-auto-hide></theoplayer-loading-indicator>
    <theoplayer-control-bar>
        <theoplayer-time-range></theoplayer-time-range>
    </theoplayer-control-bar>
    <theoplayer-control-bar>
        <!-- This bottom play button will only be shown on desktop -->
        <theoplayer-play-button mobile-hidden></theoplayer-play-button>
        <theoplayer-mute-button></theoplayer-mute-button>
        <theoplayer-time-display show-duration></theoplayer-time-display>
        <span style="flex-grow: 1"></span>
        <theoplayer-fullscreen-button></theoplayer-fullscreen-button>
    </theoplayer-control-bar>
</theoplayer-ui>
```

To show chapter markers on a time range, add the `show-chapter-markers` attribute. Add a `<theoplayer-chapter-display>` next to the seek bar to display the current chapter title.

> **Why do I need to add the styles for `[mobile-hidden]` and `[mobile-only]` to my own CSS?**
>
> Due to limitations of the `::slotted()` CSS selector, `<theoplayer-ui>`'s own CSS rules can only affect *directly* slotted elements. Descendant elements of a slotted element, such as a `<theoplayer-play-button mobile-hidden>` inside of a slotted `<theoplayer-control-bar>` cannot be targeted by such selectors.

| ![Screenshot on desktop](/pr-932/assets/images/custom-ui-desktop-81909d06ea425103824bb1035e0b80df.png) | ![Screenshot on mobile](/pr-932/assets/images/custom-ui-mobile-c33fba60bea7b749b93527d3fd408ae0.png) |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Desktop                                                                                                | Mobile                                                                                               |

## A player for livestreams

Not every control makes sense for every stream. A livestream without a DVR window cannot be seeked, so a seek bar or a playback speed setting would be useless. Conversely, a button to seek back to the live point is only useful for a livestream.

`<theoplayer-ui>` detects the stream type of its current source, and reflects it as a `stream-type` attribute with value `"vod"`, `"live"` (a livestream without DVR) or `"dvr"` (a livestream with a DVR window). Elements can declare in which stream types they want to be shown using the `stream-type-only` and `stream-type-hidden` attributes, which take a space-separated list of stream types:

```html
<theoplayer-ui configuration="..." source="...">
    <theoplayer-control-bar>
        <!-- The seek bar is only useful if there's something to seek through -->
        <theoplayer-time-range stream-type-hidden="live"></theoplayer-time-range>
    </theoplayer-control-bar>
    <theoplayer-control-bar>
        <theoplayer-play-button></theoplayer-play-button>
        <!-- This button seeks back to the live point, so only show it for livestreams -->
        <theoplayer-live-button stream-type-only="live dvr"></theoplayer-live-button>
        <theoplayer-time-display show-duration stream-type-hidden="live"></theoplayer-time-display>
    </theoplayer-control-bar>
</theoplayer-ui>
```

For the most common cases, there are shorthand boolean attributes:

| Attribute     | Equivalent to                   | Element is hidden for           |
| ------------- | ------------------------------- | ------------------------------- |
| `live-only`   | `stream-type-only="live dvr"`   | VOD streams                     |
| `live-hidden` | `stream-type-hidden="live dvr"` | all livestreams                 |
| `dvr-only`    | `stream-type-only="dvr"`        | VOD and livestreams without DVR |
| `dvr-hidden`  | `stream-type-hidden="dvr"`      | livestreams with DVR            |

An element is hidden as soon as one of its attributes says it should be hidden, so combining attributes narrows down the stream types in which the element is shown. For example, `live-only dvr-hidden` shows the element for livestreams without DVR only. (Note that `live-hidden dvr-only` therefore hides the element for *every* stream type. To show an element for VOD and DVR streams only, use `stream-type-hidden="live"` instead.)

As with `mobile-hidden` and `mobile-only`, you need to copy these rules into your own CSS if you use them on elements nested inside a slotted element, such as a control bar:

```css
/* Hide elements which are not meant for the current stream type */
theoplayer-ui[stream-type='live'] [stream-type-hidden~='live'],
theoplayer-ui[stream-type='live'] [stream-type-only]:not([stream-type-only~='live']) {
    display: none !important;
}
```

## More examples

### Default UI

It may sound odd to mention the default UI when we're talking about custom UIs. But in fact, the default UI is built in *exactly the same way* as a custom one!

The default UI comes with all the bells and whistles that you'd expect from a fully-featured player: buttons to play or mute the video, a seek bar to seek through the video, menus to change the audio language and subtitles, and support for casting to Chromecast and AirPlay. It also has an adaptive layout that changes when used on desktop or on mobile, to provide the best experience for that device type.

Have a look at [`DefaultUI.html`](https://github.com/THEOplayer/web-ui/blob/main/src/DefaultUI.html) and [`DefaultUI.css`](https://github.com/THEOplayer/web-ui/blob/main/src/DefaultUI.css) to learn how the default layout is implemented, and perhaps copy some ideas for your own UI.

### Nitflex theme

The "Nitflex" theme shows an example of a fully customized player UI, inspired by a popular streaming platform. It has a custom layout for its playback controls, custom colors to match the brand's style, and even custom icons for its buttons.

Have a look at its [HTML](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/nitflex/demo.html) and [CSS](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/nitflex/nitflex.css) to see how it's done.

![Screenshot](/pr-932/assets/images/nitflex-theme-939d70606ef41c085fca43b882ecf806.png)

---

# Making a custom component

This guide demonstrates how to make your own custom components that integrate with the player, and which you can use in your own custom UI.

> **Note**
>
> We use [Lit](https://lit.dev/) to build all components in Open Video UI for Web, and we highly recommend it for your own custom components.
>
> You can also use a different library (like [Svelte](https://svelte.dev/docs/svelte/custom-elements)), or you can use the [Custom Element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) and [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) APIs directly.

## A custom play button

First, we'll build a simple button that plays or pauses the player when clicked.

> **Tip**
>
> The built-in [`<theoplayer-play-button>`](https://theoplayer.github.io/web-ui/api/classes/PlayButton.html) also provides this functionality.

### Step 1: Create a custom button

Create a new JavaScript file called `my-play-button.js` with the following code:

[my-play-button.js (step 1)](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/guides/web/custom-component/my-play-button-step1.js)

```js
import { Button } from '@theoplayer/web-ui';
import { html } from 'lit';

// Define a new class for our custom element.
// We extend the `Button` class from Open Video UI for Web,
// so we can inherit some logic and styles.
export class MyPlayButton extends Button {
    // This method is called whenever the button is (re-)rendered.
    // See: https://lit.dev/docs/components/rendering/
    render() {
        return html`Play`;
    }

    // This method is called whenever the button gets clicked.
    handleClick() {
        alert('My play button was clicked!');
    }
}

// Define our class as the constructor for our custom element.
// This allows us to use <my-play-button> anywhere in our HTML.
// If you're using TypeScript, you can also use
// Lit's @customElement decorator on the MyPlayButton class.
// See: https://lit.dev/docs/components/defining/
customElements.define('my-play-button', MyPlayButton);
```

Now add your new button to your custom UI. In our example, we'll place it in the `centered-chrome` slot, so it'll appear in the center of the player:

```html
<script type="module" src="./my-play-button.js"></script>
<theoplayer-ui
    configuration='{"libraryLocation":"/path/to/node_modules/theoplayer/","license":"your_theoplayer_license_goes_here"}'
    source='{"sources":{"src":"https://example.com/stream.m3u8"}}'
>
    <my-play-button slot="centered-chrome"></my-play-button>
</theoplayer-ui>
```

It should look something like this:

Try clicking the "Play" button in the middle of the screen. You should see an alert window popping up saying `My play button was clicked!`.

### Step 2: Integrate with the backing player

Of course, we want the player to start playing instead of showing an alert! For this, we need to get access to the backing THEOplayer instance.

Open Video UI for Web provides a built-in mechanism to automatically inject dependencies into UI components, such as the player instance, or other fullscreen state of the UI. When a UI component is added as a child (or descendant) of a `<theoplayer-default-ui>` or `<theoplayer-ui>`, the parent UI will automatically inject those dependencies.

First, the UI component needs to opt into this mechanism by [mixing in](https://www.typescriptlang.org/docs/handbook/mixins.html) `StateReceiverMixin` into its superclass (see [API documentation](https://theoplayer.github.io/web-ui/api/functions/StateReceiverMixin.html)). This mixin takes the original superclass, and an array of dependencies which need to be injected:

```js
import { Button, StateReceiverMixin } from '@theoplayer/web-ui';

export class MyPlayButton extends StateReceiverMixin(Button, ['player']) {
    // ...
}
```

> **For TypeScript users**
>
> If you're using TypeScript, you can also use the `@stateReceiver` decorator instead.
>
> ```typescript
> import { Button, stateReceiver } from '@theoplayer/web-ui';
>
> @stateReceiver(['player'])
> export class MyPlayButton extends Button {
>     // ...
> }
> ```

Once this button is added to a `<theoplayer-ui>`, it'll automatically receive the backing THEOplayer instance in its `player` property. If you want to do some custom logic when this happens, you can implement a setter for this property:

```js
export class MyPlayButton extends StateReceiverMixin(Button, ['player']) {
    set player(player) {
        this._player = player;
        console.log('My play button received a player!');
    }
}
```

Change your `handleClick()` method to call `play()` or `pause()` on the player:

[my-play-button.js (step 2)](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/guides/web/custom-component/my-play-button-step2.js)

```js
import { Button, StateReceiverMixin } from '@theoplayer/web-ui';
import { html } from 'lit';

export class MyPlayButton extends StateReceiverMixin(Button, ['player']) {
    constructor() {
        super();
        this._player = undefined;
    }

    get player() {
        return this._player;
    }
    set player(player) {
        this._player = player;
        console.log('My play button received a player!');
    }

    render() {
        return html`Play`;
    }

    handleClick() {
        if (!this._player) {
            // Not (yet) attached to a player.
            return;
        }
        // Toggle the player's playing state.
        if (this._player.paused) {
            this._player.play();
        } else {
            this._player.pause();
        }
    }
}

customElements.define('my-play-button', MyPlayButton);
```

It should look something like this:

Try clicking the "Play" button in the middle of the screen. The player starts playing!<br />Clicking it again should pause the player.

### Step 3: Update the button text

Notice that the button text always says "Play", even when the player is already playing. To fix this, we will need to add a [reactive property](https://lit.dev/docs/components/properties/) that we can use inside our `render()` method.

[my-play-button.js (step 3)](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/guides/web/custom-component/my-play-button-step3.js)

```js
import { Button, StateReceiverMixin } from '@theoplayer/web-ui';
import { html } from 'lit';

export class MyPlayButton extends StateReceiverMixin(Button, ['player']) {
    // Define our reactive properties.
    // See: https://lit.dev/docs/components/properties/
    static properties = {
        _paused: { state: true }
    };

    constructor() {
        super();
        this._player = undefined;
        this._paused = true;
    }

    get player() {
        return this._player;
    }
    set player(player) {
        this._player = player;
        console.log('My play button received a player!');
    }

    render() {
        // Show a different label depending on the paused state.
        return html`${this._paused ? 'Play' : 'Pause'}`;
    }

    handleClick() {
        if (!this._player) {
            // Not (yet) attached to a player.
            return;
        }
        // Toggle the player's playing state,
        // and update our paused state to trigger a re-render.
        if (this._player.paused) {
            this._player.play();
            this._paused = false;
        } else {
            this._player.pause();
            this._paused = true;
        }
    }
}

customElements.define('my-play-button', MyPlayButton);
```

> **For TypeScript users**
>
> If you're using TypeScript, you can also use the `@state` decorator instead.
>
> ```typescript
> import { Button } from '@theoplayer/web-ui';
> import { state } from 'lit';
>
> export class MyPlayButton extends Button {
>     @state()
>     private accessor _paused: boolean = true;
> }
> ```

It should look something like this:

Congratulations, you've built your very own play button! 🎉

## A custom quality label

Next, let's create a label that displays the resolution of the player's current video quality.

> **Tip**
>
> The built-in [`<theoplayer-active-quality-display>`](https://theoplayer.github.io/web-ui/api/classes/ActiveQualityDisplay.html) also provides this functionality.

### Step 1: Create a custom component

Create a new JavaScript file called `my-quality-label.js` with the following code:

[my-quality-label.js (step 1)](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/guides/web/custom-component/my-quality-label-step1.js)

```js
import { css, html, LitElement } from 'lit';

// This style will be applied to every <my-quality-label>.
const myQualityLabelStyle = css`
    /* This rule targets the element itself, i.e. <my-quality-label> */
    :host {
        /* Use the same text and background color as the rest of the UI controls */
        color: var(--theoplayer-text-color, #fff);
        background: var(--theoplayer-control-background, transparent);

        /* Add some padding */
        padding: var(--theoplayer-control-padding, 10px);
    }
`;

// Define a new class for our custom element.
export class MyQualityLabel extends LitElement {
    static styles = [myQualityLabelStyle];

    render() {
        // Show something (for testing)
        return html`1080p`;
    }
}

// Define our class as the constructor for our custom element.
// This allows us to use <my-quality-label> anywhere in our HTML.
customElements.define('my-quality-label', MyQualityLabel);
```

Now add your new label to your custom UI. In our example, we'll place it inside a `<theoplayer-control-bar>` in the default slot, so it'll appear at the bottom of the player:

```html
<script type="module" src="./my-quality-label.js"></script>
<theoplayer-ui
    configuration='{"libraryLocation":"/path/to/node_modules/theoplayer/","license":"your_theoplayer_license_goes_here"}'
    source='{"sources":{"src":"https://example.com/stream.m3u8"}}'
>
    <theoplayer-control-bar>
        <!-- A seek bar -->
        <theoplayer-time-range></theoplayer-time-range>
    </theoplayer-control-bar>
    <theoplayer-control-bar>
        <!-- A few commonly used built-in controls -->
        <theoplayer-play-button></theoplayer-play-button>
        <theoplayer-mute-button></theoplayer-mute-button>
        <!-- A spacer, to fill up the remaining space in the middle -->
        <span style="flex-grow: 1"></span>
        <!-- Your brand new quality label! -->
        <my-quality-label></my-quality-label>
        <!-- Some other controls -->
        <theoplayer-settings-menu-button menu="settings-menu"></theoplayer-settings-menu-button>
        <theoplayer-fullscreen-button></theoplayer-fullscreen-button>
    </theoplayer-control-bar>
    <!-- A settings menu, so you can manually change the active quality -->
    <theoplayer-settings-menu slot="menu" id="settings-menu"></theoplayer-settings-menu>
</theoplayer-ui>
```

It should look something like this:

### Step 2: Listen to quality changes

Right now, the quality label is static, it doesn't actually update when the player's quality changes. Let's fix that!

1. Once again, we use the `StateReceiverMixin` to gain access to the backing THEOplayer instance.
2. When we receive the player, we add an event listener for the `addtrack` event of `player.videoTracks`, so we'll be notified when the video track becomes available.
3. We register an `activequalitychanged` event listener on that video track, so we can respond when the active video quality changes.
4. When our `activequalitychanged` listener fires, we update the reactive property `this._activeVideoQuality`, which will trigger a re-render when changed.
5. When we re-render the component, we return an HTML template containing the active quality's height.

[my-quality-label.js (step 2)](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/guides/web/custom-component/my-quality-label-step2.js)

```js
import { StateReceiverMixin } from '@theoplayer/web-ui';
import { css, html, LitElement } from 'lit';

const myQualityLabelStyle = css`
    :host {
        color: var(--theoplayer-text-color, #fff);
        background: var(--theoplayer-control-background, transparent);
        padding: var(--theoplayer-control-padding, 10px);
    }
`;

export class MyQualityLabel extends StateReceiverMixin(LitElement, ['player']) {
    static styles = [myQualityLabelStyle];
    static properties = {
        _activeVideoQuality: { state: true }
    };

    constructor() {
        super();
        this._player = undefined;
        this._activeVideoTrack = undefined;
        this._activeVideoQuality = undefined;
    }

    get player() {
        return this._player;
    }
    set player(player) {
        if (this._player) {
            // Clean up
            this._player.videoTracks.removeEventListener('addtrack', this.handleAddTrack);
            this.updateActiveTrack(undefined);
        }
        this._player = player;
        if (this._player) {
            // Listen for the 'addtrack' event
            this._player.videoTracks.addEventListener('addtrack', this.handleAddTrack);
            // If the player already has an active video track,
            // start using it right away!
            if (this._player.videoTracks.length > 0) {
                this.updateActiveTrack(this._player.videoTracks[0]);
            }
        }
    }

    handleAddTrack = (event) => {
        this.updateActiveTrack(event.track);
    };
    updateActiveTrack(track) {
        if (this._activeVideoTrack) {
            // Clean up
            this._activeVideoTrack.removeEventListener('activequalitychanged', this.handleActiveQualityChanged);
        }
        this._activeVideoTrack = track;
        if (this._activeVideoTrack) {
            // Listen for the 'activequalitychanged' event
            this._activeVideoTrack.addEventListener('activequalitychanged', this.handleActiveQualityChanged);
            // If the track already has an active quality,
            // start using it right away!
            if (this._activeVideoTrack.activeQuality) {
                this.updateActiveQuality(this._activeVideoTrack.activeQuality);
            }
        }
    }

    handleActiveQualityChanged = (event) => {
        this.updateActiveQuality(event.quality);
    };
    updateActiveQuality(quality) {
        // Update our (reactive) internal state, which will trigger a re-render.
        this._activeVideoQuality = quality;
    }

    render() {
        if (this._activeVideoQuality) {
            // Show the quality's height in our <span>
            return html`${this._activeVideoQuality.height}p`;
        } else {
            // No active quality yet...
            return html``;
        }
    }
}

customElements.define('my-quality-label', MyQualityLabel);
```

It should look something like this:

Try changing the active quality by clicking the ⚙️ (Settings) button, and changing "Automatic" to a specific quality. You should see your custom label update to show the height of the new quality.

That's it! You now have your very own active quality label! 🥳

## Further reading

* [Intro to Lit](https://lit.dev/tutorials/intro-to-lit/)
* [Lit documentation](https://lit.dev/docs/)
* [Web components guide on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)

---

# Localization

The Open Video UI for Web can be localized to different languages, enabling you to reach audiences from different regions of the world.

Localization works by [registering one or more locales](#register-a-locale) and then [selecting one of the registered locales using the `lang` attribute](#select-a-language).

## Register a locale

A locale is a JavaScript object mapping translation IDs to translated messages. You can register a locale with the `addLocale` function:

French locale

```javascript
import { addLocale } from '@theoplayer/web-ui';

addLocale('fr', {
    playAria: 'lire',
    pauseAria: 'pauser',
    replayAria: 'revoir'
    // ...
});
```

Some messages may need to be formatted with one or more values, based on the configuration or active state of the player. For those messages, the translation ID maps to a JavaScript function that takes those values as arguments and returns the formatted translation.

French locale (continued)

```javascript
addLocale('fr', {
    // ...
    seekForwardAria: (offset) => `avancer de ${offset}`,
    seekBackwardAria: (offset) => `reculer de ${offset}`
    // ...
});
```

Refer to the [`Locale` interface definition](https://theoplayer.github.io/web-ui/api/interfaces/Locale.html) in the API references for the complete list of translatable messages.

## Select a language

The UI automatically selects the locale based on the `lang` attribute of the `<theoplayer-ui>` (or `<theoplayer-default-ui>`) element, or from the closest parent element with such an attribute.

The value of the `lang` attribute must exactly match the locale name as it was passed to `addLocale`.

Setting the language on the UI

```html
<theoplayer-default-ui lang="fr" source='{"sources":{"src":"https://example.com/stream.m3u8"}}'></theoplayer-default-ui>
```

You can also put the `lang` attribute on any parent element. For example, if the entire page is in French, you could put the attribute on the `<html>` element:

Setting the language on the HTML document

```html
<!doctype html>
<html lang="fr">
    <head>
        <title>Ma page</title>
    </head>
    <body>
        <theoplayer-default-ui source='{"sources":{"src":"https://example.com/stream.m3u8"}}'></theoplayer-default-ui>
    </body>
</html>
```

## Remarks

### Update translations when upgrading Open Video UI

Newer versions of the Open Video UI for Web may add new messages that need to be translated. We follow [semantic versioning](https://semver.org/), so new messages can only be added in *major* or *minor* versions.

When using custom translations in your app, we recommend pinning the `@theoplayer/web-ui` dependency in your app's `package.json` to a specific minor version using a tilde constraint (`~`). Avoid using a caret constraint (`^`), since this may cause upgrading past your currently selected minor version.

package.json

```json
{
    "dependencies": {
        "@theoplayer/web-ui": "~2.2.0"
    }
}
```

When you decide to upgrade Open Video UI to the latest version, make sure to also update your translations. Check the history for [`i18n/Locale.ts`](https://github.com/THEOplayer/web-ui/commits/main/src/i18n/Locale.ts) to see whether any messages were added or changed since the previous version.

---

# Debug display

The debug display is an overlay panel that shows playback diagnostics, such as the current source, quality, buffer health and live latency. It is meant for developers, and is not part of the main Open Video UI bundle.

![Screenshot of the debug display](/pr-932/assets/images/debug-display-b4f846bc4529afba0ae9f84f5cb8943c.png)

## Add it to your player

Import the separate `@theoplayer/web-ui/debug` entry point. This entry point is only available as an ES module.

```js
import '@theoplayer/web-ui/debug';
```

Then place a `<theoplayer-debug-display>` in the `overlay` slot of your UI. Optionally, add a `<theoplayer-debug-button>` to toggle the panel from the control bar.

```html
<theoplayer-default-ui configuration='{"libraryLocation":"..."}' source='{"sources":{"src":"..."}}'>
    <theoplayer-debug-display slot="overlay" hidden></theoplayer-debug-display>
    <theoplayer-debug-button slot="bottom-control-bar"></theoplayer-debug-button>
</theoplayer-default-ui>
```

If you use Open Video UI for React, see [Debug display in React](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react/guides/debug-display.md).

## Bookmarklet

To inspect a player on any website that uses Open Video UI, without changing its code, use the debug display bookmarklet. Create a new bookmark in your browser, and paste the following code as its URL:

```text
javascript:(()=>{const s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/@theoplayer/web-ui@2/dist/THEOplayerUI.debug.bookmarklet.js';document.head.append(s)})()
```

Click the bookmark on a page with an Open Video UI player to show the debug display. Click it again to hide it.

The bookmarklet requires Open Video UI for Web 2.6.0 or higher. It does not work on websites whose [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) blocks scripts from `cdn.jsdelivr.net`, nor on players inside a cross-origin iframe. It works on players inside same-origin iframes.

---

# Migrating to Open Video UI for Web 2.x

This article will guide you through updating to Open Video UI for Web version 2 (from version 1), and the changes needed in your code.

## Update dependencies

Run the following command to install Open Video UI for Web version 2:

```sh
npm install @theoplayer/web-ui@2
```

Open Video UI for Web now depends on [Lit version 3](https://www.npmjs.com/package/lit). If your project already uses Lit, make sure you use a compatible version.

## Update polyfill for legacy browsers

In version 1, we recommended loading the [Web Components Polyfills](https://github.com/webcomponents/polyfills) on legacy browsers that do not natively support the Custom Elements API.

As of version 2, Open Video UI for Web ships its own polyfill bundle, which includes:

* [Web Components Polyfills](https://github.com/webcomponents/polyfills)
* [Lit's `polyfill-support` module](https://lit.dev/docs/v2/tools/requirements/#polyfills)

We recommend switching to our polyfill bundle, so you'll always have all the necessary polyfills needed to support legacy browsers. Alternatively, [you can load these polyfills manually](https://github.com/THEOplayer/web-ui/blob/%40theoplayer/web-ui%402.0.0/src/polyfills.ts).

```diff
- import '@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js';
- import '@webcomponents/webcomponentsjs/webcomponents-bundle.js';
+ import '@theoplayer/web-ui/polyfills';
```

## Migrate to Lit for custom components

If you've written your own custom components that extend from built-in components provided by Open Video UI (such as the `Button` component), you may notice that these components now extend from [`LitElement`](https://lit.dev/docs/api/LitElement/). This allows you to use Lit's [reactive properties](https://lit.dev/docs/components/properties/) and [template-based rendering](https://lit.dev/docs/components/rendering/) to facilitate developing your custom components.

Previously, your custom component would need to pass a `<template>` element to the built-in component to customize the rendered content.

Custom component in version 1.x

```js
import { Button, buttonTemplate } from '@theoplayer/web-ui';

const myButtonCss = `:host { color: red; }`;
const template = document.createElement('template');
template.innerHTML = buttonTemplate('Custom content', myButtonCss);

export class MyCustomButton extends Button {
    constructor() {
        super({ template });
    }

    handleClick() {
        alert('My custom button was clicked!');
    }
}
```

Now, you can override the `render` method instead and return an [`html`](https://lit.dev/docs/api/static-html/#html) template. To add styles, you can add a [`static styles` property](https://lit.dev/docs/components/styles/).

Custom component in version 2.x

```js
import { Button } from '@theoplayer/web-ui';
import { html, css } from 'lit';

export class MyCustomButton extends Button {
    static styles = [
        ...Button.styles,
        css`
            :host {
                color: red;
            }
        `
    ];

    constructor() {
        super();
    }

    render() {
        return html`Custom content`;
    }

    handleClick() {
        alert('My custom button was clicked!');
    }
}
```

> **Note**
>
> The old constructor-based API is still supported in version 2, although we highly recommend switching to the `render` method.

See the [updated custom component guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/guides/custom-component.md) for more information.

---

# Default UI

Source: Big Buck Bunny (bigBuckBunny)

Override device type:

This sample demonstrates the default UI of the player without any modifications.

Code

```html
<theoplayer-default-ui
    configuration='{"libraryLocation":"/path/to/theoplayer/","license":"your_theoplayer_license"}'
    source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"},"textTracks":[{"default":true,"src":"https://cdn.theoplayer.com/video/big_buck_bunny/thumbnails.vtt","label":"thumbnails","kind":"metadata"}]}'
    fluid
></theoplayer-default-ui>
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/default-ui/demo.html)

---

# Advertisements

Override device type:

The default UI has full support for advertisements.

During playback, it shows yellow ad markers on the seek bar to indicate the times when the content will be interrupted by an ad. While playing an ad, the UI shows ad-specific controls such as a skip button and a countdown. These controls are also mobile-aware, for example a dedicated clickthrough button replaces the regular clickthrough behavior on desktop.

Code

```js
var ui = document.querySelector('theoplayer-default-ui');
ui.source = {
    sources: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8',
    ads: [
        {
            sources: {
                src: 'https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/vmap_ad_samples&sz=640x480&cust_params=sample_ar%3Dpremidpostpod&ciu_szs=300x250&gdfp_req=1&ad_rule=1&output=vmap&unviewed_position_start=1&env=vp&impl=s&cmsid=496&vid=short_onecue&correlator=',
                type: 'vmap'
            }
        }
    ]
};
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/ads/demo.html)

---

# Styling the default UI

## Christmas theme

Source: Big Buck Bunny (bigBuckBunny)

Override device type:

---

# Removing controls

Source: Big Buck Bunny (bigBuckBunny)

Override device type:

This sample demonstrates how to remove a specific control from the default UI. The default UI exposes its internal controls as [CSS shadow parts](https://developer.mozilla.org/en-US/docs/Web/CSS/::part), so you can hide any of them with `::part()`. Here, we hide the seek bar and keep the rest.

Code

```html
<style>
    /* Hide the seek bar. */
    theoplayer-default-ui::part(time-range) {
        display: none;
    }
</style>

<theoplayer-default-ui
    configuration='{"libraryLocation":"/path/to/theoplayer/","license":"your_theoplayer_license"}'
    source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"}}'
    fluid
></theoplayer-default-ui>
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/remove-controls/demo.html)

---

# Localization

Language: English (en)

This sample demonstrates localizing the UI and switching language at runtime. A locale is registered with `addLocale`, and the language is selected through the `lang` attribute. Use the dropdown below the player to switch between English and Dutch. See also the [localization guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/guides/localization.md).

Code

```html
<script type="module">
    import { addLocale } from '@theoplayer/web-ui';

    addLocale('nl', {
        playAria: 'afspelen',
        pauseAria: 'pauzeren',
        languageMenuHeading: 'Taal',
        subtitleMenuHeading: 'Ondertitels',
        subtitleOff: 'Uit',
        settingsMenuHeading: 'Instellingen'
    });
</script>

<theoplayer-default-ui
    id="ui"
    lang="en"
    configuration='{"libraryLocation":"/path/to/theoplayer/","license":"your_theoplayer_license"}'
    source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"}}'
></theoplayer-default-ui>

<select id="lang-select">
    <option value="en">English</option>
    <option value="nl">Nederlands (Dutch)</option>
</select>

<script>
    document.querySelector('#lang-select').addEventListener('change', (event) => {
        document.querySelector('#ui').setAttribute('lang', event.target.value);
    });
</script>
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/localization/demo.html)

---

# Custom UI

Source: Big Buck Bunny (bigBuckBunny)

Override device type:

This sample demonstrates a basic custom UI.

Code

```html
<theoplayer-ui
    configuration='{"libraryLocation":"/path/to/theoplayer/","license":"your_theoplayer_license"}'
    source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"},"textTracks":[{"default":true,"src":"https://cdn.theoplayer.com/video/big_buck_bunny/thumbnails.vtt","label":"thumbnails","kind":"metadata"}]}'
    fluid
>
    <theoplayer-control-bar slot="top-chrome" class="top-chrome">
        <span class="title">Big Buck Bunny</span>
        <span class="spacer"></span>
        <theoplayer-language-menu-button menu="language-menu" mobile-only></theoplayer-language-menu-button>
        <theoplayer-settings-menu-button menu="settings-menu" mobile-only></theoplayer-settings-menu-button>
        <theoplayer-airplay-button mobile-only></theoplayer-airplay-button>
        <theoplayer-chromecast-button mobile-only></theoplayer-chromecast-button>
    </theoplayer-control-bar>
    <theoplayer-loading-indicator slot="centered-loading" no-auto-hide></theoplayer-loading-indicator>
    <div slot="centered-chrome" class="centered-chrome">
        <theoplayer-play-button></theoplayer-play-button>
    </div>
    <div class="bottom-chrome">
        <theoplayer-control-bar>
            <theoplayer-time-range></theoplayer-time-range>
        </theoplayer-control-bar>
        <theoplayer-control-bar>
            <theoplayer-play-button mobile-hidden></theoplayer-play-button>
            <theoplayer-mute-button></theoplayer-mute-button>
            <theoplayer-volume-range mobile-hidden></theoplayer-volume-range>
            <theoplayer-time-display show-duration></theoplayer-time-display>
            <span class="spacer"></span>
            <theoplayer-language-menu-button menu="language-menu" mobile-hidden></theoplayer-language-menu-button>
            <theoplayer-settings-menu-button menu="settings-menu" mobile-hidden></theoplayer-settings-menu-button>
            <theoplayer-airplay-button mobile-hidden></theoplayer-airplay-button>
            <theoplayer-chromecast-button mobile-hidden></theoplayer-chromecast-button>
            <theoplayer-fullscreen-button></theoplayer-fullscreen-button>
        </theoplayer-control-bar>
    </div>
    <theoplayer-language-menu id="language-menu" slot="menu" hidden></theoplayer-language-menu>
    <theoplayer-settings-menu id="settings-menu" slot="menu" hidden></theoplayer-settings-menu>
    <theoplayer-error-display slot="error"></theoplayer-error-display>
</theoplayer-ui>
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/custom-ui/demo.html)

---

# Custom UI: Nitflex theme

Source: Big Buck Bunny (bigBuckBunny)

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/nitflex/demo.html)

---

# Custom UI: Portrait theme

Video by [cottonbro studio](https://www.pexels.com/video/the-art-of-skateboarding-2791956/).

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/portrait/demo.html)

---

# Text tracks and subtitles

This example demonstrates the text track components for subtitle selection and styling.

The settings menu contains four submenus:

* **Subtitles**: the idiomatic `<theoplayer-track-radio-group track-type="subtitles" show-off>`, which composes `<theoplayer-text-track-off-radio-button>` and `<theoplayer-text-track-radio-button>` for you.
* **Subtitles (custom)**: the same picker built manually from `<theoplayer-text-track-off-radio-button>` and `<theoplayer-text-track-radio-button>`.
* **Subtitle appearance**: the pre-built `<theoplayer-text-track-style-menu>`, which composes `<theoplayer-text-track-style-display>`, `<theoplayer-text-track-style-radio-group>` and `<theoplayer-text-track-style-reset-button>`.
* **Font color (custom)**: a single style option built manually from `<theoplayer-text-track-style-radio-group>` and `<theoplayer-text-track-style-reset-button>`.

Code

```html
<theoplayer-ui
    configuration='{"libraryLocation":"/path/to/theoplayer/","license":"your_theoplayer_license"}'
    source='{"sources":{"src":"https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8"},"metadata":{"title":"Elephant&apos;s Dream"}}'
>
    <theoplayer-control-bar>
        <theoplayer-play-button></theoplayer-play-button>
        <theoplayer-mute-button></theoplayer-mute-button>
        <theoplayer-volume-range></theoplayer-volume-range>
        <theoplayer-time-display show-duration></theoplayer-time-display>
        <theoplayer-language-menu-button menu="language-menu"></theoplayer-language-menu-button>
        <theoplayer-menu-button menu="settings-menu">CC</theoplayer-menu-button>
        <theoplayer-fullscreen-button></theoplayer-fullscreen-button>
    </theoplayer-control-bar>

    <theoplayer-language-menu id="language-menu" slot="menu" hidden></theoplayer-language-menu>

    <theoplayer-menu-group id="settings-menu" slot="menu" hidden>
        <theoplayer-menu>
            <span slot="heading">Subtitles &amp; captions</span>
            <theoplayer-menu-button menu="subtitle-menu"><span>Select</span></theoplayer-menu-button>
            <theoplayer-menu-button menu="subtitle-style-menu">
                <theoplayer-text-track-style-display property="fontColor"></theoplayer-text-track-style-display>
            </theoplayer-menu-button>
        </theoplayer-menu>

        <!-- Idiomatic subtitle picker (composes TextTrackOffRadioButton + TextTrackRadioButton). -->
        <theoplayer-menu id="subtitle-menu" menu-close-on-input hidden>
            <span slot="heading">Subtitles</span>
            <theoplayer-track-radio-group track-type="subtitles" show-off></theoplayer-track-radio-group>
        </theoplayer-menu>

        <!-- Pre-built subtitle style menu. -->
        <theoplayer-text-track-style-menu id="subtitle-style-menu" menu-close-on-input hidden>
            <span slot="heading">Subtitle appearance</span>
        </theoplayer-text-track-style-menu>

        <!-- Manual font color submenu (TextTrackStyleRadioGroup + TextTrackStyleResetButton). -->
        <theoplayer-menu id="font-color-menu" menu-close-on-input hidden>
            <theoplayer-text-track-style-reset-button slot="heading"></theoplayer-text-track-style-reset-button>
            <span slot="heading">Font color (custom)</span>
            <theoplayer-text-track-style-radio-group property="fontColor">
                <theoplayer-radio-button value="">Default</theoplayer-radio-button>
                <theoplayer-radio-button value="rgb(255,255,0)">Yellow</theoplayer-radio-button>
                <theoplayer-radio-button value="rgb(0,255,255)">Cyan</theoplayer-radio-button>
            </theoplayer-text-track-style-radio-group>
        </theoplayer-menu>
    </theoplayer-menu-group>

    <theoplayer-error-display slot="error"></theoplayer-error-display>
</theoplayer-ui>
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/text-tracks/demo.html)

---

# Modern UI

Source: Big Buck Bunny (bigBuckBunny)

This sample demonstrates a modern, streaming-service style custom UI: a centered playback "pill" with rewind, play/pause and forward, a full-width seek bar, and rounded translucent control clusters.

Code

```html
<theoplayer-ui
    configuration='{"libraryLocation":"/path/to/theoplayer/","license":"your_theoplayer_license"}'
    source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"},"metadata":{"title":"Big Buck Bunny"}}'
>
    <div slot="centered-chrome">
        <div class="pill center-pill">
            <theoplayer-seek-button seek-offset="-10"></theoplayer-seek-button>
            <theoplayer-play-button></theoplayer-play-button>
            <theoplayer-seek-button seek-offset="10"></theoplayer-seek-button>
        </div>
    </div>
    <div class="bottom-chrome">
        <theoplayer-control-bar>
            <theoplayer-time-range></theoplayer-time-range>
        </theoplayer-control-bar>
        <div class="bottom-row">
            <span class="pill">
                <theoplayer-play-button></theoplayer-play-button>
                <span class="volume">
                    <theoplayer-mute-button></theoplayer-mute-button>
                    <theoplayer-volume-range></theoplayer-volume-range>
                </span>
                <theoplayer-time-display show-duration></theoplayer-time-display>
            </span>
            <span class="spacer"></span>
            <span class="pill">
                <theoplayer-language-menu-button menu="language-menu"></theoplayer-language-menu-button>
                <theoplayer-fullscreen-button></theoplayer-fullscreen-button>
            </span>
        </div>
    </div>
    <theoplayer-language-menu id="language-menu" slot="menu" hidden></theoplayer-language-menu>
    <theoplayer-error-display slot="error"></theoplayer-error-display>
</theoplayer-ui>
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/modern/demo.html)

---

# Custom play button

Source: Big Buck Bunny (bigBuckBunny)

This sample demonstrates a custom, animated play button.

Code

```html
<style>
    .big-play {
        color: #fff;
        background: rgba(124, 58, 237, 0.45);
        backdrop-filter: blur(6px);
        border-radius: 50%;
        padding: 32px;
        transition: transform 0.4s ease;
    }
    .big-play svg {
        width: 64px;
        height: 64px;
    }
    /* Only pulse while hovered. */
    .big-play:hover {
        animation: pulse 3s ease-in-out infinite;
    }
    @keyframes pulse {
        0%, 100% { transform: scale(1); }
        50% { transform: scale(1.06); }
    }
</style>

<theoplayer-ui
    configuration='{"libraryLocation":"/path/to/theoplayer/","license":"your_theoplayer_license"}'
    source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"}}'
>
    <div slot="centered-chrome">
        <theoplayer-play-button class="big-play">
            <svg slot="play-icon" viewBox="0 0 24 24" width="28" height="28" fill="currentColor"><path d="M8 5v14l11-7z"></path></svg>
            <svg slot="pause-icon" viewBox="0 0 24 24" width="28" height="28" fill="currentColor"><path d="M6 5h4v14H6zM14 5h4v14h-4z"></path></svg>
        </theoplayer-play-button>
    </div>
    <div class="bottom-chrome">
        <theoplayer-control-bar>
            <theoplayer-time-range></theoplayer-time-range>
        </theoplayer-control-bar>
        <theoplayer-control-bar>
            <theoplayer-play-button></theoplayer-play-button>
            <theoplayer-mute-button></theoplayer-mute-button>
            <theoplayer-volume-range></theoplayer-volume-range>
            <theoplayer-time-display show-duration></theoplayer-time-display>
            <theoplayer-fullscreen-button></theoplayer-fullscreen-button>
        </theoplayer-control-bar>
    </div>
    <theoplayer-error-display slot="error"></theoplayer-error-display>
</theoplayer-ui>
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/custom-play-button/demo.html)

---

# Open Video UI for React

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Open Video UI is the OptiView Player customization toolkit. It provides open-source, out-of-the-box components that you can compose and style to create a player UI that matches your product and brand.

Open Video UI has dedicated libraries for each supported platform, so your customized player feels native in your app. These pages explain how to get started and tailor the components to your requirements.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react/getting-started.md)

[Start building your UI in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react/guides)

[Learn how to integrate our rich set of features into your own UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react/guides)

## [🛝Examples](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react/examples)

[Find inspiration for your UI from our live demos!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react/examples)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react/changelog.md)

[Find out what's new in Open Video UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react/changelog.md)

## [\*️⃣API reference](https://theoplayer.github.io/web-ui/react-api/)

[Discover all components and hooks provided by Open Video UI for React.](https://theoplayer.github.io/web-ui/react-api/)

## [![](/pr-932/img/github.svg)![](/pr-932/img/github_dark.svg)GitHub](https://github.com/THEOplayer/web-ui/tree/main/react/)

[Browse the source code or report issues on GitHub.](https://github.com/THEOplayer/web-ui/tree/main/react/)

---

# Getting started

## Installation

1. This project requires the THEOplayer Web SDK to be installed.

   ```sh
   npm install theoplayer
   ```

   You can also install a different variant of the THEOplayer npm package if you don't need all features, as long as it's aliased as `theoplayer`.

   ```sh
   npm install theoplayer@npm:@theoplayer/basic-hls
   ```

2. Install the Open Video UI for React.
   ```sh
   npm install @theoplayer/react-ui
   ```

3. Add `@theoplayer/react-ui` to your app:
   ```jsx
   import { DefaultUI } from '@theoplayer/react-ui';
   ```
   Open Video UI will import THEOplayer from `theoplayer/chromeless`. If you're using a bundler such as Webpack or Rollup, this dependency should automatically get bundled with your web app.

## Usage

### Default UI

`<DefaultUI>` provides a fully-featured video player experience with minimal setup, and allows for small customizations such as changing colors or fonts.

```tsx
import { DefaultUI } from '@theoplayer/react-ui';
import type { ChromelessPlayer } from 'theoplayer/chromeless';

const App = () => {
    // Configure THEOplayer
    const configuration = {
        libraryLocation: '/path/to/node_modules/theoplayer/',
        license: 'your_theoplayer_license_goes_here'
    };
    // Configure a source for the player to play
    const source = {
        sources: {
            src: 'https://example.com/stream.m3u8'
        }
    };
    // Optionally, access the underlying THEOplayer player instance
    const onReady = (player: ChromelessPlayer) => {
        player.addEventListener('playing', () => console.log('THEOplayer is now playing'));
    };

    return <DefaultUI configuration={configuration} source={source} onReady={onReady} />;
};
```

See [this page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react/examples/default-ui.md) for a complete example.

### Custom UI

If you want to fully customize your video player layout, you can use a `<UIContainer>` instead.

```tsx
import { ControlBar, MuteButton, PlayButton, TimeRange, VolumeRange } from '@theoplayer/react-ui';

const App = () => {
    const configuration = {
        libraryLocation: '/path/to/node_modules/theoplayer/',
        license: 'your_theoplayer_license_goes_here'
    };
    const source = {
        sources: {
            src: 'https://example.com/stream.m3u8'
        }
    };

    return (
        <UIContainer
            configuration={configuration}
            source={source}
            bottomChrome={
                <>
                    {/* Choose your own layout using the provided components (or your own!) */}
                    <ControlBar>
                        <TimeRange />
                    </ControlBar>
                    <ControlBar>
                        <PlayButton />
                        <MuteButton />
                        <VolumeRange />
                    </ControlBar>
                </>
            }
        />
    );
};
```

See [this page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react/examples/custom-ui.md) for a complete example.

### Legacy browser support

By default, Open Video UI for React targets modern browsers that support modern JavaScript syntax (such as [async/await](https://caniuse.com/async-functions)) and native [Custom Elements](https://caniuse.com/custom-elementsv1). This keeps the download size small, so your viewers can spend less time waiting for your page to load and start watching their video faster.

On older browsers (such as Internet Explorer 11 and older smart TVs), you need to load a different version of the Open Video UI that uses older JavaScript syntax. You also need to load additional polyfills for missing features such as `Promise`, `Symbol.iterator` or Custom Elements:

* For ES2015 features like `Promise` and `Symbol.iterator`, we recommend [the Cloudflare mirror of Polyfill.io](https://cdnjs.cloudflare.com/polyfill/).
* For Custom Elements, we recommend loading our polyfill bundle from `@theoplayer/web-ui/polyfills`. Alternatively, you can load the [Web Components Polyfills](https://github.com/webcomponents/polyfills) along with [Lit's `polyfill-support` module](https://lit.dev/docs/v2/tools/requirements/#polyfills).

The simplest way to do this is to load the legacy build instead:

```tsx
import '@theoplayer/web-ui/polyfills';
import { DefaultUI } from '@theoplayer/react-ui/es5'; // note the "/es5" suffix
```

However, this will load unnecessary polyfills in modern browsers, which is suboptimal. Instead, we recommend configuring your bundler to produce a modern and legacy build of your entire web app, and to import the appropriate version of Open Video UI for each build flavor.

---

# Localization

The Open Video UI for React can be localized to different languages, enabling you to reach audiences from different regions of the world.

Localization works by [registering one or more locales](#register-a-locale) and then [selecting one of the registered locales using the `lang` prop](#select-a-language).

## Register a locale

A locale is a JavaScript object mapping translation IDs to translated messages. You can register a locale with the `addLocale` function:

French locale

```javascript
import { addLocale } from '@theoplayer/react-ui';

addLocale('fr', {
    playAria: 'lire',
    pauseAria: 'pauser',
    replayAria: 'revoir'
    // ...
});
```

Some messages may need to be formatted with one or more values, based on the configuration or active state of the player. For those messages, the translation ID maps to a JavaScript function that takes those values as arguments and returns the formatted translation.

French locale (continued)

```javascript
addLocale('fr', {
    // ...
    seekForwardAria: (offset) => `avancer de ${offset}`,
    seekBackwardAria: (offset) => `reculer de ${offset}`
    // ...
});
```

Refer to the [`Locale` interface definition](https://theoplayer.github.io/web-ui/react-api/interfaces/Locale.html) in the API references for the complete list of translatable messages.

## Select a language

The UI automatically selects the locale based on the `lang` prop of the `<UIContainer>` (or `<DefaultUI>`) component.

The value of the `lang` prop must exactly match the locale name as it was passed to `addLocale`.

Setting the language on the UI

```jsx
<DefaultUI lang="fr" source={{ sources: { src: 'https://example.com/stream.m3u8' } }} />
```

## Remarks

### Update translations when upgrading Open Video UI

Newer versions of the Open Video UI for React may add new messages that need to be translated. We follow [semantic versioning](https://semver.org/), so new messages can only be added in *major* or *minor* versions.

When using custom translations in your app, we recommend pinning the `@theoplayer/react-ui` dependency in your app's `package.json` to a specific minor version using a tilde constraint (`~`). Avoid using a caret constraint (`^`), since this may cause upgrading past your currently selected minor version.

package.json

```json
{
    "dependencies": {
        "@theoplayer/react-ui": "~2.2.0"
    }
}
```

When you decide to upgrade Open Video UI to the latest version, make sure to also update your translations. Check the history for [`i18n/Locale.ts`](https://github.com/THEOplayer/web-ui/commits/main/src/i18n/Locale.ts) to see whether any messages were added or changed since the previous version.

---

# Using with Preact

The Open Video UI for React also works with [Preact](https://preactjs.com/), without any changes to your code. All you need to do is alias `react` (and `react-dom`) to `preact/compat`, as you would for any other React library.

## Alias React to Preact

Preact's documentation explains [how to set up the alias](https://preactjs.com/guide/v10/getting-started#aliasing-react-to-preact) for the most common bundlers, such as Vite, Webpack and Rollup. Once configured, you can import and use the Open Video UI for React as usual:

```jsx
import { DefaultUI } from '@theoplayer/react-ui';

const App = () => <DefaultUI configuration={configuration} source={source} />;
```

## Without a bundler

If you're not using a bundler, you can alias `react` to `preact/compat` [using an import map](https://preactjs.com/guide/v10/getting-started#aliasing-with-import-maps) instead:

```html
<script type="importmap">
    {
        "imports": {
            "preact": "https://esm.sh/preact@10",
            "preact/hooks": "https://esm.sh/preact@10/hooks",
            "preact/compat": "https://esm.sh/preact@10/compat",
            "react": "https://esm.sh/preact@10/compat",
            "react-dom/client": "https://esm.sh/preact@10/compat/client"
        }
    }
</script>
```

See [examples/preact/default-ui.html](https://github.com/THEOplayer/web-ui/blob/main/examples/preact/default-ui.html) for a complete example.

---

# Debug display

The debug display is an overlay panel that shows playback diagnostics, such as the current source, quality, buffer health and live latency. It is meant for developers, and is not part of the main Open Video UI bundle.

![Screenshot of the debug display](/pr-932/assets/images/debug-display-b4f846bc4529afba0ae9f84f5cb8943c.png)

## Add it to your player

Import `DebugDisplay` and `DebugButton` from the separate `@theoplayer/react-ui/debug` entry point. This entry point is only available as an ES module.

Pass the `DebugDisplay` to the `overlay` prop of your `DefaultUI` or `THEOliveDefaultUI`. Optionally, add a `DebugButton` to toggle the panel from the control bar.

```jsx
import { DefaultUI } from '@theoplayer/react-ui';
import { DebugButton, DebugDisplay } from '@theoplayer/react-ui/debug';

const App = () => {
    return (
        <DefaultUI
            configuration={{ libraryLocation: '...' }}
            source={{ sources: { src: '...' } }}
            overlay={<DebugDisplay hidden />}
            bottomControlBar={<DebugButton />}
        />
    );
};
```

To inspect a player on any website without changing its code, use the [debug display bookmarklet](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/guides/debug-display.md#bookmarklet).

---

# Migrating to Open Video UI for React 2.x

This article will guide you through updating to Open Video UI for React version 2 (from version 1), and the changes needed in your code.

## Update dependencies

Run the following command to install Open Video UI for React version 2:

```sh
npm install @theoplayer/react-ui@2
```

Open Video UI for React now depends on [Lit version 3](https://www.npmjs.com/package/lit). If your project already uses Lit, make sure you use a compatible version.

## Update polyfill for legacy browsers

In version 1, we recommended loading the [Web Components Polyfills](https://github.com/webcomponents/polyfills) on legacy browsers that do not natively support the Custom Elements API.

As of version 2, Open Video UI for React ships its own polyfill bundle, which includes:

* [Web Components Polyfills](https://github.com/webcomponents/polyfills)
* [Lit's `polyfill-support` module](https://lit.dev/docs/v2/tools/requirements/#polyfills)

We recommend switching to our polyfill bundle, so you'll always have all the necessary polyfills needed to support legacy browsers. Alternatively, [you can load these polyfills manually](https://github.com/THEOplayer/web-ui/blob/%40theoplayer/react-ui%402.0.0/src/polyfills.ts).

```diff
- import '@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js';
- import '@webcomponents/webcomponentsjs/webcomponents-bundle.js';
+ import '@theoplayer/web-ui/polyfills';
```

---

# Default UI

Source: Big Buck Bunny (bigBuckBunny)

Override device type:

This sample demonstrates the default UI of the player without any modifications.

Code

```jsx
import {DefaultUI} from '@theoplayer/react-ui'

const configuration = {
    libraryLocation: "/path/to/theoplayer/",
    license: "your_theoplayer_license"
};

const source = {
    sources: {src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8'},
    metadata: {
        title: "Big Buck Bunny"
    }
};

const App = () => {
    return <DefaultUI configuration={configuration} source={source}/>;
};
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/react/default-ui/demo.html)

---

# Removing controls

Source: Big Buck Bunny (bigBuckBunny)

Override device type:

This sample demonstrates how to remove a specific control from the default UI. The default UI exposes its internal controls as [CSS shadow parts](https://developer.mozilla.org/en-US/docs/Web/CSS/::part), so you can hide any of them with `::part()` — here we hide the seek bar and keep the rest.

Code

```jsx
import { DefaultUI } from '@theoplayer/react-ui';

// In your stylesheet, hide the seek bar by targeting its shadow part:
//
//   theoplayer-default-ui::part(time-range) {
//       display: none;
//   }

const configuration = {
    libraryLocation: '/path/to/theoplayer/',
    license: 'your_theoplayer_license'
};

const source = {
    sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8' },
    metadata: { title: 'Big Buck Bunny' }
};

const App = () => {
    return <DefaultUI configuration={configuration} source={source} />;
};
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/react/remove-controls/demo.html)

---

# Localization

Language: English (en)

This sample demonstrates localizing the UI and switching language at runtime. A locale is registered with `addLocale`, and the language is selected through the `lang` prop. Use the dropdown below the player to switch between English and Dutch. See also the [localization guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/react/guides/localization.md).

Code

```jsx
import { useState } from 'react';
import { DefaultUI, addLocale } from '@theoplayer/react-ui';

const configuration = {
    libraryLocation: '/path/to/theoplayer/',
    license: 'your_theoplayer_license'
};

const source = {
    sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8' },
    metadata: { title: 'Big Buck Bunny' }
};

// Register the Dutch locale. Untranslated messages fall back to the built-in English defaults.
addLocale('nl', {
    playAria: 'afspelen',
    pauseAria: 'pauzeren',
    languageMenuHeading: 'Taal',
    subtitleMenuHeading: 'Ondertitels',
    subtitleOff: 'Uit',
    settingsMenuHeading: 'Instellingen'
    // ...
});

const App = () => {
    const [lang, setLang] = useState('en');
    return (
        <>
            <DefaultUI configuration={configuration} source={source} lang={lang} />
            <select value={lang} onChange={(event) => setLang(event.target.value)}>
                <option value="en">English</option>
                <option value="nl">Nederlands (Dutch)</option>
            </select>
        </>
    );
};
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/react/localization/demo.html)

---

# Custom UI

Source: Big Buck Bunny (bigBuckBunny)

This sample demonstrates a basic custom UI.

Code

```jsx
import * as THEOplayerReactUI from '@theoplayer/react-ui';

const configuration = {
    libraryLocation: '/path/to/theoplayer/',
    license: 'your_theoplayer_license'
};

const source = {
    sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8' },
    metadata: {
        title: "Big Buck Bunny"
    }
};

const Spacer = () => {
    return <span style={{ flexGrow: 1 }} />;
};

const App = () => {
    return (
        <THEOplayerReactUI.UIContainer
            configuration={configuration}
            source={source}
            topChrome={
                <THEOplayerReactUI.ControlBar>
                    <span className="my-title">{title}</span>
                </THEOplayerReactUI.ControlBar>
            }
            centeredChrome={<THEOplayerReactUI.PlayButton />}
            centeredLoading={<THEOplayerReactUI.LoadingIndicator />}
            bottomChrome={
                <>
                    <THEOplayerReactUI.ControlBar>
                        <THEOplayerReactUI.TimeRange />
                    </THEOplayerReactUI.ControlBar>
                    <THEOplayerReactUI.ControlBar>
                        <THEOplayerReactUI.PlayButton />
                        <THEOplayerReactUI.MuteButton />
                        <THEOplayerReactUI.VolumeRange />
                        <THEOplayerReactUI.TimeDisplay />
                        <Spacer />
                        <THEOplayerReactUI.LanguageMenuButton menu="language-menu" />
                        <THEOplayerReactUI.SettingsMenuButton menu="settings-menu" />
                        <THEOplayerReactUI.FullscreenButton />
                    </THEOplayerReactUI.ControlBar>
                </>
            }
            menu={
                <>
                    <THEOplayerReactUI.LanguageMenu id="language-menu" />
                    <THEOplayerReactUI.SettingsMenu id="settings-menu" />
                </>
            }
            error={<THEOplayerReactUI.ErrorDisplay />}
        />
    );
};
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/react/custom-ui/demo.html)

---

# Text tracks and subtitles

This example demonstrates the text track components for subtitle selection and styling.

The settings menu contains four submenus:

* **Subtitles**: the idiomatic `TrackRadioGroup` with `trackType="subtitles"` and `show-off`, which composes `TextTrackOffRadioButton` and `TextTrackRadioButton` for you.
* **Subtitles (custom)**: the same picker built manually from `TextTrackOffRadioButton` and `TextTrackRadioButton`.
* **Subtitle appearance**: the pre-built `TextTrackStyleMenu`, which composes `TextTrackStyleDisplay`, `TextTrackStyleRadioGroup` and `TextTrackStyleResetButton`.
* **Font color (custom)**: a single style option built manually from `TextTrackStyleRadioGroup` and `TextTrackStyleResetButton`.

Code

```jsx
import * as THEOplayerReactUI from '@theoplayer/react-ui';
import { useContext, useEffect, useState } from 'react';

const configuration = {
    libraryLocation: '/path/to/theoplayer/',
    license: 'your_theoplayer_license'
};

const source = {
    sources: { src: 'https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8' },
    metadata: { title: "Elephant's Dream" }
};

// A hook returning the player's subtitle text tracks.
const useSubtitleTracks = () => {
    const player = useContext(THEOplayerReactUI.PlayerContext);
    const [tracks, setTracks] = useState([]);
    useEffect(() => {
        if (!player) return;
        const textTracks = player.textTracks;
        const update = () => {
            setTracks(textTracks.filter((t) => t.kind === 'subtitles' || t.kind === 'captions'));
        };
        update();
        textTracks.addEventListener(['addtrack', 'removetrack'], update);
        return () => textTracks.removeEventListener(['addtrack', 'removetrack'], update);
    }, [player]);
    return { player, tracks };
};

// A subtitle picker built from the low-level TextTrackOffRadioButton and TextTrackRadioButton.
// In practice, prefer <TrackRadioGroup trackType="subtitles" show-off />, which composes these for you.
const CustomSubtitlePicker = () => {
    const { player, tracks } = useSubtitleTracks();
    return (
        <THEOplayerReactUI.RadioGroup>
            <THEOplayerReactUI.TextTrackOffRadioButton trackList={player?.textTracks} />
            {tracks.map((track) => (
                <THEOplayerReactUI.TextTrackRadioButton key={track.uid} track={track} />
            ))}
        </THEOplayerReactUI.RadioGroup>
    );
};

const FONT_COLORS = [
    { label: 'Default', value: '' },
    { label: 'White', value: 'rgb(255,255,255)' },
    { label: 'Yellow', value: 'rgb(255,255,0)' },
    { label: 'Green', value: 'rgb(0,255,0)' },
    { label: 'Cyan', value: 'rgb(0,255,255)' },
    { label: 'Blue', value: 'rgb(0,0,255)' },
    { label: 'Magenta', value: 'rgb(255,0,255)' },
    { label: 'Red', value: 'rgb(255,0,0)' },
    { label: 'Black', value: 'rgb(0,0,0)' }
];

const App = () => {
    return (
        <THEOplayerReactUI.UIContainer
            configuration={configuration}
            source={source}
            bottomChrome={
                <THEOplayerReactUI.ControlBar>
                    <THEOplayerReactUI.PlayButton />
                    <THEOplayerReactUI.MuteButton />
                    <THEOplayerReactUI.VolumeRange />
                    <THEOplayerReactUI.TimeDisplay />
                    <THEOplayerReactUI.LanguageMenuButton menu="language-menu" />
                    <THEOplayerReactUI.MenuButton menu="settings-menu">CC</THEOplayerReactUI.MenuButton>
                    <THEOplayerReactUI.FullscreenButton />
                </THEOplayerReactUI.ControlBar>
            }
            menu={
                <>
                    <THEOplayerReactUI.LanguageMenu id="language-menu" />
                    <THEOplayerReactUI.MenuGroup id="settings-menu">
                        <THEOplayerReactUI.Menu heading="Subtitles & captions">
                            <THEOplayerReactUI.MenuButton menu="subtitle-menu">
                                <span>Select</span>
                            </THEOplayerReactUI.MenuButton>
                            <THEOplayerReactUI.MenuButton menu="subtitle-style-menu">
                                <THEOplayerReactUI.TextTrackStyleDisplay property="fontColor" />
                            </THEOplayerReactUI.MenuButton>
                        </THEOplayerReactUI.Menu>

                        {/* Idiomatic subtitle picker using TrackRadioGroup. */}
                        <THEOplayerReactUI.Menu id="subtitle-menu" closeOnInput hidden heading="Subtitles">
                            <THEOplayerReactUI.TrackRadioGroup trackType="subtitles" show-off />
                        </THEOplayerReactUI.Menu>

                        {/* Manual subtitle picker using TextTrackOffRadioButton and TextTrackRadioButton. */}
                        <THEOplayerReactUI.Menu id="subtitle-custom-menu" closeOnInput hidden heading="Subtitles (custom)">
                            <CustomSubtitlePicker />
                        </THEOplayerReactUI.Menu>

                        {/* Pre-built subtitle style menu. */}
                        <THEOplayerReactUI.TextTrackStyleMenu
                            id="subtitle-style-menu"
                            closeOnInput
                            hidden
                            heading="Subtitle appearance"
                        />

                        {/* Manual font color submenu using TextTrackStyleRadioGroup and TextTrackStyleResetButton. */}
                        <THEOplayerReactUI.Menu id="font-color-menu" closeOnInput hidden heading="Font color (custom)">
                            <THEOplayerReactUI.TextTrackStyleResetButton slot="heading" />
                            <THEOplayerReactUI.TextTrackStyleRadioGroup property="fontColor">
                                {FONT_COLORS.map(({ label, value }) => (
                                    <THEOplayerReactUI.RadioButton key={value} value={value}>
                                        {label}
                                    </THEOplayerReactUI.RadioButton>
                                ))}
                            </THEOplayerReactUI.TextTrackStyleRadioGroup>
                        </THEOplayerReactUI.Menu>
                    </THEOplayerReactUI.MenuGroup>
                </>
            }
            error={<THEOplayerReactUI.ErrorDisplay />}
        />
    );
};
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/react/text-tracks/demo.html)

---

# Modern UI

Source: Big Buck Bunny (bigBuckBunny)

This sample demonstrates a modern, streaming-service style custom UI: a centered playback pill with rewind, play/pause and forward, a full-width seek bar, and rounded translucent control clusters.

Code

```jsx
import * as THEOplayerReactUI from '@theoplayer/react-ui';

const configuration = {
    libraryLocation: '/path/to/theoplayer/',
    license: 'your_theoplayer_license'
};

const source = {
    sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8' },
    metadata: { title: 'Big Buck Bunny' }
};

const Spacer = () => <span className="spacer" />;

const App = () => {
    return (
        <THEOplayerReactUI.UIContainer
            configuration={configuration}
            source={source}
            centeredChrome={
                <div className="pill center-pill">
                    <THEOplayerReactUI.SeekButton seekOffset={-10} />
                    <THEOplayerReactUI.PlayButton />
                    <THEOplayerReactUI.SeekButton seekOffset={10} />
                </div>
            }
            centeredLoading={<THEOplayerReactUI.LoadingIndicator />}
            bottomChrome={
                <div className="bottom-chrome">
                    <THEOplayerReactUI.ControlBar>
                        <THEOplayerReactUI.TimeRange />
                    </THEOplayerReactUI.ControlBar>
                    <div className="bottom-row">
                        <span className="pill">
                            <THEOplayerReactUI.PlayButton />
                            <span className="volume">
                                <THEOplayerReactUI.MuteButton />
                                <THEOplayerReactUI.VolumeRange />
                            </span>
                            <THEOplayerReactUI.TimeDisplay showDuration />
                        </span>
                        <Spacer />
                        <span className="pill">
                            <THEOplayerReactUI.LanguageMenuButton menu="language-menu" />
                            <THEOplayerReactUI.FullscreenButton />
                        </span>
                    </div>
                </div>
            }
            menu={<THEOplayerReactUI.LanguageMenu id="language-menu" />}
            error={<THEOplayerReactUI.ErrorDisplay />}
        />
    );
};
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/react/modern/demo.html)

---

# Custom play button

Source: Big Buck Bunny (bigBuckBunny)

This sample demonstrates a custom, animated play button. The play/pause icons are overridden through the button's named slots, and the button is styled as a circular badge that gently pulses while the player is paused (the play button reflects its paused state as a `paused` attribute, which we target with CSS).

Code

```jsx
import * as THEOplayerReactUI from '@theoplayer/react-ui';

// In your stylesheet:
//   .big-play { border-radius: 50%; padding: 32px; background: rgba(124, 58, 237, 0.45); backdrop-filter: blur(6px); }
//   .big-play svg { width: 64px; height: 64px; }
//   .big-play:hover { animation: pulse 3s ease-in-out infinite; }  /* only pulse on hover */
//   @keyframes pulse { 0%, 100% { transform: scale(1); } 50% { transform: scale(1.06); } }

const configuration = {
    libraryLocation: '/path/to/theoplayer/',
    license: 'your_theoplayer_license'
};

const source = {
    sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8' },
    metadata: { title: 'Big Buck Bunny' }
};

const App = () => {
    return (
        <THEOplayerReactUI.UIContainer
            configuration={configuration}
            source={source}
            centeredChrome={
                <THEOplayerReactUI.PlayButton className="big-play">
                    <svg slot="play-icon" viewBox="0 0 24 24" width="28" height="28" fill="currentColor">
                        <path d="M8 5v14l11-7z" />
                    </svg>
                    <svg slot="pause-icon" viewBox="0 0 24 24" width="28" height="28" fill="currentColor">
                        <path d="M6 5h4v14H6zM14 5h4v14h-4z" />
                    </svg>
                </THEOplayerReactUI.PlayButton>
            }
            bottomChrome={
                <THEOplayerReactUI.ControlBar>
                    <THEOplayerReactUI.PlayButton />
                    <THEOplayerReactUI.MuteButton />
                    <THEOplayerReactUI.TimeDisplay showDuration />
                    <THEOplayerReactUI.FullscreenButton />
                </THEOplayerReactUI.ControlBar>
            }
            error={<THEOplayerReactUI.ErrorDisplay />}
        />
    );
};
```

[📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/react/custom-play-button/demo.html)

---

# @theoplayer/react-ui

## 2.7.0

### ✨ Features

* Added `ChapterDisplay` component. ([#208](https://github.com/THEOplayer/web-ui/pull/208))

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.7.0](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.7.0/CHANGELOG.md)

## 2.6.1

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.6.1](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.6.1/CHANGELOG.md)

## 2.6.0

### ✨ Features

* Added `overlay` prop to `DefaultUI` (and `THEOliveDefaultUI`). ([#200](https://github.com/THEOplayer/web-ui/pull/200))
* Added `@theoplayer/react-ui/debug` entry point with `DebugDisplay` and `DebugButton` components. ([#201](https://github.com/THEOplayer/web-ui/pull/201))

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.6.0](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.6.0/CHANGELOG.md)

## 2.5.0

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.5.0](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.5.0/CHANGELOG.md)

## 2.4.1

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.4.1](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.4.1/CHANGELOG.md)

## 2.4.0

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.4.0](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.4.0/CHANGELOG.md)

## 2.3.3

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.3.3](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.3.3/CHANGELOG.md)

## 2.3.2

### 🐛 Issues

* Fixed a brief tap highlight appearing on the seek bar on iOS Safari when tapping or scrubbing.
* When the player is muted, the volume bar now shows its minimum value, and dragging the volume bar now unmutes the player.

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.3.2](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.3.2/CHANGELOG.md)

## 2.3.1

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.3.1](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.3.1/CHANGELOG.md)

## 2.3.0

### ✨ Features

* Added 360°/VR support: `<theoplayer-vr-button>` and `<theoplayer-vr-compass>`, included by default in `<theoplayer-default-ui>`.

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.3.0](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.3.0/CHANGELOG.md)

## 2.2.0

### ✨ Features

* Added localization support. Use `addLocale()` to register a locale, and set the `lang` attribute on the UI to apply it.

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.2.0](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.2.0/CHANGELOG.md)

## 2.1.3

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.1.3](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.1.3/CHANGELOG.md)

## 2.1.2

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.1.2](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.1.2/CHANGELOG.md)

## 2.1.1

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.1.1](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.1.1/CHANGELOG.md)

## 2.1.0

### ✨ Features

* Added support for React 19.
* Added support for THEOplayer 11.x.

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.1.0](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.1.0/CHANGELOG.md)

## 2.0.0

### 💥 Breaking Changes

* Open Video UI for Web is now built using [Lit](https://lit.dev/).

  * This shouldn't affect any custom UIs or custom components built using Open Video UI for React.
  * For older browsers that don't support Custom Elements, we recommend loading our new polyfills library from `@theoplayer/web-ui/polyfills`.

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v2.0.0](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%402.0.0/CHANGELOG.md)

## 1.16.3

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v1.16.3](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%401.16.3/CHANGELOG.md)

## 1.16.2

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v1.16.2](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%401.16.2/CHANGELOG.md)

## 1.16.1

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v1.16.1](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%401.16.1/CHANGELOG.md)

## 1.16.0

### ✨ Features

* Added `centeredChrome` slot to `DefaultUI` to replace all controls in the center of the player.

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v1.16.0](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%401.16.0/CHANGELOG.md)

## 1.15.0

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v1.15.0](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%401.15.0/CHANGELOG.md)

## 1.14.0

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v1.14.0](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%401.14.0/CHANGELOG.md)

## 1.13.1

### 📦 Dependency Updates

* See changes to [Open Video UI for Web v1.13.1](https://github.com/THEOplayer/web-ui/blob/%40theoplayer%2Fweb-ui%401.13.1/CHANGELOG.md)

## 1.13.0 (2025-09-12)

* 🏠 See changes to [Open Video UI for Web v1.13.0](https://github.com/THEOplayer/web-ui/blob/v1.13.0/CHANGELOG.md)

## 1.12.0 (2025-09-10)

* 🏠 See changes to [Open Video UI for Web v1.12.0](https://github.com/THEOplayer/web-ui/blob/v1.12.0/CHANGELOG.md)

## 1.11.3 (2025-07-22)

* 🐛 Fix issue with the `<AdClickThroughButton>` component that was triggering the error `Failed to execute 'createElement' on 'Document': The result must not have attributes`. ([#106](https://github.com/THEOplayer/web-ui/pull/106))
* 🏠 See changes to [Open Video UI for Web v1.11.3](https://github.com/THEOplayer/web-ui/blob/v1.11.3/CHANGELOG.md)

## 1.11.2 (2025-06-30)

* 🏠 See changes to [Open Video UI for Web v1.11.2](https://github.com/THEOplayer/web-ui/blob/v1.11.2/CHANGELOG.md)

## 1.11.1 (2025-06-30)

* 🏠 See changes to [Open Video UI for Web v1.11.1](https://github.com/THEOplayer/web-ui/blob/v1.11.1/CHANGELOG.md)

## 1.11.0 (2025-06-12)

* 🏠 See changes to [Open Video UI for Web v1.11.0](https://github.com/THEOplayer/web-ui/blob/v1.11.0/CHANGELOG.md)

## 1.10.0 (2025-04-02)

* 🚀 Added support for THEOplayer 9.0.
* 🏠 See changes to [Open Video UI for Web v1.10.0](https://github.com/THEOplayer/web-ui/blob/v1.10.0/CHANGELOG.md)

## 1.9.5 (2025-03-20)

* 🏠 See changes to [Open Video UI for Web v1.9.5](https://github.com/THEOplayer/web-ui/blob/v1.9.5/CHANGELOG.md)

## 1.9.4 (2025-02-19)

* 🐛 Fixed `useCurrentTime` hook causing an infinite loop in Safari. ([#89](https://github.com/THEOplayer/web-ui/pull/89))
* 🏠 See changes to [Open Video UI for Web v1.9.4](https://github.com/THEOplayer/web-ui/blob/v1.9.4/CHANGELOG.md)

## 1.9.3 (2024-12-03)

* 🏠 See changes to [Open Video UI for Web v1.9.3](https://github.com/THEOplayer/web-ui/blob/v1.9.3/CHANGELOG.md)

## 1.9.2 (2024-11-20)

* 🏠 See changes to [Open Video UI for Web v1.9.2](https://github.com/THEOplayer/web-ui/blob/v1.9.2/CHANGELOG.md)

## 1.9.1 (2024-09-27)

* 🏠 See changes to [Open Video UI for Web v1.9.1](https://github.com/THEOplayer/web-ui/blob/v1.9.1/CHANGELOG.md)

## 1.9.0 (2024-09-06)

* 🚀 Added support for THEOplayer 8.0. ([#72](https://github.com/THEOplayer/web-ui/pull/72))
* 🏠 See changes to [Open Video UI for Web v1.9.0](https://github.com/THEOplayer/web-ui/blob/v1.9.0/CHANGELOG.md)

## 1.8.2 (2024-08-29)

* 🏠 See changes to [Open Video UI for Web v1.8.2](https://github.com/THEOplayer/web-ui/blob/v1.8.2/CHANGELOG.md)

## 1.8.1 (2024-04-18)

* 🐛 Fixed backing THEOplayer not always being destroyed on unmount. ([#59](https://github.com/THEOplayer/web-ui/issues/59), [#62](https://github.com/THEOplayer/web-ui/pull/62))
* 🏠 See changes to [Open Video UI for Web v1.8.1](https://github.com/THEOplayer/web-ui/blob/v1.8.1/CHANGELOG.md)

## 1.8.0 (2024-04-12)

* 💥 **Breaking Change**: This project now requires THEOplayer version 7.0.0 or higher. ([#60](https://github.com/THEOplayer/web-ui/pull/60))
* 🚀 Added `<THEOliveDefaultUI>` that provides a default UI for THEOlive streams. ([#58](https://github.com/THEOplayer/web-ui/pull/58))
* 🏠 See changes to [Open Video UI for Web v1.8.0](https://github.com/THEOplayer/web-ui/blob/v1.8.0/CHANGELOG.md)

## 1.7.2 (2024-03-18)

* 🐛 Fixed `topChrome`, `middleChrome` and `centeredChrome` slots not auto-hiding in `<UIContainer>`. ([#55](https://github.com/THEOplayer/web-ui/pull/55))
* 🐛 Fixed `no-auto-hide` attribute not working for React components. ([#55](https://github.com/THEOplayer/web-ui/pull/55))
* 🚀 Added `<SlotContainer>`. ([#55](https://github.com/THEOplayer/web-ui/pull/55))
* 🏠 See changes to [Open Video UI for Web v1.7.2](https://github.com/THEOplayer/web-ui/blob/v1.7.2/CHANGELOG.md)

## 1.7.1 (2024-02-15)

* 🐛 Fix "Warning: useLayoutEffect does nothing on the server" when using `@theoplayer/react-ui` in Node. ([#52](https://github.com/THEOplayer/web-ui/pull/52))
* 💅 Export `version` in public API. ([#53](https://github.com/THEOplayer/web-ui/pull/53))
* 💅 Allow importing `@theoplayer/react-ui/package.json`. ([#53](https://github.com/THEOplayer/web-ui/pull/53))
* 🏠 See changes to [Open Video UI for Web v1.7.1](https://github.com/THEOplayer/web-ui/blob/v1.7.1/CHANGELOG.md)

## 1.7.0 (2024-02-15)

* 🚀 Added support for loading in Node for static site generation (SSG) or server-side rendering (SSR). ([#50](https://github.com/THEOplayer/web-ui/pull/50))

  * This allows you to pass React components (such as `<DefaultUI>`, `<UIContainer>` or `<PlayButton>`) to the [Server React DOM APIs](https://react.dev/reference/react-dom/server), or to use them with a framework that supports SSG or SSR (such as Next.js, Remix or Gatsby).
  * ⚠️ The rendered HTML must still be [hydrated](https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html) on the client to load the Open Video UI properly. (Usually, this handled automatically by your React framework.)

* 🚀 Added utility hooks such as `useCurrentTime()`, `usePaused()` and `useVolume()`. ([#51](https://github.com/THEOplayer/web-ui/pull/51))
  * See [the API documentation](https://theoplayer.github.io/web-ui/react-api/) for more information.

* 🏠 See changes to [Open Video UI for Web v1.7.0](https://github.com/THEOplayer/web-ui/blob/v1.7.0/CHANGELOG.md)

## 1.6.0 (2024-02-08)

* 🚀 Initial release
* 🏠 See changes to [Open Video UI for Web v1.6.0](https://github.com/THEOplayer/web-ui/blob/v1.6.0/CHANGELOG.md)

---

# @theoplayer/web-ui

## 2.7.0

### ✨ Features

* Added chapter support.

  * The seek bar shows chapter markers when enabled with `<theoplayer-time-range show-chapter-markers>`.
  * `<theoplayer-chapter-display>` shows the current chapter title.
  * `<theoplayer-default-ui>` has both enabled by default. ([#208](https://github.com/THEOplayer/web-ui/pull/208))

### 🐛 Issues

* Fixed errors being thrown when removing `<theoplayer-ui>` or `<theoplayer-default-ui>` from the page. ([#208](https://github.com/THEOplayer/web-ui/pull/208))

## 2.6.1

### 🐛 Issues

* Fixed the debug display bookmarklet to also find players inside same-origin iframes. ([#206](https://github.com/THEOplayer/web-ui/pull/206))

## 2.6.0

### ✨ Features

* Added `overlay` slot to `<theoplayer-ui>` and `<theoplayer-default-ui>`. ([#200](https://github.com/THEOplayer/web-ui/pull/200))
* Added `<theoplayer-debug-display>`, available from the new `@theoplayer/web-ui/debug` entry point (ESM only). ([#200](https://github.com/THEOplayer/web-ui/pull/200))
* Added `version` property to `<theoplayer-ui>`, `<theoplayer-default-ui>` and `<theolive-default-ui>`. ([#201](https://github.com/THEOplayer/web-ui/pull/201))
* Added the `THEOplayerUI.debug.bookmarklet.js` script to inject the debug display into pages with Open Video UI. ([#201](https://github.com/THEOplayer/web-ui/pull/201))

## 2.5.0

### ✨ Features

* Qualities that are currently not [available](https://optiview.dolby.com/docs/theoplayer/v11/api-reference/web/interfaces/Quality.html#available) are now greyed out and can no longer be selected in the quality menu. ([#77](https://github.com/THEOplayer/web-ui/issues/77), [#194](https://github.com/THEOplayer/web-ui/pull/194))

### 🐛 Issues

* Fixed `<theoplayer-preview-time-display>` getting stuck when tapping the seek bar on iOS Safari. ([#173](https://github.com/THEOplayer/web-ui/issues/173), [#197](https://github.com/THEOplayer/web-ui/pull/197))
* Fixed an issue where a "false" string was shown in the quality menu for videos with a single quality. ([#193](https://github.com/THEOplayer/web-ui/pull/193))
* Fixed a bug where the preview time shown while hovering the seek bar did not match the time that the player actually seeks to when clicking. ([#121](https://github.com/THEOplayer/web-ui/issues/121), [#196](https://github.com/THEOplayer/web-ui/pull/196))

## 2.4.1

### 🐛 Issues

* User defined `textTrackStyle.marginBottom` and `marginTop` values are no longer reset when the control bar is shown or hidden.
* Fixed a bug where selecting a subtitle track in the language menu did not deselect the previously selected track, so multiple subtitle tracks could be shown at the same time. ([#187](https://github.com/THEOplayer/web-ui/issues/187), [#189](https://github.com/THEOplayer/web-ui/pull/189))

## 2.4.0

### ✨ Features

* Improved support for TV remote controls.
* Added `stream-type-only` and `stream-type-hidden` attributes to show or hide UI elements for specific stream types. Both attributes take a space-separated list of stream types, for example `stream-type-hidden="live"` hides an element for livestreams without DVR, while keeping it for VOD streams and for livestreams with DVR. The existing `live-only` and `live-hidden` attributes are now shorthands for `stream-type-only="live dvr"` and `stream-type-hidden="live dvr"`, and are complemented with new `dvr-only` and `dvr-hidden` attributes.

### 🐛 Issues

* `<theoplayer-default-ui>` no longer shows the seek buttons and the playback speed setting when playing a livestream without DVR.

## 2.3.3

### 🐛 Issues

* Fixed the `@theoplayer/web-ui/polyfills` export, which pointed to a non-existent file.

## 2.3.2

### 🐛 Issues

* Fixed a brief tap highlight appearing on the seek bar on iOS Safari when tapping or scrubbing.
* When the player is muted, the volume bar now shows its minimum value, and dragging the volume bar now unmutes the player.

## 2.3.1

### 🐛 Issues

* Added support for localizing the error message in `<theoplayer-error-display>`.

## 2.3.0

### ✨ Features

* Added 360°/VR support: `<theoplayer-vr-button>` and `<theoplayer-vr-compass>`, included by default in `<theoplayer-default-ui>`.

### 🐛 Issues

* Fixed an issue where the subtitles were briefly overlapping the control bar.

## 2.2.0

### ✨ Features

* Added localization support. Use `addLocale()` to register a locale, and set the `lang` attribute on the UI to apply it.

## 2.1.3

### 🐛 Issues

* Fixed infinite `SET_VOLUME` loop when casting to receivers that don't support master volume control.

## 2.1.2

### 🐛 Issues

* Fixed a brief tap highlight appearing behind button icons on iOS Safari.

## 2.1.1

### 🐛 Issues

* Fixed `<theoplayer-time-range>` repeatedly triggering seeks when updating its value from the player's current time, which caused noticeable stutters on Safari.

## 2.1.0

### ✨ Features

* Added support for THEOplayer 11.x.

## 2.0.0

### 💥 Breaking Changes

* Open Video UI for Web is now built using [Lit](https://lit.dev/).

  * All components now extend [`LitElement`](https://lit.dev/docs/api/LitElement/) and use [reactive rendering](https://lit.dev/docs/components/rendering/), making it much easier to build custom UI components. While existing custom UI components should mostly continue to work, we highly recommend updating them to use a `render()` method instead.
  * For older browsers that don't support Custom Elements, we recommend loading our new polyfills library from `@theoplayer/web-ui/polyfills`.

### ✨ Features

* Added settings menu to default UI.

## 1.16.3

### 🐛 Issues

* Improve labels for text tracks and audio tracks in the `<theoplayer-language-menu>`.

## 1.16.2

### 🐛 Issues

* Language names in the language menu are now capitalized according to that language's case mappings.

## 1.16.1

### 🐛 Issues

* Fixed a regression where menus would always fill the entire player on desktop (rather than opening as a small popup in the bottom right corner).

## 1.16.0

### ✨ Features

* Added `centered-chrome` slot to `<theoplayer-default-ui>` to replace all controls in the center of the player.

### 🐛 Issues

* Fixed an issue where buttons inside the default UI could accidentally be clicked even when they were hidden because of user inactivity.

## 1.15.0

### ✨ Features

* The UI now takes `SourceDescription.streamType` into account when computing its own `stream-type` attribute. This is now the preferred method of overriding the stream type.

### 🐛 Issues

* Fixed `<theolive-default-ui>` to stop using deprecated OptiView Live events.
* Fixed an issue where the `<theoplayer-time-range>` inside the default UI could accidentally be clicked even when it was hidden because of user inactivity.

## 1.14.0

### ✨ Features

* `<theoplayer-default-ui>` now hides all controls except the center play button when the player size is very small on desktop.
* Add `--theoplayer-centered-chrome-button-icon-width` CSS property to change the icon width of *only* the buttons in the center slot in a `<theoplayer-default-ui>`.
* Add `--theoplayer-aspect-ratio` CSS property to change the aspect ratio of a `<theoplayer-default-ui>` or `<theoplayer-ui>`.
* Add `--theoplayer-min-width` CSS property to override the `min-width` of a `<theoplayer-default-ui>` or `<theoplayer-ui>`.
* Add `--theoplayer-height` CSS property to override the height of the inner `<theoplayer-ui>` within a `<theoplayer-default-ui>`.

### 🐛 Issues

* Fixed an issue where the menus didn't cover the entire player when the player is too small.

## 1.13.1

### 🐛 Issues

* When entering fullscreen, the player will now always hide the browser's navigation UI. (This can be overridden by setting [`ui.fullscreenOptions.navigationUI`](https://optiview.dolby.com/docs/theoplayer/v10/api-reference/web/interfaces/FullscreenOptions.html#navigationUI) in your player configuration.)

## 1.13.0 (2025-09-12)

* 🚀 Added support for THEOplayer 10.0. ([#112](https://github.com/THEOplayer/web-ui/pull/112))

## 1.12.0 (2025-09-10)

* 🚀 Fill the entire window when fullscreen is not natively supported. ([#94](https://github.com/THEOplayer/web-ui/issues/94), [#110](https://github.com/THEOplayer/web-ui/pull/110))
* 🐛 Fix settings menu and subtitle options menu not displaying correctly on older smart TVs. ([#108](https://github.com/THEOplayer/web-ui/pull/108), [#109](https://github.com/THEOplayer/web-ui/pull/109))

## 1.11.3 (2025-07-22)

* 🐛 Fix issue with the `<theoplayer-ad-clickthrough-button>` component that was triggering the error `Failed to execute 'createElement' on 'Document': The result must not have attributes` when loaded into a React application. ([#106](https://github.com/THEOplayer/web-ui/pull/106))

## 1.11.2 (2025-06-30)

* 🚀 Add `--theoplayer-play-button-icon-color` CSS property to change the icon color of *only* the `<theoplayer-play-button>`. ([#104](https://github.com/THEOplayer/web-ui/pull/104))
* 🚀 Add `--theoplayer-center-play-button-icon-color` CSS property to change the icon color of *only* the centered play button in a `<theoplayer-default-ui>`. ([#104](https://github.com/THEOplayer/web-ui/pull/104))

## 1.11.1 (2025-06-30)

* 🐛 Fix pressing `Enter` on TV remote triggering click twice. ([#101](https://github.com/THEOplayer/web-ui/pull/101))
* 🚀 Add `error` slot to default UI, to allow for a custom error display. ([#102](https://github.com/THEOplayer/web-ui/pull/102))

## 1.11.0 (2025-06-12)

* 🚀 Add settings menu button to default UI. ([#99](https://github.com/THEOplayer/web-ui/pull/99))

## 1.10.0 (2025-04-02)

* 🚀 Added support for THEOplayer 9.0. ([#95](https://github.com/THEOplayer/web-ui/pull/95))

## 1.9.5 (2025-03-20)

* 💅 Forced subtitles are no longer shown in the subtitle menu. ([#92](https://github.com/THEOplayer/web-ui/pull/92))

## 1.9.4 (2025-02-19)

* No changes

## 1.9.3 (2024-12-03)

* 🚀 Added support for MBR Millicast streams. ([#81](https://github.com/THEOplayer/web-ui/pull/81))

## 1.9.2 (2024-11-20)

* 🐛 Fixed live UI not showing for Millicast streams. ([#79](https://github.com/THEOplayer/web-ui/pull/79))

## 1.9.1 (2024-09-27)

* 🐛 Fixed `Enter` and `Space` keys not working to activate buttons in the UI. ([#76](https://github.com/THEOplayer/web-ui/pull/76))

## 1.9.0 (2024-09-06)

* 🚀 Added support for THEOplayer 8.0. ([#72](https://github.com/THEOplayer/web-ui/pull/72))

## 1.8.2 (2024-08-29)

* 🐛 Fixed blank space below UI when using `<theoplayer-default-ui>`.

* 💅 Optimized performance of `<theoplayer-time-range>`. ([#70](https://github.com/THEOplayer/web-ui/issues/70))

  * Optimized the `requestAnimationFrame` callback used to update the seekbar's progress to avoid synchronous re-layouts as much as possible.
  * When playing a long video, the seek bar no longer uses `requestAnimationFrame` at all to update its progress. Instead, it updates using only less frequent `timeupdate` events.

## 1.8.1 (2024-04-18)

* 🐛 Fixed `ui.player.destroy()` not working. ([#59](https://github.com/THEOplayer/web-ui/issues/59), [#62](https://github.com/THEOplayer/web-ui/pull/62))

## 1.8.0 (2024-04-12)

* 💥 **Breaking Change**: This project now requires THEOplayer version 7.0.0 or higher. ([#60](https://github.com/THEOplayer/web-ui/pull/60))
* 🚀 Added `<theolive-default-ui>` that provides a default UI for THEOlive streams. ([#58](https://github.com/THEOplayer/web-ui/pull/58))

## 1.7.2 (2024-03-18)

* 🚀 Added `<theoplayer-slot-container>`. ([#55](https://github.com/THEOplayer/web-ui/pull/55))

## 1.7.1 (2024-02-15)

* 💅 Export `version` in public API. ([#53](https://github.com/THEOplayer/web-ui/pull/53))
* 💅 Allow importing `@theoplayer/web-ui/package.json`. ([#53](https://github.com/THEOplayer/web-ui/pull/53))

## 1.7.0 (2024-02-15)

* 🚀 Added support for loading in Node for static site generation (SSG) or server-side rendering (SSR). ([#50](https://github.com/THEOplayer/web-ui/pull/50))

  * ⚠️ Although the Node entry point exports all custom element classes as usual, attempting to actually construct those classes will result in errors. Most dependencies are either replaced with stubs (using [`@lit-labs/ssr-dom-shim`](https://lit.dev/docs/ssr/dom-emulation/)) or removed altogether (such as THEOplayer itself).
  * This should always be used together with an SSG or SSR solution. For example, you can use [Open Video UI for React](https://www.npmjs.com/package/@theoplayer/react-ui) together with [React server rendering](https://react.dev/reference/react-dom/server).

* 🐛 Fixed an issue where `<theoplayer-ui>` could throw an error when the player changes sources before all custom elements are properly registered. ([#49](https://github.com/THEOplayer/web-ui/pull/49))

## 1.6.0 (2024-02-08)

* 🚀 Introducing [Open Video UI for React](https://www.npmjs.com/package/@theoplayer/react-ui). ([#48](https://github.com/THEOplayer/web-ui/pull/48))
  * Idiomatic React components make the Open Video UI feel right at home in your existing React web app.
* 🚀 Added support for advertisements while casting to Chromecast. This requires THEOplayer version 6.8.0 or higher. ([#47](https://github.com/THEOplayer/web-ui/pull/47))
* 🚀 Added `theoplayerready` event to `<theoplayer-default-ui>` and `<theoplayer-ui>`, which is fired once the backing THEOplayer instance is created. ([#48](https://github.com/THEOplayer/web-ui/pull/48)).

## 1.5.0 (2023-11-27)

* 🚀 Added support for smart TVs. ([#40](https://github.com/THEOplayer/web-ui/pull/40))

  * Updated `<theoplayer-default-ui>` to automatically switch to an optimized layout when running on a smart TV. For custom UIs using `<theoplayer-ui>`, you can use the `tv-only` and `tv-hidden` attributes to show or hide specific UI elements on smart TVs.
  * Added support for navigating the UI using a TV remote control.
  * Added a `tv-focus` attribute to specify which UI element should receive the initial focus when showing the controls on a TV. In the default UI, initial focus is on the seek bar.

* 🚀 Allow overriding more CSS properties of `<theoplayer-default-ui>`. ([#42](https://github.com/THEOplayer/web-ui/pull/42))

* 💅 Renamed project to "THEOplayer Open Video UI for Web". ([#43](https://github.com/THEOplayer/web-ui/pull/43))

## 1.4.0 (2023-10-04)

* 💥 **Breaking Change**: This project now requires THEOplayer version 6.0.0 or higher.
* 🚀 Open Video UI now imports THEOplayer as a JavaScript module using `import from 'theoplayer/chromeless'`. See the [README](https://github.com/THEOplayer/web-ui/blob/v1.4.0/README.md#installation) for updated installation instructions.
* 🐛 When the player's source is empty, the UI will no longer attempt to play when clicked. ([#37](https://github.com/THEOplayer/web-ui/pull/37))

## 1.3.0 (2023-05-16)

* 💥 **Breaking Change**: This project now requires THEOplayer version 5.1.0 or higher.
* 🏠 This project now depends on the chromeless version of THEOplayer, rather than the full version which includes the old video.js-based UI. ([#31](https://github.com/THEOplayer/web-ui/pull/31))
* 🐛 Fix `has-error` attribute not cleared on source change ([#29](https://github.com/THEOplayer/web-ui/pull/29))

## 1.2.0 (2023-04-26)

* 🚀 Improved support for advertisements ([#28](https://github.com/THEOplayer/web-ui/pull/28))

  * Reworked the ad control bar in `<theoplayer-default-ui>`.
  * Added a `show-ad-markers` attribute to `<theoplayer-time-range>`, to show markers on the progress bar indicating when the content will be interrupted by an advertisement.
  * `<theoplayer-ad-skip-button>` and `<theoplayer-ad-clickthrough-button>` are automatically hidden while playing a Google IMA ad. (This is unfortunately necessary, because Google IMA doesn't provide a way to modify or replace its own buttons.)

* 🐛 When the player changes sources, any open menu is now automatically closed

## 1.1.0 (2023-04-12)

* 💥 **Breaking Change**: This project now targets modern browsers, so `dist/THEOplayerUI.js` and `dist/THEOplayerUI.mjs` now use ES2017 syntax (such as `class` and `async`/`await`). See "Legacy browser support" in the [README](https://github.com/THEOplayer/web-ui/blob/v1.1.0/README.md) for more information about targeting older browsers. ([#26](https://github.com/THEOplayer/web-ui/issues/26), [#27](https://github.com/THEOplayer/web-ui/pull/27))
* 🚀 Added support for THEOplayer 5.0
* 💅 Improved accessibility ([#21](https://github.com/THEOplayer/web-ui/pull/21))
* 💅 Make menus fill entire player when player is small ([#22](https://github.com/THEOplayer/web-ui/pull/22))
* 🐛 Ensure `player` property is initialized immediately when calling `new UIContainer(configuration)` with a valid player configuration ([#24](https://github.com/THEOplayer/web-ui/pull/24))

## 1.0.0 (2023-04-05)

* 🚀 Initial release

---

# Chromeless UI on Web

A chromeless player provides playback capabilities without rendering a user interface. Your application is responsible for creating every control, displaying player state, and connecting interactions to the OptiView Player API.

Choose this approach when you need complete control over the UI and UX, cannot use Open Video UI components, or are targeting an environment that requires a fully bespoke implementation.

Building from scratch requires a solid understanding of playback states, events, media tracks, accessibility, error handling, and platform-specific behavior.

Some features are implemented on top of the default UI and are unavailable in a chromeless player. For example, the [Up Next](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/up-next.md) feature and API depend on the default UI.

Continue with [Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md) to create a `ChromelessPlayer` and map the first controls to the Player API.

---

# Getting started with a chromeless UI on Web

Building a chromeless UI means building a brand-new video player UI from scratch. You achieve this by implementing your own custom UI components, and by associating those components with the appropriate THEOplayer API. The screenshot below visualizes such a chromeless UI -- albeit not the most pretty one.

![Chromeless UI Layout](/pr-932/assets/images/chromeless-ui-7-4025542f4b233096015b9e6ecce5bcd5.png "Chromeless UI Layout")

A chromeless UI gives you complete control over your full UI and UX, but it also means that you are responsible for implementing your full UI and UX. Achieving this feat requires you to have an adequate grasp on the video player architecture and its underlying API.

The goal of this guide is to advance your understanding on how to connect the dots between custom components and the THEOplayer API. For example, this guide will explain to which THEOplayer APIs you could map your custom play button.

## Create a chromeless player instance

Create a [`ChromelessPlayer`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#constructor) instead of a `Player`. Unlike `Player`, a `ChromelessPlayer` doesn't render a default UI, so you can build your own UI on top of it.

```javascript
const element = document.querySelector('.theoplayer-container');
const player = new THEOplayer.ChromelessPlayer(element, {
  libraryLocation: '/path/to/your-theoplayer-folder/',
  license: 'your_license_string',
});
```

The following guides refer to this `player` variable.

## Track player states

Before adding controls, learn how to [track player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/track-player-states.md). Understanding the playback lifecycle lets your UI respond correctly when playback starts, pauses, buffers, ends, or encounters an error.

![Video Player States](/pr-932/assets/images/player-video-player-states-4f4f37f92d4b03a2c750ce7fe03d0a5a.png "Video Player States")

## Next steps

## [📄️Map UI components](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless/mapping-components.md)

[Connect common player controls and displays to the appropriate Player APIs.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless/mapping-components.md)

## [📄️Explore the sample code](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless/sample-code.md)

[See a basic chromeless implementation running in the browser.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless/sample-code.md)

## [📄️Add UX enhancements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless/ux-enhancements.md)

[Plan loading, poster, next-content, intro-skip, and advertising experiences.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless/ux-enhancements.md)

## [📄️Handle errors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless/error-handling.md)

[Make failures visible and actionable in your custom UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless/error-handling.md)

---

# Mapping components in a chromeless UI

A chromeless UI is made up of controls and displays that must reflect player state and call the appropriate OptiView Player APIs. This guide maps common interface components to the properties, methods, events, and supporting guides needed to implement them.

A component can provide context, perform an action, or do both. For example, a play button performs an action, while a current-time display provides context.

This guide covers:

1. Play and pause
2. Volume mute and level
3. Current time and duration
4. Scrubbing and buffered ranges
5. Live playback
6. Audio, subtitle, and quality selection
7. Fullscreen and picture-in-picture
8. Chromecast and AirPlay
9. Subtitle and advertisement overlays

![Chromeless UI Layout](/pr-932/assets/images/chromeless-ui-layout-3642d810cba7de946ee7cb69b7ab238b.png "Chromeless UI Layout")

The [Player API interfaces and events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/analytics/custom-analytics-integration.md) provide the underlying state and actions used by these components.

![OptiView Player API Interfaces and Events](/pr-932/assets/images/analytics-events-185d6ab52b556af08d8300b545ae5876.png "OptiView Player API Interfaces and Events")

## Play button

Show the play button while the player is paused, as described in [tracking player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/track-player-states.md). When a viewer selects it, call [`player.play()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#play).

## Pause button

Show the pause button while the player is playing, as described in [tracking player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/track-player-states.md). When a viewer selects it, call [`player.pause()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#pause).

## Volume mute button

Read and update the [`muted`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#muted) property. Reflect the current value in the button and toggle it with `player.muted = !player.muted`.

## Volume control

Read and update the [`volume`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#volume) property. Reflect the current level and muted state in the control.

## Current-time display

Read [`currentTime`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#currentTime) to display the relative playback position in seconds.

For live streams, you may prefer `currentProgramDateTime`, which provides an absolute value such as `"2022-04-01T13:37:42.666Z"`. This is also useful when implementing an electronic program guide.

## Duration display

Read [`duration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#duration). It returns the duration in seconds for video-on-demand streams and `Infinity` for live streams.

Calculate the remaining duration by subtracting `currentTime` from `duration` for finite streams.

## Scrub bar

Seek by setting `currentTime`. For live streams, you can use `currentProgramDateTime` to seek to absolute playback positions.

Only seek within the ranges exposed by [`seekable`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#seekable). On Web, valid values remain between `player.seekable.start(0)` and `player.seekable.end(player.seekable.length - 1)`.

Subscribe to [`timeupdate`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#timeupdate) to update the scrubber position during playback. The event is dispatched approximately every 200 milliseconds.

The player dispatches `seeking` when a seek starts and `seeked` when it completes. Consider showing a loading state between these events.

### Buffered ranges

Use the `progress` event and [`buffered`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#buffered) ranges to indicate which portions of the stream are already available for immediate playback.

## Live button

A stream is live when `duration` is `Infinity`. To move to the live edge, set `currentTime` to `player.seekable.end(player.seekable.length - 1)`.

## Audio selection

Use these guides to implement an audio-track selector:

* [Detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-audio-tracks.md)
* [Enable and disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/enable-disable-audio-tracks.md)
* [Detect audio-track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-audio-track-changes.md)

## Subtitle selection

Use these guides to implement a subtitle and closed-caption selector:

* [Detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-text-tracks.md)
* [Enable and disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/enable-disable-text-tracks.md)
* [Detect text-track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-text-track-changes.md)

## Video quality selection

Use these guides to implement a quality selector:

* [Detect video-track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-video-track-qualities.md)
* [Select a video-track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/select-video-track-quality.md)
* [Detect video-track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-video-track-quality-changes.md)

## Fullscreen button

The [`Presentation API`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Presentation) is not available for switching a chromeless player between fullscreen, inline, and picture-in-picture modes. Implement fullscreen behavior with the browser [Fullscreen API](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API).

For iOS browsers, you can use [`webkitEnterFullscreen()`](https://developer.apple.com/documentation/webkitjs/htmlvideoelement/1633500-webkitenterfullscreen) or resize the player container to fill the viewport.

## Picture-in-picture button

Implement picture-in-picture UI and behavior independently of the Player SDK. The [Player Picture-in-Picture API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/picture-in-picture.md) is not available for chromeless players.

On Web, you can locate the active video element with `player.element.querySelectorAll('video[src]')[0]`.

Related resources:

* [Picture-in-Picture for the Web](https://developers.google.com/web/updates/2017/09/picture-in-picture)
* [Safari picture-in-picture controls](https://developer.apple.com/documentation/webkitjs/adding_picture_in_picture_to_your_safari_media_controls)
* [Android picture-in-picture](https://developer.android.com/guide/topics/ui/picture-in-picture)
* [Apple platform picture-in-picture](https://developer.apple.com/documentation/avkit/adopting_picture_in_picture_in_a_custom_player)

## Chromecast button

Use the [Chromecast guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/introduction.md) to detect availability and start or stop a casting session.

## AirPlay button

Use the [AirPlay guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/airplay/introduction.md) to detect availability and start or stop an AirPlay session.

## Subtitle cues

You can retain the Player SDK's default subtitle and closed-caption rendering in a chromeless UI. Depending on your design, additional styling may be required:

```css
.theoplayer-texttracks * {
  font-size: 1em !important;
}
```

For complete rendering control, [detect active text-track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/detect-active-text-track-cues.md), then insert and remove each cue in your own interface.

## Advertisement metadata

During advertisements, your UI may need to display a countdown, skip button, or ad markers on the scrub bar.

When using [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/google-ima.md), the integration may provide some interface elements. When using the Player SDK's [default client-side ad integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/set-up-vast-and-vmap.md), subscribe to the relevant [ad events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/subscribe-to-ad-events.md) and update your UI in their callbacks.

Apply the same event-driven approach to server-side ad insertion.

---

# UX enhancements for a chromeless UI

A functional player still needs clear feedback and convenient interactions. Plan these experiences alongside the core playback controls so viewers always understand the current state and available actions.

Common enhancements include:

1. **Loading spinner:** Indicate when the player is waiting for video data.
2. **Poster:** Show an image before initial playback and after the video ends.
3. **Up next:** Near the end of playback, offer a way to open the next stream and optionally start it automatically.
4. **Skip intro:** Let viewers skip the current introduction.
5. **Ad countdown:** Display the remaining duration of the current ad break.
6. **Ad markers:** Indicate ad-break positions on the scrub bar.

Each enhancement should respond to Player events and state rather than relying on timers or visual state alone. Start with [tracking player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/track-player-states.md), then use the relevant playback and advertising APIs for each interaction.

---

# Error handling in a chromeless UI

A chromeless UI must display its own error state because there is no default interface to inform the viewer when playback fails.

Decide how your UI will present recoverable and terminal errors, whether viewers can retry, and which technical details should remain available for diagnostics. Clear any loading state when an error occurs so the player does not appear to buffer indefinitely.

See the [error-handling guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/error/introduction.md) to detect Player errors and map them to messages and recovery actions in your interface.

---

# Chromeless UI sample code on Web

This sample provides a small working chromeless player that you can use to explore the relationship between custom HTML controls and the OptiView Player API. Use it as a learning aid rather than a production-ready implementation.

You can also [open the sample directly in JSFiddle](https://jsfiddle.net/thijsl/1xbk9csq/1/).

Before extending the sample, review how to [map common UI components](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless/mapping-components.md) and consider the recommended [UX enhancements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless/ux-enhancements.md).

---

# Default UI on Web

The OptiView Player Web SDK includes a responsive default UI with standard playback controls such as play and pause, volume, seeking, language and quality selection, picture-in-picture, and fullscreen.

Use the default UI when its existing layout and controls meet your requirements. You can adapt its appearance with CSS, hide controls, and add small extensions without implementing common player interactions yourself.

The default UI is not optimized for big-screen devices such as Samsung Tizen, LG webOS, and Android TV. For those environments, use Open Video UI where supported or consider a chromeless implementation.

> **Default UI terminology**
>
> The Player SDK default UI is different from the ready-made `<theoplayer-default-ui>` layout provided by Open Video UI. Open Video UI uses its own component library on top of the chromeless Player SDK.

For more extensive control over layout and components, use [Open Video UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md). To implement every control yourself, use the [chromeless player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/chromeless.md).

---

# Getting started with the default UI on Web

The default UI is included with the OptiView Player Web SDK. Follow the [Web SDK getting-started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md) to install the SDK and include its JavaScript and CSS files.

Create a `Player` instance to enable the default UI:

```javascript
const element = document.querySelector('.theoplayer-container');
const player = new THEOplayer.Player(element, {
  libraryLocation: '/path/to/your-theoplayer-folder/',
  license: 'your_license_string',
});

player.source = {
  sources: [{ src: 'https://example.com/stream.m3u8' }],
};
```

Use `THEOplayer.Player`, rather than `THEOplayer.ChromelessPlayer`, when you want the SDK to render its default controls.

Next, explore the default UI how-to guides in the sidebar to change its appearance and behavior.

---

# How to remove an element from the UI on Web

You may want to limit the options and controls that are shown in the player's UI.

There are two general approaches:

1. Build a chromeless UI, and add only the controls you need. This is useful when you don't want to remove just one element, but want a radically different UI.
2. Hide or remove the individual element from the existing UI.

This guide focuses on the second approach.

## Code examples

You can hide an element through CSS, or remove it through JavaScript. For this example we will consider the Speed menu option (control bar > Settings > Speed) as the element to remove from the page. The following methods may of course be used for other elements.

**Hide the element with CSS**

We identify the element and hide it. Since In this specific case there is no id or class to identify this element specifically, we make use of its aria attribute. Of course, should it change, this line of code should be adapted accordingly.

```css
.theoplayer-skin li[aria-label='Open the video speed settings menu'] {
  display: none !important;
}
```

**Remove the element through JavaScript**

In alternative to CSS, it is also possible to achieve the same result with JavaScript, in the following way.

```js
function firstplay(event) {
  player.removeEventListener('playing', firstplay);
  var speed = document.querySelector('.theoplayer-skin li[aria-label="Open the video speed settings menu"]');
  speed.parentNode.removeChild(speed);
}
player.addEventListener('sourcechange', function () {
  player.removeEventListener('playing', firstplay);
  player.addEventListener('playing', firstplay);
});
```

---

# How to align the timeline in the middle on Web

This question is asked when developers want to change the appearance of the current time digits and duration digits in the seekbar. For example, instead of having it aligned on the left of the control bar, they might want to have it in the middle.

Please note that this article isn't final.

![Align timeline middle](/pr-932/assets/images/align-timeline-middle-66bdd5275fa323e16204484e31301562.png "Align timeline middle")

## Implementation

One approach is to create a new overlay. The code snippet below implements this strategy.

CSS

```css
.custom-timeline {
  display: none;
  bottom: 0;
  position: absolute;
  width: 100%;
  text-align: center;
  line-height: 36px;
  pointer-events: none;
}

.vjs-has-started .custom-timeline.show {
  display: block;
}

.vjs-time-control {
  display: none !important;
}

.theo-mobile .custom-timeline {
  display: none;
}

.vjs-fullscreen .custom-timeline {
  margin-bottom: 8px;
}
```

HTML and JS

```html
<div class="video-container video-js theoplayer-skin">
  <div class="custom-timeline"><span class="current-time">00:00:00</span> / <span class="duration"></span></div>
</div>
<script>
  var player = new THEOplayer.Player(element, playerConfig);
  ...
  function secondsToHms(d) {
      d = Number(d);
      var h = Math.floor(d / 3600);
      var m = Math.floor(d % 3600 / 60);
      var s = Math.floor(d % 3600 % 60);

      var hDisplay = h > 0 ? h + (h == 1 ? ":" : ":") : "00:";
      var mDisplay = m > 0 ? m + (m == 1 ? ":" : ":") : "00:";
      var sDisplay = s;
      return hDisplay + mDisplay + sDisplay;
  }

  player.addEventListener('timeupdate', function(e) {
      document.querySelector('.custom-timeline .current-time').innerText = secondsToHms(Math.floor(e.currentTime));
  })

  player.addEventListener('durationchange', function(e) {
      document.querySelector('.custom-timeline .duration').innerText = secondsToHms(Math.floor(e.duration));
      document.querySelector('.custom-timeline').classList.add('show');
  })
  ...
</script>
```

---

# How to change the big play button on Web

The question above is typically asked by developers who want to increase/decrease the size, set a different image instead, or introduce on-hover behavior.

## Code example

The snippet below demonstrates how you could set another image instead of the default big play button. Additionally, the button becomes bigger when you hover it.

```css
/* Increase button size when hovering */
.theoplayer-skin .vjs-big-play-button:hover {
  background: none;
  -webkit-transition-duration: 0.2s;
  -moz-transition-duration: 0.2s;
  transition-duration: 0.2s;
  transform: translate(-50%, -50%) scale(1.2);
  transition: transform 0.2s;
}
/* Set other image */
.theoplayer-skin .vjs-big-play-button:before {
  content: '';
  background: url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+Cjxzdmcgd2lkdGg9IjcycHgiIGhlaWdodD0iNzJweCIgdmlld0JveD0iMCAwIDcyIDcyIiB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiPgogICAgPCEtLSBHZW5lcmF0b3I6IFNrZXRjaCA0My4yICgzOTA2OSkgLSBodHRwOi8vd3d3LmJvaGVtaWFuY29kaW5nLmNvbS9za2V0Y2ggLS0+CiAgICA8dGl0bGU+dmlkZW8gaWNvbiBjb3B5IDQ8L3RpdGxlPgogICAgPGRlc2M+Q3JlYXRlZCB3aXRoIFNrZXRjaC48L2Rlc2M+CiAgICA8ZGVmcz48L2RlZnM+CiAgICA8ZyBpZD0iSG9tZXBhZ2UiIHN0cm9rZT0ibm9uZSIgc3Ryb2tlLXdpZHRoPSIxIiBmaWxsPSJub25lIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPgogICAgICAgIDxnIGlkPSJIb21lcGFnZS1fZGVza3RvcCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoLTQ3MC4wMDAwMDAsIC0zMDEyLjAwMDAwMCkiPgogICAgICAgICAgICA8ZyBpZD0iZnd0diIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTIwLjAwMDAwMCwgMjc4OC4wMDAwMDApIj4KICAgICAgICAgICAgICAgIDxnIGlkPSJiaWctdmlkZW8iIHRyYW5zZm9ybT0idHJhbnNsYXRlKDAuMDAwMDAwLCA1MC4wMDAwMDApIj4KICAgICAgICAgICAgICAgICAgICA8ZyBpZD0idmlkZW8tMnB4IiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgzNTEuMDAwMDAwLCAxNzUuMDAwMDAwKSI+CiAgICAgICAgICAgICAgICAgICAgICAgIDxnIGlkPSJ2aWRlby1jb3B5IiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgzNS4wMDAwMDAsIDM1LjAwMDAwMCkgcm90YXRlKC0zNjAuMDAwMDAwKSB0cmFuc2xhdGUoLTM1LjAwMDAwMCwgLTM1LjAwMDAwMCkgIj4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxjaXJjbGUgaWQ9Ik92YWwtMiIgc3Ryb2tlPSIjRkZGRkZGIiBzdHJva2Utd2lkdGg9IjIiIGZpbGwtb3BhY2l0eT0iMC4xNSIgZmlsbD0iIzAwMDAwMCIgY3g9IjM1IiBjeT0iMzUiIHI9IjM1Ij48L2NpcmNsZT4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxwb2x5Z29uIGlkPSJUcmlhbmdsZSIgZmlsbD0iI0ZGRkZGRiIgcG9pbnRzPSIyNi45ODI4NTY5IDQ5Ljk1Mzc1MiAyNi45ODI4NTY5IDE5LjM0MjEwNTMgNDguNTQzNDU4OSAzMy45OTY5NDI5Ij48L3BvbHlnb24+CiAgICAgICAgICAgICAgICAgICAgICAgIDwvZz4KICAgICAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgIDwvZz4KICAgICAgICA8L2c+CiAgICA8L2c+Cjwvc3ZnPg==')
    no-repeat 0 0;
  /* background: url('http://i.stack.imgur.com/LT3WE.png') no-repeat 0 0; */ /* Use image instead */
  background-size: 100%;
  display: block;
}
/* Remove default THEOplayer image */
.theo-big-play-button-svg-container svg {
  display: none;
}
/* Remove default spotlight around button on focus */
.theoplayer-skin:hover .vjs-big-play-button:after,
.theoplayer-skin .vjs-big-play-button:focus:after {
  opacity: 0;
}
```

The snippet above also removes some default behavior, such as the shadow-effect when hovering the big play button.

![Big Play Button](/pr-932/assets/images/big-play-button-7ba8ac3c1d83a855d6fb4f1035f4c466.png "Big Play Button")

---

# How to keep the control bar always visible on Web

The question above is typically asked by developers who want to be able to see the control bar at all times without having to continuously move the cursor over it (or tap the screen).

## Open Video UI

Set the `user-idle-timeout` attribute (or the `userIdleTimeout` property) to a negative value. This disables idle detection, so the control bar never fades out.

```html
<theoplayer-default-ui user-idle-timeout="-1"></theoplayer-default-ui>
```

```js
ui.userIdleTimeout = -1;
```

## Default UI

The following CSS lines overwrite the fade-out transition and keep the control bar always visible.

```css
.theo-secondary-color.vjs-control-bar {
  opacity: 1 !important;
  visibility: visible !important;
}
```

See the [Keep the control bar visible](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/keep-control-bar-visible.md) example for a working demo of both UIs.

---

# How to detect the visibility of the control bar on Web

This question is typically asked by developers that want to insert a custom element that should

1. disappear when the default control bar disappears,
2. appear when the default control bar appears.

This article discusses three approaches that allow you to detect whether the control bar is visible.

1. [Using a chromeless UI](#using-a-chromeless-ui)
2. [Using a MutationObserver](#using-a-mutationobserver)
3. [Using CSS](#using-css)

## Using a chromeless UI

Instead of making the default THEOplayer UI fit your use cases, it might make sense to opt for a [chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/build-chromeless-ui.md). When you use a Chromeless UI, you have full control over the UI and UX, and you are not restricted to the complexities of our default UI.

## Using a MutationObserver

You can use a [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) to detect the visibility of the control bar.

Generally speaking, the default control bar is visible when the following scenario is true for your THEOplayer container's [`classList`](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList):

1. The `vjs-user-active` class is listed in the `classList`;
2. Or if the `vjs-paused` class is listed in the `classList`;
3. And the `vjs-has-started` class is listed in the `classList`.

The control bar is visible in the screenshot below because `vjs-paused` and `vjs-has-started` are classes of the THEOplayer container, as highlighted with the yellow rectangles.

![](/pr-932/assets/images/ui-control-bar-visibile-8e0fc2133328b496d115b9798f356b5c.png)

If we map that to JavaScript code:

```javascript
const theoplayerContainer = document.querySelector('.video-js');
const controlBarVisible =
  (theoplayerContainer.classList.contains('vjs-user-active') || theoplayerContainer.classList.contains('vjs-paused')) &&
  theoplayerContainer.classList.contains('vjs-has-started');
```

It should be noted that this approach does not take the opacity of the control bar into account. The default control bar UI has a "fade in" and "fade out" effect. If you want to take this into account, you can capture its opacity through JavaScript when you have a reference to your control bar DOM element. The snippet below illustrates how you could poll the opacity every 100ms.

```javascript
setInterval(function () {
  const controlBar = document.querySelectorAll('.vjs-control-bar')[1];
  const controlBarOpacity = getComputedStyle(controlBar).opacity;
  console.log('control bar opacity', controlBarOpacity);
}, 100);
```

The snippet below demonstrates how use the previously specified `controlBarVisible` variable in combination with a `MutationObserver`.

```javascript
const theoplayerContainer = document.querySelector('.video-js');
var controlBarObserver = new MutationObserver(function (event) {
  for (let i = 0; i < event.length; i++) {
    const el = event[i].target;
    const controlBarVisible =
      (el.classList.contains('vjs-user-active') || el.classList.contains('vjs-paused')) && el.classList.contains('vjs-has-started');
    const message = {
      controlBarVisible: controlBarVisible,
    };
    console.log(message);
  }
});
controlBarObserver.observe(theoplayerContainer, {
  attributes: true,
  attributeFilter: ['class'],
  childList: false,
  characterData: false,
});
```

You can try out this snippet at <https://detect-visibility-default-control-bar--thijslowette.repl.co/>, and verify the `{"controlBarVisible": true}` (or `{"controlBarVisible": false}`) logs in the developer console.

## Using CSS

If you insert your custom elements through JavaScript, you can use CSS queries to align the visibility of your custom controls with the default control bar.

The snippet at <https://detect-visibility-default-control-bar--thijslowette.repl.co/> has a text ("Hello World!") that's only visible when the control bar is visible. We also leverage the `vjs-has-started`, `vjs-paused` and `vjs-user-active` classes mentioned in the previous approach.

---

# How to hide the Google IMA UI on Web

You may want to know which controls are visible to the viewer during ads, so you can use your own UI elements instead.

Unfortunately Google IMA provides very limited control over the UI. The only thing that you can change or hide from THEOplayer is the countdown: to do so, set `showCountdown` to `false` in your [`AdsConfiguration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/AdsConfiguration#showCountdown).

Using other methods, like CSS or JavaScript, to modify the Google IMA UI elements styles will also not work due to:

* the usual higher specificity of the *iframe* CSS
* the security restrictions on XSS.

---

# How to insert a button on Web

This article provides information on how developers can add custom buttons to THEOplayer's **default UI**.

THEOplayer's default UI is based on Video.js, so you insert a button with HTML, CSS and JavaScript.

## Code example

This code example adds 2 time-jump buttons to the control bar. A button to go back 10 seconds in time should be positioned to the left of the play-button, and a button to go forward 10 seconds in time should be positioned to the right of the play-button.

The buttons use the [Font Awesome](http://fontawesome.io/) icon set. This means that we first need to include the Font Awesome CSS stylesheet.

```html
<link rel="stylesheet" type="text/css" href="http://cdn.theoplayer.com/demos/font-awesome/css/font-awesome.min.css" />
```

The code below inserts two buttons in the control bar, lets viewers jump in time when it is clicked, and adds a tooltip to the button.

```js
// setting up the rewind button by setting up a video-js component
var Button = THEOplayer.videojs.getComponent('Button');
var RewindButton = THEOplayer.videojs.extend(Button, {
  constructor: function () {
    Button.apply(this, arguments);
    /* initialize your button */
    // this.el() = created DOM-element

    // add tooltip
    var tooltipSpan = document.createElement('span');
    tooltipSpan.className = 'theo-button-tooltip vjs-hidden';
    tooltipSpan.innerText = 'Go back 10 seconds';
    function toggleTooltip() {
      tooltipSpan.classList.toggle('vjs-hidden');
    }
    this.el().addEventListener('mouseover', toggleTooltip);
    this.el().addEventListener('mouseout', toggleTooltip);
    this.el().appendChild(tooltipSpan);
  },
  handleClick: () => {
    player.currentTime -= 10;
  },
  buildCSSClass: function () {
    return 'fa fa-step-backward vjs-button'; // insert all class names here
  },
});
THEOplayer.videojs.registerComponent('RewindButton', RewindButton);
player.ui.getChild('controlBar').addChild('RewindButton', {});

// setting up the forward button by setting up a video-js component
var Button = THEOplayer.videojs.getComponent('Button');
var ForwardButton = THEOplayer.videojs.extend(Button, {
  constructor: function () {
    Button.apply(this, arguments);
    /* initialize your button */
    // this.el() = created DOM-element

    // add tooltip
    var tooltipSpan = document.createElement('span');
    tooltipSpan.className = 'theo-button-tooltip vjs-hidden';
    tooltipSpan.innerText = 'Go forward 10 seconds';
    function toggleTooltip() {
      tooltipSpan.classList.toggle('vjs-hidden');
    }
    this.el().addEventListener('mouseover', toggleTooltip);
    this.el().addEventListener('mouseout', toggleTooltip);
    this.el().appendChild(tooltipSpan);
  },
  handleClick: () => {
    player.currentTime += 10;
  },
  buildCSSClass: function () {
    return 'fa fa-step-forward vjs-button'; // insert all class names here
  },
});
THEOplayer.videojs.registerComponent('ForwardButton', ForwardButton);
player.ui.getChild('controlBar').addChild('ForwardButton', {});
```

You could add `vjs-control` to the return-string of `buildCSSClass` to make the button more similar to the default buttons.

Finally, you can adjust the position of the custom buttons with the order attribute, and force the cursor to use a pointer.

```css
.fa-step-backward {
  order: -101; /* to the left of the play/pause-button */
  cursor: pointer;
}
.fa-step-forward {
  order: -100; /* to the right of the play/pause-button */
  cursor: pointer;
}
```

## Sample resources

The pages or projects below demonstrate implementations of similar use cases.

* Web SDK - Demo Page: <https://www.theoplayer.com/theoplayer-demo-adding-buttons-to-the-ui-with-custom-logic>
* Web SDK - Sample App: <https://github.com/THEOplayer/samples-html5-sdk/tree/master/reference-apps/ui-adding-buttons>

---

# How to change the UI language on Web

This article describes how to change the default UI language to other.

The [`UIConfiguration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UIConfiguration) object has a `language` and a `languages` property to change the default UI language, i.e. English, to any other language. Both properties are optional, but when `language` is defined, its language code must have a matching language dictionary in the `languages` configuration.

When this configuration is set, the labels and tooltips in the UI will be replaced by their translated version from the language. If no translation is found for a label or tooltip, the original English version will be used instead.

## Prerequisites

* A valid THEOplayer license for the Web SDK.
* The language dictionary that you want to add to your project.

**Language JSON Links**

Arabic : <http://cdn.theoplayer.com/demos/theoplayer/lang/ar.js>

Bashkir: <http://cdn.theoplayer.com/demos/theoplayer/lang/ba.js>

Bulgarian: <http://cdn.theoplayer.com/demos/theoplayer/lang/bg.js>

Catalan: <http://cdn.theoplayer.com/demos/theoplayer/lang/ca.js>

Czech: <http://cdn.theoplayer.com/demos/theoplayer/lang/cs.js>

Danish: <http://cdn.theoplayer.com/demos/theoplayer/lang/da.js>

German: <http://cdn.theoplayer.com/demos/theoplayer/lang/de.js>

Greek: <http://cdn.theoplayer.com/demos/theoplayer/lang/el.js>

Spanish: <http://cdn.theoplayer.com/demos/theoplayer/lang/es.js>

Persian: <http://cdn.theoplayer.com/demos/theoplayer/lang/fa.js>

Finnish: <http://cdn.theoplayer.com/demos/theoplayer/lang/fi.js>

French: <http://cdn.theoplayer.com/demos/theoplayer/lang/fr.js>

Croatian: <http://cdn.theoplayer.com/demos/theoplayer/lang/hr.js>

Hungarian: <http://cdn.theoplayer.com/demos/theoplayer/lang/hu.js>

Italian: <http://cdn.theoplayer.com/demos/theoplayer/lang/it.js>

Japanese: <http://cdn.theoplayer.com/demos/theoplayer/lang/ja.js>

Korean: <http://cdn.theoplayer.com/demos/theoplayer/lang/ko.js>

Dutch: <http://cdn.theoplayer.com/demos/theoplayer/lang/nl.js>

Polish: <http://cdn.theoplayer.com/demos/theoplayer/lang/pl.js>

Portuguese: <http://cdn.theoplayer.com/demos/theoplayer/lang/pt-BR.js>

Russian: <http://cdn.theoplayer.com/demos/theoplayer/lang/ru.js>

Serbian: <http://cdn.theoplayer.com/demos/theoplayer/lang/sr.js>

Swedish: <http://cdn.theoplayer.com/demos/theoplayer/lang/sv.js>

Turkish: <http://cdn.theoplayer.com/demos/theoplayer/lang/tr.js>

Ukrainian: <http://cdn.theoplayer.com/demos/theoplayer/lang/uk.js>

Vietnamese: <http://cdn.theoplayer.com/demos/theoplayer/lang/vi.js>

Chinese: <http://cdn.theoplayer.com/demos/theoplayer/lang/zh-CN.js> | <http://cdn.theoplayer.com/demos/theoplayer/lang/zh-TW.js>

## Implementation

```js
player = new THEOplayer.Player(playerElement, {
  libraryLocation: 'path/to/theoplayer/',
  license: 'your-license-here',
  ui: {
    language: 'esp',
    languages: {
      esp: {
        Play: 'Reproducir',
        Pause: 'Pausa',
        'Current Time': 'Tiempo actual',
        'Duration Time': 'Duración',
        'Remaining Time': 'Tiempo restante',
      },
    },
  },
});
```

---

# How to customize the UI during ad playback on Web

This how-to guide describes how to customize the look and feel of the player when an advertisement is playing. We will be leveraging mainly some event listeners and CSS. In the section *Resources*, at the bottom of the page, you will also find links to the reference API and to a related how-to guide that explains when and how the texts displayed during ad playback (if any) may be changed.

## How to customize the ad playback UI

You may want to alter the UI during ad playback, for example in order to hide some elements, to show some new elements or to change the aspect of existing ones. In the following, we will see some example related to this.

### Detecting ad playback

There are two general approaches to detect advertisement playback:

1. A responsive approach using a **CSS rule**.
2. A programmatic approach using **events**.

Whenever you create a THEOplayer instance, you need to provide a DOM-element which will be the container of the player (for more information regarding this, see Resources). This container gains the `.theo-ad-playing` class whenever an advertisement is playing. Through CSS, you could use this class to enforce certain behavior. For example, you could hide the fullscreen button if an ad is playing.

```css
.theo-ad-playing .vjs-fullscreen-control {
  display: none !important;
}
```

### Events

The [Ads API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Ads) exposes, among others, the following events:

* `adbegin`: dispatched when an ad starts
* `adend`: dispatched when an ad ends
* `adbreakbegin`: dispatched when an ad break (or ad slot) starts
* `adbreakend`: dispatched when an ad break ends

The snippet below demonstrates how you could detect the start of an adbreak through a JavaScript event listener.

```js
player.ads.addEventListener('adbreakbegin', console.log);
```

These events can be used to trigger a certain behavior programmatically.

### Displaying an advertisement label

The snippet below demonstrates how to add a label to the control bar during ad playback using CSS and JavaScript.

CSS

```css
.theo-ad-playing .theo-advert-label {
  display: block !important;
}

.theo-ad-playing .vjs-fullscreen-control {
  display: none !important;
}
```

JavaScript

```js
var button = THEOplayer.videojs.getComponent('Button');
var myButton = THEOplayer.videojs.extend(button, {
  constructor: function () {
    button.apply(this, arguments);
    this.el().innerHTML = 'Ad';
  },
  handleClick: function () {
    elementContainer.classList.toggle('hidden');
  },
  buildCSSClass: function () {
    return 'theo-advert-label';
  },
});
THEOplayer.videojs.registerComponent('AdvertLabelButton', myButton);
player.ui.getChild('controlBar').addChild('AdvertLabelButton', {});
```

### Adding a custom countdown

The snippet below demonstrates how to add a countdown timer using primarily JavaScript.

CSS

```css
.theo-ad-countdown {
  position: absolute;
  top: 50%;
  left: 50%;
  font-size: 5em;
}
```

JavaScript

```js
function updateTime() {
  var countdown = document.querySelector('.theo-ad-countdown');
  if (countdown) {
    countdown.innerHTML = Math.round(player.duration - player.currentTime);
  }
}

player.ads.addEventListener('adbegin', function (e) {
  var countdown = document.createElement('div');
  countdown.className = 'theo-ad-countdown';
  countdown.innerHTML = player.duration;
  element.appendChild(countdown);

  player.addEventListener('timeupdate', updateTime);
});

player.ads.addEventListener('adend', function (e) {
  var countdown = document.querySelector('.theo-ad-countdown');
  if (countdown) {
    player.removeEventListener('timeupdate', updateTime);
    element.removeChild(countdown);
  }
});
```

---

# How to change how a video should fit inside a container on Web

You may want to alter how a video is sized inside the player's frame. By default, a video player respects the aspect ratio of the video. This means that black bars can appear on the sides of the player, or above and below the video, when its aspect ratio differs from the player's aspect ratio.

Instead, you may want the video to cover the entire player. Note that this either

* cuts off the content that falls outside of the player, or
* deforms the content, so it no longer matches its original aspect ratio.

## Implementation

The CSS [`object-fit`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) property serves this use-case.

```css
.theoplayer-skin video {
  object-fit: contain; /* default */
  /* object-fit: cover; // content outside of the container, hence some content might be missing from the container */
  /* object-fit: fill; // all content inside of the container, but the content might be deformed to be fitted inside of it */
}

/*
// if you are doing object-fit: cover, and you don't want to show the content outside of the container, then do:
.theoplayer-skin {
    overflow-y: hidden;
}
// additionally, the object-position CSS property can help position the content, e.g.
.theoplayer-skin video {
    object-position: top;
}
*/
```

Alternatively, if you cannot use CSS for some reason, you could try to achieve the same through JavaScript.

```javascript
const videos = document.querySelectorAll('.theoplayer-skin video');
for (let i = 0; i < videos.length; i++) {
  videos[i].style.objectFit = 'cover';
}
```

---

# How to make an audio-only player on Web

This article tells you how to manipulate THEOplayer to make an audio-only interface, using only CSS and JavaScript.

Going from this ![Audio Only](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAf0AAAEhCAYAAAB1MHncAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAABKvSURBVHhe7d1vsF1VeQdgtWAEiWBAI/9CgoGQSIgGQsQQIhhgpqWdYFstMIrTCmNrFREwQztatKWFgtggcVI6dkBQalOlKBQLUwZoh8GRts60tS0znZYPOvClpbRjP+7y3nafu3Py3su95+x9/qw8Z+bJZH5nnb3WXufDunuftdd6VeXl5eXl5eV1QLxe9fIr/gEAypeGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQ2AKrVh+UHXxtmXV9ZefUN35a2urh3ZtrL53zzurf3ngnOqFR8+rXnry/OrHT10wI/4fWbwXZaJsfCY+G8eIY2V1AFMtDYEpcObaQ2cG6Qc+//bquQe3Vf/z1IWtimPGsaOOqCtrAzBV0hCYUBdtOWLmijyu0LOBut/zf35e9YO9Z1dP37W5emzPGdUju0+fEf+PLN6LMtln+0WdUXe0IWsbMPHSEJgg61YuqW69avW8A/2z92+t9t68obrhylXV+95zVLX+xCXVkte+Jj1eJsrGZ+KzcYw4VhwzqytEW6JN0bbseMBESkNgAsQVddxezwbduDq/78b11RU7jq5WveXg9PNtiGNHHVHXXHcEoo2u/mEqpCEwRjGRLm6/9w+uLz6xvfrKZ0+tdpyzLP3cKETd0YZoS3/7os3R9uxzwERIQ2AMtpx22Mws+v7B9Jl7z6o+cclxi7pd37VoS7Qp2tbf3jiHOJfsc8BYpSEwQjGA7t55yn6DZ1w5x2/s2WcmSbQxuzMR5zRJf6gAeQiMyGUXvnm/CXoxq34aBvt+0eZoe/Nc4tziHLPywMilITAC8fhbc4CMiXJxyzwrO03iHPon/cW5ZmWBkUpDoEOx0E2sgtccFGNy3JFLy7kVHucS59Q8xzhni/zAWKUh0JEPXbR8ZgnceiCMK+LIsrIliHNrXvXHuZd8vjDh0hDowGc+vLI3+IVYGa/LZ+wnRZxjnGvz3KMvsrJAp9IQaNmua07eZ9C747o1abmSxTk3+yD6JCsHdCYNgRb1T9i77gMr0nIHgjj3Zl+Y4AcjlYZAS/oHfL9n/9/v/M0+MfDDyKQh0IL+W/rT+Ox9V6Ivmn3jVj+MRBoCQ+qftGfA31//wG9yH3QuDYEh9N++dkt/bvoKRioNgQHF4jPN5/AP5El7C9Wc3Bd9ZwEf6EwaAgNqrrR3ID6WN6jm43zRh1kZYGhpCAygOVM/FqPJygzq3I1L07wkzQV8zOiHTqQhsEixk1w9YMWys22utPfag19d/e1Xz6q+/7V3VXuuX1td+nJdhx9a3pa10WfNJXvtzgetS0NgEWLP+Ob2uG1PRtu64bDqv/9ydp5A+NF3zq3uv2XDzI52xx51UPq5adSc2Bd9aj9+aFUaAouwe+cpvYEqdpbLygzjql84rnf8zA8ffnd129UnVetWLkk/P22au/NF32ZlgIGkIbBAW047rDdAxa3pLrbHvfPX913Vby7//vj26vevX1ttXjfds9+jD5u3+aOPs3LAoqUhsEAP7drYG5ziVntWZlhP/sGmXh0Ldc/nTq22b3pDerxpEH1Zn0v0cVYGWLQ0BBbg4m3LegPT03dtTsu04flHzu3Vs1jf/N0N1Y5zlqXHnXTRp/V5RF9nZYBFSUNgAR7bc0ZvUOpqmd1TVy3p1TGMvTedVp31ttendUyq5jK90ddZGWBR0hB4BRdtOWIkA9L7t++7Pv0wXnpye3XLx1dXS6focb/mH1bR51kZYMHSEHgFD3z+7b3BqMvNdHZ+cN/959vw91/fUn3kvcek9U2a5tV+9HlWBliwNATmEY/G1QPRM/eelZZpy+5PzS5P27YHf+8dUzHZL/q4bnMpjyXCmKQhMI9br1rdG4S6mrFf+9Zts3cUunLHy39YTPICP82Z/NH3WRlgQdIQmEe9+t6LT2zvfMW4v/nq7FVul+KcPnnZ8Wkbxi36OPq6bmdWBliQNATm0JzA18Xqe/1eeHR2kZpRiDsLZ6w5JG3LODVX6TOhDwaWhsAcmjvpdf38e8yyr+sapfhDIyYQZm0al+jrun124IOBpSEwh/rWfiwTm73fprjirge6cZi0q/56aV63+GFgaQgkzlx7aG9AvO/G9WmZNrX5jP6gJumqP/q8bld8F1kZYF5pCCSuv/yE3qBzxY6j0zJt6uIZ/UFNwlV/9HndnvgusjLAvNIQSDQX5Fn1loPTMm26+WOzjwZOgnFf9Uef122xUA8MJA2BxHMPbpsZcJ69f2v6ftu+cPVJvUFuksSAe8rxr03b3LXo+2hDfBfZ+8C80hDos2L5Qb1Bb+/NG9IybYtFc+o6J01MpvvAT745bXeXou/rNsR3kpUB5pSGQJ/mNro3XLkqLdO25uOBk+q2q09K296V6Pu6btvtwqKlIdCnOYmvyw12mu76jbf16pxkj+4+vdo0otn0zQ14TOaDRUtDoE/zqnv9iaPZ9OWrvzm7Ct2k+9F3zh3Jzn3R93WdFumBRUtDoM9Duzb2Bpuu19uv7b3ptF6d02LP9Wur13XYP9H3dV3xnWRlgDmlIdDne/e8c2agGcVKfLU/vbX7Hfa68FdfPrPauuGw9JzaUK/MF99J9j4wpzQE+tTL7/5g79np+114aNc79hlMp8nzj5xb/eLPvCU9r2HFdxB1WI4XFi0NgT71bndP37U5fb8LMUGuOZBOo9/+6FvTcxtGfAdx7PhOsveBOaUh0OelJ8+fGWge23NG+n4XHr9z0z4D6LT62m+1u09BfAdx3PhOsveBOaUh0OfHT10wM9A88vLVd/Z+Fx790vRf6dfid/5jjvyJ9DwXK76DOGZ8J9n7wJzSEOgzjkH/z26ffWJg2v3Fy1fnRy1tZ1a/QR8GloZAn3Hc3v9WY4OfaXb7tSen5zcot/dhYGkI9BnHRL4/aawzP60+/v5j03Mbhol8MLA0BPqM45G9P7px/T4D6DT5x2+cXf302W9Mz2tYHtmDgaUh0Gcci/N85bPTswxv0903vG1m7/vsnNpgcR4YWBoCfcaxDO8ffnpdr85p8Hdf31Jd/lPL03Npi2V4YShpCPQZx4Y7sY59Xeek+9LOU6ojW5qdPx8b7sBQ0hDoM46tdb943ZpenZPqu3dvrn7uvCPT9nfB1rowlDQE+ly8bVlvsLnhylVpmbbddvVJvTon0S1Xra6WHPzqtO1dib6v64/vJCsDzCkNgT4rlh/UG2z23rwhLdO2mz62ulfnJImVAi/cfETa5q5F39ftiO8kKwPMKQ2BxHMPbpsZbJ69f2v6fts+8+GVvQFuEsQjcp+89Pi0raMSfR9tie8iex+YVxoCiQcaK+R1+Uha7aM/f2yvvnHbvfOU6tijxntlHX1etye+i6wMMK80BBLNyXxX7Dg6LdOmSy54U6++cXn49o3VBZsPT9s3atHndbtM4oOBpCGQOHPtob1B574b290uNnPBmYf36hu1f/rG1upj72t/Cd1hRJ/X7YvvIisDzCsNgTnUy/GOYmW+jScf0hvkRmnXNSdXb3pDO9vgtqleic/yuzCwNATm0FykZ8c53T4yFr+h13WNwre/8I7qvI1L07aMW/R13U6L8sDA0hCYw0VbjugNPrE2flamLc0lZ7v0xJ2bqssufHPahknR3IcgvoOsDPCK0hCYR32L/8Untne+Dv9/PL69N9i17a/vPav65Z89Jq13kkQfR19Hm93ah6GkITCPW6+aXTTnE5ccl5Zpy7/9/9oAbfrnb26tdn5wRXXQa/I6J030cd326PusDLAgaQjMY93K2U1fnnn5ajkr05bvf+1dvbqG9cOH313d+CsnVm98/Wh2CWxL9HF9DtH3WRlgQdIQeAXNhXq63IDn8Ts39eoZ1H8+sb26/dqTq7ce3f2CQm1rbrBjQR4YWhoCr6A5oe+xPWekZdoQK+HV9SzWfz15fvXlT6+rTl9zSHrsaRB9W5+PCXwwtDQEFqA5IHV1tf+R9x7Tq2Ohnn/kvOqL166pNqx+XXrMadG8yu/yDys4gKQhsADN7XafvmtzWmZY79n0hl4dr+Rfv72t+p1ffWt14gj2BRiF6NP63GyjC61IQ2CBHtq1sTcwdTGT/4TGlr5z+Yc/3lJ9+pdWVkcuna4JevNpztiPPs7KAIuWhsACbTntsN7gFMvEdjHwfv++fAb/d+/eXF196fHVkoNfnX5uWkUf1kvuhujjrBywaGkILEJzsl0Xq/R967bZJwViP/k7rlszsxlPVrYEzdX3om+zMsBA0hBYhFgxrl6lL3zoouVpuUHd8ak11b2fO7V6//buHg2cFNF3dT9Gn3a94iEcYNIQWKRYu74erOLW9KoWJ9MtPfTAGPiiz5q39Sd9PwCYQmkIDKC5A98ju09PyzC36LO6/+ykB51IQ2BA37vnnb2BK357z8qwv+irut+iD7MywNDSEBjQmWsPrV568vzeAHbdB1ak5ZgVfVT3V/Rd9GFWDhhaGgJDaE5GC21P7CuJvoKRSkNgSJ/58Mp9BrMuN+WZVs1ldkP0WVYOaE0aAi3Ydc3J+wxqBv5Z/QN+9FVWDmhVGgItac7oD25f739L30x9GJk0BFrUP/AfyJP7mpP2ggEfRioNgZb13+o/EB/naz6WF9zSh5FLQ6AD/ZP7YjGaNlfum1Rxjs2Fd4JJezAWaQh0JH7Pbj7HH8vOlvw7f5xbc2ndOHfzGmBs0hDoUCw+01y5L8TOciXthx/n0twtL8Q5W3gHxioNgRHon+AXV8SfuOS4tOw0iXNoXt0HE/ZgIqQhMCKxk1xzW97w9F2bp/KZ/mhztL15LnFudsuDiZGGwAjFnvG7d56yz2AZHttzxlQM/tHGaGt/++Oc7IcPEyUNgTHYctph1UO7Nu43eD5z71kzt8wnaQCNtkSbom397Y1ziHPJPgeMVRoCY3TxtmXplfOLT2yfmRy345xl6edGIeqONkRb+tsXbY62Z58DJkIaAhPgoi1HVA98/u37Da4hJsrdd+P66oodR3f6rH8cO+qIuvon59WijdHW7PPARElDYIKsW7mkuvWq1ftN+Gt69v6t1d6bN1Q3XLlq5jf29ScuWdTPAVE2PhOfjWPEseKYWV0h2hJtirZlxwMmUhoCEyquqOPxt/n+AGiKq/Mf7D17ZlZ93H6PlfFC/D+yeG+uK/h+UWfU7aoeplYaAlMgFrq5/vITZm6vP/fgtnSgHkYcM44ddVhUB4qQhsAUWrH8oJmJdDFIxxV5zKKPVfDiCv2FR8+bWQL3x09dMCP+H1m8F2WibHwmPhvHiGNldQBTLQ0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE3l5eXl5eXldQC8qup/AZqSq1BORoY4AAAAAElFTkSuQmCC "Audio Only")

to this

![Audio Only](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAf8AAAA0CAYAAACEqTF9AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAN2SURBVHhe7d0xSxx5HMdhCWIhiI2FBGLjO0hpZy0ptMlbSJvG0sLORoiCvQgWqQwWwglJFQvroIJgDsRCBEW0UNH8c785R1Z3PDDZXXPzf77woOvODCHNZzeOpiv9s66uLgAgA0X3xR8A8iH+AJAZ8QeAzIg/AGRG/AEgM+IPAJkRfwDIjPgDQGZ+Of4jIyMAwB+iqtWPEX8AqIGqVj9G/AGgBqpa/RjxB4AaqGr1Y345/gDA/5P4A0BmxB8AMiP+AJAZ8QeAzIg/AGRG/AEgM+IPAJkRfwDIjPgDQGayjP/w8HDx8fvf39OnT5/SwMBA0zEAUFdtif+rV6+e/HuGO2V2draIfnx+dnZW/AX8+PEjra6uNh0LAHUUa3n8JyYmiguvrKyk7u7uymOeQ4Q/tr+/XzyemppKl5eXxddiHz9+bDoHAOom1rb4x87Pz9Pbt28rj+ukMvyxMv6hp6cn/bW+fvtMSu/fv793HgDUTayt8S+3sbGR+vr6Ko9vt8bwx8r4Ly0tFfGPz/f29ornbm5uUn9//73zAaBOYh2Jf+zq6ipNTk5WntNKnz9/TicnJ3cerox/fM//6Ogo9fb2Fjf9Rfhjc3NzTdcEgLqIdSz+5XZ3d+/uuG+HiPt/rTH+senp6eJx+e5/Z2fn3vUAoE5iHY9/LN5lz8/PV57/u54a/2/fvhWP44a/WPxrQOP1AKBOYs8S/9iXL18qz/9dT41/+U5/cXGxeHx8fHzvegBQJ7GOx//09DS9efOm8txWeGr8P3z4UDyOFwGx+LZE4/UAoE5iHYt//DKd5eXl9OLFi8rzWmV7e7v4tkLp4Rrjf3FxkQYHB4u7/uOGxFj8FMDDawJAXcQ6Ev+Dg4P0+vXryuPbbW1t7fZP8e/K+K+vr6ehoaHi868bX2+fTXdfA4A6irU1/tfX12lmZqbyuE5qfAFQxr/U+HsAFhYW7j0HAHUTa1v84y76ly9fVh7zHMoXAGX8x8fH0+HhYfG12ObmZtM5AFA3sZbHP4L/7t27yueeW7wAeHjDXyxu9vuT/h8CAGiXWMvj/6cbGxsrPsaP9G1tbaXR0dGmYwCgrrKMf8k7fQBylHX8ASBH4g8AmRF/AMiM+ANAZsQfADIj/gCQGfEHgMyIPwBkRvwBIDN38TczM7N8Jv5mZmaZTfzNzMyyWko/AakVHpXdu7n/AAAAAElFTkSuQmCC "Audio Only")

## Making the audio player from the video player

This section explains how to alter the default video player UI into the UI shown in the picture below, thus transforming a default THEOplayer instance in an audio player. This can, of course, be further customized to your liking to adapt to the rest of your implementation.

![Audio Only](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAArMAAAAvCAYAAADw3EIKAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAggSURBVHhe7d1vqE3bGsfxkySRlCgpSiQlJSnaipRckRdESrwREfGGdpGQ8sILvBBSnEjyJ+3rb+meQuocUXLLn0S4CeeG/Cnb9X/c8RvHWGfsuZ+19tx7O2ePre9TH9YzxzPHWnOXeow15tw/OYIgCIIgCILopPGTD/0BAAAAdApp+NwuAgAAAHKUhs/tIgAAACBHafjcLgIAAABylIbP7SIAAAAgR2n43C4CAAAAcpSGz+0iAAAAIEdp+NwuAgAAAHKUhs/tIgAAACBHafjcLir632//ALJw8+bNNqmrqwMAABmyes9a0vC5XVRkNRVAR7Aa1TKsfzwAAKDjWb1nLWn43C4qspoKoCNYjWoZ1j8eAADQ8azes5Y0fG4XFVlNBdARrEa1DOsfDwAA6HhW71lLGj63iwAAAIAcpeFzuwgAAADIURo+t4sAAACAHKXhc7sIAAAAyFEaPreLAAAAgByl4XO7CAAAAMhRGj63iwAAAIAcpeFzuwgAAADIURo+t4sAAACAHKXhc7sIAAAAyFEaPreLfiR9+/Z1PXr0cCtXrnRPnz51CxcuNOsAAACQvzR8bheVNXXqVLdjx46KiRMnVsZGjRrVZGzBggVNzv079OvXz71588bNnDnTrV279ttlO/fixYvw2a1zAAAAkK80fG4XlXXu3LlvU/0R+/btq4ylzaPi+r+vNzn3rxYbWYWa2UGDBrkbN26EXPHx48dwzDq3tbp06WIel1pjUXvPTw0ZMiSsRltjRd26dTOPt/Y9i9p7PgAAQDVp+NwuKivXZjZtZBVqZuPYlClT3IcPH8Lx58+fu65duzY5tzU2bNjg3r59G+Z69uyZGz58eDiuOX/97dfQMH/58sVdv37dDR06tNn5avquXLniPn/+HOouX75c+TyLFi1yjx49CnO/fPnSzZkzp9n5llevXrn6+npzLLVq1aowd+/evSvHql1P0bVr18JnjvSeOl7regAAAL6HNHxuF5WVYzNbbGQVambnzp3rli1bFmpmz579bcS506dPN5ujjLq6Ovf161e3Z88eN3bsWPf7f393T548CWP6OaiRnTx5cthuoWZPjV1xjsOHD7tPnz65MWPGhC0amm/37t1u2LBh4bUaw8GDB7uGfzaE5tBqiFNakdV5PXv2NMdFzevFixe/Xf2fzWyt6ylqfNfozp49GxpsmTZtWjhe7XqK5wMAALRVGj63i8rKoZlVE6ZmMVITWYx0z+z69evDeSdOnAi5VmmLc5Zx5MgR9/79+0q+ZMmSMJ++ut+8eXN4vzimVVqteOr1vXv33KVLl8Jrffbp06eH17169QoNq+Zds2ZNmGvgwIFhTHMqtm/fHvJqtLKq1WZrLFq9erVrbGwM+5gVsZmtdT3z5s0LP1et1Hbv3j0c138IVJOu3la7njgOAADQXmn43C4qK4dmVo1qS5E2s2rkdJ5WTWNoJbE4b0vUoOqr+JhrNVOhldi0rn///uFrd9Urb2hocLt27WpSo9XLd+/eBdrzOnr06DDXjBkzwnic+/jx403OK9J2hpMnT5pjkZpRbQfQDXCK2MzWup5Jkya5W7duuQEDBoTGVqFV1xhbt26tnCfF60nHAAAA2iMNn9tFZXXGZlYxcuTIcG5syBYvXtxs3pZcvXrVPX78uJKraVOoSY7HtDqpJydo9VfbH+LxIn09r0ZSn2fjxo3h2OvXr8PX+UePHq1smzh27Fizc1N6H62YWmNFxWa2zPWItmpo9VdbC7RyfPfu3dC0pjXW9QAAAHwPafjcLiqrszaz48aNC+dqxVSxfPnyZvO2RNeefqU/YcKEMFefPn1Crr/jtgettMa6Wu7cuROaWL3W1/VqCNUo/uuXX0Jju2nTpmbnRFpJ1df61pil2My2dD3V6HMq4ipyKr0eAACA7yENn9tFZXXGZjbukY1foyvGjx/fbN6W6Kt03ewUc82vlUi91g1YamT1XrUa2TNnzjT5mZ06dSo0pFrR3bJlS9gSoOO6sUsxa9asSm3Rvp9/dvfv3zfHLMVmttb1pNatW1fZ8yt6frBCN61Vu56YAwAAtFcaPreLysqhmdXX3WqYorh1II20md2/f384b+/evSHX6mxbnouqZ9QqtEdVK71qXrUSqbHz58+HMd2QNX/+/ECfQWM6tmLFivD64MGD4f1145QeGaYbsB4+fBgeZ6XGUlsMdAOWtgDoBrJaj7l6+J+HrXpyQLGZrXU9I0aMcIcOHQq18T8P+nnq6Qp6fFhcfa12PfE9AQAA2isNn9tFZeXQzBbpZq7iEw3UgKmh3LlzZ6VGja8i3pjVFgcOHAhzKLSvVauTOh7nTkOfSWPaQ3v79u3wWiuwDx48CA246LgaR41t27atsg1CWwysr/EjNeN6z+LNZ7Wo2VToM8Rj1a5n6dKl4VicX816vEZdV3wGbq3rAQAA+B7S8LldVFaOzawUG9q4Kiq6Iz/eUKX9qC3tCW2JtgK09PzXlugzpE1lpCa1zNyq0xMHrLHWKns9es9qjWq16wEAAGivNHxuF5WVazMraUOrZlZNmh6LFbch6O+27JUFAABAx0nD53ZRWXqk1YULFyr0W7bimJrJdCz+soK/U2xo1cymzbX2o7blCQYAAADoWGn43C76kehpAvrFBfX19eGGJP3CAt1UZdUCAAAgb2n43C76EWmPp1hjAAAA6BzS8LldBAAAAOQoDZ/bRQAAAECO0vC5XQQAAADkKA2f20UAAABAjtLwuV0EAAAA5CgNn9tFAAAAQI7+DOf+D9Obw/667MRKAAAAAElFTkSuQmCC "Audio Only")

The alteration involves 8 steps:

1. Add a new class to 2 HTML elements in the player (JavaScript)
2. Hide unnecessary buttons from the control bar (CSS)
3. Hide content that might appear above the control bar (CSS)
4. Decrease the player's height (CSS)
5. Ensure the control bar is always visible (CSS)
6. Rescale the loading spinner (CSS)
7. Change appearance for when the stream is not yet loaded (CSS)
8. (Optional) Add the audioOnly flag (JavaScript)

In the following, you can find a description and a code example for each step.

## Code examples

### 1 - Add a new class to 2 HTML elements in the player

To comfortably provide the required CSS during the next steps, we add CSS classes to two HTML elements, respectively:

1. 'audioplayer' to the player element (select it using the 'vjs-fluid' class)
2. 'audiocontrol' to the controls element (select it using the 'vjs-control-bar' class)

```js
function transformPlayer(forAudio) {
  var player = document.querySelector('.vjs-fluid');
  var controlbar = document.querySelector('.vjs-control-bar');
  if (forAudio) {
    player.classList.add('audioplayer');
    controlbar.classList.add('audiocontrol');
  } else {
    player.classList.remove('audioplayer');
    controlbar.classList.remove('audiocontrol');
  }
}
```

### 2 - Hide unnecessary buttons from the control bar

There are a bunch of buttons in the control bar that might not be relevant for an audio-only stream. Hence, we hide the following buttons using CSS:

* Subtitles button
* Quality label
* Audio menu
* Settings menu
* Fullscreen control
* Cast button

```css
.audiocontrol .vjs-icon-subtitles,
.audiocontrol .theo-quality-label,
.audiocontrol .vjs-icon-audio,
.audiocontrol .vjs-icon-cog,
.audiocontrol .vjs-fullscreen-control,
.audiocontrol .theo-cast-button,
.audioplayer video {
  display: none !important;
}
```

### 3 - Hide content that might appear above the control bar

Now we need to make sure no content appears above our controls. Again, we use CSS to hide elements:

* Poster image
* Video
* Metadata (like song info)

```css
.audiocontrol .theoplayer-poster,
.audiocontrol .song-info,
.audioplayer video {
  display: none !important;
}
```

### 4- Decrease the player's height

Next up, decreasing the player height to 50px.

```css
.audioplayer {
  padding: 0 !important;
  height: 50px !important;
}
```

### 5 Ensure the control bar is always visible

By default, the control bar fades away to ensure better user experience for the video viewer. The following snippet ensures that the controls stay always visible.

```css
.audiocontrol.vjs-control-bar {
  visibility: visible !important;
  opacity: 1 !important;
  display: flex !important;
}
```

### 6 - Rescale the loading spinner

An optional step is to scale the loading icon that spins when the player stalls.

```css
.audioplayer .vjs-loading-spinner {
  transform: scale(0.3) !important;
}
```

### 7 - Change appearance for when the stream is not yet loaded

We're almost there. We just need to remove the giant play-button that shows when the video hasn't started yet.

```css
:not(.vjs-has-started).audioplayer .vjs-big-play-button {
  display: none !important;
}
```

Should we stop here, the audio player would show 0:00 / 0:00 as time information, since the stream is not yet loaded. This looks a bit clumsy, so we can hide it until the stream has started.

```css
:not(.vjs-has-started).audioplayer .vjs-current-time,
:not(.vjs-has-started).audioplayer .vjs-time-divider,
:not(.vjs-has-started).audioplayer .vjs-duration {
  display: none !important;
}

.vjs-has-started .vjs-current-time,
.vjs-has-started .vjs-time-divider,
.vjs-has-started .vjs-duration {
  display: flex !important;
}
```

Note: if you preload the source, hiding the time information before the player starts playing may not be needed, as the duration will be already available.

### 8 - (Optional) Add the audioOnly flag

Finally, we recommend you to set the audioOnly flag to true in the player configuration. In that case, the player will use an audio element instead of a video element for media playback. This is only supported for HLS streams for now. Otherwise, the player uses a video element instead. This plays without any issue on most platforms, however we have noticed that Firefox doesn’t handle video elements with height and width 0 well.

```js
const player = new THEOplayer.Player(element, {
  audioOnly: true,
});
```

### Result

You should end up with a player that looks like this:

![Audio Only](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAq4AAAAxCAYAAAAbUCu5AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAefSURBVHhe7d1tiE1rH8fxO0kiKVFSlEhKSlI0ipQckRdESrwREfGGFAkpL7zACyHFiSQPaW6PpaOQckRpTnlIxNwJ54Q8lHE8X+f8/rdr32vW/u+918zuPnONvv/6ZO//tdbae01N/VzrWmv+9XcFAAAAoBNwmwAAAEBq3CYAAACQGrcJAAAApMZtAgAAAKlxmwAAAEBq3CYAAACQGrdZ5s9ffwKScPv27XZpaGgAAAAJ8rJnBW6zjBcggI7ghdIivF8UAADQ8bzsWYHbLOMFCKAjeKG0CO8XBQAAdDwve1bgNst4AQLoCF4oLcL7RQEAAB3Py54VuE0AAAAgNW4TAAAASI3bBAAAAFLjNgEAAIDUuE0AAAAgNW4TAAAASI3bBAAAAFLjNgEAAIDUuE0AAAAgNW4TAAAASI3b/KH07ds39OjRI6xcuTI8e/YsLFy40N0OAAAASXObhU2dOjXs3LmzZOLEiaWxUaNGtRpbsGBBq33/Cf369Qtv374NM2fODOvWrQuxXr58ad/d2wcAAABJcpuFnT9//nsU/G/t37+/NJYNiqqm35pa7fv/FkOrSsF10KBB4datW/Ze9enTJ+t5+7ZVly5d3L5UG4vq3T9ryJAhNsvsjeV169bN7bf1M/Pq3R8AAMDhNgtLNbhmQ6tKwTWOTZkyJXz8+NH6L168CF27dm21b1ts3LgxvHv3zo71/PnzMHz4cOvrmFd/vWrh+OvXr6GpqSkMHTq0bH8FvOvXr4cvX77YdteuXSt9n0WLFoXHjx/bsV+9ehXmzJlTtr/n9evXYc2aNe5Y1qpVq+zYvXv3LvUqnU/ezZs37TtH+kz1q50PAABAndxmYSkG13xoVSm4zp07Nyxbtsy2mT179veREM6cOVN2jCIaGhrCt2/fwt69e8PYsWPD73/8Hp4+fWpj+jkotE6ePNmWTCjYKcTlj3HkyJHw+fPnMGbMGFtmoePt2bMnDBs2zF4rBA4ePDg0/rvRgqAXfrM006r9evbs6Y6Lgurly5e/n/3/gmu188lred8Szp07Z2Fapk2bZv1K55PfHwAAoB3cZmEpBFcFLgXDSIExX9k1rhs2bLD9Tp48ae81+5o/ZhFHjx4NHz58KL1fsmSJHU+X37ds2WKfF8c0+6qZTL1+8OBBuHLlir3Wd58+fbq97tWrl4VTHXft2rV2rIEDB9qYjqnasWOHva9EM6aaRfbGotWrV4eWlhZbd6yKwbXa+cybN89+rpqB7d69u/UV/rVNdla20vnEcQAAgDq4zcJSCK4KpbUqG1wV2rSfZkNjaYYwf9xaFEZ1OT2+1yylSjOs2e369+9vl861vd43NjaG3bt3t9pGs5Lv3783WqM6evRoO9aMGTNsPB77xIkTrfbL05KEU6dOuWORgqcu6evmNFUMrtXOZ9KkSeHOnTthwIABFmJVmk2NtW3bttJ+kj+f7BgAAEA7uc3COmNwVY0cOdL2jeFr8eLFZcet5caNG+HJkyel9wpoKgXi2NOso55goFldLWGI/TxdYldo1PfZtGmT9d68eWOX5I8dO1Za+nD8+PGyfbP0OZoJ9cby8sG1yPmIlltoVlfLAzQjfP/+fQuo2W288wEAAKiT2yysswbXcePG2b6aCVUtX7687Li16Nyzl+UnTJhgx+rTp4+9179x6YJmUON21dy7d88Cq17rkrvCn0LhLxcuWIjdvHlz2T6RZkh1ad4b8+SDa63zqUTfUxVnh7Oy5wMAAFAnt1lYZwyucU1rvBSuGj9+fNlxa9HlcN2IFN/r+Jph1GvdHKXQqs+qFlrPnj3b6md2+vRpC5+aqd26datd1ldfN12pZs2aVdo2b//PP4eHDx+6Y558cK12Plnr168vrdEVPZ9XpRvKKp1PfA8AAFAHt1lYCsFVl6wVjqJ4+T9b2eB64MAB22/fvn32XrOu7XnuqJ4Bq9KaUs3gKqhqhlFjFy9etDHdLDV//nyj76Ax9VasWGGvDx06ZJ+vm5r0mC7dHNXc3GyPkFKI1DIB3Ryly/i6uavao6Wa/9Pcpjv488G12vmMGDEiHD582LaN/1HQz1NPOdAju+KsaqXziZ8JAABQB7dZWArBNU83WuWfLKCwpfC4a9eu0jYKuap401R7HDx40I6h0jpUzTqqH4+dLX0njWnN6927d+21ZlYfPXpkYVvUV0jU2Pbt20tLGbRMwLsUHyl46zPzN4ZVo2Cp0neIvUrns3TpUuvF4yuYx3PUecVnzFY7HwAAgDq5zcJSDK6SD69xtlN0Z3y82UnrR2ut4axFl/NrPV+1Fn2HbICMFEiLHFvb6c5/b6ytip6PPrNSKK10PgAAAHVwm4WlGlwlG14VXBXI9CiquJRA/7ZnbSsAAAA6hNssTI+RunTpUon+OlUcU3DMjsUH//+TYnhVcM0Gaa0fbc+TBAAAANBh3OYPRXf1648A6O/362YhPfxfNzx52wIAACBZbvOHpDWZ4o0BAAAgeW4TAAAASI3bBAAAAFLjNgEAAIDUuE0AAAAgNW4TAAAASI3bBAAAAFLjNgEAAIDUuE0AAAAgNW4TAAAASMv3P91PURRFURRFUUkXwZWiKIqiKIrqBBXCX2Lvh9WhXJHWAAAAAElFTkSuQmCC "Audio Only")

You can further modify the audio player that you have at this point to better fit in your implementation.

## Sample application

The demo below illustrates the transformation from video player to audio player.

* Demo: <http://cdn.theoplayer.com/demos/nus/audio-only.html>

---

# How to customize the volume slider on Web

This article provides information regarding the implementation of a vertical volume slider instead of the default horizontal one.

**Please note that the following page is meant as a general example and need in all cases to be further personalized. The aim is to show you the process of implementing a vertical volume slider.**

**In other words, this is a first step in a work in progress as it does not yet account for color and aspect customization, as well as for a series of other small details.**

There is currently no ready-made option in THEOplayer for changing the orientation of the volume slider with a simple parameter. However, good results can be achieved with a [custom button](https://www.theoplayer.com/theoplayer-demo-adding-buttons-to-the-ui-with-custom-logic).

Notes about the current example:

* it has been successfully tested on major browsers (Chrome, Firefox, Safari) but no complete investigation has been performed. In Edge the slider still does not appear correctly and needs some more CSS tinkering.
* it has been successfully tested in several conditions (fullscreen and inline presentation mode and on different resolutions). However, it still needs testing in your specific implementation and use case.
* The aspect of the current volume slider differs depending on the browser: we encourage you to replace it with your favorite one and customize it
* The volume icon changes when the player is muted, but otherwise do not reflect volume increases/decreases.
* When the player is muted, the slider and the aria values do not go to 0 yet

---

# How to disable click to pause on Web

When you use the default UI of THEOplayer you can pause (and resume) the video by clicking anywhere on the video (except in the control bar). You can confirm this behavior at <https://optiview.dolby.com/resources/demos/test-stream/>.

You might be interested in disabling this behavior because your functional requirements don't allow you to pause the video.

You can disable this default UX behavior through CSS. We'll also discuss some related APIs.

The following CSS snippet disables pause to click by no longer catching the pointer event.

```css
.video-js .vjs-tech {
  pointer-events: none;
}
```

The following JavaScript snippet automatically resumes a video when someone tries to pause it by leveraging the [`pause`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerEventMap#pause) event and the [`play()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/ChromelessPlayer#play) method.

```javascript
player.addEventListener('pause', () => {
  player.play();
});
```

The following CSS snippet hides the play and pause button.

```css
.video-js .vjs-play-control {
  display: none;
}
```

Interested in autoplay behavior? You might find ["How to combat autoplay policies"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-combat-autoplay-policies.md) an interesting read.

---

# UI skinning on Web

THEOplayer allows you to style the player to your own needs. This guide will give an in-depth explanation of which colors can be changed and which parts of the player are affected. First it will explain how to change the skin of your player using 6 custom CSS classes. Afterwards, an overview follows explaining which parts of the players are affected by each class. If you don't already have an up-and-running version of THEOplayer, take a look at our [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md).

## CSS properties to override

THEOplayer provides multiple colors you can change to create your desired look-and-feel. These colors can be changed easily by including a custom CSS file which overrides some classes. An example of such a file is given below. There is also an example page available where you can interactively change these colors and immediately see the effect: [Changing the UI with CSS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/changing-ui-with-css.md). **NOTE:** The vjs-selected is needed to change the color of selected items in the menus.

```html
<style>
  .theo-primary-color,
  .vjs-selected {
    color: #ffc50f !important;
  }

  .theo-primary-background {
    color: #000000 !important;
    background-color: #ffc50f !important;
  }

  .theo-secondary-color {
    color: #ffffff !important;
  }

  .theo-secondary-background {
    color: #000000 !important;
    background-color: #ffffff !important;
  }

  .theo-tertiary-color {
    color: #000000 !important;
  }

  .theo-tertiary-background {
    color: #ffffff !important;
    background-color: #000000 !important;
  }
</style>
```

## Affected Components

This section discusses which parts of the components are affected by each CSS class.

When the player is added to the page, the only visible control is the **big-play-button**. The color of this component is equal to the *theoplayer-primary-color.*

When the big-play-button is clicked, the player starts playing the video. Two components are visible now: the **control-bar** and the **sharing button**.

The background color of the\*\* control bar\*\* can be styled using *theoplayer-tertiary-color*.

The **control bar** exists of: **control-bar-icons**, the **progress bar** and **menu**s.

* The color of the control bar icons can be set using `theoplayer-secondary-color`.

* The color of the progress bar can be set using `theoplayer-primary-color`.

* The color and background color of the header of the menu can be set using `theoplayer-primary-background`.

* The color and background color of the content of the menu can be set using `theoplayer-tertiary-background`.

* The color of the selected text of the menu can be set using `theoplayer-primary-color`.

## Summary

After this tutorial, you should be able to style your THEOplayer to your own needs. All CSS properties and the components they affect were discussed. A brief summary of these properties is given below:

| Color                | Affected components                             |
| -------------------- | ----------------------------------------------- |
| Primary color        | Big play button, progress bar, menu text        |
| Primary background   | Menu header                                     |
| Secondary color      | Control bar icons (including time and tooltips) |
| Secondary background | Social sharing close button                     |
| Tertiary color       | Control bar background                          |
| Tertiary background  | Menu content background                         |

---

# Examples

See the player in action!

Search examples…

## Getting started

## [▶️Basic player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/getting-started/basic.md)

[A minimal player setup playing an HLS stream, with Open Video UI and with the Default UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/getting-started/basic.md)

## Streaming

## [🖥️4K streaming](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/4k-streaming.md)

[Play a 4K Ultra HD DASH stream, and see which quality is playing.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/4k-streaming.md)

## [📶Adaptive bitrate (ABR)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/abr.md)

[Compare the performance, quality and bandwidth ABR strategies, set an initial bitrate, and see which quality the player picks.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/abr.md)

## [⏪DVR and sliding windows for live streams](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/dvr.md)

[Seek within a live DVR window and follow program time.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/dvr.md)

## [⚡Fast source switching](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/fast-source-switching.md)

[Measure startup time when switching between video sources.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/fast-source-switching.md)

## [✨MPEG-5 LCEVC](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/lcevc.md)

[Play DASH or HLS streams with MPEG-5 LCEVC enhancement.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/lcevc.md)

## [🥽Virtual reality (360°)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/vr.md)

[Play a 360° video and read the VR direction (yaw, pitch and roll) and stereo mode from the VR API.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/vr.md)

## [🌐Network API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/network-api.md)

[Inspect and modify the player's HTTP requests and responses with network interceptors.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/network-api.md)

## [📡OptiView Real-time Streaming](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/millicast.md)

[Play a sub-second latency OptiView Real-time Streaming live stream.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/millicast.md)

## [📺OptiView Live Streaming](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/theolive.md)

[Play an OptiView Live Streaming real-time stream and see the current latency.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/theolive.md)

## [🔊Dolby Atmos](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/dolby-atmos.md)

[Detect and play Dolby Atmos audio.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/dolby-atmos.md)

## [🌈Dolby Vision](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/dolby-vision.md)

[Detect and play Dolby Vision video.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/streaming/dolby-vision.md)

## Playback control

## [🎞️Frame accurate seeking](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/frame-accurate-seeking.md)

[Step through a video frame by frame, or jump to a specific frame number.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/frame-accurate-seeking.md)

## [⏩Playback speed](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/playback-speed.md)

[Speed up or slow down a video by changing the playback rate.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/playback-speed.md)

## [⏱️Keeping track of time](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/keeping-track-of-time.md)

[Read the player's time, played, buffered, and seekable ranges.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/keeping-track-of-time.md)

## [🔁Continuous play](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/continuous-play.md)

[Resume playback from its last saved position.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/continuous-play.md)

## [🔖Creating bookmarks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/bookmarks.md)

[Save and restore playback bookmarks across videos.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/bookmarks.md)

## [⏳Preload](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/preload.md)

[Control how much of the video is buffered before playback starts with the preload property.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/preload.md)

## [📃Playlist and caching](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/playlist-and-caching.md)

[Build a playlist and preload upcoming items with the caching API.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/playlist-and-caching.md)

## User interface

## [🧩Adding buttons to the UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/adding-buttons.md)

[Add a custom menu, Skip intro button and seek buttons to both player UIs.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/adding-buttons.md)

## [🎨Changing the UI with CSS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/changing-ui-with-css.md)

[Change player colors and controls with CSS.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/changing-ui-with-css.md)

## [⚠️Custom error messages](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/custom-error-messages.md)

[Replace the default error messages with your own, in both Open Video UI and the Default UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/custom-error-messages.md)

## [🎬Related content](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/related-content.md)

[Show related videos in the player and play them without leaving the page.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/related-content.md)

## [🔗Social sharing](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/social-sharing.md)

[Add social sharing links, a direct link and an embed code to the player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/social-sharing.md)

## [🖼️Preview thumbnails](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/preview-thumbnails.md)

[Show preview thumbnails on the seek bar from manifest or side-loaded WebVTT tracks.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/preview-thumbnails.md)

## [🎧Audio-only player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/audio-only.md)

[Build an audio-only player with Open Video UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/audio-only.md)

## [👀Keep the control bar visible](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/keep-control-bar-visible.md)

[Keep the control bar visible at all times.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/keep-control-bar-visible.md)

## Subtitles and metadata

## [💬Closed captions and subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/subtitles-metadata/closed-captions-subtitles.md)

[Load, style, and inspect subtitles and closed captions.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/subtitles-metadata/closed-captions-subtitles.md)

## [🏷️ID3 metadata](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/subtitles-metadata/id3-metadata.md)

[Read ID3 metadata from an audio stream, show WXXX artwork behind the player, and overlay the song details.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/subtitles-metadata/id3-metadata.md)

## Casting

## [📺AirPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/casting/airplay.md)

[Stream to an Apple TV or another AirPlay receiver from Safari.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/casting/airplay.md)

## [📡Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/casting/chromecast.md)

[Cast to a Chromecast device with the auto, manual or disabled cast strategy, and test your own receiver application ID.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/casting/chromecast.md)

## Content protection

## [🔒DRM and AES-128 encryption](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/content-protection/drm.md)

[Play content protected with Widevine, PlayReady or FairPlay DRM, or encrypted with AES-128.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/content-protection/drm.md)

## Ads

## [📺Google DAI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/google-dai.md)

[Load Google DAI streams and inspect their ad breaks and events.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/google-dai.md)

## [📢Advertisement tester](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/advertisement-tester.md)

[Schedule VAST, VMAP and Google IMA ads at different positions, and inspect the resulting ad events.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/advertisement-tester.md)

## [🚫Ad block detection](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/ad-block-detection.md)

[Detect ad blockers and ad errors, and choose whether to block the content.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/ad-block-detection.md)

## Analytics

## [📊Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/analytics/conviva.md)

[Monitor playback with the Conviva connector.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/analytics/conviva.md)

---

# Basic player

This example plays a Big Buck Bunny HLS stream using a minimal player setup.

## Open Video UI

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

Open Video UI is provided by `<theoplayer-default-ui>`, configured through its `configuration` and `source` attributes.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Basic player</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the theoplayer.com CDN.
      For production use, we recommend hosting THEOplayer yourself
      and changing this (as well as the <script> tags above)
      to point to THEOplayer's location on your own website.

      licenseUrl: Change this to point to your THEOplayer license file.
      Alternatively, replace it with a "license" property whose value is your THEOplayer license itself.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg","metadata":{"title":"Big Buck Bunny"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
  </body>
</html>
```

## Default UI

The [Default UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/default-ui.md) is created with `new THEOplayer.Player()`.

Code

default-ui.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Basic player (Default UI)</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      .theoplayer-skin {
        width: 100%;
      }
    </style>
    <link rel="stylesheet" href="https://cdn.theoplayer.com/dash/theoplayer/ui.css" />
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
  </head>
  <body>
    <div id="player" class="video-js theoplayer-skin vjs-16-9"></div>
    <script>
      var player = new THEOplayer.Player(document.querySelector('#player'), {
        // For demonstration purposes, we use the theoplayer.com CDN.
        // For production use, we recommend hosting THEOplayer yourself
        // and changing this (as well as the <script> and <link> tags above)
        // to point to THEOplayer's location on your own website.
        libraryLocation: 'https://cdn.theoplayer.com/dash/theoplayer/',
        // Change this property to point to your THEOplayer license file:
        licenseUrl: '../../../../theoplayer-license.txt',
        // Alternatively, uncomment this, change its value to your THEOplayer license, and remove "licenseUrl":
        // license: 'your_theoplayer_license',
      });
      player.source = {
        sources: [
          {
            src: '//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
            type: 'application/x-mpegurl',
          },
        ],
      };
    </script>
  </body>
</html>
```

---

# 4K streaming

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

| Active video quality | Press play to start |
| -------------------- | ------------------- |
| Frame rate           | -                   |
| Bitrate              | -                   |

This example plays a 4K Ultra HD (3840×2160) MPEG-DASH stream using Open Video UI. The player uses adaptive bitrate streaming to pick the best quality that your network and device can handle, and switches to the 4K quality when enough bandwidth is available. You can also select a quality manually from the settings menu in the player.

The box below the player shows the quality that is currently playing, using the `activequalitychanged` event of the active video track.

By default, the player limits quality to the rendered player size only on mobile devices. Set `abr: { restrictToPlayerSize: true }` to apply this limit on all devices. Set `abr: { restrictToPlayerSize: false }` to allow larger qualities. Set `abr` on a typed source or in the player configuration. See [`restrictToPlayerSize`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/SourceAbrConfiguration#restrictToPlayerSize).

```js
player.source = {
  sources: {
    src: 'https://dash.akamaized.net/akamai/bbb_30fps/bbb_30fps.mpd',
    type: 'application/dash+xml',
    abr: { restrictToPlayerSize: true },
  },
};
```

> **Tip**
>
> To play 4K content, your device must be able to decode it and your screen should be large enough to show it. Enter fullscreen for the best experience.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>4K streaming</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the theoplayer.com CDN.
      For production use, we recommend hosting THEOplayer yourself
      and changing this (as well as the <script> tags above)
      to point to THEOplayer's location on your own website.

      licenseUrl: Change this to point to your THEOplayer license file.
      Alternatively, replace it with a "license" property whose value is your THEOplayer license itself.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://dash.akamaized.net/akamai/bbb_30fps/bbb_30fps.mpd","type":"application/dash+xml"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster-alt3.jpg","metadata":{"title":"Big Buck Bunny (4K)"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      onPlayerReady((player) => {
        // Report the quality of the video track that is currently playing.
        function reportActiveQuality() {
          const track = Array.from(player.videoTracks).find((track) => track.enabled);
          const quality = track && track.activeQuality;
          console.log('Active video quality', quality);
          sendToParent('activequality', {
            quality: quality && { width: quality.width, height: quality.height, bandwidth: quality.bandwidth, frameRate: quality.frameRate },
          });
        }

        player.videoTracks.addEventListener('addtrack', (event) => {
          event.track.addEventListener('activequalitychanged', reportActiveQuality);
        });
      });
    </script>
  </body>
</html>
```

---

# Adaptive bitrate (ABR)

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

ABR strategy

\[ ]`performance`\[ ]`quality`\[x]`bandwidth`

Start with a quality based on the bandwidth measured during previous sessions.

Initial bitrate (`metadata.bitrate`, in bps):e.g. 2000000Apply and reload

```js
player.abr.strategy = {
  type: 'bandwidth'
};
```

Qualities

| Current strategy                | - |
| ------------------------------- | - |
| Initial quality (chosen by ABR) | - |
| Active quality                  | - |
| Bandwidth estimate              | - |

| Available quality                 | Bandwidth |
| --------------------------------- | --------- |
| Press play to load the qualities. |           |

This example shows how the [ABR strategy](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/ABRStrategy) affects the quality that the player picks when it starts playing a stream.

* **`performance`**: start with a lower quality, so the video starts playing as fast as possible.
* **`quality`**: start with the highest quality, for the best visual quality from the start.
* **`bandwidth`** (default): start with a quality based on the bandwidth that was measured in previous sessions.

You can also pass ABR metadata with the strategy. The `metadata.bitrate` property sets the initial bitrate (in bits per second), which the player uses to pick its first quality before it has measured the actual bandwidth.

Choose a strategy, optionally enter an initial bitrate, and click **Apply and reload** to reload the stream with the new strategy. The box below the player lists the available qualities, the initial quality chosen by the ABR strategy, and the quality that is currently playing.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Adaptive bitrate (ABR)</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the theoplayer.com CDN.
      For production use, we recommend hosting THEOplayer yourself
      and changing this (as well as the <script> tags above)
      to point to THEOplayer's location on your own website.

      licenseUrl: Change this to point to your THEOplayer license file.
      Alternatively, replace it with a "license" property whose value is your THEOplayer license itself.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","abr":{"strategy":"bandwidth"},"mutedAutoplay":"all"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg","metadata":{"title":"Big Buck Bunny"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      onPlayerReady((player) => {
        const source = player.source;
        let initialQuality;

        function describeQuality(quality) {
          return quality && { id: quality.id, width: quality.width, height: quality.height, bandwidth: quality.bandwidth };
        }

        function reportState() {
          const track = Array.from(player.videoTracks).find((track) => track.enabled);
          sendToParent('abr', {
            strategy: player.abr.strategy,
            qualities: track ? Array.from(track.qualities).map(describeQuality) : [],
            initialQuality: describeQuality(initialQuality),
            activeQuality: describeQuality(track && track.activeQuality),
            bandwidthEstimate: player.metrics.currentBandwidthEstimate,
          });
        }

        player.videoTracks.addEventListener('addtrack', (event) => {
          const track = event.track;
          track.addEventListener('activequalitychanged', (event) => {
            // The first quality chosen after loading a source is picked by the ABR strategy.
            if (!initialQuality) {
              initialQuality = event.quality;
            }
            reportState();
          });
          reportState();
        });
        player.addEventListener(['progress', 'emptied'], reportState);

        // Change the ABR strategy, then reload the source to see which initial quality it picks.
        onParentMessage('abr-strategy', ({ strategy }) => {
          player.abr.strategy = strategy;
          initialQuality = undefined;
          player.autoplay = true;
          player.source = source;
          reportState();
        });

        reportState();
      });
    </script>
  </body>
</html>
```

---

# DVR and sliding windows for live streams

Use the seekable window to rewind a live stream or jump back to the live edge.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

### Seek controls

−30 s+30 sStart of windowGo live

**Buffered**

**Seekable**

| DVR window        | —–— (—) |
| ----------------- | ------- |
| Behind live       | —       |
| Current time      | 0.0 s   |
| Program date/time | —       |

A live stream can have `duration === Infinity`. The `seekable` ranges show the part of the live stream that is available for seeking. Open Video UI uses a live button to return to the end of the window.

```js
const lastRange = player.seekable.length - 1;
const liveEdge = player.seekable.end(lastRange);
player.currentTime = liveEdge - 30;
```

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>DVR</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://demo.unified-streaming.com/k8s/live/stable/live.isml/.m3u8","type":"application/x-mpegurl"},"metadata":{"title":"Live DVR stream"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      onPlayerReady((player) => {
        function ranges(timeRanges) {
          const result = [];
          for (let index = 0; index < timeRanges.length; index += 1) {
            result.push({ start: timeRanges.start(index), end: timeRanges.end(index) });
          }
          return result;
        }

        function currentWindow() {
          const ranges = player.seekable;
          if (ranges.length === 0) return null;
          return { start: ranges.start(0), end: ranges.end(ranges.length - 1) };
        }

        function report() {
          const range = currentWindow();
          const programDateTime = player.currentProgramDateTime;
          sendToParent('dvr', {
            currentTime: player.currentTime,
            duration: player.duration,
            seekableStart: range ? range.start : null,
            seekableEnd: range ? range.end : null,
            seekableLength: range ? range.end - range.start : null,
            behindLive: range ? Math.max(0, range.end - player.currentTime) : null,
            programDateTime: programDateTime instanceof Date && Number.isFinite(programDateTime.getTime()) ? programDateTime.toISOString() : null,
            buffered: ranges(player.buffered),
            seekable: ranges(player.seekable),
          });
        }

        onParentMessage('dvr-seek', (message) => {
          const range = currentWindow();
          if (!range) return;
          if (message.action === 'back') player.currentTime = Math.max(range.start, player.currentTime - 30);
          if (message.action === 'forward') player.currentTime = Math.min(range.end, player.currentTime + 30);
          if (message.action === 'start') player.currentTime = range.start;
          if (message.action === 'live') player.currentTime = player.seekable.end(player.seekable.length - 1);
          report();
        });

        player.addEventListener(['timeupdate', 'progress', 'durationchange', 'seeked'], report);
        let pausedTimer = 0;
        function updatePausedTimer() {
          window.clearInterval(pausedTimer);
          if (player.paused) pausedTimer = window.setInterval(report, 1000);
        }
        player.addEventListener(['play', 'pause'], updatePausedTimer);
        window.addEventListener('pagehide', () => window.clearInterval(pausedTimer));

        report();
        updatePausedTimer();
      });
    </script>
  </body>
</html>
```

---

# Fast source switching

Compare how long the player takes to start after changing the source.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

### Presets

Big Buck BunnyFrame counter 60 fpsAdult Swim

### Custom stream

URLTypeAuto (auto)Load

### Latest TTFF

Waiting for the first measurement.

### Recent switches

| Source                 | TTFF | Since source |
| ---------------------- | ---- | ------------ |
| No completed switches. |      |              |

The initial source stays paused until you start playback, so the time since it was set is left blank. When you load another source, the demo measures time to first frame and time since that source was set. It ignores events from superseded switches.

```js
function loadSource(streamUrl) {
  player.autoplay = true;
  player.source = {
    sources: { src: streamUrl, type: 'application/x-mpegurl' },
  };
}
```

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Fast source switching</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const initialSource = {
        src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
        label: 'Big Buck Bunny',
        mediaType: 'hls',
        poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
      };
      let switchToken = 0;
      let activeListeners = [];

      function sourceConfiguration(source) {
        const contentType = source.mediaType === 'hls' ? 'application/x-mpegurl' : source.mediaType === 'dash' ? 'application/dash+xml' : null;
        return {
          sources: {
            src: source.src,
            ...(contentType ? { type: contentType } : {}),
          },
          ...(source.poster ? { poster: source.poster } : {}),
          metadata: { title: source.label },
        };
      }

      onPlayerReady((player) => {
        let history = [];

        function report(record) {
          history = [record, ...history].slice(0, 10);
          sendToParent('switch-measurements', { latest: record, history });
        }

        function removeActiveListeners() {
          activeListeners.forEach(([eventName, listener]) => player.removeEventListener(eventName, listener));
          activeListeners = [];
        }

        function trackSwitch(source, sourceSetAt) {
          removeActiveListeners();
          const token = ++switchToken;
          const measurement = {
            source: source.label,
            playStartedAt: null,
            complete: false,
          };

          function isCurrent() {
            return token === switchToken;
          }

          function finish(error) {
            if (!isCurrent() || measurement.complete) return;
            measurement.complete = true;
            const now = performance.now();
            report({
              source: measurement.source,
              ttff: measurement.playStartedAt === null || error ? null : now - measurement.playStartedAt,
              sinceSourceChange: sourceSetAt === null || error ? null : now - sourceSetAt,
              error: error || null,
            });
            removeActiveListeners();
          }

          function onPlay() {
            if (!isCurrent() || measurement.complete || measurement.playStartedAt !== null) return;
            measurement.playStartedAt = performance.now();
          }

          function onPlaying() {
            if (!isCurrent() || measurement.complete || measurement.playStartedAt === null) return;
            finish(null);
          }

          function onError(event) {
            const playerError = player.errorObject;
            const message =
              (playerError && playerError.message) || (event && event.message) || (event && event.error && event.error.message) || 'Player error';
            finish(message);
          }

          activeListeners = [
            ['play', onPlay],
            ['playing', onPlaying],
            ['error', onError],
          ];
          activeListeners.forEach(([eventName, listener]) => player.addEventListener(eventName, listener));
        }

        function beginSwitch(source) {
          const sourceSetAt = performance.now();
          trackSwitch(source, sourceSetAt);
          player.source = sourceConfiguration(source);
        }

        onParentMessage('switch-source', (message) => {
          if (typeof message.src !== 'string' || !message.src) return;
          const mediaType = message.mediaType === 'hls' || message.mediaType === 'dash' ? message.mediaType : 'auto';
          player.autoplay = true;
          beginSwitch({
            src: message.src,
            label: typeof message.label === 'string' ? message.label : message.src,
            mediaType,
          });
        });

        trackSwitch(initialSource, null);
        player.source = sourceConfiguration(initialSource);
      });
    </script>
  </body>
</html>
```

---

# MPEG-5 LCEVC

Load the LCEVC decoder before setting a source that uses LCEVC enhancement.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

DASHHLS

| LCEVC decoder loaded | No |
| -------------------- | -- |
| Active quality       | —  |

### Available qualities

| Quality                          | Bandwidth |
| -------------------------------- | --------- |
| Waiting for quality information. |           |

The SDK must include the `lcevc` feature, and the LCEVC decoder script must load before the source is set. LCEVC playback requires Media Source Extensions. On iOS Safari, the player falls back to native playback without LCEVC enhancement.

```html
<script src="https://unpkg.com/lcevc_dec.js@1.3.0/dist/lcevc_dec.min.js"></script>
```

```js
function loadLcevcSource() {
  player.autoplay = true;
  player.abr.strategy = 'quality';
  player.source = {
    sources: {
      src: 'https://d3mfda3gpj3dw1.cloudfront.net/vnU7dmJoRQgbO0gr/master.mpd',
      type: 'application/dash+xml',
      lcevc: true,
    },
  };
}
```

See [how to play an LCEVC source](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/how-to-play-an-lcevc-source-with-theoplayer.md) for more prerequisites.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>MPEG-5 LCEVC</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://unpkg.com/lcevc_dec.js@1.3.0/dist/lcevc_dec.min.js"></script>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const sources = {
        dash: {
          sources: {
            src: 'https://d3mfda3gpj3dw1.cloudfront.net/vnU7dmJoRQgbO0gr/master.mpd',
            type: 'application/dash+xml',
            lcevc: true,
          },
        },
        hls: {
          sources: {
            src: 'https://d3mfda3gpj3dw1.cloudfront.net/vnU7dmJoRQgbO0gr/master.m3u8',
            type: 'application/x-mpegurl',
            lcevc: true,
          },
        },
      };

      onPlayerReady((player) => {
        player.abr.strategy = 'quality';

        function report() {
          const track = Array.from(player.videoTracks).find((videoTrack) => videoTrack.enabled);
          const activeQuality = track && track.activeQuality;
          sendToParent('lcevc', {
            decoderLoaded: typeof LCEVCdec !== 'undefined',
            activeQuality: activeQuality
              ? {
                  id: activeQuality.id,
                  width: activeQuality.width,
                  height: activeQuality.height,
                  bandwidth: activeQuality.bandwidth,
                  frameRate: activeQuality.frameRate,
                }
              : null,
            qualities: track
              ? Array.from(track.qualities).map((quality) => ({
                  id: quality.id,
                  width: quality.width,
                  height: quality.height,
                  bandwidth: quality.bandwidth,
                  frameRate: quality.frameRate,
                }))
              : [],
          });
        }

        player.videoTracks.addEventListener('addtrack', (event) => {
          event.track.addEventListener('activequalitychanged', report);
          report();
        });
        player.addEventListener(['sourcechange', 'durationchange'], report);
        player.addEventListener('error', report);
        onParentMessage('lcevc-format', (message) => {
          if (message.format !== 'dash' && message.format !== 'hls') return;
          player.autoplay = true;
          player.source = sources[message.format];
          report();
        });

        player.source = sources.dash;
        report();
      });
    </script>
  </body>
</html>
```

---

# Virtual reality (360°)

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

| `vr.state`           | - |
| -------------------- | - |
| `vr.stereo`          | - |
| `vr.direction.yaw`   | - |
| `vr.direction.pitch` | - |
| `vr.direction.roll`  | - |
| `vr.verticalFOV`     | - |
| `vr.canPresentVR`    | - |

This example plays a 360° video. To mark a source as a 360° video, set `vr: { 360: true }` on the source description. Drag the video (or move your phone) to look around.

The box below the player reports the values of the [VR API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VR). They are updated using the `directionchange`, `stereochange` and `statechange` events of `player.vr`. Stereo mode is toggled with the button in the player's control bar, which only appears when `player.vr.canPresentVR` is true (for example, when a WebXR device such as a VR headset is available). Entering an immersive WebXR session must be triggered by a user gesture inside the player's page.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Virtual reality (360°)</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the theoplayer.com CDN.
      For production use, we recommend hosting THEOplayer yourself
      and changing this (as well as the <script> tags above)
      to point to THEOplayer's location on your own website.

      licenseUrl: Change this to point to your THEOplayer license file.
      Alternatively, replace it with a "license" property whose value is your THEOplayer license itself.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","vr":{"useWebXR":true}}'
      source='{"sources":{"src":"https://demo.theoplayer.com/hubfs/videos/natgeo/playlist.m3u8","type":"application/x-mpegurl"},"poster":"https://demo.theoplayer.com/hubfs/videos/natgeo/poster.jpg","vr":{"360":true},"metadata":{"title":"National Geographic 360\u00b0"}}'
    >
      <theoplayer-button
        id="stereo-toggle"
        slot="bottom-control-bar"
        aria-label="Toggle stereo (VR headset)"
        title="Toggle stereo (VR headset)"
        hidden
        >Stereo</theoplayer-button
      >
    </theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      onPlayerReady((player) => {
        const vr = player.vr;
        let pending = false;

        function reportState() {
          // Report at most once per animation frame, since the direction changes very often.
          if (pending) return;
          pending = true;
          requestAnimationFrame(() => {
            pending = false;
            sendToParent('vr', {
              state: vr.state,
              canPresentVR: vr.canPresentVR,
              stereo: vr.stereo,
              verticalFOV: vr.verticalFOV,
              direction: { ...vr.direction },
            });
          });
        }
        vr.addEventListener(['directionchange', 'stereochange', 'statechange'], reportState);

        const stereoButton = document.querySelector('#stereo-toggle');
        function updateStereoButton() {
          const canPresentVR = vr.canPresentVR;
          stereoButton.hidden = !canPresentVR;
          stereoButton.disabled = !canPresentVR;
          stereoButton.setAttribute('aria-pressed', String(vr.stereo));
          stereoButton.textContent = vr.stereo ? 'Stereo on' : 'Stereo';
        }
        stereoButton.addEventListener('click', () => {
          vr.stereo = !vr.stereo;
        });
        vr.addEventListener(['statechange', 'stereochange'], updateStereoButton);
        updateStereoButton();

        reportState();
      });
    </script>
  </body>
</html>
```

---

# Network API

Inspect and modify every HTTP request and response the player performs with network interceptors.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

### Network log

AllRequestsResponses

Pause logClear\[x]Reverse subtitle text (response interceptor)

No requests logged yet. Play the video to see network traffic.

`player.network.addRequestInterceptor()` fires for every outgoing request; `addResponseInterceptor()` for every incoming response. This example logs each one, and — while the checkbox is on — reverses the text of every `.vtt` subtitle response body with `response.respondWith()`, so enable subtitles to see the effect. The interceptor only affects subtitle files loaded after it runs.

```js
player.network.addRequestInterceptor((request) => {
  console.log('Request', request.method, request.url);
});

player.network.addResponseInterceptor((response) => {
  console.log('Response', response.status, response.url);
  if (response.url.indexOf('.vtt') !== -1 && typeof response.body === 'string') {
    response.respondWith({ body: transform(response.body) });
  }
});
```

See the [request and response interceptors guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/network/request-response-interceptors.md).

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Network API</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      id="player-ui"
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/tears_of_steel/index.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/tears_of_steel/poster.jpg","metadata":{"title":"Tears of Steel"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      let reverseSubtitles = true;

      function header(headers, name) {
        if (!headers) return '—';
        const key = Object.keys(headers).find((entry) => entry.toLowerCase() === name.toLowerCase());
        return key ? headers[key] : '—';
      }

      function timestamp() {
        const now = new Date();
        const pad = (value, length) => String(value).padStart(length, '0');
        return `${pad(now.getUTCHours(), 2)}:${pad(now.getUTCMinutes(), 2)}:${pad(now.getUTCSeconds(), 2)}.${pad(now.getUTCMilliseconds(), 3)}`;
      }

      function logEntry(entry) {
        sendToParent('network-entry', { entry });
      }

      onPlayerReady((player) => {
        // Intercept every request the player makes and report it to the demo page.
        player.network.addRequestInterceptor((request) => {
          logEntry({
            kind: 'Request',
            time: timestamp(),
            method: request.method || '—',
            type: request.type || '—',
            subType: request.subType || '—',
            url: request.url,
            contentType: header(request.headers, 'Content-Type'),
            contentLength: header(request.headers, 'Content-Length'),
          });
        });

        // Intercept every response. For .vtt subtitle files, reverse each cue's text.
        player.network.addResponseInterceptor((response) => {
          logEntry({
            kind: 'Response',
            time: timestamp(),
            status: `${response.status} ${response.statusText || ''}`.trim(),
            type: (response.request && response.request.type) || '—',
            subType: (response.request && response.request.subType) || '—',
            url: response.url,
            contentType: header(response.headers, 'Content-Type'),
            contentLength: header(response.headers, 'Content-Length'),
          });
          if (
            reverseSubtitles &&
            response.url.indexOf('.vtt') !== -1 &&
            (typeof response.body === 'string' || response.body instanceof ArrayBuffer)
          ) {
            const text = typeof response.body === 'string' ? response.body : new TextDecoder().decode(response.body);
            const newText = text.replace(/\r\n/g, '\n').replace(/.+ --> .+\n([\s\S]*?)\n\n/g, (match, cueText) => {
              const newCueText = cueText
                .split('\n')
                .map((line) => line.split('').reverse().join(''))
                .join('\n');
              return match.replace(cueText, newCueText);
            });
            response.respondWith({
              body: typeof response.body === 'string' ? newText : new TextEncoder().encode(newText).buffer,
            });
          }
        });

        onParentMessage('network-reverse', (message) => {
          if (typeof message.enabled === 'boolean') reverseSubtitles = message.enabled;
        });
      });
    </script>
  </body>
</html>
```

---

# OptiView Real-time Streaming

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

[OptiView Real-time Streaming](https://docs-preview.optiview.dolby.com/pr-932/millicast/getting-started.md) (formerly Millicast) delivers real-time streaming with sub-second latency over WebRTC. THEOplayer can subscribe to an OptiView Real-time stream directly: set the source `type` to `"millicast"` and provide the stream name (`src`) and account identifier (`streamAccountId`).

```js
player.source = {
  sources: {
    type: 'millicast',
    src: 'multiview',
    streamAccountId: 'k9Mwad',
    // subscriberToken: '...' // for secure streams
  },
};
```

See the [`MillicastSource`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/MillicastSource) API reference for all available fields, including `subscriberToken` for secure streams.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>OptiView Real-time Streaming</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.

      An OptiView Real-time Streaming live source: 'src' is the stream name, 'streamAccountId' the account.
      Secure streams also need a 'subscriberToken'.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
      source='{"sources":{"type":"millicast","src":"multiview","streamAccountId":"k9Mwad"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
  </body>
</html>
```

---

# OptiView Live Streaming

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

| player.latency.currentLatency | — |
| ----------------------------- | - |

[OptiView Live Streaming](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/theolive/getting-started.md) delivers real-time video at sub-second latency. Set the source `type` to `"theolive"` and `src` to your channel or distribution ID.

```js
player.source = {
  sources: {
    type: 'theolive',
    src: 'ar5c53uzm3si4h4zgkzrju44h',
  },
};
```

The readout above shows `player.latency.currentLatency`, the end-to-end latency in seconds, updated on every `timeupdate` event. See the [`TheoLiveSource`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TheoLiveSource) API reference for all available fields.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>OptiView Live Streaming</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.

      An OptiView Live Streaming source: 'src' is the channel or distribution ID.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
      source='{"sources":{"type":"theolive","src":"ar5c53uzm3si4h4zgkzrju44h"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      onPlayerReady((player) => {
        // player.latency.currentLatency is only available during live playback.
        player.addEventListener('timeupdate', () => {
          sendToParent('latency', { latency: player.latency.currentLatency ?? null });
        });
      });
    </script>
  </body>
</html>
```

---

# Dolby Atmos

**Checking support…**

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

**Source**

DASHHLS

This example plays a Dolby Atmos (ec-3, 16/JOC) stream and probes the browser for Atmos support with [`MediaCapabilities.decodingInfo`](https://developer.mozilla.org/en-US/docs/Web/API/Media_Capabilities_API): once for plain Dolby Digital Plus decoding, and once with `spatialRendering: true` for Atmos. When `navigator.mediaCapabilities` is unavailable it falls back to `MediaSource.isTypeSupported`.

```js
await navigator.mediaCapabilities.decodingInfo({
  type: 'media-source',
  audio: {
    contentType: 'audio/mp4; codecs="ec-3"',
    channels: '16',
    bitrate: 768000,
    samplerate: 48000,
    spatialRendering: true,
  },
});
```

The status box above the player is green when both checks pass, yellow when the stream plays but without Atmos spatial rendering, and red when the browser cannot decode ec-3 at all.

> **Note**
>
> Browsers cannot report whether the connected speakers or headphones are Atmos-capable — the check only covers decoding, not the output device.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Dolby Atmos</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
      source='{"sources":{"src":"https://ott.dolby.com/OTTEP/ddp/clear_cmaf/16JOC/dash.mpd","type":"application/dash+xml"},"metadata":{"title":"Dolby Atmos (16/JOC)"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      // Detect Dolby Atmos support: ec-3 (Dolby Digital Plus) decoding with spatial rendering.
      async function probeAudio(contentType, channels, spatialRendering) {
        const audio = { contentType, channels, bitrate: 768000, samplerate: 48000, spatialRendering };
        if (navigator.mediaCapabilities && navigator.mediaCapabilities.decodingInfo) {
          try {
            const result = await navigator.mediaCapabilities.decodingInfo({ type: 'media-source', audio });
            return { status: result.supported ? 'supported' : 'unsupported' };
          } catch (e) {
            return { status: 'unsupported' };
          }
        }
        if (window.MediaSource) {
          // MediaSource.isTypeSupported cannot probe channel count or spatial rendering.
          return { status: MediaSource.isTypeSupported(contentType) ? 'supported' : 'unsupported', fallback: true };
        }
        return { status: 'unavailable' };
      }

      function reportActiveCodecs(player) {
        const videoTrack = Array.from(player.videoTracks).find((track) => track.enabled);
        const audioTrack = Array.from(player.audioTracks).find((track) => track.enabled);
        const codecs = [
          videoTrack && videoTrack.activeQuality && videoTrack.activeQuality.codecs,
          audioTrack && audioTrack.activeQuality && audioTrack.activeQuality.codecs,
        ]
          .filter(Boolean)
          .join(', ');
        if (codecs) sendToParent('playing-codecs', { codecs });
      }

      onPlayerReady(async (player) => {
        const ec3 = 'audio/mp4; codecs="ec-3"';
        const [ddp, atmos] = await Promise.all([probeAudio(ec3, '16', false), probeAudio(ec3, '16', true)]);
        const checks = [
          { label: 'Dolby Digital Plus (ec-3, 16 channels)' + (ddp.fallback ? ' — via MediaSource.isTypeSupported' : ''), status: ddp.status },
          { label: 'Dolby Atmos (ec-3 spatial rendering)' + (atmos.fallback ? ' — via MediaSource.isTypeSupported' : ''), status: atmos.status },
        ];
        const level = ddp.status === 'supported' && atmos.status === 'supported' ? 'success' : ddp.status === 'supported' ? 'warning' : 'danger';
        const summary =
          level === 'success'
            ? 'Dolby Atmos is supported on this device.'
            : level === 'warning'
              ? 'Dolby Digital Plus plays, but without Atmos spatial rendering.'
              : 'This browser cannot decode Dolby Digital Plus (ec-3) audio.';
        sendToParent('detection-status', { level, summary, checks });

        player.videoTracks.addEventListener('addtrack', (event) =>
          event.track.addEventListener('activequalitychanged', () => reportActiveCodecs(player))
        );
        player.audioTracks.addEventListener('addtrack', (event) =>
          event.track.addEventListener('activequalitychanged', () => reportActiveCodecs(player))
        );

        onParentMessage('load-source', (message) => {
          player.autoplay = true;
          player.source = message.source;
        });
      });
    </script>
  </body>
</html>
```

---

# Dolby Vision

**Checking support…**

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

**Source**

DASHHLS

This example plays a Dolby Vision profile 8.4 stream (an HLG-compatible base layer with a Dolby Vision enhancement layer, signaled via supplemental codecs: `dvh1.08.xx` in DASH via `scte214:supplementalCodecs`, and `dvhe.08.xx` in HLS via `SUPPLEMENTAL-CODECS`). It probes the browser with [`MediaCapabilities.decodingInfo`](https://developer.mozilla.org/en-US/docs/Web/API/Media_Capabilities_API) for the Dolby Vision codec (`dvh1.08.09` or `dvhe.08.09`) and the HEVC Main10 HLG base layer (`hvc1.2.4.L153.90` or `hev1.2.4.L153.90`), and checks for an HDR display with `matchMedia('(dynamic-range: high)')`, re-checking when the display capability changes.

```js
await navigator.mediaCapabilities.decodingInfo({
  type: 'media-source',
  video: {
    contentType: 'video/mp4; codecs="dvh1.08.09"',
    bitrate: 18000000,
    width: 3840,
    height: 2160,
    framerate: 60,
    transferFunction: 'hlg',
  },
});

const hdrDisplay = matchMedia('(dynamic-range: high)').matches;
```

The status box is green when Dolby Vision decoding and an HDR display are both present, yellow when the browser can decode only the HEVC HLG base layer and not Dolby Vision, or when the display does not support HDR, and red when the browser cannot decode the HEVC base layer at all.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Dolby Vision</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
      source='{"sources":{"src":"https://ott.dolby.com/OTTEP/prod/v1_1/dovi/11/ta/clear/p8.4/60fps/hvc1/hvc1_supp.mpd","type":"application/dash+xml"},"metadata":{"title":"Dolby Vision (profile 8.4)"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      // Detect Dolby Vision support: a Dolby Vision codec (dvh1/dvhe, profile 8) plus an HDR display.
      // The DASH manifest signals dvh1.08.xx, the HLS manifest dvhe.08.xx; base layer is hvc1/hev1 HLG.
      async function probeVideo(contentType, transferFunction) {
        const video = { contentType, bitrate: 18000000, width: 3840, height: 2160, framerate: 60, transferFunction };
        if (navigator.mediaCapabilities && navigator.mediaCapabilities.decodingInfo) {
          try {
            const result = await navigator.mediaCapabilities.decodingInfo({ type: 'media-source', video });
            return { status: result.supported ? 'supported' : 'unsupported' };
          } catch (e) {
            return { status: 'unsupported' };
          }
        }
        if (window.MediaSource) {
          // MediaSource.isTypeSupported cannot probe the transfer function.
          return { status: MediaSource.isTypeSupported(contentType) ? 'supported' : 'unsupported', fallback: true };
        }
        return { status: 'unavailable' };
      }

      function hdrDisplay() {
        if (!window.matchMedia) return { status: 'unavailable' };
        return { status: window.matchMedia('(dynamic-range: high)').matches ? 'supported' : 'unsupported' };
      }

      function reportActiveCodecs(player) {
        const videoTrack = Array.from(player.videoTracks).find((track) => track.enabled);
        const audioTrack = Array.from(player.audioTracks).find((track) => track.enabled);
        const codecs = [
          videoTrack && videoTrack.activeQuality && videoTrack.activeQuality.codecs,
          audioTrack && audioTrack.activeQuality && audioTrack.activeQuality.codecs,
        ]
          .filter(Boolean)
          .join(', ');
        if (codecs) sendToParent('playing-codecs', { codecs });
      }

      onPlayerReady(async (player) => {
        async function report() {
          const [dvh1, dvhe, hvc1, hev1] = await Promise.all([
            probeVideo('video/mp4; codecs="dvh1.08.09"', 'hlg'),
            probeVideo('video/mp4; codecs="dvhe.08.09"', 'hlg'),
            probeVideo('video/mp4; codecs="hvc1.2.4.L153.90"', 'hlg'),
            probeVideo('video/mp4; codecs="hev1.2.4.L153.90"', 'hlg'),
          ]);
          // Either codec string is enough: dvh1 (DASH) or dvhe (HLS) for Dolby Vision,
          // hvc1 (DASH) or hev1 (HLS) for the HEVC HLG base layer.
          const dv =
            dvh1.status === 'supported' || dvhe.status === 'supported'
              ? { status: 'supported', fallback: dvh1.fallback && dvhe.fallback }
              : {
                  status: dvh1.status === 'unavailable' && dvhe.status === 'unavailable' ? 'unavailable' : 'unsupported',
                  fallback: dvh1.fallback || dvhe.fallback,
                };
          const hevc =
            hvc1.status === 'supported' || hev1.status === 'supported'
              ? { status: 'supported', fallback: hvc1.fallback && hev1.fallback }
              : {
                  status: hvc1.status === 'unavailable' && hev1.status === 'unavailable' ? 'unavailable' : 'unsupported',
                  fallback: hvc1.fallback || hev1.fallback,
                };
          const hdr = hdrDisplay();
          const checks = [
            {
              label: 'Dolby Vision codec (dvh1.08.09 or dvhe.08.09, HLG)' + (dv.fallback ? ' — via MediaSource.isTypeSupported' : ''),
              status: dv.status,
            },
            {
              label:
                'HEVC Main10 HLG base layer (hvc1.2.4.L153.90 or hev1.2.4.L153.90)' + (hevc.fallback ? ' — via MediaSource.isTypeSupported' : ''),
              status: hevc.status,
            },
            { label: 'HDR display (dynamic-range: high)', status: hdr.status },
          ];
          const level = hevc.status !== 'supported' ? 'danger' : dv.status !== 'supported' || hdr.status !== 'supported' ? 'warning' : 'success';
          const summary =
            level === 'success'
              ? 'Dolby Vision is supported on this device and display.'
              : level === 'danger'
                ? 'This browser cannot decode HEVC video.'
                : dv.status !== 'supported'
                  ? 'This browser cannot decode Dolby Vision, only the HEVC HLG base layer.'
                  : 'This browser can decode Dolby Vision, but this display does not support HDR.';
          sendToParent('detection-status', { level, summary, checks });
        }

        await report();
        if (window.matchMedia) {
          window.matchMedia('(dynamic-range: high)').addEventListener('change', report);
        }

        player.videoTracks.addEventListener('addtrack', (event) =>
          event.track.addEventListener('activequalitychanged', () => reportActiveCodecs(player))
        );
        player.audioTracks.addEventListener('addtrack', (event) =>
          event.track.addEventListener('activequalitychanged', () => reportActiveCodecs(player))
        );

        onParentMessage('load-source', (message) => {
          player.autoplay = true;
          player.source = message.source;
        });
      });
    </script>
  </body>
</html>
```

---

# Frame accurate seeking

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

Previous frameNext frame

Frame:240Go to frame

| Current frame | - |
| ------------- | - |
| Current time  | - |
| Frame rate    | - |
| Status        | - |

This example shows how to step through a video frame by frame, or jump directly to a specific frame.

A frame number is converted to a time by dividing it by the frame rate of the video (24 frames per second for this video), and the player seeks to the middle of that frame by setting `player.currentTime`. The current frame number is calculated the other way around, from `player.currentTime`.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Frame accurate seeking</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the theoplayer.com CDN.
      For production use, we recommend hosting THEOplayer yourself
      and changing this (as well as the <script> tags above)
      to point to THEOplayer's location on your own website.

      licenseUrl: Change this to point to your THEOplayer license file.
      Alternatively, replace it with a "license" property whose value is your THEOplayer license itself.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg","metadata":{"title":"Big Buck Bunny"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      // The frame rate of the stream. Big Buck Bunny runs at 24 frames per second.
      const DEFAULT_FRAME_RATE = 24;

      onPlayerReady((player) => {
        function getFrameRate() {
          const track = Array.from(player.videoTracks).find((track) => track.enabled);
          const quality = track && track.activeQuality;
          return (quality && quality.frameRate) || DEFAULT_FRAME_RATE;
        }

        function getCurrentFrame() {
          // Add a small margin to avoid rounding errors.
          return Math.floor(player.currentTime * getFrameRate() + 0.001);
        }

        function seekToFrame(frame) {
          player.pause();
          // Seek to the middle of the frame, so the player shows exactly that frame.
          player.currentTime = (Math.max(0, frame) + 0.5) / getFrameRate();
        }

        function reportState() {
          sendToParent('frame', {
            frame: getCurrentFrame(),
            currentTime: player.currentTime,
            frameRate: getFrameRate(),
            paused: player.paused,
          });
        }
        player.addEventListener(['timeupdate', 'seeked', 'play', 'pause', 'loadedmetadata'], reportState);

        onParentMessage('frame', ({ action, frame }) => {
          switch (action) {
            case 'previous':
              seekToFrame(getCurrentFrame() - 1);
              break;
            case 'next':
              seekToFrame(getCurrentFrame() + 1);
              break;
            case 'goto':
              seekToFrame(frame);
              break;
          }
        });

        reportState();
      });
    </script>
  </body>
</html>
```

---

# Playback speed

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

0.25×0.5×0.75×1×1.25×1.5×2×4×

| `player.playbackRate` | 1 |
| --------------------- | - |

This example shows how to change the playback speed of a video with `player.playbackRate`. A value of `1` plays the video at normal speed, lower values slow it down and higher values speed it up. You can also change the playback speed from the settings menu in the player.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Playback speed</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the theoplayer.com CDN.
      For production use, we recommend hosting THEOplayer yourself
      and changing this (as well as the <script> tags above)
      to point to THEOplayer's location on your own website.

      licenseUrl: Change this to point to your THEOplayer license file.
      Alternatively, replace it with a "license" property whose value is your THEOplayer license itself.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/poster.jpg","metadata":{"title":"Star Wars: The Force Awakens (Comic-Con 2015 reel)"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      onPlayerReady((player) => {
        function reportPlaybackRate() {
          sendToParent('ratechange', { playbackRate: player.playbackRate });
        }
        player.addEventListener('ratechange', reportPlaybackRate);

        onParentMessage('playback-rate', ({ playbackRate }) => {
          player.playbackRate = playbackRate;
        });

        reportPlaybackRate();
      });
    </script>
  </body>
</html>
```

---

# Keeping track of time

Inspect the current playhead and the ranges that describe media playback.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

| Current time | 0:00.0 |
| ------------ | ------ |
| Duration     | 0:00.0 |
| Paused       | Yes    |

**Played**

**Buffered**

**Seekable**

`TimeRanges` can contain zero or more intervals. Listen for playback and buffering events to keep a readout current. See the [`TimeRanges` API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TimeRanges).

```js
function updateRanges() {
  console.log(player.currentTime, player.duration, player.played, player.buffered, player.seekable);
}

player.addEventListener(['timeupdate', 'progress', 'durationchange', 'seeking', 'seeked', 'play', 'pause'], updateRanges);
```

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Keeping track of time</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg","metadata":{"title":"Big Buck Bunny"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      onPlayerReady((player) => {
        function ranges(timeRanges) {
          const result = [];
          for (let index = 0; index < timeRanges.length; index += 1) {
            result.push({ start: timeRanges.start(index), end: timeRanges.end(index) });
          }
          return result;
        }

        function report() {
          sendToParent('time-ranges', {
            currentTime: player.currentTime,
            duration: player.duration,
            paused: player.paused,
            played: ranges(player.played),
            buffered: ranges(player.buffered),
            seekable: ranges(player.seekable),
          });
        }

        player.addEventListener(['timeupdate', 'progress', 'durationchange', 'seeking', 'seeked', 'play', 'pause'], report);
        report();
      });
    </script>
  </body>
</html>
```

---

# Continuous play

Save the current playhead position and restore it when the player loads again.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

### Saved position

Reload playerClear saved position

| Saved            | —    |
| ---------------- | ---- |
| Restored from    | —    |
| Current playhead | 0:00 |

This demo stores the playhead in `localStorage` for this source URL. It saves during playback, on pause, and when the page is closed. The position is cleared when playback ends. Local storage and cookies persist only in the same browser. For cross-device continuity, store the position on your server for the signed-in user.

```js
const key = `theoplayer-continuous-play:${sourceUrl}`;
localStorage.setItem(key, String(player.currentTime));
```

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Continuous play</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg","metadata":{"title":"Big Buck Bunny"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const sourceUrl = 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8';
      const storageKey = `theoplayer-continuous-play:${sourceUrl}`;
      let saved = null;
      let restoredFrom = null;
      let lastSavedAt = 0;
      let restored = false;
      let savingEnabled = true;

      onPlayerReady((player) => {
        function report() {
          sendToParent('continuous-play', {
            saved,
            restoredFrom,
            currentTime: player.currentTime,
          });
        }

        function savePosition() {
          if (!savingEnabled || !Number.isFinite(player.currentTime) || player.currentTime <= 0) return;
          saved = player.currentTime;
          localStorage.setItem(storageKey, String(saved));
          lastSavedAt = Date.now();
          report();
        }

        function restorePosition() {
          if (restored) return;
          restored = true;
          const stored = localStorage.getItem(storageKey);
          const position = stored === null ? null : Number(stored);
          if (position !== null && Number.isFinite(position) && position > 0) {
            saved = position;
            restoredFrom = position;
            player.currentTime = position;
          }
          report();
        }

        player.addEventListener('loadedmetadata', restorePosition);
        player.addEventListener('durationchange', restorePosition);
        player.addEventListener('timeupdate', () => {
          if (savingEnabled && Date.now() - lastSavedAt >= 1000) savePosition();
          else report();
        });
        player.addEventListener('play', () => {
          savingEnabled = true;
        });
        player.addEventListener('pause', () => {
          if (savingEnabled) savePosition();
        });
        player.addEventListener('ended', () => {
          localStorage.removeItem(storageKey);
          saved = null;
          restoredFrom = null;
          report();
        });
        window.addEventListener('pagehide', () => {
          if (savingEnabled) savePosition();
        });

        onParentMessage('clear-saved-position', () => {
          localStorage.removeItem(storageKey);
          saved = null;
          restoredFrom = null;
          savingEnabled = false;
          report();
        });

        if (player.readyState >= 1) restorePosition();
        report();
      });
    </script>
  </body>
</html>
```

---

# Creating bookmarks

Select a bookmark to seek within the current stream or switch to another stream and start playback.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

Add bookmark at current time



Each bookmark stores its title, source, poster, and playhead position. Selecting a bookmark saves the current position before seeking or loading the selected source. Use the button below the player to add a bookmark at the current playhead.

```js
function selectBookmark(bookmark) {
  player.autoplay = true;
  player.addEventListener(
    'loadedmetadata',
    () => {
      player.currentTime = bookmark.currentTime;
    },
    { once: true }
  );
  player.source = {
    sources: [{ src: bookmark.src, type: 'application/x-mpegurl' }],
    poster: bookmark.poster,
  };
}
```

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Creating bookmarks</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/poster.jpg","metadata":{"title":"Star Wars Reel"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const starWars = {
        src: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
        poster: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/poster.jpg',
        title: 'Star Wars Reel',
      };
      const tearsOfSteel = {
        src: 'https://cdn.theoplayer.com/video/tears_of_steel/index.m3u8',
        poster: 'https://cdn.theoplayer.com/video/tears_of_steel/poster.jpg',
        title: 'Tears of Steel',
      };
      const bookmarks = [
        { ...starWars, currentTime: 150, duration: 0 },
        { ...starWars, currentTime: 20, duration: 0 },
        { ...tearsOfSteel, currentTime: 500, duration: 0 },
      ];
      let activeIndex = -1;
      let currentSource = starWars.src;
      let switchToken = 0;
      let lastReportAt = 0;

      function getSource(bookmark) {
        return {
          sources: [{ src: bookmark.src, type: 'application/x-mpegurl' }],
          poster: bookmark.poster,
          metadata: { title: bookmark.title },
        };
      }

      onPlayerReady((player) => {
        function report() {
          sendToParent('bookmarks', {
            bookmarks: bookmarks.map((bookmark) => ({ ...bookmark })),
            activeIndex,
          });
          lastReportAt = Date.now();
        }

        function saveActivePosition() {
          if (activeIndex < 0 || !bookmarks[activeIndex] || player.readyState < 1) return;
          bookmarks[activeIndex].currentTime = player.currentTime;
          bookmarks[activeIndex].duration = Number.isFinite(player.duration) ? player.duration : 0;
        }

        function selectBookmark(index) {
          if (!bookmarks[index]) return;
          saveActivePosition();
          const bookmark = bookmarks[index];
          const token = ++switchToken;
          currentSource = bookmark.src;
          activeIndex = index;
          report();
          player.addEventListener(
            'loadedmetadata',
            () => {
              if (token !== switchToken) return;
              player.currentTime = bookmark.currentTime;
              saveActivePosition();
              report();
            },
            { once: true }
          );
          player.source = getSource(bookmark);
        }

        player.addEventListener('timeupdate', () => {
          if (Date.now() - lastReportAt < 500) return;
          saveActivePosition();
          report();
        });
        player.addEventListener('durationchange', () => {
          if (activeIndex >= 0 && bookmarks[activeIndex].src === currentSource) saveActivePosition();
          report();
        });

        onParentMessage('select-bookmark', (message) => {
          if (typeof message.index === 'number') {
            player.autoplay = true;
            selectBookmark(message.index);
          }
        });
        onParentMessage('add-bookmark', () => {
          if (activeIndex < 0) return;
          saveActivePosition();
          const current = bookmarks[activeIndex];
          bookmarks.push({
            title: `Bookmark ${bookmarks.length + 1}`,
            src: currentSource,
            poster: current ? current.poster : '',
            currentTime: player.currentTime,
            duration: Number.isFinite(player.duration) ? player.duration : 0,
          });
          activeIndex = bookmarks.length - 1;
          report();
        });

        report();
        selectBookmark(1);
      });
    </script>
  </body>
</html>
```

---

# Preload

Control how much of the video the player buffers before playback starts.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

**Preload**

nonemetadataauto

**Buffered**

| player.preload | auto          |
| -------------- | ------------- |
| readyState     | HAVE\_NOTHING |
| Buffered ahead | 0.0 s         |

`player.preload` accepts `'none'`, `'metadata'` or `'auto'`. Switching the option re-creates the player with the new setting so you can compare the buffered range below the player.

```js
player.preload = 'auto';
player.source = {
  sources: { src: 'https://cdn.theoplayer.com/video/dash/webvtt-embedded-in-isobmff/Manifest.mpd', type: 'application/dash+xml' },
};
```

See the [preloading guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/preloading.md).

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Preload</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      id="player-ui"
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const source = {
        sources: { src: 'https://cdn.theoplayer.com/video/dash/webvtt-embedded-in-isobmff/Manifest.mpd', type: 'application/dash+xml' },
        poster: 'https://cdn.theoplayer.com/video/sintel.png',
        metadata: { title: 'Sintel' },
      };

      const allowedPreloads = ['none', 'metadata', 'auto'];

      function ranges(timeRanges) {
        const result = [];
        for (let i = 0; i < timeRanges.length; i++) {
          result.push({ start: timeRanges.start(i), end: timeRanges.end(i) });
        }
        return result;
      }

      const reportEvents = [
        'progress',
        'timeupdate',
        'durationchange',
        'sourcechange',
        'emptied',
        'readystatechange',
        'loadedmetadata',
        'loadeddata',
        'canplay',
        'canplaythrough',
        'seeked',
        'suspend',
        'stalled',
        'pause',
        'playing',
        'waiting',
      ];

      let pollInterval = null;

      function createPlayer(preload) {
        // Re-assigning player.source while a source is loaded throws
        // "Already loaded a media source", so switching modes re-creates the player.
        if (pollInterval) {
          clearInterval(pollInterval);
          pollInterval = null;
        }
        const oldUi = document.querySelector('#player-ui');
        const configuration = oldUi.getAttribute('configuration');
        if (oldUi.player) {
          oldUi.player.destroy();
        }
        oldUi.remove();
        const ui = document.createElement('theoplayer-default-ui');
        ui.id = 'player-ui';
        ui.setAttribute('configuration', configuration);
        document.body.appendChild(ui);
        ui.addEventListener(
          'theoplayerready',
          () => {
            const player = ui.player;
            window.player = player;

            function report() {
              const buffered = ranges(player.buffered);
              const ahead = buffered
                .filter((range) => range.end > player.currentTime)
                .reduce((max, range) => Math.max(max, range.end - player.currentTime), 0);
              sendToParent('preload-state', {
                preload: player.preload,
                readyState: player.readyState,
                duration: player.duration,
                currentTime: player.currentTime,
                buffered,
                bufferedAhead: ahead,
              });
            }

            player.addEventListener(reportEvents, report);
            // Buffer growth is not guaranteed to fire an event while paused, so poll lightly too.
            pollInterval = setInterval(report, 500);

            player.preload = preload;
            player.source = source;
            report();
            sendToParent('ready');
          },
          { once: true }
        );
      }

      onParentMessage('set-preload', (message) => {
        if (!allowedPreloads.includes(message.preload)) return;
        createPlayer(message.preload);
      });

      createPlayer('auto');
    </script>
  </body>
</html>
```

---

# Playlist and caching

Build a playlist and preload the next item in the background with the caching API.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

### Playlist

PreviousNextCache next item now



The playlist is just an array of source descriptions — each click assigns the next one to `player.source`. Once playback passes 75% of the current item, `THEOplayer.cache.createTask()` starts caching the first 25% of the next item, so it starts faster. You can also trigger it manually with "Cache next item now".

```js
player.addEventListener('ended', () => {
  player.autoplay = true;
  player.source = playlist[active + 1].source;
});

// Cache part of an upcoming item:
const task = THEOplayer.cache.createTask(playlist[active + 1].source, { amount: '25%' });
task.start();
```

See the [`Cache` API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Cache).

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Playlist and caching</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      id="player-ui"
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const playlist = [
        {
          title: 'Big Buck Bunny',
          poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
          source: {
            sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8', type: 'application/x-mpegurl' },
            poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
            metadata: { title: 'Big Buck Bunny' },
          },
        },
        {
          title: 'Star Wars',
          poster: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/poster.jpg',
          source: {
            sources: {
              src: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
              type: 'application/x-mpegurl',
            },
            poster: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/poster.jpg',
            metadata: { title: 'Star Wars' },
          },
        },
        {
          title: 'Tears of Steel',
          poster: 'https://cdn.theoplayer.com/video/tears_of_steel/poster.jpg',
          source: {
            sources: { src: 'https://cdn.theoplayer.com/video/tears_of_steel/index.m3u8', type: 'application/x-mpegurl' },
            poster: 'https://cdn.theoplayer.com/video/tears_of_steel/poster.jpg',
            metadata: { title: 'Tears of Steel' },
          },
        },
      ];

      onPlayerReady((player) => {
        let active = 0;
        // Per-item cache state reported to the demo page.
        const cacheStatus = playlist.map(() => 'none');
        const cacheProgress = playlist.map(() => 0);
        const cacheTasks = playlist.map(() => null);

        function canCacheNext() {
          const next = active + 1;
          return next < playlist.length && cacheStatus[next] === 'none';
        }

        function report() {
          sendToParent('playlist-state', {
            active,
            canCacheNext: canCacheNext(),
            items: playlist.map((item, index) => ({
              title: item.title,
              poster: item.poster,
              status: cacheStatus[index],
              progress: cacheProgress[index],
            })),
          });
        }

        function loadItem(index, autoplay) {
          if (index < 0 || index >= playlist.length) return;
          active = index;
          if (autoplay) player.autoplay = true;
          player.source = playlist[index].source;
          report();
        }

        function watchTask(task, index) {
          cacheTasks[index] = task;
          cacheStatus[index] = task.status === 'done' ? 'done' : task.status === 'error' ? 'error' : 'caching';
          cacheProgress[index] = Math.round(task.percentageCached * 100);
          report();
          task.addEventListener('progress', () => {
            cacheProgress[index] = Math.round(task.percentageCached * 100);
            report();
          });
          task.addEventListener('statechange', () => {
            if (task.status === 'done') cacheStatus[index] = 'done';
            else if (task.status === 'error') cacheStatus[index] = 'error';
            cacheProgress[index] = Math.round(task.percentageCached * 100);
            report();
          });
        }

        // Reuse an existing task for the same source instead of creating a duplicate.
        // Tasks persist in THEOplayer.cache.tasks across reloads of this page.
        function taskForSource(src) {
          for (const task of THEOplayer.cache.tasks) {
            const taskSrc = task.source && task.source.sources && task.source.sources.src;
            if (taskSrc === src && task.status !== 'error' && task.status !== 'evicted') return task;
          }
          return null;
        }

        function cacheNext() {
          const next = active + 1;
          if (!canCacheNext()) return;
          const src = playlist[next].source.sources.src;
          const task = taskForSource(src) || THEOplayer.cache.createTask(playlist[next].source, { amount: '25%' });
          if (cacheTasks[next] !== task) watchTask(task, next);
          if (task.status === 'idle') task.start();
        }

        // Cache the first 25% of the next item once playback passes 75%.
        function maybeCacheNext() {
          if (!canCacheNext()) return;
          if (!Number.isFinite(player.duration) || player.duration <= 0) return;
          if (player.currentTime / player.duration < 0.75) return;
          cacheNext();
        }

        onParentMessage('playlist-load', (message) => {
          loadItem(message.index, true);
        });
        onParentMessage('playlist-previous', () => {
          loadItem(active - 1, true);
        });
        onParentMessage('playlist-next', () => {
          loadItem(active + 1, true);
        });
        onParentMessage('playlist-cache-next', () => {
          cacheNext();
        });

        player.addEventListener('ended', () => loadItem(active + 1, true));
        player.addEventListener('timeupdate', maybeCacheNext);
        player.addEventListener('sourcechange', report);

        // Initial item, no autoplay.
        loadItem(0, false);
      });
    </script>
  </body>
</html>
```

---

# Adding buttons to the UI

This example adds an Info menu, a Skip intro button and seek back/forward buttons to the player.

## Open Video UI

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

The Info button opens a menu with live player values. Skip intro seeks to 10 seconds and disappears after that point. Two `<theoplayer-seek-button>` elements in the `bottom-control-bar` seek 10 seconds back and forward (hidden on mobile, where the centered seek buttons already do this).

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Adding buttons to the UI</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }

      #info-menu {
        box-sizing: border-box;
        max-width: min(22rem, calc(100vw - 2rem));
        padding: 1rem;
        color: #fff;
      }

      #info-menu [slot='heading'] {
        font-weight: 700;
      }

      .info-values {
        display: grid;
        grid-template-columns: auto 1fr;
        gap: 0.35rem 1rem;
        margin: 0.75rem 0 0;
      }

      .info-values dt {
        opacity: 0.75;
      }

      .info-values dd {
        margin: 0;
        text-align: right;
      }

      .info-icon {
        width: 1.25rem;
        height: 1.25rem;
        vertical-align: middle;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      id="player-ui"
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg","metadata":{"title":"Big Buck Bunny"}}'
    >
      <theoplayer-button id="skip-intro" slot="top-control-bar">Skip intro</theoplayer-button>
      <theoplayer-seek-button slot="bottom-control-bar" seek-offset="-10" mobile-hidden></theoplayer-seek-button>
      <theoplayer-seek-button slot="bottom-control-bar" seek-offset="10" mobile-hidden></theoplayer-seek-button>
      <theoplayer-menu-button slot="bottom-control-bar" menu="info-menu" aria-label="Info">
        <svg class="info-icon" viewBox="0 0 24 24" fill="none" aria-hidden="true">
          <circle cx="12" cy="12" r="9" fill="none" stroke="currentColor" stroke-width="2" />
          <path d="M12 11v6m0-10h.01" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
        </svg>
      </theoplayer-menu-button>
      <theoplayer-menu id="info-menu" slot="menu" hidden>
        <span slot="heading">About this video</span>
        <p>Big Buck Bunny is a short animated film by the Blender Foundation.</p>
        <dl class="info-values">
          <dt>Quality</dt>
          <dd id="current-quality">Loading</dd>
          <dt>Duration</dt>
          <dd id="duration">Loading</dd>
        </dl>
      </theoplayer-menu>
    </theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const ui = document.querySelector('#player-ui');
      const skipButton = document.querySelector('#skip-intro');
      const qualityValue = document.querySelector('#current-quality');
      const durationValue = document.querySelector('#duration');

      function formatDuration(duration) {
        if (!Number.isFinite(duration)) return 'Live';
        const minutes = Math.floor(duration / 60);
        const seconds = Math.floor(duration % 60);
        return `${minutes}:${String(seconds).padStart(2, '0')}`;
      }

      onPlayerReady((player) => {
        function updateInfo() {
          const track = Array.from(player.videoTracks).find((videoTrack) => videoTrack.enabled);
          const quality = track && track.activeQuality;
          qualityValue.textContent = quality ? `${quality.height}p` : '—';
          durationValue.textContent = formatDuration(player.duration);
          skipButton.hidden = player.currentTime > 10;
        }

        skipButton.addEventListener('click', () => {
          player.currentTime = 10;
        });
        player.addEventListener(['durationchange', 'timeupdate'], updateInfo);
        player.videoTracks.addEventListener('addtrack', (event) => {
          event.track.addEventListener('activequalitychanged', updateInfo);
          updateInfo();
        });
        updateInfo();
      });
    </script>
  </body>
</html>
```

## Default UI

The [Default UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/default-ui.md) is created with `new THEOplayer.Player()`. Its Info button toggles an overlay inside the player, and two video.js `Button` components inserted after the play toggle seek 10 seconds back and forward, clamped to the content duration.

Code

default-ui.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Adding buttons to the UI (Default UI)</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="https://cdn.theoplayer.com/dash/theoplayer/ui.css" />
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      #player {
        position: relative;
        width: 100%;
      }

      .custom-info-button {
        width: 3rem;
      }

      .custom-info-button svg {
        width: 1.25rem;
        height: 1.25rem;
        vertical-align: middle;
      }

      .custom-info-overlay {
        position: absolute;
        z-index: 10;
        right: 1rem;
        bottom: 4.5rem;
        box-sizing: border-box;
        width: min(22rem, calc(100% - 2rem));
        padding: 1rem;
        border-radius: 0.4rem;
        background: rgb(0 0 0 / 90%);
        color: #fff;
        font:
          14px/1.5 Arial,
          sans-serif;
      }

      .custom-info-overlay[hidden] {
        display: none;
      }

      .custom-seek-button {
        width: 3rem;
        cursor: pointer;
      }

      .custom-seek-button svg {
        width: 1.25rem;
        height: 1.25rem;
        vertical-align: middle;
      }

      .custom-info-overlay h2 {
        margin: 0 2rem 0.5rem 0;
        font-size: 1rem;
      }

      .custom-info-overlay p {
        margin: 0;
      }

      .custom-info-close {
        position: absolute;
        top: 0.5rem;
        right: 0.5rem;
        border: 0;
        background: transparent;
        color: inherit;
        font: inherit;
        font-size: 1.25rem;
        cursor: pointer;
      }
    </style>
  </head>
  <body>
    <div id="player" class="video-js theoplayer-skin vjs-16-9"></div>
    <script>
      var playerElement = document.querySelector('#player');
      var player = new THEOplayer.Player(playerElement, {
        libraryLocation: 'https://cdn.theoplayer.com/dash/theoplayer/',
        licenseUrl: '../../../../theoplayer-license.txt',
      });
      player.source = {
        sources: [
          {
            src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
            type: 'application/x-mpegurl',
          },
        ],
        poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
        metadata: { title: 'Big Buck Bunny' },
      };

      var videojs = THEOplayer.videojs;
      var overlay = document.createElement('div');
      overlay.className = 'custom-info-overlay';
      overlay.hidden = true;
      overlay.innerHTML =
        '<button class="custom-info-close" type="button" aria-label="Close">×</button>' +
        '<h2>About this video</h2>' +
        '<p>Big Buck Bunny is a short animated film by the Blender Foundation.</p>';

      var InfoButton = videojs.extend(videojs.getComponent('Button'), {
        constructor: function (player, options) {
          videojs.getComponent('Button').call(this, player, options);
          this.controlText('Info');
        },
        buildCSSClass: function () {
          return 'custom-info-button vjs-control vjs-button';
        },
        handleClick: function () {
          overlay.hidden = !overlay.hidden;
        },
      });
      videojs.registerComponent('InfoButton', InfoButton);

      // Seek back/forward 10 seconds, clamped to the content duration.
      function registerSeekButton(name, offset, label, iconPath) {
        var SeekButton = videojs.extend(videojs.getComponent('Button'), {
          constructor: function (player, options) {
            videojs.getComponent('Button').call(this, player, options);
            this.controlText(label);
          },
          buildCSSClass: function () {
            return 'custom-seek-button vjs-control vjs-button';
          },
          handleClick: function () {
            player.currentTime = Math.max(0, Math.min(player.duration || Infinity, player.currentTime + offset));
          },
        });
        videojs.registerComponent(name, SeekButton);
        var button = player.ui.getChild('controlBar').addChild(name, {});
        var icon = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
        icon.setAttribute('viewBox', '0 0 24 24');
        icon.setAttribute('fill', 'none');
        icon.setAttribute('aria-hidden', 'true');
        icon.innerHTML = iconPath;
        button.el().insertBefore(icon, button.el().firstChild);
        button.el().setAttribute('aria-label', label);
        return button;
      }

      var seekBack = registerSeekButton(
        'SeekBackButton',
        -10,
        'Seek back 10 seconds',
        '<path d="M12 5V2L7 7l5 5V8c3.3 0 6 2.7 6 6s-2.7 6-6 6-6-2.7-6-6H4c0 4.4 3.6 8 8 8s8-3.6 8-8-3.6-8-8-8z" fill="currentColor"></path>'
      );
      var seekForward = registerSeekButton(
        'SeekForwardButton',
        10,
        'Seek forward 10 seconds',
        '<path d="M12 5V2l5 5-5 5V8c-3.3 0-6 2.7-6 6s2.7 6 6 6 6-2.7 6-6h2c0 4.4-3.6 8-8 8s-8-3.6-8-8 3.6-8 8-8z" fill="currentColor"></path>'
      );
      // Place the seek buttons right after the play toggle in the control bar.
      var controlBar = player.ui.getChild('controlBar');
      controlBar.el().insertBefore(seekForward.el(), controlBar.el().children[1]);
      controlBar.el().insertBefore(seekBack.el(), controlBar.el().children[1]);

      var infoButton = player.ui.getChild('controlBar').addChild('InfoButton', {});
      var icon = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
      icon.setAttribute('viewBox', '0 0 24 24');
      icon.setAttribute('fill', 'none');
      icon.setAttribute('aria-hidden', 'true');
      icon.innerHTML =
        '<circle cx="12" cy="12" r="9" fill="none" stroke="currentColor" stroke-width="2"></circle><path d="M12 11v6m0-10h.01" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"></path>';
      infoButton.el().insertBefore(icon, infoButton.el().firstChild);
      infoButton.el().setAttribute('aria-label', 'Info');
      playerElement.appendChild(overlay);
      overlay.querySelector('.custom-info-close').addEventListener('click', function () {
        overlay.hidden = true;
      });
    </script>
  </body>
</html>
```

---

# Changing the UI with CSS

Use CSS custom properties and shadow parts to match the player to your site.

## Open Video UI

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

### Primary (accent)

Seek bar fill#ffc50fSeek bar thumb#ffc50fCenter play button icon#ffc50f

### Secondary (foreground)

Text#ffffffControl icons#ffffffMenu text#ffffff

### Tertiary (backgrounds)

Control bar gradient end#000000Menu backdrop#000000

Reset

Generated CSS

```css
theoplayer-default-ui {
  --theoplayer-range-bar-color: #ffc50f;
  --theoplayer-range-thumb-background: #ffc50f;
  --theoplayer-center-play-button-icon-color: #ffc50f;
  --theoplayer-text-color: #ffffff;
  --theoplayer-icon-color: #ffffff;
  --theoplayer-menu-color: #ffffff;
  --theoplayer-control-background-gradient-stops: transparent 0%, #000000 100%;
  --theoplayer-menu-backdrop-background: #000000;
}
```

Open Video UI exposes its colors through CSS custom properties such as `--theoplayer-icon-color`, `--theoplayer-menu-color`, `--theoplayer-range-bar-color` and `--theoplayer-control-background-gradient-stops`, grouped below into accent, foreground and background colors. See the [Open Video UI styling example](https://optiview.dolby.com/docs/open-video-ui/web/examples/styling/) for more options.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Changing the UI with CSS</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
        --theoplayer-range-bar-color: #ffc50f;
        --theoplayer-range-thumb-background: #ffc50f;
        --theoplayer-center-play-button-icon-color: #ffc50f;
        --theoplayer-text-color: #ffffff;
        --theoplayer-icon-color: #ffffff;
        --theoplayer-range-thumb-height: 18px;
        --theoplayer-range-thumb-width: 18px;
        --theoplayer-range-track-height: 6px;
        --theoplayer-control-background-gradient-stops: transparent 0%, #000000 100%;
        --theoplayer-menu-backdrop-background: rgb(0 0 0 / 85%);
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      id="player-ui"
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg","metadata":{"title":"Big Buck Bunny"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const ui = document.querySelector('#player-ui');
      const hexPattern = /^#[0-9a-f]{6}$/i;

      function isHex(value) {
        return typeof value === 'string' && hexPattern.test(value);
      }

      onPlayerReady(() => {
        onParentMessage('ui-colors', (message) => {
          const colors = message.colors;
          if (typeof colors !== 'object' || colors == null) return;
          if (isHex(colors['range-bar-color'])) ui.style.setProperty('--theoplayer-range-bar-color', colors['range-bar-color']);
          if (isHex(colors['range-thumb-background'])) ui.style.setProperty('--theoplayer-range-thumb-background', colors['range-thumb-background']);
          if (isHex(colors['center-play-button-icon-color']))
            ui.style.setProperty('--theoplayer-center-play-button-icon-color', colors['center-play-button-icon-color']);
          if (isHex(colors['text-color'])) ui.style.setProperty('--theoplayer-text-color', colors['text-color']);
          if (isHex(colors['icon-color'])) ui.style.setProperty('--theoplayer-icon-color', colors['icon-color']);
          if (isHex(colors['menu-color'])) ui.style.setProperty('--theoplayer-menu-color', colors['menu-color']);
          if (isHex(colors['control-background-end']))
            ui.style.setProperty('--theoplayer-control-background-gradient-stops', `transparent 0%, ${colors['control-background-end']} 100%`);
          if (isHex(colors['menu-backdrop-background']))
            ui.style.setProperty('--theoplayer-menu-backdrop-background', colors['menu-backdrop-background']);
        });
      });
    </script>
  </body>
</html>
```

## Default UI

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

### Primary

Primary color#ffc50fPrimary background text#000000Primary background#ffc50f

### Secondary

Secondary color#ffffffSecondary background text#000000Secondary background#ffffff

### Tertiary

Tertiary color#000000Tertiary background text#ffffffTertiary background#000000

Reset

Generated CSS

```css
.theoplayer-skin .theo-primary-color,
.theoplayer-skin .vjs-selected {
  color: #ffc50f !important;
}
.theoplayer-skin .theo-primary-background {
  color: #000000 !important;
  background-color: #ffc50f !important;
}
.theoplayer-skin .theo-secondary-color {
  color: #ffffff !important;
}
.theoplayer-skin .theo-secondary-background {
  color: #000000 !important;
  background-color: #ffffff !important;
}
.theoplayer-skin .theo-tertiary-color {
  color: #000000 !important;
}
.theoplayer-skin .theo-tertiary-background {
  color: #ffffff !important;
  background-color: #000000 !important;
}
```

The [Default UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/default-ui.md) groups its themed elements into six color classes: `.theo-primary-color` and `.theo-primary-background`, `.theo-secondary-color` and `.theo-secondary-background`, and `.theo-tertiary-color` and `.theo-tertiary-background`, plus `.vjs-selected` for selected menu items. Override these classes to recolor every element at once; see [UI skinning](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/ui-skinning.md) for what each class affects.

Code

default-ui.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Changing the Default UI with CSS</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="https://cdn.theoplayer.com/dash/theoplayer/ui.css" />
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script src="../utils.js"></script>
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      .theoplayer-skin {
        width: 100%;
        --primary-color: #ffc50f;
        --primary-background-text: #000000;
        --primary-background: #ffc50f;
        --secondary-color: #ffffff;
        --secondary-background-text: #000000;
        --secondary-background: #ffffff;
        --tertiary-color: #000000;
        --tertiary-background-text: #ffffff;
        --tertiary-background: #000000;
      }

      .theoplayer-skin .theo-primary-color,
      .theoplayer-skin .vjs-selected {
        color: var(--primary-color) !important;
      }

      .theoplayer-skin .theo-primary-background {
        color: var(--primary-background-text) !important;
        background-color: var(--primary-background) !important;
      }

      .theoplayer-skin .theo-secondary-color {
        color: var(--secondary-color) !important;
      }

      .theoplayer-skin .theo-secondary-background {
        color: var(--secondary-background-text) !important;
        background-color: var(--secondary-background) !important;
      }

      .theoplayer-skin .theo-tertiary-color {
        color: var(--tertiary-color) !important;
      }

      .theoplayer-skin .theo-tertiary-background {
        color: var(--tertiary-background-text) !important;
        background-color: var(--tertiary-background) !important;
      }
    </style>
  </head>
  <body>
    <div id="player" class="video-js theoplayer-skin vjs-16-9"></div>
    <script>
      var player = new THEOplayer.Player(document.querySelector('#player'), {
        libraryLocation: 'https://cdn.theoplayer.com/dash/theoplayer/',
        licenseUrl: '../../../../theoplayer-license.txt',
      });
      player.source = {
        sources: [
          {
            src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
            type: 'application/x-mpegurl',
          },
        ],
        poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
        metadata: { title: 'Big Buck Bunny' },
      };

      var colorKeys = [
        'primary-color',
        'primary-background-text',
        'primary-background',
        'secondary-color',
        'secondary-background-text',
        'secondary-background',
        'tertiary-color',
        'tertiary-background-text',
        'tertiary-background',
      ];

      onParentMessage('ui-colors', (message) => {
        var colors = message.colors;
        if (typeof colors !== 'object' || colors == null) return;
        var skin = document.querySelector('.theoplayer-skin');
        colorKeys.forEach(function (key) {
          var value = colors[key];
          if (typeof value === 'string' && /^#[0-9a-f]{6}$/i.test(value)) {
            skin.style.setProperty('--' + key, value);
          }
        });
      });
    </script>
  </body>
</html>
```

---

# Custom error messages

This example shows how to replace the default error messages of the player with your own messages, for example to show a friendlier message to your viewers, or to translate it into their language. Each error has a [`code`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/enums/ErrorCode) that you can use to pick the right message.

Use the options below each player to load a stream that fails with a specific error, or a valid stream.

## Open Video UI

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

\[x]Missing stream (MANIFEST\_LOAD\_ERROR)\[ ]Unsupported source (SOURCE\_NOT\_SUPPORTED)\[ ]Valid stream (no error)

Open Video UI shows the error message from its locale. Register a custom locale with `THEOplayerUI.addLocale()`, override its `errorHeading` and `errorMessage` properties, and set the `lang` attribute of the UI to the name of that locale.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Custom error messages</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the theoplayer.com CDN.
      For production use, we recommend hosting THEOplayer yourself
      and changing this (as well as the <script> tags above)
      to point to THEOplayer's location on your own website.

      licenseUrl: Change this to point to your THEOplayer license file.
      Alternatively, replace it with a "license" property whose value is your THEOplayer license itself.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      lang="en-custom"
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      // Custom messages for specific error codes.
      function getCustomErrorMessage(error) {
        switch (error.code) {
          case THEOplayer.ErrorCode.MANIFEST_LOAD_ERROR:
            return 'This video is not available right now. Please try again later.';
          case THEOplayer.ErrorCode.SOURCE_NOT_SUPPORTED:
            return 'This video format is not supported by your browser.';
          case THEOplayer.ErrorCode.NETWORK_ERROR:
          case THEOplayer.ErrorCode.NETWORK_TIMEOUT:
            return 'Please check your internet connection and try again.';
          default:
            return `Something went wrong while playing this video (error ${error.code}).`;
        }
      }

      // Register a locale with a custom error heading and message,
      // and use it for the UI through its lang="en-custom" attribute.
      THEOplayerUI.addLocale('en-custom', {
        errorHeading: 'Oops, something went wrong',
        errorMessage: (error) => getCustomErrorMessage(error),
      });

      const sources = {
        // The manifest does not exist, so the player fails with a MANIFEST_LOAD_ERROR.
        notFound: {
          sources: { src: 'https://cdn.theoplayer.com/video/this-stream-does-not-exist/index.m3u8', type: 'application/x-mpegurl' },
        },
        // The source has a type which the player does not support, so the player fails with a SOURCE_NOT_SUPPORTED error.
        unsupported: {
          sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8', type: 'video/x-unsupported' },
        },
        // A valid stream, which plays without errors.
        valid: {
          sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8', type: 'application/x-mpegurl' },
          poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
        },
      };

      onPlayerReady((player) => {
        // Load the manifest right away, so errors are shown without having to press play.
        player.preload = 'auto';
        player.source = sources.notFound;
        onParentMessage('error-source', ({ name }) => {
          player.source = sources[name];
        });
      });
    </script>
  </body>
</html>
```

## Default UI

\[x]Missing stream (MANIFEST\_LOAD\_ERROR)\[ ]Unsupported source (SOURCE\_NOT\_SUPPORTED)\[ ]Valid stream (no error)

The [Default UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/default-ui.md) (created with `new THEOplayer.Player()`) shows the error message in its error display. Listen for the `error` event on the player, and replace the text in the error display with your own message.

Code

default-ui.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Custom error messages (Default UI)</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="https://cdn.theoplayer.com/dash/theoplayer/ui.css" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
  </head>
  <body>
    <div id="player" class="video-js theoplayer-skin vjs-16-9"></div>
    <script src="../utils.js"></script>
    <script>
      // Custom messages for specific error codes.
      function getCustomErrorMessage(error) {
        switch (error.code) {
          case THEOplayer.ErrorCode.MANIFEST_LOAD_ERROR:
            return 'This video is not available right now. Please try again later.';
          case THEOplayer.ErrorCode.SOURCE_NOT_SUPPORTED:
            return 'This video format is not supported by your browser.';
          case THEOplayer.ErrorCode.NETWORK_ERROR:
          case THEOplayer.ErrorCode.NETWORK_TIMEOUT:
            return 'Please check your internet connection and try again.';
          default:
            return `Something went wrong while playing this video (error ${error.code}).`;
        }
      }

      const sources = {
        // The manifest does not exist, so the player fails with a MANIFEST_LOAD_ERROR.
        notFound: {
          sources: { src: 'https://cdn.theoplayer.com/video/this-stream-does-not-exist/index.m3u8', type: 'application/x-mpegurl' },
        },
        // The source has a type which the player does not support, so the player fails with a SOURCE_NOT_SUPPORTED error.
        unsupported: {
          sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8', type: 'video/x-unsupported' },
        },
        // A valid stream, which plays without errors.
        valid: {
          sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8', type: 'application/x-mpegurl' },
          poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
        },
      };

      /*
        libraryLocation: For demonstration purposes, we use the theoplayer.com CDN.
        For production use, we recommend hosting THEOplayer yourself
        and changing this (as well as the <script> and <link> tags above)
        to point to THEOplayer's location on your own website.

        licenseUrl: Change this to point to your THEOplayer license file.
        Alternatively, replace it with a "license" property whose value is your THEOplayer license itself.
      */
      const element = document.querySelector('#player');
      var player = new THEOplayer.Player(element, {
        libraryLocation: 'https://cdn.theoplayer.com/dash/theoplayer/',
        licenseUrl: '../../../../theoplayer-license.txt',
      });

      // Replace the message in the error display when an error occurs.
      player.addEventListener('error', (event) => {
        const message = getCustomErrorMessage(event.errorObject);
        // Wait for the UI to show its own error message first.
        setTimeout(() => {
          const content = element.querySelector('.vjs-error-display .vjs-modal-dialog-content');
          if (content) {
            content.textContent = message;
          }
        });
      });

      // Load the manifest right away, so errors are shown without having to press play.
      player.preload = 'auto';
      player.source = sources.notFound;

      onParentMessage('error-source', ({ name }) => {
        player.source = sources[name];
      });
    </script>
  </body>
</html>
```

---

# Related content

Show related videos inside the player and load them in place when the viewer picks one.

## Open Video UI

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

Open Video UI has no built-in related-content overlay, so this example fills a `theoplayer-menu` with a grid of tiles. Each tile loads its source directly in the player, and the menu opens automatically when the video ends.

```js
tile.addEventListener('click', () => {
  relatedMenu.closeMenu();
  player.autoplay = true;
  player.source = {
    sources: { src: item.source, type: 'application/x-mpegurl' },
    poster: item.image,
    metadata: { title: item.title },
  };
});

player.addEventListener('ended', () => {
  if (relatedMenu.hasAttribute('hidden')) {
    relatedButton.click();
  }
});
```

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Related content</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }

      #related-menu {
        box-sizing: border-box;
        max-width: min(34rem, calc(100vw - 2rem));
        padding: 1rem;
        color: #fff;
      }

      #related-menu [slot='heading'] {
        font-weight: 700;
      }

      .related-grid {
        display: grid;
        grid-template-columns: repeat(auto-fill, minmax(9rem, 1fr));
        gap: 0.75rem;
        margin-top: 0.75rem;
      }

      .related-tile {
        padding: 0;
        border: 0;
        border-radius: 0.4rem;
        overflow: hidden;
        background: rgb(255 255 255 / 8%);
        color: #fff;
        font: inherit;
        text-align: left;
        cursor: pointer;
      }

      .related-tile:hover,
      .related-tile:focus-visible {
        background: rgb(255 255 255 / 18%);
      }

      .related-tile img {
        display: block;
        width: 100%;
        aspect-ratio: 16 / 9;
        object-fit: cover;
      }

      .related-tile span {
        display: block;
        padding: 0.4rem 0.5rem;
      }

      .related-tile .related-duration {
        padding-top: 0;
        font-size: 0.8rem;
        opacity: 0.75;
      }

      .related-icon {
        width: 1.25rem;
        height: 1.25rem;
        vertical-align: middle;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      id="player-ui"
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg","metadata":{"title":"Big Buck Bunny"}}'
    >
      <theoplayer-menu-button slot="bottom-control-bar" menu="related-menu" aria-label="Related content">
        <svg class="related-icon" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
          <rect x="3" y="3" width="7" height="7" rx="1" />
          <rect x="14" y="3" width="7" height="7" rx="1" />
          <rect x="3" y="14" width="7" height="7" rx="1" />
          <rect x="14" y="14" width="7" height="7" rx="1" />
        </svg>
      </theoplayer-menu-button>
      <theoplayer-menu id="related-menu" slot="menu" hidden>
        <span slot="heading">Related content</span>
        <div class="related-grid" id="related-grid"></div>
      </theoplayer-menu>
    </theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const relatedMenu = document.querySelector('#related-menu');
      const relatedButton = document.querySelector('theoplayer-menu-button[menu="related-menu"]');
      const relatedGrid = document.querySelector('#related-grid');

      const relatedItems = [
        {
          title: 'Tears of Steel',
          duration: '12:14',
          image: 'https://cdn.theoplayer.com/video/tears_of_steel/poster.jpg',
          source: 'https://cdn.theoplayer.com/video/tears_of_steel/index.m3u8',
        },
        {
          title: 'Star Wars',
          duration: '3:31',
          image: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/poster.jpg',
          source: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
        },
        {
          title: 'Big Buck Bunny',
          duration: '9:56',
          image: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster-alt1.jpg',
          source: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
        },
      ];

      onPlayerReady((player) => {
        for (const item of relatedItems) {
          const tile = document.createElement('button');
          tile.className = 'related-tile';
          tile.type = 'button';
          const image = document.createElement('img');
          image.src = item.image;
          image.alt = '';
          tile.appendChild(image);
          const title = document.createElement('span');
          title.textContent = item.title;
          tile.appendChild(title);
          const duration = document.createElement('span');
          duration.className = 'related-duration';
          duration.textContent = item.duration;
          tile.appendChild(duration);
          tile.addEventListener('click', () => {
            relatedMenu.closeMenu();
            player.autoplay = true;
            player.source = {
              sources: { src: item.source, type: 'application/x-mpegurl' },
              poster: item.image,
              metadata: { title: item.title },
            };
          });
          relatedGrid.appendChild(tile);
        }

        player.addEventListener('ended', () => {
          if (relatedMenu.hasAttribute('hidden')) {
            relatedButton.click();
          }
        });
      });
    </script>
  </body>
</html>
```

## Default UI

The [Default UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/default-ui.md) has a built-in related-content overlay driven by `player.related.sources`. Each item carries a `source` description, so clicking a tile loads it in the same player.

```js
player.related.sources = [
  {
    image: 'https://cdn.theoplayer.com/video/tears_of_steel/poster.jpg',
    title: 'Tears of Steel',
    duration: '12:14',
    source: {
      sources: [{ src: 'https://cdn.theoplayer.com/video/tears_of_steel/index.m3u8', type: 'application/x-mpegurl' }],
    },
  },
];

player.addEventListener('ended', () => {
  if (!player.related.showing) {
    player.related.show();
  }
});
```

Code

default-ui.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Related content (Default UI)</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="https://cdn.theoplayer.com/dash/theoplayer/ui.css" />
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      #player {
        position: relative;
        width: 100%;
      }
    </style>
  </head>
  <body>
    <div id="player" class="video-js theoplayer-skin vjs-16-9"></div>
    <script>
      var player = new THEOplayer.Player(document.querySelector('#player'), {
        libraryLocation: 'https://cdn.theoplayer.com/dash/theoplayer/',
        licenseUrl: '../../../../theoplayer-license.txt',
      });
      player.source = {
        sources: [{ src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8', type: 'application/x-mpegurl' }],
        poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
        metadata: { title: 'Big Buck Bunny' },
      };

      // Each related item carries its own source description, so clicking a tile loads it in this player.
      player.related.sources = [
        {
          image: 'https://cdn.theoplayer.com/video/tears_of_steel/poster.jpg',
          title: 'Tears of Steel',
          duration: '12:14',
          source: {
            sources: [{ src: 'https://cdn.theoplayer.com/video/tears_of_steel/index.m3u8', type: 'application/x-mpegurl' }],
            poster: 'https://cdn.theoplayer.com/video/tears_of_steel/poster.jpg',
            metadata: { title: 'Tears of Steel' },
          },
        },
        {
          image: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/poster.jpg',
          title: 'Star Wars',
          duration: '3:31',
          source: {
            sources: [
              {
                src: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
                type: 'application/x-mpegurl',
              },
            ],
            poster: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/poster.jpg',
            metadata: { title: 'Star Wars' },
          },
        },
        {
          image: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster-alt1.jpg',
          title: 'Big Buck Bunny',
          duration: '9:56',
          source: {
            sources: [{ src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8', type: 'application/x-mpegurl' }],
            poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster-alt1.jpg',
            metadata: { title: 'Big Buck Bunny' },
          },
        },
      ];

      player.addEventListener('ended', function () {
        if (!player.related.showing) {
          player.related.show();
        }
      });
    </script>
  </body>
</html>
```

---

# Social sharing

Let viewers share the video on social networks, copy a direct link, or grab an embed code.

## Open Video UI

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

This example adds a share button to the `top-control-bar` that opens a `theoplayer-menu` with share links, a direct link and an embed code.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Social sharing</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }

      /* Make the menu cover the whole player, like the Default UI social overlay. */
      #player-ui {
        --theoplayer-menu-layer-padding: 0;
        --theoplayer-menu-backdrop-background: transparent;
        --theoplayer-menu-margin-top: 0;
        --theoplayer-menu-margin-right: 0;
        --theoplayer-menu-margin-bottom: 0;
        --theoplayer-menu-margin-left: 0;
      }

      /* Keep the built-in heading row (back button) above the overlay. */
      #share-menu::part(heading) {
        position: relative;
        z-index: 1;
      }

      #share-menu {
        position: absolute;
        top: 0;
        right: 0;
        bottom: 0;
        left: 0;
        --theoplayer-menu-min-width: 100%;
        --theoplayer-menu-margin: 0;
        --theoplayer-menu-margin-top: 0;
        --theoplayer-menu-margin-right: 0;
        --theoplayer-menu-margin-bottom: 0;
        --theoplayer-menu-margin-left: 0;
        color: #fff;
      }

      .share-overlay {
        /* absolute+inset:0 — the menu's inner content part does not stretch,
           so height:100% leaves the bottom strip of the player uncovered. */
        position: absolute;
        inset: 0;
        box-sizing: border-box;
        display: flex;
        flex-direction: column;
        align-items: center;
        padding: 1rem;
        background: rgb(0 0 0 / 60%);
        text-align: center;
        overflow-y: auto;
      }

      .share-overlay .share-heading {
        font-weight: 700;
        font-size: 1.05rem;
      }

      .share-content {
        width: min(26rem, calc(100% - 1rem));
        margin: auto;
      }

      .share-links {
        display: flex;
        flex-wrap: wrap;
        gap: 0.5rem;
        margin: 0.75rem 0;
      }

      .share-links a {
        display: inline-flex;
        align-items: center;
        gap: 0.4rem;
        padding: 0.35rem 0.6rem;
        border-radius: 0.3rem;
        background: rgb(255 255 255 / 10%);
        color: #fff;
        text-decoration: none;
      }

      .share-links a:hover {
        background: rgb(255 255 255 / 20%);
      }

      .share-links img {
        width: 1.1rem;
        height: 1.1rem;
      }

      .share-field {
        display: grid;
        gap: 0.3rem;
        margin-top: 0.75rem;
        text-align: left;
      }

      .share-field label {
        font-size: 0.85rem;
        opacity: 0.8;
      }

      .share-field .share-copy {
        display: flex;
        align-items: flex-start;
        gap: 0.4rem;
      }

      .share-field input,
      .share-field .share-embed {
        flex: 1;
        min-width: 0;
        margin: 0;
        padding: 0.3rem 0.5rem;
        border: 1px solid rgb(255 255 255 / 30%);
        border-radius: 0.3rem;
        background: rgb(0 0 0 / 40%);
        color: #fff;
        font: inherit;
        font-size: 0.8rem;
      }

      .share-field .share-embed {
        overflow-wrap: anywhere;
        white-space: pre-wrap;
      }

      .share-field button {
        padding: 0.3rem 0.7rem;
        border: 0;
        border-radius: 0.3rem;
        background: #ffc50f;
        color: #000;
        font: inherit;
        cursor: pointer;
      }

      .share-icon {
        width: 1.5rem;
        height: 1.5rem;
        vertical-align: middle;
      }

      /* Compact layout on small players so nothing is clipped. */
      @media (max-height: 320px), (max-width: 400px) {
        .share-overlay {
          padding: 0.5rem;
          font-size: 0.8rem;
        }

        .share-content {
          margin-top: 0;
          margin-bottom: 0;
        }

        .share-links {
          gap: 0.3rem;
          margin: 0.4rem 0;
        }

        .share-links a {
          padding: 0.2rem 0.4rem;
          font-size: 0.75rem;
        }

        .share-field {
          gap: 0.15rem;
          margin-top: 0.4rem;
        }
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      id="player-ui"
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg","metadata":{"title":"Big Buck Bunny"}}'
    >
      <theoplayer-menu-button slot="top-control-bar" menu="share-menu" aria-label="Share">
        <svg class="share-icon" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
          <circle cx="6" cy="12" r="2.5" />
          <circle cx="17" cy="5.5" r="2.5" />
          <circle cx="17" cy="18.5" r="2.5" />
          <path d="M8.2 10.9l6.6-4M8.2 13.1l6.6 4" stroke="currentColor" stroke-width="1.8" fill="none" />
        </svg>
      </theoplayer-menu-button>
      <theoplayer-menu id="share-menu" slot="menu" hidden>
        <div class="share-overlay">
          <div class="share-content">
            <div class="share-heading">Share this video</div>
            <div class="share-links">
              <a id="share-facebook" target="_blank" rel="noopener noreferrer"><img src="facebook.svg" alt="" />Facebook</a>
              <a id="share-x" target="_blank" rel="noopener noreferrer"><img src="x.svg" alt="" />X</a>
              <a id="share-linkedin" target="_blank" rel="noopener noreferrer"><img src="linkedin.svg" alt="" />LinkedIn</a>
            </div>
            <div class="share-field">
              <label for="share-link">Direct link</label>
              <div class="share-copy">
                <input id="share-link" readonly />
                <button type="button" data-copy="share-link">Copy</button>
              </div>
            </div>
            <div class="share-field">
              <label>Embed</label>
              <div class="share-copy">
                <pre class="share-embed" id="share-embed"></pre>
                <button type="button" data-copy="share-embed">Copy</button>
              </div>
            </div>
          </div>
        </div>
      </theoplayer-menu>
    </theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const shareUrl = 'https://optiview.dolby.com/docs/theoplayer/examples/ui/social-sharing/';
      const embedCode = `<iframe width="640" height="360" src="${shareUrl}" frameborder="0" allowfullscreen>\n</iframe>`;

      document.querySelector('#share-facebook').href = `https://www.facebook.com/sharer/sharer.php?u=${encodeURIComponent(shareUrl)}`;
      document.querySelector('#share-x').href = `https://x.com/intent/post?url=${encodeURIComponent(shareUrl)}`;
      document.querySelector('#share-linkedin').href = `https://www.linkedin.com/sharing/share-offsite/?url=${encodeURIComponent(shareUrl)}`;
      document.querySelector('#share-link').value = shareUrl;
      document.querySelector('#share-embed').textContent = embedCode;

      document.querySelectorAll('[data-copy]').forEach((button) => {
        button.addEventListener('click', () => {
          const field = document.getElementById(button.dataset.copy);
          const text = field.value !== undefined ? field.value : field.textContent;
          const copied = () => {
            button.textContent = 'Copied';
            setTimeout(() => {
              button.textContent = 'Copy';
            }, 1500);
          };
          if (navigator.clipboard && navigator.clipboard.writeText) {
            navigator.clipboard.writeText(text).then(copied, () => {
              if (field.select) field.select();
            });
          } else if (field.select) {
            field.select();
          }
        });
      });
    </script>
  </body>
</html>
```

## Default UI

The [Default UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/default-ui.md) provides a built-in sharing overlay through `player.social`. `<URL>` inside each item's `src` is replaced with `player.social.url`.

```js
player.social.url = 'https://optiview.dolby.com/docs/theoplayer/examples/ui/social-sharing/';
player.social.items = [
  {
    label: 'Facebook',
    icon: 'facebook.svg',
    src: 'https://www.facebook.com/sharer/sharer.php?u=<URL>',
  },
  {
    label: 'Embed',
    text: '<iframe width="640" height="360" src="https://optiview.dolby.com/docs/theoplayer/examples/ui/social-sharing/" frameborder="0" allowfullscreen>\n</iframe>',
  },
];
```

Code

default-ui.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Social sharing (Default UI)</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="https://cdn.theoplayer.com/dash/theoplayer/ui.css" />
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      #player {
        position: relative;
        width: 100%;
      }
    </style>
  </head>
  <body>
    <div id="player" class="video-js theoplayer-skin vjs-16-9"></div>
    <script>
      var shareUrl = 'https://optiview.dolby.com/docs/theoplayer/examples/ui/social-sharing/';

      var player = new THEOplayer.Player(document.querySelector('#player'), {
        libraryLocation: 'https://cdn.theoplayer.com/dash/theoplayer/',
        licenseUrl: '../../../../theoplayer-license.txt',
      });
      player.source = {
        sources: [{ src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8', type: 'application/x-mpegurl' }],
        poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
        metadata: { title: 'Big Buck Bunny' },
      };

      // <URL> in each src is replaced with player.social.url.
      player.social.url = shareUrl;
      player.social.items = [
        {
          label: 'Facebook',
          icon: 'facebook.svg',
          src: 'https://www.facebook.com/sharer/sharer.php?u=<URL>',
        },
        {
          label: 'X',
          icon: 'x.svg',
          src: 'https://x.com/intent/post?url=<URL>',
        },
        {
          label: 'LinkedIn',
          icon: 'linkedin.svg',
          src: 'https://www.linkedin.com/sharing/share-offsite/?url=<URL>',
        },
        {
          label: 'Direct link',
          src: shareUrl,
        },
        {
          label: 'Embed',
          text: '<iframe width="640" height="360" src="' + shareUrl + '" frameborder="0" allowfullscreen>\n</iframe>',
        },
      ];
    </script>
  </body>
</html>
```

---

# Preview thumbnails

Show preview thumbnails when hovering the seek bar, sourced from the manifest or a side-loaded WebVTT track.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

**Thumbnail source**

In-manifest (DASH tiled thumbnails)Side-loaded (WebVTT)

Hover or scrub the seek bar to see the preview thumbnails.

DASH streams can carry tiled thumbnails inside the manifest. For streams without them, you can side-load a WebVTT file whose cues point at thumbnail images: add it as a `metadata` text track labeled `thumbnails` and the player's seek bar picks it up automatically.

```js
player.source = {
  sources: [{ src: 'https://example.com/video.mpd', type: 'application/dash+xml' }],
  textTracks: [
    {
      default: true,
      src: 'https://example.com/thumbnails.vtt',
      label: 'thumbnails',
      kind: 'metadata',
    },
  ],
};
```

See the [preview thumbnails guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/what-are-the-benefits-of-preview-thumbnails.md).

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Preview thumbnails</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      id="player-ui"
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const ui = document.querySelector('#player-ui');

      // Thumbnails can come from the manifest (DASH tiled thumbnails)
      // or from a side-loaded WebVTT metadata track labelled "thumbnails".
      const sources = {
        manifest: {
          sources: [
            {
              src: 'https://cdn.theoplayer.com/video/dash/bbb_30fps/bbb_with_multiple_tiled_thumbnails.mpd',
              type: 'application/dash+xml',
            },
          ],
          poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
          metadata: { title: 'Big Buck Bunny with In-manifest Thumbnails' },
        },
        sideloaded: {
          sources: [
            {
              src: 'https://cdn.theoplayer.com/video/dash/big_buck_bunny/BigBuckBunny_10s_simple_2014_05_09.mpd',
              type: 'application/dash+xml',
            },
          ],
          poster: 'https://cdn.theoplayer.com/video/posters/big_buck_bunny.jpg',
          metadata: {
            title: 'Big Buck Bunny with Side-loaded Thumbnails',
            subtitle: 'DASH • Side-loaded Thumbnails',
            mediaUri: 'https://optiview.dolby.com',
            displayIconUri: 'https://cdn.theoplayer.com/video/posters/big_buck_bunny.jpg',
            artist: 'Dolby',
          },
          textTracks: [
            {
              default: true,
              src: 'https://cdn.theoplayer.com/dash/theoplayer/thumbnails/big_buck_bunny_thumbnails.vtt',
              label: 'thumbnails',
              kind: 'metadata',
            },
          ],
        },
      };

      onPlayerReady((player) => {
        function reportTracks() {
          const tracks = Array.from(player.textTracks).map((track) => ({
            kind: track.kind,
            label: track.label,
            mode: track.mode,
            cues: track.cues ? track.cues.length : 0,
          }));
          sendToParent('thumbnail-tracks', { tracks });
        }

        onParentMessage('load-thumbnails', (message) => {
          if (message.kind !== 'manifest' && message.kind !== 'sideloaded') return;
          player.autoplay = true;
          player.source = sources[message.kind];
        });
        function watchTrack(track) {
          track.addEventListener(['addcue', 'removecue', 'readystatechange'], reportTracks);
        }
        for (const track of player.textTracks) watchTrack(track);
        player.textTracks.addEventListener(['addtrack', 'removetrack', 'change'], reportTracks);
        player.textTracks.addEventListener('addtrack', (event) => {
          if (event.track) watchTrack(event.track);
        });
        player.addEventListener('loadedmetadata', reportTracks);

        player.source = sources.manifest;
      });
    </script>
  </body>
</html>
```

---

# Audio-only player

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

With Open Video UI you compose a player from only the controls you need. This example uses a bare `<theoplayer-ui>` element with a track info area in the top chrome and a control bar containing just a play button, the current time, a seek bar, the remaining time, a mute button and a volume slider — no video area, center play button or fullscreen button.

The video is hidden by styling the `media-layer` shadow part with [`::part`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part), and the aspect-ratio box is removed with a CSS custom property, so no `display: none` overrides of individual controls are needed:

```css
theoplayer-ui {
  --theoplayer-aspect-ratio: none;
  --theoplayer-height: 7.25rem;
}

theoplayer-ui::part(media-layer) {
  visibility: hidden;
}
```

```html
<theoplayer-ui configuration="..." source="...">
  <div slot="top-chrome" class="track-info" no-auto-hide>...</div>
  <theoplayer-control-bar no-auto-hide>
    <theoplayer-play-button></theoplayer-play-button>
    <theoplayer-time-display></theoplayer-time-display>
    <theoplayer-time-range>
      <div slot="preview"></div>
    </theoplayer-time-range>
    <theoplayer-time-display remaining></theoplayer-time-display>
    <theoplayer-mute-button></theoplayer-mute-button>
    <theoplayer-volume-range></theoplayer-volume-range>
  </theoplayer-control-bar>
</theoplayer-ui>
```

`no-auto-hide` on the controls keeps them visible at all times instead of letting them fade out when the player is idle, since there is no video to tap when the controls fade out. The empty element in the seek bar's `preview` slot replaces the default time preview that pops up while hovering or dragging the seek bar.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Audio-only player</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-ui {
        display: block;
        width: 100%;
        /* This player renders audio controls only: no aspect-ratio box, fixed height. */
        --theoplayer-aspect-ratio: none;
        --theoplayer-height: 7.25rem;
        --theoplayer-control-height: 32px;
        font-family: 'Noto Sans', sans-serif;
        background: linear-gradient(135deg, #2b1055, #7597de);
      }

      /* Hide the media layer: nothing renders the <video>, the player is audio-only. */
      theoplayer-ui::part(media-layer) {
        visibility: hidden;
      }

      .track-info {
        display: flex;
        align-items: center;
        gap: 0.75rem;
        padding: 0.5rem 0.75rem;
        color: #fff;
      }

      .track-info img {
        width: 3rem;
        height: 3rem;
        border-radius: 0.4rem;
        object-fit: cover;
      }

      .track-info .title {
        font-weight: 700;
      }

      .track-info .artist {
        font-size: 0.85rem;
        opacity: 0.8;
      }

      theoplayer-control-bar {
        display: flex;
        align-items: center;
      }

      theoplayer-time-range {
        flex: 1;
        min-width: 4rem;
      }

      /* On narrow screens drop the volume slider so the time display fits; the mute button stays. */
      @media (max-width: 480px) {
        theoplayer-volume-range {
          display: none;
        }
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.

      no-auto-hide on the controls: keep them visible instead of letting them
      fade out when the player is idle.
    -->
    <theoplayer-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8","type":"application/x-mpegurl"},"metadata":{"title":"Elephants Dream"}}'
    >
      <div slot="top-chrome" class="track-info" no-auto-hide>
        <img src="https://cdn.theoplayer.com/video/posters/elephants_dream.jpg" alt="" />
        <div>
          <div class="title">Elephants Dream</div>
          <div class="artist">Blender Foundation</div>
        </div>
      </div>
      <theoplayer-control-bar no-auto-hide>
        <theoplayer-play-button></theoplayer-play-button>
        <theoplayer-time-display></theoplayer-time-display>
        <theoplayer-time-range>
          <!-- An empty preview slot replaces the default time preview above the seek bar. -->
          <div slot="preview"></div>
        </theoplayer-time-range>
        <theoplayer-time-display remaining></theoplayer-time-display>
        <theoplayer-mute-button></theoplayer-mute-button>
        <theoplayer-volume-range></theoplayer-volume-range>
      </theoplayer-control-bar>
    </theoplayer-ui>
    <script src="../utils.js"></script>
  </body>
</html>
```

---

# Keep the control bar visible

By default the control bar fades out after a few seconds of inactivity. These examples keep it visible at all times.

## Open Video UI

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

Set `user-idle-timeout` to a negative value to disable idle detection, so the controls never fade out.

```html
<theoplayer-default-ui user-idle-timeout="-1">...</theoplayer-default-ui>
```

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Keep control bar visible</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.

      user-idle-timeout="-1": a negative timeout disables the idle detection,
      so the control bar never fades out.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg","metadata":{"title":"Big Buck Bunny"}}'
      user-idle-timeout="-1"
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
  </body>
</html>
```

## Default UI

In the [Default UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/default-ui.md), override the fade-out transition with two CSS lines.

```css
.theo-secondary-color.vjs-control-bar {
  opacity: 1 !important;
  visibility: visible !important;
}
```

Code

default-ui.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Keep control bar visible (Default UI)</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="https://cdn.theoplayer.com/dash/theoplayer/ui.css" />
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      #player {
        position: relative;
        width: 100%;
      }

      /* Keep the control bar visible by overriding the fade-out transition. */
      .theo-secondary-color.vjs-control-bar {
        opacity: 1 !important;
        visibility: visible !important;
      }
    </style>
  </head>
  <body>
    <div id="player" class="video-js theoplayer-skin vjs-16-9"></div>
    <script>
      var player = new THEOplayer.Player(document.querySelector('#player'), {
        libraryLocation: 'https://cdn.theoplayer.com/dash/theoplayer/',
        licenseUrl: '../../../../theoplayer-license.txt',
        mutedAutoplay: 'all',
      });
      player.source = {
        sources: [{ src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8', type: 'application/x-mpegurl' }],
        poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
        metadata: { title: 'Big Buck Bunny' },
      };
    </script>
  </body>
</html>
```

---

# Closed captions and subtitles

Compare sideloaded subtitles with captions and subtitles included in a stream. For sideloaded text tracks, set `format` on the text track description (for example, `'srt'`, `'webvtt'`, and other supported formats).

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

### Sources

Sideloaded SRTSideloaded WebVTTCEA-608 captionsDASH TTML

### Subtitle style

DefaultYellow on blackLarge with edge

### Text tracks

| Label                        | Lang | Kind | Format | Mode |
| ---------------------------- | ---- | ---- | ------ | ---- |
| No text tracks reported yet. |      |      |        |      |

WebVTT, TTML, and CEA-608 tracks can be included in a manifest. You can also add a subtitle file when setting the source. The demo filters out metadata tracks and reports each text track's label, language, kind, format, and mode.

## Style subtitles

You can set `player.textTrackStyle` directly. See the [`TextTrackStyle` API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TextTrackStyle) for supported properties.

```js
player.textTrackStyle = {
  backgroundColor: 'rgba(0, 0, 0, 0.85)',
  edgeStyle: 'dropshadow',
  fontColor: '#ffff00',
  fontSize: '150%',
};
```

See [how to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/insert-subtitles.md) for more details.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Closed captions and subtitles</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/elephants-dream/playlist.png","textTracks":[{"src":"https://cdn.theoplayer.com/video/elephants-dream/captions.nl.srt","srclang":"nl","label":"Dutch (SRT)","kind":"subtitles","format":"srt","default":true}],"metadata":{"title":"Elephants Dream"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const sourceConfigurations = {
        srt: {
          sources: {
            src: 'https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
            type: 'application/x-mpegurl',
          },
          poster: 'https://cdn.theoplayer.com/video/elephants-dream/playlist.png',
          textTracks: [
            {
              src: 'https://cdn.theoplayer.com/video/elephants-dream/captions.nl.srt',
              srclang: 'nl',
              label: 'Dutch (SRT)',
              kind: 'subtitles',
              format: 'srt',
              default: true,
            },
          ],
          metadata: { title: 'Elephants Dream' },
        },
        webvtt: {
          sources: {
            src: 'https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
            type: 'application/x-mpegurl',
          },
          poster: 'https://cdn.theoplayer.com/video/elephants-dream/playlist.png',
          textTracks: [
            {
              src: 'https://cdn.theoplayer.com/video/elephants-dream/captions.en.vtt',
              srclang: 'en',
              label: 'English (WebVTT)',
              kind: 'subtitles',
              format: 'webvtt',
              default: true,
            },
          ],
          metadata: { title: 'Elephants Dream' },
        },
        cea608: {
          sources: {
            src: 'https://cdn.theoplayer.com/video/adultswim2/clip.m3u8',
            type: 'application/x-mpegurl',
          },
          poster: 'https://cdn.theoplayer.com/video/adultswim2/poster.jpg',
          metadata: { title: 'Adult Swim (CEA-608)' },
        },
        ttml: {
          sources: {
            src: 'https://livesim.dashif.org/dash/vod/testpic_2s/multi_subs.mpd',
            type: 'application/dash+xml',
          },
          metadata: { title: 'DASH TTML subtitles' },
        },
      };

      const resetStyle = {
        backgroundColor: undefined,
        edgeStyle: undefined,
        fontColor: undefined,
        fontFamily: undefined,
        fontSize: undefined,
        marginBottom: undefined,
        marginLeft: undefined,
        marginRight: undefined,
        marginTop: undefined,
        windowColor: undefined,
      };

      const stylePresets = {
        default: {},
        yellow: {
          backgroundColor: 'rgba(0, 0, 0, 0.85)',
          edgeStyle: 'none',
          fontColor: '#ffff00',
          windowColor: 'rgba(0, 0, 0, 0.85)',
        },
        large: {
          backgroundColor: 'rgba(0, 0, 0, 0.65)',
          edgeStyle: 'dropshadow',
          fontColor: '#ffffff',
          fontSize: '150%',
          windowColor: 'rgba(0, 0, 0, 0.65)',
        },
      };

      onPlayerReady((player) => {
        let currentSource = 'srt';
        let autoSelectedTrack;

        function reportTracks() {
          const tracks = Array.from(player.textTracks)
            .filter((track) => track.kind !== 'metadata')
            .map((track) => ({
              label: track.label || track.kind,
              language: track.language || '',
              kind: track.kind,
              format: track.type || track.format || '—',
              mode: track.mode,
            }));
          sendToParent('text-tracks', { tracks });
        }

        function selectSubtitleTrack() {
          if (currentSource !== 'cea608' && currentSource !== 'ttml') return;
          const tracks = Array.from(player.textTracks).filter((track) => track.kind === 'subtitles' || track.kind === 'captions');
          const showingTrack = tracks.find((track) => track.mode === 'showing');
          const englishTrack = currentSource === 'ttml' ? tracks.find((track) => (track.language || '').toLowerCase().startsWith('en')) : undefined;

          if (showingTrack) {
            if (englishTrack && showingTrack === autoSelectedTrack && showingTrack !== englishTrack) {
              showingTrack.mode = 'disabled';
              englishTrack.mode = 'showing';
              autoSelectedTrack = englishTrack;
              reportTracks();
            }
            return;
          }

          const track = englishTrack || tracks[0];
          if (track) {
            track.mode = 'showing';
            autoSelectedTrack = track;
            reportTracks();
          }
        }

        player.textTracks.addEventListener(['addtrack', 'removetrack', 'change'], reportTracks);
        player.textTracks.addEventListener('addtrack', selectSubtitleTrack);
        player.addEventListener('sourcechange', reportTracks);

        onParentMessage('text-source', (message) => {
          if (typeof message.name !== 'string' || !sourceConfigurations[message.name]) return;
          if (message.name === 'cea608' || message.name === 'ttml') {
            Array.from(player.textTracks)
              .filter((track) => track.kind === 'subtitles' || track.kind === 'captions')
              .forEach((track) => {
                track.mode = 'disabled';
              });
          }
          currentSource = message.name;
          autoSelectedTrack = undefined;
          player.autoplay = true;
          player.source = sourceConfigurations[message.name];
          reportTracks();
        });
        onParentMessage('text-style', (message) => {
          if (typeof message.name !== 'string' || !stylePresets[message.name]) return;
          Object.assign(player.textTrackStyle, resetStyle, stylePresets[message.name]);
        });

        reportTracks();
      });
    </script>
  </body>
</html>
```

---

# ID3 metadata

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

Now playing: -

| Frame                         | Value |
| ----------------------------- | ----- |
| No ID3 metadata received yet. |       |

This example plays an HLS audio stream with timed ID3 metadata, such as the title and artist of the song that is playing.

THEOplayer exposes ID3 metadata as a text track of type `id3`. Each cue in this track contains a parsed ID3 frame in its `content` property, for example `{ id: 'TIT2', text: 'Song title' }` or `{ id: 'WXXX', description: 'artwork', url: '...' }`. The example listens for the `entercue` event on this track. It shows artwork from the `WXXX` frame behind the player like a poster, and overlays the artist, title, album and year from the `TPE1`, `TIT2`, `TALB` and `TDRC` frames on top. The box below the player still lists the latest value of every frame.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>ID3 metadata</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        /* This is an audio-only stream, so show the artwork behind the (transparent) video. */
        --theoplayer-background: #000 var(--artwork) center / contain no-repeat;
        --artwork: url('background.svg');
      }

      .song-info[hidden] {
        display: none;
      }

      .song-info p {
        margin: 0;
      }

      .song-artist {
        font-size: 1.25em;
      }

      .song-title {
        font-size: 1.75em;
        font-weight: bold;
      }

      .song-details {
        font-size: 0.9em;
        opacity: 0.8;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the theoplayer.com CDN.
      For production use, we recommend hosting THEOplayer yourself
      and changing this (as well as the <script> tags above)
      to point to THEOplayer's location on your own website.

      licenseUrl: Change this to point to your THEOplayer license file.
      Alternatively, replace it with a "license" property whose value is your THEOplayer license itself.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/indexcom/index.m3u8","type":"application/x-mpegurl"},"poster":"background.svg"}'
    >
      <!-- Song details, slotted into the title area at the top of the player. -->
      <div class="song-info" slot="title" hidden>
        <p class="song-artist"></p>
        <p class="song-title"></p>
        <p class="song-details"></p>
      </div>
    </theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      // Convert an ID3 frame into a simple { id, description, value } object.
      function parseFrame(frame) {
        switch (frame.id) {
          case 'TXXX': // User defined text
            return { id: frame.id, description: frame.description, value: frame.text };
          case 'WXXX': // User defined URL
            return { id: frame.id, description: frame.description, value: frame.url };
          case 'COMM': // Comments
            return { id: frame.id, description: frame.description, value: frame.text };
          case 'PRIV': // Private data
            return { id: frame.id, description: frame.ownerIdentifier, value: '(private data)' };
          default:
            if ('text' in frame) {
              return { id: frame.id, value: frame.text };
            }
            if ('url' in frame) {
              return { id: frame.id, value: frame.url };
            }
            return { id: frame.id, value: '(binary data)' };
        }
      }

      const ui = document.querySelector('theoplayer-default-ui');
      const songInfo = document.querySelector('.song-info');
      const song = {};

      function updateSongInfo(frame) {
        switch (frame.id) {
          case 'WXXX': {
            // Artwork URL. The artwork of this (old) stream has moved to the theoplayer.com CDN.
            const artwork = frame.url.replace('http://www.indexcom.com/img/rdj/5', 'https://cdn.theoplayer.com/demos/id3/images');
            ui.style.setProperty('--artwork', `url("${artwork}")`);
            return;
          }
          case 'TPE1': // Artist
          case 'TIT2': // Title
          case 'TALB': // Album
          case 'TDRC': // Recording time
            song[frame.id] = frame.text;
            break;
          default:
            return;
        }
        songInfo.querySelector('.song-artist').textContent = song.TPE1 || '';
        songInfo.querySelector('.song-title').textContent = song.TIT2 || '';
        songInfo.querySelector('.song-details').textContent = [song.TALB, song.TDRC].filter(Boolean).join(' \u2022 ');
        songInfo.hidden = false;
      }

      onPlayerReady((player) => {
        player.textTracks.addEventListener('addtrack', (event) => {
          const track = event.track;
          if (track.type !== 'id3') return;
          // Metadata tracks must be enabled to receive cues.
          track.mode = 'hidden';
          track.addEventListener('entercue', (event) => {
            const cue = event.cue;
            const frame = parseFrame(cue.content);
            console.log('ID3 frame', cue.content);
            updateSongInfo(cue.content);
            sendToParent('id3', { frame: { ...frame, startTime: cue.startTime } });
          });
        });
      });
    </script>
  </body>
</html>
```

---

# AirPlay

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

| `player.cast.airplay.state`   | - |
| ----------------------------- | - |
| `player.cast.airplay.casting` | - |

This example shows how to stream a video to an Apple TV or another AirPlay receiver. Open Video UI shows an AirPlay button in the control bar when AirPlay is available. Click it to choose a receiver and start streaming.

AirPlay is only available in Safari on macOS, iOS and iPadOS. The box below the player shows the AirPlay state, using the `statechange` event of `player.cast.airplay`.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>AirPlay</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the theoplayer.com CDN.
      For production use, we recommend hosting THEOplayer yourself
      and changing this (as well as the <script> tags above)
      to point to THEOplayer's location on your own website.

      licenseUrl: Change this to point to your THEOplayer license file.
      Alternatively, replace it with a "license" property whose value is your THEOplayer license itself.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg","metadata":{"title":"Big Buck Bunny"}}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      onPlayerReady((player) => {
        const airplay = player.cast && player.cast.airplay;

        function reportState() {
          sendToParent('airplay', {
            supported: !!airplay,
            state: airplay ? airplay.state : 'unavailable',
            casting: airplay ? airplay.casting : false,
          });
        }
        if (airplay) {
          airplay.addEventListener('statechange', reportState);
        }

        reportState();
      });
    </script>
  </body>
</html>
```

---

# Chromecast

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

Cast strategy

\[ ]`auto`\[x]`manual`\[ ]`disabled`

The player only starts casting when the viewer clicks the cast button.

Receiver application ID

Default: 8E80B9CEApplyReset to default

| Cast strategy                  | manual             |
| ------------------------------ | ------------------ |
| Receiver application ID        | 8E80B9CE (default) |
| `player.cast.chromecast.state` | -                  |

```js
const player = new THEOplayer.ChromelessPlayer(element, {
  // ...
  cast: {
    strategy: 'manual',
    chromecast: {
      appID: '8E80B9CE', // THEOplayer's default receiver, replace with your own app ID
    },
  },
});
```

This example shows how to cast a video to a Chromecast device from Google Chrome. Click the cast button in the control bar to choose a device and start casting.

The [cast strategy](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/JoinStrategy) (`cast.strategy`) controls how the player joins cast sessions:

* **`auto`**: the player automatically joins an existing cast session, for example one that was started from another tab.
* **`manual`** (default): the player only starts casting when the viewer clicks the cast button.
* **`disabled`**: the player never casts, and does not show a cast button.

By default, THEOplayer uses its own Chromecast receiver application with ID **`8E80B9CE`**. To cast to your own [custom receiver](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/enable-chromecast-on-the-sender.md), enter its application ID and click **Apply**. For example, use `44BAE7D1` to connect to the OptiView Player receiver application that uses Google's legacy Media Player Library (MPL). The player is recreated whenever you change the cast strategy or the application ID.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Chromecast</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <!-- Google's Cast Sender SDK, required for Chromecast support. -->
    <script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the theoplayer.com CDN.
      For production use, we recommend hosting THEOplayer yourself
      and changing this (as well as the <script> tags above)
      to point to THEOplayer's location on your own website.

      licenseUrl: Change this to point to your THEOplayer license file.
      Alternatively, replace it with a "license" property whose value is your THEOplayer license itself.
    -->
    <script src="../utils.js"></script>
    <script>
      // Read the cast configuration from the URL, e.g. demo.html?strategy=auto&appID=8E80B9CE
      const params = new URLSearchParams(location.search);
      const strategy = params.get('strategy') || 'manual';
      const appID = params.get('appID') || undefined;

      const configuration = {
        libraryLocation: 'https://cdn.theoplayer.com/dash/theoplayer/',
        licenseUrl: '../../../../theoplayer-license.txt',
        cast: {
          strategy: strategy,
          // When no appID is set, THEOplayer uses its default receiver application.
          chromecast: appID ? { appID: appID } : {},
        },
      };
      const source = {
        sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8', type: 'application/x-mpegurl' },
        poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
        metadata: { title: 'Big Buck Bunny' },
      };

      // Create a new player with this configuration.
      const ui = document.createElement('theoplayer-default-ui');
      ui.setAttribute('configuration', JSON.stringify(configuration));
      ui.setAttribute('source', JSON.stringify(source));
      document.body.appendChild(ui);

      onPlayerReady((player) => {
        const chromecast = player.cast && player.cast.chromecast;

        function reportState() {
          sendToParent('chromecast', {
            strategy: strategy,
            appID: appID,
            state: chromecast ? chromecast.state : 'unavailable',
            casting: chromecast ? chromecast.casting : false,
          });
        }
        if (chromecast) {
          chromecast.addEventListener('statechange', reportState);
        }

        reportState();
      });
    </script>
  </body>
</html>
```

---

# DRM and AES-128 encryption

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

\[x]DRM: Widevine or PlayReady (DASH), FairPlay (HLS)\[ ]AES-128 (HLS)

| Selected stream             | -                                      |
| --------------------------- | -------------------------------------- |
| Key systems in this browser | Widevine: …, PlayReady: …, FairPlay: … |

This example plays protected content:

* **DRM**: a single source description with a DASH stream protected with Widevine and PlayReady, and an HLS stream protected with FairPlay. The player picks the first stream that the current browser supports: Widevine or PlayReady in most browsers, and FairPlay in Safari. The license requests are handled by the KeyOS [DRM integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/buydrm-keyos.md).
* **AES-128**: an HLS stream encrypted with AES-128. The player fetches the decryption key from the URL in the HLS playlist, so no extra configuration is needed.

The box below the player shows which stream the player selected, and which DRM key systems your browser supports.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>DRM and AES-128 encryption</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the theoplayer.com CDN.
      For production use, we recommend hosting THEOplayer yourself
      and changing this (as well as the <script> tags above)
      to point to THEOplayer's location on your own website.

      licenseUrl: Change this to point to your THEOplayer license file.
      Alternatively, replace it with a "license" property whose value is your THEOplayer license itself.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      // A test token for the KeyOS license server.
      const keyosCustomData =
        'PEtleU9TQXV0aGVudGljYXRpb25YTUw+PERhdGE+PEdlbmVyYXRpb25UaW1lPjIwMTYtMTEtMTkgMDk6MzQ6MDEuOTkyPC9HZW5lcmF0aW9uVGltZT48RXhwaXJhdGlvblRpbWU+MjAyNi0xMS0xOSAwOTozNDowMS45OTI8L0V4cGlyYXRpb25UaW1lPjxVbmlxdWVJZD4wZmZmMTk3YWQzMzQ0ZTMyOWU0MTA0OTIwMmQ5M2VlYzwvVW5pcXVlSWQ+PFJTQVB1YktleUlkPjdlMTE0MDBjN2RjY2QyOWQwMTc0YzY3NDM5N2Q5OWRkPC9SU0FQdWJLZXlJZD48V2lkZXZpbmVQb2xpY3kgZmxfQ2FuUGxheT0idHJ1ZSIgZmxfQ2FuUGVyc2lzdD0iZmFsc2UiIC8+PFdpZGV2aW5lQ29udGVudEtleVNwZWMgVHJhY2tUeXBlPSJIRCI+PFNlY3VyaXR5TGV2ZWw+MTwvU2VjdXJpdHlMZXZlbD48L1dpZGV2aW5lQ29udGVudEtleVNwZWM+PEZhaXJQbGF5UG9saWN5IC8+PExpY2Vuc2UgdHlwZT0ic2ltcGxlIiAvPjwvRGF0YT48U2lnbmF0dXJlPk1sNnhkcU5xc1VNalNuMDdicU8wME15bHhVZUZpeERXSHB5WjhLWElBYlAwOE9nN3dnRUFvMTlYK1c3MDJOdytRdmEzNFR0eDQydTlDUlJPU1NnREQzZTM4aXE1RHREcW9HelcwS2w2a0JLTWxHejhZZGRZOWhNWmpPTGJkNFVkRnJUbmxxU21raC9CWnNjSFljSmdaUm5DcUZIbGI1Y0p0cDU1QjN4QmtxMUREZUEydnJUNEVVcVJiM3YyV1NueUhGeVZqWDhCR3o0ZWFwZmVFeDlxSitKbWI3dUt3VjNqVXN2Y0Fab1ozSHh4QzU3WTlySzRqdk9Wc1I0QUd6UDlCc3pYSXhKd1ZSZEk3RXRoMjhZNXVEQUVZVi9hZXRxdWZiSXIrNVZOaE9yQ2JIVjhrR2praDhHRE43dC9nYWh6OWhVeUdOaXRqY2NCekJvZHRnaXdSUT09PC9TaWduYXR1cmU+PC9LZXlPU0F1dGhlbnRpY2F0aW9uWE1MPg==';

      const sources = {
        // HLS with AES-128 encryption: no extra configuration is needed.
        aes: {
          sources: {
            src: 'https://cdn.theoplayer.com/video/big_buck_bunny_encrypted/stream-800/index.m3u8',
            type: 'application/x-mpegurl',
          },
          poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
          metadata: { title: 'Big Buck Bunny (AES-128)' },
        },
        // The player picks the first source that is supported by the current browser:
        // DASH with Widevine or PlayReady, or HLS with FairPlay.
        drm: {
          sources: [
            {
              src: 'https://d2jl6e4h8300i8.cloudfront.net/netflix_meridian/4k-18.5!9/keyos-logo/g180-avc_a2.0-vbr-aac-128k/r30/dash-wv-pr/stream.mpd',
              type: 'application/dash+xml',
              contentProtection: {
                integration: 'keyos',
                widevine: {},
                playready: {},
                preferredKeySystems: ['widevine', 'playready'],
                customdata: keyosCustomData,
              },
            },
            {
              src: 'https://d2jl6e4h8300i8.cloudfront.net/netflix_meridian/4k-19.5!9/keyos-logo/g180-avc_a2.0-vbr-aac-128k/r30/hls-fp/master.m3u8',
              type: 'application/x-mpegurl',
              contentProtection: {
                integration: 'keyos',
                fairplay: {
                  certificateURL: 'https://fp-keyos.licensekeyserver.com/cert/7e11400c7dccd29d0174c674397d99dd.der',
                  licenseAcquisitionURL: 'https://fp-keyos.licensekeyserver.com/getkey/',
                },
                customdata: keyosCustomData,
              },
            },
          ],
          metadata: { title: 'Meridian (Widevine, PlayReady or FairPlay)' },
        },
      };

      const ui = document.querySelector('theoplayer-default-ui');
      ui.source = sources.drm;

      onPlayerReady((player) => {
        function reportState(error) {
          sendToParent('drm', { src: player.src, error: error && { code: error.code, message: error.message } });
        }
        player.addEventListener(['sourcechange', 'loadedmetadata'], () => reportState());
        player.addEventListener('error', (event) => reportState(event.errorObject));

        onParentMessage('drm-source', ({ name }) => {
          player.autoplay = true;
          player.source = sources[name];
        });

        reportState();
      });
    </script>
  </body>
</html>
```

---

# Google DAI

Load a Google DAI stream and inspect its scheduled ad breaks, events, and content time.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

### Stream configuration

**Stream type**

VODLive

**Stream format**

HLSDASH

Content source ID2548831Video IDtears-of-steelAPI key (optional)

Advanced options

Auth tokenNetwork codeStream activity monitor ID\[ ]Enable nonce

### Ad tag parameters

Add sample

| Key                   | Value | Action |
| --------------------- | ----- | ------ |
| No ad tag parameters. |       |        |

Add parameterReset to sampleLoad stream

Generated source

```js
player.source = {
  "sources": {
    "type": "application/x-mpegurl",
    "ssai": {
      "integration": "google-dai",
      "availabilityType": "vod",
      "apiKey": "",
      "contentSourceID": "2548831",
      "videoID": "tears-of-steel"
    }
  }
};
```

### Stream and content time

| Stream time  | — |
| ------------ | - |
| Content time | — |

### Scheduled ad breaks

| Offset                            | Max duration | Ads |
| --------------------------------- | ------------ | --- |
| No scheduled breaks reported yet. |              |     |

### Events

Clear

| Clock / player time     | Event | Details |
| ----------------------- | ----- | ------- |
| No events reported yet. |       |         |

The stream type and the `ssai` configuration identify the Google DAI stream. VOD uses a content source ID and video ID; live streams use an asset key.

```js
function loadVOD() {
  player.autoplay = true;
  player.source = {
    sources: {
      type: 'application/x-mpegurl',
      ssai: {
        integration: 'google-dai',
        availabilityType: 'vod',
        apiKey: '',
        contentSourceID: '2548831',
        videoID: 'tears-of-steel',
        adTagParameters: {
          description_url: window.location.href,
        },
      },
    },
  };
}

function loadLive() {
  player.autoplay = true;
  player.source = {
    sources: {
      type: 'application/x-mpegurl',
      ssai: {
        integration: 'google-dai',
        availabilityType: 'live',
        apiKey: '',
        assetKey: 'c-rArva4ShKVIAkNfy6HUQ',
      },
    },
  };
}
```

Listen to `player.ads` events to track ad playback. Ad blockers can block the Google IMA DAI SDK.

```js
player.ads.addEventListener('adbegin', (event) => {
  console.log(event.ad.id, event.ad.duration, event.adBreak.timeOffset);
});
```

See the [Google DAI guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/google-dai.md) and the [`GoogleDAIConfiguration` API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/GoogleDAIConfiguration).

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Google DAI</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const adEventNames = [
        'addadbreak',
        'removeadbreak',
        'adbreakbegin',
        'adbegin',
        'adfirstquartile',
        'admidpoint',
        'adthirdquartile',
        'adend',
        'adbreakend',
        'adimpression',
        'adskip',
        'aderror',
        'adloaded',
        'updateadbreak',
        'adbreakchange',
        'addad',
        'updatead',
        'adbuffering',
        'adclicked',
      ];

      const defaultConfiguration = {
        format: 'hls',
        availabilityType: 'vod',
        contentSourceID: '2548831',
        videoID: 'tears-of-steel',
        apiKey: '',
      };

      onPlayerReady((player) => {
        let events = [];
        let adBreaks = [];
        let previousAdBreaks = new Set();
        let sourceToken = 0;

        function describeAdBreak(adBreak) {
          return {
            timeOffset: adBreak.timeOffset,
            maxDuration: adBreak.maxDuration,
            adCount: adBreak.ads.length,
          };
        }

        function reportState() {
          sendToParent('dai-state', {
            adBreaks: adBreaks.slice(),
            events: events.slice(),
          });
        }

        function reportTime() {
          const streamTime = player.currentTime;
          sendToParent('dai-time', {
            streamTime,
            contentTime: player.ads.dai.contentTimeForStreamTime(streamTime),
          });
        }

        function logEvent(name, event) {
          const details = [];
          if (event.adBreak) {
            const breakInfo = describeAdBreak(event.adBreak);
            const existingIndex = adBreaks.findIndex((adBreak) => adBreak.timeOffset === breakInfo.timeOffset);
            if (name === 'removeadbreak') {
              if (existingIndex >= 0) adBreaks.splice(existingIndex, 1);
            } else if ((name === 'addadbreak' || name === 'updateadbreak') && !previousAdBreaks.has(event.adBreak)) {
              if (existingIndex >= 0) adBreaks[existingIndex] = breakInfo;
              else adBreaks.push(breakInfo);
            }
          }
          if (event.ad) {
            if (event.ad.id) details.push(`Ad ${event.ad.id}`);
            if (event.ad.duration !== undefined) details.push(`duration ${event.ad.duration.toFixed(1)} s`);
          }
          if (event.adBreak) {
            details.push(`break at ${event.adBreak.timeOffset.toFixed(1)} s`);
          }
          const errorMessage = event.error?.message || event.error || event.message;
          if (errorMessage) details.push(String(errorMessage));
          events = [
            {
              wallClock: new Date().toLocaleTimeString(),
              playerTime: player.currentTime,
              event: name,
              details: details.join(' · '),
            },
            ...events,
          ].slice(0, 100);
          reportState();
        }

        function sourceFor(configuration) {
          const ssai = {
            integration: 'google-dai',
            availabilityType: configuration.availabilityType,
            apiKey: configuration.apiKey,
          };
          if (configuration.authToken) ssai.authToken = configuration.authToken;
          if (configuration.networkCode) ssai.networkCode = configuration.networkCode;
          if (configuration.streamActivityMonitorID) ssai.streamActivityMonitorID = configuration.streamActivityMonitorID;
          if (configuration.enableNonce) ssai.enableNonce = true;
          if (configuration.adTagParameters && Object.keys(configuration.adTagParameters).length > 0) {
            ssai.adTagParameters = configuration.adTagParameters;
          }
          if (configuration.availabilityType === 'vod') {
            if (configuration.contentSourceID) ssai.contentSourceID = configuration.contentSourceID;
            if (configuration.videoID) ssai.videoID = configuration.videoID;
          } else if (configuration.assetKey) ssai.assetKey = configuration.assetKey;
          return {
            sources: {
              type: configuration.format === 'dash' ? 'application/dash+xml' : 'application/x-mpegurl',
              ssai,
            },
          };
        }

        function setConfiguration(configuration) {
          previousAdBreaks = configuration.availabilityType === 'live' ? new Set(player.ads.scheduledAdBreaks) : new Set();
          const token = ++sourceToken;
          events = [];
          adBreaks = [];
          player.addEventListener(
            'loadedmetadata',
            () => {
              if (token !== sourceToken) return;
              adBreaks = player.ads.scheduledAdBreaks.filter((adBreak) => !previousAdBreaks.has(adBreak)).map(describeAdBreak);
              reportState();
            },
            { once: true }
          );
          player.source = sourceFor(configuration);
          reportState();
        }

        player.ads.addEventListener(adEventNames, (event) => logEvent(event.type, event));
        player.addEventListener('sourcechange', (event) => {
          events = [];
          adBreaks = [];
          logEvent('sourcechange', event);
        });
        player.addEventListener('error', (event) => {
          const error = player.errorObject;
          logEvent('error', { ...event, message: error?.message || event.message || 'Player error' });
        });
        player.addEventListener('timeupdate', reportTime);

        onParentMessage('load-dai', (message) => {
          player.autoplay = true;
          setConfiguration(message.config);
        });
        onParentMessage('clear-dai-log', () => {
          events = [];
          reportState();
        });

        setConfiguration(defaultConfiguration);
      });
    </script>
  </body>
</html>
```

---

# Advertisement tester

Schedule ad breaks in a stream and inspect the resulting ad events and companion ads.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

### Ad configuration

Ad templatesVAST pre-roll (vast-preroll)Video URLhttps\://cdn.theoplayer.com/video/big\_buck\_bunny/big\_buck\_bunny\_metadata.m3u8Ad URLhttps\://cdn.theoplayer.com/demos/preroll.xmlIntegrationTHEOplayer (CSAI) (csai)PositionPre-roll (start)

Load sourceReset to template

Generated code

```js
player.source = {
  "sources": {
    "src": "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8",
    "type": "application/x-mpegurl"
  },
  "poster": "https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg",
  "metadata": {
    "title": "Big Buck Bunny"
  },
  "ads": [
    {
      "sources": "https://cdn.theoplayer.com/demos/preroll.xml",
      "integration": "csai",
      "timeOffset": "start"
    }
  ]
};

// Schedule an ad break at any time:
player.ads.schedule({
  "sources": "https://cdn.theoplayer.com/demos/preroll.xml",
  "integration": "csai"
});
```

### Events

Clear

No events reported yet.

THEOplayer supports client-side ad insertion (CSAI) of VAST and VMAP ads through the `csai` integration, and ads served through Google's IMA SDK with the `google-ima` integration. VPAID and non-linear overlay ads require `google-ima`. Ad breaks are scheduled with the `ads` array in the source, or at any time with `player.ads.schedule()`. A `timeOffset` of `'start'` schedules a pre-roll, `'end'` a post-roll, and a timestamp or percentage a mid-roll; VMAP ads carry their own offsets and ignore `timeOffset`.

```js
player.source = {
  sources: { src: 'https://example.com/video.m3u8' },
  ads: [
    {
      sources: 'https://example.com/vast.xml',
      integration: 'csai',
      timeOffset: 'start',
    },
  ],
};

// Schedule an ad break while the content is already playing:
player.ads.schedule({
  sources: 'https://example.com/vast.xml',
  integration: 'csai',
});
```

See [Set up VAST and VMAP](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/set-up-vast-and-vmap.md), [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/google-ima.md) and [Subscribe to ad events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/subscribe-to-ad-events.md).

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Advertisement tester</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      id="player-ui"
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
      source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8","type":"application/x-mpegurl"},"poster":"https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg","metadata":{"title":"Big Buck Bunny"},"ads":[{"sources":"https://cdn.theoplayer.com/demos/preroll.xml","integration":"csai","timeOffset":"start"}]}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const adEventNames = [
        'addadbreak',
        'removeadbreak',
        'adbreakbegin',
        'adbegin',
        'adloaded',
        'adimpression',
        'adfirstquartile',
        'admidpoint',
        'adthirdquartile',
        'adskip',
        'adend',
        'adbreakend',
        'aderror',
        'adclicked',
      ];

      const allowedIntegrations = ['csai', 'google-ima'];

      function isSafeUrl(value) {
        if (typeof value !== 'string' || value.length === 0) return false;
        try {
          const url = new URL(value);
          return url.protocol === 'https:' || url.protocol === 'http:' || url.protocol === 'data:';
        } catch {
          return false;
        }
      }

      function sanitizeAdDescription(ad) {
        if (typeof ad !== 'object' || ad == null || !isSafeUrl(ad.sources)) return null;
        const description = {
          sources: ad.sources,
          integration: allowedIntegrations.includes(ad.integration) ? ad.integration : 'csai',
        };
        if (typeof ad.timeOffset === 'number' && Number.isFinite(ad.timeOffset)) {
          description.timeOffset = ad.timeOffset;
        } else if (typeof ad.timeOffset === 'string' && /^(start|end|\d+%|\d{1,2}:\d{2}:\d{2}(\.\d+)?)$/.test(ad.timeOffset)) {
          description.timeOffset = ad.timeOffset;
        }

        return description;
      }

      function sanitizeSource(source) {
        if (typeof source !== 'object' || source == null) return null;
        const src = source.sources && source.sources.src;
        if (!isSafeUrl(src)) return null;
        const allowedTypes = ['application/dash+xml', 'application/x-mpegurl'];
        const result = {
          sources: allowedTypes.includes(source.sources.type) ? { src, type: source.sources.type } : { src },
        };
        if (isSafeUrl(source.poster)) result.poster = source.poster;
        if (source.metadata && typeof source.metadata.title === 'string') result.metadata = { title: source.metadata.title };
        if (Array.isArray(source.ads)) {
          const ads = source.ads.map(sanitizeAdDescription).filter(Boolean);
          if (ads.length > 0) result.ads = ads;
        }
        return result;
      }

      onPlayerReady((player) => {
        let events = [];

        function reportEvents() {
          sendToParent('ad-events', { events: events.slice() });
        }

        function logEvent(name, details) {
          events = [
            {
              time: new Date().toLocaleTimeString('en-GB', { hour12: false }),
              event: name,
              details: details || '',
            },
            ...events,
          ].slice(0, 100);
          reportEvents();
        }

        function describeEvent(name, event) {
          const details = [];
          if (event.ad) {
            if (event.ad.id) details.push(`ad ${event.ad.id}`);
            if (event.ad.integration) details.push(event.ad.integration);
            if (typeof event.ad.duration === 'number' && Number.isFinite(event.ad.duration)) {
              details.push(`duration ${event.ad.duration.toFixed(1)} s`);
            }
          }
          if (event.adBreak && typeof event.adBreak.timeOffset === 'number') {
            details.push(`break at ${event.adBreak.timeOffset.toFixed(1)} s`);
          }
          const errorMessage = event.error?.message || event.error || event.message;
          if (errorMessage) details.push(String(errorMessage));
          logEvent(name, details.join(' · '));
        }

        function reportCompanions(companions) {
          sendToParent('companions', {
            companions: companions.map((companion) => ({
              resourceURI: typeof companion.resourceURI === 'string' ? companion.resourceURI : '',
              clickThrough: typeof companion.clickThrough === 'string' ? companion.clickThrough : '',
              altText: typeof companion.altText === 'string' ? companion.altText : '',
            })),
          });
        }

        player.ads.addEventListener(adEventNames, (event) => {
          describeEvent(event.type, event);
          if (event.type === 'adbegin' && event.ad && Array.isArray(event.ad.companions) && event.ad.companions.length > 0) {
            reportCompanions(event.ad.companions);
          }
          if (event.type === 'adbreakend') {
            reportCompanions([]);
          }
        });
        player.addEventListener('sourcechange', (event) => {
          reportCompanions([]);
          describeEvent('sourcechange', event);
        });
        player.addEventListener('error', () => {
          const error = player.errorObject;
          logEvent('error', error?.message || 'Player error');
        });

        onParentMessage('load-ad-source', (message) => {
          const source = sanitizeSource(message.source);
          if (!source) return;
          player.autoplay = true;
          player.source = source;
        });
        onParentMessage('clear-ad-log', () => {
          events = [];
          reportEvents();
        });
      });
    </script>
  </body>
</html>
```

---

# Ad block detection

Detect when an ad fails to load — for example because an ad blocker is active — and decide whether the content may still play.

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

\[ ]Block content if the ad fails (`blockContentIfAdError`)

|   |
| - |

When the ad request fails, the player fires an `aderror` event on `player.ads`. Set `blockContentIfAdError` on the source to stop content playback as well — the player then also raises a fatal `error` event. Enable an ad blocker in your browser and press play to reproduce what happens when the ad tag is unreachable — a pre-roll ad is only requested when playback starts, so the error appears after pressing play.

```js
player.ads.addEventListener('aderror', (event) => {
  // Custom behavior when the ad could not be loaded.
});

player.source = {
  sources: { src: 'https://example.com/video.m3u8' },
  ads: [{ sources: 'https://example.com/vast.xml' }],
  blockContentIfAdError: true,
};
```

See the [ad block detection guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/block-detection.md).

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Ad block detection</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      id="player-ui"
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt"}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      const contentUrl = 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8';
      const posterUrl = 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg';
      const adUrl =
        'https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=';

      let blockContentIfAdError = false;

      function sourceFor() {
        return {
          sources: { src: contentUrl, type: 'application/x-mpegurl' },
          poster: posterUrl,
          metadata: { title: 'Big Buck Bunny' },
          ads: [{ sources: adUrl, integration: 'csai' }],
          blockContentIfAdError,
        };
      }

      onPlayerReady((player) => {
        function report(status, blocked, message) {
          sendToParent('ad-block-status', { status, blocked, message: message || '' });
        }

        player.ads.addEventListener('adbegin', () => {
          report('adbegin', false);
        });
        player.ads.addEventListener('aderror', (event) => {
          const message = event.error?.message || event.error || event.message || 'Ad error';
          report('aderror', blockContentIfAdError, String(message));
        });
        player.addEventListener('error', () => {
          const error = player.errorObject;
          report('playererror', blockContentIfAdError, error?.message || 'Player error');
        });
        player.addEventListener('sourcechange', () => {
          report('waiting', false);
        });

        onParentMessage('ad-block-config', (message) => {
          if (typeof message.blockContentIfAdError === 'boolean') blockContentIfAdError = message.blockContentIfAdError;
          report('waiting', false);
          player.source = sourceFor();
        });

        player.source = sourceFor();
        report('waiting', false);
      });
    </script>
  </body>
</html>
```

---

# Conviva

Tip: open your browser's developer console and use the `player` and `THEOplayer` variables to interact with this demo.

**Stream template**HLS VOD (Big Buck Bunny) (hls-vod)**Customer key**876a2328cc34e791190d855daf389567c96d1e86**Gateway URL**https\://876a2328cc34e791190d855daf389567c96d1e86.ts-testonly.conviva.comLoad stream

No events reported yet.

This example reports playback to [Conviva](https://pulse.conviva.com/) using the [Conviva connector for THEOplayer](https://www.npmjs.com/package/@theoplayer/conviva-connector-web) ([API reference](https://theoplayer.github.io/web-connectors/api/modules/Conviva_Connector.html)). The connector bridges player events to the Conviva SDK: it starts a session when playback begins and reports content metadata, buffering and errors automatically. The connector must be created before any source is set on the player.

```js
const convivaIntegration = new THEOplayerConvivaConnector.ConvivaConnector(player, convivaMetadata, {
  debug: true,
  customerKey,
  gatewayUrl,
});

// Source-specific metadata does not carry over to the next source,
// so set it again after every sourcechange.
player.addEventListener('sourcechange', () => {
  convivaIntegration.setContentInfo({
    ['Conviva.assetName']: 'Big Buck Bunny',
    ['Conviva.streamUrl']: source.sources.src,
    ['Conviva.streamType']: 'VOD',
  });
});
```

The Customer key and Gateway URL inputs accept your own credentials; an empty input falls back to the demo's test values (omit `gatewayUrl` for production). Pressing **Load stream** calls `convivaIntegration.destroy()` to close the previous session, creates a new `ConvivaConnector` with the entered credentials, and then sets the selected source. Use the stream templates to switch between HLS/DASH and VOD/live sources; the content metadata is updated on each `sourcechange`.

> **Note**
>
> With `debug: true`, Conviva SDK debug logs are printed in the browser's DevTools console.

Code

demo.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Conviva</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
      }

      theoplayer-default-ui:not(:defined) {
        display: inline-block;
        box-sizing: border-box;
      }

      theoplayer-default-ui {
        display: block;
        width: 100%;
        aspect-ratio: 16 / 9;
        font-family: 'Noto Sans', sans-serif;
        background: #000;
      }
    </style>
    <script src="https://cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <script nomodule src="https://unpkg.com/@theoplayer/web-ui@2/polyfills"></script>
    <script async src="https://unpkg.com/@theoplayer/web-ui@2"></script>
    <!-- Conviva core SDK (exposes the global Conviva object) -->
    <script src="https://unpkg.com/@convivainc/conviva-js-coresdk@4.9.0/conviva-core-sdk.js"></script>
    <!-- THEOplayer Conviva connector (exposes THEOplayerConvivaConnector) -->
    <script src="https://unpkg.com/@theoplayer/conviva-connector-web@3.3.2/dist/conviva-connector.umd.js"></script>
  </head>
  <body>
    <!--
      libraryLocation: For demonstration purposes, we use the THEOplayer CDN.
      For production use, host the library yourself and update this URL and the script above.

      licenseUrl: Point this to your license file, or replace it with a license property.
    -->
    <theoplayer-default-ui
      configuration='{"libraryLocation":"https://cdn.theoplayer.com/dash/theoplayer/","licenseUrl":"../../../../theoplayer-license.txt","mutedAutoplay":"all"}'
    ></theoplayer-default-ui>
    <script src="../utils.js"></script>
    <script>
      // Default Conviva credentials; the page's inputs can override them.
      // `gatewayUrl` points to the Touchstone (test) backend; omit it for production.
      const defaultCustomerKey = '876a2328cc34e791190d855daf389567c96d1e86';
      const defaultGatewayUrl = `https://${defaultCustomerKey}.ts-testonly.conviva.com`;

      function makeConvivaMetadata(template) {
        return {
          ['Conviva.assetName']: template.assetName,
          ['Conviva.streamUrl']: template.source.sources.src,
          ['Conviva.streamType']: template.streamType,
          ['Conviva.applicationName']: 'THEOplayer Conviva example',
          ['Conviva.applicationVersion']: '1.0.0',
          ['Conviva.viewerId']: 'theoplayer-conviva-demo-viewer',
        };
      }

      const events = [];

      function logEvent(event, details) {
        events.push({ time: new Date().toLocaleTimeString(), event, details });
        if (events.length > 200) events.shift();
        sendToParent('conviva-events', { events });
      }

      function formatCurrentTime(player) {
        return `at ${player.currentTime.toFixed(1)} s`;
      }

      onPlayerReady((player) => {
        let convivaIntegration = null;
        let currentTemplate = null;

        // Create the connector before setting any source.
        function createConnector(template, customerKey, gatewayUrl) {
          if (convivaIntegration) {
            convivaIntegration.destroy();
            logEvent('destroy', 'Previous Conviva session closed');
          }
          convivaIntegration = new THEOplayerConvivaConnector.ConvivaConnector(player, makeConvivaMetadata(template), {
            debug: true,
            customerKey,
            gatewayUrl,
          });
          window.convivaIntegration = convivaIntegration;
          logEvent('connector', `ConvivaConnector created (customer key ${customerKey.slice(0, 8)}…, gateway ${gatewayUrl})`);
          currentTemplate = template;
        }

        // Source-specific metadata does not carry over between sources,
        // so set it again after every sourcechange.
        player.addEventListener('sourcechange', () => {
          if (convivaIntegration && currentTemplate) {
            convivaIntegration.setContentInfo({
              ['Conviva.assetName']: currentTemplate.assetName,
              ['Conviva.streamUrl']: currentTemplate.source.sources.src,
              ['Conviva.streamType']: currentTemplate.streamType,
            });
          }
          if (currentTemplate) {
            logEvent('sourcechange', `setContentInfo: assetName=${currentTemplate.assetName}, streamType=${currentTemplate.streamType}`);
          }
        });

        player.addEventListener('loadedmetadata', () => {
          logEvent('loadedmetadata', player.duration === Infinity ? 'LIVE' : `duration ${player.duration.toFixed(1)} s`);
        });
        for (const type of ['play', 'playing', 'pause', 'seeking', 'seeked', 'waiting']) {
          player.addEventListener(type, () => logEvent(type, formatCurrentTime(player)));
        }
        player.addEventListener('ended', () => logEvent('ended', formatCurrentTime(player)));
        player.addEventListener('error', () => logEvent('error', player.errorObject ? player.errorObject.message : 'unknown'));
        player.addEventListener('volumechange', () => logEvent('volumechange', `volume ${player.volume.toFixed(2)}, muted ${player.muted}`));
        player.addEventListener('ratechange', () => logEvent('ratechange', `playbackRate ${player.playbackRate}`));
        player.videoTracks.addEventListener('addtrack', (event) =>
          event.track.addEventListener('activequalitychanged', () => {
            const quality = event.track.activeQuality;
            if (quality) {
              const bitrate = quality.bandwidth ? `${(quality.bandwidth / 1e6).toFixed(2)} Mbps` : '';
              const size = quality.width ? `${quality.width}×${quality.height}` : '';
              logEvent('activequalitychanged', [bitrate, size].filter(Boolean).join(', '));
            }
          })
        );

        onParentMessage('load-stream', (message) => {
          events.length = 0;
          createConnector(message.template, message.customerKey, message.gatewayUrl);
          player.autoplay = true;
          player.source = message.template.source;
          logEvent('source', `Source set: ${message.template.source.sources.src}`);
        });

        // Initial load: default credentials, HLS VOD source, no autoplay.
        createConnector(
          {
            assetName: 'Big Buck Bunny (HLS)',
            streamType: 'VOD',
            source: {
              sources: { src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_corrected.m3u8', type: 'application/x-mpegurl' },
              poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
              metadata: { title: 'Big Buck Bunny', subtitle: 'HLS • VOD' },
            },
          },
          defaultCustomerKey,
          defaultGatewayUrl
        );
        player.source = currentTemplate.source;
        logEvent('source', `Source set: ${currentTemplate.source.sources.src}`);
      });
    </script>
  </body>
</html>
```

---

# Connectors for THEOplayer Web SDK

## [Adscript](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/adscript)

[Integrate with Adscript analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/adscript)

## [☁️CMCD](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/cmcd)

[Integrate with Common Media Client Data (CMCD) for server-side analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/cmcd)

## [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/comscore)

[Integrate with Comscore for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/comscore)

## [![](/pr-932/img/conviva.svg)![](/pr-932/img/conviva_dark.svg)Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/conviva)

[Integrate with Conviva for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/conviva)

## [![](/pr-932/img/gemius.svg)![](/pr-932/img/gemius_dark.svg)Gemius](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/gemius)

[Integrate with Gemius analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/gemius)

## [Nielsen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/nielsen)

[Integrate with Nielsen for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/nielsen)

## [![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAy0SURBVHgB7d1PbhRJFsfxiLIxs+iW2DbuaZVvwNzASGB6iU+AOQGuHd2YwSVhYId9AsMJYNmYkewb2DdwafjjWXoBEvUvYzKqSMqmjV1ZlZnxIuL7kVpqoZaM6M5f53svMp5SAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAORwt3q8fpn8pAKXQSij78Ju5S7tKmXr6m1z/0vm0tbC3eawAFEZkABwurl6Zm/tpN/3NXRv9qm4lpt/89e2TFwpAIcQFwNkP/ykH7U5veWHvWUsBmIqoABjj4f/GaP2i0+42CQJgcmICIM/DP6JbSidbV99sbCoAuYkIgMke/pPoDwCTcB4A0z/8I5QFQD5OA6DIh/+k4diw95IgAM7nLADKevhHKAuAizgJgPIf/pN0q93pXudtAPi7ygOg2od/hP4A8HeVBoCrh/+E4/Rnb/6y87ipAFQXAAIe/hPoDwBWJQEg6+EfoSxA7EoPAKkP/ylab7bb3S2CALEpNQC8ePi/oSxAfEoNgPc31zZrWt1TXhkEwXIaBAcKCFxNlUhrc0V5x9Rrurb/4dbDbW4jQuhKDQCfaWNWLs/NHh4trT1SQKAIgAsYpdY/Lj08fH/zzxUFBIYAGMugLNj+uLT2irIAISEA8rltywL6AwgFATCBYX/g0i5lAXxHAEwsKwseHr67sbaoAA8RAFMz9Zma2qUsgI8IgIIwNoSPCICCMTaETwiAUnwbG+5TFkAyAqBc1xgbQjICoALZ2PDjrQerChCEAKiMqSujn9v+wIelP24rQAACoHJ23fnMK8oCSEAAOHJybGgvTlGAAwSAY3ZseHnu533GhnCBABBhdKyYsgBVIgBEMXXGhqgSASBQNjbkWDHKRgCIZeocK0bZCADxhv0BygKUgQDwRDY2/Hjr4XOCAEUhAHxjzCq3EaEoBICXRmPDNAg82LoEqQgAr7HEBNMhAALwtT+wz9gQeREA4bjC2BB5EQDBYYkJxkcAhIslJrgQARA4lpjgPARAFFhigrMRAFFhiQlOIwAixBITZAiAiDE2BAEQPZaYxIwAQIYlJhEiAHAKY8O4EAA4w2hsyBKTsBEAOAdLTEJHAOBCLDEJFwGAsbHEJDwEAHJiiUlICABMiCUmISAAMBWWmPiNAEABWGLiKwIABWKJiW8IABTu9NiQIJCMAEBphmNDjhVLRgCgZIwNJSMAUBHGhhIRAKgUS0xkIQDgAktMhCAA4BBLTFwjACABS0wcIQAgBrcRVY8AgDCjsWEaBNcUSkUAQKhBEOxTFpSLAIBoLDEpFwEALzA2LAcBAI8M+wNHN9d2KQuKQQDAO0arRcaGxSAA4C3GhtMjAOA5lphMgwBAIFhiMgkCAEFhiUk+pQaASdSBAhxgicl4tCrZ0e/36yaZ2U1/VF0Bbhy0O73lhb1nLYVTSg+AjE3imtaPCAK4YrR+0Wl3mwTBSGUBYB0url+Zm+utpj+UY51wRLeUTrauvtnYVKg2ADK2LEiSmXWt9B0FOKFbiek3f3375IWKmJMAyLy7sbY4UzPblAVwJfaywGkAZOgPwLX0QVj/0um9jC0IRASAZcuCfn92tabVPQU4EV9ZICYAMvQH4J5utTvd6zG8DYgLgAxlAVyLoT8gNgAyBAEcO04fks1fdh43VYDEB4BFWQD3wuwPeBEAmeGx4tnn6d/y2Sdced3u9BqhlAVeBUCGsgDOab3Zbne3fA8CLwMg82FpLS0LzB2CAG74XxZ4HQAW/QG4NwiC5TQIvPv83fsAyHztD7xK/5ZtMnDCx7FhMAGQoT8A1+yxYl/GhsEFQGbYHxgcK+ZaKDjgR38g2ACw6A/ANW3U3pdu767UsiDoAMhwLRlck9ofiCIAMvQH4Ja8siCqALC4lgzu6ZZRvcb8ztPXyrHoAiBDfwCuSSgLog2ATFoWXEvLgleUBXDF5dgw+gDI0B+AW276AwTACcOyYHaF/gAcqnSJCQFwBvoDcK2q/gDLQc/wy1/PWvM7Gyumr5bTfxUtBVRssOT08kzp917wBjAG+gOolFF77Zne3YW/yi8DCIAxURagfKbVT/Tdf/7n8Z6qCAGQE0GAEhwbpbY6nU+bC3ubx6pCBMCEKAtQBKNN2uz73Kj6wc8QAFN6f+PBaq1mPzvWdQWMK63z+0Y1q3zdPwsBUADKAuRwnLb4m1LWkxMABRp8dtyf3U7/VBcV8J20zm+6qPPPQwCUgP4ATqlwrJcXAVAiriWLXfVjvbwIgJLRH4jSYKw3v/N4XQkXVAC8u7G2OKvVo6SmW9KuX+La8ji4HuvlFUQAHC3er6vLlx4ZY1ZO/rrE65npDwRKyFgvL68D4HBx9co/5n66l75uraof1tkyr2f+2h/gs2P/HScmafi6HszbAPjv0h+3Z5XdFGzq4/zzEq9npj/gN4ljvby8C4CszjcTztolXs/MtWSeETzWy8ubALCv+5fnfk5fmc2qmppuKZ1sSTmNlaE/IJ38sV5eXgTA0dLao/Pr/EnJ6w9wbblI3oz18hIdAPZ1f6amt8et8yclsSygPyBDYtRWt/tp3ec6/zwiA2Aw1rs0u22qPlOv9Wa73d2SFATDEDTblAUV83Ssl5eoACi2zp+UzLEh/YHKeD3Wy0tMAPzv5r/vJTpZV2LOzeu04WNENXxsWdDvz67W9OD7AhTL2a08LjkPAPuKW6up51roEVn6AxEIaKyXl7MAcFbnT8geK/7S+bQl6f8OlAXTCm+sl1flATDe8V2p6A8EItixXl6VBsDwP9Tac+X99/G61e50r1MW+Cf0sV5elQTAtMd3pZLaHzCJ/UZClb5VxiuRjPXyKjUAfvSZbmCO0z/ETT47lsqkZZsRV7ZJUWoAfFh68CKeV1Kh/YF4ry2PcqyXFwFQvNftTq9Bf8ChiMd6eREAJRHbHwj62nLGenmxHrwkg/XOc5d2bS2uhLBrz6++fXw9McndwNae22Ubjas7Gws8/PnwBlAJ3TKq15jfefpaCRLCteWM9aZDAFSIY8UFYqxXCALAgeGx4t5LeecHZnblTwtMq6eSxm/C3qZ8RQ/AgXQ8tS6yP5DW0IL7A3as12x3Pv+Lh784vAE4Nzg/sPzr2ycHShBR15Yz1isNbwDOmXpN1/Y/3Hq4fWhPTgphP5TRtd6CUealciT92Qf9RF23kwse/nLwBiCM0G1GVV9bbsd6TWm3NoeINwBhbH/g49LDQ0n9AVueVNUfsGO9dufTAg9/NXgDkO2g3ektyxsbzq4U3h9grOcEAeCBsM8PMNZziRLAA9mx4o+3Hji8Lfk0Ozac39lYMX21PGFZwFhPAN4AvBPEtWSv27Veg86+ewSAp6SWBeddW27HekmiG9T5chAAvhO4zeiM/gBjPaEIgCDILQu0rtW5lUcuAiAo8rYZQTamAEEx9Zma2pV2rBhyEQABGo4NZw+PltYe2UUsCvgBAiBgw8+Of96XdKwYshAAwRt8bbhtvy+gLMD3CIBomLotC+gP4CQCIDJf+wP7tj+gED0CIE5XJH52jOoRAFEb9geObq7tUhbEiQCAslub6Q/EiQDAN9lnx4e/EwKxIAAwYtSevaGYz3TjMasAlmpGiwCIm72VZ6vT+czXepEiAOLFrTwgAKLD7bs4gQCIx/BWnh1u5cEIARABu2yj2/20Tp2P7xEAIWOpJi5AAASJsR7GQwCEhbEeciEAAmG0edFpf27w4CMPAsB338Z6G3sKyIkA8NdxYpKGtF0A8AsB4CG7VJNlGygCAeATxnooGAHgBcZ6KAcBINtgrDe/s7GugBIQAEJxfBdVIACk4Ws9VIgAkIOxHipHALj39fguYz1UjwBwibEeHCMAnGCsBxkIgGoNb+V5w608kIEAqAhjPUhEAJSNsR4EIwBKY1o9lTR+e/v0tQKEIgCKx6088AYBUCyWbcArBEABjDIHSaIb1PnwDQEwncFYb56xHjxFAEyIsR5CQADklY71EjX4aOdAAZ4jAMbG8V2EhwC4GGM9BIsAOMdg2YbuNxnrIVQEwFlYtoFIlBoAxpg9rfUd5Y/h13o7jPUQB61K9v7mnys1XdtWwrFsAzEqPQAs0SHArTyIWCUBYMkLAcZ6QGUBYAkJAS7hBL6qNAAslyEwGOu1Pzd48IGhygPAqjwEuJUHOJOTALAqCgGWbQDncBYAVpkhwFgPuJjTALAKDwHGesDYnAeAVUwIMNYD8hIRANYUITAY683vPF5XAHIREwBW3hDgVh5gOqICwBorBBjrAYUQFwDWj0PAtBJjmoz1gGKIDADruxDg+C5QArEBYA1CQNXuMNYDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABALP4PxPhKst9YjwYAAAAASUVORK5CYII=)Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/yospace)

[Integrate with Yospace for server-side ad insertion (SSAI).](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/yospace)

---

# adscript-connector-web

The AdScript connector provides an AdScript integration for THEOplayer.

## Installation

Install using your favorite package manager for Node (such as `npm` or `yarn`):

### npm

```bash
npm install @theoplayer/adscript-connector-web
```

### yarn

```bash
yarn add @theoplayer/adscript-connector-web
```

## Usage

First you need to add the AdScript connector to your app :

* Add as a regular script

```html

<script type="text/javascript" src="path/to/adscript-connector.umd.js"></script>
<script type="text/javascript">
    const player = new THEOplayer.Player(element, configuration);

    // Define your configuration for the connector:
    const adScriptConfig = {
        implementationId: 'your-implementation-id', // Replace this!
        metadata: {
            "assetid": "v0000001",
            "type": "content",
            "program": "Big Buck Bunny",
            "title": "Sample Video - Extended",
            "length": "635",
            "crossId": "000 111 22222",
            "livestream": "0",
            "channelId": "",
            "attribute": "1"
        },
        debug: false
    }

    // Create the AdScriptConnector:
    const adScriptConnector = new THEOplayerAdScriptConnector.AdScriptConnector(player, adScriptConfig);
</script>
```

* Add as an ES2015 module

```html

<script type="module">
    import {AdScriptConnector} from "@theoplayer/adscript-connector-web";

    const player = new THEOplayer.Player(element, configuration);

    // Define your configuration for the connector:
    const adScriptConfig = {
        implementationId: 'your-implementation-id', // Replace this!
        metadata: {
            "assetid": "v0000001",
            "type": "content",
            "program": "Big Buck Bunny",
            "title": "Sample Video - Extended",
            "length": "635",
            "crossId": "000 111 22222",
            "livestream": "0",
            "channelId": "",
            "attribute": "1"
        },
        debug: false
    }

    // Create the AdScriptConnector:
    const adScriptConnector = new AdScriptConnector(player, adScriptConfig);
</script>
```

## Updating metadata

If the metadata has changed during playback, you can update it with:

```javascript
adScriptConnector.updateMetadata(newMetadata);
```

## Updating userInfo

If the user info has changed during playback, you can update it with:

```javascript
adScriptConnector.updateUser(i12n);
```

---

# @theoplayer/adscript-connector-web

## 0.5.0

### ✨ Features

* Added support for THEOplayer v11.

## 0.4.0

### ✨ Features

* Added support for THEOplayer version 10.

## 0.3.0

### ✨ Features

* Added support for THEOplayer `9.0`.

## 0.2.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 0.1.0

### ✨ Features

* Initial release.

---

# cmcd-connector-web

A connector between a THEOplayer instance and a Common Media Client Data (CMCD) server for the THEOplayer HTML5/Tizen/webOS SDK. This implementation supports CMCD data as defined in CTA-5004, published in September 2020.

## Prerequisites

In order to use this connector, a [THEOplayer](https://www.npmjs.com/package/theoplayer) build with a valid license is required. You can use your existing THEOplayer HTML5 SDK license or request yours via [THEOportal](https://portal.theoplayer.com/).

## Installation

Install using your favorite package manager for Node (such as `npm` or `yarn`):

### Install via npm

```bash
npm install @theoplayer/cmcd-connector-web
```

### Install via yarn

```bash
yarn add @theoplayer/cmcd-connector-web
```

## Usage

First you need to add the CMCD connector to your app :

* Add as a regular script

```html
<script type="text/javascript" src="path/to/cmcd-connector.umd.js"></script>
<script type="text/javascript">
  const player = new THEOplayer.Player(element, playerConfiguration);
  const connector = THEOplayerCMCDConnector.createCMCDConnector(player);
</script>
```

* Add as an ES2015 module

```html
<script type="module">
    import { createCMCDConnector } from "path/to/cmcd-connector.esm.js";
    const player = new THEOplayer.Player(element, playerConfiguration);  
    const connector = createCMCDConnector(player);
</script>
```

By default, the data is sent via query arguments, but you can configure the transmission mode before creating the CMCD connector. For example, to transmit via HTTP headers:

* regular script

```html
<script type="text/javascript" src="path/to/cmcd-connector.umd.js"></script>
<script>
  const player = new THEOplayer.Player(element, playerConfiguration);
  const configuration = {
    transmissionMode: THEOplayerCMCDConnector.TransmissionMode.HTTP_HEADER
  }
  const connector = THEOplayerCMCDConnector.createCMCDConnector(player, configuration);
</script>
```

* ES2015 module

```html
<script type="module">
    import { createCMCDConnector, TransmissionMode } from "path/to/cmcd-connector.esm.js";
    const player = new THEOplayer.Player(element, playerConfiguration);
    const configuration = {
      transmissionMode: TransmissionMode.HTTP_HEADER
    }
    const connector = createCMCDConnector(player, configuration);
</script>
```

The connector will be automatically destroyed upon destruction of the provided player. When changing the player source and a content ID is being passed in, this is to be reset through `reconfigure()` as it will not be cleared automatically.

## Remarks

Note that when native playback is being used, either through THEOplayer's configuration, or due to absence of MSE/EME APIs, the JSON Object transmission mode should be used.

Currently, all standardized reserved keys are reported, except:

* Object duration (`d`)
* Next object request (`nor`)
* Next range request (`nrr`)

---

# @theoplayer/cmcd-connector-web

## 1.5.0

### ✨ Features

* Added support for THEOplayer v11.

## 1.4.0

### ✨ Features

* Added support for THEOplayer version 10.

## 1.3.0

### ✨ Features

* Added support for THEOplayer `9.0`.

## 1.2.0

### ✨ Features

* Disable CMCD for HESP requests

## 1.1.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 1.0.2

### 🐛 Issues

* Fix missing API types in TypeScript type definitions.
* Fixed an issue where multiple CMCD query arguments were being added to the request URL.

## 1.0.1

### 🐛 Issues

* Added support for THEOplayer 7.0.

## 1.0.0

### ✨ Features

* Initial release

---

# comscore-connector-web

The Comscore connector provides a Comscore integration for THEOplayer.

## Installation

```sh
npm install @theoplayer/comscore-connector-web
```

This connector depends on the JavaScript ComScore SDK, which should be loaded and available in the global scope before the connector. Get it from your ComScore dashboard or talk to a ComScore representative. This connector was developed and tested with versions 7.2.0.200214 and 7.6.1.210506

```html
<script src="/path/to/comscore.js">
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, a ComscoreConfiguration (which contains your publisher id, also referred to as the c2 value) and the ComscoreMetadata of the first source being set to the player. You can change the metadata dynamically throughout the lifecycle of the connector.

```js
import { ComscoreConnector } from '../../dist/comscore-connector.esm.js';

const comscoreConfig = {
    publisherId: '<your publisher id>',
    applicationName: 'Test App',
    userConsent: '1',
    platformApi: ns_.analytics.PlatformAPIs.WebBrowser,
    debug: true
};

const comscoreMetadata = {
    mediaType: 'longFormOnDemand',
    uniqueId: 'testuniqueId',
    length: 634566, // in milliseconds
    stationTitle: 'THEOTV',
    programTitle: 'Big Buck Bunny',
    episodeTitle: 'Intro',
    genreName: 'Animation',
    classifyAsAudioStream: false,
    customLabels: {
        testcustomlabel: 'testcustomvalue'
    }
};

const comscoreConnector = new ComscoreConnector(player, comscoreConfig, comscoreMetadata);
```

### Optional ComscoreConfiguration properties

#### `usagePropertiesAutoUpdateMode`

When omitted this wil default to foregroundOnly.

#### `skeleton`

Pass an interface object with target platform specific implementations for the necessary Platform APIs. E.g.

```js
analytics.PlatformApi.setPlatformApi(analytics.PlatformApi.PlatformApis.Skeleton, {
    onDataFetch: function (onSuccessCallback, onErrorCallback) {
        // Execute a function with platform-specific code to retrieve up-to-date information.
        runPlatformSpecificCodeToRetrieveValues(onSuccessCallback, onErrorCallback);
    }

    // Other overridden PlatformAPI methods, as needed.
});
```

For more information, please consult the [Skeleton PlatformAPI Implementation Guide](https://mymetrix-support.comscore.com/hc/en-us/article_attachments/31257678886299)

Note that if the skeleton property is defined, the connector will always use `setPlatformAPI(ns_.analytics.PlatformAPIs.Skeleton)`.

#### `platformApi`

Pass a valid value from `ns_.analytics.PlatformAPIs`. When omitted, the connector will report `setPlatformAPI(ns_.analytics.PlatformAPIs.html5)`.

#### `adIdProcessor`

Pass a function with the following signature if you require custom ad id handling: `(ad: Ad) => string`. When omitted, the connector will use `(ad) => ad.id`. Consult THEOplayer's types for more info about the `Ad` interface.

#### `debug`

A flag to enable verbose logging.

### Passing metadata dynamically

The connector allows updating the current asset's metadata at any time. Do it when setting a new source to the player.

```js
comscoreConnector.update(newMetadata);
```

### ComscoreMetadata fields

Based on the `ComscoreMetadata` type, you can tell which fields are mandatory and which aren't. Note that this is purely for the integration to work correctly. Depending on the Comscore solution you are using, different fields are required/optional. The mandatory fields in the `ComscoreMetadata` type are the ones that are mandatory for all three Comscore solutions:

* Video Metrix (V)
* Cross Platform Product Suite (X)
* Cross Media Audience Measurement (C)

| Property                           | Required | Optional |
| ---------------------------------- | -------- | -------- |
| `mediaType`                        | All      |          |
| `uniqueId`                         | All      |          |
| `length`                           | All      |          |
| `c3?`                              | V        |          |
| `c4?`                              | V        |          |
| `c6?`                              | V        |          |
| `stationTitle`                     | All      |          |
| `stationCode?`                     |          | All      |
| `networkAffiliate?`                |          | All      |
| `publisherName?`                   | X C      | V        |
| `programTitle`                     | All      |          |
| `programId?`                       |          | V C      |
| `episodeTitle`                     | All      |          |
| `episodeId?`                       |          | X C      |
| `episodeSeasonNumber?`             | X C      |          |
| `episodeNumber?`                   | X C      |          |
| `genreName`                        | All      |          |
| `genreId?`                         |          | All      |
| `carryTvAdvertisementLoad?`        | X        |          |
| `classifyAsCompleteEpisode?`       | X        |          |
| `dateOfProduction?`                |          | C        |
| `timeOfProduction?`                |          | C        |
| `dateOfTvAiring?`                  | X C      |          |
| `timeOfTvAiring?`                  |          | X C      |
| `dateOfDigitalAiring?`             | X C      |          |
| `timeOfDigitalAiring?`             |          | X C      |
| `feedType?`                        | X        |          |
| `classifyAsAudioStream`            | Al       |          |
| `deliveryMode?`                    |          | All      |
| `deliverySubscriptionType?`        |          | All      |
| `deliveryComposition?`             |          | All      |
| `deliveryAdvertisementCapability?` |          | All      |
| `mediaFormat?`                     |          | All      |
| `distributionModel?`               |          | All      |
| `playlistTitle?`                   |          | C        |
| `totalSegments?`                   |          | V C      |
| `clipUrl?`                         |          | V C      |
| `videoDimension?`                  |          | C        |
| `customLabels?`                    |          | All      |

## Documentation

The integration guidelines from ComScore can be found on their [Unified Digital Measurements page](https://www.comscore.com/Products/Digital/Unified-Digital-Measurement-Enhanced) in the Tagging section.

---

# @theoplayer/comscore-connector-web

## 1.5.0

### ✨ Features

* Added support for THEOplayer v11.

## 1.4.0

### ✨ Features

* Added support for THEOplayer version 10.

## 1.3.0

### ✨ Features

* Added support for THEOplayer `9.0`.

## 1.2.0

### ✨ Features

* Add the option to inform the ComScore library of the environment it is running in through the `setPlatformAPI`.

### 🐛 Issues

* Fixed an issue where DVR window length and offsets were incorrectly reported.
* Fixed an issue where playhead positions or content/ad durations were not reported in (rounded) milliseconds.
* Fixed an issue where only one ad in an adbreak would be reported.
* Fixed an issue where playback of the main content wouldn't get reported if Google IMA returned an empty pre-roll ad break.
* Fixed an issue where no content metadata was reported during a pre-roll ad.

## 1.1.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 1.0.21

### ✨ Features

* Initial release as a connector on npm.

### 🐛 Issues

* Fixed multiple issues where the timing of reporting the DVR window length and the playhead's offset wrt the DVR window end was wrong if a LIVE stream with a CSAI pre-roll was set as the player source.

---

# conviva-connector-web

The Conviva connector provides a Conviva integration for THEOplayer.

## Prerequisites

In order to use this connector, a [THEOplayer](https://www.npmjs.com/package/theoplayer) build with a valid license is required. You can use your existing THEOplayer HTML5 SDK license or request yours via [THEOportal](https://portal.theoplayer.com/).

For setting up a valid Conviva session, you must have access to a [Conviva developer account](https://pulse.conviva.com/) with access to a debug or production key.

## Installation

Install using your favorite package manager for Node (such as `npm` or `yarn`):

### Install via npm

```bash
npm install @theoplayer/conviva-connector-web
```

### Install via yarn

```bash
yarn add @theoplayer/conviva-connector-web
```

## Usage

First you need to define the Conviva metadata and configuration:

```javascript
    const convivaMetadata = {
        ['Conviva.assetName']: 'ASSET_NAME_GOES_HERE',
        ['Conviva.streamUrl']: 'CUSTOMER_STREAM_URL_GOES_HERE',
        ['Conviva.streamType']: 'STREAM_TYPE_GOES_HERE', // VOD or LIVE
        ['Conviva.applicationName']: 'APPLICATION_NAME_GOES_HERE',
        ['Conviva.viewerId']: 'VIEWER_ID_GOES_HERE'
    };

    const convivaConfig = {
        debug: false,
        gatewayUrl: 'CUSTOMER_GATEWAY_GOES_HERE',
        customerKey: 'CUSTOMER_KEY_GOES_HERE' // Can be a test or production key.
    };
```

Optionally, you can include device metadata in the ConvivaConfiguration object. Note that `SCREEN_RESOLUTION_WIDTH`, `SCREEN_RESOLUTION_HEIGHT` and `SCREEN_RESOLUTION_SCALE_FACTOR` are the only fields that Conviva will auto-collect on most web-based platforms.

```typescript
const exampleDeviceMetadata: ConvivaDeviceMetadata = {
    [Constants.DeviceMetadata.BRAND]: "Samsung",
    [Constants.DeviceMetadata.MANUFACTURER]: "Samsung",
    [Constants.DeviceMetadata.MODEL]: "QE43Q64BAUXXN",
    [Constants.DeviceMetadata.TYPE]:  Constants.DeviceType.SMARTTV,
    [Constants.DeviceMetadata.VERSION]: "6.5.0",
    [Constants.DeviceMetadata.OS_NAME]: "Tizen",
    [Constants.DeviceMetadata.OS_VERSION]: "6.5.0",
    [Constants.DeviceMetadata.CATEGORY]: Constants.DeviceCategory.SAMSUNG_TV,
    [Constants.DeviceMetadata.SCREEN_RESOLUTION_WIDTH]: 3840,
    [Constants.DeviceMetadata.SCREEN_RESOLUTION_HEIGHT]: 2160,
    [Constants.DeviceMetadata.SCREEN_RESOLUTION_SCALE_FACTOR]: 1
}

convivaMetadata.deviceMetadata = exampleDeviceMetadata
```

Using these configs you can create the Conviva connector with THEOplayer.

* Add as a regular script:

```html
<script type="text/javascript" src="path/to/conviva-connector.umd.js"></script>
<script type="text/javascript">
    const player = new THEOplayer.Player(element, configuration);
    const convivaIntegration = new THEOplayerConvivaConnector.ConvivaConnector(
            player,
            convivaMetadata,
            convivaConfig
    );
</script>
```

* Add as an ES2015 module:

```html
<script type="module">
    import { ConvivaConnector } from "path/to/conviva-connector.esm.js";
    const player = new THEOplayer.Player(element, configuration);
    const convivaIntegration = new ConvivaConnector(player, convivaMetadata, convivaConfig);
</script>
```

The Conviva connector is now ready to start a session once THEOplayer starts playing a source.

Note that the `convivaMetadata` provided to the `ConvivaConnector` constructor is primarily used to pass application specific information to Conviva. Source specific metadata can be provided through the connector's `setContentInfo` method. This data does not carry over to the following sources and needs to be set after the `sourcechange` event has been received.

```js
player.source = exampleSource;

const onSourceChange = () => {
    convivaIntegration.setContentInfo(exampleSourceMetadata);
}
player.addEventListener('sourcechange', onSourceChange);
```

## Usage with Yospace connector

If you have a Yospace SSAI stream and want to also report ad related events to Conviva, you can use this connector in combination with the Yospace connector: [@theoplayer/yospace-connector-web](https://www.npmjs.com/package/@theoplayer/yospace-connector-web)

After configuring the Yospace connector, can link it to the Conviva connector:

```javascript
async function setupYospaceConnector(player) {
        const source = {
            sources: [
                {
                    src: "https://csm-e-sdk-validation.bln1.yospace.com/csm/extlive/yospace02,hlssample42.m3u8?yo.br=true&yo.av=4",
                    ssai: {
                        integration: "yospace"
                    }
                }
            ]
        };
        
        // Create the connectors.
        const yospace = new THEOplayerYospaceConnector.YospaceConnector(player);
        const conviva = new THEOplayerConvivaConnector.ConvivaConnector(player, convivaMetadata, convivaConfig);
    
        // Link ConvivaConnector with the YospaceConnector.
        conviva.connect(yospace);
        
        // Set the source.
        await yospace.setupYospaceSession(source);
    }
```

---

# @theoplayer/conviva-connector-web

## 3.3.2

### 🐛 Issues

* Report THEOads interstitial errors as failed ads.

## 3.3.1

### 🐛 Issues

* Added support for `@theoplayer/yospace-connector-web` version 3.

## 3.3.0

### ✨ Features

* Added support for THEOplayer v11.

## 3.2.0

### ✨ Features

* Changed the behaviour of `stopAndStartNewSession`, not starting a new session if the player is paused until play-out is resumed.
* Added reporting of THEOads `streamActivityMonitorId`, which is passed to the GAM Pod stream request.

## 3.1.2

### 🐛 Issues

* Fixed an issue where ads were no longer reported correctly, caused by a deprecation in the adBreakBegin event.

## 3.1.1

### 🐛 Issues

* Fixed an issue that prevented the ESM build from being loaded using an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap).
  * The ESM build now imports the Conviva SDK using a default import (`import Conviva from '@convivainc/conviva-js-coresdk'`) rather than a named import (`import { Analytics, Constants } from '@convivainc/conviva-js-coresdk'`).

## 3.1.0

### ✨ Features

* Moved the ad start tracking to when the first frame has loaded.
* Added reporting of `encoding_type` (either "DASH", "HLS" or "HESP"), as well as `Constant.defaultResource` and `intentToFallback` reason for THEOlive sources.

## 3.0.0

### 💥 Breaking Changes

* Dropped support for THEOplayer version 8.11.0 and lower.

### ✨ Features

* Added support for THEOplayer version 10.

## 2.9.0

### ✨ Features

* Added play-out configuration values such as `liveOffset`, `targetBuffer`, `bufferLookbackWindow`, `abrStrategy` and `abrMetadata` as custom metadata fields.
* Fixed an issue where the `streamType` value set through the connector API could be overriden with a different value by the connector.

## 2.8.0

### ✨ Features

* Added full call stack info to an error report by splitting it in multiple entries.

## 2.7.0

### ✨ Features

* Added the ability to include the player name in the metadata object passed when creating the ConvivaConnector.
* Added support for THEOplayer `9.0`.

## 2.6.0

### ✨ Features

* Added a check to differentiate between Samsung, LG, Xbox and Vizio when defining the default device category in the metadata.
* Added a detailed report, containing the current player buffer and last fetched segments, in case of a playback failure.

### 🐛 Issues

* Added 'Server Guided' as ad type passed when reporting a THEOads ad break has started.

## 2.5.1

### 🐛 Issues

* Fixed an issue where the stream type, either `VOD` or `Live`, would sometimes be set with a wrong value for live streams.

## 2.5.0

### ✨ Features

* Added `deviceMetadata` property to `ConvivaConfiguration`.

### 🐛 Issues

* Fixed an issue where an asset name, provided via a `ConvivaMetadata` object in the `ConvivaConnector` initialization, stops getting reported after a `sourcechange` event.
* Fixed an issue where the content type of an ad would sometimes be reported as "Live".

## 2.4.0

### ✨ Features

* Added 'Server Guided' ad technology.

## 2.3.0

### ✨ Features

* Added reporting of slate for THEOads.
* Added additional error details on playback failure.

## 2.2.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 2.1.4

### 🐛 Issues

* Fixed an issue where we could throw an error for non Google-IMA ads.

## 2.1.3

### 🐛 Issues

* Fixed an issue where the metadata is not passed correctly after a replay.

## 2.1.2

### 🐛 Issues

* Fixed an issue where the `segmentnotfound` event was reported as a fatal error.

## 2.1.1

### 🐛 Issues

* Report average bitrate to Conviva.

## 2.1.0

### ✨ Features

* Changed Conviva SDK to a peer dependency, enabling users to update it independently from the Conviva connector.

### 🐛 Issues

* Fixed an issue where TypeScript could throw a TS2307 type error on the generated type definitions when the optional `@theoplayer/yospace-connector-web` peer dependency is not installed.

### 📦 Dependency Updates

* @theoplayer/yospace-connector-web\@2.1.2

## 2.0.2

### 🐛 Issues

* Fixed an issue where the THEOplayer library and the Yospace connector were accidentally bundled together with the Conviva connector.

### 📦 Dependency Updates

* @theoplayer/yospace-connector-web\@2.1.1

## 2.0.1

### 🐛 Issues

* Added functionality to listen for external ad events using the `convivaAdEventsExtension` property.

## 2.0.0

### 📦 Dependency Updates

* @theoplayer/yospace-connector-web\@2.1.0

## 1.3.0

### ✨ Features

* Updated to be compatible with THEOplayer `6.X`.

## 1.2.0

### ✨ Features

* Added error event with addition error information on playback failed.

## 1.1.7

### 🐛 Issues

* Removed reporting a buffering state on getting an `emptied` event.

## 1.1.6

### ✨ Features

* Added ad metadata for CSAI.

### 🐛 Issues

* Fixed an issue where the ad break position would be incorrectly reported.

## 1.1.5

### 🐛 Issues

* Updated yospace connector peer dependency.

## 1.1.4

### 🐛 Issues

* Fixed an issue where a session could be created without a source.

## 1.1.3

### Changed

* Made THEOplayer an external dependency.

## 1.1.2

### 🐛 Issues

* Fixed passing content length for a live stream or on early error.

## 1.1.1

### Changed

* Updated THEOplayer version to 5.X.

## 1.1.0

### ✨ Features

* Added `setContentInfo` to pass video metadata during playback.
* Added `setAdInfo` to pass ad metadata during playback.
* Added `reportPlaybackFailed` to notify Conviva of non-video errors.
* Added `stopAndStartNewSession` to enable explicitly stopping the current session and starting a new one.
* Added visibility change reporting.
* Updated THEOplayer version to 4.X.
* Improved error handling.
* Improved default metadata.

### 🐛 Issues

* Fixed handling a replay of the same source.

## 1.0.0

### ✨ Features

* Initial release

---

# gemius-connector-web

The Gemius connector provides a Gemius integration for THEOplayer.

## Installation

```sh
npm install @theoplayer/gemius-connector-web
```

Load the gplayer.js library from Gemius. There are two options to to this: either you do it synchronously:

```html

<script type="text/javascript" src="https://PREFIX.hit.gemius.pl/gplayer.js"></script>
```

... or asynchronously

```html
<script type="text/javascript">
<!--//--><![CDATA[//><!--
function gemius_pending(i) { window[i] = window[i] || function() {var x = window[i+'_pdata']
= window[i+'_pdata'] || []; x[x.length]=arguments;};};
gemius_pending('gemius_init');
function gemius_player_pending(obj,fun) {obj[fun] = obj[fun] || function() {var x =
window['gemius_player_data'] = window['gemius_player_data'] || [];
x[x.length]=[this,fun,arguments];};};
gemius_player_pending(window,"GemiusPlayer");
gemius_player_pending(GemiusPlayer.prototype,"newProgram");
gemius_player_pending(GemiusPlayer.prototype,"newAd");
gemius_player_pending(GemiusPlayer.prototype,"adEvent");
gemius_player_pending(GemiusPlayer.prototype,"programEvent");
gemius_player_pending(GemiusPlayer.prototype,"setVideoObject");
(function(d,t) {try {var gt=d.createElement(t),s=d.getElementsByTagName(t)[0],
l='http'+((location.protocol=='https:')?'s':''); gt.setAttribute('async','async');
gt.setAttribute('defer','defer'); gt.src=l+'://PREFIX.hit.gemius.pl/gplayer.js';
s.parentNode.insertBefore(gt,s);} catch (e) {}})(document,'script');
//--><!]]>
```

Make sure you replace `PREFIX` with the short string of letters specifying the Gemius collecting server. It can be acquired as a part of the tracking code from gemiusPrism interface ( in Settings / Scripts / Streaming Players) or from your local Gemius Tech Support Department.

## Usage

First you need to add the Gemius connector to your app :

* Add as a regular script

```html

<script type="text/javascript" src="path/to/gemius-connector.umd.js"></script>
<script type="text/javascript">
    const player = new THEOplayer.Player(element, configuration);

    // Define your configuration for the connector:
    const gemiusConfig = {
        gemiusID: '<your-publisher-id>',
        debug: true
    };

    // Define the initial program parameters:
    const programParameters = {
        "programID": "000001",
        "programName": "Big Buck Bunny (DASH)",
        "programDuration": 635,
        "programType": "video",
        "transmissionType": 1,
        "programGenre": 4,
        "series": "Test Content",
        "programSeason": "season 1",
        "programProducer": "Blender",
        "customAttributes": {
            "intCategory": "Comedy",
            "intType": "vod",
            "intStatus": "public"
        }
    };

    // Create the GemiusConnector:
    const gemiusConnector = new THEOplayerGemiusConnector.GemiusConnector(player, gemiusConfig, programParameters);
</script>
```

* Add as an ES2015 module

```html
<script type="module">
    import {GemiusConnector} from "path/to/gemius-connector.esm.js";

    const player = new THEOplayer.Player(element, configuration);

    // Define your configuration for the connector:
    const gemiusConfig = {
        gemiusID: '<your-publisher-id>',
        debug: true
    };

    // Define the initial program parameters:
    const programParameters = {
        "programID": "000001",
        "programName": "Big Buck Bunny (DASH)",
        "programDuration": 635,
        "programType": "video",
        "transmissionType": 1,
        "programGenre": 4,
        "series": "Test Content",
        "programSeason": "season 1",
        "programProducer": "Blender",
        "customAttributes": {
            "intCategory": "Comedy",
            "intType": "vod",
            "intStatus": "public"
        }
    };

    // Create the GemiusConnector:
    const gemiusConnector = new GemiusConnector(player, gemiusConfig, programParameters);
</script>
```

## Updating program parameters

If the program parameters changed during playback, you can update it with:

```javascript
const newProgramParameters = { ... };

gemiusConnector.update(newProgramParameters);
```

---

# @theoplayer/gemius-connector-web

## 0.5.0

### ✨ Features

* Added support for THEOplayer v11.

## 0.4.0

### ✨ Features

* Added support for THEOplayer version 10.

## 0.3.0

### ✨ Features

* Added support for THEOplayer `9.0`.

## 0.2.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 0.1.0

### ✨ Features

* Initial release.

---

# Nielsen Web Connector

A connector implementing Nielsen with THEOplayer.

## Installation

```sh
npm install @theoplayer/nielsen-connector-web
```

## Usage

### Configuring the connector

Create the connector by providing the following mandatory parameters:

* The `THEOplayer` instance
* the Nielsen App ID
* the channelName for the asset

and optionally the following parameters:

* a `NielsenOptions` object
* a `NielsenConfiguration` object (if none is provided, the default configuration disables DCR, enables DTVR and sets the country to US)

```js
import { NielsenConnector } from '../../dist/THEOplayerNielsenConnector';

const appId = '<your app ID>';
const channelName = '<your channel name>';

// Non-mandatory options
const options: NielsenOptions = {
    containerId: 'THEOplayer',
    optout: false
};

// Non-mandatory configuration (e.g. for DCR tracking with the Czech Republic SDK)
const configuration: NielsenConfiguration = {
    country: NielsenCountry.CZ,
    enableDTVR: false,
    enableDCR: true
};
const nielsenConnector = new NielsenConnector(player, appId, channelName, options);
```

The `NielsenOptions` can have the following fields:

| Key            | Value                                                           |
| -------------- | --------------------------------------------------------------- |
| `containerId`  | HTML DOM element id of the player container.                    |
| `nol_sdkDebug` | Enables Debug Mode which allows output to be viewed in console. |
| `optout`       | Whether to opt-out of Nielsen Measurement.                      |

### Passing metadata dynamically (DTVR)

The connector allows updating the current asset's metadata at any time. Note that Nielsen's [documentation](https://engineeringportal.nielsen.com/wiki/updateMetadata_\(Browser\)) prohibits updating of the values for `type`, `vidtype` or `assetid` parameters

```js
const metadata = {
    ['channelName']: 'newChannelName',
    ['customTag1']: 'customValue1',
    ['customTag2']: 'customValue2'
};
nielsenConnector.updateMetadata(metadata);
```

### Passing metadata when setting a source to the player (DCR)

This can be achieved through the `updateDCRContentMetadata` method, e.g.:

```js
const metadata: NielsenDCRContentMetadataCZ = {
    assetid: 'cz-500358-98731568435405',
    program: 'Animated Test Content',
    title: 'Big Buck Bunny',
    length: '596',
    airdate: '20230620 20:00:00',
    isfullepisode: true,
    crossId1: '915 954 39504',
    c2: '651678089925925',
    segB: '011',
    adloadtype: AdLoadType.linear,
    hasAds: HasAds.supports_ads
};

nielsenConnector.updateDCRContentMetadata(metadata);
```

Note that types are included in the package: `NielsenDCRContentMetadataUS`, `NielsenDCRContentMetadataCZ`. Please contact your THEO Technologies representative if you need support for another International DCR SDK.

---

# @theoplayer/nielsen-connector-web

## 1.7.0

### ✨ Features

* Added support for THEOplayer v11.

## 1.6.0

### ✨ Features

* Added support for THEOplayer version 10.

## 1.5.0

### ✨ Features

* Added support for THEOplayer `9.0`.

## 1.4.0

### ✨ Features

* Added an optional c4 parameter to `NielsenDCRContentMetadataCZ`.

## 1.3.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 1.2.0

### ✨ Features

* Add DCR support (CZ and US).

## 1.1.2

### 🐛 Issues

* Fixed an issue where the package did not properly export the Nielsen types.

## 1.1.1

### 🐛 Issues

* Added support for DASH emsg cue payloads.

## 1.1.0

### ✨ Features

* Updated to be compatible with THEOplayer `6.X`.

## 1.0.0

### ✨ Features

* Initial release

---

# yospace-connector-web

The Yospace connector provides a Server-Side Ad Insertion (SSAI) integration with Yospace for THEOplayer.

## Prerequisites

In order to use this connector, a [THEOplayer](https://www.npmjs.com/package/theoplayer) build with a valid license is required. You can use your existing THEOplayer HTML5 SDK license or request yours via [THEOportal](https://portal.theoplayer.com/).

For setting up a valid Yospace session, the Yospace Ad Management SDK is required. For more information on how to install the Ad Management SDK, please refer to the documentation of [Yospace](https://docs.yospace.com/library/technical/sdks/en/ad-management-sdks-v3/javascript.html).

**Remark:** This version of the Yospace Connector is compatible with Yospace Ad Management SDK version 3.10.0 or higher. If you still want to use an older Ad Management SDK, please use the connector version 2.8.0 or earlier.

## Installation

Install using your favorite package manager for Node (such as `npm` or `yarn`):

### Install via npm

```bash
npm install @theoplayer/yospace-connector-web
```

### Install via yarn

```bash
yarn add @theoplayer/yospace-connector-web
```

## Usage

First you need to add the Yospace connector to your app :

* Add as a regular script

```html
<script type="text/javascript" src="path/to/yospace-connector.umd.js"></script>
<script type="text/javascript">
    const player = new THEOplayer.Player(element, configuration);
    const yospaceConnector = new THEOplayerYospaceConnector.YospaceConnector(player);
</script>
```

* Add as an ES2015 module

```html
<script type="module">
    import { YospaceConnector } from "path/to/yospace-connector.esm.js";
    const player = new THEOplayer.Player(element, configuration);
    const yospaceConnector = new YospaceConnector(player);
</script>
```

To make use of the Yospace integration, you need to set up a session for your Yospace source :

```javascript
const source = {
    sources: [
        {
            src: "YOUR_YOSPACE_SRC",
            ssai: {
                integration: "yospace"
                // If necessary, you can define your streamType.
                // streamType: 'vod' | 'live' | 'livepause'
            }
        }
    ]
}

await yospaceConnector.setupYospaceSession(source);
```

If you want to customize your session, you can also pass your customized `SessionProperties` from the Yospace Ad Management SDK :

```javascript
// create a new SessionProperties object using the Ad Management SDK.
const sessionProperties = new YospaceAdManagement.SessionProperties();
const source = {
    sources: [
        {
            src: "YOUR_YOSPACE_SRC",
            ssai: {
                integration: "yospace"
                // If necessary, you can define your streamType.
                // streamType: 'vod' | 'live' | 'livepause'
            }
        }
    ]
}

await yospaceConnector.setupYospaceSession(source, sessionProperties);
```

Once the setup of the Yospace session is done, you can continue to use the player and the connector will handle everything related to Yospace.

---

# @theoplayer/yospace-connector-web

## 3.0.0

### 💥 Breaking Changes

* Removed `isPlaceholder()` and `isEncoded()` type definitions since they were removed in Yospace Ad Management SDK 3.11.0.
* Replaced `PlaybackMode` with `SessionMode` for compatibility with Yospace Ad Management SDK 3.10.0+. This change brings the minimum supported Yospace Ad Management SDK version to 3.10.0.

### 🐛 Issues

* Fixed an exception when an ad break starts without data during live playback.

## 2.8.0

### ✨ Features

* Added support for THEOplayer v11.

## 2.7.0

### ✨ Features

* Added support for THEOplayer version 10.

## 2.6.0

### ✨ Features

* Added support for THEOplayer `9.0`.

## 2.5.0

### ✨ Features

* Create ad break from advert start, if missing

### 🐛 Issues

* Require THEOplayer 8.1.0 or higher for correct TypeScript type definitions.

## 2.4.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 2.3.0

### ✨ Features

* Added `YospaceServerSideAdInsertionConfiguration` type definition to the connector, superseding the type defined by the THEOplayer Web SDK.

## 2.2.0

### ✨ Features

* The connector now integrates with the [custom server-side ad integration API](https://www.theoplayer.com/docs/theoplayer/v7/api-reference/web/interfaces/Ads.html#registerServerSideIntegration.registerServerSideIntegration-1) introduced in THEOplayer 7.4.0. This allows Yospace adverts to show up through the `player.ads` API of THEOplayer.

## 2.1.3

### 🐛 Issues

* Fixed playback position reporting for live DVR streams (with `streamType` set to `"livepause"`).

## 2.1.2

### 🐛 Issues

* Fix missing API types in TypeScript type definitions.

## 2.1.1

### 🐛 Issues

* Added support for THEOplayer 7.0.

## 2.1.0

### ✨ Features

* Exposed SessionErrorCode.

## 2.0.0

### ✨ Features

* Upgrade to latest Yospace Ad Management SDK

## 1.4.0

### ✨ Features

* Allow THEOplayer 6.0.0 as peer dependency

## 1.3.0

### ✨ Features

* Update THEOplayer peer dependency

## 1.2.0

### ✨ Features

* Expose typings

### 🐛 Issues

* Handle empty `activeCues` list

## 1.1.0

### ✨ Features

* Add support for custom Analytics Event Observers

## 1.0.0

### ✨ Features

* Initial release

---

# OptiView Player Android SDK

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Dolby OptiView Player is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/getting-started.md)

[Set up your first THEOplayer in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android.md)

## [🎨UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android.md)

[Customize with Open Video UI or build from scratch.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android.md)

## [🔌Connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android.md)

[Integrate third-party solutions with THEOplayer using our pre-built connectors.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md)

[Find out what's new in the OptiView Player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md)

## [\*️⃣API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android)

[Discover all properties and functions of THEOplayer.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

# Getting started on Android

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

## Add THEOplayer and Kotlin libraries to your application

We have to modify the `build.gradle` files to be able to fetch the Android SDK and the Kotlin plugin.

1. In your **top-level** (project) `settings.gradle.kts` file

2. Add the THEOplayer Maven repository.

**Groovy**

```groovy
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url "https://maven.theoplayer.com/releases" }
    }
}
```

**Kotlin**

```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://maven.theoplayer.com/releases") }
    }
}
```

1. Next, we need to edit the `build.gradle` on the **module-level** (**app/build.gradle**)

**Groovy**

```groovy
implementation "com.theoplayer.theoplayer-sdk-android:core:+"
implementation "org.jetbrains.kotlin:kotlin-stdlib:1.6.21"
implementation "androidx.appcompat:appcompat:1.7.0"
```

**Kotlin**

```kotlin
implementation("com.theoplayer.theoplayer-sdk-android:core:+")
implementation("org.jetbrains.kotlin:kotlin-stdlib:1.6.21")
implementation("androidx.appcompat:appcompat:1.7.0")
```

*Note*: It's possible to replace the `+` with a particular version of THEOplayer that should be used, for example:

`implementation 'com.theoplayer.theoplayer-sdk-android:core:8.0.0'`

## Setting up the license

You need to configure your THEOplayer license, if you don't enter this license string, you might encounter licensing issues (e.g.: when trying to play non-whitelisted video streams).

First, obtain a THEOplayer Android SDK license through the [THEOplayer Developer Portal](https://portal.theoplayer.com/login). ![](https://cdn.theoplayer.com/images/git/theoplayer-android-sdk-license-string.png)

Then, identify your license string from the screenshot above and add the `<meta-data ...` tag below at the appropriate location in your `AndroidManifest.xml`, and swap `your_license_here` with your actual license string.

```xml
<application>
    <meta-data
        android:name="THEOPLAYER_LICENSE"
        android:value="your_license_here" />
</application>
```

Additionally, to play online videos with THEOplayer, you first need to add [INTERNET](https://developer.android.com/reference/android/Manifest.permission.html#INTERNET) permission into the `AndroidManifest.xml` file too.

```xml
<uses-permission android:name="android.permission.INTERNET" />
```

More information regarding the license can be found [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/license/introduction.md).

## Add THEOplayer view to your application

THEOplayer can be added to an Android application either:

1. **Through a layout (XML)**: By adding the `THEOplayerView` to your layout XML file (e.g., `activity_main.xml`), or
2. **Programmatically using the Constructor API**: This approach also allows you to configure the license string through a programmatic configuration instead of the `AndroidManifest.xml`.

### Adding THEOplayerView via XML layout

You can add the `THEOplayerView` to the layout of the `MainActivity` with the snippet below.

![](/pr-932/assets/images/android-getting-started-13_2-2581c1dcb239371b38441eff6e36e67d.png)

At least the `id`, `width` and `height` attributes need to be specified on the new view. The `id` is important as it is used to identify the view object in your `MainActivity` class.

```xml
<com.theoplayer.android.api.THEOplayerView
    android:id="@+id/theoplayer"
    android:layout_width="match_parent"
    android:layout_height="300dp"
    app:layout_constraintTop_toTopOf="parent">
</com.theoplayer.android.api.THEOplayerView>
```

![](/pr-932/assets/images/android-getting-started-14_2-d3679a00ce0fd4aa120793ddf8a96df3.png)

### Adding THEOplayerView programmatically (Constructor API)

In the Activity/Fragment, you can use the [constructor API](https://docs.theoplayer.com/api-reference/android/index.html?com/theoplayer/android/api/THEOplayerView.html) to create a THEOplayer instance by passing along a context and a [`THEOplayerConfig`](https://docs.theoplayer.com/api-reference/android/index.html?com/theoplayer/android/api/THEOplayerConfig.html).

In this `THEOplayerConfig`, you can configure your license string, as demonstrated in the snippet below.

**Kotlin**

```kotlin
val playerConfig = THEOplayerConfig.Builder()
    .license("your_license_here")
    .build()

val theoPlayerView = THEOplayerView(this, playerConfig)
```

**Java**

```java
THEOplayerConfig playerConfig = new THEOplayerConfig.Builder()
    .license("your_license_here")
    .build();

THEOplayerView theoPlayerView = new THEOplayerView(this, playerConfig);
```

This approach is ideal when you need to adjust the configuration dynamically, such as during runtime or based on specific app conditions. It removes the need for XML-based configuration and is useful for advanced customization scenarios.

## Use THEOplayer API in your application

Now in the `MainActivity` we can retrieve the `THEOplayerView` by the `id` we set earlier using the `findViewById` method.

### 1. Get the THEOplayer instance

**Kotlin**

```kotlin
...
import com.theoplayer.android.api.THEOplayerView

class MainActivity : ComponentActivity() {
    lateinit var theoPlayerView: THEOplayerView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        theoPlayerView = findViewById(R.id.theoplayer)
    }
}
```

**Java**

```java

import com.theoplayer.android.api.THEOplayerView;

public class MainActivity extends ComponentActivity {
    private THEOplayerView theoPlayerView;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        theoPlayerView = findViewById(R.id.theoplayer);
    }
}
```

### 2. Configure source

To play a video in THEOplayer, we need to configure a source for the player in our `MainActivity`:

**Kotlin**

```kotlin
val typedSource = TypedSource
    .Builder("https://cdn.theoplayer.com/video/dash/big_buck_bunny/BigBuckBunny_10s_simple_2014_05_09.mpd")
    .type(SourceType.DASH)
    .build()

val sourceDescription = SourceDescription
    .Builder(typedSource)
    .build()

theoPlayerView.player.source = sourceDescription
```

**Java**

```java
TypedSource typedSource = new TypedSource
        .Builder("https://cdn.theoplayer.com/video/dash/big_buck_bunny/BigBuckBunny_10s_simple_2014_05_09.mpd")
        .type(SourceType.DASH)
        .build();

SourceDescription sourceDescription = new SourceDescription
        .Builder(typedSource)
        .build();

theoPlayerView.getPlayer().setSource(sourceDescription);
```

### 3. Control THEOplayer through the API

We will now introduce a button to start/stop the video in the player.

First add the button to our `activity_main.xml` layout file.

```xml
<Button
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:id="@+id/btn_playpause"
        android:text="PLAY/PAUSE" />
```

![](/pr-932/assets/images/android-getting-started-16_2-c9da3210e9ea5233dd37a28b23cf3436.png)

Then set an `OnClickListener()` on the button in our `MainActivity` code to trigger `play()` and `pause()` on the player.

**Kotlin**

```kotlin
val btnPlayPause = findViewById<Button>(R.id.btn_playpause)
btnPlayPause.setOnClickListener {
    if (theoPlayerView.player.isPaused) {
        theoPlayerView.player.play()
    } else {
        theoPlayerView.player.pause()
    }
}
```

**Java**

```java
Button btnPlayPause = findViewById(R.id.btn_playpause);
btnPlayPause.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        if (theoPlayerView.getPlayer().isPaused()) {
            theoPlayerView.getPlayer().play();
        } else {
            theoPlayerView.getPlayer().pause();
        }
    }
});
```

![](/pr-932/assets/images/android-getting-started-17_2-7c2ab5a4cca6f765e67b9c91989dab65.png)

### 4. Listen for THEOplayer events

The next step is listening for player events.

First, we need to create two more TextViews in the `activity_main.xml` file.

```xml
<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/txt_playstatus"
    android:layout_marginStart="20dp"/>

<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/txt_timeupdate"
    android:layout_marginStart="20dp"/>
```

We will now listen for `PLAY`, `PAUSE` and `TIMEUPDATE` in this example.

**Kotlin**

```kotlin
val txtPlayStatus = findViewById<TextView>(R.id.txt_playstatus)
val txtTimeUpdate = findViewById<TextView>(R.id.txt_timeupdate)

theoPlayerView.player.addEventListener(PlayerEventTypes.PLAY) {
    txtPlayStatus.text = "Playing"
}

theoPlayerView.player.addEventListener(PlayerEventTypes.PAUSE) {
    txtPlayStatus.text = "Paused"
}

theoPlayerView.player.addEventListener(PlayerEventTypes.TIMEUPDATE) { timeUpdateEvent ->
    txtTimeUpdate.text = timeUpdateEvent.currentTime.toString()
}
```

**Java**

```java
TextView txtPlayStatus = findViewById(R.id.txt_playstatus);
TextView txtTimeUpdate = findViewById(R.id.txt_timeupdate);

theoPlayerView.getPlayer().addEventListener(PlayerEventTypes.PLAY, new EventListener<PlayEvent>() {
    @Override
    public void handleEvent(PlayEvent playEvent) {
        txtPlayStatus.setText("Playing");
    }
});

theoPlayerView.getPlayer().addEventListener(PlayerEventTypes.PAUSE, new EventListener<PauseEvent>() {
    @Override
    public void handleEvent(PauseEvent pauseEvent) {
        txtPlayStatus.setText("Paused");
    }
});

theoPlayerView.getPlayer().addEventListener(PlayerEventTypes.TIMEUPDATE, new EventListener<TimeUpdateEvent>() {
    @Override
    public void handleEvent(TimeUpdateEvent timeUpdateEvent) {
        txtTimeUpdate.setText(String.valueOf(timeUpdateEvent.getCurrentTime()));
    }
});
```

When the events are triggered, we will update the **MainActivity** UI with the corresponding state.

### 5. Play fullscreen video in landscape mode

THEOplayer SDK contains a default fullscreen activity which can be started automatically when you rotate your device.

We have to configure our player instance in the `MainActivity` to react to orientation changes and start the Fullscreen activity.

**Kotlin**

```kotlin
override fun onCreate(savedInstanceState: Bundle?) {
    //...
    theoPlayerView = findViewById(R.id.theoplayer)
    theoPlayerView.fullScreenManager.isFullScreenOrientationCoupled = true
    //...
}
```

**Java**

```java
@Override
protected void onCreate(Bundle savedInstanceState) {
    // ...
    theoPlayerView = findViewById(R.id.theoplayer);
    theoPlayerView.getFullScreenManager().setFullScreenOrientationCoupled(true);
    // ...
}
```

![](/pr-932/assets/images/android-getting-started-21_2-2d0fe0d572fda2b75cd485696997f3b8.png)

In the `AndroidManifest.xml` we can disable the default orientation behavior on our `MainActivity` and lock it in portrait. Then, because we enabled fullscreen orientation coupling with the `setFullScreenOrientationCoupled(true)` method earlier, THEOplayer will take care of the support of seamless landscape activity transition at rotation.

```xml
<activity android:name=".MainActivity"
    android:screenOrientation="userPortrait"
    android:configChanges="orientation|screenSize" >
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />

        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>
```

If you would like to customize the Fullscreen Activity, you can take a look at our sample [here](https://github.com/THEOplayer/samples-android-sdk/tree/master/full-screen-handling).

## Couple THEOplayer with the lifecycle callbacks

In order for THEOplayer to work properly and in sync with the [Activity lifecycle changes](https://developer.android.com/guide/components/activities/activity-lifecycle) (e.g. when we rotate the device or start a new Activity or the app goes to background). We need to call the `onResume`, `onPause` and `onDestroy` methods of the `THEOplayerView` when the matching methods are called in the Activity.

**Kotlin**

```kotlin
class MainActivity : ComponentActivity() {

    // ...

    override fun onPause() {
        super.onPause()
        theoPlayerView.onPause()
    }

    override fun onResume() {
        super.onResume()
        theoPlayerView.onResume()
    }

    override fun onDestroy() {
        super.onDestroy()
        theoPlayerView.onDestroy()
    }

    // ...

}
```

**Java**

```java
public class MainActivity extends AppCompatActivity{

    // ...

    @Override
    protected void onPause() {
        super.onPause();
        theoPlayerView.onPause();
    }

    @Override
    protected void onResume() {
        super.onResume();
        theoPlayerView.onResume();
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        theoPlayerView.onDestroy();
    }

    // ...
}
```

## Run your application

Here you have some screenshots from the running application:

### Start screen

![](/pr-932/assets/images/android-getting-started-screenshot-1-38ce0ff7ab21b1cffa889c91d2543b9f.png)

### Playing screen

![](/pr-932/assets/images/android-getting-started-screenshot-2-d107e77d808409e46aceb0af2254c254.png)

### Paused screen

![](/pr-932/assets/images/android-getting-started-screenshot-3-a2952d823ef5f5c639d5fca97458b8f6.png)

### Rotated fullscreen

![](/pr-932/assets/images/android-getting-started-screenshot-4-cadbdc87fd1b76e026ce32081367c1d6.png)

## Summary

This guide focuses on creating an Android application from scratch and integrating the THEOplayer Android SDK.

* You have learned how to interact with the player via the available APIs in Kotlin and Java,
* you have registered player events,
* and you have learned how to enable automatic orientation detection.

You can find various samples for different use cases on [GitHub](https://github.com/THEOplayer/samples-android-sdk/tree/master).

Did you encounter any issues? Raise a ticket through [the ticketing system](https://opentelly.atlassian.net/servicedesk/customer/portal/1) and we will be happy to assist.

---

# Getting started with the Android UI

For the most up-to-date information about our new open source, fully native Android UI, visit [the GitHub page](https://github.com/THEOplayer/android-ui).

---

# Android Feature Integrations

## Modularization

The Android THEOplayer SDK uses modularized features, which means there is a base SDK that can handle basic playback and additional feature integrations are provided as separate modules that can be added as desired. This approach gives more flexibility and results in a reduced application size, since non-required parts are not included in the build of the application.

For example, the base SDK is provided by:

```groovy
implementation 'com.theoplayer.theoplayer-sdk-android:core:8.0.0'
```

Meanwhile, additional features such as Google IMA and Google Cast are provided by:

```groovy
implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-ima:8.0.0'
implementation 'com.theoplayer.theoplayer-sdk-android:integration-cast:8.0.0'
```

## Importing additional integration modules

As shown in the previous section, importing additional integration modules can be done by simply adding the dependency in the `build.gradle` file of the module using THEOplayer.

> **Important**
>
> It is required to keep the Android base SDK and all the required integration modules on the **same** version number. For example one should **not** import `core:8.1.0` and `integration-cast:8.2.0` in the same project.
>
> Consider using [version catalogs](https://developer.android.com/build/migrate-to-catalogs) in your app to manage the version of the base SDK and the integration modules.

## Adding integrations

After importing the dependencies, it's time to create the integrations and connect them to THEOplayer.

### Adding integrations automatically

Starting with version 8.13.0, the Android SDK supports automatically connecting all available integrations to your player. When constructing your `THEOplayerView`, set [`THEOplayerConfig.autoIntegrations`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/THEOplayerConfig.Builder#autoIntegrations\(boolean\)) to `true`:

```kotlin
val theoplayerConfig = THEOplayerConfig.Builder()
    .autoIntegrations(true)
    .build()
val theoplayerView = THEOplayerView(context, theoplayerConfig)
```

The player will automatically create and attach any integrations that were added to your app's dependencies.

> **Info**
>
> Starting with version 9.0.0, this automatic behavior will become the default. You can always opt out by manually setting [`THEOplayerConfig.autoIntegrations`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/THEOplayerConfig.Builder#autoIntegrations\(boolean\)) to `false`.

### Adding integrations manually

You can also create and attach each integration manually.

Each module provides a **Factory** class that allows the creation of that specific integration. For example, the Google IMA module provides [`GoogleImaIntegrationFactory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/ima/GoogleImaIntegrationFactory) and the Google Cast module provides [`CastIntegrationFactory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/cast/CastIntegrationFactory). You can then attach the created integration to your player using the [`addIntegration(Integration integration)`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#addIntegration\(com.theoplayer.android.api.Integration\)) method of the `Player` API.

For example, to set up the Google IMA integration, you create an integration using the [`GoogleImaIntegrationFactory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/ima/GoogleImaIntegrationFactory) and then attach it to the player using [`addIntegration(Integration integration)`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#addIntegration\(com.theoplayer.android.api.Integration\)):

```kotlin
import com.theoplayer.android.api.ads.ima.GoogleImaIntegrationFactory

val theoplayerView = THEOplayerView(context)
val googleImaIntegration = GoogleImaIntegrationFactory.createGoogleImaIntegration(theoplayerView)
theoplayerView.player.addIntegration(googleImaIntegration)
```

[The documentation of each individual integration](#available-feature-integrations) provides more detail on how to set up and configure that integration.

> **Warning**
>
> You must call `addIntegration()` before using the integration. Attempting to call a method on the integration without attaching it to a player will throw an error.

## Available feature integrations

With Android THEOplayer SDK we currently support the following feature integrations:

| Feature         | Dependency                      | Release | Documentation                                                                                                                               |
| --------------- | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Google IMA      | `integration-ads-ima:+`         | 3.1.0+  | [Google IMA Documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/google-ima.md)               |
| Chromecast      | `integration-cast:+`            | 3.4.0+  | [Chromecast Documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/introduction.md) |
| AWS MediaTailor | `integration-ads-mediatailor:+` | 4.0.0+  | [AWS MediaTailor Documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/mediatailor.md)         |
| Google DAI      | `integration-ads-dai:+`         | 4.3.0+  | [Google DAI Documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/google-dai.md)               |
| Optiview Ads    | `integration-ads-theoads:+`     | 8.2.0+  | [Optiview Ads Documentation](https://docs-preview.optiview.dolby.com/pr-932/ads/player-integration/optiview-player/android.md)              |
| Millicast       | `integration-millicast:+`       | 8.2.0+  | [Millicast Documentation](https://docs-preview.optiview.dolby.com/pr-932/millicast/android-player)                                          |
| Jetpack Media3  | `integration-media3:+`          | 8.10.0+ | [Media3 Documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media3/getting-started.md)           |

---

# Migrating to THEOplayer Android SDK 11.x

This article will guide you through updating to THEOplayer Android SDK version 11 (from version 10), and the changes needed in your code.

## Update THEOplayer

Update THEOplayer Android SDK to version 11 in your **module-level** `build.gradle` file:

```groovy
dependencies {
    implementation 'com.theoplayer.theoplayer-sdk-android:core:11.+'
}
```

If you're using the [Open Video UI for Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui.md) or one of [our connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android.md), make sure to update them to the latest version too to ensure proper support for THEOplayer version 11.

## Player methods must be called from the main thread

All methods on `Player` and `THEOplayerView` must only be called from the main thread. Calling these methods from a different thread will now throw an `IllegalStateException`.

These methods are now annotated with [`@MainThread`](https://developer.android.com/reference/androidx/annotation/MainThread), which should help the Android build tools to catch potential threading issues at compile time.

## Google IMA SDK integration requires core library desugaring

The Google IMA SDK integration now requires [core library desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) to be enabled.

```groovy
android {
    compileOptions {
        coreLibraryDesugaringEnabled = true
    }
}

dependencies {
    implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
    implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-ima:+'

    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5'
}
```

See [our updated guide for Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/google-ima.md) for more information.

## Replace or remove usages of deprecated APIs

Some properties and methods that were previously deprecated have been removed from the API. Update your code to use the new APIs instead.

* Removed `preloadChannels` in THEOlive API.
* Changed `MediaTailorAdAvail.id` to return a `String` instead of an `Int`, to align with `AdBreak.id`. If you need the original `Int` value, use `AdBreak.id.toInt()` instead.
* Removed `TheoAdsErrorEvent`, use `AdErrorEvent` instead.
* Removed `TheoAdsEventTypes.THEOADS_ERROR`, use `AdsEventTypes.AD_ERROR` instead.

---

# How-to guides for OptiView Player Android SDK

Want to start implementing features to your SDK? Our how-to-guides will help you with all kind of integrations!

## [💰Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/introduction.md)

[10 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/introduction.md)

## [📊Analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/introduction.md)

[12 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/introduction.md)

## [Cast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/introduction.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/introduction.md)

## [🔐DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md)

[20 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md)

## [🔌Integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/integrations/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/integrations/introduction.md)

## [🎥Media tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/introduction.md)

[9 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/introduction.md)

## [\*️⃣Miscellaneous](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/introduction.md)

[5 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/introduction.md)

## [📡Network](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/network/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/network/introduction.md)

## [▶️Player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/player/introduction.md)

[5 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/player/introduction.md)

## [💬Text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/introduction.md)

[9 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/introduction.md)

## [🔑License](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/license/introduction.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/license/introduction.md)

## [☁️CMCD](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cmcd/getting-started.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cmcd/getting-started.md)

## [Media3](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media3/getting-started.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media3/getting-started.md)

## [🚀OptiView Live](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/theolive/getting-started.md)

[Integrate OptiView Live streaming into your Android app.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/theolive/getting-started.md)

---

# Advertisements on Android

The articles in this section describe how to implement common use-cases related to advertisements. These use-cases can range from customizing the UX during advertisements, to detecting ad blockers.

Consider reading our [Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/user-guide.md) to learn more about advertising and THEOplayer's capabilities.

We recommend starting with [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/set-up-vast-and-vmap.md), as this article explains how to set up client-side advertisements.

### Table of Contents

* Client-side advertisement systems

  * [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/set-up-vast-and-vmap.md)
  * [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/google-ima.md)

* Server-side advertisement systems

  * [Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/yospace.md)
  * [Google DAI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/google-dai.md)
  * [MediaTailor](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/mediatailor.md)
  * [Custom Server Side Ad Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/custom-ssai-integration.md)

* Other

  * [How to subscribe to ad events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/subscribe-to-ad-events.md)
  * [Customizing the ad overlay text](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/customizing-the-ad-overlay-text.md)
  * [Prebid.js](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/prebidjs.md)

---

# Customizing the ad overlay text on Android

This guide explains how to customize the overlay text shown during an ad break. You may ask this question if you want to change the styling or override the texts shown during an ad break.

Depending on the ad integration kind you use, the steps to take differ.

## Google IMA/DAI

With Google IMA/DAI, it is not possible to directly edit the default UI. You can pass a locale to IMA to completely localize the ad UI.

### Changing or localizing the text

You can pass [your preferred language](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/ImaSdkSettings.html#setLanguage\(java.lang.String\)) while adding the Google IMA integration to the player:

```kotlin
private fun addGoogleImaIntegration() {
    val settings = ImaSdkFactory.getInstance().createImaSdkSettings()
    settings.language = "nl"

    val imaIntegration = createGoogleImaIntegration(tpv!!, settings)

    tpv?.player?.addIntegration(imaIntegration)
}
```

You can find a list of locales supported by the IMA SDK on Android [here](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/localization#locale-codes).

### Changing the styling

Please refer to the relevant [Google IMA guide](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/custom-ui) on how to disable the default UI and implement your own ad UI.

## Remarks

* If you customize OptiView Player with [Open Video UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md), there may be other ways to edit certain elements depending on the platform and ad integration. See the [Web SDK CSAI example](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/examples/ads.md) for reference.
* The `Why this ad?` text or the `?` (question mark) icon that may appear while using the Google IMA/DAI integration is inserted by the IMA SDK itself and is required to be displayed with any ad that was not manually selected. The icon is rendered as a VAST icon and is automatically generated by Ad Manager where required.

## Resources

* [THEOplayer advertisement tester](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/advertisement-tester.md)

---

# How to set up VAST and VMAP ads on Android

This article explains how to schedule client-side VAST and VMAP advertisements through THEOplayer.

* A VAST advertisement is a single ad break, and you can position it as a pre-roll, mid-roll or post-roll.
* A VMAP advertisement is a playlist of ad breaks, and can contain any combination of pre-rolls, mid-rolls and/or post-rolls.

Through the THEOplayer API, app developers can define which "ad integration" they want to use. Scheduling VAST and VMAP ads through all ad integrations is very similar, so consider this article as a reference guide.

On Android, client-side advertisements are scheduled through the [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/google-ima.md) ad integration, so [make sure to set it up](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/google-ima.md) before starting.

## VAST

Setting up a client-side VAST advertisement means scheduling a VAST ad tag.

As an app developer, you associate a VAST ad tag (URL) (e.g. `https://cdn.theoplayer.com/demos/ads/vast/vast.xml`) with a time offset.

You may also schedule multiple ad tags.

Let's consider the following common use-cases:

1. [Scheduling a single pre-roll](#scheduling-a-single-pre-roll)
2. [Scheduling two pre-rolls, two mid-rolls and one post-roll](#scheduling-two-pre-rolls-two-mid-rolls-and-one-post-roll)

### Scheduling a single pre-roll

You configure a [GoogleImaAdDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/source/addescription/GoogleImaAdDescription.Builder) in the `ads` property of your [`SourceDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/source/SourceDescription.Builder#ads-com.theoplayer.android.api.source.addescription.AdDescription...-).

In this `GoogleImaAdDescription`,

* You set an ad tag URL.
* You set the value of [`timeOffset`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/source/addescription/GoogleImaAdDescription.Builder#timeOffset-java.lang.String-) to `"start"` (or `00:00:00` or `0%`) to indicate that it's a pre-roll.

```kotlin
theoPlayer.source = SourceDescription.Builder(
    TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8").build())
    .ads(
        GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/dfp-linear-inline-no-skip.xml")
            .timeOffset("start")
            .build())
    .build()
```

If you wanted to schedule a post-roll instead of a pre-roll, you set the value of `timeOffset` to `"end"`.

If you want to schedule a mid-roll instead of a pre-roll, you set the value of `timeOffset` to the `HH:MM:SS` format.

For example, to schedule an advertisement at the 15s mark, you set the value of `timeOffset` to `"00:00:15"`.

### Scheduling two pre-rolls, two mid-rolls and one post-roll

Scheduling multiple VAST ads is only slightly different from scheduling a single VAST ad. Instead of passing along one ad description, you pass along multiple ad descriptions.

```kotlin
val typedSource = TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8")
val sourceDescription = SourceDescription.Builder(typedSource.build())

sourceDescription.ads(
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
        .timeOffset("start")
        .build(),
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
        .timeOffset("start")
        .build(),
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
        .timeOffset("00:00:15")
        .build(),
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
        .timeOffset("00:00:15")
        .build(),
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
        .timeOffset("end")
        .build()
)

theoPlayer.source = sourceDescription.build()
```

### Skippable ads

To allow viewers to skip an ad, leverage the `skipOffset` property in your VAST (or VMAP) file, and adhere to the [VAST standard](https://iabtechlab.com/standards/vast/), because this offers the widest support across ad integrations and platforms.

## VMAP

Scheduling a VMAP advertisement is similar to scheduling a VAST advertisement. However, you don't define the `timeOffset`, because the VMAP playlist defines the offsets of each ad break it contains. The time offset helps VAST ads to play at a specific timestamp. VMAP ads can define that behavior inside their manifest file, thus they should not have a timeOffset parameter. This property may not be configured for ad types other than `VAST`. Setting a `timeOffset` on a `VMAP` ad will cause your ads not to be scheduled correctly, unless you explicitly configured an `AdSource.type`, in which case `timeOffset` will be ignored. This is because the player must decide up front when to load the ad source: `VMAP` ads must be loaded immediately in order to schedule them correctly, while loading a `VAST` ad can be deferred until right before the `timeOffset` at which to play them. Therefore, if a `timeOffset` is configured without an explicit `AdSource.Type`, the player will assume that it's a `VAST` ad.

The snippet below demonstrates how to configure a VMAP advertisement.

```kotlin
val typedSource = TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8")
val sourceDescription = SourceDescription.Builder(typedSource.build())

sourceDescription.ads(
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vmap/single-pre-mid-post-no-skip.xml")
        .build()
)

theoPlayer.source = sourceDescription.build()
```

## Dynamic scheduling

If you've read our [Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/user-guide.md#dynamic-ad-scheduling), you might have picked up that you can also dynamically schedule VAST advertisements in THEOplayer. All previous samples in this article use static, pre-defined scheduling; you schedule the ads whenever you schedule the stream. With dynamic scheduling, you schedule ads at runtime.

You use the `Ads` interface to schedule an ad description at runtime. More specifically, you invoke the `schedule` function when your video is already playing.

Note that specifying the `timeOffset` is optional, and that this value is an absolute value. For example, let's consider that your current playhead position is at the 20 seconds mark, and that you want to schedule an ad at the 30 seconds mark. To achieve this, you would set `timeOffset: "00:00:30"`, and not `timeOffset: "00:00:10"`, because this would be 10 seconds in the past, and the ad would instantly start playing.

Invoking the following example function when the video is already playing will instantly schedule the VAST ad to be played:

```kotlin
theoPlayer.ads.schedule(
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
        .build()
)
```

## Resources

* [Samples for Android SDK](https://github.com/THEOplayer/samples-android-sdk)

---

# Yospace on Android

Yospace is a Server-Side Ad Insertion solution. THEOplayer partnered with Yospace to fully integrate their solution, allowing you to play their streams in a breeze.

## Usage

You need to set up [THEOplayer Yospace Connector for Android](https://github.com/THEOplayer/android-connector/tree/master/connectors/yospace). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/yospace) section to learn all about how to integrate and use the Yospace connector on Android (TV) SDK.

## Conclusion

This partnership means that we are compatible with each other: THEOplayer has a long history with and is optimized to play Yospace streams. We regularly validate our connectors and are the first to know about changes to the Yospace infrastructure.

## Resources

* [Getting started on Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/getting-started.md)
* [Yospace website](https://www.yospace.com/)

---

# Google Dynamic Ad Insertion (DAI) on Android

Google Dynamic Ad Insertion (DAI) is a Server-Side Ad-Insertion solution offered by Google where THEOplayer offers playback for HLS and DASH streams.

Using Google DAI in the Android SDK consists of 3 steps.

## Importing the Google DAI feature module

Add `implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-dai:+'` to your module `build.gradle` file, as demonstrated below:

```groovy
dependencies {
    // ...
    implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
    implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-dai:+'
    // ...
}
```

## Creating an instance of the Google DAI integration

> **Tip**
>
> If you're using [automatic integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/features.md#adding-integrations-automatically), you can skip this step.

Create a `GoogleDaiIntegration` through the `GoogleDaiIntegrationFactory`, and add it to your player instance, as demonstrated below:

```kotlin
val theoplayerView = THEOplayerView(context)
val daiIntegration = GoogleDaiIntegrationFactory.createGoogleDaiIntegration(theoplayerView)
theoplayerView.player.addIntegration(daiIntegration)
```

## Using a Google DAI source

Use a [GoogleDaiVodConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/source/ssai/dai/GoogleDaiVodConfiguration) or [GoogleDaiLiveConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/source/ssai/dai/GoogleDaiLiveConfiguration) to create a `GoogleDaiTypedSource` to request stream, as demonstrated below:

```kotlin
theoplayerView.player.source = SourceDescription.Builder(
    GoogleDaiTypedSource.Builder(
        GoogleDaiVodConfiguration.Builder("api_key", "content_source_id", "video_id")
            .build()
    )
    .type(SourceType.DASH)
    .build()
).build()
```

or:

```kotlin
theoplayerView.player.source = SourceDescription.Builder(
    GoogleDaiTypedSource.Builder(
        GoogleDaiLiveConfiguration.Builder("api_key", "asset_key")
            .build()
    )
    .type(SourceType.DASH)
    .build()
).build()
```

## Notes

The Google DAI integration exposes events through the Ads API. More information is available at [How to subscribe to ad events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/subscribe-to-ad-events.md).

The integration exposes a number of additional methods. These are available directly on the [`GoogleDaiIntegration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/dai/GoogleDaiIntegration) object, or indirectly through `player.ads.dai` (only for Kotlin). For example:

* [requestStream(StreamRequest, AdsRenderingSettings)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/dai/GoogleDaiIntegration#requestStream\(StreamRequest,AdsRenderingSettings\)) can be used to request stream through the native Google DAI API.
* [contentTimeForStreamTime(double)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/dai/GoogleDaiIntegration#contentTimeForStreamTime\(double\)) / [streamTimeForContentTime(double)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/dai/GoogleDaiIntegration#streamTimeForContentTime\(double\)) can be used to convert content time to stream time and vice versa.

## Resources

* [Google DAI website](https://developers.google.com/interactive-media-ads)
* [Google DAI Android Reference](https://developers.google.com/interactive-media-ads/docs/sdks/android/dai)

---

# Prebid.js on Android

This article explains how you can connect THEOplayer with Prebid.js. Prebid.js is an open-source header bidding solution. On the client-side, you can request bids from multiple ad networks, take a winning bid and select its associated advertisement. You want to configure and play this selected advertisement in THEOplayer.

Because Prebid.js is a separate library, you can connect it with THEOplayer on any platform that supports both Prebid.js and THEOplayer.

Prebid.js allows you to request bids. This request will respond with bids through a callback function. In this callback function, you have to select a winning bid and extract the ad tag URL. You can configure this URL as THEOplayer's ad source.

## Code example

Refer to <https://docs.prebid.org/prebid-mobile/pbm-api/android/code-integration-android.html> to integrate Prebid on the Android SDK. The same THEOplayer API to configure advertisements is available on the Android SDK, as explained in [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/set-up-vast-and-vmap.md).

## Resources

* [What is Prebid?](https://prebid.org/product-suite/prebidjs/)
* [Prebid.js documentation](https://docs.prebid.org/)
* [Prebid.js on GitHub](https://github.com/prebid/Prebid.js)

---

# Google IMA on Android

THEOplayer offers support for Google IMA as an ad integration system. Users of Google Ad Manager (formerly known as DoubleClick for Publishers) should use this ad integration.

To schedule and track ads through Google IMA, you need to include the Google IMA SDK and indicate through the API that you want to use Google IMA as the ad integration.

Using Google IMA in the Android SDK consists of 3 steps:

1. Add the `integration-ads-ima` dependency to your module's `build.gradle`.
2. Use the `GoogleImaIntegrationFactory` to create and add a `GoogleImaIntegration`.
3. Use a `GoogleImaAdDescription` to schedule ads.

## Add the `integration-ads-ima` dependency

Add `implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-ima:+'` to your module `build.gradle` file, as demonstrated below:

```groovy
android {
    // ...
    compileOptions {
        // Required by IMA SDK v3.37.0+
        coreLibraryDesugaringEnabled = true
    }
}

dependencies {
    // ...

    implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
    implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-ima:+'

    // Required by IMA SDK v3.37.0+
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5'

    // ...
}
```

## Use the `GoogleImaIntegrationFactory`

> **Tip**
>
> If you're using [automatic integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/features.md#adding-integrations-automatically), you can skip this step.

Create a `GoogleImaIntegration` through the `GoogleImaIntegrationFactory`, and add it to your player instance, as demonstrated below:

```kotlin
import com.theoplayer.android.api.ads.ima.GoogleImaIntegrationFactory

val theoplayerView = THEOplayerView(context)
val imaIntegration = GoogleImaIntegrationFactory.createGoogleImaIntegration(theoplayerView)
theoplayerView.player.addIntegration(imaIntegration)
```

## Use a `GoogleImaAdDescription`

Use a [`GoogleImaAdDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/source/addescription/GoogleImaAdDescription) to schedule advertisements, as demonstrated below:

```kotlin
val typedSource = TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8")
    .build()

val imaAdDescription = GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
    .timeOffset("start")
    .build()

val sourceDescription = SourceDescription.Builder(typedSource)
    .ads(imaAdDescription)
    .build()

theoplayerView.player.source = sourceDescription
```

More information on scheduling ads is available at [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/set-up-vast-and-vmap.md).

## Next steps

The Google IMA integration exposes events through the Ads API. More information is available at [How to subscribe to ad events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/subscribe-to-ad-events.md).

The integration exposes a number of additional methods. These are available directly on the [`GoogleImaIntegration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/ima/GoogleImaIntegration) object, or indirectly through `player.ads.ima` (only for Kotlin). For example, [`schedule()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/ima/GoogleImaIntegration#schedule\(GoogleImaAdDescription\)) can be used to schedule ads dynamically, and [`requestAds()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/ima/GoogleImaIntegration#requestAds\(AdsRequest,AdsRenderingSettings\)) can be used to request ads through the native Google IMA API.

## Updating the Google IMA SDK

The IMA integration depends on Google's [IMA SDK for Android](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/) from [Maven](https://mvnrepository.com/artifact/com.google.ads.interactivemedia.v3/interactivemedia). By adding the THEOplayer IMA integration to your Gradle dependencies, the Google IMA SDK is also automatically added to your app.

Our integration is tested with a specific version of the Google IMA SDK, and by default Gradle will automatically add the same version to your app. However, you can overwrite this [with a later version](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/history) (at your own risk) by manually adding a dependency on `com.google.ads.interactivemedia.v3:interactivemedia` to your `build.gradle`.

[Starting with IMA SDK version 3.37.0](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/history), `coreLibraryDesugaring` must be enabled in your app. Without this, your app will not build. See the [Android documentation](https://developer.android.com/studio/write/java8-support#library-desugaring) for instructions on how to enable it.

## Remarks

* The release notes for the IMA SDK can be found on the [IMA Android SDK release history](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/history) page.
* THEOplayer internally supports IMA SDK up until a certain version across different SDKs. We regularly update the internal code to stay up to date with the latest version of IMA SDK. Later versions of IMA SDK should work as expected, however there could be cases where a fix for a breaking change or a newly introduced API is required. Please reach out to us if you require support for a more recent IMA SDK since we intend to rectify this limitation.
* The limitations documented on the support and compatibility pages of the IMA SDK also apply to THEOplayer when the IMA integration is used. You can find the [support matrix of the IMA Android SDK](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/compatibility) on their website.
* You can try out the snippets mentioned here on our [samples app for Android SDK](https://github.com/THEOplayer/samples-android-sdk/).

---

# How to subscribe to ad events on Android

When building a custom UI, or when logging events to an analytics service, app developers often need to be able to listen (and react) to ad events. For example, if an ad break starts, they want to draw a countdown on top of their UI. Alternatively, when an ad error occurs, they want to log this to an analytics server.

This article explains how you can programmatically subscribe to ad-related events.

## Subscribing to an event

This subsection explains how you detect ad-related events. The other subsections zoom in on particular use-cases, such as detecting the beginning and end of an ad.

If you are scheduling [client-side advertisements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/set-up-vast-and-vmap.md), then you use the `Ads` interface to detect ad events.

The `Player` API exposes an [`getAds()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#getAds--) method which belongs to the [`Ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/Ads) interface. Because this `Ads` interface inherits from [`EventDispatcher<AdEvent>`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/ads/AdEvent), you can leverage event listeners in this interface.

The Android SDK currently only allows client-side ad playback through [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/google-ima.md). The available events are documented in [`GoogleImaAdEventType`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/ima/GoogleImaAdEventType).

To subscribe to an event, you select an appropriate `GoogleImaAdEventType` or `AdsEventType`, use the `Ads` interface, call the `addEventListener` method, and set the event as the first parameter, and the callback as the second parameter.

For example, if you want to track the start of an ad break, you could use the following snippet:

```kotlin
theoPlayer.ads.addEventListener(GoogleImaAdEventType.AD_BREAK_STARTED) {
    Log.d("ADS", "AD_BREAK_STARTED")
}
```

## Ad begin and end

Detecting the start and stop of ad breaks and individual ad pods is a common requirement.

This use-case is an application of [Subscribing to an event](#subscribing-to-an-event), and relates to the following events:

* `STARTED`
* `AD_BREAK_STARTED`
* `AD_PERIOD_STARTED`
* `AD_BREAK_ENDED`
* `AD_PERIOD_ENDED`
* `COMPLETED`
* `ALL_ADS_COMPLETED`

```kotlin
theoPlayer.ads.addEventListener(GoogleImaAdEventType.AD_BREAK_STARTED) {
    Log.d("ADS", "AD_BREAK_STARTED")
}
```

## Ad error

Ad error events might be triggered when an ad blocker is active, or when an "empty" ad is returned. As an app developer, you might want to detect and possibly react to this.

This use-case is an application of [Subscribing to an event](#subscribing-to-an-event), specifically the `AD_ERROR` event.

The following snippet would trigger the callback when an ad error occurs:

```kotlin
theoPlayer.ads.addEventListener(GoogleImaAdEventType.AD_ERROR) {
    Log.d("ADS", "AD_ERROR")
}
```

## Server-side ads

If you're scheduling server-side ads, you might need to use a different interface than the `Ads` interface which you use when scheduling client-side ads.

* [Google DAI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/google-dai.md): if you're using Google DAI, you can use the same API as the one for client-side ads, as described in the sections above.
* [Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/yospace.md): if you're using Yospace, you must use the Yospace interface. You can read more about detecting ad-related events with Yospace at our [Yospace documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/yospace.md).

If you're building a [custom server-side ad insertion solution](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/custom-ssai-integration.md), you might be interested in using our `TextTrack` API to detect `id3/emsg/EventStream/EXT-X-DATERANGE` cues, and the `timeupdate` event in the `Player` interface to determine the current playhead position.

## Resources

* More samples are available on our GitHub repository for the [Android SDK](https://github.com/THEOplayer/samples-android-sdk).
* [THEOplayer advertisement tester](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/advertisement-tester.md)

---

# MediaTailor on Android

[AWS Elemental MediaTailor](https://docs.aws.amazon.com/mediatailor/index.html) is a service that provides scalable ad insertion and channel assembly. It is able to serve targeted ad content to viewers and create linear streams while maintaining broadcast quality in over-the-top (OTT) video applications. It supports HLS and DASH for both VOD and live workflows.

At the moment of writing only linear ads are supported, but it is possible to expand it to non-linear and companion ads as well.

## Configuration

To use a MediaTailor stream with THEOplayer on Android SDK, first import our MediaTailor module dependency in your `build.gradle` file.

```groovy
implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-mediatailor:+' // add MediaTailor dependency
```

Then, add the MediaTailor integration to the `Player`.

> **Tip**
>
> If you're using [automatic integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/features.md#adding-integrations-automatically), you can skip this step.

```kotlin
val theoplayerView = THEOplayerView(context)
val mediaTailorIntegration = MediaTailorIntegrationFactory.createMediaTailorIntegration(theoPlayerView);
theoplayerView.player.addIntegration(mediaTailorIntegration)
```

Finally, set a [`MediaTailorSource`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/source/mediatailor/MediaTailorSource) to play.

```kotlin
val mediaTailorSource = MediaTailorSource(src = "<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>")

theoplayerView.player.source = SourceDescription(listOf(mediaTailorSource))

// or using the Builder pattern

val mediaTailorSource = MediaTailorSource
    .Builder("<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>")
    .build()

theoplayerView.player.source = SourceDescription
    .Builder(mediaTailorSource)
    .build()
```

Optionally, you can pass parameters regarding e.g. session data and device type by using the `adsParams` property, as described in the [MediaTailor documentation](https://docs.aws.amazon.com/mediatailor/latest/ug/ad-reporting-client-side.html#ad-reporting-client-side-enabling).

```kotlin
val adsParams = emptyMap<String, String>().toMutableMap()
adsParams["param1"] = "value1"
adsParams["param2"] = "value 2"
val mediaTailorSource = MediaTailorSource(
    src = "<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>",
    adParams = adsParams    // Note the deprecated parameter name
)

// or using the Builder pattern

val mediaTailorSource = MediaTailorSource
    .Builder("<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>")
    .adsParams(adsParams)
    .build()
```

> **Deprecated**
>
> The source definition currently still uses the deprecated `adParams` property. This will be replaced by the `adsParams` property in a future version.

---

# Custom Server Side Ad Insertion on Android

THEOplayer provides a way to integrate with third-party advertisement providers, and have them report their ads and ad-related events through the THEOplayer APIs.

## Integration ID

To make use of the custom server side ad insertion, first you need an integration ID which will identify the provided sources and ads to the specific ad provider.

## ServerSideAdIntegrationFactory

You would also need to register a `ServerSideAdIntegrationFactory` that will receive a `ServerSideAdIntegrationController`. The controller can be used to create the THEOplayer `AdBreak`/`Ad` objects using the `AdBreakInit`/`AdInit` data. Additionally, it can be used to keep the player's state up-to-date such as when an ad begins or ends.

The `ServerSideAdIntegrationFactory` requires an implementation of the `ServerSideAdIntegrationHandler` interface. The handler will provide few callbacks that can be overridden which allows you to setup and clear the integration as needed.

A concrete implementation can be found [in the Yospace Connector](https://github.com/THEOplayer/android-connector/blob/master/connectors/yospace/src/main/java/com/theoplayer/android/connector/yospace/internal/YospaceAdIntegration.kt).

Meanwhile, an empty implementation would look like below. Details to follow.

```kotlin
player.ads.registerServerSideIntegration("integrationID") { controller ->
    object : ServerSideAdIntegrationHandler {

        override suspend fun setSource(source: SourceDescription): SourceDescription {
            return super.setSource(source)
        }

        override fun skipAd(ad: Ad) {
            super.skipAd(ad)
        }

        override suspend fun resetSource() {
            super.resetSource()
        }

        override suspend fun destroy() {
            super.destroy()
        }
    }
}
```

### Setting a Source

When a new source is loaded into the player the `setSource(source: SourceDescription)` callback is triggered. It allows the integration to transform the source description, e.g. by calling an external service to replace the content URL (`TypedSource.src`), or by adding a fixed pre-roll linear ad to the list of ads (`SourceDescription.ads`).

### Skipping an Ad

When an ad is requested to be skipped, the `skipAd(ad: Ad)` is called. At this point the controller should call its own `skipAd()` method.

### Resetting a Source

Before a new source is loaded into the player, or before the player is destroyed, `resetSource()` is triggered. This allows the integration to clean up any source-specific resources, such as scheduled ads or pending HTTP requests.

### Destroying the player

When the player is destroyed, the `destroy()` is called. This allows the integration to clean up any resources, such as UI views or event listeners.

### Creating Ad objects

When the advertisement provider reports an ad, an `AdBreak` and an `Ad` object should be created using `createAdBreak(props: AdBreakInit)` and `createAd(props: AdInit, adBreak: AdBreak?)` methods respectively from the controller. For example, for a preroll `AdBreak` containing 2 advertisements it would be:

```kotlin
val adBreak = controller.createAdBreak(AdBreakInit(timeOffset = 0))

val firstAdInit = AdInit(
    type = "linear",
    skipOffset = 5,
    id = "first_ad_id",
    duration = 10,
    clickThrough = first_ad_click_through_url,
    resourceURI = first_ad_resource_url
)
val firstAd = controller.createAd(firstAdInit, adBreak)

val secondAdInit = AdInit(
    type = "linear",
    skipOffset = 5,
    id = "second_ad_id",
    duration = 10,
    clickThrough = second_ad_click_through_url,
    resourceURI = second_ad_resource_url
)
val secondAd = controller.createAd(secondAdInit, adBreak)
```

### Playing an Ad

When an Ad begins the playback, the controller must inform the player by calling `beginAd(ad: Ad)`, this will trigger the relevant AdBreak and Ad events.

Additionally, during the playback of the Ad, calling `updateAdProgress(ad: Ad, progress: Double)` is needed to keep the player in sync with the progress.

Finally, when the playback of the Ad is completed, `endAd(ad: Ad)` should be called to notify about it.

## CustomSsaiDescriptionSerializer

To hold the configuration parameters specific to your integration, you can create a new class that inherits from [`CustomSsaiDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/source/ssai/CustomSsaiDescription). This allows it to be set on a `TypedSource` through [`TypedSource.Builder.ssai()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/source/TypedSource.Builder#ssai\(com.theoplayer.android.api.source.ssai.SsaiDescription\)). Then, register a `CustomSsaiDescriptionSerializer` using the integration ID and provide a way to serialize/deserialize the new `CustomSsaiDescription`.

Below is an example of a [YoSpace integration](https://github.com/THEOplayer/android-connector/tree/master/connectors/yospace) showing `YospaceSsaiDescription` extending `CustomSsaiDescription`:

```kotlin
data class YospaceSsaiDescription constructor(
    /**
     * The type of the requested stream.
     *
     * Default: [YospaceStreamType.LIVE]
     */
    val streamType: YospaceStreamType = YospaceStreamType.LIVE,
    /**
     * Custom properties to set when initializing the Yospace session.
     */
    val sessionProperties: Session.SessionProperties = Session.SessionProperties()
) : CustomSsaiDescription() {
    override val customIntegration = YospaceConnector.INTEGRATION_ID
}
```

And then, the implementation of the `CustomSsaiDescriptionSerializer` specific for YoSpace:

```kotlin
class YospaceSsaiDescriptionSerializer : CustomSsaiDescriptionSerializer {
    override fun fromJson(json: String): YospaceSsaiDescription {
        return Json.decodeFromString(json)
    }

    override fun toJson(value: CustomSsaiDescription): String {
        return Json.encodeToString(value)
    }
}
```

Finally, registering the `YospaceSsaiDescriptionSerializer`:

```kotlin
CustomSsaiDescriptionRegistry.register(YospaceConnector.INTEGRATION_ID, YospaceSsaiDescriptionSerializer())
```

> **Note**
>
> Registering the `CustomSsaiDescriptionSerializer` should happen before registering the `ServerSideAdIntegrationFactory`.

---

# Analytics on Android

Video analytics offer all sorts of insights, ranging from the behavior of your viewers, to the performance of your video players.

There are different approaches to collect these insights.

* You can use a commercial video analytics vendor (e.g. Conviva, Mux, Wicket Labs, Youbora, ...).
* You can implement a custom analytics service that you created.
* You can leverage back-end and CDN logs.

Insights are deducted from metrics. Metrics are calculated from raw video data. For example,

1. INSIGHT: "the videos on my website start faster than the industry average (e.g. 4.71s)"
2. METRIC: "because the average video startup time was 1.7s on my website last month"
3. DATA: "that I calculated by measuring the video startup time of 1 million unique video sessions on my website"

The online video streaming industry often talks about Quality of Service (QoS) and Quality of Experience (QoE). When talking about metrics, you'll often hear terms like Startup Time, Buffer Rate, Error Rate, Seek Time, Exit Before Video Start. When talking about raw data, you might hear terms like heartbeat (or ping) events, buffer events, play events, seek events and error events.

## Analytics and video players

As an application developer, you want your video player to expose an API that allows you to track video events and query video states. With this API, a developer can implement an integration with a commercial analytics service, or implement a connection with their custom analytics service.

With a video player, you want to be able to access the raw video data. A video player typically doesn't calculate metrics or insights, because it doesn't have access to historical data.

As an app developer,

1. you want to track raw video data with the assistance of your video player API,
2. do some (optional) processing at runtime,
3. and forward the (processed) data to a remote analytics service.

Then, someone on the back-end, 4. would manage & manipulate this data on this remote analytics service, 5. to convert this raw data into metrics, and the metrics into insights.

## Integrations

THEOplayer *should* be compatible with any industry-standard commercial or custom analytics service. The THEOplayer API gives application developers access to a vast number of video events.

As an app developer, you have the option to leverage one of our existing integrations with commercial analytics services, or the option to create a custom integration.

The following commercial video analytics integrations are documented. These articles explain how to leverage an out-of-the-box integration, or how to implement a connector, or how to achieve a custom implementation with a specific vendor.

* [Mux](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/mux.md)
* [Youbora](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/youbora.md)
* [Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/conviva.md)
* [Adobe Analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/adobe-analytics.md)
* [MediaMelon SmartSight](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/mediamelon-smartsight.md)
* [Wicket Labs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/wicket-labs.md)
* [Google Analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/custom-analytics-integration.md#integrating-google-analytics)
* [Tealium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/tealium.md)
* [Segment](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/segment.md)
* [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/comscore.md)
* [Nielsen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/nielsen.md)

A connector is an open-source integration that is listed on our GitHub at <https://github.com/THEOplayer>. There might be connectors on our GitHub that are missing from the list above.

Alternatively, if you are not able to locate documentation on a specific vendor, then reach out to this vendor, because they might be the maintainer of an integration related to THEOplayer.

## Creating a custom analytics integration

Head over to [Custom Analytics Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/custom-analytics-integration.md) if you want to learn more about creating your own analytics integration using the THEOplayer API.

## THEOplayer Analytics Dashboard

If you've used the THEOplayer Developer Portal - for example to create a THEOplayer SDK -, then you might have noticed that there is an analytics dashboard at <https://portal.theoplayer.com>.

This analytics dashboard is located in the "Usage" tab of your Portal account. The dashboard should resemble the screenshot below.

![THEOplayer Portal Analytics Dashboard](/pr-932/assets/images/analytics-introduction-portal-dashboard-777c17a7b2bbf13b27a40bfdc3a4d1f9.png "THEOplayer Portal Analytics Dashboard")

This dashboard allows you to track your [impressions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-is-an-impression.md) across different periods of times across different SDKs.

We don't *really* consider this dashboard as a "video analytics service". The primary purpose of this dashboard is for you to monitor your impressions, as the impressions might be related to your THEOplayer pricing model. That being said, it is a useful dashboard, as it visualizes the consumption of your videos throughout time.

---

# Mux on Android

[Mux /data](https://mux.com/data/) is a video analytics service. Mux is currently the maintainer of the Mux-THEOplayer integration. Their documentation describes how to connect Mux to THEOplayer for each of the THEOplayer SDKs.

## Connecting Mux to THEOplayer

Mux is currently the maintainer of the Mux-THEOplayer integration for Android. Their documentation for the THEOplayer Android SDK is located at <https://docs.mux.com/guides/data/monitor-theoplayer-android>.

If you choose to [build a custom integration](https://docs.mux.com/guides/data/build-a-custom-integration), the following article from Mux describes how you can achieve this:

* Java: <https://docs.mux.com/guides/data/custom-java-integration>

---

# Youbora (NPAW Plugin) on Android

Youbora adapter (NPAW plugin) for THEOplayer is maintained by the NPAW team and regularly kept up to date to make sure it is compatible with the latest THEOplayer version.

In order to access the links on this guide, you may need to login with your NPAW developer account.

Before you get started, for general information on NPAW plugin, please refer to [this guide](https://documentation.npaw.com/integration-docs/docs/first-steps).

## Connecting Youbora to THEOplayer

For general information on NPAW plugin for Android (TV) and how to set it up, please refer to [this guide](https://documentation.npaw.com/integration-docs/docs/android-integration-guide).

For integration with THEOplayer Android SDK, please reach out to the NPAW team to get the latest resources.

## Related articles

* [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/set-up-vast-and-vmap.md)

---

# Conviva on Android

Conviva is an analytics service. THEOplayer offers a connector which can be initialized depending upon the customer requirements for measuring all the solutions offered by Conviva (Video Analytics & Ads Analytics).

The Conviva connector has full support for Video and Ad Analytics offered by Conviva. It is built using all public APIs of THEOplayer and Conviva, so it can be maintained and managed across teams, and any new updates or changes can easily be modified and customized as per customer requirements. (There is no dependency on the THEOplayer or Conviva library version.)

## Usage

You need to set up [THEOplayer Conviva Connector for Android](https://github.com/THEOplayer/android-connector/tree/master/connectors/analytics/conviva). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/conviva) section to learn all about how to integrate and use the Conviva connector on Android SDK.

## Resources

* Demo page: [Conviva Analytics Test Page](https://cdn.theoplayer.com/conviva/conviva_test.html)
* [Conviva SDK Documentation](https://cdn.theoplayer.com/conviva/Conviva_Documentation_4.0.14/index.html)
* More Information about [Conviva Video Experience](https://www.conviva.com/experience-insights/)
* More Information about [Conviva Ad Insights](https://www.conviva.com/ad-insights/)

---

# Custom Analytics Integration on Android

Video analytics provide tremendous insights into your user's QoE, bring extra business intelligence and enhance decision-making. There are a wide selection of analytics systems in the current landscape (e.g. Google Analytics, Conviva, ...), often with their own focus, expertise and value.

What most video analytics systems have in common is that their insights (partly) originate from video events:

* `play` event: a user clicks the play button, or resumes playback after a pause
* `fullscreen` event: a user goes fullscreen on their device
* `quality` change event: the video quality switches from a lower resolution to a higher one
* `waiting` event: the video is stalled and unable to continue playback for some time
* ...

To access these video events, and forward them to a video analytics system, an application developer must hook into the video player API.

This guide explains the role of the THEOplayer API. Additionally, it explains how to do a custom integration with an analytics system, with Google Analytics as a sample case. This guide should be useful when THEOplayer doesn't have an existing sample integration with a specific (commercial) video analytics service, or when you want to fully control the data flow.

Keep in mind that Google Analytics is not the only analytics system out there. The APIs and concepts that we'll discuss are relevant for all analytics systems. For example, you can easily swap out the Google Analytics example with something like [Nielsen](https://www.nielsen.com/solutions/audience-measurement/) or [Youbora](https://npaw.com/) (NPAW), or even your own custom analytics back-end.

## Prerequisites

There are two prerequisites in order to continue with this guide:

1. You have a THEOplayer license. You can grab a license at <https://portal.theoplayer.com>.
2. You have some basic knowledge on how to use THEOplayer, and can navigate comfortably through [the API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android) to find relevant events.

Refer to our [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/getting-started.md) before advancing to the code samples.

## API

You can access the video data through the THEOplayer API. Through the API, you can subscribe to events, and attach a callback. For example, when the `ended` event is triggered (meaning: someone completely watched the video), your callback could be that when this happens, you do a request to a remote video analytics service.

Events are organized across interfaces and subinterfaces, as illustrated by the image below. For example, the player contains general video player events like `play`, `pause` and `ended`. The ads interface contains events related to advertisements, like `adbreakbegin` and `adend`.

![THEOplayer API Interfaces and Events](/pr-932/assets/images/analytics-events-185d6ab52b556af08d8300b545ae5876.png "THEOplayer API Interfaces and Events")

When creating a custom analytics implementation, you must familiarize yourself with the relevant interfaces and events. Below is an (incomplete) list of some common interfaces and their event maps.

* [Player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/player/PlayerEventTypes): general video events, like a play, a pause, and so on.
* [Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/ads/AdsEventTypes): to detect when an ad starts and stops.
* [AudioTrackList](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/mediatrack/audio/list/AudioTrackListEventTypes): to detect when a new audio track is added, or when another audio track becomes active.
* [VideoTrack](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/mediatrack/video/VideoTrackEventTypes): to detect when another video quality becomes active.
* [TextTrackList](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/texttrack/list/TextTrackListEventTypes): comparable to AudioTrackList, but for subtitles, closed captions and metadata (e.g. id3, emsg, EventStream, EXT-X-DATERANGE).
* [Cast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/chromecast/package-summary): to detect events related to Chromecast.

Note that maintaining the above list manually is unfortunately a no-go because our interfaces evolve. This means that you should research your events through our [API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android).

When doing a custom analytics integration, you should also check our articles on [error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/error/introduction.md).

### Video analytics metrics and events

Let's discuss some popular metrics, and how you could track them with video player events.

Plays (or Impressions). This metric represents the amount of plays. You can calculate this event by identifying the first `playing` event after every `sourcechange` event.

Video Startup Time (or Time-to-First-Frame or Join Latency). This metric represents the time it takes your video to start. You can calculate this event by calculating the difference between the timestamps of the first `playing` and the first `play` event after every `sourcechange` event.

Seek Time (or Seek Latency). This metric represents the time it takes for your video to resume when you scrub to another position. You can calculate this event by calculating the difference between the timestamps of the `seeking` and the `seeked` event.

Watch Time. This metric represents how much time is spent watching content by your viewers. You calculate this value by tracking the `playing` event, and halting it when the `waiting`, `pause`, `ended` or `error` event occurs.

Rebuffer Ratio (or Stalls). This metric represents how often the viewer is watching the "spinner icon" versus the actual video. This metric is closely related to the Watch Time. You can calculate this event by tracking the `waiting` event, which is triggered when the video starts to stall, and the `playing` event.

Average Bitrate. This metric represents the average video quality that your viewers are watching. You can calculate this metric by tracking the `activequalitychanged` event of the active video track.

Average % Complete (or Watched Ratio). This metric represents the relative completion rate of your videos. This metric is related to the Watch Time, and related in a similar fashion. You could also use the player's `duration` to determine the length of the asset.

Exit Before Video Start. This metric represents how often your viewers aren't able to start the video, even though they had the intent to watch it. You can calculate this metric by tracking the first `play` event, and it never getting to the `playing` event.

Video Playback Failure. This metric represents how often your viewers have a problem with playback once a video starts. You can calculate this metric by tracking the `error` event after the first `playing` event.

Note that these proposed calculations are only loosely formulated to help you understand the relationship between video metrics and a video player API.

When talking about metrics, you often apply dimensions or filters to a metric. For example, when talking about the "Plays" metric (see above), the base metric would apply to all logs throughout all time. When analyzing your data, you might want to apply a filter (or dimension), such time (to consider all "Plays" for a specific period of time), asset (to research a specific asset), user (to check a specific user's activity), and so on. It is up to you (or your commercial analytics service) to associate certain dimensions with a raw video player event.

### Session management

It's important to note that THEOplayer doesn't associate a user ID or session ID with an event. (This is pretty normal, because THEOplayer is a client-side video player library. It's not aware of your "back-end" "CMS", "users" or "sessions".)

When you are implementing an analytics service, you usually want to associate a session or user with an event when forwarding the event to your remote analytics database. As an app developer, it is your responsibility to do this association.

## Integrating Google Analytics

Refer to Google Analytics' documentation at <https://developers.google.com/analytics/solutions/mobile> if you're interested in integrating Google Analytics. Similar to the Web SDK, developers would subscribe to events and properties emitted by THEOplayer and create a custom mapping to the Google Analytics library.

## Conclusion

A custom analytics integration gives you full control over your code, and the data you want to submit to your analytics system. This data is exposed through the THEOplayer API, and allows you to subscribe to events such as the start of an ad, or a direction change event in 360/VR playback.

Extra resources:

1. [THEOplayer API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android)
2. [THEOplayer Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/getting-started.md)

---

# Adobe Analytics on Android

[Adobe Streaming Media Collection Add-on](https://experienceleague.adobe.com/en/docs/media-analytics/using/media-overview) is a video analytics service, and is part of [Adobe Experience Cloud](https://business.adobe.com/products/analytics/adobe-analytics.html).

This product was formerly known as "Adobe Heartbeat".

Adobe Streaming Media Collection Add-on or older iterations of this product can be implemented on top of THEOplayer as a custom analytics integration.

Refer to the article on [building a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/custom-analytics-integration.md) for more information on how to build an integration on top of THEOplayer.

## Connecting Adobe Analytics to THEOplayer

You can use the [Adobe Experience Platform (AEP) Mobile SDKs](https://experienceleague.adobe.com/en/docs/media-analytics/using/implementation/analytics-only/media-sdk/mobile-implementation) for iOS and Android to integrate Adobe Analytics, as the Media Analytics SDK for Android has been [deprecated since 31 August 2021](https://experienceleague.adobe.com/en/docs/media-analytics/using/getting-started/end-of-support/end-of-support-faqs).

The Media API reference is available [here](https://developer.adobe.com/client-sdks/solution/adobe-media-analytics/api-reference/).

Alternatively, you can consider using the [RESTful Media Collection API](https://experienceleague.adobe.com/en/docs/media-analytics/using/implementation/analytics-only/streaming-media-apis/mc-api-overview).

For more information about how to use Adobe Analytics on other platforms, please refer to the [Adobe Streaming Media Collection Add-on overview](https://experienceleague.adobe.com/en/docs/media-analytics/using/media-overview).

---

# MediaMelon SmartSight on Android

MediaMelon SmartSight is an analytics service maintained by MediaMelon. The library is maintained by the MediaMelon team.

## Prerequisites

1. A valid THEOplayer license.
2. A MediaMelon SDK.
3. A MediaMelon Customer ID (**Note:** If you do not know your Customer ID contact MediaMelon at <support@mediamelon.com>.

## Connecting MediaMelon to THEOplayer

For the most up to date information on how to integrate MediaMelon SmartSight with THEOplayer Android (TV) SDK, please refer to their integration guide [here](https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/android) where you can find step by step guidance as well as code examples.

---

# Wicket Labs on Android

[Wicket Labs](https://www.wicketlabs.com/) is an audience insights platform for video, and offers products like the "[Wicket Scoreboard](https://www.wicketlabs.com/wicket-scorecard/)".

To generate these insights, a video player emits playback events to a third-party database service (e.g. Firebase). Wicket Labs provides [guidelines](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/) on how to format these playback events. Wicket Labs then pulls the data from the selected third-party database service, and integrates it into their platform.

## Connecting Wicket Labs with THEOplayer

An integration with Wicket Labs can be integrated on top of THEOplayer.

1. As a customer of Wicket Labs, you need to verify that Wicket Labs can ingest data from your selected database solution (e.g. Firebase). *(It should be noted that Wicket Labs does not provide its own database service to store playback events. Instead, Wicket Labs plugs into your database service.)*
2. As a customer of Wicket Labs and THEOplayer, you need to emit the playback events ([as defined per Wicket Labs](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/)) to your database service. In other words, you need to hook into certain events emitted by THEOplayer, reformat them, and re-emit them to your database service.

* To facilitate the implementation of Wicket Labs \[related to THEOplayer], Wicket Labs and THEOplayer collaborate on publicly available code samples. These code samples are published as Git repositories on <https://github.com/THEOplayer>.
* Developers are free to do their custom integration of Wicket Labs and THEOplayer, or may modify the publicly available code samples.
  * Wicket Labs' article on [How to Setup Firebase for OTT Video Services](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/) is a great starting point if you're interested in customizing.

- Our article on [Custom Analytics Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/custom-analytics-integration.md) may help developers out.

THEOplayer and Wicket Labs currently do not host a sample implementation for Android-based platforms on GitHub.

Developers are encouraged to use our [sample implementation for the Web SDK](https://github.com/THEOplayer/samples-wicket-labs-html5-sdk) as a reference for the order and format of the playback events, together with Wicket Labs' [guidelines on setting up Firebase](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/), as a starting point. Additionally, developers are encouraged to reach out to their contacts at THEOplayer and/or Wicket Labs if they need assistance, which could prompt THEOplayer and Wicket Labs into publishing a sample implementation on GitHub.

## Related links

* wicketlabs.com: [How to Setup Firebase for OTT Video Services](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/)

---

# Tealium on Android

Tealium is a [tag management system](https://tealium.com/resource/fundamentals/what-is-tag-management/) and offers [integrations](https://tealium.com/integrations/) with [Google Analytics](https://tealium.com/integrations/google-analytics/), [Adobe Analytics](https://tealium.com/integrations/adobe-analytics/), and others.

Tealium can be implemented on top of THEOplayer as a custom analytics integration.

Refer to the article on [building a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/custom-analytics-integration.md) for more information on how to build an integration on top of THEOplayer.

## Connecting Tealium to THEOplayer

The Tealium documentation includes articles that describe:

* How to install Tealium [for Java](https://docs.tealium.com/platforms/android-java/install/) or [for Kotlin](https://docs.tealium.com/platforms/android-kotlin/install/).
* How to implement tracking [for Java](https://docs.tealium.com/platforms/android-java/track/) or [for Kotlin](https://docs.tealium.com/platforms/android-kotlin/install/).
* [Basic video tracking](https://docs.tealium.com/platforms/getting-started-web/data-layer/definitions/basic-video-tracking/) on the data layer.
* [An introduction to the Data Layer](https://docs.tealium.com/platforms/getting-started-web/data-layer/an-introduction-to-the-data-layer/).

For other platforms, refer to the documentation at <https://docs.tealium.com/platforms/>.

---

# Segment on Android

Segment is a [Customer Data Platform](https://segment.com/docs/guides/), and offers [integrations](https://segment.com/docs/connections/destinations/catalog/index-all/) with [Google Analytics](https://segment.com/docs/connections/destinations/catalog/google-analytics/), [Adobe Analytics](https://segment.com/docs/connections/destinations/catalog/adobe-analytics/), [Youbora](https://segment.com/docs/connections/destinations/catalog/youbora/), and others.

Segment sets up "[Connections](https://segment.com/docs/connections/)" between "[Sources](https://segment.com/docs/connections/sources/)" and "[Destinations](https://segment.com/docs/connections/destinations/)".

* Sources send messages into Segment (and other tools). They have JavaScript source, an Android source, and so on.
* Destinations (like Google Analytics, Adobe Analytics, Youbora) receive messages from Segment.

Segment can be implemented on top of THEOplayer as a custom analytics integration.

Refer to the article on [building a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/analytics/custom-analytics-integration.md) for more information on how to build an integration on top of THEOplayer.

## Connecting Segment to THEOplayer

You'll (most likely) use the "[Analytics for Android SDK](https://segment.com/docs/connections/sources/catalog/libraries/mobile/android/)" source to get access to the Segment API.

Then, for each of your destinations, you want to figure out whether you can use the "Video Spec", or whether you need to do something specific for some destinations (e.g. [Youbora](https://segment.com/docs/connections/destinations/catalog/youbora/)).

Segment describes a "Video Spec" at <https://segment.com/docs/connections/spec/video/>, but this article also mentions that "not all destinations support video tracking and you should always check with the individual destination documentation to confirm".

For other platforms, refer to the documentation at <https://segment.com/docs/>.

---

# Comscore on Android

Comscore is an analytics service which provides audience measurement and content ratings. THEOplayer offers a connector which reports playback and ad events to the Comscore Streaming Tag.

## Usage

You need to set up [THEOplayer Comscore Connector for Android](https://github.com/THEOplayer/android-connector/tree/master/connectors/analytics/comscore). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/comscore) section to learn all about how to integrate and use the Comscore connector on Android SDK.

## Resources

* [Comscore website](https://www.comscore.com/)

---

# Nielsen on Android

Nielsen is an analytics service which provides audience measurement. THEOplayer offers a connector which reports playback and ad events to the Nielsen SDK.

## Usage

You need to set up [THEOplayer Nielsen Connector for Android](https://github.com/THEOplayer/android-connector/tree/master/connectors/analytics/nielsen). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/nielsen) section to learn all about how to integrate and use the Nielsen connector on Android SDK.

## Resources

* [Nielsen website](https://www.nielsen.com/solutions/audience-measurement/)

---

# Chromecast on Android

In this section you will learn everything about how THEOplayer works with Chromecast.

## API

As a developer, you might need to use the THEOplayer Chromecast API to build a custom Chromecast UI and UX, or to dispatch an event to an analytics service, or for workflow purposes.

For more information, see the API reference of [`Chromecast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/cast/chromecast/Chromecast), which is exposed on the [`Cast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/cast/Cast) interface.

Use the API as demonstrated below:

```kotlin
// Verify the Cast dependency is present in your build.gradle file.
// Add Cast Integration to the player.
val castIntegration = CastIntegrationFactory.createCastIntegration(theoPlayerView)
theoPlayerView.player.addIntegration(castIntegration)

// For actions you can use both the THEOplayerView and the CastIntegration object.
theoPlayerView.cast.chromecast.start()
// or
castIntegration.start()

// For listening to events nothing changed.
theoPlayerView.cast.chromecast.addEventListener(ChromecastEventTypes.STATECHANGE) { event ->
    // Handle the state change.
}
```

## Sender Applications vs Receiver Applications

When a viewer is streaming through a Chromecast device, they are actually casting content from a sender application (e.g. an Android application) to a receiver application. A sender application informs a physical Chromecast device which receiver application it should load through an application ID.

![Casting approaches](/pr-932/assets/images/casting-approaches-45dc2983f20d11409d27d3248b57a6ef.png "Casting approaches")

By specifying the application ID, you implicitly connect it with a type of receiver application. The following three types of receiver applications are common:

| Type                                    | Maintainer             | Info                                                                                                                                                                                                                        | Benefits                                                                                                                                                                                                      | Disadvantages                                                                                                                       |
| --------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Default THEOplayer Receiver Application | THEOplayer             | This is the default receiver application THEOplayer SDKs will connect with. The app ID of this default THEOplayer receiver application is `8E80B9CE`.                                                                       | You (i.e. the developer) do not need to do anything extra on the Chromecast receiver application side. You don't need to create a Chromecast receiver, you don't need to register it at, ... - it just works. | You are limited w\.r.t. customizing the UI and integrating custom logic.                                                            |
| Custom THEOplayer Receiver Application  | Developer + THEOplayer | This is a custom receiver application you can build, and where you integrate the [THEOplayer Chromecast SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md). | You (i.e. the developer) can adjust the look and feel, and integrate custom logic.                                                                                                                            | You need to create a Chromecast receiver, register it, maintain it, ...                                                             |
| Customer Receiver Application           | Developer              | This is a custom receiver application you can build, but without using the THEOplayer Chromecast SDK.                                                                                                                       | The THEOplayer Chromecast Receiver SDK is not a dependency.                                                                                                                                                   | You are responsible for building and maintaining the receiver application, and its connection with the various sender applications. |

If you have implemented THEOplayer in your sender application, you can [enable Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/enable-chromecast-on-the-sender.md). Furthermore, you can also [specify the application ID](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/enable-chromecast-on-the-sender.md#custom-receiver-app) in your sender application.

## Whitelisting Receiver Applications

Streaming services and products often require you to whitelist domain names to allow playback. When viewers are casting content to a Chromecast receiver application, your Chromecast device will actually stream the content on a domain name. In other words: CORS and whitelisting/blacklisting policies do apply to Chromecast sessions. Ensure that you've whitelisted the domain name which hosts your Chromecast receiver application. (You can look up the domain name of your receiver application at <https://cast.google.com/publish/#/overview>.)

If you're using the Default THEOplayer Receiver Application you may whitelist `https://d3ojqkc95d8mrd.cloudfront.net/`.

## Related articles

* [Connecting from custom Sender applications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/connecting-from-custom-sender-applications.md)
* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/how-to-configure-to-a-different-stream.md)
* [Sending messages from/to Sender to/from Receiver](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/sending-messages-from-to-sender-to-from-receiver.md)
* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)
* [Enable Chromecast on the Sender](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/enable-chromecast-on-the-sender.md)

---

# Connecting from custom Sender applications on Android

In general, the following flow should be followed:

1. Set up Google Cast context with correct receiver application ID.
2. Connect to Chromecast device.
3. Set up Google Cast MediaInfo object with correct contentID and contentType.
4. Send Google Cast LoadRequest with a serialized THEOplayer SourceDescription object as a key in the customData of the LoadRequest. So something like `{sourceDescription: ${SourceDescription you want to cast}}`.

## Usage

First, set up your `CastOptionsProvider`:

```kotlin
package com.yourcomp.chromecastSender

import android.content.Context
import com.google.android.gms.cast.framework.CastOptions
import com.google.android.gms.cast.framework.OptionsProvider
import com.google.android.gms.cast.framework.SessionProvider

class THEOCastOptionsProvider : OptionsProvider {

    override fun getCastOptions(context: Context): CastOptions =
        CastOptions.Builder()
            .setReceiverApplicationId(DEFAULT_APP_ID)
            .build()

    override fun getAdditionalSessionProviders(context: Context): List<SessionProvider>? = null

    companion object {
        const val DEFAULT_APP_ID = "8E80B9CE"
    }
}
```

And link to it in your `AndroidManifest.xml` file:

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.yourcomp.chromecastSenderApp">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />

    <application
    ...
        <meta-data
            android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
            android:value="com.yourcomp.chromecastSender.CastOptionsProvider" />
    </application>

</manifest>
```

Fill in the correct class name by replacing `com.yourcomp.chromecastSender.CastOptionsProvider`! You can change the `DEFAULT_APP_ID` to direct to your own Chromecast app. Next you can actually do the casting like the following:

```kotlin
package com.yourcomp.chromecastSender

import android.app.Activity
import androidx.mediarouter.app.MediaRouteChooserDialog
import com.google.android.gms.cast.MediaInfo
import com.google.android.gms.cast.MediaLoadOptions
import com.google.android.gms.cast.framework.CastContext
import com.google.android.gms.cast.framework.CastSession
import com.google.android.gms.cast.framework.SessionManagerListener
import org.json.JSONObject

private const val SOURCE_URL =
    "https://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/manifest(format=mpd-time-csf)"

class ChromecastSender {

    fun sendSourceToChromecast(context: Activity) {
        val castContext = CastContext.getSharedInstance(context)
        showCastChooserDialog(context, castContext)

        val sourceDescriptionJson = JSONObject(
            """
            {
              "sourceDescription": {
                "sources": [
                  {
                    "src": "$SOURCE_URL",
                    "type": "application/dash+xml",
                    "contentProtection": {
                      "widevine": {
                        "licenseAcquisitionURL": "https://amssamples.keydelivery.mediaservices.windows.net/Widevine/?KID=1ab45440-532c-4399-94dc-5c5ad9584bac"
                      }
                    }
                  }
                ]
              }
            }
            """.trimIndent()
        )
        val mediaLoadOptions = MediaLoadOptions.Builder().setCustomData(sourceDescriptionJson).build()
        val mediaInfo = MediaInfo.Builder(SOURCE_URL)
            .setContentType("application/dash+xml")
            .build()

        castContext.sessionManager.addSessionManagerListener(
            object : SessionManagerListener<CastSession> {
                override fun onSessionStarting(castSession: CastSession) {}

                override fun onSessionStarted(castSession: CastSession, sessionId: String) {
                    castSession.remoteMediaClient?.load(mediaInfo, mediaLoadOptions)
                }

                override fun onSessionStartFailed(castSession: CastSession, error: Int) {}

                override fun onSessionEnding(castSession: CastSession) {}

                override fun onSessionEnded(castSession: CastSession, error: Int) {}

                override fun onSessionResuming(castSession: CastSession, sessionId: String) {}

                override fun onSessionResumed(castSession: CastSession, wasSuspended: Boolean) {}

                override fun onSessionResumeFailed(castSession: CastSession, error: Int) {}

                override fun onSessionSuspended(castSession: CastSession, reason: Int) {}
            },
            CastSession::class.java
        )
    }

    private fun showCastChooserDialog(context: Activity, castContext: CastContext) {
        MediaRouteChooserDialog(context).apply {
            routeSelector = castContext.mergedSelector!!
        }.show()
    }
}
```

Instantiate this class and then connect to a device. This will start casting the source listed in the class to the Chromecast receiver.

## Related articles

* [How can we track the first play(ing) event?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/player/track-first-playing-event.md)

* [How to start with a specific quality?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/start-with-specific-quality.md)

* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)

* [How to know whether a live stream is playing?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-know-when-livestream-is-playing.md)

* [Getting started on Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md)

---

# How to configure a different stream to Chromecast on Android

Some streaming setups require you to cast a different stream to a Chromecast Receiver device than the one playing on a Chromecast Receiver device. For example, if you're playing HLS + FairPlay DRM on your iOS application, you need to cast a different source with DASH + Widevine DRM to your Chromecast application, because Chromecast applications aren't able to support FairPlay.

You can achieve this use case with the ChromecastConnection API.

## ChromecastConnection API

The ChromecastConnection API allows you to implement callbacks related to Chromecast playback. To achieve the described use case you can use the `onStart` (i.e. the start of a Chromecast session) to set a new stream, and `onStop` (i.e. the end of a Chromecast session) to (re)set your previous stream.

You may also be interested in `onJoin` (i.e. joining an existing Chromecast session with a new device) or `onLeave` (i.e. leaving an existing Chromecast session on a device).

The snippet below has two [sources](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/source/SourceDescription.Builder):

1. `senderSource` is intended for playback on your sender device (i.e. your Android app)
2. `chromecastSource` is intended for playback on your Chromecast application

The [`setConnectionCallback`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/cast/chromecast/Chromecast#setConnectionCallback-com.theoplayer.android.api.cast.chromecast.ChromecastConnectionCallback-) method on the [`Chromecast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/cast/chromecast/Chromecast) instance is used to:

1. Set the `chromecastSource` when Chromecast playback starts through the `onStart` callback.
2. Revert to the `senderSource` when Chromecast playback stops through the `onStop` callback.

```kotlin
val senderSource = SourceDescription.Builder(
    TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8")
        .type(SourceType.HLS)
        .build()
).build()
val chromecastSource = SourceDescription.Builder(
    TypedSource.Builder("https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8")
        .type(SourceType.HLS)
        .build()
).build()

val player = theoPlayerView.player
val chromecast = theoPlayerView.cast.chromecast

player.source = senderSource
chromecast.setConnectionCallback(object : ChromecastConnectionCallback {
    override fun onStart(sourceDescription: SourceDescription?): SourceDescription = chromecastSource

    override fun onStop(sourceDescription: SourceDescription?): SourceDescription = senderSource

    override fun onJoin(sourceDescription: SourceDescription?): SourceDescription? = sourceDescription

    override fun onLeave(sourceDescription: SourceDescription?): SourceDescription? = sourceDescription
})
```

The `onJoin` and `onLeave` implementations in the above snippet adhere to the default behavior.

---

# Sending messages from/to Sender to/from Receiver on Android

This article will explain how to send data to an active receiver and how to respond on the receiver.

## Send data to the receiver

The Google Cast SDK has a global object that everyone can access. This global object is also being used by THEOplayer. The general idea is to retrieve the current active cast session and send a message on a specific namespace.

```kotlin
// Retrieve the current cast session
val castSession = CastContext.getSharedInstance(this).sessionManager.currentCastSession
// Send message on defined namespace channel
castSession?.sendMessage("namespace", "message")
```

Reference:

* <https://developers.google.com/android/reference/com/google/android/gms/cast/framework/CastSession>

## Receive data from the receiver

The general idea is to retrieve the current active cast session and add an event listener on the specific namespace.

```kotlin
// Retrieve the current cast session
val castSession = CastContext.getSharedInstance(this).sessionManager.currentCastSession
// Create callback handler
val callback = Cast.MessageReceivedCallback { castDevice, namespace, message ->
    // Do something with the message
}
// Add the message listener to the current cast session
castSession?.setMessageReceivedCallbacks("namespace", callback)
```

Reference:

* <https://developers.google.com/android/reference/com/google/android/gms/cast/framework/CastSession.html#setMessageReceivedCallbacks(java.lang.String,%20com.google.android.gms.cast.Cast.MessageReceivedCallback)>

## Receive data on the receiver

*This example is for receiver version 2.*

The general idea is to retrieve the receiver manager and add a message listener for the specific namespace. **This needs to be done before a THEOplayer instance is created. THEOplayer will call the start method of the receiverManager on initialization.**

```js
// Retrieve the cast receiver manager
var castReceiverManager = cast.receiver.CastReceiverManager.getInstance();
// Retrieve the message bus from the cast receiver manager
var messageBus = castReceiverManager.getCastMessageBus('namespace');
// Add message listener to the message bus
messageBus.onMessage = function (event) {
  console.log(event);
};
```

Reference:

* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus>
* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus#onMessage>
* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus.Event>

## Send data from the receiver

*This example is for receiver version 2.*

There are multiple possibilities to send data from the receiver:

1. When a message is received on the receiver, you can answer the sender

2. Broadcast to all connected senders

```js
// 1.
messageBus.onMessage = function (event) {
  messageBus.send(event.senderId, 'message');
};
// 2.
messageBus.broadcast('message');
```

Reference:

* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus#broadcast>
* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus#send>

## Related articles

* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)

* [Chromecast SDK Setup](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md)

* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/how-to-configure-to-a-different-stream.md)

* [Connecting from custom Sender applications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/connecting-from-custom-sender-applications.md)

---

# Pass subtitle selection on to Chromecast on Android

Currently, it is intended behavior that when you start casting the player to a Chromecast device the subtitle selection setting isn't carried over. A new player is generated with the `SourceConfiguration` of the sender, but not any adjustments.

You can work around the default behavior by adding event listeners to the player.

The code adds an event on textTracks `change`. Whenever the subtitles change, this event is called and stores the current active textTrack in `currentTextTrack` by iterating over the textTracks array and checking whether `.mode` is `showing`. Once a Chromecast session is created, the code will check if the ID of the textTracks in the new player corresponds with the ID of the stored currentTextTrack. If so, it will activate that textTrack.

## Solution

Here is how you pass the current active subtitle track to the Chromecast session:

```kotlin
var currentTextTrack: TextTrack? = null
val player = theoPlayerView.player
val chromecast = theoPlayerView.cast.chromecast

player.textTracks.addEventListener(TextTrackListEventTypes.TRACKLISTCHANGE) {
    currentTextTrack = player.textTracks.firstOrNull { it.mode == TextTrackMode.SHOWING }
}

chromecast.addEventListener(ChromecastEventTypes.STATECHANGE) {
    if (chromecast.state == PlayerCastState.CONNECTED) {
        player.addEventListener(PlayerEventTypes.PLAYING) {
            val tt = player.textTracks.firstOrNull { it.id == currentTextTrack?.id }
            tt?.mode = TextTrackMode.SHOWING
        }
    }
}
```

---

# Enable Chromecast on the Sender on Android

This article explains how to enable the Chromecast Sender capabilities. This article also documents how you can connect with a custom Chromecast Receiver application.

> **Note**
>
> Chromecast support is not available for the Android TV and Fire TV SDKs.

## Prerequisites

1. Your Sender device needs to be on the same Wi-Fi network as your Chromecast Receiver device.

## Add the Chromecast integration

In order to enable Chromecast on the THEOplayer Android SDK, add the feature integration dependency in your `build.gradle` file.

```groovy
implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
implementation 'com.theoplayer.theoplayer-sdk-android:integration-cast:+' // add cast dependency
```

## Set `CastOptionsProvider`

To enable Chromecast on Android a `CastOptionsProvider` should be specified. This class contains the configuration for Chromecast on Android. A `DefaultCastOptionsProvider` is provided as part of the THEOplayer Android SDK. This `DefaultCastOptionsProvider` associates the default THEOplayer Chromecast receiver application with your Sender application. You will need to register this class in your `AndroidManifest.xml` file within a meta-data tag under your application node, as demonstrated at <https://github.com/THEOplayer/samples-android-sdk/blob/master/Google-Cast/app/src/main/AndroidManifest.xml#L17-L19>.

```xml
<meta-data
    android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
    android:value="com.theoplayer.android.api.cast.chromecast.DefaultCastOptionsProvider"/>
```

## Optional: Add routing button to your app

In order to get this button to appear in your application's Toolbar, the easiest way is to include it in the menu XML file for your Activity.

1. In your `res` folder add a menu folder

2. Add an `activity_main_menu.xml` file

3. Add the following contents to this file:

```xml
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    <item
    android:id="@+id/media_route_menu_item"
    android:title="Cast"
    app:actionProviderClass="androidx.mediarouter.app.MediaRouteActionProvider"
    app:showAsAction="always" />
</menu>
```

4. Initialize this new `MenuItem` in the `onCreateOptionsMenu` method of your Activity. (Make sure you have an `AppCompatActivity`).

```kotlin
override fun onCreateOptionsMenu(menu: Menu): Boolean {
    super.onCreateOptionsMenu(menu)
    menuInflater.inflate(R.menu.activity_main_menu, menu)
    CastButtonFactory.setUpMediaRouteButton(applicationContext, menu, R.id.media_route_menu_item)
    return true
}
```

## Optional: Add MiniController to your app

In your main activity xml add the following fragment:

```xml
<fragment
    android:id="@+id/castMiniController"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_alignParentBottom="true"
    android:visibility="gone"
    class="com.google.android.gms.cast.framework.media.widget.MiniControllerFragment" />
```

## Optional: Set a `CastStrategy` to your THEOplayerConfig

THEOplayer Android SDK support Chromecast CastStrategy to define the joining behavior.

```kotlin
THEOplayerConfig.Builder()
    .castStrategy(CastStrategy.AUTO)
    .build()
```

## Connect with custom Chromecast Receiver application

The THEOplayer SDK on your Sender application connects with THEO Chromecast Receiver application by default, but you can connect it to a custom Chromecast Receiver application instead. The default Dolby OptiView Chromecast Receiver application has OptiView Player functionality, but uses Shaka for media playback. If you want to use Google's legacy Media Player Library (MPL) for playback, you will need to use either a custom application or connect to Dolby OptiView's MPL Receiver application, using the `appID` value of `44BAE7D1`. Note that the MPL receiver does not support HLS-CMAF streams.

To connect with a custom Chromecast Receiver application, you can create your own `CastOptionsProvider` by subclassing `com.google.android.gms.cast.framework.OptionsProvider` and implementing the `getCastOptions` method. This approach is further demonstrated at <https://github.com/THEOplayer/samples-android-sdk/tree/master/Google-Cast/guides/howto-google-cast-integration#initializing-cast-context>, and in the snippet below.

```kotlin
override fun getCastOptions(context: Context): CastOptions =
    CastOptions.Builder()
        .setReceiverApplicationId(DEFAULT_APP_ID)
        .build()
```

---

# DRM on Android

THEOplayer supports FairPlay, PlayReady and Widevine by default. To use these DRM systems, you will need to pass a DRM configuration along with the `source` object. We are partnered with many multi-DRM vendors to make it as easy as possible to get your DRM streams running.

## Integrations

These DRM vendors can be used through an integration. An integration is not part of the SDK: it is added on top of it as a [custom DRM integration](#custom-integration). Ready-made integrations for many vendors are available in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration). Vendors which don't require custom license or certificate requests can be used with a plain key system configuration instead.

* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/arris-titanium.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/buydrm-keyos.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/doverunner.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/intertrust-expressplay.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/microsoft-azure.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/uplynk.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/verimatrix-multirights.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vimond.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vualto-vudrm.md)

## Pre-integrations

THEOplayer is also pre-integrated with a number of commercial multi-DRM vendors. These pre-integrations are part of the SDK itself: you select the vendor and pass its parameters, and the SDK takes care of the vendor's license and certificate requests. When integrating DRM for the first time or updating your integration, an integration is preferred over a pre-integration.

* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/arris-titanium.md)
* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/axinom.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/buydrm-keyos.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/castlabs-drmtoday.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/nagra-conax-contego.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vualto-vudrm.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/xstream.md)

## Other guides

* [Clear Key](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/clear-key.md): how to play a Clear Key protected stream.
* [Offline DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/offline-drm.md): how to implement playback of downloadable content-protected streams.
* [Customizing offline DRM notifications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/offline-drm-notifications.md)
* [Multi-key HLS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/multikey-hls.md): how to serve one HLS stream to all key systems.

## Custom configuration

Developers can use the generic DRM-functionalities in case in-house DRM-solutions are used, or services from DRM-vendors for which no integration is available.

To configure DRM on the Android SDK, developers can put a DRMConfiguration inside a SourceDescription.

```java
// Map<String, String> headers =  new HashMap<String, String>();
// headers.put("<KEY>", "<VALUE>");
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration.Builder(
            "<LICENSE_KEY_URL_WIDEVINE>"
            )// , headers, <USE_CREDENTIALS>, <QUERY_PARAMETERS>
            .build()
        )
        .build();
TypedSource typedSource = new TypedSource.Builder("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = new SourceDescription.Builder(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Custom integration

Developers can make their own custom DRM integration for any DRM vendor. This can be done by making use of the [DRM integration API repository](https://github.com/THEOplayer/samples-drm-integration).

A complete guide on how to create a new integration, and some example integrations can be found in the provided repository.

---

# Arris Titanium on Android

This article describes how to configure Arris Titanium DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Arris Titanium integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/android/app/src/main/java/com/theoplayer/contentprotectionintegration/integration/titanium).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```java
DRMConfiguration drmConfiguration = TitaniumDRMConfiguration.Builder
    .titaniumDrm("<ACCOUNT_NAME>", ">CUSTOMER_NAME>", "<PORTAL_ID>")
    // .friendlyName("<FRIENDLY_NAME>")
    // .authToken("<AUTH_TOKEN>")
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Resources

* <https://www.arris.com/products/titanium-cas/>
* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/nagra-conax-contego.md)

---

# Axinom on Android

This article describes how to configure Axinom DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```java
DRMConfiguration drmConfiguration = new AxinomDRMConfiguration.Builder("<AXINOM_TOKEN>")
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Resources

* <https://www.axinom.com/products/drm>

## Related articles

* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vualto-vudrm.md)

---

# BuyDRM KeyOS on Android

This article describes how to configure BuyDRM KeyOS DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The BuyDRM KeyOS integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/android/app/src/main/java/com/theoplayer/contentprotectionintegration/integration/keyos).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

Pass your BuyDRM token as custom data, and tell THEOplayer that you are using KeyOS. The token is the Authentication XML generated from the BuyDRM platform.

```java
DRMConfiguration drmConfiguration = KeyOSDRMConfiguration.Builder
    .keyOsDrm()
    .widevine(
        new KeyOSKeySystemConfiguration("<CUSTOM_DATA>", "<LICENSE_KEY_URL_WIDEVINE>")
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Resources

* <https://test.buydrm.com/sites/default/files/pdf/webinar/050217_DeployingKeyOSMulti-DRM_withTHEOPLayer_Webinar.pdf>
* [KeyOS BuyDRM](https://www.buydrm.com/keyosplayer)

---

# castLabs DRMToday on Android

This article describes how to configure castLabs DRMToday with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```java
DRMConfiguration drmConfiguration = DRMTodayConfiguration.Builder
    .drmToday(
        new KeySystemConfiguration("<LICENSE_KEY_URL_WIDEVINE>")
    )
    .merchant("<MERCHANT>")
    .sessionId("<SESSION_ID>")
    .token("<TOKEN>")
    .userId("<USER_ID>")
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Resources

* <https://castlabs.com/drmtoday/>

---

# EZDRM on Android

This article describes how to configure [EZDRM](https://www.ezdrm.com/) with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Code example

```java
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Resources

* [EZDRM documentation](https://www.ezdrm.com/documentation)
* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vualto-vudrm.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vimond.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/verimatrix-multirights.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/doverunner.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/nagra-conax-contego.md)

---

# Intertrust ExpressPlay on Android

This article describes how to configure Intertrust ExpressPlay DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the Android and Android TV SDKs.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Code example

**Not verified.**

```java
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Resources

* [Verimatrix ExpressPlay DRM and THEOplayer](https://www.verimatrix.com/partners/theoplayer/)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/nagra-conax-contego.md)

---

# Irdeto on Android

This article describes how to configure Irdeto DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```java
DRMConfiguration drmConfiguration = new IrdetoConfiguration("<CRM_ID>", "<ACCOUNT_ID>", "<CONTENT_ID>",
                "<SESSION_ID>", "<TICKET>", new KeySystemConfiguration("<LICENSE_KEY_URL_WIDEVINE"));
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Resources

* <https://irdeto.com/video-entertainment/multi-drm-and-rights-management/>

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/nagra-conax-contego.md)

---

# Microsoft Azure on Android

> **Warning**
>
> Azure Media Services has been retired since June 30th, 2024.

This article describes how to configure Microsoft Azure DRM with THEOplayer. Head to [Azure Media Services 3rd Party Player Samples - THEOplayer](https://github.com/Azure-Samples/media-services-3rdparty-player-samples/tree/master/docs/THEOplayer) for an implementation reference sample.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Microsoft Azure integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/android/app/src/main/java/com/theoplayer/contentprotectionintegration/integration/azuredrm).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```java
DRMConfiguration drmConfiguration = new AzureDRMConfiguration.Builder("<CERTIFICATE_URL>", "<TOKEN>")
    .widevine(
        new KeySystemConfiguration("<LICENSE_KEY_URL_WIDEVINE>")
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Resources

* <https://azure.microsoft.com/nl-nl/services/media-services/content-protection/>

## Related articles

* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vualto-vudrm.md)
* [Azure Media Services - THEOplayer Implementation Sample](https://github.com/Azure-Samples/media-services-3rdparty-player-samples/tree/master/docs/THEOplayer)

---

# Nagra Conax Contego on Android

This article describes how to configure [Conax](https://dtv.nagra.com/scalable-service-protection) DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```java
DRMConfiguration drmConfiguration = ConaxDRMConfiguration.Builder.conaxDrm("<DEVICE_ID>", "<CONAX_TOKEN>")
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/microsoft-azure.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/uplynk.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/verimatrix-multirights.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vimond.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vualto-vudrm.md)

---

# Verimatrix MultiRights on Android

This article describes how to configure Verimatrix MultiRights with THEOplayer. [MultiRights](https://www.verimatrix.com/solutions/multirights-ott) is a multi-DRM solution by [Verimatrix](https://www.verimatrix.com/).

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Verimatrix Core integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/android/app/src/main/java/com/theoplayer/contentprotectionintegration/integration/verimatrixcoredrm).

## Code example

```java
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Resources

* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vualto-vudrm.md)

---

# Vimond on Android

This article describes how to configure Vimond DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the Android SDK.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Code example

```java
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Resources

* [Vimond](https://www.vimond.com/)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/nagra-conax-contego.md)

---

# Vualto VuDRM on Android

This article describes how to configure Vualto VuDRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Vualto VuDRM integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/tree/master/android/app/src/main/java/com/theoplayer/contentprotectionintegration/integration/vudrm).

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```java
DRMConfiguration drmConfiguration = new VudrmDRMConfiguration("<TOKEN>", null,
                new KeySystemConfiguration("<LICENSE_KEY_URL>"));
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Resources

* <https://www.vualto.com/products/vudrm-drm/>
* <https://github.com/Vualto/vuplay-theoplayer>

## Related articles

* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vualto-vudrm.md)

---

# Uplynk on Android

This article describes how to configure Uplynk DRM with THEOplayer.

**Important:** Uplynk customers should configure DRM through the [THEOplayer Uplynk connector for Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk/preplay.md). (The Uplynk connector provides an out-of-the-box integration with Uplynk's Preplay, Ping and Asset Info services, exposes additional APIs, and enhances your UI and UX.)

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

The [Uplynk connector for Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk/preplay.md) takes care of the DRM configuration as part of its Preplay logic: when you request a content-protected asset with the [`contentProtected`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk/preplay.md) flag, the connector sets up the DRM configuration of the resulting source for you.

## Resources

* [Content Protection (Uplynk)](https://docs.uplynk.com/docs/content-protection)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/nagra-conax-contego.md)

---

# Xstream on Android

This article describes how to configure Xstream DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Pre-integration

> **Note**
>
> When integrating DRM for the first time or updating your integration, the DRM integration described above is preferred over the pre-integration below.

```java
DRMConfiguration drmConfiguration = new XstreamConfiguration.Builder("<STREAM_ID>", "<TICKET_ACQUISITION_URL>")
    .widevine(
        KeySystemConfiguration.Builder.keySystemConfiguration("LA_URL").build()
    )
    .build()
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Related articles

* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vualto-vudrm.md)

---

# Clear Key on Android

This article provides a simple example of how to use Clear Key with THEOplayer.

Usually, DRM systems require you to specify a `licenseAcquisitionURL` and additional optional data (e.g.: certificate, credentials, headers). Clear Key does not need a DRM provider. You can provide the key(s) directly to the player (hence "clear" key) through the `keys` property in its `LicenseAcquisitionDescription` (in fact, this property is only available for Clear Key). Alternatively, you can have the player fetch the keys from a `licenseAcquisitionURL`, which returns a JSON object containing the same keys.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

Please check also our related [API documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/source/drm/ClearkeyKeySystemConfiguration) on how to set these.

## Code example

```java
SourceDescription.Builder clearKey = new SourceDescription.Builder(
        new TypedSource.Builder("https://storage.googleapis.com/shaka-demo-assets/angel-one-clearkey/dash.mpd")
                .drm(
                        new DRMConfiguration.Builder()
                                .clearkey(
                                        new ClearkeyKeySystemConfiguration.Builder("https://cwip-shaka-proxy.appspot.com/clearkey?_u3wDe7erb7v8Lqt8A3QDQ=ABEiM0RVZneImaq7zN3u_w")
                                                .useCredentials(false)
                                                .build()
                                )
                                .build()
                )
                .build()
);

tpv.getPlayer().setSource(clearKey.build());
```

## Resources

* [Generate MPEG DASH content encrypted with MPEG CENC ClearKey](https://github.com/Dash-Industry-Forum/dash.js/wiki/Generate-MPEG-DASH-content-encrypted-with-MPEG-CENC-ClearKey): DASH IF on GitHub
* [Clear Key license format](https://w3c.github.io/encrypted-media/#clear-key-license-format): W3C - Encrypted Media Extensions

---

# DoveRunner on Android

This article describes how to configure [DoveRunner Multi-DRM](https://doverunner.com/docs/content-security/multi-drm/) with THEOplayer. This content is based on DoveRunner's documentation.

**Note**: The details in the guide apply for DoveRunner (formerly known as "PallyCon"). While most details, API hostnames and variables have been updated to reflect DoveRunner, certain configurations such as the `pallycon-customdata-v2` HTTP request header will still apply.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Code example

```java
// Map<String, String> headers =  new HashMap<String, String>();
// headers.put("<CUSTOM_HEADER_NAME>", "<CUSTOM_HEADER_VALUE>"); // e.g. "pallycon-customdata-v2", "eyJkYXRhIjoibWJLV1NjSUNIU25WMjZQWFB4cGlDQUJVbnZsOGxCOWRNZDhHZ3dhbjZqRDFwNFZoQk51VlhQY2RMaG9nNTNYbngyTjFaalwvQ3BxZ3RUS2k5Rzd3MUZ3PT0iLCJzaXRlX2lkIjoiREVNTyIsImRybV90eXBlIjoiUGxheVJlYWR5In0="
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>", headers, false, null
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Resources

* <https://doverunner.com/docs/content-security/multi-drm/>
* <https://doverunner.com/docs/content-security/multi-drm/clients/widevine-android/>

## Related articles

* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vualto-vudrm.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/vimond.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/verimatrix-multirights.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/nagra-conax-contego.md)

---

# Multi-key HLS on Android

There are multiple DRM key systems on the market to choose from. The most popular ones are Google Widevine, Microsoft PlayReady and Apple FairPlay. Under the hood, all these systems encrypt the media samples using the AES-128 encryption algorithm. AES-128 is a standardized block-cipher that allows for multiple ways of choosing the blocks. Widevine and PlayReady both use `CTR` and FairPlay uses `CBC`. Therefore, it was possible to share segments between Widevine and PlayReady protected streams, but not with FairPlay protected stream. However, support has been added for Widevine and PlayReady with AES-128 in `CBC` mode. Hence, it is now possible to create HLS streams compatible with all these key systems. Where you previously had to encode the stream twice, this is no longer needed.

A multi-key HLS stream will play on all Android platforms, using either the Widevine or the PlayReady key from the playlist.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/introduction.md) for more general information.

## The HLS playlist

A multi-key HLS playlist could look like this:

```text
#EXTM3U
#EXT-X-TARGETDURATION:6
#EXT-X-VERSION:5
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-KEY:METHOD=SAMPLE-AES,KEYFORMAT="urn:uuid:edef8ba9-79d6-4ace-a3c8-27dcd51d21ed",KEYFORMATVERSIONS="1",URI="WIDEVINE_INIT_DATA_URL"
#EXT-X-KEY:METHOD=SAMPLE-AES,KEYFORMAT="com.microsoft.playready",KEYFORMATVERSIONS="1",URI="PLAYREADY_INIT_DATA_URL"
#EXT-X-KEY:METHOD=SAMPLE-AES,KEYFORMAT="com.apple.streamingkeydelivery",KEYFORMATVERSIONS="1",URI="FAIRPLAY_INIT_DATA_URL"
#EXT-X-MAP:URI="init.mp4"
#EXTINF:6,
1.mp4
#EXTINF:6,
2.mp4
#EXTINF:6,
3.mp4
#EXTINF:6,
4.mp4
#EXTINF:6,
5.mp4
#EXT-X-ENDLIST
```

There is an `#EXT-X-KEY` tag for all the key systems which all have method `SAMPLE-AES`. The `KEYFORMAT` specifies the key system:

* `urn:uuid:edef8ba9-79d6-4ace-a3c8-27dcd51d21ed` for Widevine
* `com.microsoft.playready` for PlayReady
* `com.apple.streamingkeydelivery` for FairPlay

The `URI` is either a data URI containing the initialization data, or a URI pointing to the initialization data. For more information, please check out the specifications for [Widevine](https://www.academia.edu/36030972/Widevine_DRM_for_HLS), [PlayReady](https://docs.microsoft.com/en-us/playready/packaging/mp4-based-formats-supported-by-playready-clients?tabs=case4) and [FairPlay](https://developer.apple.com/streaming/fps/).

## Configuring THEOplayer

The Android SDK plays the key system that is available on the device: Widevine on all Android devices, and PlayReady on devices which support it (such as Android TV). Configure a license acquisition URL for each of these key systems:

```java
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration.Builder("https://widevine-server.com/license").build()
    )
    .playready(
        new KeySystemConfiguration.Builder("https://playready-server.com/license").build()
    )
    .build();
TypedSource typedSource = new TypedSource.Builder("https://yourdomain.com/playlist.m3u8")
    .type(SourceType.HLS)
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = new SourceDescription.Builder(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

The `#EXT-X-KEY` tags of the other key systems are ignored.

---

# Offline DRM on Android

This how-to guide describes how to implement playback of downloadable content-protected streams using THEOplayer.

*Currently, Widevine and FairPlay (respectively for Android SDK and iOS SDK) are each supported together with the Uplynk-Verizon, Azure DRM and DRMToday integrations.*

This how-to guide describes how to implement playback of downloadable content-protected MPEG-DASH using the THEOplayer Android SDK. Currently, Widevine is supported together with the Irdeto and DRMToday integrations.

## Prerequisites

In order to do offline DRM on Android, your license key should be downloadable, and cacheable. The SDK will not be able to decrypt your content if your key expired.

To enable the display of progress notifications for downloading content in your Android application you need to include the following permissions in your AndroidManifest.xml file:

```xml
<manifest>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    <application>
        ...
    </application>
</manifest>
```

* android.permission.FOREGROUND\_SERVICE: This permission allows THEOplayer to run a foreground service, ensuring uninterrupted content downloads even when the application is not in the foreground. See more at [Foreground service permission](https://developer.android.com/guide/components/foreground-services#request-foreground-service-permissions).

* android.permission.POST\_NOTIFICATIONS: This permission is required if an application is targeting API 33 (Android 13) and above. It enables THEOplayer to create and display notifications, keeping users informed about the progress of content downloads. For more information, refer to the [Notification runtime permission](https://developer.android.com/develop/ui/views/notifications/notification-permission).

Including these permissions in your AndroidManifest.xml file is necessary for THEOplayer to run a foreground service and provide progress notifications during content downloads.

## Code example

The snippet below downloads a Widevine MPEG-DASH asset.

```java
private void cacheSource(String sessionId, String src, String amount, Date expirationDate) {
    Cache cache = THEOplayerGlobal.getSharedInstance(this).getCache();
    DRMConfiguration drmToday = createDrmTodayConfiguration(sessionId);
    SourceDescription source = new SourceDescription.Builder(
        new TypedSource.Builder(src)
            .drm(drmToday)
        .build())
    .build();
    CachingParameters cachingParameters = new CachingParameters.Builder()
                .amount(amount)
                .expirationDate(expirationDate)
                .build();
    CachingTask cachingTask = cache.createTask(source, cachingParameters);
    cachingTask.addEventListener(CachingTaskEventTypes.CACHING_TASK_STATE_CHANGE, e -> {
        switch (cachingTask.getStatus()) {
            case DONE:
                // handle success..
                break;
            case ERROR:
                // handle error..
                break;
            default: // do nothing
                break;
        }
    });
    cachingTask.start();
}

private DRMConfiguration createDrmConfiguration(String sessionId) {
    KeySystemConfiguration widevine = new KeySystemConfiguration.Builder()
        .keySystemConfiguration(LICENSE_ACQUISITION_URL)
        .licenseType(LicenseType.PERSISTENT)
        .build();
    return YOUR_DRM_INTEGRATION_WITH_WIVDEVINE(widevine)
}
```

To playback cached material, create and play the stream as per usual. The cached content will be used for the known source.

```java
private void playSourceFromCache(String sessionId, String src) {
    DRMConfiguration drmConf = createDrmConfiguration(sessionId);
    SourceDescription sourceDescription =
        new SourceDescription.Builder(
                new TypedSource.Builder(src)
                        .drm(drmConf)
                        .build())
                .build();
    tpv.getPlayer().setSource(sourceDescription);
    tpv.getPlayer().play();
}
```

A caching task can be paused and restarted through the task object itself.

```java
private void startAndPauseTask(CachingTask task) {
    // When not started, the task will be in the "IDLE" state
    task.start();
    // The status of the task will now be "LOADING"
    task.pause();
    // The task reverts back to "IDLE" after finishing its current segment download
    task.start();
    // The task continues where it was paused
}
```

After creating a caching task, it is possible to check an estimate for the total size of the caching task on disk, and the current progression in bytes (stored).

```java
private void checkStorageRequirements(CachingTask unstartedTask) {
    // We can get an estimate for the amount of space this task will consume. This will be ready once the manifest is preprocessed when the task is created. Starting is not necessary.
    System.out.println(unstartedTask.getBytes());
    unstartedTask.start();

    // ... Additional logic here

    // At any time, we can check the current amount of bytes cached by the task
    System.out.println(unstartedTask.getBytesCached());
}
```

## Listing and restarting caching tasks

An important side note when calling previously cached tasks is that you need to initialize the cache first. Initializing happens asynchronously, so calling upon the cache immediately after initializing may result in an empty list as it is still initializing. (You could initialize the cache as soon as your app opens, such that you can access it later in other pages in the app). To initialize the cache, you need to run the following command:

```java
Cache cache = THEOplayerGlobal.getSharedInstance(this).getCache();
```

If you only want to initialize it at the moment that you need it, you can use an eventListener to see when it's initialized, e.g.

```java
Cache cache = THEOplayerGlobal.getSharedInstance(this).getCache();
cache.addEventListener(CacheEventTypes.CACHE_STATE_CHANGE, new EventListener<CacheStateChangeEvent>() {
    @Override
    public void handleEvent(CacheStateChangeEvent cacheStateChangeEvent) {
        // Logic once cache is initialized.
        // Status can always be fetched using
        // cache.getStatus(), which will return the ENUM CacheStateChangeEvent.INITIALISED or CacheStateChangeEvent.UNINITIALISED
    }
});
```

Once the cache is properly initialized, you can call upon the cache with methods such as "getTasks()" which will return a TaskList that you can iterate through to find previously cached tasks and resume caching or play the resource. Example:

```java
// If you're in a different activity, you can always call upon the previously initialized cache
Cache cache = THEOplayerGlobal.getSharedInstance(this).getCache();

// Loop over previously cached tasks
for (CachingTask cachedVideo : cache.getTasks()) {
    // Do logic with the found cached video e.g.
    CachingTaskStatus status = cachedVideo.getStatus();
    SourceDescription sourceDescription = cachedVideo.getSource();
    Double percentageCached = cachedVideo.getPercentageCached();
    cachedVideo.pause(); // Pause if not already paused
    cachedVideo.start(); // start or resume caching task}
}
```

For all possible API calls, we refer you to the JavaDoc available [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/cache/package-summary)

---

# Customizing offline DRM notifications on Android

Head to our page on [offline DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/drm/offline-drm.md) for more general information.

## Text Resources Customization

To customize the text or add translations to the notifications, you can override the following string resources:

1. `<string name="theo_download_progress_title">Downloading video</string>`

   * This resource represents the title displayed during the progress of video downloading.

2. `<string name="theo_download_status_title">Download %s</string>`

   * This resource represents the title displayed during the download process. The `%s` placeholder will be replaced with the actual file name.

3. `<string name="theo_download_status_percentage">%d%%</string>`

   * This resource represents the percentage of download progress displayed in the notification. The `%d` placeholder will be replaced with the actual progress value.

4. `<string name="theo_download_finished_status_title">Download finished</string>`

   * This resource represents the title displayed when the download is completed successfully.

5. `<string name="theo_download_paused_status_title">Download paused</string>`

   * This resource represents the title displayed when the download is paused.

6. `<string name="theo_download_failed_status_title">Download failed</string>`

   * This resource represents the title displayed when the download fails.

7. `<string name="theo_download_stopped_status_title">Download stopped</string>`

   * This resource represents the title displayed when the download is manually stopped.

8. `<string name="theo_cache_notifications_channel_name">Media downloader</string>`

   * This resource represents the name of the notification channel used for media downloading.

9. `<string name="theo_cache_notifications_channel_description">Downloads media to make it available for offline playback</string>`

   * This resource represents the description of the notification channel used for media downloading.

To customize these texts or add translations, create corresponding string resources in your app's resource file (e.g., `strings.xml`) and provide the desired values.

By overriding these resources, you can tailor the text content of the notifications to match your application's branding or localize them for different languages or regions.

## Customization of Notification Builders

The `CacheNotificationsBuilder` interface provides the ability to create customized notification appearances using the NotificationCompat.Builder. This feature allows you to design notifications according to your specific preferences and requirements.

The `CacheNotificationsBuilder` interface includes three methods:

1. `createProgressNotificationBuilder`: This method allows you to customize the `builder` parameter and create a custom progress notification builder for a specific caching task. It takes the `task` parameter, which represents the caching task for which the progress notification is being created, and the `builder` parameter, which is the base notification builder to customize. It returns the customized notification builder for the progress notification.

2. `createStatusNotificationBuilder`: In this method, you have the ability to customize the `builder` parameter and create a custom status notification builder for a given caching task. It takes the `task` parameter, which represents the caching task for which the status notification is being created, and the `builder` parameter, which is the base notification builder to customize. It returns the customized notification builder for the status notification.

3. `createNotificationChannel`: This method enables you to customize the `channel` parameter and create a custom notification channel for caching notifications. It takes the `channel` parameter, which is the base notification channel builder to customize. It returns the customized notification channel builder.

   **Note:** If you decide to return `null` in the `createNotificationChannel` method, the library will not create any notification channel. This means that notifications related to caching will not have a designated channel for grouping or presentation.

These methods allow you to customize the appearance and behavior of notifications and notification channels according to your specific requirements when downloading media files using cache in THEOplayer.

To implement this interface, follow these steps:

1. Obtain an instance of THEOplayer cache by calling `THEOplayerGlobal.getSharedInstance(this).cache`.

2. Assign an object that implements the CacheNotificationsBuilder interface to `theoCache.notificationBuilder`.

   Example:

   ```kotlin
   val theoCache = THEOplayerGlobal.getSharedInstance(this).cache
   theoCache.notificationBuilder = object : CacheNotificationsBuilder {
       override fun createNotificationChannel(channel: NotificationChannelCompat.Builder): NotificationChannelCompat.Builder {
           // Customization logic for the notification channel
           ...
           return channel
       }

       override fun createProgressNotificationBuilder(task: CachingTask, builder: NotificationCompat.Builder): NotificationCompat.Builder {
           // Customization logic for the progress notification builder
           ...
           return builder
       }

       override fun createStatusNotificationBuilder(task: CachingTask, builder: NotificationCompat.Builder): NotificationCompat.Builder {
           // Customization logic for the status notification builder
           ...
           return builder
       }
   }
   ```

In the `createProgressNotificationBuilder` and `createStatusNotificationBuilder` methods, you can refer to the official [NotificationCompat.Builder documentation](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) for detailed information on how to customize the notification appearance, add actions, and handle interactions.

Inside the implementation of each method, you can customize the respective notification channel or builder according to your requirements. Make sure to return the modified notification channel or builder as per the method's return type.

By completing these steps, you will set up the implementation of the CacheNotificationsBuilder interface, allowing you to customize the appearance and behavior of notifications in THEOplayer cache.

## Hiding notifications

To hide a notification, you can simply return `null` in the corresponding method of the `CacheNotificationsBuilder` interface.

For example, if you want to hide the progress notification or status notification for a specific caching task, you can return `null` in the `createProgressNotificationBuilder` or `createStatusNotificationBuilder` method, respectively. This will prevent the notification from being shown.

Please note that when you return `null` in the `createProgressNotificationBuilder` or `createStatusNotificationBuilder` methods to hide the notification, the downloading process will not be performed using a foreground service.

Ensure that you consider the implications of hiding notifications and not using a foreground service for downloading media files. It is recommended to provide alternative ways to inform the user about the download progress or completion if you choose to hide notifications.

---

# Integrations on Android

In this section, you can figure out how THEOplayer integrates with various partners.

## Related articles

* [Deliver Low-Latency HLS live streams](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/integrations/wowza-streaming-engine/low-latency-hls.md)

---

# Wowza Streaming Engine on Android

[Wowza Streaming Engine™](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/) is a media server for live and on-demand streaming. THEOplayer can play back its streams, and integrates with a number of its features.

---

# Deliver Low-Latency HLS live streams with Wowza Streaming Engine on Android

Wowza Streaming Engine™ media server software can deliver Low-Latency HLS (LL-HLS) live streams, which THEOplayer can play back on every platform.

Low-Latency HLS streams conform to [Apple's protocol extension to the HLS specification](https://developer.apple.com/documentation/http-live-streaming/enabling-low-latency-http-live-streaming-hls).

## Prerequisites

There are three prerequisites in order to continue with this guide:

1. In order to generate LL-HLS streams, you must first get a SSL certificate to secure your port and configure the port for HTTPS playback. LL-HLS playback does not work without an SSL secured port. For information on how to do this, refer to [How to Get an SSL Certificate from Wowza's Streamlock Service](https://www.wowza.com/docs/how-to-get-ssl-certificates-from-the-streamlock-service).

2. This guide expects that you have a THEOplayer license. If you are not using THEOplayer yet, you can start your free trial [here](https://portal.theoplayer.com/).

3. This guide expects that you are a Wowza Streaming Engine client and that you are integrated with their streaming infrastructure. Information on Wowza Streaming Engine can be found [here](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/). Be sure to have Wowza Streaming Engine media server software version 4.7.8 or higher.

**Please Note:** Wowza occasionally update their documentation, which can be accessed [here](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine).

## Configure a live application to deliver LL-HLS streams

You can use the default **live** application that installs with Wowza Streaming Engine or create and use a new **Live** or **Live HTTP Origin** application. Use the **Live** application type for sending streams from Wowza Streaming Engine to clients or Wowza Streaming Engine edges. Use the **Live HTTP Origin** application type to connect to a CDN edge, such as the Fastly CDN, that can pull streams from the Wowza Streaming Engine origin application.

The following steps use the default **live** application to enable LL-HLS live streaming by editing the **Application.xml** and **VHost.xml** configuration files.

**Please Note:** If you're trying to use the CMAF packetizer to deliver LL-HLS and HLS or MPEG-DASH streams, you must use two separate live applications: one configured specifically for LL-HLS and another for CMAF-packetized HLS and MPEG-DASH.

### Enable LL-HLS in Wowza Streaming Engine XML

The following steps enable transmuxing for CMAF packetization for LL-HLS delivery.

1. Navigate to **\[install-dir]/conf/live** or **\[install-dir]/conf/\[custom live application]** and open the **Application.xml** file in a text editor.
2. Add **cmafstreamingpacketizer** to the **LiveStreamPacketizers** property. You can add it to the prepopulated comma-separated list, or it can be the only packetizer specified. The XML looks like this:

```xml
<Streams>
    ...
    <LiveStreamPacketizers>cmafstreamingpacketizer</LiveStreamPacketizers>
    ...
</Streams>
```

**Please Note:** If you enable **cupertinostreamingpacketizer** and **cmafstreamingpacketizer**, Wowza Streaming Engine generates both MPEG-TS segments (using **cupertinostreamingpacketizer**) and fMP4 segments (using **cmafstreamingpacketizer**).

3. Add the **cmafLLEnableLowLatency** property to the **LiveStreamPacketizer** container element and set it to true.

```xml
<LiveStreamPacketizer>
    <Properties>
        <Property>
            <Name>cmafLLEnableLowLatency</Name>
            <Value>true</Value>
            <Type>Boolean</Type>
        </Property>
    </Properties>
</LiveStreamPacketizer>
```

4. For the **HTTPStreamers** property, make sure HLS (**cupertinostreaming**) is specified. The XML looks like this:

```xml
<HTTPStreamers>cupertinostreaming</HTTPStreamers>
```

5. Go to **\[install-dir]/conf/** and open the **VHost.xml** file in a text editor.

6. Add the `AllowHttp2` property to the `<SSLConfig>` container element in the `<HostPort>` you configured for SSL/TLS and set it to true.

```xml
<SSLConfig>
    ...
    <AllowHttp2>true</AllowHttp2>
    ...
</SSLConfig>
```

7. Save your changes.

Your live application is now configured to deliver LL-HLS streams.

### Configure optional low latency partial segment properties and media playlist property

Configuring the following properties is optional as Wowza Streaming Engine will use the property's default value for any of the properties that you do not configure. You can configure the optional LL-HLS properties by editing the **Application.xml** file for your LL-HLS live stream application. For information about configuring custom (optional) properties, see [Add custom properties](https://www.wowza.com/docs/add-a-custom-property#add-custom-properties).

#### Low latency CMAF property reference

You can configure any of these optional **LiveStreamPacketizer** properties for the LL-HLS segments and video and audio partial segments (chunks) in the **Application/LiveStreamPacketizer/Properties** container element.

**Please Note:** If partial segments are too small, servers can become overloaded with frequent media playlist requests and cause playback to be less reliable.

| Name                                                                                                                                                          | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **cmafLLChunkingScheme**                                                                                                                                      | String  | Specifies the chunking scheme for low latency CMAF-packetized streams. Valid values are **byFrame** or **byDuration**. The default is **byDuration**. If the value is **byDuration**, packetization is configured using the **cmafLLChunkDurationTargetAudio** and **cmafLLChunkDurationTargetVideo** properties. If the value is **byFrame**, packetization is configured using the **cmafLLChunkFrameCountTargetAudio** and **cmafLLChunkFrameCountTargetVideo** properties. |
| **cmafLLChunkDurationTargetAudio**                                                                                                                            | Integer | Specifies, in milliseconds, the target duration of each low latency CMAF **audio** chunk. The default is **1000** and is recommended. The duration cannot exceed the [cmafSegmentDurationTarget](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine#cmafsegmentdurationtarget) value. This property is only available if **cmafLLChunkingScheme** is **byDuration**.                                                           |
| **cmafLLChunkDurationTargetVideo**                                                                                                                            | Integer | Specifies, in milliseconds, the target duration of each low latency CMAF **video** chunk. The default is **1000** and is recommended. The duration cannot exceed the [cmafSegmentDurationTarget](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine#cmafsegmentdurationtarget) value. This property is only available if **cmafLLChunkingScheme** is **byDuration**.                                                           |
| **cmafLLChunkFrameCountTargetAudio**                                                                                                                          | Integer | Specifies the target number of audio frames to include in each low latency CMAF audio chunk. The default is **47** and is recommended. This property is only enabled if **cmafLLChunkingScheme** is **byFrame**.                                                                                                                                                                                                                                                               |
| **cmafLLChunkFrameCountTargetAudio**                                                                                                                          | Integer | Specifies the target number of audio frames to include in each low latency CMAF audio chunk. The default is **30** and is recommended. This property is only enabled if **cmafLLChunkingScheme** is **byFrame**.                                                                                                                                                                                                                                                               |
| **[cmafSegmentDurationTarget](https://www.wowza.com/docs/configure-cmaf-packetization-in-wowza-streaming-engine#cmaf-live-packetization-property-reference)** | Integer | Specifies, in milliseconds, the duration of the fMP4 segments in the stream. The default is **6000** (6 seconds) and is recommended. This property is configurable from the **CMAFStreamingPacketizer** properties section in Wowza Streaming Engine Manager.                                                                                                                                                                                                                  |

#### Advanced LL-HLS property reference

For advanced tuning, you can configure the following optional **HTTPStreamer** property in the **Application/HTTPStreamer/Properties** container element.

| Name                                    | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cupertinoPartHoldBack (4.8.0 and later) | Double | Specifies, in floating-point seconds, the server-recommended minimum distance from the live edge at which clients should begin to play or seek in a LL-HLS stream (the PART-HOLD-BACK attribute in media playlists). If you do not configure this property, Wowza Streaming Engine uses the default value, which is recommended. The default value is calculated as three times the maximum value of PART-TARGET out of all of a stream's variant media playlists. **Please Note:** PART-TARGET is an attribute of the EXT-X-PART-INF tag in media playlists and is based on the target values set with the **cmafLLChunkDurationTargetVideo** and **cmafLLChunkDurationTargetAudio** properties or the **cmafLLChunkFrameCountTargetVideo** and **cmafLLChunkFrameCountTargetAudio** properties. Wowza Streaming Engine will adjust the PART-HOLD-BACK value to be equal to the maximum value of PART-TARGET (across all variant media playlists) if you set this property to less than a partial segment duration. |

#### Transcoding considerations for LL-HLS

To bypass encoding streams with Transcoder, source streams should meet the following encoding recommendations. Otherwise, transcoding is recommended. Although a small amount of latency is introduced with transcoding, if your source stream does not meet the encoding recommendations, transcoding will ultimately improve reliability of LL-HLS streaming.

##### Encoding recommendations

* CMAF-supported codecs (required)

| Video          | Audio                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - H.264, H.265 | - AAC, AAC-LC, HE-AAC (AAC+ or aacPlus),<br />- HE-AACv2 (enhanced AAC+, aacPlus v2) - Dolby Digital 5.1 Surround Sound (AC-3) and Dolby Digital Plus (Enhanced AC-3 or E-AC-3) |

* GOP size: 1 or 2 seconds
* Closed GOPs
* H.264 and H.265 byte streams contain metadata about the GOP structure
* Constant frame rate video

A stream configured for transcoding and LL-HLS delivery cannot use **Passthrough** for the **Video Codec** of a stream rendition but not other renditions of the same stream. If you use **Passthrough** to pass a video source through to output without making any changes for any **Video Codec** in a stream's renditions, all of the video codecs must be set to **Passthrough**.

Stream name groups (NGRP) are not supported with LL-HLS. To group multiple stream renditions for LL-HLS, you need to create a SMIL file in accordance with CMAF HLS. See [Set up adaptive bitrate CMAF streaming](https://www.wowza.com/docs/create-adaptive-bitrate-cmaf-streams-using-wowza-streaming-engine#set-up-adaptive-bitrate-cmaf-streaming) for how to do this.

#### Scale LL-HLS with a CDN

Optionally, with your own CDN account, you can scale LL-HLS delivery by connecting a Wowza Streaming Engine **Live HTTP Origin** application to a CDN edge that can pull streams from the Wowza Streaming Engine origin application, such as the Fastly CDN.

To connect the **Live HTTP Origin** application to your CDN, provide the IP address or hostname of the Wowza Streaming Engine origin server in your CDN configuration. Also in your CDN configuration, enable connecting to the origin server over SSL/TLS using the port you configured for SSL/TLS in the Wowza Streaming Engine origin (default port 443).

#### Test stream playback

After your live application is configured to deliver an LL-HLS stream, complete the stream setup by connecting a source encoder or IP camera to Wowza Streaming Engine and publishing the live source stream to the server. When the camera or encoder is connected and the live stream is active, test LL-HLS playback using a supported test player.

To test LL-HLS live streams when only **cmafstreamingpacketizer** is enabled, specify the stream playback URL using one of the following formats:

**Single bitrate** https\://\[address]/\[application]/\[application-instance]/\[stream-name]/playlist.m3u8

If **cmafstreamingpacketizer** and **cupertinostreamingpacketizer** are enabled, specify the stream playback URL using one of the following formats:

**Single bitrate** https\://\[address]/\[application]/\[application-instance]/\[stream-name]/playlist\_sfm4s.m3u8

Where:

**\[address]** is the IP address or domain and port (default port 443) **\[application]** is the application name **\[application-instance]** is the name of the application instance (if omitted, defaults to ***definst***) **\[stream-name]** is the stream name So, for example, if only **cmafstreamingpacketizer** is enabled, the playlist URL for an adaptive bitrate LL-HLS stream that uses the address **example.com**, the default **live** application, and the default stream name **myStream** is:

<https://example.com/live/smil:myStream.smil/playlist.m3u8>

If **cmafstreamingpacketizer** and **cupertinostreamingpacketizer** are both enabled, the adaptive bitrate LL-HLS playlist URL for the same example is:

<https://example.com/live/smil:myStream.smil/playlist_sfm4s.m3u8>

and the playback URL for the Cupertino HLS stream is either:

<https://example.com/live/smil:myStream.smil/playlist.m3u8>

or

<https://example.com/live/smil:myStream.smil/playlist_sfts.m3u8>

where **\_sfts** indicates that the media playlist contains .ts segments.

## Configure THEOplayer to play your LL-HLS stream

1. Set up a basic app with THEOplayer. See "[Getting started on Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/getting-started.md)".
2. Specify the LL-HLS stream generated above as the `src` of your typed source.
3. Set `lowLatency` to `true` on that source.

```kotlin
val typedSource = TypedSource.Builder("https://5d6e17f1ca731.streamlock.net/LowLatencyBBB/myStream/playlist.m3u8")
    .type(SourceType.HLS)
    .lowLatency(true)
    .build()

theoPlayerView.player.source = SourceDescription.Builder(typedSource).build()
```

## Resources

* [Getting Started with Wowza Streaming Engine](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/)
* [Deliver Apple Low-Latency HLS live streams using Wowza Streaming Engine](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine)

---

# Media tracks on Android

The articles in this section describe how to implement common use-cases related to audio and video tracks, such as switching between audio languages, or selecting a specific video quality.

The MediaTrack API, and its AudioTrack and VideoTrack sub-APIs, allow you to programmatically enable and disable audio tracks, inspect the available video qualities, override the ABR algorithm and more.

## Related articles

* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/enable-disable-audio-tracks.md)
* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-audio-tracks.md)
* [How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-audio-track-changes.md)
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/select-video-track-quality.md)
* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-video-track-qualities.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-video-track-quality-changes.md)
* [How to reduce data usage on mobile devices](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/reduce-data-usage.md)
* [How to start with a specific quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/start-with-specific-quality.md)

---

# How to programmatically enable or disable audio tracks on Android

This article describes how you can use the AudioTrack API, a sub-API of the MediaTrack API, to enable or disable audio tracks. Implementing this functionality is a common use-case for developers who want to build their own UI to toggle audio languages on and off.

Once you have programmatically selected a track, you can set its `enabled` property (or method) to `true` or `false`. Because only one audio track can play at a time, enabling an audio track automatically disables all other audio tracks. Note that this does not apply to text tracks: multiple text tracks can be active at the same time.

## Usage

The Android SDK exposes the audio tracks through [`player.getAudioTracks()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#getAudioTracks\(\)), which contains [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrack) objects with a [`setEnabled`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrack#setEnabled\(boolean\)) method.

```kotlin
// enable a specific audio track
player.audioTracks.getItem(indexOfRequestedAudioTrack).isEnabled = true
```

## Related articles

* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-audio-tracks.md)
* [How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-audio-track-changes.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/build-chromeless-ui.md)

---

# How to programmatically detect audio tracks on Android

This article describes how you can use the AudioTrack API, a sub-API of the MediaTrack API, to detect audio tracks. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available audio languages.

## Usage

Listen for the [`ADDTRACK`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/mediatrack/audio/list/AudioTrackListEventTypes#ADDTRACK) event on [`player.getAudioTracks()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#getAudioTracks\(\)) to detect every [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrack) that is added to the player.

```kotlin
player.audioTracks.addEventListener(AudioTrackListEventTypes.ADDTRACK) { addTrackEvent ->
    val audioTrack = addTrackEvent.track
}
```

## Related articles

* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/enable-disable-audio-tracks.md)
* [How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-audio-track-changes.md)
* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-video-track-qualities.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/build-chromeless-ui.md)

---

# How to programmatically select a video track quality on Android

This article describes how you can use the VideoTrack API, a sub-API of the MediaTrack API, to select a video track quality. If you select a specific quality, you overrule the ABR algorithm.

Implementing this functionality is a common use-case for developers who want to build their own UI to toggle a specific video quality.

## Usage

Set the [`targetQuality`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrack#setTargetQuality\(Q\)) or [`targetQualities`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrack#setTargetQualities\(java.util.List\)) of a [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrack).

```kotlin
val videoTrack = player.videoTracks.getItem(0)

// enable a specific video track quality
videoTrack.targetQuality = videoTrack.qualities.getItem(indexOfRequestedVideoTrackQuality)

// do ABR on a set of qualities:
// the ABR algorithm only selects qualities belonging to the given list
videoTrack.targetQualities = listOf(
    videoTrack.qualities.getItem(0),
    videoTrack.qualities.getItem(1),
)

// set to default ABR algorithm
videoTrack.targetQualities = emptyList()
```

## Related articles

* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-video-track-qualities.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-video-track-quality-changes.md)
* [How to reduce data usage on mobile devices](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/reduce-data-usage.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/build-chromeless-ui.md)

---

# How to programmatically detect video track qualities on Android

This article describes how you can use the VideoTrack API, a sub-API of the MediaTrack API, to detect video track qualities. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available video track qualities.

## Usage

The [`qualities`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrack#getQualities\(\)) of a video track are available as soon as the track is added to [`player.getVideoTracks()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#getVideoTracks\(\)).

```kotlin
player.videoTracks.addEventListener(VideoTrackListEventTypes.ADDTRACK) { addTrackEvent ->
    val videoTrackQualities = addTrackEvent.track.qualities
}
```

## Related articles

* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/select-video-track-quality.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-video-track-quality-changes.md)
* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-audio-tracks.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/build-chromeless-ui.md)

---

# How to start with a specific quality on Android

This article describes how you can start playback with a specific quality. Developers typically want their HLS or MPEG-DASH stream to start with a specific rendition of the manifest to speed up the time-to-first-frame, to serve a better quality to the customer, or to serve a different quality on different platforms.

## Usage

When the `ADDTRACK` event is dispatched, THEOplayer has not started buffering yet, so you can still adjust the [`targetQuality`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrack#setTargetQuality\(Q\)). You reset the ABR selection by setting `targetQuality` to `null`.

```kotlin
val progressListener = object : EventListener<ProgressEvent> {
    override fun handleEvent(event: ProgressEvent) {
        val buffered = player.buffered
        // switch to normal ABR when THEOplayer buffered beyond 10 seconds
        if (buffered.length() > 0 && buffered.getEnd(buffered.length() - 1) > 10) {
            player.videoTracks.getItem(0).targetQuality = null
            player.removeEventListener(PlayerEventTypes.PROGRESS, this)
        }
    }
}

player.videoTracks.addEventListener(VideoTrackListEventTypes.ADDTRACK) {
    val videoTrack = player.videoTracks.getItem(0)
    // start with a specific quality
    videoTrack.targetQuality = videoTrack.qualities.getItem(0)
    player.addEventListener(PlayerEventTypes.PROGRESS, progressListener)
}
```

## Related articles

* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/select-video-track-quality.md)
* [How to reduce data usage on mobile devices](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/reduce-data-usage.md)

---

# How to reduce data usage on mobile devices on Android

Customers who leverage THEOplayer's preloading capabilities (`preload = "auto"`), or who provide very high qualities, sometimes receive complaints about data usage on mobile devices. You can combat this by leveraging the ABR API and the MediaTrack API, as described in the steps below.

## 1. Lower the target buffer

The target buffer is the amount of seconds which the player buffers ahead of the current playback position. The standard buffer time is 20 seconds. Setting a lower number (e.g. 6 seconds) allows you to download less information in front of the playhead position. This value is also used when preloading content.

Use the [`targetBuffer`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/abr/Abr#setTargetBuffer\(int\)) property of the [ABR API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/abr/Abr) to set it to 6 seconds:

```kotlin
player.abr.targetBuffer = 6
```

## 2. Manage preloading

Preloading is a powerful feature when trying to reduce the join time. It is more effective in some situations than others, and managing it correctly helps you reduce the data usage:

* preloading a live stream may entail appending information in the buffer that will never be played, if the user waits long enough before clicking "Play";
* in those situations when a user is not yet likely to be playing a stream (e.g. the player is not yet in view), preloading may also mean downloading information that the user will not consume.

So, based on your use case, you might decide whether to enable preloading.

```kotlin
player.preload = PreloadType.AUTO
```

## 3. Choose the renditions considered for ABR

On mobile devices, THEOplayer by default takes into account the player size for ABR: this lets it avoid selecting renditions too big to be appreciated on the current device, thus avoiding wasting data.

Leveraging the target quality of the MediaTrack API, you can refine the rendition choice further and indicate yourself to the player which qualities should be considered for ABR. For example, you could configure that THEOplayer should only do ABR on the lowest 3 qualities of a stream containing 5.

See [how to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/select-video-track-quality.md) to learn how to set the [`targetQuality`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrack#setTargetQuality\(Q\)) of a video track.

## Conclusion

There are several actions that can be taken to drastically reduce data usage on mobile devices, both in the player and at other levels. As far as the player is concerned, by leveraging its API as described you can filter different use cases and handle several aspects related to media download for each use case. This enables you to manage the precise behavior in each case and optimize data usage.

## Related articles

* [How to start with a specific quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/start-with-specific-quality.md)
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/select-video-track-quality.md)
* [Preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/preloading.md)

---

# How to programmatically detect video track quality changes on Android

This article describes how you can use the VideoTrack API, a sub-API of the MediaTrack API, to detect video track quality changes. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the video track quality that is currently active.

## Usage

Listen for the [`ACTIVEQUALITYCHANGEDEVENT`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/mediatrack/video/VideoTrackEventTypes#ACTIVEQUALITYCHANGEDEVENT) event of a [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrack).

```kotlin
// detect video tracks being added to the player
player.videoTracks.addEventListener(VideoTrackListEventTypes.ADDTRACK) { addTrackEvent ->
    // detect quality changes of a track
    addTrackEvent.track.addEventListener(VideoTrackEventTypes.ACTIVEQUALITYCHANGEDEVENT) { event ->
        println("activequalitychanged event detected! ${event.quality}")
    }
}
```

## Related articles

* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-video-track-qualities.md)
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/select-video-track-quality.md)
* [How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-audio-track-changes.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/build-chromeless-ui.md)

---

# How to programmatically detect audio track changes on Android

This article describes how you can use the AudioTrack API to detect audio track changes. An audio track "change" is triggered by enabling (or disabling) an audio track.

Implementing this functionality is a common use-case for developers who want to build their own UI, and annotate the audio track that is currently active.

## Usage

The implementation of the Android SDK applies to all Android-based platforms, including Android TV and Fire TV.

The Android SDK exposes the AudioTrack API through [`player.getAudioTracks()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#getAudioTracks\(\)). This `getAudioTracks()` method returns a [`MediaTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrackList) that inherits from the [`TrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/TrackList). This `TrackList` dispatches the events from the [`AudioTrackListEventTypes`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/mediatrack/audio/list/AudioTrackListEventTypes). The `AudioTrackListEventTypes` contains the [`TRACKLISTCHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/mediatrack/audio/list/AudioTrackListEventTypes#TRACKLISTCHANGE) event, as well as the `ADDTRACK` and `REMOVETRACK` event.

The code below allows you to detect audio track changes.

```kotlin
player.audioTracks.addEventListener(AudioTrackListEventTypes.TRACKLISTCHANGE) { event ->
    val track = event.track
    println("${track.label}, ${track.language}, ${track.isEnabled}")
}
```

The properties of a media `track` (e.g. `enabled`, `language`) are described in the [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrack) and [`Track`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/Track) API references.

## Related articles

Are you reading this article because you are interested in audio tracks? Continue reading below.

* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-audio-tracks.md)
* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/enable-disable-audio-tracks.md)

Are you reading this article because you are implementing a custom UI? Then you will find the following articles interesting:

* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/build-chromeless-ui.md)
* [How to detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-video-track-quality-changes.md)
* [How to detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-text-track-changes.md)

---

# Miscellaneous on Android

In this section, you can find guides on how to use many of the player features that are not addressed in the other sections of this documentation.

## [📄️Picture-in-Picture](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/picture-in-picture.md)

[On Android and Fire TV, there is no API to explicitly only allow in-app Picture-in-Picture:](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/picture-in-picture.md)

## [📄️HLS date ranges](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/hls-date-range.md)

[Enabling date ranges](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/hls-date-range.md)

## [📄️Preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/preloading.md)

[Usage](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/preloading.md)

## [⚠️Error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/error/introduction.md)

[3 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/error/introduction.md)

---

# Picture-in-Picture on Android

The Picture-in-Picture (PiP) feature allows you to create a floating player. This is commonly used to let the video remain playing on screen even if:

* The user scrolls to another section of the page (causing the original player to no longer be visible).
* The user sends the application to the background.
* The user opens a new page within the same application.

THEOplayer distinguishes two flavors of Picture-in-Picture:

* With **in-app** Picture-in-Picture, the visibility of the PiP window is contained to the inside of the app. In other words, it goes to background and foreground together with the application.
* With **out-of-app** Picture-in-Picture, the visibility of the PiP window is not contained to the inside of the app. It can remain visible while the user navigates to other views, pages or apps.

Picture-in-Picture is a presentation mode of the player. As such, you can listen for a `presentationmodechange` event, or read the player's presentation mode, to find out what the presentation mode is at a given moment or to detect a change.

On Android and Fire TV, there is no API to explicitly only allow in-app Picture-in-Picture: the [PiP API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/pip/package-summary) always activates out-of-app Picture-in-Picture as well. Note that the minimum required Android version for out-of-app PiP is Oreo (API level 26).

## Enabling Picture-in-Picture

Instantiate the player with a `PipConfiguration`, passed in the `THEOplayerConfig`.

```kotlin
val playerConfig = THEOplayerConfig.Builder()
    .pipConfiguration(PipConfiguration.Builder().build())
    .build()

val theoPlayerView = THEOplayerView(context, playerConfig)
```

Once Picture-in-Picture is enabled, you can enter it through the PiP manager of your `THEOplayerView`.

```kotlin
theoPlayerView.piPManager?.enterPiP(PiPType.ACTIVITY)
```

THEOplayer supports three PiP types:

* **ACTIVITY**: this mode generates a separate Android activity that functions as the PiP window.
* **DIALOG**: in this mode, a dialog window is used as the PiP window. The video content is displayed within the dialog.
* **CUSTOM**: unlike the predefined PiP types, `CUSTOM` allows you to design and implement your own PiP window. For details on implementing a custom PiP window, explore this [Android documentation](https://developer.android.com/develop/ui/views/picture-in-picture).

## Observing Picture-in-Picture

Listen for the `PRESENTATIONMODECHANGE` event, or read the presentation mode of the player, to find out what the presentation mode is at a given moment or to detect a change.

```kotlin
theoPlayerView.player.addEventListener(PlayerEventTypes.PRESENTATIONMODECHANGE) { event ->
    if (event.presentationMode == PresentationMode.PICTURE_IN_PICTURE) {
        // Currently in PiP
    }
}

// The listener above is triggered by one of:
theoPlayerView.piPManager?.enterPiP(PiPType.ACTIVITY)
theoPlayerView.piPManager?.exitPiP()
```

## Returning from Picture-in-Picture

### ACTIVITY PiP type

When your app uses the `ACTIVITY` PiP type and the user closes the PiP window, playback is automatically paused, provided that `theoPlayerView.settings.setAllowBackgroundPlayback(false)` is set to `false` (which is the default setting).

To resume playback, check whether your app's activity is in the foreground. If it is, call the `play()` method on the player instance.

```kotlin
theoPlayerView.player.addEventListener(PlayerEventTypes.PRESENTATIONMODECHANGE) { event ->
    if (event.presentationMode == PresentationMode.INLINE) {
        // Playback pauses after closing the PiP window
        if (lifecycle.currentState == Lifecycle.State.STARTED) {
            theoPlayerView.player.play()
        }
    }
}
```

### DIALOG PiP type

For the `DIALOG` PiP type, in order to correctly exit the PiP window, you should override `onPictureInPictureModeChanged` and call `piPManager.exitPiP()`.

```kotlin
override fun onPictureInPictureModeChanged(
    isInPictureInPictureMode: Boolean,
    newConfig: Configuration
) {
    super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)

    if (!isInPictureInPictureMode) {
        theoPlayerView.piPManager?.exitPiP()
    }
}
```

This example ensures that playback pauses if the activity that holds THEOplayer is in the background and background playback is not allowed, providing a smoother transition for users returning from PiP mode.

### CUSTOM PiP type

For the `CUSTOM` PiP type, you are responsible for implementing your own PiP window and handling the necessary tasks for entering and exiting PiP mode. Managing playback after returning from PiP mode is in your hands as a developer. You can use the code snippet for the `ACTIVITY` type as a starting point, and adapt it to match your app's unique design and logic.

## Known limitations

* Android TV: when the player is showing a native Google IMA advertisement while being in Picture-in-Picture mode, and the user triggers something which moves the PiP window (such as opening the keyboard), then the view showing the advertisement might be misaligned. This is a limitation of the Android framework.

## Resources

* [PipConfiguration API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/pip/PipConfiguration.Builder)
* [PiPManager API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/pip/PiPManager)
* [Sample application](https://github.com/THEOplayer/samples-android-sdk/tree/master/pip-handling)

---

# HLS date ranges on Android

The `#EXT-X-DATERANGE` tag associates a date range (i.e. a range of time defined by a starting and ending date) with a set of attribute/value pairs. It is a way of providing timed metadata in an HLS manifest. A possible use case is defining timed metadata for interstitial regions such as advertisements, but it can be used for any timed metadata needed by your stream.

Date ranges are not parsed by default. To enable them, set `hlsDateRange` to `true`, either on the player configuration (for all sources) or on an individual source.

Once enabled, the player exposes the date ranges as cues on a metadata text track, which you can consume through the text tracks API.

## Enabling date ranges

```kotlin
// in the player configuration
val playerConfig = THEOplayerConfig.Builder()
    .hlsDateRange(true)
    .build()
val theoPlayerView = THEOplayerView(this, playerConfig)

// or in the source description
val typedSource = TypedSource.Builder("https://example.com/example-stream.m3u8")
    .hlsDateRange(true)
    .build()
```

## Reading date range cues

Date ranges are exposed as cues on a metadata text track. See "[How to detect active text track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-active-text-track-cues.md)" to learn how to listen for those cues.

## Resources

* [HLS specification: EXT-X-DATERANGE](https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.2.7)

---

# Preloading on Android

The aim of preloading is to improve the user experience by loading parts of the video before the play button is hit, when the user is likely to play the video.

Choosing to preload your video content reduces the start-up time of your videos. It also makes some data regarding the current source (video duration, timeline thumbnails, etc.) available before the user initiates playback. On the other hand, when the video is less likely to be played, or when it is less beneficial (live video, autoplay), you can configure the player to not preload it and save bandwidth.

## Preloading settings

| Value      | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none`     | Do not preload anything. After setting the source, the player does not load the manifest nor any media files until the play method is invoked on the player.                                                                                                                                                                                                                           |
| `metadata` | Preload the metadata of the video. After setting the source, the player automatically loads the manifest file and waits for loading media files until the play method is invoked on the player. For static videos (e.g. MP4 files), this translates to preloading data from the start of the video in order to acquire e.g. the video's width and height and the initial video frames. |
| `auto`     | Preload enough data to allow for smooth initial playback. After setting the source, the player loads both the manifest files and enough media files until a sufficient playback buffer has been obtained.                                                                                                                                                                              |

## Usage

In this example, we are preloading metadata only.

```kotlin
import com.theoplayer.android.api.player.PreloadType

theoPlayerView.player.preload = PreloadType.METADATA
```

## Remarks

* THEOplayer always prefers downloading data for the currently playing video over downloading data for a preloading video. Only when the currently playing video has enough data to play to the end of the video, does the player start preloading other videos.
* When preloading the first segment(s) (preload `auto`), the first frame of the video is shown under the big play button, if there is no poster.

## Resources

* [What are the benefits of preloading?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-are-the-benefits-of-preloading.md)
* [PreloadType API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/PreloadType)

---

# Errors on Android

We live in an imperfect world, and sometimes things go wrong. A viewer might not be able to watch a video stream for a variety of reasons. Some example reasons are:

* The video stream is unavailable,
* The video stream is not supported on the selected platform,
* The THEOplayer license is incorrectly configured.

**When an issue occurs, an error should be triggered**.

When a fatal playback issue occurs, THEOplayer exposes information about the error through the THEOplayer API. This allows you to detect errors: as a developer, you can use an event handler to catch (and handle) `error` events. This feature (i.e. being able to intercept errors and act on it) may be mandatory to you to achieve a use-case:

* You want to log the error on an analytics stack,
* You want to show your own error message to the viewer,
* ...

THEOplayer associates error codes with errors to categorize types of issues. As a developer, these error codes may help you to log an error on an analytics stack, or may help you to generate a custom error message towards your viewer.

## Related resources

* [How to do error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/error/error-handling.md): this article explains how you use event listeners to intercept the `error` event.
* [Error codes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/error/error-codes.md): this article explains what error codes are, and why they are useful.

---

# How to do error handling on Android

As a developer, you could be interested in error handling for any of the following reasons:

* You want to render human-friendly error messages inside the video player. Reading this error message,

  * the user can either remediate the issue by themselves (e.g. by refreshing the page, by checking again in some time, ...),
  * or contact a support service with this error code.

* You want to send error-data to an analytics service. (And this service helps you to identify frequent issues.)

* You want to self-remediate the issue. For example, if a stream is unavailable, you want to retry to load the stream, or load a different stream.

* ...

THEOplayer exposes different types of errors, and you can interact with them in two ways:

1. Through an event listener, and attaching an event handler to this listener.
2. Through a getter, which holds data when an error has occurred.

The sections below describe the "top-level", "generic", "player" `error` event. This event is fatal and prevents playback. There are also other `error` events, for example the one dispatched by the Chromecast API. You handle those `error` events in the same fashion.

## Event listener

Subscribe to the [`ERROR`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/player/PlayerEventTypes#ERROR) event of the player, and attach a listener which implements the error handling. The [`THEOplayerException`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/error/THEOplayerException) causing the error is available through [`getErrorObject()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/player/ErrorEvent#getErrorObject\(\)).

```kotlin
theoPlayerView.player.addEventListener(PlayerEventTypes.ERROR) { event ->
    println(event.errorObject)
}
```

## Getter

You can query the last error that occurred for the current source through [`player.error`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#getError\(\)).

```kotlin
println(theoPlayerView.player.error)
```

## Types of errors

"[Which error related events does the player expose](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/which-error-related-events-does-player-expose.md)" lists which types of errors there are. Note that generally speaking only the "generic error event" is fatal. Other events, like the "Chromecast error event" and the "ad error event", are considered non-fatal because some type of playback can still continue.

"[Error codes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/error/error-codes.md)" lists which error codes are available for the "generic error event".

---

# Error codes on Android

THEOplayer has different types of error events. One of those error events is the "generic player error event". This error event indicates a fatal error, and can be intercepted through the player.

This error event exposes an "error code" to explain the occurred error. An error code may be more interesting to track than a verbose error message. For example, if you are logging errors through an analytics service, it could be useful to filter them by their error code.

An error code is a number (e.g. 2001), and it belongs to a category. The format of an error code is "\[category]\[sub-code]". For example, error "2001" belongs to category 2, and has sub-code 001. If the error is a generic sub-code for its category, then the sub-code is `000`. In other words, error `11000` is the "catch-all" for category `11`.

## Categories

Each error code belongs to an error category. At the time of writing, there are 11 categories.

1. Configuration error: the integrator misconfigured the player.
2. License error: the player license is no longer valid, incorrect or not provided.
3. Source invalid: the source is not valid, or cannot be played on the current platform.
4. Manifest load error: the manifest cannot be loaded or parsed.
5. Media not supported: the media cannot be played on the current platform.
6. Network error: the network timed out, or is not available.
7. Content protection error: anything DRM related. Key system is not supported, invalid license, license expired, key missing, output restricted...
8. Subtitle load error: the subtitles cannot be loaded or parsed...
9. VR not supported: VR is not available on the current platform, VR presentation cannot be switched.
10. Ad blocker detected: an ad has been blocked (or the third party CSAI library was not loaded).
11. Fullscreen error: switching to fullscreen is not possible (note: this may be the case when fullscreen was not triggered by user interaction).

Refer to "[How to do error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/error/error-handling.md)" to learn how to detect the "generic player error event".

## Requesting categories and codes

The error category of an error code is available through [`ErrorCategory.fromCode()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/error/ErrorCategory#fromCode\(com.theoplayer.android.api.error.ErrorCode\)).

## API references

* [`ErrorCategory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/error/ErrorCategory)
* [`ErrorCode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/error/ErrorCode)

---

# Network on Android

THEOplayer makes a number of network requests, and receives responses, while it is loading and playing a stream. The Network API allows you to intercept those requests and responses, so you can inspect them, modify them, redirect them, or respond with your own data.

Common use cases are adding authentication headers or query parameters to segment requests, redirecting requests to another CDN, or rewriting a manifest before the player parses it.

The Android SDK exposes this API through [`player.network`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#getNetwork\(\)).

## Related articles

* [How to add and remove request and response interceptors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/network/request-response-interceptors.md)

---

# How to add and remove request and response interceptors on Android

A *request interceptor* runs before the player opens the connection, so it can change properties of the request such as its URL, method, headers or body. It can also respond to the request immediately, without contacting the server.

A *response interceptor* runs before the player consumes the response, so it can change the status, the headers or the body of the response.

## Prerequisites

This guide assumes that you already have THEOplayer set up in your app. If not, start with our [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/getting-started.md).

## Adding and removing an interceptor

The Android SDK provides the [`HTTPInterceptor`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/network/http/HTTPInterceptor) interface, which contains two methods that you can implement depending on your use case:

* `suspend fun onRequest(request: InterceptableHTTPRequest)`: intercepts an HTTP request before opening the connection.
* `suspend fun onResponse(response: InterceptableHTTPResponse)`: intercepts an HTTP response before consuming the response body.

To start intercepting HTTP requests, add the interceptor to the Network API:

```kotlin
theoPlayerView.player.network.addHTTPInterceptor(httpInterceptor)
```

To stop intercepting HTTP requests, remove the interceptor again:

```kotlin
theoPlayerView.player.network.removeHTTPInterceptor(httpInterceptor)
```

## Intercepting a request

The [`request`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/network/http/InterceptableHTTPRequest) parameter of `onRequest` allows you to read and write properties of the request, or to interrupt the request by responding to it directly.

The snippet below shows some common use cases.

```kotlin
override suspend fun onRequest(request: InterceptableHTTPRequest) {
    // Read request properties
    Log.d("Interceptor", "onRequest - url: ${request.url}")

    // Add/override request headers
    request.headers["newKey"] = "newValue"

    // Replace properties
    request.method = "GET|POST|.."
    request.url = URL("new_url")
    request.headers = HashMap()

    // Replace POST/PUT request body
    request.body = "new post body".toByteArray()

    // Perform another async computation
    delay(1000) // simulating an async call

    // Interrupt the request and respond with a CompleteHTTPResponse
    request.respondWith(
        CompleteHTTPResponse(
            request,
            request.url,
            request.headers,
            200,
            "OK",
            "new post body".toByteArray()
        )
    )
}
```

## Intercepting a response

The [`response`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/network/http/InterceptableHTTPResponse) parameter of `onResponse` allows you to read and write properties of the received response.

The snippet below shows some common use cases.

```kotlin
override suspend fun onResponse(response: InterceptableHTTPResponse) {
    // Read response properties
    Log.d("Interceptor", "onResponse - headers: ${response.headers}")

    // Add/override response headers
    response.headers["newKey"] = "newValue"

    // Replace properties
    response.url = URL("new_url")
    response.headers = HashMap()
    response.status = 200
    response.statusText = "OK"

    // Get the chunks of the response body as they are read from the HTTP connection
    response.onChunk { chunk: ByteArray ->
        Log.d("Interceptor", "onResponse - onChunk: ${chunk.size}")
        delay(100)
        chunk
    }

    // Read the complete response body
    response.onBody { body: ByteArray ->
        Log.d("Interceptor", "onResponse - onBody: ${body.size}")

        // Read response body
        val string = body.decodeToString()
        val json = JSONObject(string)

        // Perform another async computation
        delay(1000) // simulating an async call

        // Replace response body
        "new response body".toByteArray()
    }
}
```

## Related articles

* [Network introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/network/introduction.md)

---

# Player on Android

The Player API is the top-level API. This API exposes:

* basic functions to manipulate video playback, such as start and pause;
* properties to check states and values, such as the playhead position;
* events to track changes.

## Events

As a developer, you can programmatically attach event listeners to different APIs. Event listeners are often used to implement a custom UI, or to implement a custom analytics integration.

The THEOplayer API exposes many events across different interfaces, as can be seen in the graphic below. Furthermore, most events exist in all SDKs (Web, iOS-based, Android-based and Roku).

![THEOplayer API Interfaces and Events](/pr-932/assets/images/analytics-events-185d6ab52b556af08d8300b545ae5876.png "THEOplayer API Interfaces and Events")

Our APIs are continuously evolving, and so is our list of events. Refer to [the `PlayerEventTypes` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/player/PlayerEventTypes) to go through the latest set of player events, and to [the Android SDK API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android) for the events of the other interfaces.

## Related articles

* [How do you know when a stream or an advertisement is playing?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/player/detect-stream-or-ad-playing.md)
* [How to measure the time-to-first-frame](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/player/measure-time-to-first-frame.md)
* [How to track the first play(ing) event](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/player/track-first-playing-event.md)
* [How to track player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/player/track-player-states.md)

---

# How do you know when a stream or an advertisement is playing on Android?

This guide explains how to determine programmatically when the player is playing, and whether it is playing a stream or a client-side advertisement. This is useful when you want different behavior, or a different UI, for content and for advertisements.

The `playing` event tells you when content or an advertisement starts playing. Its event handler is the right place to check whether an advertisement is playing.

This approach only works for client-side advertisements, not for server-side advertisements.

## Usage

The Android SDK exposes whether an advertisement is playing through [`player.ads.isPlaying()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/ads/Ads#isPlaying\(\)).

```kotlin
player.addEventListener(PlayerEventTypes.PLAYING) { event ->
    val adIsPlaying = player.ads.isPlaying
    println("PLAYING " + if (adIsPlaying) "Advertisement" else "Content")
}
```

## Related articles

* [How to track the first play(ing) event](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/player/track-first-playing-event.md)

---

# How to measure the time-to-first-frame on Android

The time-to-first-frame, also known as the start-up time, is the time between the moment where playback is requested and the moment where the first frame is rendered.

To measure it, measure the time between the `play` event and the `playing` event.

## Usage

```kotlin
var playEventRegisteredAt = 0L

val playListener = object : EventListener<PlayEvent> {
    override fun handleEvent(event: PlayEvent) {
        player.removeEventListener(PlayerEventTypes.PLAY, this)
        playEventRegisteredAt = System.currentTimeMillis()
    }
}

val playingListener = object : EventListener<PlayingEvent> {
    override fun handleEvent(event: PlayingEvent) {
        player.removeEventListener(PlayerEventTypes.PLAYING, this)
        val timeToFirstFrame = System.currentTimeMillis() - playEventRegisteredAt
        println("Time-to-first-frame: $timeToFirstFrame")
    }
}

player.addEventListener(PlayerEventTypes.PLAY, playListener)
player.addEventListener(PlayerEventTypes.PLAYING, playingListener)
```

---

# How to track the first play(ing) event on Android

Sometimes you want to know when a new stream starts playing for the first time, for example to forward a `firstplay` event to an analytics back-end. THEOplayer does not expose such an event, but you can implement it yourself, which gives you more control over its logic.

The implementation below listens for the first `playing` event after every source change. If the viewer pauses and resumes the stream, the event is not dispatched again. If the viewer switches to another stream, it is dispatched once more.

You can swap out the `playing` event for a `play` event, or for any other event for that matter.

## Usage

```kotlin
val firstPlayingListener = object : EventListener<PlayingEvent> {
    override fun handleEvent(event: PlayingEvent) {
        player.removeEventListener(PlayerEventTypes.PLAYING, this)
        println("First playing event!")
    }
}

player.addEventListener(PlayerEventTypes.SOURCECHANGE) {
    player.removeEventListener(PlayerEventTypes.PLAYING, firstPlayingListener)
    player.addEventListener(PlayerEventTypes.PLAYING, firstPlayingListener)
}
```

Instead of `SOURCECHANGE`, you can also listen for `LOADEDMETADATA`, which is dispatched once the player has loaded the metadata of the new stream.

## Related articles

* [How do you know when a stream or an advertisement is playing?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/player/detect-stream-or-ad-playing.md)

---

# How to track player states on Android

A video player has states. As a developer, you should understand these states, as each state grants you access to different data, and might imply a re-render of your UI. For example, if your video player is in the "Paused" state, you want to show a play-button instead of a pause-button.

The objective of this guide is to define some video player states, and how to track the transition between states.

Although there's no official list of video player states, we'll define 11 states for learning purposes. These 11 states are visualized in the state diagram below.

![Video Player States](/pr-932/assets/images/player-video-player-states-4f4f37f92d4b03a2c750ce7fe03d0a5a.png "Video Player States")

The table below provides the definitions of these 11 states.

| State                            | Description                                                                                                                                                                                                                                                                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A: Empty                         | A state where the player is created, but has no information or data retained on the source which is to be played. The player is idle and not undertaking any interaction with the system.                                                                                                                                                         |
| B: Initialized                   | A state where the player knows the source which is to be played, but no media data is loaded. The player is idle and not undertaking any interaction with the system.                                                                                                                                                                             |
| C: Playing - HAVE\_NOTHING       | A state where the player wants to start playing a source, but has no media data available. The player is actively loading media data in order to initiate playback.                                                                                                                                                                               |
| D: Paused - HAVE\_NOTHING        | A state where the player wants to fill its buffer without playing, but has no media data available. The player is actively loading media data in order to fill its buffer.                                                                                                                                                                        |
| E: Playing - HAVE\_METADATA      | A state where the player wants to start playing a source, but only metadata is available and the entire buffer is still empty. The player knows which tracks and qualities are available. The player is actively loading media data in order to initiate playback.                                                                                |
| F: Paused - HAVE\_METADATA       | A state where the player wants to fill its buffer without playing, but only metadata is available and the entire buffer is still empty. The player knows which tracks and qualities are available. The player is actively loading media data in order to fill its buffer.                                                                         |
| G: Playing - HAVE\_CURRENT\_DATA | A state where the player wants to start playing a source and has media data in its buffer for the current timestamp, but this data is insufficient to start playback and guarantee a smooth viewer experience. The player is actively loading media data in order to initiate playback.                                                           |
| H: Paused - HAVE\_CURRENT\_DATA  | A state where the player wants to fill its buffer without playing and has media data in the buffer for the current timestamp, but this data is insufficient to start playback and guarantee a smooth viewer experience. The player is actively loading media data in order to fill its buffer.                                                    |
| I: Playing                       | A state where the player is actively rendering out media data. The current timestamp is progressing at the speed of the current playback rate and media buffer data is being consumed and loaded in parallel. timeupdate events will be dispatched regularly during playback and progress events will be dispatched as additional data is loaded. |
| J: Paused                        | A state where the player has sufficient media data in its buffer in order to guarantee a smooth viewer experience when playback is started, but it is in a paused state. The player is not consuming any media data, but might be loading additional media data to grow its buffer in the background.                                             |
| K: Error                         | A state where the player has observed a fatal, non recoverable error. The player cannot continue playback and needs to be initialized again in order to restart playback. A player can get into this state from any state other than the Empty-state.                                                                                             |

The table below explains what triggers each of the 26 transitions between states, and what video player events are related.

| Transition | Triggers                                                                                                   | Events                                                                                                                                                    |
| ---------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1          | `new THEOplayer.Player`                                                                                    |                                                                                                                                                           |
| 2          | `player.source = X`                                                                                        | `sourcechange`, `currentsourcechange`                                                                                                                     |
| 3          | `player.play()`                                                                                            | `play`, `loadstart`                                                                                                                                       |
| 4          | `player.load()`                                                                                            | `loadstart`                                                                                                                                               |
| 5          | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 6          | `player.play()`                                                                                            | `play`                                                                                                                                                    |
| 7          | The stream manifest being loaded                                                                           | `readystatechange`, `loadedmetadata`, `durationchange`                                                                                                    |
| 8          | The stream manifest being loaded                                                                           | `readystatechange`, `loadedmetadata`, `durationchange`                                                                                                    |
| 9          | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 10         | `player.play()`                                                                                            | `play`                                                                                                                                                    |
| 11         | Stream media data is loaded                                                                                | `readystatechange`, `loadeddata`, `progress`, `canplay`                                                                                                   |
| 12         | Stream media data is loaded                                                                                | `readystatechange`, `loadeddata`, `progress`, `canplay`                                                                                                   |
| 13         | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 14         | `player.play()`                                                                                            | `play`                                                                                                                                                    |
| 15         | Sufficient media data is loaded to start playback fluently.                                                | `progress`, `canplaythrough`, `readystatechange`, `playing`<br />*A `seeked` event can be dispatched if the entrance of this state was caused by a seek.* |
| 16         | Sufficient media data is loaded to start playback fluently.                                                | `canplaythrough`, `readystatechange`<br />*A `seeked` event can be dispatched if the entrance of this state was caused by a seek.*                        |
| 17         | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 18         | `player.play()`                                                                                            | `play`, `playing`                                                                                                                                         |
| 19         | `player.currentTime = X` and there is some media data at the target time, but not enough to play fluently. | `seeking`, `readystatechange`                                                                                                                             |
| 20         | The player buffer is not being filled enough, causing a stall.                                             | `waiting`, `readystatechange`                                                                                                                             |
| 21         | `player.currentTime = X` and there is no media data at the target time.                                    | `seeking`, `readystatechange`                                                                                                                             |
| 22         | Playback has ended.                                                                                        | `ended`, `readystatechange`                                                                                                                               |
| 23         | `player.currentTime = X` and there is some media data at the target time, but not enough to play fluently. | `seeking`, `readystatechange`                                                                                                                             |
| 24         | `player.currentTime = X` and there is no media data at the target time.                                    | `seeking`, `readystatechange`                                                                                                                             |
| 25         | An error occurred.                                                                                         | `error`                                                                                                                                                   |
| 26         | `player.source = null`                                                                                     | `emptied`                                                                                                                                                 |

## Implementation

The code samples below demonstrate how you track some of the 18 events related to the state transitions.

* `sourcechange`
* `currentsourcechange`
* `play`
* `loadstart`
* `pause`
* `readystatechange`
* `loadedmetadata`
* `durationchange`
* `loadeddata`
* `progress`
* `canplay`
* `canplaythrough`
* `playing`
* `waiting`
* `seeking`
* `ended`
* `error`
* `emptied`

All 18 events are dispatched by the `Player` interface.

The snippet below demonstrates how you can track some of the related events through the Android SDK. All other events can be tracked similarly. You can find the event names in [the `PlayerEventTypes` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/player/PlayerEventTypes), and the properties of the player in [the `Player` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player). This approach is valid for all Android-based platforms, including Android TV and Fire TV.

```kotlin
player.addEventListener(PlayerEventTypes.SOURCECHANGE) { event ->
    println(event)
}
// ...
player.addEventListener(PlayerEventTypes.ENDED) { event ->
    println(event)
}
```

---

# Text tracks on Android

The articles in this section describe how to implement common use-cases related to text tracks, subtitles, closed captions and metadata. These use-cases can range from programmatically detecting new metadata, to side-loading subtitles.

THEOplayer supports

* subtitle and closed caption formats like WebVTT, CEA-608, DVB Subs and TTML;
* metadata formats like ID3, emsg, EventStream and `EXT-X-DATERANGE`.

The TextTrack API allows you to programmatically switch between text tracks, detect events related to text tracks (e.g. a new active cue) and more.

## Related articles

* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/change-visible-captions.md)
* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-text-tracks.md)
* [How to programmatically detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-text-track-changes.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/enable-disable-text-tracks.md)
* [How to detect active text track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-active-text-track-cues.md)
* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/insert-subtitles.md)
* [How to implement preview thumbnails](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/preview-thumbnails.md)
* [How to track ID3 cues/tags](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/track-id3-cues.md)

---

# How to dynamically change the visible captions on Android

This article describes how you can dynamically change the currently selected subtitle or closed captions language, or how you can set a default language.

This article assumes that you are using text tracks that are loaded with the manifest. If you add the text track separately, you can also mark it as the default track when you configure your source.

The examples below match tracks on their `language` property, which contains the ISO language code of the track. If that is not sufficient for your use case, for example when a stream contains multiple tracks with the same language, you can match on the track's `label` instead, which contains the human-readable name shown in your UI.

## Usage

The function below disables all text tracks which are currently active, and then enables the text track with the requested language.

```kotlin
fun setLanguage(player: Player, language: String) {
    for (textTrack in player.textTracks) {
        textTrack.mode = if (textTrack.language == language) {
            TextTrackMode.SHOWING
        } else {
            TextTrackMode.DISABLED
        }
    }
}
```

## Related articles

* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-text-tracks.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/enable-disable-text-tracks.md)
* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/insert-subtitles.md)

---

# How to programmatically detect text tracks on Android

This article describes how you can use the TextTrack API to detect text tracks, which can be subtitles, closed captions or metadata. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available subtitle languages.

## Usage

Listen for the [`ADDTRACK`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/texttrack/list/TextTrackListEventTypes#ADDTRACK) event on [`player.getTextTracks()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#getTextTracks\(\)) to detect every [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrack) that is added to the player.

```kotlin
player.textTracks.addEventListener(TextTrackListEventTypes.ADDTRACK) { addTrackEvent ->
    val textTrack = addTrackEvent.track
}
```

## Related articles

* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/enable-disable-text-tracks.md)
* [How to programmatically detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-text-track-changes.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/build-chromeless-ui.md)

---

# How to programmatically enable or disable text tracks on Android

This article describes how you can use the TextTrack API to enable or disable subtitles, closed captions or metadata. Implementing this functionality is a common use-case for developers who want to build their own UI to toggle subtitles.

It is advised to disable the text tracks which you do not want to display, in order to avoid issues with overlapping text.

## Usage

Set the [`mode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrack#setMode\(com.theoplayer.android.api.player.track.texttrack.TextTrackMode\)) of a [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrack).

```kotlin
// disable all text tracks
for (textTrack in player.textTracks) {
    textTrack.mode = TextTrackMode.DISABLED
}
// enable a specific text track
player.textTracks.getItem(indexOfRequestedTextTrack).mode = TextTrackMode.SHOWING
```

## Related articles

* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/change-visible-captions.md)
* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-text-tracks.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/build-chromeless-ui.md)

---

# How to insert subtitles on Android

This article describes how you can side-load subtitles or closed captions, i.e. how you can add text tracks which are not part of your HLS or MPEG-DASH manifest.

Every source description has a text tracks property, which accepts an array of side-loaded text tracks. All valid tracks are available for playback as long as the player's source is not set again.

Text track descriptions can also be used for other purposes, e.g. for including preview thumbnails and chapters.

## Usage

Each text track is described by a [`TextTrackDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/source/TextTrackDescription).

```kotlin
val sourceWithSubs = SourceDescription.Builder("//path/to/your-manifest.m3u8")
    .textTracks(
        TextTrackDescription.Builder("path/to/your-subs-track1.vtt")
            .isDefault(true)
            .kind(TextTrackKind.SUBTITLES)
            .srclang("en")
            .label("English subs")
            .build()
    )
    .build()
```

## Related articles

* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/change-visible-captions.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/enable-disable-text-tracks.md)
* [How to implement preview thumbnails](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/preview-thumbnails.md)

---

# How to implement preview thumbnails on Android

This article describes how you can enable preview thumbnails, which THEOplayer implements through the TextTrack API. The thumbnails are loaded as a separate text track, by side-loading them as a text track in your source description.

A demo of the preview thumbnails on the THEOplayer Web SDK is available at [preview thumbnails](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/preview-thumbnails.md).

## Usage

You can add or edit your source description as follows.

```kotlin
val sourceWithThumbnails =
    SourceDescription.Builder("https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8")
        .textTracks(
            TextTrackDescription.Builder("https://cdn.theoplayer.com/dash/theoplayer/thumbnails/big_buck_bunny_thumbnails.vtt")
                .isDefault(true)
                .kind(TextTrackKind.METADATA)
                .srclang("en")
                .label("thumbnails")
                .build()
        )
        .build()
```

## Related articles

* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/insert-subtitles.md)

---

# How to track ID3 cues and tags on Android

[ID3](https://en.wikipedia.org/wiki/ID3) is a type of metadata which can be inserted in HTTP live streams. Once an ID3 cue is inserted, it is added to a THEOplayer text track.

Developers commonly track ID3 cues because they want to introduce a certain behavior depending on the metadata contained by the ID3 cues, for example:

* to schedule advertisements dynamically by using information passed on by the ID3 metadata;
* to overlay certain text on top of the player (e.g. the score of a football match).

The demo at <https://demo.theoplayer.com/audio-id3-metadata> demonstrates a usage of ID3 metadata. Just before the song changes, an `enter` event is dispatched. The song information (title, album, etc.) is contained within this `enter` event, and can be used to update the UI.

This article describes how you can listen for timed metadata events, and how you can track the `enter` event.

## Listening for timed metadata events

Listen for the [`CUECHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/texttrack/TextTrackEventTypes#CUECHANGE) event of a [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrack).

```kotlin
player.textTracks.addEventListener(TextTrackListEventTypes.ADDTRACK) { addTrackEvent ->
    addTrackEvent.track.addEventListener(TextTrackEventTypes.CUECHANGE) { cueChangeEvent ->
        val cues = cueChangeEvent.textTrack.cues
    }
}
```

## Tracking the enter event

The `enter` event, which is part of the TextTrack API, maps to the moment in time when the ID3 cue becomes relevant.

```kotlin
player.textTracks.addEventListener(TextTrackListEventTypes.ADDTRACK) { addTrackEvent ->
    addTrackEvent.track.addEventListener(TextTrackEventTypes.ENTERCUE) { enterCueEvent ->
        println("enterCueEvent: ${enterCueEvent.cue.content}")
    }
}
```

## Resources

* <https://demo.theoplayer.com/audio-id3-metadata>: a demo which illustrates the use of ID3 in production.
* <http://id3.org/>: ID3.org home page.
* <https://en.wikipedia.org/wiki/ID3>: Wikipedia - ID3.
* <https://dev.w3.org/html5/html-sourcing-inband-tracks/>: Sourcing In-band Media Resource Tracks from Media Containers into HTML.

## Related articles

* [How to detect active text track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-active-text-track-cues.md)
* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-text-tracks.md)

---

# How to programmatically detect text track changes on Android

This article describes how you can use the TextTrack API to detect text track changes. A text track "change" is triggered by enabling (or disabling) a subtitle or closed captions track.

Implementing this functionality is a common use-case for developers who want to build their own UI, and annotate the subtitle (or closed captions) track that is currently active.

## Usage

The implementation of the Android SDK applies to all Android-based platforms, including Android TV and Fire TV.

The Android SDK exposes the TextTrack API through [`player.getTextTracks()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#getTextTracks\(\)). This `getTextTracks()` method returns a [`TextTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrackList) that inherits from the [`TrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/TrackList). This `TrackList` dispatches the events from the [`TextTrackListEventTypes`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/texttrack/list/TextTrackListEventTypes). The `TextTrackListEventTypes` contains the [`TRACKLISTCHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/texttrack/list/TextTrackListEventTypes#TRACKLISTCHANGE) event, as well as the `ADDTRACK` and `REMOVETRACK` event.

The code below allows you to detect text track changes.

```kotlin
player.textTracks.addEventListener(TextTrackListEventTypes.TRACKLISTCHANGE) { event ->
    val track = event.track
    val isEnabled = track.mode == TextTrackMode.SHOWING
    println("${track.label}, ${track.kind}, ${track.type}, $isEnabled")
}
```

The properties of a text `track` (e.g. `mode`, `kind`) are described in the [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrack) and [`Track`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/Track) API references.

## Related articles

Are you reading this article because you are interested in subtitles and closed captions? Continue reading below.

* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-text-tracks.md)
* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/change-visible-captions.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/enable-disable-text-tracks.md)
* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/insert-subtitles.md)

Refer to [how to track ID3 cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/track-id3-cues.md) if you are interested in timed metadata (ID3, emsg, EventStream, `EXT-X-DATERANGE`, ...).

Are you reading this article because you are implementing a custom UI? Then you will find the following articles interesting:

* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/build-chromeless-ui.md)
* [How to detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-video-track-quality-changes.md)
* [How to detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-audio-track-changes.md)

---

# How to detect active text track cues on Android

This article describes how you can use the TextTrack API to detect the active text track cues, by subscribing to the `enter` and `exit` events of a cue, or to the `cuechange` event of a text track.

Implementing this functionality can be a use-case for developers who want to build their own UI, and insert and style their subtitles with maximum freedom. Alternatively, you may need to access the active cues for analytics purposes, or to render them outside of the video player.

Another common use-case is to detect the active text track cue of timed metadata. This article also discusses this use-case.

## Implementation for subtitles and closed captions

Note that this section focuses on detecting active cues for subtitles and closed captions. Go to the section on ["implementation for timed metadata"](#implementation-for-timed-metadata) if you rather want to track timed metadata like ID3, emsg, `EXT-X-DATERANGE` and EventStream.

The Android SDK exposes the TextTrack API through [`player.getTextTracks()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#getTextTracks\(\)). This `getTextTracks()` method returns a [`TextTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrackList) that inherits from the [`TrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/TrackList). This `TrackList` dispatches the events from the [`TextTrackListEventTypes`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/texttrack/list/TextTrackListEventTypes). The `TextTrackListEventTypes` contains the [`ADDTRACK`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/texttrack/list/TextTrackListEventTypes#ADDTRACK) event, as well as the `TRACKLISTCHANGE` and `REMOVETRACK` event.

In the callback of your `ADDTRACK` event, you want to track the [`ADDCUE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/texttrack/TextTrackEventTypes#ADDCUE) event through the [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrack) interface. Then, in the callback of your `ADDCUE` event, you want to track the [`ENTER`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/texttrack/texttrackcue/TextTrackCueEventTypes#ENTER) and [`EXIT`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/texttrack/texttrackcue/TextTrackCueEventTypes#EXIT) events through the [`TextTrackCue`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/cue/TextTrackCue) interface. The `ENTER` event is dispatched when a cue becomes active and the `EXIT` event is dispatched when a cue becomes inactive. You can fetch the actual content in the callback of your `ENTER` event through its [`getContent()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/cue/TextTrackCue#getContent\(\)) method.

Alternatively, in the callback of your `ADDTRACK` event, you could track the [`CUECHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/track/texttrack/TextTrackEventTypes#CUECHANGE) event through the `TextTrack` interface. Then, in the callback of your `CUECHANGE` event, you want to iterate over the active cues. For each active cue, you could also query its `content` property.

The code below allows you to detect the active text track cues.

```kotlin
player.textTracks.addEventListener(TextTrackListEventTypes.ADDTRACK) { addTrackEvent ->
    val track = addTrackEvent.track
    track.addEventListener(TextTrackEventTypes.ADDCUE) { addCueEvent ->
        val cue = addCueEvent.cue
        cue.addEventListener(TextTrackCueEventTypes.ENTER) { enterEvent ->
            println("$enterEvent ${enterEvent.cue.content}")
        }
        cue.addEventListener(TextTrackCueEventTypes.EXIT) { exitEvent ->
            println(exitEvent)
        }
    }
    track.addEventListener(TextTrackEventTypes.CUECHANGE) { cueChangeEvent ->
        val cues = cueChangeEvent.textTrack.activeCues
        for (i in 0 until cues.length()) {
            println("cuechange active cue $i ${cues.getItem(i)}")
        }
    }
}
// ...
// player.source = ...
```

You should invoke these event handlers before you configure your stream, because the player might have already dispatched the event before you were able to subscribe to it.

## Implementation for timed metadata

The implementation for timed metadata is identical to the one for subtitles and closed captions, except for three things.

1. You do not necessarily use the `enter` event. For cues that span a period of time, for example `EXT-X-DATERANGE` cues, you might want to perform your action when the cue ends, so on the `exit` event instead.

2. You might need to set the `mode` of the relevant text track to `hidden`, as documented in [how to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/enable-disable-text-tracks.md). Some types of timed metadata, for example `EXT-X-DATERANGE` and EventStream, are `disabled` by default. You should add a condition to your `addtrack` callback to decide whether you want to set your track to `hidden`.

3. You should set [`hlsDateRange`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/THEOplayerConfig.Builder#hlsDateRange\(boolean\)) to `true` in your player configuration or stream configuration, if you want to detect `EXT-X-DATERANGE` tags in an HLS stream.

The article on [how to track ID3 cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/track-id3-cues.md) might be useful to learn more about detecting ID3 tags specifically.

## Related articles

* [How to programmatically detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-text-track-changes.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/enable-disable-text-tracks.md)
* [How to track ID3 cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/track-id3-cues.md)

---

# License on Android

A THEOplayer license is required to use THEOplayer. The licensing schema was previously based on the built-in license from the SDK build, but THEOplayer now allows you to update the license without rebuilding or re-integrating the player SDK.

This article explains how to configure the license at runtime.

## Passing the license through the player configuration

Include the license in the player configuration, either by passing the license as a string or by passing a license URL:

```kotlin
// passing the license as a string
val playerConfig = THEOplayerConfig.Builder()
    .license("your_license_here")
    .build()
```

```kotlin
// passing the license as a URL
val playerConfig = THEOplayerConfig.Builder()
    .licenseUrl("your_licenseUrl_here")
    .build()
```

## Passing the license through the manifest

Define the same `license` or `licenseUrl` as a new key in the app's manifest.

The Android SDK allows configuring the license through metadata keys, which can be either `THEOPLAYER_LICENSE` or `THEOPLAYER_LICENSE_URL`.

* `THEOPLAYER_LICENSE` must be a license string
* `THEOPLAYER_LICENSE_URL` must be a valid URL to a license server

The license defined in the player configuration has higher precedence than the license provided in the app's manifest. If neither of these are defined, then the player will throw a license error.

## FAQ

### Why do I have to configure a license?

In order to provide THEOplayer insights if a stream can be played, it needs to have access to an active license. You can choose to either configure this license, or configure a URL where this license can be retrieved. We recommend everyone to configure an active license or a license URL.

### How do I avoid introducing any dependencies on THEOplayer servers?

There are two important aspects which can introduce a dependency on THEOplayer servers:

1. **Loading a THEOplayer SDK from the THEOplayer CDN.** This issue is only relevant for the Web SDK. In order to avoid this dependency, we recommend to self-host your THEOplayer SDK. The easiest approach is to load the player through npm, or download the player SDK as a zip file from the developer portal. More information on how to self-host your player can be found in "[Self-hosting THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/self-hosting-theoplayer.md)".
2. **Loading a THEOplayer license from the THEOplayer license system.** In order to avoid this dependency, it is important to always keep your license up to date, either by configuring an updated license or by configuring your own license URL. When your THEOplayer license expires, a new player instance will actively check against THEOplayer's license system if there is an updated license available. This system should however only serve as a fallback for applications which cannot be updated.

### Should I pass a license string or a license URL?

We recommend our customers to use the license string whenever possible.

In special cases it is possible to use the license URL instead. Use cases include contractual or legal (for example privacy) requirements. For more information, please contact <support@theoplayer.com>.

If the player is configured with both a license string and a license URL, it will first try to validate the license string. If the license string is either not configured or expired, the player will attempt to request the license URL instead. If no license URL is defined, then a default license URL will be used. If no valid license can be found, the player will throw a license error.

### Should I update my application upon license renewal?

Yes. After renewing your license, you should make sure to include the new THEOplayer license in your next app update.

### What happens if I don't timely update the license in my application?

The player will attempt to update the license up to 72 hours before expiration. For this, the player will request a new license either from the configured license URL, or as a fallback (when there is no license URL configured) from `validate.theoplayer.com`. Either way, if the request is successful, the player will store the license locally. We highly recommend you to self-host the license using the license URL in the player configuration.

For self-hosting, the license file with the latest license string for your application should be hosted. The full URL to this file should then be configured as the license URL in the player configuration.

### Will I still be able to play offline content with my THEOplayer SDK if my license expires?

When your license expires, THEOplayer will attempt to load an updated license. If an updated license is available, offline playback will still function. If no valid license is available, and no license server can be reached (due to the client being offline), the player will throw an error and stop playback. For this reason, it is important to always keep your license up to date.

### What should I do to protect my license?

The THEOplayer license you get from THEOportal is already an obfuscated string. If you want to protect your license, you need to make sure to configure your [page and source domains](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/page-and-source-domains.md) to guarantee that your license string cannot be used anywhere other than the specified pages and/or with those source domains.

---

# Getting started with CMCD on Android

Media player clients can transmit useful information to Content Delivery Networks (CDNs) with each object request. This implementation is planned to fully support Common Media Client Data (CMCD) as defined in [CTA-5004-B](https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html), published in April 2026.

CMCD supports two modes of transmission:

* **Request mode**: CMCD data is sent as HTTP headers or query parameters on manifest and media segment requests.
* **Event mode** (available since v11.4.0): CMCD events are POSTed to configured HTTP endpoints.

## Request Mode

To enable CMCD, developers can add a CMCDTransmissionMode inside a SourceDescription.

```kotlin
val typedSource = TypedSource.Builder("<HLS_STREAM_URL>")
    .cmcdTransmissionMode(CMCDTransmissionMode.HTTP_HEADER)
    .build()

val sourceDescription = SourceDescription.Builder(typedSource)
    .build()

theoPlayerView.player.source = sourceDescription
```

The preferred mode of transmission for HTTP requests is to use custom headers, but you can configure the transmission mode when creating the CMCD source. For example, to transmit via query arguments:

```kotlin
val typedSource = TypedSource.Builder("<HLS_STREAM_URL>")
    .cmcdTransmissionMode(CMCDTransmissionMode.QUERY_ARGUMENT)
    .build()

val sourceDescription = SourceDescription.Builder(typedSource)
    .build()

theoPlayerView.player.source = sourceDescription
```

## Event Mode

Event mode allows posting CMCD events to configured HTTP endpoints.

> **Info**
>
> Event mode is supported starting from version 11.4.0.

### Player-level configuration

```kotlin
val config = THEOplayerConfig.Builder()
    .cmcd(CMCDConfiguration(
        externalSessionId = "YOUR-EXTERNAL-SESSION-ID", // optional
        userId = "YOUR-USER-ID", // optional
        eventEndpoints = listOf(
            CMCDEndpointConfiguration(url = "https://example.com/cmcd-event-endpoint")
        )
    ))
    .build()

val player = THEOplayerView(context, config)
```

### Source-level configuration

```kotlin
player.player.source = SourceDescription.Builder(
    TypedSource("<HLS_STREAM_URL>")
)
    .cmcd(CMCDSourceConfiguration(
        externalSessionId = "YOUR-EXTERNAL-SESSION-ID", // optional
        sessionId = "YOUR-SESSION-ID", // optional
        userId = "YOUR-USER-ID", // optional
        eventEndpoints = listOf(
            CMCDEndpointConfiguration(url = "https://example.com/cmcd-event-other-endpoint")
        )
    ))
    .build()
```

### Merging behavior

* Source-level values take precedence for `externalSessionId` and `userId`.
* `eventEndpoints` from both levels are **merged** (both player and source endpoints receive events).

> **Warning**
>
> Event mode reporting currently only supports DRM and ad events.

---

# Media3 pipeline for Android

The THEOplayer Android Media3 pipeline is a new and rebuilt base layer for playback of video and audio files for the THEOplayer Android SDK. It is based on [Jetpack Media3](https://developer.android.com/media/media3) components, and it provides more stable playback covering a broader range of use cases, all while being lighter in size and more performant.

## Usage

The Media3 pipeline is part of the THEOplayer Android SDK. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/getting-started.md) to set up THEOplayer in your Android app.

> **Info**
>
> In THEOplayer version 9.x, the Media3 and legacy pipelines were available side-by-side. Starting with version 10.0, the THEOplayer Android SDK has fully switched over to the Media3 pipeline, and the legacy pipeline has been retired.
>
> See [our migration guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/migrating-to-theoplayer-10.md) for more information.

## FAQ

### How does Media3 affect the THEOplayer Android SDK?

Media3 replaces the media playback layer of the THEOplayer Android SDK, offering improvements in performance and stability for playback over our current implementation. As only core media playback is affected, all player APIs remain identical and other features and integrations (such as ads, analytics or Chromecast) are not affected and will function the same.

### Does this use ExoPlayer?

While we make use of ExoPlayer components, this is not a plain ExoPlayer implementation. In addition to the integrations, features and support already offered by the THEOplayer Android SDK, we've reused what makes sense to implement our own playback pipeline that offers improvements, bugfixes and additional functionality over ExoPlayer.

---

# Getting started

To begin with the Dolby OptiView platform please review our guide for getting started with [OptiView Streaming](https://docs-preview.optiview.dolby.com/pr-932/theolive/getting-started.md).

### Installing the THEOplayer for Android

1. Support for OptiView Live comes out of the box with the THEOplayer for Android. Please follow [this guide for installing the Player SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/getting-started.md) for Android development.

2. Once the Player is installed, continue following the guide for setting up the player. Please note that THEOplayer licenses can be found for streaming customers [here](https://docs-preview.optiview.dolby.com/pr-932/theolive/getting-started.md) in the OptiView Live dashboard.

3. With the player installed and set up with a valid license, you can now import the `THEOliveSource` object from the SDK:

```kotlin
import com.theoplayer.android.api.theolive.TheoLiveSource
```

Rather than set your Player `source` as a manifest as you would for a HLS stream, you can now instead set it as a `TheoLiveSource` including your channel alias:

```kotlin
theoPlayer.source = SourceDescription
    .Builder(
        TheoLiveSource(
            src = "YOUR_THEOLIVE_CHANNEL_ALIAS"
        )
    )
    .build()
```

For testing, you can use this HESP demo source: `ar5c53uzm3si4h4zgkzrju44h` which the OptiView team [keeps live 24/7](https://demo.theo.live/?channel=ar5c53uzm3si4h4zgkzrju44h).

From here, your OptiView Live source should be ready to playback in THEOplayer.

### Adding Player Controls

At this stage in implementation, you should have an OptiView Live stream playing within your Android app. The Player SDK provides functionality for controlling stream playback which can be extended to users in the form of controls or buttons. The platform also supports an [Open Video UI for the Android SDK](https://docs-preview.optiview.dolby.com/pr-932/open-video-ui/android/getting-started), which provides a component library for advanced styling and control of UI components.

#### 1. Adding Play/Pause Controls

To add a play/pause button to your app, you’ll first need to create a button. This could be done via an XML layout file, for example:

```xml
<Button
    android:id="@+id/playPauseButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Play/Pause" />
```

Your app could then listen to interaction with the button and call either the `.play()` or `.pause()` functions from the Player SDK:

```kotlin
findViewById<Button>(R.id.playPauseButton).setOnClickListener {
    if (theoPlayer.isPaused) {
        theoPlayer.play()
        Log.i(TAG, "Playback started")
    } else {
        theoPlayer.pause()
        Log.i(TAG, "Playback paused")
    }
}
```

#### 2. Adding a Volume Slider

Like play/pause, a slider could also be added to control volume:

```xml
<SeekBar
    android:id="@+id/volumeSlider"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:max="100" />
```

The Player SDK tracks volume and allows you to adjust it as a percentage of the max volume:

```kotlin
findViewById<SeekBar>(R.id.volumeSlider).apply {
    max = 100
    progress = (theoPlayer.volume * 100).toInt()

    setOnSeekBarChangeListener(object : SeekBar.OnSeekBarChangeListener {
        override fun onProgressChanged(seekBar: SeekBar?, progress: Int, fromUser: Boolean) {
            val volumeLevel = progress / 100.0
            theoPlayer.volume = volumeLevel
            Log.i(TAG, "Volume set to ${Math.round(volumeLevel * 100)}%")
        }

        override fun onStartTrackingTouch(seekBar: SeekBar?) {}
        override fun onStopTrackingTouch(seekBar: SeekBar?) {}
    })
}
```

This will allow users to adjust the volume between 0% and 100%.

#### 3. Adding Fullscreen Support

To add a fullscreen button, add the following to your layout file:

```xml
<Button
    android:id="@+id/fullscreenButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Fullscreen" />
```

Then, set up the button in your `MainActivity`:

```kotlin
// Fullscreen Button
findViewById<Button>(R.id.fullscreenButton).setOnClickListener {
    theoPlayerView.fullScreenManager.requestFullScreen()
    Log.i(TAG, "Fullscreen enabled")
}
```

> **Tip**
>
> Looking for a UI component library to style the player experience? We recommend using our [Open Video UI for Android](https://docs-preview.optiview.dolby.com/pr-932/open-video-ui/android/getting-started) for faster development and control over UI components in the player.

### Adding Logging

To assist with debugging and understanding how your player is behaving, you can add event listeners for key player events. For example:

```kotlin
// Add basic playback event listeners
private fun configureTHEOplayer(theoPlayer: Player) {
    theoPlayer.addEventListener(PlayerEventTypes.PLAY) { Log.i(TAG, "Event: PLAY") }
    theoPlayer.addEventListener(PlayerEventTypes.PLAYING) { Log.i(TAG, "Event: PLAYING") }
    theoPlayer.addEventListener(PlayerEventTypes.PAUSE) { Log.i(TAG, "Event: PAUSE") }
    theoPlayer.addEventListener(PlayerEventTypes.ERROR) { event ->
        Log.e(TAG, "Event: ERROR, error=${event.errorObject}")
        Toast.makeText(this, "Stream Error: ${event.errorObject}", Toast.LENGTH_LONG).show()
    }
}
```

This will log important events like play, pause, and errors to the Android logcat, making it easier to identify issues during development. An exhaustive list of events can be found at our [API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/api/event/player/PlayerEventTypes).

## Troubleshooting

1. When building with the Android SDK please use `Android SDK Build-Tools 35 (build-tools;35.0.0)` or greater.
2. `Event: ERROR, error=com.theoplayer.android.api.error.THEOplayerException: The publication could not be found`. This error indicates the channel alias is invalid. An alias could be invalid because it doesn't exist, the channel is not started, or the channel is started but content isn't available for delivery.

## More information

* [Android Player SDK Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android).

---

# Token based security

OptiView Live offers the option to enable JWT token security on a distribution (formerly referred to as an alias) level. This can be interesting if you only want valid users to access your stream. Read more about the feature and configuring it on your channels on the [token based security guide](https://docs-preview.optiview.dolby.com/pr-932/theolive/distribution/security/token-based-security.md).

This page will demonstrate how to configure the Android SDK for playback of channels with token based security enabled.

## Setting up the Android THEOplayer SDK for OptiView Live

Refer to the [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/theolive/getting-started.md) for the prerequisite steps in getting the web SDK up and running for OptiView Live playback.

## Configuring THEOplayer to pass the token

The token needs to be passed along with player requests as a Bearer token in the `Authorization` header of the requests. To do so we can make use of the Network API of the player, which works as follows:

```kotlin
val token = getToken() // Generate or request your token, for more information check the token based security guide linked above.
player.theoLive.authToken = token
```

This will ensure the player includes your authorization header on all subsequent requests it performs for playback of your OptiView Live distribution.

## Dealing with token expiry and rotation

If your tokens are short-lived, you want to make sure to update the token being passed to the player and requests before it expires, to allow playback to continue beyond expiry. This can simply be done by updating the header on the player in the same way. For example, one could check on an interval that makes sense for your token lifespan whether the token is about to expire and update when necessary, for example:

```kotlin
private var token: String? = null
private var tokenUpdateJob: Job? = null

// Helper function to check whether your token will expire within one minute from now
private fun tokenWillExpireSoon(): Boolean {
    val currentToken = token ?: return true

    return try {
        val parts = currentToken.split(".")
        if (parts.size < 2) return true

        val payload = String(Base64.decode(parts[1], Base64.DEFAULT))
        val jsonPayload = JSONObject(payload)
        val exp = jsonPayload.getLong("exp").seconds
        val now = System.currentTimeMillis().milliseconds

        exp - now <= 60.seconds
    } catch (e: Exception) {
        true // If parsing fails, assume token needs refresh
    }
}

private fun maybeUpdateToken() {
    if (token == null || tokenWillExpireSoon()) {
        token = getToken() // Generate or request your token
        token?.let { newToken ->
            player.theoLive.authToken = newToken
        }
    }
}

// Start the token management
private fun startTokenManagement(scope: CoroutineScope) {
    scope.launch {
        maybeUpdateToken() // Initial token update

        // Check every 30 seconds
        tokenUpdateJob = scope.launch {
            while (isActive) {
                delay(30.seconds)
                maybeUpdateToken()
            }
        }
    }
}

fun stopTokenManagement() {
    tokenUpdateJob?.cancel()
}
```

> **Info**
>
> For coroutine support with kotlin, ensure you have the `kotlinx-coroutines-android` dependency installed.
>
> ```groovy
> dependencies {
>     // ... Other dependencies
>     implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:$coroutineVersion'
> }
> ```
>
> `coroutineVersion` represents the library version as defined elsewhere in your project setup.

## Clearing the token

If the token isn't needed anymore, e.g. when switching to an unprotected distribution or a non-OptiView Live source altogether, the header can be simply removed as follows:

```kotlin
player.theoLive.authToken = null;
```

---

# Metadata

Metadata that travels through your OptiView Live stream — whether [pushed via the API or embedded as SEI](https://docs-preview.optiview.dolby.com/pr-932/theolive/channel/metadata-insertion.md) — surfaces on the player as cues on a text track. The general approach is the same in every case:

1. Listen for `addtrack` on `player.textTracks` so you find out when a new metadata track shows up.
2. Subscribe to a cue event on that track.
3. Inspect the cue to make sure it carries the metadata you care about.
4. Read the payload from `cue.content`.

The properties you match on, the cue event you subscribe to, and the shape of `cue.content` all depend on which kind of metadata is being delivered.

## User-data-unregistered SEI and API push

UDU SEI and API-pushed payloads surface as ID3 `PRIV` frames inside an ID3 v2.4 tag embedded in an `emsg` box, carried by the CMAF segments of the stream.

* The owner identifier of the `PRIV` frame will be set to: `optiview.live:meta:<your-uuid>`
* The frame's private data will contain your metadata as raw binary data.

(See [section 4.27 of the ID3 v2.4 Native Frames specification](https://id3.org/id3v2.4.0-frames) and [ID3 in CMAF](https://aomediacodec.github.io/id3-emsg/) for more details.)

The OptiView Player Android SDK exposes these ID3 frames on a text track with [`TextTrack.type`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrack#getType\(\)) equal to `TextTrackType.ID3`. Listen for the cue event that matches when you want to react:

* `TextTrackEventTypes.ADDCUE` fires as soon as a cue becomes available on the track, before playback reaches it — useful when you want to prefetch data or update application state ahead of time.
* `TextTrackEventTypes.ENTERCUE` fires when playback enters the cue — useful when you want to act in sync with the video, for example to render an overlay at the moment the cue was inserted.

The ID3 frame will be contained in `cue.frame` as a [ID3Frame.Private](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/id3/ID3Frame.Private) with `ownerIdentifier` equal to `optiview.live:meta:<your-uuid>`.

> **Important**
>
> Make sure to always check the frame's type and `ownerIdentifier` before using it, to avoid processing unrelated ID3 frames.

Suppose your UUID is `11111111-1111-1111-1111-111111111111`:

```kotlin
val addCueListener = EventListener<AddCueEvent> { event ->
    val cue = event.cue as? ID3Cue ?: return@EventListener
    val frame = cue.frame as? ID3Frame.Private ?: return@EventListener
    if (frame.ownerIdentifier == "optiview.live:meta:11111111-1111-1111-1111-111111111111") {
        Log.d("MyApp", "Metadata: ${frame.data.decodeToString()}")
    }
}
theoplayerView.player.textTracks.addEventListener(TextTrackListEventTypes.ADDTRACK) { event ->
    val track = event.track as TextTrack
    if (track.type == TextTrackType.ID3) {
        // ID3 track was added. Listen for incoming ID3 cues.
        track.addEventListener(TextTrackEventTypes.ADDCUE /* or TextTrackEventTypes.ENTERCUE */, addCueListener)
    }
}
```

Here the `frame.data` carries the binary payload exactly as it was sent — your application is responsible for parsing it (for example UTF-8 JSON, protobuf, or your own format).

## Source timecode

When the video you ingest carries SMPTE timecode in its picture timing SEI, the Low-Latency HLS and HLS (CMAF) output passes it on as ID3 timed metadata, so players can read the timecode of every frame without parsing the video bitstream. No channel configuration is needed. Channels whose source carries no timecode get no timecode events, and HLS (MPEG-TS) output does not carry them.

Timecode events travel the same way as the metadata above: an ID3 v2.4 tag in an `emsg` box with scheme `https://aomedia.org/emsg/ID3`, carried by the CMAF segments of the stream. The tag holds a `TXXX` (user defined text) frame:

* The description of the `TXXX` frame is `optiview.live:timecode`.
* Its value is the timecode as `HH:MM:SS:FF`, for example `10:00:00:12`. A drop-frame timecode has `;` before the frames instead: `10:00:00;12`.

(See [section 4.2.6 of the ID3 v2.4 Native Frames specification](https://id3.org/id3v2.4.0-frames) for the `TXXX` frame.)

### Where the events sit

There is one timecode event per segment and per partial segment. The event sits on the frame of that segment or partial segment that is presented first, and its `emsg` box declares a duration of exactly one frame. OptiView Player starts the cue at that frame's presentation time and keeps it active until the next timecode cue starts.

A segment and its first partial segment open on the same frame, so they carry the same event, with the same `emsg` id. If your player reports it twice, the two cues are identical.

### Timecode of any other frame

Only the first-presented frame of each segment or partial segment carries an event. To find the timecode of any other frame:

1. Take the latest timecode event that starts at or before the presentation time of the frame.
2. Count the frames presented since that event: multiply the time between the start of the event and the presentation time of the frame by the frame rate, which the multivariant playlist declares for each rendition as `FRAME-RATE`.
3. Add that many frames to the timecode of the event, counting with the frame rate rounded to a whole number (30 for 29.97 fps). For a drop-frame timecode, skip the frame numbers that drop-frame timecode leaves out: frames `00` and `01` at the start of every minute except every tenth minute at 29.97 fps, and frames `00` to `03` at 59.94 fps.

This assumes the rendition has the frame rate of the source. Every frame carries the timecode of the source frame it was encoded from, so on a rendition with a lower frame rate than the source, such as a 30 fps rendition of a 60 fps source, count at the frame rate of the source instead.

A jump in the source timecode, for example when the source switches to another timecode generator, only shows from the next segment or partial segment on. Until then, counting on from the previous event continues the old sequence.

### Reading the timecode with the Android SDK

Timecode events surface on the same `TextTrackType.ID3` text track as the metadata above, as an `ID3Cue` whose `frame` is an [ID3Frame.Text](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/id3/ID3Frame.Text) with `id` equal to `"TXXX"` and `description` equal to `"optiview.live:timecode"`. The frame's `text` holds the timecode.

`TextTrackEventTypes.ENTERCUE` fires when the frame carrying the timecode is presented, and `TextTrackEventTypes.EXITCUE` when the next timecode cue starts:

```kotlin
val enterCueListener = EventListener<EnterCueEvent> { event ->
    val frame = (event.cue as? ID3Cue)?.frame as? ID3Frame.Text ?: return@EventListener
    if (frame.id == "TXXX" && frame.description == "optiview.live:timecode") {
        Log.d("MyApp", "Timecode: ${frame.text}")
    }
}
val exitCueListener = EventListener<ExitCueEvent> { event ->
    val frame = (event.cue as? ID3Cue)?.frame as? ID3Frame.Text ?: return@EventListener
    if (frame.id == "TXXX" && frame.description == "optiview.live:timecode") {
        Log.d("MyApp", "Timecode ended: ${frame.text}")
    }
}
theoplayerView.player.textTracks.addEventListener(TextTrackListEventTypes.ADDTRACK) { event ->
    val track = event.track as TextTrack
    if (track.type == TextTrackType.ID3) {
        track.addEventListener(TextTrackEventTypes.ENTERCUE, enterCueListener)
        track.addEventListener(TextTrackEventTypes.EXITCUE, exitCueListener)
    }
}
```

## Picture timing SEI

Picture timing SEI cues surface on a text track with [`TextTrack.type`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrack#getType\(\)) equal to `TextTrackType.TIMECODE`. Each cue is anchored to a frame, so `entercue` is usually the most useful event: it fires when playback reaches the cue, letting you react in sync with the video.

```kotlin
theoplayerView.player.textTracks.addEventListener(TextTrackListEventTypes.ADDTRACK) { event ->
    val track = event.track as TextTrack
    if (track.type == TextTrackType.TIMECODE) {
        // Timecode track was added. Listen for incoming timecode cues.
        track.addEventListener(TextTrackEventTypes.ENTERCUE, onTimeCode)
    }
}
```

The cue `content` is a `TimeCode` object encoded as a `JSONObject`:

```kotlin
@Serializable
data class TimeCode(
    val hours: Int,
    val minutes: Int,
    val seconds: Int,
    val frames: Int
)
```

A handler can then turn that timecode into whatever action your app needs:

```kotlin
val onTimeCode = EventListener<EnterCueEvent> { event ->
    val cue = event.cue
    val content = checkNotNull(cue.content)
    val timeCode = Json.decodeFromString<TimeCode>(content.toString())
    Log.d("MyApp", "Timecode: ${timeCode.hours}h ${timeCode.minutes}m ${timeCode.seconds}s ${timeCode.frames}f")
}
```

A full example could be as follows: you distribute sports matches and want to display an overlay on the player when the score changes. Every time a score change happens, you add a picture timing SEI message to the stream and store in your backend that this time corresponds with this score. (You could also just add the timing message to all frames if this is easier, but this requires more processing both server and player side.) This information can then be retrieved by the application running on the device of a viewer. You then add the event listener and listen for the `entercue` events. In the listener you check whether the `TimeCode` corresponds with a score change event you recorded earlier and if so, display an overlay over the player.

---

# Discovery URLs

Before the player can play an OptiView Live channel, it sends a discovery request to find the stream details of that channel (such as its manifest URLs and token security settings). OptiView Live channels are served by one of three discovery API versions:

| API version | Channels                                          |
| ----------- | ------------------------------------------------- |
| V1 (legacy) | Channels created with the legacy THEOlive API.    |
| V2          | Distributions created with the OptiView Live API. |
| V3          | Distributions served by the newest discovery API. |

The player does not know in advance which API version serves your channel. If you do not configure a discovery URL, the player tries its built-in discovery URLs one by one, in this order:

1. V2
2. V1 (legacy)
3. V3

The player stops at the first discovery URL that returns the channel. If your channel is not served by V2, the earlier requests fail before the right one succeeds. These failed requests add a small delay before playback starts, and they show up as `404` responses in the network tab of your browser or in a network proxy. The `404` responses are expected and do not mean that playback failed.

## Why configure a discovery URL

When you configure the discovery URL that serves your channel, the player sends its first discovery request to that URL. This removes the failed requests and the extra startup delay.

Configured discovery URLs do not replace the built-in discovery URLs. The player tries them first, and continues with the built-in discovery URLs (V2, V1, V3) if the configured ones do not return the channel. A wrong discovery URL therefore costs one extra request, but it does not break playback.

On platforms that support both `discoveryUrl` and `discoveryUrls`, the player tries `discoveryUrl` first, then each URL of `discoveryUrls` in the order of the list, and then the built-in discovery URLs.

## Which discovery URL to use

The player derives the API version from the path of the discovery URL, so use the URL exactly as listed for your platform, including the trailing `/`. The URL for V1 channels is different on Web than on the other platforms.

| API version | Web                                             | Android, iOS, Roku                              |
| ----------- | ----------------------------------------------- | ----------------------------------------------- |
| V2          | `https://discovery.theo.live/v2/distributions/` | `https://discovery.theo.live/v2/distributions/` |
| V1 (legacy) | `https://discovery.theo.live/`                  | `https://discovery.theo.live/v2/publications/`  |
| V3          | `https://discovery.theo.live/v3/`               | `https://discovery.theo.live/v3/`               |

React Native and Flutter apps pass the discovery URL to the underlying Web, Android or iOS SDK, so the same rules apply per platform.

> **Find the API version of your channel**
>
> Play your channel without a discovery URL and open the network tab of your browser (or a network proxy for a native app). The discovery request that returns `200` shows the discovery URL that serves your channel. For example, a request to `https://discovery.theo.live/v2/distributions/<your-channel-id>` means that your channel is served by V2.

## Configure the discovery URL

Create a `THEOLiveConfig` with the discovery URL and pass it to the player configuration with `theoLive`. For example, for a channel served by V2:

```kotlin
import com.theoplayer.android.api.THEOplayerConfig
import com.theoplayer.android.api.theolive.THEOLiveConfig

val theoLiveConfig = THEOLiveConfig.Builder()
    .discoveryUrl("https://discovery.theo.live/v2/distributions/")
    .build()

val playerConfig = THEOplayerConfig.Builder()
    .license("your-license")
    .theoLive(theoLiveConfig)
    .build()
```

Android supports one configured discovery URL. If the channel is not found there, the player continues with the built-in discovery URLs.

The player derives the API version from the URL path:

* A URL that contains `/v3/` is a V3 discovery URL.
* A URL that contains `/v2/distributions/` is a V2 discovery URL.
* Any other URL, including `https://discovery.theo.live/v2/publications/`, is a V1 discovery URL.

Because of these rules, `https://discovery.theo.live/v2/` without `distributions/` is treated as a V1 discovery URL on Android.

## Configuration reference

[`THEOLiveConfig`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/theolive/THEOLiveConfig) has the following properties. You can set them with the methods of `THEOLiveConfig.Builder`, or as named arguments of the `THEOLiveConfig.Builder` constructor.

| Property            | Type      | Description                                                                                                                      |
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `discoveryUrl`      | `String?` | A discovery URL that the player tries before the built-in discovery URLs. Defaults to `null`.                                    |
| `analyticsDisabled` | `Boolean` | Whether OptiView Live analytics is disabled. Defaults to `false`.                                                                |
| `externalSessionId` | `String?` | Deprecated. An ID used to report usage analytics. Use `THEOplayerConfig.cmcd.externalSessionId` instead, which takes precedence. |

The default discovery order V2, V1, V3 applies from THEOplayer 11.13.0. Earlier versions try V1 first.

---

# UI on Android

Choose the approach that fits your requirements:

* Use Open Video UI when you want a custom experience without building common player components yourself.
* Use the chromeless player when you want to start with no UI and build every control and interaction from scratch.
* Use the basic default UI when its ready-made controls meet your needs and one is available.

| Approach      | Starting point                 | Flexibility | Development effort |
| ------------- | ------------------------------ | ----------- | ------------------ |
| Open Video UI | Ready-made, modular components | High        | Moderate           |
| Chromeless    | Player API without a UI        | Complete    | Highest            |
| Default UI    | Complete basic player UI       | Basic       | Lowest             |

Building a chromeless UI means using the OptiView Player API and your own application code without a ready-made UI. You are responsible for adding every control, such as a play button, and connecting it to the player API, such as `player.play()`. This approach gives you total control over the UI and UX, but requires an understanding of video playback and the OptiView Player API.

## Open Video UI

Use [Open Video UI for Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui.md) to customize the player with ready-made, open-source components that you can use as is or compose and style to match your application.

If you're building a React Native application, use [Open Video UI for React Native](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native/open-video-ui.md) instead.

## Chromeless

For complete control, you can start without a UI and build every control and interaction with the native technologies and programming languages of the platform. The OptiView Player API exposes all the events and properties that you need to implement a custom design from scratch.

Refer to our article on [how to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/build-chromeless-ui.md) for more information.

## Default UI

As of THEOplayer 5, the Android SDK no longer ships a default UI.

## Related articles

* [How to change how a video should fit inside a container](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/change-video-fit.md)

---

# Open Video UI for Android

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Open Video UI is the OptiView Player customization toolkit. It provides open-source, out-of-the-box components that you can compose and style to create a player UI that matches your product and brand.

Open Video UI has dedicated libraries for each supported platform, so your customized player feels native in your app. These pages explain how to get started and tailor the components to your requirements.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui/getting-started.md)

[Start building your UI in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui/guides)

[Learn how to integrate our rich set of features into your own UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui/guides)

## [🛝Examples](https://github.com/THEOplayer/android-ui/tree/main/app)

[See the player in action!](https://github.com/THEOplayer/android-ui/tree/main/app)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui/changelog.md)

[Find out what's new in Open Video UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui/changelog.md)

## [\*️⃣API reference](https://theoplayer.github.io/android-ui/api/)

[Discover all components provided by Open Video UI for Android.](https://theoplayer.github.io/android-ui/api/)

## [![](/pr-932/img/github.svg)![](/pr-932/img/github_dark.svg)GitHub](https://github.com/THEOplayer/android-ui/)

[Browse the source code or report issues on GitHub.](https://github.com/THEOplayer/android-ui/)

---

# Getting started

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

## Installation

1. Create a new Jetpack Compose app or set up Compose in your existing Android app by following [the Compose quick start guide](https://developer.android.com/jetpack/compose/setup).

2. Add the native OptiView Player Android SDK to your project by following [these installation instructions](https://github.com/THEOplayer/theoplayer-sdk-android#installation).

3. Add the OptiView Player Maven repository to your project-level `settings.gradle` file:

   **Groovy**

   ```groovy
   dependencyResolutionManagement {
       repositories {
           google()
           mavenCentral()
           maven { url "https://maven.theoplayer.com/releases" }
       }
   }
   ```

   **Kotlin**

   ```kotlin
   dependencyResolutionManagement {
       repositories {
           google()
           mavenCentral()
           maven { url = uri("https://maven.theoplayer.com/releases") }
       }
   }
   ```

4. Add Open Video UI as a dependency in your module-level `build.gradle` file:

   **Groovy**

   ```groovy
   dependencies {
       implementation "com.theoplayer.theoplayer-sdk-android:core:5.+"
       implementation "com.theoplayer.android-ui:android-ui:1.+"
   }
   ```

   **Kotlin**

   ```kotlin
   dependencies {
       implementation("com.theoplayer.theoplayer-sdk-android:core:5.+")
       implementation("com.theoplayer.android-ui:android-ui:1.+")
   }
   ```

## Usage

### Default UI

`DefaultUI` provides a fully-featured video player experience with minimal setup.

```kotlin
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import com.theoplayer.android.api.THEOplayerConfig
import com.theoplayer.android.api.source.SourceDescription
import com.theoplayer.android.ui.DefaultUI
import com.theoplayer.android.ui.theme.THEOplayerTheme

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            THEOplayerTheme(useDarkTheme = true) {
                DefaultUI(
                    config = THEOplayerConfig.Builder().build(),
                    source = SourceDescription.Builder("https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8")
                        .build(),
                    title = "Big Buck Bunny"
                )
            }
        }
    }
}
```

See [the demo app](https://github.com/THEOplayer/android-ui/blob/main/app/src/main/java/com/theoplayer/android/ui/demo/MainActivity.kt) for a complete and working example.

### Custom UI

If you want to fully customize your video player layout, you can use a `UIController` instead.

```kotlin
setContent {
    UIController(
        config = THEOplayerConfig.Builder().build(),
        source = SourceDescription.Builder("https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8")
            .build(),
        // Choose your own layout using the provided components (or your own!)
        bottomChrome = {
            SeekBar()
            Row {
                PlayButton()
                MuteButton()
                Spacer(modifier = Modifier.weight(1f))
                FullscreenButton()
            }
        }
    )
}
```

---

# Making a custom UI

Although the default UI was designed to support a variety of usage scenarios, you may still run into a case that it doesn't handle very well. Perhaps you want to move some buttons around, or add like and dislike buttons to the control bar, or perhaps integrate a text chat component inside your player. In these situations, you may want to build a custom player UI to create a truly unique experience for your viewers.

In this guide, you will build a custom player from scratch, starting from a basic player and gradually adding more features. Finally, we will look at some more complete examples of custom players, which you can use as reference for your own UI.

## A basic player

We'll start by making the most basic player possible: one with just a play button.

```kotlin
setContent {
    UIController(
        config = THEOplayerConfig.Builder().build(),
        source = SourceDescription.Builder("https://example.com/stream.m3u8").build(),
        centerChrome = {
            PlayButton()
        }
    )
}
```

The `UIController` component is the main container of our custom UI. It handles creating and managing the underlying THEOplayer instance, using the given `config` and `source` properties.

It also provides a skeleton layout for plugging in our playback controls, using [slots](https://developer.android.com/develop/ui/compose/layouts/basics#slot-based-layouts) such as `topChrome` or `centerChrome`. We pass a composable lambda as the `centerChrome` parameter, in which we create a `PlayButton`. This will place a play button in the center of our player.

![Screenshot](/pr-932/assets/images/custom-ui-basic-1083cd0c52b63808ba61800b0a336944.png)

We can add more components so the user can mute or seek the player, or go fullscreen.

```kotlin
setContent {
    UIController(
        config = THEOplayerConfig.Builder().build(),
        source = SourceDescription.Builder("https://example.com/stream.m3u8").build(),
        centerOverlay = {
            LoadingSpinner()
        },
        centerChrome = {
            PlayButton(
                iconModifier = Modifier.size(96.dp),
                contentPadding = PaddingValues(8.dp)
            )
        },
        bottomChrome = {
            SeekBar()
            Row(verticalAlignment = Alignment.CenterVertically) {
                MuteButton()
                CurrentTimeDisplay(showDuration = true)
                Spacer(modifier = Modifier.weight(1f))
                FullscreenButton()
            }
        }
    )
}
```

* `LoadingSpinner` is a circular loading spinner that is automatically shown when the player is waiting for more data. It is placed in the `centerOverlay` slot, which appears in the center of the player but behind the `centerChrome` slot.
* `SeekBar` is a seek bar, showing the player's current position in the video, and allowing the user to seek to a different time.
* `MuteButton` is a button to mute or unmute the player's audio.
* `CurrentTimeDisplay` is a text showing the player's current position in hours, minutes and seconds. By setting `showDuration = true`, the text will also show the player's total video duration.
* `FullscreenButton` is a button to make the player take up the entire screen.

Additionally, we change the size and padding of the play button, to make it bigger and easier to tap.

![Screenshot](/pr-932/assets/images/custom-ui-seekbar-ebca039cc2324cfd56ec2d8053a56e3c.png)

## Using the player's state

You might have noticed that all buttons are visible immediately, even before the video starts playing for the first time. Most of the time however, you want to initially show only the play button, and then show the rest of the buttons after the video has started playing. To do this, you should check the player's current state and then adjust your player layout accordingly.

Within any of the composable lambdas you pass to `UIController`, you can use `Player.current` to access the current player. This `Player` object exposes properties for the player's current time, duration, paused and muted states, etc. See [`Player.kt`](https://github.com/THEOplayer/android-ui/blob/main/ui/src/main/java/com/theoplayer/android/ui/Player.kt) for the full list of properties.

You can then perform any logic on these properties to adjust your player layout. For example, you can check the `firstPlay` property to see if the player has already started playing for the first time, and only show certain buttons if that property is `true`:

```kotlin
setContent {
    UIController(
        config = THEOplayerConfig.Builder().build(),
        source = SourceDescription.Builder("https://example.com/stream.m3u8").build(),
        centerChrome = {
            PlayButton(
                iconModifier = Modifier.size(96.dp),
                contentPadding = PaddingValues(8.dp)
            )
        },
        bottomChrome = {
            // Retrieve the player's state
            val state = Player.current
            // Show the bottom control bar only if we have already started playing before
            if (state?.firstPlay == true) {
                SeekBar()
                Row(verticalAlignment = Alignment.CenterVertically) {
                    MuteButton()
                    CurrentTimeDisplay(showDuration = true)
                    Spacer(modifier = Modifier.weight(1f))
                    FullscreenButton()
                }
            }
        }
    )
}
```

All of the `Player` properties are backed by an observable [`State`](https://developer.android.com/reference/kotlin/androidx/compose/runtime/State), so composables that read these properties will automatically re-compose whenever that property changes. This means you don't need any extra logic to re-draw the bottom control bar whenever `firstPlay` changes from `false` to `true`. This also makes it easy to create your own custom player components. [See the Jetpack Compose documentation for more information.](https://developer.android.com/jetpack/compose/state)

```kotlin
@Composable
fun MyCurrentTimeDisplay(
) {
    val player = Player.current
    val currentTime = player?.currentTime ?: 0.0
    // This text will automatically update whenever the current time changes
    Text(text = currentTime.toString())
}
```

## More examples

### Default UI

It may sound odd to mention the default UI when we're talking about custom UIs. But in fact, the default UI is built in *exactly the same way* as a custom one!

The default UI comes with all the bells and whistles that you'd expect from a fully-featured player: buttons to play or mute the video, a seek bar to seek through the video, menus to change the audio language and subtitles, and support for casting to Chromecast.

Have a look at [`DefaultUI.kt`](https://github.com/THEOplayer/android-ui/blob/main/ui/src/main/java/com/theoplayer/android/ui/DefaultUI.kt) to learn how the default layout is implemented, and perhaps copy some ideas for your own UI.

---

# Setting up Chromecast

The Open Video UI for Android has integrated support for Chromecast.

* When using the `DefaultUI`, the Chromecast button is automatically added in the top right corner of the player.
* When creating a custom UI using a `UIController`, you can add a `ChromecastButton` component anywhere you like. You should also add a `ChromecastDisplay` to show a "Playing on Chromecast" message while casting.

However, you need to perform some additional setup to get it fully working.

## Install the THEOplayer Cast integration

The Chromecast support requires the THEOplayer Cast integration to be included in your app. We'll also need to interact with the Cast Application Framework directly, so we'll include that too:

build.gradle

```groovy
dependencies {
    implementation "com.theoplayer.theoplayer-sdk-android:core:7.+"
    implementation "com.theoplayer.theoplayer-sdk-android:integration-cast:7.+"
    implementation "com.google.android.gms:play-services-cast-framework:21.5.0"
    implementation "com.theoplayer.android-ui:android-ui:1.+"
}
```

Create the player manually using `rememberPlayer()`, and then create and add the cast integration:

MainActivity.kt

```kotlin
import com.theoplayer.android.api.cast.CastConfiguration
import com.theoplayer.android.api.cast.CastIntegrationFactory
import com.theoplayer.android.api.cast.CastStrategy

setContent {
    val player = rememberPlayer()
    LaunchedEffect(player) {
        player.theoplayerView?.let { theoplayerView ->
            // Add Chromecast integration
            val castConfiguration = CastConfiguration.Builder().apply {
                castStrategy(CastStrategy.AUTO)
            }.build()
            theoplayerView.player.addIntegration(
                CastIntegrationFactory.createCastIntegration(theoplayerView, castConfiguration)
            )
        }
    }

    DefaultUI(
        player = player
    )
}
```

## Initialize the `CastContext` during activity creation

The Cast Application Framework handles automatic discovery of Chromecast receivers. However, this only works correctly if the `CastContext` is initialized immediately when your app's activity is constructed.

Therefore, make sure to call `CastContext.getSharedInstance(this)` inside `Activity.onCreate()`:

MainActivity.kt

```kotlin
import com.google.android.gms.cast.framework.CastContext

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Initialize Chromecast immediately, for automatic receiver discovery to work correctly.
        CastContext.getSharedInstance(this)

        setContent {
            // ...
        }
    }
}
```

## Use an `AppCompat` theme

The Cast Application Framework creates dialogs such as [MediaRouteChooserDialog](https://developer.android.com/reference/androidx/mediarouter/app/MediaRouteChooserDialog) and [MediaRouteControllerDialog](https://developer.android.com/reference/androidx/mediarouter/app/MediaRouteControllerDialog) to start and control a cast session. However, because these dialogs inherit from [AppCompatDialog](https://developer.android.com/reference/androidx/appcompat/app/AppCompatDialog), you need to use theme based on `Theme.AppCompat` in your app:

src/main/res/values/themes.xml

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- don't do this:
    <style name="Theme.MyAppTheme" parent="android:Theme.Material.Light.NoActionBar">
         instead, do this:
    -->
    <style name="Theme.MyAppTheme" parent="Theme.AppCompat.Light.NoActionBar">
        <!-- your app's theme colors go here -->
    </style>
</resources>
```

---

# Localization

The Open Video UI for Android can be localized to different languages, enabling you to reach audiences from different regions of the world.

Localization works by [providing alternative resources](https://developer.android.com/guide/topics/resources/providing-resources#AlternativeResources) in one or more languages. You can choose to [change the text of the default language](#changing-the-default-language) to target a single audience, or [add alternative languages](#add-alternative-languages) to target many audiences.

## Changing the default language

By default, the Open Video UI ships with English texts only. If your app targets a non-English speaking audience, you can override these texts with translations for another language.

1. Copy the English string resources from [`res/values/strings.xml`](https://github.com/THEOplayer/android-ui/blob/main/ui/src/main/res/values/strings.xml) to your app's resources for the default locale (i.e. `res/values/strings.xml`).

2. Change the resource values to the translated texts. For example, to change the title of the "Language" menu, you would change the contents of the `theoplayer_ui_menu_language` resource:

   res/values/strings.xml

   ```xml
   <resources>
     <string name="theoplayer_ui_menu_language">Langue</string> <!-- translated to French -->
   </resources>
   ```

   > **Tip**
   >
   > You can also use the [Translations Editor in Android Studio](https://developer.android.com/studio/write/translations-editor) to edit these values.

3. Build and run your app. The translated texts should now appear in your player UI.

## Add alternative languages

If your app targets many audiences speaking different languages, you can add multiple translations using locale-specific resources.

1. Copy the English string resources from [`res/values/strings.xml`](https://github.com/THEOplayer/android-ui/blob/main/ui/src/main/res/values/strings.xml) to your app's resources for the default locale (i.e. `res/values/strings.xml`).

2. Add a new string resources file for a new locale. For example, for French, create the file: `res/values-fr/strings.xml`.

3. Add translated versions for each English string resource to the new resources file. For example, to translate the title of the "Language" menu, you would add an entry for `theoplayer_ui_menu_language`:

   res/values-fr/strings.xml

   ```xml
   <resources>
     <string name="theoplayer_ui_menu_language">Langue</string>
   </resources>
   ```

## Remarks

### Update translations when upgrading Open Video UI

Newer versions of the Open Video UI for Android may add new string resources that need to be translated.

When using custom translations in your app, we recommend pinning the `com.theoplayer.android-ui:android-ui` dependency in your app's `build.gradle` to a specific version. Avoid using `+` in the dependency's version range.

build.gradle

```groovy
dependencies {
    implementation "com.theoplayer.android-ui:android-ui:1.9.0"
}
```

When you decide to upgrade Open Video UI to the latest version, make sure to also update your translations. Check the history for [`res/values/strings.xml`](https://github.com/THEOplayer/android-ui/commits/main/ui/src/main/res/values/strings.xml) to see whether any string resources were added or changed since the previous version.

## More information

* [Localize your app on Android Developers](https://developer.android.com/guide/topics/resources/localization)
* [Support different languages and cultures on Android Developers](https://developer.android.com/training/basics/supporting-devices/languages)

---

# Changelog

> **Tags:**
>
> * 💥 Breaking Change
> * 🚀 New Feature
> * 🐛 Bug Fix
> * 👎 Deprecation
> * 📝 Documentation
> * 🏠 Internal
> * 💅 Polish

## [Unreleased](https://github.com/THEOplayer/android-ui/compare/v1.14.2...HEAD)

## [1.14.2](https://github.com/THEOplayer/android-ui/compare/v1.14.1...v1.14.2) (2026-10-13)

* 🐛 Fixed a listener leak in picture-in-picture mode detection on Android 15 and higher. ([#113](https://github.com/THEOplayer/android-ui/pull/113))
* 🐛 Fixed the player controls not being disposed when `UIController` leaves the composition. ([#117](https://github.com/THEOplayer/android-ui/pull/117))

## [1.14.1](https://github.com/THEOplayer/android-ui/compare/v1.14.0...v1.14.1) (2026-04-20)

* 🐛 Fixed the menu background disappearing after opening. ([#100](https://github.com/THEOplayer/android-ui/pull/100))

## [1.14.0](https://github.com/THEOplayer/android-ui/compare/v1.13.4...v1.14.0) (2026-04-20)

* 🚀 Added support for THEOplayer 11.0. ([#98](https://github.com/THEOplayer/android-ui/pull/98))
* 🚀 Updated to Jetpack Compose version 1.10.6 ([BOM](https://developer.android.com/jetpack/compose/bom) 2026.03.01).

## [1.13.4](https://github.com/THEOplayer/android-ui/compare/v1.13.3...v1.13.4) (2026-04-07)

* 🐛 The language menu now prefers to show CEA-608/708 closed caption tracks with their localized language name (if available) instead of their language code (e.g. "en") or channel number (e.g. "CC1"). ([#84](https://github.com/THEOplayer/android-ui/pull/84), [#95](https://github.com/THEOplayer/android-ui/pull/95))

## [1.13.3](https://github.com/THEOplayer/android-ui/compare/v1.13.2...v1.13.3) (2026-03-23)

* 🐛 Changed the minimum supported THEOplayer version to 7.6.0. ([#85](https://github.com/THEOplayer/android-ui/pull/85))

  * This was effectively already the minimum version as of Open Video UI for Android version 1.7.2, but it wasn't noticed until now.
  * Future versions will be properly tested with the minimum supported THEOplayer version to avoid similar compatibility issues.

* 🐛 `Player.pictureInPicture` now also checks whether the `Activity` itself is in picture-in-picture mode, in case the activity has custom picture-in-picture logic (that does not use THEOplayer's `PiPManager` API). ([#89](https://github.com/THEOplayer/android-ui/pull/89/))

## [1.13.2](https://github.com/THEOplayer/android-ui/compare/v1.13.1...v1.13.2) (2026-03-03)

* 🐛 Fixed `PictureInPictureButton` to only be shown when the backing `THEOplayerView` has a valid `PiPConfiguration`. ([#81](https://github.com/THEOplayer/android-ui/pull/81))

## [1.13.1](https://github.com/THEOplayer/android-ui/compare/v1.13.0...v1.13.1) (2026-01-05)

* 🐛 Changed THEOplayer to be an `api` dependency in Gradle. ([#76](https://github.com/THEOplayer/android-ui/pull/76))
* 🐛 The alpha value of the `UIController`'s background color is now correctly preserved. ([#78](https://github.com/THEOplayer/android-ui/issues/78), [#79](https://github.com/THEOplayer/android-ui/pull/79))

## [1.13.0](https://github.com/THEOplayer/android-ui/compare/v1.12.0...v1.13.0) (2025-09-12)

* 💥 The `minSdk` is now API 23 (Android 6.0 "Marshmallow"), to align with THEOplayer 10.0. ([#74](https://github.com/THEOplayer/android-ui/pull/74))
* 💥 Open Video UI for Android is now compiled using the Kotlin 2 compiler. Update your app to use Kotlin Gradle Plugin 2.0.0 or newer. ([#74](https://github.com/THEOplayer/android-ui/pull/74))
* 💥 Updated to Jetpack Compose version 1.9.0 ([BOM](https://developer.android.com/jetpack/compose/bom) 2025.08.01).
* 🚀 Added support for THEOplayer 10.0. ([#74](https://github.com/THEOplayer/android-ui/pull/74))

## [1.12.0](https://github.com/THEOplayer/android-ui/compare/v1.11.1...v1.12.0) (2025-09-08)

* 🚀 Added `PictureInPictureButton`. ([#19](https://github.com/THEOplayer/android-ui/issues/19), [#70](https://github.com/THEOplayer/android-ui/pull/70))
* 🚀 The default UI now shows a minimal set of controls while playing an ad. ([#71](https://github.com/THEOplayer/android-ui/pull/71))
* 🚀 `UIController` no longer hides all controls while playing an ad. ([#71](https://github.com/THEOplayer/android-ui/pull/71))

## [1.11.1](https://github.com/THEOplayer/android-ui/compare/v1.11.0...v1.11.1) (2025-08-01)

* 🐛 Fixed clicking on overlays from OptiView Ads not working. ([#68](https://github.com/THEOplayer/android-ui/pull/68))

## [1.11.0](https://github.com/THEOplayer/android-ui/compare/v1.10.0...v1.11.0) (2025-04-29)

* 💥 Bumped `compileSdk` to API 35 (Android 15).

* 🚀 Added localization support.

  * See `res/values/strings.xml` for the full list of translatable strings, which you can override in your app's `strings.xml`.
  * For more information, see [Localize your app on Android Developers](https://developer.android.com/guide/topics/resources/localization).

## [1.10.0](https://github.com/THEOplayer/android-ui/compare/v1.9.4...v1.10.0) (2025-04-02)

* 🚀 Added support for THEOplayer 9.0. ([#61](https://github.com/THEOplayer/android-ui/pull/61))

## [1.9.4](https://github.com/THEOplayer/android-ui/compare/v1.9.3...v1.9.4) (2024-12-18)

* 🐛 Revert to `compileSdk` 34. ([#56](https://github.com/THEOplayer/android-ui/pull/56/))

## [1.9.3](https://github.com/THEOplayer/android-ui/compare/v1.9.2...v1.9.3) (2024-12-17)

* 💥 Updated to Jetpack Compose version 1.7.5 ([BOM](https://developer.android.com/jetpack/compose/bom) 2024.11.00).
* 🐛 Fix `SeekBar` not working for livestreams with a large `player.seekable.start(0)`, such as MPEG-DASH streams that use Unix timestamps for their MPD timeline. ([#52](https://github.com/THEOplayer/android-ui/pull/52))

## [1.9.2](https://github.com/THEOplayer/android-ui/compare/v1.9.1...v1.9.2) (2024-10-15)

* 🐛 Fix `Player.cast` not available before first source change.

## [1.9.1](https://github.com/THEOplayer/android-ui/compare/v1.9.0...v1.9.1) (2024-10-01)

* 🐛 Fix `DurationDisplay` to show the time of the live point when playing a live or DVR stream.
* 🐛 Fix `CurrentTimeDisplay` to show the time offset to the live point when playing a live or DVR stream with `showRemaining = true`.
* 💅 Changed `DefaultUi` to hide the current time display when playing a live stream.
* 💅 Changed `DefaultUi` to show the time offset to the live point when playing a DVR stream.
* 💅 Changed `LanguageMenuButton` to automatically hide itself when there are no alternative audio or subtitle tracks to select.

## [1.9.0](https://github.com/THEOplayer/android-ui/compare/v1.8.0...v1.9.0) (2024-09-10)

* 💥 Updated to Jetpack Compose version 1.7.0 ([BOM](https://developer.android.com/jetpack/compose/bom) 2024.09.00).
* 💥 Changed `colors` parameter in `IconButton` and `LiveButton` to be an `IconButtonColors`.
* 🚀 Added support for Android Lollipop (API 21), to align with the THEOplayer Android SDK.
* 🚀 Added `rememberPlayer(THEOplayerView)` to create a `Player` wrapping an existing `THEOplayerView`.

## [1.8.0](https://github.com/THEOplayer/android-ui/compare/v1.7.4...v1.8.0) (2024-09-06)

* 🚀 Added support for THEOplayer 8.0. ([#37](https://github.com/THEOplayer/android-ui/pull/37))

## [1.7.4](https://github.com/THEOplayer/android-ui/compare/v1.7.3...v1.7.4) (2024-09-02)

* 🐛 Fixed a crash when playing a live stream on Chromecast.

## [1.7.3](https://github.com/THEOplayer/android-ui/compare/v1.7.2...v1.7.3) (2024-09-02)

* 🐛 Fixed the Chromecast button never appearing. ([#34](https://github.com/THEOplayer/android-ui/pull/34))
* 🐛 Fixed the seek bar being disabled while casting. ([#35](https://github.com/THEOplayer/android-ui/issues/35), [#36](https://github.com/THEOplayer/android-ui/pull/36))
* 📝 Added a ["Setting up Chromecast" guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui/guides/chromecast.md).

## [1.7.2](https://github.com/THEOplayer/android-ui/compare/v1.7.1...v1.7.2) (2024-08-28)

* 🐛 Fixed ad clickthrough not working. ([#33](https://github.com/THEOplayer/android-ui/pull/33))
* 🐛 Fixed UI not re-appearing after playing an ad. ([#33](https://github.com/THEOplayer/android-ui/pull/33))
* 🐛 Fixed exiting fullscreen disabling [edge-to-edge display](https://developer.android.com/develop/ui/views/layout/edge-to-edge-manually). ([#32](https://github.com/THEOplayer/android-ui/pull/32))

## [1.7.1](https://github.com/THEOplayer/android-ui/compare/v1.7.0...v1.7.1) (2024-08-20)

* 🐛 Disable system gestures on the `SeekBar` component. ([#30](https://github.com/THEOplayer/android-ui/pull/30))

## [1.7.0](https://github.com/THEOplayer/android-ui/compare/v1.6.0...v1.7.0) (2024-08-12)

* 💥 Updated to Jetpack Compose version 1.6.8 ([BOM](https://developer.android.com/jetpack/compose/bom) 2024.06.00).
* 🚀 Added basic support for advertisements. (Requires THEOplayer SDK version 7.10.0 or higher.)

## [1.6.0](https://github.com/THEOplayer/android-ui/compare/v1.5.0...v1.6.0) (2024-04-16)

* 🚀 Added support for THEOplayer Android SDK version 7.

## [1.5.0](https://github.com/THEOplayer/android-ui/compare/v1.4.0...v1.5.0) (2024-02-21)

* 💥 Updated to Jetpack Compose version 1.6.1 ([BOM](https://developer.android.com/jetpack/compose/bom) 2024.02.00).
* 🐛 Fixed dragging the `SeekBar` when using [Compose Material 3 version 1.2.0](https://developer.android.com/jetpack/androidx/releases/compose-material3#1.2.0) or higher. ([#24](https://github.com/THEOplayer/android-ui/issues/24))

## [1.4.0](https://github.com/THEOplayer/android-ui/compare/v1.3.4...v1.4.0) (2023-11-27)

* 💥 Updated to Jetpack Compose version 1.5.4 ([BOM](https://developer.android.com/jetpack/compose/bom) 2023.10.01).
* 💅 Renamed project to "THEOplayer Open Video UI for Android".

## [1.3.4](https://github.com/THEOplayer/android-ui/compare/v1.3.3...v1.3.4) (2023-10-17)

* 🚀 Allow THEOplayer Android SDK 6.

## [1.3.3](https://github.com/THEOplayer/android-ui/compare/v1.3.2...v1.3.3) (2023-07-13)

* 💅 `UIController` now sizes itself to match the video's aspect ratio, except if this were to conflict with a different size constraint (such as `Modifier.fillMaxSize()`).

## [1.3.2](https://github.com/THEOplayer/android-ui/compare/v1.3.1...v1.3.2) (2023-07-13)

* 🏠 Publish to THEOplayer's own Maven repository.

## [1.3.1](https://github.com/THEOplayer/android-ui/compare/v1.3.0...v1.3.1) (2023-06-30)

* 🚀 Added `Player.source`, `.videoWidth` and `.videoHeight` properties.
* 🚀 Added `Player.play()` and `.pause()` shortcut methods.
* 🐛 Fixed player not following device rotation while fullscreen.
* 💅 When autoplaying a new video, the UI now starts out as hidden.

## [1.3.0](https://github.com/THEOplayer/android-ui/compare/v1.2.0...v1.3.0) (2023-06-29)

* 🚀 Added `THEOplayerTheme.playerAnimations` to control the animation settings of the various UI components.
* 🐛 Fix consuming apps unable to install different version of the THEOplayer Android SDK.

## [1.2.0](https://github.com/THEOplayer/android-ui/compare/v1.1.0...v1.2.0) (2023-06-28)

* 💥 Renamed `PlayerState` to `Player`.
* 🚀 Added overloads to `DefaultUI` and `UIController` that accept a `Player`. This allows constructing a player instance in advance, and even moving it between custom UIs when recomposing.
* 🚀 Added `UIControllerScope.player` as an non-null alternative to `Player.current`.

## [1.1.0](https://github.com/THEOplayer/android-ui/compare/v1.0.0...v1.1.0) (2023-06-27)

* 💥 Update to THEOplayer Android SDK 5. To migrate, switch to `com.theoplayer.theoplayer-sdk-android:core` in your Gradle dependencies.
  ```diff
    dependencies {
  -   implementation "com.theoplayer.theoplayer-sdk-android:unified:+"
  +   implementation "com.theoplayer.theoplayer-sdk-android:core:5.+"
      implementation "com.theoplayer.android-ui:android-ui:1.+"
    }
  ```
* 🚀 Added a `UIController` overload which accepts a `THEOplayerView` directly.

## [1.0.0](https://github.com/THEOplayer/android-ui/commits/v1.0.0) (2023-04-05)

* 🚀 Initial release.

---

# Chromeless UI on Android

A chromeless Android player renders video without playback controls. Your application creates every control with Android UI technologies and connects each interaction to the OptiView Player API.

Choose this approach when you need complete control over the interface or cannot use Open Video UI components. Building from scratch requires an understanding of playback states, tracks, accessibility, errors, casting, and Android lifecycle behavior.

Continue with [Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/build-chromeless-ui.md) to create a `THEOplayerView` and access its Player API.

---

# Getting started with a chromeless UI on Android

Building a chromeless UI means building a brand-new video player UI from scratch. You achieve this by implementing your own custom UI components, and by associating those components with the appropriate THEOplayer API. The screenshot below visualizes such a chromeless UI -- albeit not the most pretty one.

![Chromeless UI Layout](/pr-932/assets/images/chromeless-ui-7-4025542f4b233096015b9e6ecce5bcd5.png "Chromeless UI Layout")

A chromeless UI gives you complete control over your full UI and UX, but it also means that you are responsible for implementing your full UI and UX. Achieving this feat requires you to have an adequate grasp on the video player architecture and its underlying API.

The goal of this guide is to advance your understanding on how to connect the dots between custom components and the THEOplayer API. For example, this guide will explain to which THEOplayer APIs you could map your custom play button.

## Create a chromeless player instance

The Android SDK does not ship a default UI. A [`THEOplayerView`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/THEOplayerView) renders the video, and your application adds its own controls on top.

```kotlin
val config = THEOplayerConfig.Builder()
    .license("your_license_string")
    .build()
val theoPlayerView = THEOplayerView(this, config)
val player = theoPlayerView.player
```

The following guides refer to this `player` variable. If you prefer to start with ready-made components, use [Open Video UI for Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui.md).

## Track player states

Before adding controls, learn how to [track player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/player/track-player-states.md). Your UI should respond correctly when playback starts, pauses, buffers, ends, or encounters an error.

![Video Player States](/pr-932/assets/images/player-video-player-states-4f4f37f92d4b03a2c750ce7fe03d0a5a.png "Video Player States")

## Next steps

## [📄️Map UI components](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/chromeless/mapping-components.md)

[Connect Android controls and displays to the appropriate Player APIs.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/chromeless/mapping-components.md)

## [📄️Add UX enhancements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/chromeless/ux-enhancements.md)

[Plan loading, poster, next-content, intro-skip, and advertising experiences.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/chromeless/ux-enhancements.md)

## [📄️Handle errors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/chromeless/error-handling.md)

[Make failures visible and actionable in your custom UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/chromeless/error-handling.md)

---

# Mapping components in a chromeless UI on Android

A chromeless UI is made up of native Android controls and displays that must reflect player state and call the appropriate OptiView Player APIs. This guide maps the most common components to the APIs and supporting guides used to implement them.

![Chromeless UI Layout](/pr-932/assets/images/chromeless-ui-layout-3642d810cba7de946ee7cb69b7ab238b.png "Chromeless UI Layout")

## Play and pause

Show the appropriate control for the current state, as described in [tracking player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/player/track-player-states.md). Call [`play()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#play--) or [`pause()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#pause--) when the viewer selects it.

## Mute and volume

Use [`isMuted()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#isMuted--) and [`setMuted()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#setMuted-boolean-) to implement mute controls.

Android delegates volume level changes to hardware controls, so the application should not provide an independent software volume slider.

## Current time and duration

Use [`requestCurrentTime()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#requestCurrentTime-com.theoplayer.android.api.player.RequestCallback-) and [`setCurrentTime()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#setCurrentTime-double-) for the playback position. Use [`getDuration()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#getDuration--) for duration.

For live streams, `duration` is `Infinity`. You can use `currentProgramDateTime` when the interface needs an absolute program time.

## Scrub bar and buffered ranges

Only seek within [`requestSeekable()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#requestSeekable-com.theoplayer.android.api.player.RequestCallback-) ranges. Update the scrubber in response to [`TIMEUPDATE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/player/PlayerEventTypes#TIMEUPDATE), and represent buffered ranges using [`requestBuffered()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#requestBuffered-com.theoplayer.android.api.player.RequestCallback-).

Display a loading state between seeking and seek completion when appropriate.

## Audio, subtitle, and quality selection

Use the platform guides to build track selectors:

* [Detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-audio-tracks.md)
* [Enable and disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/enable-disable-audio-tracks.md)
* [Detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-text-tracks.md)
* [Enable and disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/enable-disable-text-tracks.md)
* [Detect video-track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/detect-video-track-qualities.md)
* [Select a video-track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media-tracks/select-video-track-quality.md)

## Fullscreen and picture-in-picture

Implement fullscreen handling and orientation changes in the application rather than relying on `FullScreenManager`. See Android's [immersive-mode guidance](https://developer.android.com/training/system-ui/immersive).

Implement picture-in-picture UI independently of the Player SDK. The [Player Picture-in-Picture API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/picture-in-picture.md) is not available for chromeless players.

## Casting

Use the [Chromecast guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/cast/chromecast/introduction.md) to detect availability and start or stop a casting session. AirPlay guidance is available in the [Web SDK documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/airplay/introduction.md).

## Subtitle and advertisement overlays

You can use the SDK's subtitle rendering or [detect active text-track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/text-tracks/detect-active-text-track-cues.md) and render them yourself.

For advertising controls such as countdowns, skip buttons, and scrub-bar markers, subscribe to the relevant [ad events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/ads/subscribe-to-ad-events.md) and update your interface from their callbacks.

---

# How to change how a video should fit inside a container on Android

You may want to alter how a video is sized inside the player's frame. By default, a video player respects the aspect ratio of the video. This means that black bars can appear on the sides of the player, or above and below the video, when its aspect ratio differs from the player's aspect ratio.

Instead, you may want the video to cover the entire player. Note that this either

* cuts off the content that falls outside of the player, or
* deforms the content, so it no longer matches its original aspect ratio.

## Implementation

Use [`Player.setAspectRatio`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/Player#setAspectRatio\(AspectRatio\)) to change how the video is fitted inside the player, using one of the [`AspectRatio`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/player/AspectRatio) values:

* `FIT`: fit the video inside the player, preserving its aspect ratio. This is the default.
* `FILL`: fill the player with the video, deforming the video if needed.
* `ASPECT_FILL`: fill the player with the video, preserving its aspect ratio and cropping the video if needed.

The snippet below demonstrates how you could use this API:

```kotlin
theoPlayerView.player.aspectRatio = AspectRatio.ASPECT_FILL
```

---

# UX enhancements for a chromeless UI on Android

A functional player still needs clear feedback and convenient interactions. Plan these experiences alongside the core playback controls:

1. **Loading spinner:** Indicate when the player is waiting for video data.
2. **Poster:** Show an image before initial playback and after the video ends.
3. **Up next:** Offer the next stream near the end of playback and optionally start it automatically.
4. **Skip intro:** Let viewers skip the current introduction.
5. **Ad countdown:** Display the remaining duration of an ad break.
6. **Ad markers:** Indicate ad-break positions on the scrub bar.

Drive each enhancement from Player events and state. Start with [tracking player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/player/track-player-states.md), then account for Android lifecycle transitions and configuration changes.

---

# Error handling in a chromeless UI on Android

A chromeless UI must present its own error state because the SDK does not render controls or viewer-facing error messages for you.

Decide how to present recoverable and terminal failures, whether viewers can retry, and which details should be retained for diagnostics. Clear loading indicators when an error occurs so the interface does not appear to buffer indefinitely.

See the [Android error-handling guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/miscellaneous/error/introduction.md) to detect Player errors and map them to messages and recovery actions.

---

# Connectors for THEOplayer Android SDK

## [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/comscore)

[Integrate with Comscore for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/comscore)

## [![](/pr-932/img/conviva.svg)![](/pr-932/img/conviva_dark.svg)Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/conviva)

[Integrate with Conviva for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/conviva)

## [Nielsen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/nielsen)

[Integrate with Nielsen for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/nielsen)

## [📱Media Session](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/mediasession)

[Integrate with Android Media Session to delegate system-level playback controls to your app.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/mediasession)

## [![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAy0SURBVHgB7d1PbhRJFsfxiLIxs+iW2DbuaZVvwNzASGB6iU+AOQGuHd2YwSVhYId9AsMJYNmYkewb2DdwafjjWXoBEvUvYzKqSMqmjV1ZlZnxIuL7kVpqoZaM6M5f53svMp5SAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAORwt3q8fpn8pAKXQSij78Ju5S7tKmXr6m1z/0vm0tbC3eawAFEZkABwurl6Zm/tpN/3NXRv9qm4lpt/89e2TFwpAIcQFwNkP/ykH7U5veWHvWUsBmIqoABjj4f/GaP2i0+42CQJgcmICIM/DP6JbSidbV99sbCoAuYkIgMke/pPoDwCTcB4A0z/8I5QFQD5OA6DIh/+k4diw95IgAM7nLADKevhHKAuAizgJgPIf/pN0q93pXudtAPi7ygOg2od/hP4A8HeVBoCrh/+E4/Rnb/6y87ipAFQXAAIe/hPoDwBWJQEg6+EfoSxA7EoPAKkP/ylab7bb3S2CALEpNQC8ePi/oSxAfEoNgPc31zZrWt1TXhkEwXIaBAcKCFxNlUhrc0V5x9Rrurb/4dbDbW4jQuhKDQCfaWNWLs/NHh4trT1SQKAIgAsYpdY/Lj08fH/zzxUFBIYAGMugLNj+uLT2irIAISEA8rltywL6AwgFATCBYX/g0i5lAXxHAEwsKwseHr67sbaoAA8RAFMz9Zma2qUsgI8IgIIwNoSPCICCMTaETwiAUnwbG+5TFkAyAqBc1xgbQjICoALZ2PDjrQerChCEAKiMqSujn9v+wIelP24rQAACoHJ23fnMK8oCSEAAOHJybGgvTlGAAwSAY3ZseHnu533GhnCBABBhdKyYsgBVIgBEMXXGhqgSASBQNjbkWDHKRgCIZeocK0bZCADxhv0BygKUgQDwRDY2/Hjr4XOCAEUhAHxjzCq3EaEoBICXRmPDNAg82LoEqQgAr7HEBNMhAALwtT+wz9gQeREA4bjC2BB5EQDBYYkJxkcAhIslJrgQARA4lpjgPARAFFhigrMRAFFhiQlOIwAixBITZAiAiDE2BAEQPZaYxIwAQIYlJhEiAHAKY8O4EAA4w2hsyBKTsBEAOAdLTEJHAOBCLDEJFwGAsbHEJDwEAHJiiUlICABMiCUmISAAMBWWmPiNAEABWGLiKwIABWKJiW8IABTu9NiQIJCMAEBphmNDjhVLRgCgZIwNJSMAUBHGhhIRAKgUS0xkIQDgAktMhCAA4BBLTFwjACABS0wcIQAgBrcRVY8AgDCjsWEaBNcUSkUAQKhBEOxTFpSLAIBoLDEpFwEALzA2LAcBAI8M+wNHN9d2KQuKQQDAO0arRcaGxSAA4C3GhtMjAOA5lphMgwBAIFhiMgkCAEFhiUk+pQaASdSBAhxgicl4tCrZ0e/36yaZ2U1/VF0Bbhy0O73lhb1nLYVTSg+AjE3imtaPCAK4YrR+0Wl3mwTBSGUBYB0url+Zm+utpj+UY51wRLeUTrauvtnYVKg2ADK2LEiSmXWt9B0FOKFbiek3f3375IWKmJMAyLy7sbY4UzPblAVwJfaywGkAZOgPwLX0QVj/0um9jC0IRASAZcuCfn92tabVPQU4EV9ZICYAMvQH4J5utTvd6zG8DYgLgAxlAVyLoT8gNgAyBAEcO04fks1fdh43VYDEB4BFWQD3wuwPeBEAmeGx4tnn6d/y2Sdced3u9BqhlAVeBUCGsgDOab3Zbne3fA8CLwMg82FpLS0LzB2CAG74XxZ4HQAW/QG4NwiC5TQIvPv83fsAyHztD7xK/5ZtMnDCx7FhMAGQoT8A1+yxYl/GhsEFQGbYHxgcK+ZaKDjgR38g2ACw6A/ANW3U3pdu767UsiDoAMhwLRlck9ofiCIAMvQH4Ja8siCqALC4lgzu6ZZRvcb8ztPXyrHoAiBDfwCuSSgLog2ATFoWXEvLgleUBXDF5dgw+gDI0B+AW276AwTACcOyYHaF/gAcqnSJCQFwBvoDcK2q/gDLQc/wy1/PWvM7Gyumr5bTfxUtBVRssOT08kzp917wBjAG+gOolFF77Zne3YW/yi8DCIAxURagfKbVT/Tdf/7n8Z6qCAGQE0GAEhwbpbY6nU+bC3ubx6pCBMCEKAtQBKNN2uz73Kj6wc8QAFN6f+PBaq1mPzvWdQWMK63z+0Y1q3zdPwsBUADKAuRwnLb4m1LWkxMABRp8dtyf3U7/VBcV8J20zm+6qPPPQwCUgP4ATqlwrJcXAVAiriWLXfVjvbwIgJLRH4jSYKw3v/N4XQkXVAC8u7G2OKvVo6SmW9KuX+La8ji4HuvlFUQAHC3er6vLlx4ZY1ZO/rrE65npDwRKyFgvL68D4HBx9co/5n66l75uraof1tkyr2f+2h/gs2P/HScmafi6HszbAPjv0h+3Z5XdFGzq4/zzEq9npj/gN4ljvby8C4CszjcTztolXs/MtWSeETzWy8ubALCv+5fnfk5fmc2qmppuKZ1sSTmNlaE/IJ38sV5eXgTA0dLao/Pr/EnJ6w9wbblI3oz18hIdAPZ1f6amt8et8yclsSygPyBDYtRWt/tp3ec6/zwiA2Aw1rs0u22qPlOv9Wa73d2SFATDEDTblAUV83Ssl5eoACi2zp+UzLEh/YHKeD3Wy0tMAPzv5r/vJTpZV2LOzeu04WNENXxsWdDvz67W9OD7AhTL2a08LjkPAPuKW6up51roEVn6AxEIaKyXl7MAcFbnT8geK/7S+bQl6f8OlAXTCm+sl1flATDe8V2p6A8EItixXl6VBsDwP9Tac+X99/G61e50r1MW+Cf0sV5elQTAtMd3pZLaHzCJ/UZClb5VxiuRjPXyKjUAfvSZbmCO0z/ETT47lsqkZZsRV7ZJUWoAfFh68CKeV1Kh/YF4ry2PcqyXFwFQvNftTq9Bf8ChiMd6eREAJRHbHwj62nLGenmxHrwkg/XOc5d2bS2uhLBrz6++fXw9McndwNae22Ubjas7Gws8/PnwBlAJ3TKq15jfefpaCRLCteWM9aZDAFSIY8UFYqxXCALAgeGx4t5LeecHZnblTwtMq6eSxm/C3qZ8RQ/AgXQ8tS6yP5DW0IL7A3as12x3Pv+Lh784vAE4Nzg/sPzr2ycHShBR15Yz1isNbwDOmXpN1/Y/3Hq4fWhPTgphP5TRtd6CUealciT92Qf9RF23kwse/nLwBiCM0G1GVV9bbsd6TWm3NoeINwBhbH/g49LDQ0n9AVueVNUfsGO9dufTAg9/NXgDkO2g3ektyxsbzq4U3h9grOcEAeCBsM8PMNZziRLAA9mx4o+3Hji8Lfk0Ozac39lYMX21PGFZwFhPAN4AvBPEtWSv27Veg86+ewSAp6SWBeddW27HekmiG9T5chAAvhO4zeiM/gBjPaEIgCDILQu0rtW5lUcuAiAo8rYZQTamAEEx9Zma2pV2rBhyEQABGo4NZw+PltYe2UUsCvgBAiBgw8+Of96XdKwYshAAwRt8bbhtvy+gLMD3CIBomLotC+gP4CQCIDJf+wP7tj+gED0CIE5XJH52jOoRAFEb9geObq7tUhbEiQCAslub6Q/EiQDAN9lnx4e/EwKxIAAwYtSevaGYz3TjMasAlmpGiwCIm72VZ6vT+czXepEiAOLFrTwgAKLD7bs4gQCIx/BWnh1u5cEIARABu2yj2/20Tp2P7xEAIWOpJi5AAASJsR7GQwCEhbEeciEAAmG0edFpf27w4CMPAsB338Z6G3sKyIkA8NdxYpKGtF0A8AsB4CG7VJNlGygCAeATxnooGAHgBcZ6KAcBINtgrDe/s7GugBIQAEJxfBdVIACk4Ws9VIgAkIOxHipHALj39fguYz1UjwBwibEeHCMAnGCsBxkIgGoNb+V5w608kIEAqAhjPUhEAJSNsR4EIwBKY1o9lTR+e/v0tQKEIgCKx6088AYBUCyWbcArBEABjDIHSaIb1PnwDQEwncFYb56xHjxFAEyIsR5CQADklY71EjX4aOdAAZ4jAMbG8V2EhwC4GGM9BIsAOMdg2YbuNxnrIVQEwFlYtoFIlBoAxpg9rfUd5Y/h13o7jPUQB61K9v7mnys1XdtWwrFsAzEqPQAs0SHArTyIWCUBYMkLAcZ6QGUBYAkJAS7hBL6qNAAslyEwGOu1Pzd48IGhygPAqjwEuJUHOJOTALAqCgGWbQDncBYAVpkhwFgPuJjTALAKDwHGesDYnAeAVUwIMNYD8hIRANYUITAY683vPF5XAHIREwBW3hDgVh5gOqICwBorBBjrAYUQFwDWj0PAtBJjmoz1gGKIDADruxDg+C5QArEBYA1CQNXuMNYDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABALP4PxPhKst9YjwYAAAAASUVORK5CYII=)Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/yospace)

[Integrate with Yospace for server-side ad insertion (SSAI).](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/yospace)

## [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk)

[Add support for Uplynk CMS to your player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk)

---

# THEOplayer Android Comscore Connector

A Comscore analytics connector for use with THEOplayer in Android applications.

## Usage

### Configuring the Connector

Create the connector by providing the `THEOplayer` instance, a `ComscoreConfiguration` (which contains your publisher id), and the `ComscoreMetadata` of the first source you will set to the player (you can change it dynamically throughout the entire lifecycle of the connector):

```kotlin
val comscoreConfiguration = ComscoreConfiguration(
    publisherId = "<your publisher ID here>", // Can be a test or production key.
    applicationName = "THEOplayer Demo",
    userConsent = "1",
    childDirected = false,
    secureTransmission = true,
    usagePropertiesAutoUpdateMode = 1,
    debug = true
)
val metadata = ComscoreMetaData(
    mediaType = ComscoreMediaType.LONG_FORM_ON_DEMAND,
    uniqueId = "testuniqueId",
    length = 634,
    stationTitle = "THEOTV",
    programTitle = "Big Buck Bunny",
    episodeTitle = "Intro",
    genreName = "Animation",
    classifyAsAudioStream = false,
    c3 = "c3value",
    c4 = "c4value",
    c6 = "c6value",
    stationCode = null,
    networkAffiliate = null,
    publisherName = null,
    programId = null,
    episodeId = null,
    episodeSeasonNumber = null,
    episodeNumber = null,
    genreId = null,
    carryTvAdvertisementLoad = null,
    classifyAsCompleteEpisode = null,
    dateOfProduction = null,
    timeOfProduction = null,
    dateOfTvAiring = null,
    timeOfTvAiring = null,
    dateOfDigitalAiring = null,
    timeOfDigitalAiring = null,
    feedType = null,
    deliveryMode = null,
    deliverySubscriptionType = null,
    deliveryComposition = null,
    deliveryAdvertisementCapability = null,
    mediaFormat = null,
    distributionModel = null,
    playlistTitle = null,
    totalSegments = null,
    clipUrl = null,
    videoDimension = null,
    customLabels = emptyMap(),
)

val comscore = ComscoreConnector(this, theoplayerView.player, comscoreConfiguration, metadata)

val playerConfig = THEOplayerConfig.Builder()
    .analytics(comscore)
    .build()

val theoplayerView = THEOplayerView(this)
theoplayerView.config = playerConfig

val theoplayer = theoplayerView.theoplayer
theoplayer.source = SourceDescription.Builder()
    .sources("YOUR_SOURCE_URL_HERE")
    .build()

theoplayerView.onCreatePlayer { player ->
    // Initialize Comscore connector
    comscore.init(player)
}
```

### Passing Metadata Dynamically

The connector allows passing or updating the current asset's metadata at any time:

```kotlin
comscoreConnector.update(ComscoreMetaData())
```

### ComscoreMetadata Fields

Based on the `ComscoreMetaData` type, you can tell which fields are mandatory and which aren't. Note that this is purely for the integration to work correctly. Depending on the Comscore solution you are using, different fields are required/optional. The mandatory fields in the `ComscoreMetadata` type are the ones that are mandatory for all three Comscore solutions:

* Video Metrix (V)
* Cross Platform Product Suite (X)
* Cross Media Audience Measurement (C)

| Property                          | Required | Optional |
| --------------------------------- | -------- | -------- |
| `mediaType`                       | All      |          |
| `uniqueId`                        | All      |          |
| `length`                          | All      |          |
| `c3`                              | V        |          |
| `c4`                              | V        |          |
| `c6`                              | V        |          |
| `stationTitle`                    | All      |          |
| `stationCode`                     |          | All      |
| `networkAffiliate`                |          | All      |
| `publisherName`                   | X C      | V        |
| `programTitle`                    | All      |          |
| `programId`                       |          | V C      |
| `episodeTitle`                    | All      |          |
| `episodeId`                       |          | X C      |
| `episodeSeasonNumber`             | X C      |          |
| `episodeNumber`                   | X C      |          |
| `genreName`                       | All      |          |
| `genreId`                         |          | All      |
| `carryTvAdvertisementLoad`        | X        |          |
| `classifyAsCompleteEpisode`       | X        |          |
| `dateOfProduction`                |          | C        |
| `timeOfProduction`                |          | C        |
| `dateOfTvAiring`                  | X C      |          |
| `timeOfTvAiring`                  |          | X C      |
| `dateOfDigitalAiring`             | X C      |          |
| `timeOfDigitalAiring`             |          | X C      |
| `feedType`                        | X        |          |
| `classifyAsAudioStream`           | All      |          |
| `deliveryMode`                    |          | All      |
| `deliverySubscriptionType`        |          | All      |
| `deliveryComposition`             |          | All      |
| `deliveryAdvertisementCapability` |          | All      |
| `mediaFormat`                     |          | All      |
| `distributionModel`               |          | All      |
| `playlistTitle`                   |          | C        |
| `totalSegments`                   |          | V C      |
| `clipUrl`                         |          | V C      |
| `videoDimension`                  |          | C        |
| `customLabels`                    |          | All      |

---

# THEOplayer Android SDK Conviva Connector

The Conviva connector provides a Conviva integration for THEOplayer Android SDK.

## Prerequisites

The THEOplayer Android SDK Conviva Connector requires the application to import the THEOplayer Android SDK since the connector relies on its public APIs. For more details, check out our [Getting started on Android](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/android/getting-started/) guide.

For setting up a valid Conviva session, you must have access to a [Conviva developer account](https://pulse.conviva.com/) with access to a debug or production key.

## Installation

After setting up the THEOplayer Android SDK, in your **module** level `build.gradle` file add the THEOplayer Android SDK Conviva Connector and the Conviva SDK:

```text
implementation 'com.theoplayer.android-connector:conviva:+'
implementation 'com.conviva.sdk:conviva-core-sdk:4.0.33'
```

## Usage

### Setting up the Conviva Connector

```kotlin
val theoplayerView: THEOplayerView

private fun setupConviva() {
    val customerKey = "your_conviva_customer_key"
    val gatewayUrl = "your_conviva_debug_gateway_url"
    
    val metadata = hashMapOf(
        "Conviva.applicationName" to "THEOplayer",
        "Conviva.viewerId" to "viewerId"
    )
    val config = ConvivaConfiguration(
        customerKey,
        true, // debug
        gatewayUrl,
    )
    convivaConnector = ConvivaConnector(applicationContext, theoplayerView.player, metadata, config)
}
```

### Setting asset metadata

Most media related properties, such as its streamURL, duration or whether it is a live or vod stream, are determined and passed by the connector itself when setting a new source.

Whenever a new source is set on the player, the metadata `title` property is used to pass an asset name.

```kotlin
theoplayerView.player.source = 
    SourceDescription.Builder(
        TypedSource.Builder("https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8").build()
    )
    .metadata(MetadataDescription(mapOf("title" to "Big Buck Bunny")))
    .build()
```

Alternatively, the asset name can be passed to the connector at any time during playback along with additional metadata through an open key-value map. An important note is that the `setContentInfo` call needs to happen after the `sourcechange` event is dispatched, for example:

```kotlin
theoplayerView.player.source = sourceDescription

theoplayerView.player.addEventListener(PlayerEventTypes.SOURCECHANGE) {
    convivaConnector.setContentInfo(hashMapOf(
        "Conviva.assetName" to "Big Buck Bunny",
        "customTag1" to "customValue1",
        "customTag2" to "customValue2"
    ))
}
```

### Starting a new session on program boundaries

By default, new sessions are only started on play-out of a new source, or when an ad break starts. During a live stream it is possible to manually mark the start of a new session, for example when a new program starts.

```kotlin
convivaConnector?.stopAndStartNewSession(hashMapOf(
    "Conviva.assetName" to "New program",
    "customTag1" to "customValue1",
    "customTag2" to "customValue2"
))
```

### Destroying / Cleaning up

To release listeners and resources, call destroy whenever the Conviva Connector is no longer needed.

```kotlin
convivaConnector?.destroy()
```

Note:

* After destroying a Conviva Connector instance, it can no longer be used. If needed, a new instance should be created.

---

# THEOplayer Android SDK Nielsen Connector

The Nielsen connector provides a Nielsen integration for THEOplayer Android SDK.

## Prerequisites

The THEOplayer Android SDK Nielsen Connector requires the application to import the THEOplayer Android SDK since the connector relies on its public APIs. For more details, check out our [Getting started on Android](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/android/getting-started/) guide.

## Installation

After setting up the THEOplayer Android SDK, in your **module** level `build.gradle` file add the THEOplayer Android SDK Nielsen Connector and the Nielsen SDK dependencies:

```groovy
implementation 'com.theoplayer.android-connector:nielsen:+'
implementation 'com.nielsenappsdk.global:ad:9.1.0.0'
```

Also in the `build.gradle` file, specify the Nielsen maven repository inside the repositories section:

```groovy
repositories {
    maven { url 'https://maven.theoplayer.com/releases/' }
    maven { url 'https://raw.githubusercontent.com/NielsenDigitalSDK/nielsenappsdk-android/master/'}
}
```

## Usage

### Setting up the Nielsen Connector

```kotlin
val theoplayerView: THEOplayerView

private fun setupNielsen() {
    val appId = "your_nielsen_app_id"
    val debug = true
    nielsenConnector = NielsenConnector(applicationContext, theoplayerView.player, appId, debug)
}
```

### Updating metadata

Whenever a new source is set on the player, update the current metadata as follows:

```kotlin
theoplayerView.player.source = sourceDescription
nielsenConnector?.updateMetadata(hashMapOf(
    "assetid" to "C112233",
    "program" to "programName"
))
```

### Destroying / Cleaning up

To release listeners and resources, call destroy whenever the Nielsen Connector is no longer needed.

```kotlin
nielsenConnector?.destroy()
```

Note:

* After destroying a Nielsen Connector instance, it can no longer be used. If needed, a new instance should be created.

---

# THEOplayer Media Session Connector

The media session connector provides a universal way for Android to interact with THEOplayer. Integrating with the connector allows an app to advertise media playback and to receive playback commands from external sources, such as from a TV remote or through Google Assistant commands using voice commands such as *'What is currently playing?'*.

## Android Media Session

As described on the Android documentation pages [Using a Media Session](https://developer.android.com/guide/topics/media-apps/working-with-a-media-session):

> Media sessions provide a universal way of interacting with an audio or video player. By informing Android that media is playing in an app, playback controls can be delegated to the app. Integrating with the media session allows an app to advertise media playback externally and to receive playback commands from external sources. These sources can be physical buttons (such as the play button on a headset or TV remote control) or indirect commands (such as instructing "pause" to Google Assistant). The media session then delegates these commands to the app that applies them to the media player for which it is transparent where the commands originated.

## Getting Started

This section details how to integrate the connector in a video app, as demonstrated on Android's [Building a video app](https://developer.android.com/guide/topics/media-apps/video-app/building-a-video-app). The app will advertise its player state and media metadata to the media session through the connector, and responds to requests from the media session.

In this example the media session is active as long as the app's activity is active and running in the foreground. The full example code is available in our [Sample repository](https://github.com/THEOplayer/samples-android-sdk).

For a demonstration on how to build a more extensive app that does background audio playback, we refer to the Android documentation on [Building an audio app](https://developer.android.com/guide/topics/media-apps/audio-app/building-an-audio-app), as well as our [Sample repository](https://github.com/THEOplayer/samples-android-sdk).

### Creating the media session connector

After [Creating and initializing a media session](https://developer.android.com/guide/topics/media-apps/working-with-a-media-session#init-session), pass the `mediaSession` and THEOplayer instances to the connector.

Optionally set the `debug` flag to receive log statements from the connector.

```text
private lateinit var mediaSession: MediaSessionCompat
private lateinit var mediaSessionConnector: MediaSessionConnector

public override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Create and initialize the media session
    mediaSession = MediaSessionCompat(this, TAG).apply {
        // Do not let MediaButtons restart the player when the app is not visible
        setMediaButtonReceiver(null)
    }

    // Create a MediaSessionConnector and attach the THEOplayer instance.
    mediaSessionConnector = MediaSessionConnector(mediaSession)
    mediaSessionConnector.debug = true
    
    // Pass the player instance
    mediaSessionConnector.player = viewBinding.theoPlayerView.player
    
    // Set mediaSession to active
    mediaSessionConnector.setActive(true)
}
```

### Passing media metadata

The connector advertises the currently playing asset to the media session. The `MetadataDescription` object that is passed to THEOplayer's source description provides additional information on the asset, such as title, author and an icon.

If your app uses a [MediaController](https://developer.android.com/reference/kotlin/android/support/v4/media/session/MediaControllerCompat) to interact with the media session, the [onMetadataChanged](https://developer.android.com/reference/kotlin/android/support/v4/media/session/MediaControllerCompat.Callback#onMetadataChanged\(android.support.v4.media.MediaMetadataCompat\)) callback can be used to display the metadata on screen.

A full list of supported metadata properties is available in [MediaMetadataProvider](https://github.com/THEOplayer/android-connector/blob/-/connectors/mediasession/src/main/java/com/theoplayer/android/connector/mediasession/MediaMetadataProvider.kt)

```text
val metadataFields = hashMapOf<String, Any>(
    "title" to "Elephants Dream",
    "displaySubtitle" to "by the Orange Open Movie Project",
    "mediaId" to "stream01",
    "mediaUri" to "https://theoplayer.com",
    "album" to "THEOplayer test streams",
    "author" to "THEOplayer"
)
player.source = SourceDescription.Builder(
    TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlistCorrectionENG.m3u8")
        .type(SourceType.HLSX)
        .build()
    )
    .metadata(MetadataDescription(metadataFields))
    .build()
```

![](/pr-932/assets/images/sample-c23a4a59c15abdd122d9b4cd6ecdd966.png)

### Lifecyle callbacks

The THEOplayer instance needs to know about the Activity's lifecycle methods. In accordance, the connector will need to update its state as well.

```text
override fun onPause() {
    viewBinding.theoPlayerView.onPause()
    mediaSessionConnector.setActive(false)
    super.onPause()
}

override fun onResume() {
    viewBinding.theoPlayerView.onResume()
    mediaSessionConnector.setActive(true)
    super.onResume()
}

override fun onDestroy() {
    mediaSessionConnector.destroy()
    viewBinding.theoPlayerView.onDestroy()
    super.onDestroy()
}
```

### Connector interfaces

Besides basic playback requests, the media session can also send requests related to queued media items, setting ratings and custom actions. These are forwarded to optionally implemented interfaces of the connector:

* `QueueNavigator` allows handling queue navigation actions.
* `QueueEditor` allows handling queue editing actions.
* `PlaybackPreparer` allows handling media prepare actions.
* `RatingCallback` allows handling rating actions.
* `CustomActionProvider` allows handling custom actions.

We refer to our [Sample repository](https://github.com/THEOplayer/samples-android-sdk) for an example on how these could be implemented.

### Dispatching media commands

Using `adb` (Android Debug Bridge), media commands can be triggered command-line as well:

```text
$ adb shell media dispatch KEY
```

with `KEY` being any command `play, pause, play-pause, mute, headsethook, stop, next, previous, rewind, record, fast-forward.`

### Media player state

The player's current state can be queried using `adb`:

```text
$ adb shell dumpsys media_session

MEDIA SESSION SERVICE (dumpsys media_session)

5 sessions listeners.
Global priority session is null
User Records:
Record for full_user=0
  Volume key long-press listener: null
  Volume key long-press listener package: 
  Media key listener: null
  Media key listener package: 
  Callback: android.media.session.ICallback$Stub$Proxy@ff4b775
  Last MediaButtonReceiver: null
  Restored MediaButtonReceiver: null
  Restored MediaButtonReceiverComponentType: 0
  Media button session is com.theoplayer.android.mediasession.demo/PlayerActivity (userId=0)
  Sessions Stack - have 2 sessions:
    PlayerActivity com.theoplayer.android.mediasession.demo/PlayerActivity (userId=0)
      ownerPid=7705, ownerUid=10060, userId=0
      package=com.theoplayer.android.mediasession.demo
      launchIntent=null
      mediaButtonReceiver=null
      active=true
      flags=3
      rating type=0
      controllers: 15
      state=PlaybackState {state=3, position=45840, buffered position=66664, speed=1.0, updated=333568, actions=4199295, custom actions=[], active item id=1, error=null}
      audioAttrs=AudioAttributes: usage=USAGE_MEDIA content=CONTENT_TYPE_UNKNOWN flags=0x800 tags= bundle=null
      volumeType=1, controlType=2, max=0, current=0
      metadata: size=5, description=Elephants Dream, null, Elephants Dream
      queueTitle=null, size=0
```

## Resources

* [Using a media session](https://developer.android.com/guide/topics/media-apps/working-with-a-media-session)
* [Building an audio app](https://developer.android.com/guide/topics/media-apps/audio-app/building-an-audio-app)
* [Building a video app](https://developer.android.com/guide/topics/media-apps/video-app/building-a-video-app)

---

# THEOplayer Yospace Connector for Android

The Yospace connector provides a Yospace Server-Side Ad Insertion (SSAI) integration for THEOplayer.

## Installation

1. Add the THEOplayer Maven repository to your project-level `settings.gradle` file:
   ```groovy
   dependencyResolutionManagement {
       repositories {
           google()
           mavenCentral()
           maven { url = uri("https://maven.theoplayer.com/releases/") }
       }
   }
   ```
2. Add the Yospace Maven repository to that same `settings.gradle` file. Please refer to the [Yospace Ad Management SDK documentation](https://docs.yospace.com/library/technical/sdks/en/ad-management-sdks-v3/android.html##) for instructions.
3. Add THEOplayer, the Yospace Ad Management SDK and the Yospace Connector as dependencies in your module-level `build.gradle` file:
   ```groovy
   dependencies {
       implementation "com.theoplayer.theoplayer-sdk-android:core:11.+"
       implementation "com.yospace:admanagement-sdk:3.+"
       implementation "com.theoplayer.android-connector:yospace:11.+"
   }
   ```

## Usage

First, follow [the getting started guide for the THEOplayer Android SDK](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/android/getting-started/) to set up a `THEOplayerView` in your app.

Then, create the `YospaceConnector`:

```kotlin
import com.theoplayer.android.api.THEOplayerView
import com.theoplayer.android.connector.yospace.YospaceConnector

val theoPlayerView = findViewById(R.id.theoplayer)
val yospaceConnector = YospaceConnector(theoPlayerView)
```

Finally, set the THEOplayer source to a `SourceDescription` with a `YospaceSsaiDescription` as its `ssai` description:

```kotlin
theoplayerView.player.source = SourceDescription.Builder(
   TypedSource.Builder("https://example.com/stream.m3u8")
      .ssai(
         YospaceSsaiDescription(streamType = YospaceStreamType.LIVE)
      )
      .build()
).build()
```

---

# THEOplayer Uplynk Connector for Android

The Uplynk connector provides a Uplynk integration for THEOplayer.

## Installation

1. Add the THEOplayer Maven repository to your project-level `settings.gradle` file:
   ```groovy
   dependencyResolutionManagement {
       repositories {
           google()
           mavenCentral()
           maven { url = uri("https://maven.theoplayer.com/releases/") }
       }
   }
   ```
2. Add THEOplayer and the Uplynk Connector as dependencies in your module-level `build.gradle` file:
   ```groovy
   dependencies {
       implementation "com.theoplayer.theoplayer-sdk-android:core:11.+"
       implementation "com.theoplayer.android-connector:uplynk:11.+"
   }
   ```

## Usage

First, follow [the getting started guide for the THEOplayer Android SDK](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/android/getting-started/) to set up a `THEOplayerView` in your app.

Then, create the `UplynkConnector`:

```kotlin
import com.theoplayer.android.api.THEOplayerView
import com.theoplayer.android.connector.uplynk.UplynkConnector
...
val theoPlayerView = findViewById(R.id.theoplayer)
val uplynkConnector = UplynkConnector(theoPlayerView)
```

Finally, set the THEOplayer source to a `SourceDescription` with a `UplynkSsaiDescription` as its `ssai` description:

```kotlin
theoplayerView.player.source = SourceDescription
    .Builder(
        TypedSource.Builder("no source")
            .ssai(
                UplynkSsaiDescription
                    .Builder()
                    .prefix("https://content.uplynk.com")
                    .assetIds(listOf(
                        "41afc04d34ad4cbd855db52402ef210e",
                        "c6b61470c27d44c4842346980ec2c7bd",
                        "588f9d967643409580aa5dbe136697a1",
                        "b1927a5d5bd9404c85fde75c307c63ad",
                        "7e9932d922e2459bac1599938f12b272",
                        "a4c40e2a8d5b46338b09d7f863049675",
                        "bcf7d78c4ff94c969b2668a6edc64278",
                    ))
                    .preplayParameters(linkedMapOf(
                        "ad" to "adtest",
                        "ad.lib" to "15_sec_spots"
                    ))
                    .build())
            .build()
    )
    .build()
```

### Getting Ad Information

To retrieve information about the currently playing ad or ad break, you can use the following properties of THEOplayer:

* `player.ads.currentAds`: Provides a list of currently playing ads.
* `player.ads.currentAdBreak`: Provides information about the currently active ad break.

These fields contain generic data for any ad or ad break in THEOplayer. However, for Uplynk-specific ad data, you can access the `customData` property. Below are examples demonstrating how to do that:

```kotlin
fun logCurrentAd() {
    val uplynkAd =
        theoplayerView.player.ads.currentAds.firstOrNull()?.customData as? UplynkAd ?: return
    Log.d(
        TAG, "UplynkAd: " +
                "apiFramework = ${uplynkAd.apiFramework}, " +
                "events = ${uplynkAd.events}, " +
                "duration = ${uplynkAd.duration}, " +
                "height = ${uplynkAd.height}, " +
                "width = ${uplynkAd.width}, " +
                "fwParameters = ${uplynkAd.fwParameters}, " +
                "mimeType = ${uplynkAd.mimeType}"
    )
}

fun logCurrentAdBreak() {
    val uplynkAdBreak =
        theoplayerView.player.ads.currentAdBreak?.customData as? UplynkAdBreak ?: return
    Log.d(
        TAG, "UplynkAdBreak: " +
                "type = ${uplynkAdBreak.type}, " +
                "ads = ${uplynkAdBreak.ads.size}, " +
                "duration = ${uplynkAdBreak.duration}, " +
                "timeOffset = ${uplynkAdBreak.timeOffset}, " +
                "position = ${uplynkAdBreak.position}"
    )
}
```

---

# Introduction

THEOplayer and Uplynk are partners in the streaming industry. The [Uplynk Platform](https://www.uplynk.com/) offers services like encoding, transcoding, server-side ad-insertion, a CDN and more.

> Uplynk was previously known as EdgeIO or Verizon Media. The iOS and Android connector will refer to the new name which is Uplynk.

Uplynk offers services which can enhance the API, UI and UX of video players and applications. The most popular services are called Preplay, Ping and Asset Info. THEOplayer integrates these services so that developers and viewers can benefit from them.

For example,

* Viewers can skip over ads;
* Viewers can see when an ad is playing (and stopping);
* Developers can define the behavior when viewers try to seek over an ad;
* Developers can query metadata to render a playlist in their application.

A live demo of THEOplayer's integration of Uplynk on the Web is available [here](https://cdn.theoplayer.com/demos/verizon-media/index.html).

Once the connector is added to your project, you can import it like so:

```kotlin
import com.theoplayer.android.connector.uplynk.UplynkConnector
```

To instantiate the connector, we first need to create a configuration for it, to describe how the connector should be behave when it comes to Ads:

```kotlin
val uplynkConfiguration = UplynkConfiguration(defaultSkipOffset: ..., onSeekOverAd: ...)
```

> `defaultSkipOffset` describes how many seconds the user has to wait before an ad is skippable. `onSeekOverAd` controls how the connector behaves when seeking over ads. There are three values: `PLAY_ALL`, `PLAY_LAST` and `PLAY_NONE`. The first option forces playback of all the unwatched ads before the seek point. `PLAY_LAST` forces playback of the last ad before the seek point.

We can now instantiate the `UplynkConnector` provided that you have an available `THEOplayer` instance:

```kotlin
val uplynkConnector = UplynkConnector(theoplayerView = yourTHEOplayer, uplynkConfiguration = uplynkConfiguration)
```

For more information on the connector and available APIs, continue to read on the pages below.

* [Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk/preplay.md): this article provides information on how to configure a Uplynk source.
* [Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk/ads.md): this article provides information on which APIs can be leveraged to track and enhance the ad-viewing experience.
* [Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk/ping.md): this article provides information on how to leverage the Ping service and which THEOplayer APIs you should use.

---

# Preplay

This article explains how to leverage the Uplynk Preplay API through THEOplayer. This API allows developers to pre-integrate with Uplynk Preplay service.

Uplynk users can use an API (i.e. Preplay) to generate a streaming playlist given 1 or more assets or advertisements. The back-end of Uplynk stitches the content together and allows for server-side ad-insertion (SSAI) when applicable. This document describes how THEOplayer users should configure their source to leverage this Preplay service.

Assumptions:

* THEOplayer assumes the availability of the Preplay API and Uplynk content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
* THEOplayer assumes that developers who are interested in this feature have a basic understanding of the Preplay API. Uplynk documents this service at <https://api-docs.uplynk.com/#Develop/Preplayv2.htm>
* THEOplayer assumes that developers provide correct asset identifiers, as well as the proper content protection level.

## Stream Configuration (without ads)

The examples below demonstrate how to configure a stream through the Uplynk connector.

We start by creating an `UplynkSsaiDescription` object that describes how to configure an Uplynk source.

```kotlin
    val ssaiDescription = UplynkSsaiDescription
        .Builder()
        .prefix("https://content.uplynk.com")
        .assetType(UplynkAssetType.ASSET)
        .assetIds( your list of asset IDs )
        .preplayParameters( your linkedMapOf preplay parameters)
        .contentProtected(false)
        .build()
```

* `assetIds`: This field identifies the asset. Developers can also specify an array of one or more asset IDs as strings, which will be stitched into a continuous stream. Assets can also be identified by `externalIds` and a `userId` in the builder. `userId` **must** always be provided with `externalIds` else `IllegalArgumentException` will be thrown.

* `preplayParameters`: The `preplayParameters` object should have string-key-string-value combinations, which will be used as query parameters for the Preplay API call. Nested objects are not supported.

* `contentProtected`: Boolean value which will internally set any necessary content-protection information. No content-protection details have to be specified by the customer.

* **A Preplay request must include all parameters defined within the playback request, hence these parameters must be included in the THEOplayer source**. This request must also include a digital signature if the 'Require a token for playback' option is enabled in the back-end on the corresponding live channel. (See also : [Signing a Playback URL Tutorial](https://docs.uplynk.com/docs/sign-playback-url))

* Uplynk specific documentation on the available playback URL query parameters can be found on the Uplynk documentation site under [Customizing Playback via Parameters](https://docs.uplynk.com/docs/customize-playback-via-parameters)

* Some parameters can be excluded from the digital signature calculation. These parameters may enable certain use cases (e.g. DVR) and would for this reason be excluded from the digital signature.

Now, you can create a typed source, and attach the `UplynkSsaiDescription` object to the `ssai` property of the source

```kotlin
    val typedSource = TypedSource.Builder("no source")
        .ssai(ssai)
        .build()
    
    val sourceDescription = SourceDescription.Builder(typedSource)
    yourTHEOplayer.source = sourceDescription
```

## Stream Configuration (with ads)

Ad specific parameters can be passed in the `preplayParameters` argument of the `UplynkSsaiDescription`. An example of that is:

```kotlin
    val ssaiDescription = UplynkSsaiDescription
        .Builder()
        .prefix("https://content.uplynk.com")
        .assetType(UplynkAssetType.ASSET)
        .assetIds(...)
        .preplayParameters(
            linkedMapOf(
                "ad" to "adtest",
                "ad.lib" to "15_sec_spots"
            )
        )
        .contentProtected(false)
        .build()
```

## Preplay Response

THEOplayer automatically interprets the response returned by the Preplay service. However, if a developer wants to perform their own logic with the Preplay API response, then they can register their implementation of the `UplynkListener` interface through the `UplynkConnector` `addListener`. There, you can get access to the `PreplayLiveResponse` or `PreplayVodResponse` objects through:

```kotlin
    uplynkConnector.addListener(object : UplynkListener {
        .....
    
        override fun onPreplayLiveResponse(response: PreplayLiveResponse) {
            Log.d("UplynkConnectorEvents", "PREPLAY_LIVE_RESPONSE $response")
        }
    
        override fun onPreplayVodResponse(response: PreplayVodResponse) {
            Log.d("UplynkConnectorEvents", "PREPLAY_VOD_RESPONSE $response")
        }
    }
```

## Using Tokens

Uplynk users often leverage URL signatures (i.e. tokens) to further secure their content -- on top of AES-128 encryption or studio DRM.

A token is (typically) generated on back-end using an API key and a set of parameters. (The documentation at [Signing a Playback URL Tutorial](https://docs.uplynk.com/docs/sign-playback-url) describes this process.) This set of parameters should also be passed along to the `playbackUrlParameters` in a `UplynkSsaiDescription`.

If you do not configure the `playbackUrlParameters` correctly in relation to your signature parameters, then the Preplay request made by THEOplayer will most likely return an invalid Preplay response, preventing THEOplayer from setting up your stream.

# Related articles

* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk/ads.md)
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk/ping.md)

---

# Uplynk Ads

Uplynk offers support for server-side ad-insertion or in-short SSAI.

This article explains how to use the THEOplayer's Ads APIs to interact with the Uplynk Ads service

## Global Configuration

The examples below demonstrate how to pass along global configuration for Uplynk Ads in the Connector.

```kotlin
val uplynkConfiguration = UplynkConfiguration(defaultSkipOffset: ..., onSeekOverAd: ...)
```

> `defaultSkipOffset` describes how many seconds the user has to wait before an ad is skippable. `onSeekOverAd` controls how the connector behaves when seeking over ads. There are three values: `PLAY_ALL`, `PLAY_LAST` and `PLAY_NONE`. The first option forces playback of all the unwatched ads before the seek point. `PLAY_LAST` forces playback of the last ad before the seek point.

## Uplynk Ads API

Specifying a source which contains server-side ads configured through Uplynk will have the THEOplayer instance report such ads through its Ads API.

Users can use the THEOplayer Ads events to interact with Uplynk Ads:

```kotlin
player.ads.addEventListener(AdsEventTypes.ADD_AD_BREAK) {
    Log.d("UplynkConnectorEvents", "ADD_AD_BREAK ")
}

player.ads.addEventListener(AdsEventTypes.AD_BREAK_BEGIN) {
    Log.d("UplynkConnectorEvents", "AD_BREAK_BEGIN ")
}

player.ads.addEventListener(AdsEventTypes.AD_BEGIN) {
    Log.d("UplynkConnectorEvents", "AD_BEGIN ")
}

player.ads.addEventListener(AdsEventTypes.AD_FIRST_QUARTILE) {
    Log.d("UplynkConnectorEvents", "AD_FIRST_QUARTILE ")
}

player.ads.addEventListener(AdsEventTypes.AD_MIDPOINT) {
    Log.d("UplynkConnectorEvents", "AD_MIDPOINT ")
}

player.ads.addEventListener(AdsEventTypes.AD_THIRD_QUARTILE) {
    Log.d("UplynkConnectorEvents", "AD_THIRD_QUARTILE ")
}

player.ads.addEventListener(AdsEventTypes.AD_END) {
    Log.d("UplynkConnectorEvents", "AD_END ")
}

player.ads.addEventListener(AdsEventTypes.AD_BREAK_END) {
    Log.d("UplynkConnectorEvents", "AD_BREAK_END ")
}

player.ads.addEventListener(AdsEventTypes.AD_ERROR) {
    Log.d("UplynkConnectorEvents", "AD_ERROR " + it.error)
}

player.ads.addEventListener(AdsEventTypes.AD_SKIP) {
    Log.d("UplynkConnectorEvents", "AD_SKIP ")
}

player.addEventListener(PlayerEventTypes.ERROR) {
    Log.d("UplynkConnectorEvents", "ERROR " + it.errorObject)
}
```

Users can also skip Ads through the `skip` API in THEOplayer:

```kotlin
player.ads.skip()
```

> Calling the `player.ads.skip()` function on a live stream will not have any effect.

## Related articles

* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk/preplay.md)
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk/ping.md)

---

# Ping

This article explains how to use the Uplynk Ping API.

The Ping API for Uplynk allows users of their CMS to receive updates about SSAI on running live-streams or provide better playback position beaconing for Video on demand. The Ping API is used together with the Preplay API because the latter provides a session to be used with the Ping API.

This connector allows the user to specify a source for Preplay, and enable or disable certain features of the Ping API. The player will then perform these Ping calls internally, without the user having to write their own Ping client. The response of Ping calls will be exposed for external handling if necessary.

**Feature Assumptions** We assume the SSAI information returned through the Ping API to be of a certain format, which we compile from examples and our own testing. The documentation does not define the structure of this payload very well and only states that it is "like the object returned in Preplay requests", though the formats are not a one-on-one match.

**Assumptions**

* THEOplayer assumes the availability of the Ping API and Uplynk content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
* THEOplayer assumes application developers have a notion of the Ping API, namely any extra parameters to be appended to the requests to Uplynk (e.g. for correct ad insertion). As documented in <https://api-docs.uplynk.com/#Develop/Preplayv2.htm>
* THEOplayer assumes application developers provide proper ID's of the Assets they want to play back, as well as the proper content protection level.

## Configuring Ping

The connector allows specification of the desired features of the Ping API as listed [in the official Ping API documentation](https://api-docs.uplynk.com/#Develop/Preplayv2.htm#Features).

In the THEOplayer-Connector-Uplynk, these features can be activated through the `pingConfiguration` property in the SSAI description:

```kotlin
  val ssaiDescription = UplynkSsaiDescription
    .Builder()
    .prefix("https://content.uplynk.com")
    .assetType(UplynkAssetType.ASSET)
    .assetIds( your list of asset IDs )
    .preplayParameters( your linkedMapOf preplay parameters)
    .contentProtected(false)
    .pingConfiguration(
      UplynkPingConfiguration.Builder()
        .adImpressions(true)
        .freeWheelVideoViews(false)
        .linearAdData(false)
        .build()
    )
    .build()
```

By default, the ping API is disabled for all sessions. To enable it, the `ad.cping=1` parameter must be added to your preplay request. In addition to enabling the API, you must also notify the server of the features you want to support for this viewing session. To specify which features you'd like to enable, you add the`ad.pingf={some value}` parameter to the playback token. The value of the parameter is detailed in the official Ping Documentation.

Ping is enabled and `ad.pingf` is set to a proper value when the `UplynkPingConfiguration` has one or more of the `adImpressions`, `freeWheelVideoViews` or `linearAdData` configuration set to `true`.

If you attempt to call the API without passing in the `ad.cping` parameter, you can throw off the server's ability to make ad event calls correctly.

Sample Preplay URL with `ad.cping`:

`https://content.uplynk.com/preplay/cc829785506f46dda4c605abdf65392b.json?ad=adserver&ad.cping=1&ad.pingf=3`

The default value for `UplynkPingConfiguration` has `adImpressions`, `freeWheelVideoViews` and `linearAdData` all set to false, ie, Ping API will not be used.

## Ping requests

When the Ping API is enabled, THEOplayer will call the Ping URL located at:

```text
{prefix}/session/ping/{sessionID}.json?v=3&pt={currentTime}&ev={event}&ft={freeWheelTime}
```

Where:

* `{prefix}`: Is the prefix URL from the Preplay response.

* `{sessionID}`: Is the session ID from the Preplay response.

* `{currentTime}`: Mandatory parameter. This is the current player time in seconds.

* `{event}`: Is the current Ping event. An event should only be passed when playback starts or when a viewer seeks to a new position. Valid values are:

  * **start**: Pass this event, along with `pt=0`, when the player starts playback. This lets the server know where playback starts and allows the server to fire start events as needed.
  * **seek**: Pass this event when a viewer seeks. This resets the timeline to prevent inadvertently firing events for skipped ads.

* `{freeWheelTime}`: Indicates the playback position, in seconds, right before a viewer seeks to a different position in the timeline. This property is mandatory when the freeWheelVideoViews is used.

## Ping Response

When performed correctly, a Ping request will return a JSON response which is decoded into a `PingResponse`.

The ping response includes:

* nextTime: A new beacon will be scheduled when the player's currentTime passes this value. In case the value is -1, no further beacons will be scheduled.

* ads: Will be interpreted in order to create AdBreak's and Ad's as well as expose Ad information through the THEOplayer instance's `ads.scheduledAds` property.

  * ads.breaks.timeOffset will be used in order to determine the start time of the ad break (in seconds).

  * ads.breaks.ads will be looped in order to extract the list of ad's in an UplynkAdBreak:

    * apiFramework - Indicates the API Framework for the ad (e.g., VPAID).
    * companions - List of companion ads that go with the ad.
    * mimeType - Indicates the ad's Internet media type (aka mime-type)
    * creative - If applicable, indicates the creative to display.
    * events - Object containing all of the events for this ad. Each event type contains an array of URLs.
    * width - If applicable, indicates the width of the creative.
    * height - If applicable, indicates the height of the creative.
    * duration - Indicates the duration, in seconds, of an ad's encoded video.
    * extensions - Contains the custom set of VAST extensions returned by the ad server.
    * fwParameters - If the ad response provided by FreeWheel contains creative parameters, they will be reported as name-value pairs within this object.

  * ads.breaks.duration - Indicates the duration of the ad break.

  * ads.breaks.position - Indicates the position of the ad break. Valid values are: preroll | midroll | postroll | pause | overlay.

  * ads.breaks.type - Indicates the ad break type. Valid values are: "linear", "nonlinear".

The ping response can be retrieved from the `onPingResponse(:)` callback method by setting an `addListener` to the `UplynkConnector` instance.

| Callback method | Description                             | Arguments                                           |
| --------------- | --------------------------------------- | --------------------------------------------------- |
| onPingResponse  | Fired when a Ping response is received. | `pingResponse` argument contains the `PingResponse` |

## Related articles

* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk/preplay.md)
* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/uplynk/ads.md)

---

# OptiView Player iOS & tvOS SDK

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Dolby OptiView Player is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/ios/getting-started.md)

[Set up your first THEOplayer in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/ios/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios.md)

## [🎨UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios.md)

[Build a native interface from scratch.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios.md)

## [🔌Connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios.md)

[Integrate third-party solutions with THEOplayer using our pre-built connectors.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md)

[Find out what's new in the OptiView Player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md)

## [\*️⃣API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios)

[Discover all properties and functions of THEOplayer.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

# Getting started on iOS/tvOS

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

## Introduction

This guide covers the steps to obtain and set up the core Dolby OptiView Player SDK targeting a native iOS/tvOS application. It also provides information and usage of the commonly used APIs.

## Setup

### THEOplayer license

THEOplayer requires a valid THEOplayer license to be configured in order to access the SDK APIs (with the exception of some whitelisted sources hosted by our CDN). Request your license via <https://portal.theoplayer.com>.

After creating your license, you can copy its license string to your clipboard as demonstrated in the screenshot below.

![](https://cdn.theoplayer.com/images/git/theoplayer-ios-sdk-license-string.png)

> **Note**
>
> It's possible to add multiple platforms in a single license i.e. iOS & tvOS.

Later in the guide we explain how to configure the license ([in this section](#adding-the-theoplayer-license)).

### Installation

The THEOplayer SDK is published on the following package managers:

#### CocoaPods

> **Tip**
>
> It's considered good practice to run `pod repo update` before adding new pods to your Podfile. This will help find newly added pods by updating the list of references to the public spec repos. If you just installed CocoaPods or are already up-to-date, then this step can be skipped.

<br />

Add the following entry to your Podfile:

```ruby
target 'MyApp' do
  pod 'THEOplayerSDK-core', '~> 8' # at the time of writing, v8 is the latest major version.
end
```

> **Note**
>
> You can skip specifying the version to get the latest published version of THEOplayerSDK.

Then, using the terminal navigate to the directory where your Podfile is located and run:

```bash
pod install
```

If it's the first time that your project integrates with CocoaPods, then after this step you should stop using the `xcodeproj` file and instead start using the `xcworkspace` file generated by CocoaPods.

#### Swift Package Manager

Navigate to your Xcode project, and select the `Package Dependencies` tab, then click on the `+` button to add a new dependency. Then in the search bar, add the following URL <https://github.com/THEOplayer/theoplayer-sdk-apple>. Choose the version and click on `Add Package`.

The following image illustrates what it should look like:

![](/pr-932/assets/images/ios-getting-started-1-892e63410e915e1e73824a33fa3038de.png)

> **Info**
>
> If Xcode fails to fetch the THEOplayer package, navigate in Terminal to the root directory of your project and run `xcodebuild -resolvePackageDependencies`. This will re-attempt to fetch the packages specified in the project. Restart your Xcode and the package dependencies should be in place.

And make sure the THEOplayerSDK framework is added to the target application:

![](/pr-932/assets/images/ios-getting-started-3-af7cd19fa611660e32ef5dc2b71957b1.png)

## Usage

The following code snippets will demonstrate a basic playback scenario. The demo adopts the `UIKit` framework, and assumes the usage of `UIViewController`.

### Adding the THEOplayer license

[After obtaining your THEOplayer license string](#theoplayer-license), navigate to your Xcode project's plist file and add a new key/value entry. The key should be `THEOplayerLicense` and the value should be your license string.

The following image illustrates what it should look like:

![](/pr-932/assets/images/ios-getting-started-2-773df42c859c8472dbeda2b02ef975c1.png)

### Importing the framework

Add the import statement in your source files where you would like to use THEOplayer:

```swift
import THEOplayerSDK
```

### Setting up the player

THEOplayer provides a configuration object to configure the player settings. In the following snippet we configure the player license to be passed to the player.

> **Note**
>
> If the license is provided through the `plist` file (as mentioned above), then passing again in the player configuration is not required.

```swift
var theoplayer: THEOplayer?
...
...
override func viewDidLoad() {
...
	let configBuilder = THEOplayerConfigurationBuilder()
    configBuilder.license = "your_license_here"
    let theoplayer = THEOplayer(configuration: configBuilder.build())
    self.theoplayer = theoplayer
...
}
```

> **Info**
>
> It is important to keep a strong reference to the player as demonstrated in the above code snippet, otherwise the player will not be retained by ARC.

### Displaying the player

THEOplayer provides conventional APIs similar to UIKit framework's view related APIs. The following snippet demonstrates how to present an inline player view:

```swift
let playerFrame = CGRect(x: 0, y: 0, width: 320, height: 180)
theoplayer.frame = playerFrame
theoplayer.center = view.center
theoplayer.addAsSubview(of: self.view)
```

For more information on how to present the player in various modes, please check out the player documentation for the `PresentationMode` API. The link to the API reference can be found at the end of this guide.

### Adding a source for playback

Sources are passed to the player via an object called SourceDescription. The following snippet uses a source URL that serves an HLS manifest file:

```swift
let source = "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"
let mimeType = "application/x-mpegurl"
theoplayer.source = SourceDescription(source: TypedSource(src: source, type: mimeType))
```

> **Warning**
>
> Sources that are not whitelisted in the THEOplayer license will fail to play. If no player license is configured, then by default only sources from the `theoplayer` domain will play. This can be the reason of failure when updating the source in the snippet above.

### Basic playback controls

#### Starting playback

```swift
theoplayer.play()
```

#### Pausing or stopping playback

```swift
theoplayer.pause()
// or
theoplayer.stop()
```

The difference between the `pause` and `stop` methods is that `pause` will allow the player to continue if `play` is called, whereas `stop` will end playback. When stopped, a new source is expected to be set.

#### Seeking forward or backward in time

```swift
let time: Double = 30.0
theoplayer.currentTime = time
```

#### Seeking forward relatively to current time

```swift
let currentTime = theoplayer.currentTime
// Jump 10 seconds forward
theoplayer.currentTime = currentTime + 10
```

### Attaching player event listeners

It's very useful during the player's lifecycle, especially for state management and UI updates, to listen to certain events that are dispatched from the THEOplayer SDK.

For example, to listen to the time update event and update the UI of the application to reflect the change:

```swift
var eventListener: EventListener?
...
...
eventListener = theoplayer.addEventListener(type: PlayerEventTypes.TIME_UPDATE) { [weak self] event in self?.onTimeUpdate(event: event) }
...
...
func onTimeUpdate(event: TimeUpdateEvent) {
    playerInterfaceView.currentTime = Float(event.currentTime)
}
```

To remove an event listener:

```swift
theoplayer.removeEventListener(type: PlayerEventTypes.TIME_UPDATE, listener: eventListener!)
```

For more player event types, please check out the player documentation for the `PlayerEventTypes` API. The link to the API reference can be found at the end of this guide.

## Useful links

* [THEOplayer iOS SDK API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/index)
* [THEOplayer iOS sample app with basic playback](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Basic-Playback)
* [THEOplayer iOS sample app with Google IMA integration](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Google-IMA)
* [THEOplayer iOS sample app with Google Cast playback](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Google-Cast)

---

# THEOplayer iOS/tvOS 5.0 Feature Integrations

## Modularization

The THEOplayer iOS 5.0 SDK uses modularized features, which means there is a base SDK that can handle basic playback and additional feature integrations are provided as separate modules that can be added as desired. This approach gives more flexibility and results in a reduced application size, since non-required parts are not included in the build of the application.

For example, the core SDK is provided by:

```swift
import THEOplayerSDK
```

Meanwhile, additional features such as Google IMA and Google Cast are provided by:

```swift
import THEOplayerGoogleIMAIntegration
import THEOplayerGoogleCastIntegration
```

## Importing additional integration modules

As shown in the previous section, importing additional integration modules can be done by simply adding the dependency to your swift source file.

For more information on how to fetch the dependencies to your Xcode project, [please check the getting started guide.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/ios/getting-started.md)

**Important Note:** It is required to keep the THEOplayer core SDK and all the required feature modules on the **same** version number. For example one should **not** import `THEOplayerSDK-core~>5.6.0` and `THEOplayer-Integration-GoogleIMA~>5.5.0` in the same project.

## Adding integrations

After importing the dependencies, it's time to create the integrations and connect them to THEOplayer.

Each module provides a **Factory** class that allows the creation of that specific integration. For example, the Google IMA module provides `GoogleImaIntegrationFactory` and the Google Cast module provides `GoogleCastIntegrationFactory`.

Additionally, the `THEOplayer` class provides the `addIntegration(_ integration: Integration)` API which allows adding the integration to the player.

Connecting the feature integration with the `THEOplayer` will make them available to be used. Otherwise, calling an API from an integration without adding it to the `THEOplayer` will cause an error to be thrown.

## Available feature integrations

With THEOplayer iOS 5.0 SDK we currently support the following feature integrations:

| Feature    | Dependency                        | Release | Documentation                                                                                                   |
| ---------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| Google IMA | `THEOplayerGoogleIMAIntegration`  | 5.0.0   | [documentation](https://github.com/THEOplayer/theoplayer-sdk-ios/tree/master/THEOplayer-Integration-GoogleIMA)  |
| Chromecast | `THEOplayerGoogleCastIntegration` | 5.0.0   | [documentation](https://github.com/THEOplayer/theoplayer-sdk-ios/tree/master/THEOplayer-Integration-GoogleCast) |

---

# Migrating to THEOplayer iOS/tvOS SDK 11.x

This article will guide you through updating to THEOplayer iOS/tvOS SDK version 11 (from version 10), and the changes needed in your code.

## Update THEOplayer

Update THEOplayer iOS/tvOS SDK to version 11 in your `Podfile`.

We also recommend adding [our public self-hosted CocoaPods spec repo](https://github.com/THEOplayer/cocoapods-specs) as a source, instead of using the default CocoaPods spec repo. [See below for details.](#self-hosted-spec-repo-for-cocoapods)

```ruby
source 'https://github.com/THEOplayer/cocoapods-specs'

target 'MyApp' do
  pod 'THEOplayerSDK-core', '~> 11'
end
```

If you're using one of [our connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios.md), make sure to update them to the latest version too to ensure proper support for THEOplayer version 11.

## Update deployment target to 15.0 or higher

In version 11, the minimum supported version of our iOS/tvOS SDK is raised from 13.0 to 15.0. This update aligns with current Xcode tooling requirements and enables us to maintain a high standard of performance, security, and long-term support for the SDK.

All devices that support iOS/tvOS 13 and 14 are capable of upgrading to iOS/tvOS 15 or later, meaning no active hardware is excluded by this change. Additionally, based on our internal analytics, fewer than 1% of end users remain on versions below iOS/tvOS 15, and those users are predominantly on older SDK versions. This change allows us to focus development efforts on modern platform capabilities while minimizing impact to production environments.

In your Xcode project settings, make sure the "Deployment target" is set to 15.0 or higher.

![Screenshot of Xcode project settings](/pr-932/assets/images/xcode-deployment-target-25c3050c19e8c7180e197d8d66e51d89.png)

## Builds generated with Xcode 26

Starting with version 11.1.0, in an effort to align with the changes made by Apple regarding the [App Store publishing policy](https://developer.apple.com/news/?id=ueeok6yw), we now build the THEOplayer iOS SDK and its integrations with Xcode 26 (instead of Xcode 16). Effectively, this means that developing a client application using THEOplayer iOS/tvOS SDK will require a minimum version of Xcode 26.

## Self-hosted spec repo for CocoaPods

Starting with version 11, the THEOplayer iOS SDK will be released in a public self-hosted spec repo at <https://github.com/THEOplayer/cocoapods-specs>. This decision comes as a solution to [the planned read-only change to the CocoaPods public spec repo at the end of 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/).

For now, we will keep publishing to both sources, but we highly recommended switching to THEOplayer's spec repo. Starting with 12.0.0 later this year, we plan to stop publishing to the CocoaPods public spec repo.

To get the SDK from our hosted repo, simply add it to your `Podfile`:

```ruby
source 'https://github.com/THEOplayer/cocoapods-specs'
```

## New Chromecast pipeline

We deprecated our old Chromecast pipeline in favor of the new experimental pipeline introduced in version 10.6.0. The new Chromecast pipeline offers new features and improved performance, and we are heading towards switching to the new pipeline by default.

In version 11, the old pipeline is still enabled by default. However, we highly recommend customers switch to the new pipeline by setting `enableExperimentalPipeline` to `true` in [`CastConfiguration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/CastConfiguration).

Starting with 12.0.0 later this year, we plan to retire the `enableExperimentalPipeline` property together with the old pipeline, making the new pipeline the default for all customers.

## Replace or remove usages of deprecated APIs

Some properties and methods that were previously deprecated have been removed from the API. Update your code to use the new APIs instead.

* Removed deprecated `ManifestInterceptor` and `DeveloperSettings` APIs in favor of `NetworkAPI`.
* Renamed `playerMetrics` API to `metrics`.
* Changed `Ad.adBreak` type to be optional.
* Removed deprecated `MediaTrack.activeQualityBandwidth` property in favor of `MediaTrack.activeQuality.bandwidth`.
* Removed deprecated `SourceDescription.enableStreamingDVR` property.
* Errors in `CachingTaskErrorStateChangeEvent` now dispatch cache related error codes instead of `NETWORK_ERROR` code. For more details, check the `cause` property of the error.
* Removed `preloadPublications` in THEOlive API.

---

# How-to guides for OptiView Player iOS & tvOS SDK

Want to start implementing features to your SDK? Our how-to-guides will help you with all kind of integrations!

## [💰Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/introduction.md)

[9 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/introduction.md)

## [📊Analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/introduction.md)

[12 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/introduction.md)

## [Cast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/introduction.md)

## [🔐DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md)

[17 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md)

## [🔌Integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/integrations/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/integrations/introduction.md)

## [🎥Media tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/introduction.md)

[8 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/introduction.md)

## [\*️⃣Miscellaneous](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/introduction.md)

[6 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/introduction.md)

## [📡Network](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/network/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/network/introduction.md)

## [▶️Player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/player/introduction.md)

[5 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/player/introduction.md)

## [💬Text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/introduction.md)

[9 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/introduction.md)

## [🔑License](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/license/introduction.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/license/introduction.md)

## [☁️CMCD](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cmcd/getting-started.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cmcd/getting-started.md)

## [🚀OptiView Live](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/theolive/getting-started.md)

[Integrate OptiView Live streaming into your iOS app.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/theolive/getting-started.md)

---

# Advertisements on iOS

The articles in this section describe how to implement common use-cases related to advertisements. These use-cases can range from customizing the UX during advertisements, to detecting ad blockers.

Consider reading our [Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/user-guide.md) to learn more about advertising and THEOplayer's capabilities.

We recommend starting with [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/set-up-vast-and-vmap.md), as this article explains how to set up client-side advertisements.

### Table of Contents

* Client-side advertisement systems

  * [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/set-up-vast-and-vmap.md)
  * [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/google-ima.md)

* Server-side advertisement systems

  * [Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/yospace.md)
  * [Google DAI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/google-dai.md)
  * [Custom Server Side Ad Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/custom-ssai-integration.md)

* Other

  * [How to subscribe to ad events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/subscribe-to-ad-events.md)
  * [Customizing the ad overlay text](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/customizing-the-ad-overlay-text.md)
  * [Prebid.js](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/prebidjs.md)

---

# Customizing the ad overlay text on iOS

This guide explains how to customize the overlay text shown during an ad break. You may ask this question if you want to change the styling or override the texts shown during an ad break.

Depending on the ad integration kind you use, the steps to take differ.

## Google IMA/DAI

With Google IMA/DAI, it is not possible to directly edit the default UI. You can pass a locale to IMA to completely localize the ad UI.

### Changing or localizing the text

You can pass [your preferred language](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/reference/Classes/IMASettings#language) while adding the Google IMA integration to the player:

```swift
private func setupImaIntegration() {
    let imaSettings = IMASettings()
    imaSettings.language = "nl"

    let imaIntegration: GoogleImaIntegration = GoogleIMAIntegrationFactory.createIntegration(on: self.theoplayer!, with: imaSettings)

    theoplayer.addIntegration(imaIntegration)
    }
```

You can find a list of locales supported by the IMA SDK on iOS [here](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/localization#locale-codes).

### Changing the styling

Please refer to the relevant [Google IMA guide](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/custom-ui) on how to disable the default UI and implement your own ad UI.

## Remarks

* If you customize OptiView Player with [Open Video UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md), there may be other ways to edit certain elements depending on the platform and ad integration. See the [Web SDK CSAI example](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/examples/ads.md) for reference.
* The `Why this ad?` text or the `?` (question mark) icon that may appear while using the Google IMA/DAI integration is inserted by the IMA SDK itself and is required to be displayed with any ad that was not manually selected. The icon is rendered as a VAST icon and is automatically generated by Ad Manager where required.

## Resources

* [THEOplayer advertisement tester](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/advertisement-tester.md)

---

# How to set up VAST and VMAP ads on iOS

This article explains how to schedule client-side VAST and VMAP advertisements through THEOplayer.

* A VAST advertisement is a single ad break, and you can position it as a pre-roll, mid-roll or post-roll.
* A VMAP advertisement is a playlist of ad breaks, and can contain any combination of pre-rolls, mid-rolls and/or post-rolls.

Through the THEOplayer API, app developers can define which "ad integration" they want to use. Scheduling VAST and VMAP ads through all ad integrations is very similar, so consider this article as a reference guide.

On iOS and tvOS, client-side advertisements are scheduled through the [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/google-ima.md) ad integration, so [make sure to set it up](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/google-ima.md) before starting.

## VAST

Setting up a client-side VAST advertisement means scheduling a VAST ad tag.

As an app developer, you associate a VAST ad tag (URL) (e.g. `https://cdn.theoplayer.com/demos/ads/vast/vast.xml`) with a time offset.

You may also schedule multiple ad tags.

Let's consider the following common use-cases:

1. [Scheduling a single pre-roll](#scheduling-a-single-pre-roll)
2. [Scheduling two pre-rolls, two mid-rolls and one post-roll](#scheduling-two-pre-rolls-two-mid-rolls-and-one-post-roll)

### Scheduling a single pre-roll

You configure a [GoogleImaAdDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/GoogleImaAdDescription) in the `ads` property of your [`SourceDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/SourceDescription#/s:13THEOplayerSDK17SourceDescriptionC3adsSayAA02AdD0_pGSgvp).

In this `GoogleImaAdDescription`,

* You set an ad tag URL.
* You set the value of [`timeOffset`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOAdDescription#/c:@M@THEOplayerSDK@objc\(cs\)THEOAdDescription\(py\)timeOffset) to `"start"` (or `00:00:00` or `0%`) to indicate that it's a pre-roll.

```swift
private var source: SourceDescription {
    // Declare a TypedSource object with a stream URL and its type
    let typedSource = TypedSource(
        src: videoUrl,
        type: mimeType
    )

    // The AdDescription object that defines the IMA ad to be played.
    let offset = "start",
    let adDescription: GoogleImaAdDescription = GoogleImaAdDescription(src: adTagUrl, timeOffset: offset)

    // Returns a computed SourceDescription object
    return SourceDescription(
        source: typedSource,
        ads: [adDescription],
        poster: posterUrl
    )
}
```

If you wanted to schedule a post-roll instead of a pre-roll, you set the value of `timeOffset` to `"end"`.

If you want to schedule a mid-roll instead of a pre-roll, you set the value of `timeOffset` to the `HH:MM:SS` format.

For example, to schedule an advertisement at the 15s mark, you set the value of `timeOffset` to `"00:00:15"`.

### Scheduling two pre-rolls, two mid-rolls and one post-roll

Scheduling multiple VAST ads is only slightly different from scheduling a single VAST ad. Instead of passing along one ad description to your array, you pass along multiple ad descriptions to the array.

```swift
let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")

let vastAdTag = "https://cdn.theoplayer.com/demos/ads/vast/vast.xml"
let ad1 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "start")
let ad2 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "start")
let ad3 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "00:00:15")
let ad4 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "00:00:15")
let ad5 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "end")
let source = SourceDescription(source : typedSource, ads: [ad1, ad2, ad3, ad4, ad5])

theoplayer.source = source
```

### Skippable ads

To allow viewers to skip an ad, leverage the `skipOffset` property in your VAST (or VMAP) file, and adhere to the [VAST standard](https://iabtechlab.com/standards/vast/), because this offers the widest support across ad integrations and platforms.

## VMAP

Scheduling a VMAP advertisement is similar to scheduling a VAST advertisement. However, you don't define the `timeOffset`, because the VMAP playlist defines the offsets of each ad break it contains. The time offset helps VAST ads to play at a specific timestamp. VMAP ads can define that behavior inside their manifest file, thus they should not have a timeOffset parameter. This property may not be configured for ad types other than `VAST`. Setting a `timeOffset` on a `VMAP` ad will cause your ads not to be scheduled correctly, unless you explicitly configured an `AdSource.type`, in which case `timeOffset` will be ignored. This is because the player must decide up front when to load the ad source: `VMAP` ads must be loaded immediately in order to schedule them correctly, while loading a `VAST` ad can be deferred until right before the `timeOffset` at which to play them. Therefore, if a `timeOffset` is configured without an explicit `AdSource.Type`, the player will assume that it's a `VAST` ad.

The snippet below demonstrates how to configure a VMAP advertisement.

```swift
let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")

let vmapSource = "https://cdn.theoplayer.com/demos/ads/vmap/single-pre-mid-post-no-skip.xml"
let ad = GoogleImaAdDescription(src : vmapSource)

let source = SourceDescription(source : typedSource, ads: [ad])
theoplayer.source = source
```

## Dynamic scheduling

If you've read our [Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/user-guide.md#dynamic-ad-scheduling), you might have picked up that you can also dynamically schedule VAST advertisements in THEOplayer. All previous samples in this article use static, pre-defined scheduling; you schedule the ads whenever you schedule the stream. With dynamic scheduling, you schedule ads at runtime.

You use the `Ads` interface to schedule an ad description at runtime. More specifically, you invoke the `schedule` function when your video is already playing.

Note that specifying the `timeOffset` is optional, and that this value is an absolute value. For example, let's consider that your current playhead position is at the 20 seconds mark, and that you want to schedule an ad at the 30 seconds mark. To achieve this, you would set `timeOffset: "00:00:30"`, and not `timeOffset: "00:00:10"`, because this would be 10 seconds in the past, and the ad would instantly start playing.

Invoking the following example function when the video is already playing will instantly schedule the VAST ad to be played:

```swift
theoplayer.ads.schedule(adDescription: GoogleImaAdDescription(src: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml"))
```

## Resources

* [Samples for iOS SDK](https://github.com/THEOplayer/samples-ios-sdk)

---

# Yospace on iOS

Yospace is a Server-Side Ad Insertion solution. THEOplayer partnered with Yospace to fully integrate their solution, allowing you to play their streams in a breeze.

## Usage

You need to set up [THEOplayer Yospace connector for iOS](https://github.com/THEOplayer/iOS-Connector/tree/main/Code/Yospace). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/yospace) section to learn all about how to integrate and use the Yospace connector on iOS (/tvOS) SDK.

## Conclusion

This partnership means that we are compatible with each other: THEOplayer has a long history with and is optimized to play Yospace streams. We regularly validate our connectors and are the first to know about changes to the Yospace infrastructure.

## Resources

* [Getting started on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/ios/getting-started.md)
* [Yospace website](https://www.yospace.com/)

---

# Google Dynamic Ad Insertion (DAI) on iOS

Google Dynamic Ad Insertion (DAI) is a Server-Side Ad-Insertion solution offered by Google where THEOplayer offers playback for HLS and DASH streams.

## Prerequisites

To use Google DAI with the THEOplayer iOS SDK, the **THEOplayer GoogleIMA Integration** should be integrated. For instructions on installation, importing and adding the integration, [please refer to this guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/google-ima.md).

## Usage

Define a `GoogleDAITypedSource` and a `GoogleDAIVodConfiguration` to pass to theoplayer's source:

```swift
let daiConfig = GoogleDAIVodConfiguration(videoID: "tears-of-steel", contentSourceID: "2548831", apiKey: "", authToken: nil, streamActivityMonitorID: nil, adTagParameters: nil)
let typedSource = GoogleDAITypedSource(ssai: daiConfig)
theoplayer.source = SourceDescription(source: typedSource)
```

or

```swift
let daiConfig = GoogleDAILiveConfiguration(assetKey: "c-rArva4ShKVIAkNfy6HUQ", apiKey: "", authToken: nil, streamActivityMonitorID: nil, adTagParameters: nil)
let typedSource = GoogleDAITypedSource(ssai: daiConfig)
theoplayer.source = SourceDescription(source: typedSource)
```

And THEOplayer will take care of the rest.

Additional DAI APIs can be found on the `imaIntegration.dai` endpoint.

## Resources

* [Google DAI website](https://developers.google.com/interactive-media-ads)
* [Google DAI iOS Reference](https://developers.google.com/interactive-media-ads/docs/sdks/ios/dai)

---

# Prebid.js on iOS

This article explains how you can connect THEOplayer with Prebid.js. Prebid.js is an open-source header bidding solution. On the client-side, you can request bids from multiple ad networks, take a winning bid and select its associated advertisement. You want to configure and play this selected advertisement in THEOplayer.

Because Prebid.js is a separate library, you can connect it with THEOplayer on any platform that supports both Prebid.js and THEOplayer.

Prebid.js allows you to request bids. This request will respond with bids through a callback function. In this callback function, you have to select a winning bid and extract the ad tag URL. You can configure this URL as THEOplayer's ad source.

## Code example

Refer to <https://docs.prebid.org/prebid-mobile/pbm-api/ios/code-integration-ios.html> to integrate Prebid on the iOS/tvOS SDK. The same THEOplayer API to configure advertisements is available on the iOS SDK, as explained in [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/set-up-vast-and-vmap.md).

## Resources

* [What is Prebid?](https://prebid.org/product-suite/prebidjs/)
* [Prebid.js documentation](https://docs.prebid.org/)
* [Prebid.js on GitHub](https://github.com/prebid/Prebid.js)

---

# Google IMA on iOS

THEOplayer offers support for Google IMA as an ad integration system. Users of Google Ad Manager (formerly known as DoubleClick for Publishers) should use this ad integration.

To schedule and track ads through Google IMA, you need to include the Google IMA SDK and indicate through the API that you want to use Google IMA as the ad integration.

To use Google IMA with the THEOplayer iOS SDK, the **THEOplayer GoogleIMA Integration** should be integrated. The integration is a lightweight module written in Swift, for serving advertisements from the Google IMA SDK.

> **Info**
>
> The THEOplayer GoogleIMA integration supports both iOS and tvOS platforms.

## Installation

The THEOplayer GoogleIMA integration is published on the following package managers:

### CocoaPods

Simply add the following to your project's Podfile:

```ruby
pod 'THEOplayer-Integration-GoogleIMA'
```

The above entry automatically manages the fetching of the IMA SDK dependency.

If you would want to set a specific version for the IMA SDK, replace the Podfile entry with:

```ruby
pod 'THEOplayer-Integration-GoogleIMA/Base'
pod 'GoogleAds-IMA-iOS-SDK', '3.31.0' # specify the desired version
# or
pod 'GoogleAds-IMA-tvOS-SDK', '4.16.0' # specify the desired version
```

### Swift Package Manager

Please check the [installation instruction found here](https://github.com/THEOplayer/theoplayer-sdk-apple/README.md#installation).

> **Info**
>
> This will not get the IMA SDK, but only the THEOplayer IMA integration. The IMA SDKs can be found at <https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios> and <https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos>. You should add these to your Xcode project's `Package Dependencies` for SPM to fetch.

> **Minimum supported IMA SDK versions**
>
> The THEOplayer GoogleIMA integration requires a minimum IMA SDK version of **3.31.0** for iOS and **4.16.0** for tvOS. Using an older version will result in compilation errors due to new APIs used by the integration.

## Import

Import the framework in the source files where it will be used:

```swift
import THEOplayerGoogleIMAIntegration
```

You will also need the THEOplayer core SDK since the THEOplayer GoogleIMA integration extends its functionality.

<br />

To import the THEOplayer core SDK framework add:

```swift
import THEOplayerSDK
```

## Usage

Initialize the integration and pass it to the `THEOplayer` instance:

```swift
let configBuilder = THEOplayerConfigurationBuilder()
configBuilder.license = "your_theoplayer_license"
let theoplayer = THEOplayer(configuration: configBuilder.build()
let imaIntegration = GoogleIMAIntegrationFactory.createIntegration(on: theoplayer)
theoplayer.addIntegration(imaIntegration)
```

Optionally, the `createIntegration` accepts a configuration argument of type IMASetting:

```swift
import GoogleInteractiveMediaAds // required to access definitions such as `IMASettings`
..
..
..
let settings = IMASettings()
settings.language = "en"
let imaIntegration = GoogleIMAIntegrationFactory.createIntegration(on: theoplayer, with: settings)
```

Define a `GoogleImaAdDescription` in your source object to specify the advertisement:

```swift
let adSrc = "https://cdn.theoplayer.com/demos/ads/vast/dfp-preroll-skip-5s.xml"
let adDescription = GoogleImaAdDescription(src: adSrc)
// or
let adDescriptionWithOffset = GoogleImaAdDescription(src: adSrc, timeOffset: "10")
```

The time offset helps VAST ads to play at a specific timestamp. VMAP ads can define that behavior inside their manifest file, thus they should not have a timeOffset parameter.

Finally, we pass the ad description to the player either by setting it in the source:

```swift
let source = "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"
let mimeType = "application/x-mpegurl"
let typedSource = TypedSource(src: source, type: mimeType)
let sourceDescription = SourceDescription(source: typedSource, ads: [adDescription])
theoplayer.source = sourceDescription
```

Or by calling the ad schedule API:

```swift
theoplayer.ads.schedule(adDescription: adDescription)
```

> **A VAST ad without a timeOffset argument in the description will be scheduled to play at the player's currentTime. If the source is not loaded yet, it will be scheduled as a preroll.**

More information on scheduling ads is available at [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/set-up-vast-and-vmap.md).

## Limitations

1. Prerolls must be loaded after the player view is fully rendered and ready. This means attempting to load the ad in the `viewDidLoad` lifecycle will result in a failed request.
2. There is a known bug by Apple that throws runtime warnings concerning the main thread. If you run into this warning while using the IMA SDK, please check [this thread for more information.](https://developer.apple.com/forums/thread/714467?answerId=734799022#734799022)
3. When using `SwiftUI`, make sure to wrap the `THEOplayer` in a `UIViewControllerRepresentable` rather than a `UIViewRepresentable`, as the Google IMA SDK requires a `UIViewController` as a precondition before making ad requests. Otherwise, the ads will not play.

## Remarks

* The release notes for the IMA SDK can be found on the [IMA iOS SDK release history](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/history) page.
* THEOplayer internally supports IMA SDK up until a certain version across different SDKs. We regularly update the internal code to stay up to date with the latest version of IMA SDK. Later versions of IMA SDK should work as expected, however there could be cases where a fix for a breaking change or a newly introduced API is required. Please reach out to us if you require support for a more recent IMA SDK since we intend to rectify this limitation.
* The limitations documented on the support and compatibility pages of the IMA SDK also apply to THEOplayer when the IMA integration is used. You can find the [support matrix of the IMA iOS SDK](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/compatibility) on their website.
* You can try out the snippets mentioned here on our [samples app for iOS SDK](https://github.com/THEOplayer/samples-ios-sdk).

---

# How to subscribe to ad events on iOS

When building a custom UI, or when logging events to an analytics service, app developers often need to be able to listen (and react) to ad events. For example, if an ad break starts, they want to draw a countdown on top of their UI. Alternatively, when an ad error occurs, they want to log this to an analytics server.

This article explains how you can programmatically subscribe to ad-related events.

## Subscribing to an event

This subsection explains how you detect ad-related events. The other subsections zoom in on particular use-cases, such as detecting the beginning and end of an ad.

If you are scheduling [client-side advertisements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/set-up-vast-and-vmap.md), then you use the `Ads` interface to detect ad events.

The `Player` API exposes an [`ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C3adsAA3Ads_pvp) property which belongs to the [`Ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/Ads) interface. Because this `Ads` interface inherits from [`EventDispatcher`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Ads%20Events), you can leverage event listeners in this interface.

The ad-related events are documented in [AdsEventTypes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/AdsEventTypes).

To subscribe to an event, you select an event from this page, use the `Ads` interface, call the `addEventListener` method, and set the event as the first parameter, and the callback as the second parameter.

For example, if you want to track the start of an ad break, you could use the following snippet:

```swift
player.ads.addEventListener(type: AdsEventTypes.AD_BREAK_BEGIN) { (event) in
    print(event)
}
```

## Ad begin and end

Detecting the start and stop of ad breaks and individual ad pods is a common requirement.

This use-case is an application of [Subscribing to an event](#subscribing-to-an-event), and relates to the following events:

* `AD_BEGIN`
* `AD_BREAK_BEGIN`
* `AD_END`
* `AD_BREAK_END`

```swift
player.ads.addEventListener(type: AdsEventTypes.AD_BREAK_BEGIN) { (event) in
    print(event)
}
```

## Ad error

Ad error events might be triggered when an ad blocker is active, or when an "empty" ad is returned. As an app developer, you might want to detect and possibly react to this.

This use-case is an application of [Subscribing to an event](#subscribing-to-an-event), specifically the `AD_ERROR` event.

The following snippet would trigger the callback when an ad error occurs:

```swift
player.ads.addEventListener(type: AdsEventTypes.AD_ERROR) { (event) in
    print(event)
}
```

## Server-side ads

If you're scheduling server-side ads, you might need to use a different interface than the `Ads` interface which you use when scheduling client-side ads.

* [Google DAI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/google-dai.md): if you're using Google DAI, you can use the same API as the one for client-side ads, as described in the sections above.
* [Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/yospace.md): if you're using Yospace, you must use the Yospace interface. You can read more about detecting ad-related events with Yospace at our [Yospace documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/yospace.md).

If you're building a custom server-side ad insertion solution, you might be interested in using our `TextTrack` API to detect `id3/emsg/EventStream/EXT-X-DATERANGE` cues, and the `timeupdate` event in the `Player` interface to determine the current playhead position.

## Resources

* More samples are available on our GitHub repository for the [iOS SDK](https://github.com/THEOplayer/samples-ios-sdk).
* [THEOplayer advertisement tester](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/advertisement-tester.md)

---

# Custom Server Side Ad Insertion on iOS

THEOplayer provides a way to integrate with third-party advertisement providers, and have them report their ads and ad-related events through the THEOplayer APIs.

## Integration ID

To make use of the custom server side ad insertion, first you need an integration ID which will identify the provided sources and ads to the specific ad provider.

## ServerSideAdIntegrationFactory

You would also need to register a `ServerSideAdIntegrationFactory` through [`player.ads.registerServerSideIntegration(integrationId:integrationFactory:)`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/Ads#/s:13THEOplayerSDK3AdsP29registerServerSideIntegration13integrationId0H7FactoryySS_AA0ef2AdG7Handler_pAA0efkG10Controller_pXEtF). The factory receives a `ServerSideAdIntegrationController`. The controller can be used to create the THEOplayer `AdBreak`/`Ad` objects using the `AdBreakInit`/`AdInit` data. Additionally, it can be used to keep the player's state up-to-date such as when an ad begins or ends.

The factory requires an implementation of the `ServerSideAdIntegrationHandler` protocol. The handler provides a few callbacks that can be overridden which allows you to setup and clear the integration as needed.

A concrete implementation can be found [in the Yospace Connector](https://github.com/THEOplayer/iOS-Connector/blob/main/Code/Yospace/Source/YospaceManager.swift).

Meanwhile, an empty implementation would look like below. Details to follow.

```swift
class MyAdIntegration: THEOplayerSDK.ServerSideAdIntegrationHandler {
    let controller: THEOplayerSDK.ServerSideAdIntegrationController

    init(controller: THEOplayerSDK.ServerSideAdIntegrationController) {
        self.controller = controller
    }

    func setSource(source: THEOplayerSDK.SourceDescription) -> Bool {
        return false
    }

    func skipAd(ad: THEOplayerSDK.Ad) -> Bool {
        return false
    }

    func resetSource() -> Bool {
        return true
    }

    func destroy() {
    }
}

player.ads.registerServerSideIntegration(integrationId: "integrationID") { controller in
    return MyAdIntegration(controller: controller)
}
```

### Setting a source

When a new source is loaded into the player the `setSource(source:)` callback is triggered. It allows the integration to transform the source description, e.g. by calling an external service to replace the content URL (`TypedSource.src`), or by adding a fixed pre-roll linear ad to the list of ads (`SourceDescription.ads`). Return `true` if the integration handles this source, or `false` to let the player load the source as-is.

### Skipping an ad

When an ad is requested to be skipped, `skipAd(ad:)` is called. At this point the integration should call the controller's own `skipAd(ad:)` method.

### Resetting a source

Before a new source is loaded into the player, or before the player is destroyed, `resetSource()` is triggered. This allows the integration to clean up any source-specific resources, such as scheduled ads or pending HTTP requests.

### Destroying the player

When the player is destroyed, `destroy()` is called. This allows the integration to clean up any resources, such as UI views or event listeners.

### Creating Ad objects

When the advertisement provider reports an ad, an `AdBreak` and an `Ad` object should be created using `createAdBreak(params:)` and `createAd(params:adBreak:)` methods respectively from the controller. For example, for a pre-roll `AdBreak` containing 2 advertisements it would be:

```swift
let adBreak: THEOplayerSDK.AdBreak = controller.createAdBreak(
    params: THEOplayerSDK.AdBreakInit(timeOffset: 0)
)

let firstAdInit = THEOplayerSDK.AdInit(
    type: "linear",
    id: "first_ad_id",
    skipOffset: 5,
    resourceURI: firstAdResourceURL,
    duration: 10,
    clickThrough: firstAdClickThroughURL
)
let firstAd: THEOplayerSDK.Ad = controller.createAd(params: firstAdInit, adBreak: adBreak)

let secondAdInit = THEOplayerSDK.AdInit(
    type: "linear",
    id: "second_ad_id",
    skipOffset: 5,
    resourceURI: secondAdResourceURL,
    duration: 10,
    clickThrough: secondAdClickThroughURL
)
let secondAd: THEOplayerSDK.Ad = controller.createAd(params: secondAdInit, adBreak: adBreak)
```

### Playing an ad

When an ad begins the playback, the integration must inform the player by calling `controller.beginAd(ad:)`, this will trigger the relevant ad break and ad events.

Additionally, during the playback of the ad, calling `controller.updateAdProgress(ad:progress:)` is needed to keep the player in sync with the progress.

Finally, when the playback of the ad is completed, `controller.endAd(ad:)` should be called to notify about it.

## CustomServerSideAdInsertionConfiguration

To hold the configuration parameters specific to your integration, you can create a new class that conforms to [`CustomServerSideAdInsertionConfiguration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/CustomServerSideAdInsertionConfiguration). Its `customIntegration` property must equal your integration ID, so the player knows which integration should handle the source. This configuration can then be set on a `TypedSource` through its `ssai` property, and read back by the integration in its `setSource(source:)` handler.

Below is an example of a [Yospace integration](https://github.com/THEOplayer/iOS-Connector/tree/main/Code/Yospace) showing `YospaceServerSideAdInsertionConfiguration` conforming to `CustomServerSideAdInsertionConfiguration`:

```swift
public class YospaceServerSideAdInsertionConfiguration: NSObject, THEOplayerSDK.CustomServerSideAdInsertionConfiguration {
    public let integration: THEOplayerSDK.SSAIIntegrationId = .CustomSSAIIntegrationID
    public let customIntegration: String = "yospace"

    public let streamType: YospaceStreamType
    public let sessionProperties: YOSessionProperties

    public init(streamType: YospaceStreamType = .live,
                sessionProperties: YOSessionProperties = YOSessionProperties()) {
        self.streamType = streamType
        self.sessionProperties = sessionProperties
    }
}
```

---

# Analytics on iOS

Video analytics offer all sorts of insights, ranging from the behavior of your viewers, to the performance of your video players.

There are different approaches to collect these insights.

* You can use a commercial video analytics vendor (e.g. Conviva, Mux, Wicket Labs, Youbora, ...).
* You can implement a custom analytics service that you created.
* You can leverage back-end and CDN logs.

Insights are deducted from metrics. Metrics are calculated from raw video data. For example,

1. INSIGHT: "the videos on my website start faster than the industry average (e.g. 4.71s)"
2. METRIC: "because the average video startup time was 1.7s on my website last month"
3. DATA: "that I calculated by measuring the video startup time of 1 million unique video sessions on my website"

The online video streaming industry often talks about Quality of Service (QoS) and Quality of Experience (QoE). When talking about metrics, you'll often hear terms like Startup Time, Buffer Rate, Error Rate, Seek Time, Exit Before Video Start. When talking about raw data, you might hear terms like heartbeat (or ping) events, buffer events, play events, seek events and error events.

## Analytics and video players

As an application developer, you want your video player to expose an API that allows you to track video events and query video states. With this API, a developer can implement an integration with a commercial analytics service, or implement a connection with their custom analytics service.

With a video player, you want to be able to access the raw video data. A video player typically doesn't calculate metrics or insights, because it doesn't have access to historical data.

As an app developer,

1. you want to track raw video data with the assistance of your video player API,
2. do some (optional) processing at runtime,
3. and forward the (processed) data to a remote analytics service.

Then, someone on the back-end, 4. would manage & manipulate this data on this remote analytics service, 5. to convert this raw data into metrics, and the metrics into insights.

## Integrations

THEOplayer *should* be compatible with any industry-standard commercial or custom analytics service. The THEOplayer API gives application developers access to a vast number of video events.

As an app developer, you have the option to leverage one of our existing integrations with commercial analytics services, or the option to create a custom integration.

The following commercial video analytics integrations are documented. These articles explain how to leverage an out-of-the-box integration, or how to implement a connector, or how to achieve a custom implementation with a specific vendor.

* [Mux](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/mux.md)
* [Youbora](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/youbora.md)
* [Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/conviva.md)
* [Adobe Analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/adobe-analytics.md)
* [MediaMelon SmartSight](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/mediamelon-smartsight.md)
* [Wicket Labs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/wicket-labs.md)
* [Google Analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/custom-analytics-integration.md#integrating-google-analytics)
* [Tealium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/tealium.md)
* [Segment](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/segment.md)
* [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/comscore.md)
* [Nielsen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/nielsen.md)

A connector is an open-source integration that is listed on our GitHub at <https://github.com/THEOplayer>. There might be connectors on our GitHub that are missing from the list above.

Alternatively, if you are not able to locate documentation on a specific vendor, then reach out to this vendor, because they might be the maintainer of an integration related to THEOplayer.

## Creating a custom analytics integration

Head over to [Custom Analytics Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/custom-analytics-integration.md) if you want to learn more about creating your own analytics integration using the THEOplayer API.

## THEOplayer Analytics Dashboard

If you've used the THEOplayer Developer Portal - for example to create a THEOplayer SDK -, then you might have noticed that there is an analytics dashboard at <https://portal.theoplayer.com>.

This analytics dashboard is located in the "Usage" tab of your Portal account. The dashboard should resemble the screenshot below.

![THEOplayer Portal Analytics Dashboard](/pr-932/assets/images/analytics-introduction-portal-dashboard-777c17a7b2bbf13b27a40bfdc3a4d1f9.png "THEOplayer Portal Analytics Dashboard")

This dashboard allows you to track your [impressions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-is-an-impression.md) across different periods of times across different SDKs.

We don't *really* consider this dashboard as a "video analytics service". The primary purpose of this dashboard is for you to monitor your impressions, as the impressions might be related to your THEOplayer pricing model. That being said, it is a useful dashboard, as it visualizes the consumption of your videos throughout time.

---

# Mux on iOS

[Mux /data](https://mux.com/data/) is a video analytics service. Mux is currently the maintainer of the Mux-THEOplayer integration. Their documentation describes how to connect Mux to THEOplayer for each of the THEOplayer SDKs.

## Connecting Mux to THEOplayer

Mux is currently the maintainer of the Mux-THEOplayer integration for iOS. Their documentation for the THEOplayer iOS SDK is located at <https://docs.mux.com/guides/data/monitor-theoplayer-ios>.

If you choose to [build a custom integration](https://docs.mux.com/guides/data/build-a-custom-integration), the following article from Mux describes how you can achieve this:

* Objective-C: <https://docs.mux.com/guides/data/custom-objectivec-integration>

---

# Youbora (NPAW Plugin) on iOS

Youbora adapter (NPAW plugin) for THEOplayer is maintained by the NPAW team and regularly kept up to date to make sure it is compatible with the latest THEOplayer version.

In order to access the links on this guide, you may need to login with your NPAW developer account.

Before you get started, for general information on NPAW plugin, please refer to [this guide](https://documentation.npaw.com/integration-docs/docs/first-steps).

## Connecting Youbora to THEOplayer

For general information on NPAW plugin for iOS/tvOS and how to set it up, please refer to [this guide](https://documentation.npaw.com/integration-docs/docs/ios-integration-guide).

For integration with THEOplayer iOS/tvOS SDK, please reach out to the NPAW team to get the latest resources.

## Related articles

* [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/set-up-vast-and-vmap.md)

---

# Conviva on iOS

Conviva is an analytics service. THEOplayer offers a connector which can be initialized depending upon the customer requirements for measuring all the solutions offered by Conviva (Video Analytics & Ads Analytics).

The Conviva connector has full support for Video and Ad Analytics offered by Conviva. It is built using all public APIs of THEOplayer and Conviva, so it can be maintained and managed across teams, and any new updates or changes can easily be modified and customized as per customer requirements. (There is no dependency on the THEOplayer or Conviva library version.)

## Usage

You need to set up [THEOplayer Conviva Connector for iOS](https://github.com/THEOplayer/iOS-Connector/tree/main/Code/Conviva). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/conviva) section to learn all about how to integrate and use the Conviva connector on iOS SDK.

## Resources

* Demo page: [Conviva Analytics Test Page](https://cdn.theoplayer.com/conviva/conviva_test.html)
* [Conviva SDK Documentation](https://cdn.theoplayer.com/conviva/Conviva_Documentation_4.0.14/index.html)
* More Information about [Conviva Video Experience](https://www.conviva.com/experience-insights/)
* More Information about [Conviva Ad Insights](https://www.conviva.com/ad-insights/)

---

# Custom Analytics Integration on iOS

Video analytics provide tremendous insights into your user's QoE, bring extra business intelligence and enhance decision-making. There are a wide selection of analytics systems in the current landscape (e.g. Google Analytics, Conviva, ...), often with their own focus, expertise and value.

What most video analytics systems have in common is that their insights (partly) originate from video events:

* `play` event: a user clicks the play button, or resumes playback after a pause
* `fullscreen` event: a user goes fullscreen on their device
* `quality` change event: the video quality switches from a lower resolution to a higher one
* `waiting` event: the video is stalled and unable to continue playback for some time
* ...

To access these video events, and forward them to a video analytics system, an application developer must hook into the video player API.

This guide explains the role of the THEOplayer API. Additionally, it explains how to do a custom integration with an analytics system, with Google Analytics as a sample case. This guide should be useful when THEOplayer doesn't have an existing sample integration with a specific (commercial) video analytics service, or when you want to fully control the data flow.

Keep in mind that Google Analytics is not the only analytics system out there. The APIs and concepts that we'll discuss are relevant for all analytics systems. For example, you can easily swap out the Google Analytics example with something like [Nielsen](https://www.nielsen.com/solutions/audience-measurement/) or [Youbora](https://npaw.com/) (NPAW), or even your own custom analytics back-end.

## Prerequisites

There are two prerequisites in order to continue with this guide:

1. You have a THEOplayer license. You can grab a license at <https://portal.theoplayer.com>.
2. You have some basic knowledge on how to use THEOplayer, and can navigate comfortably through [the API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios) to find relevant events.

Refer to our [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/ios/getting-started.md) before advancing to the code samples.

## API

You can access the video data through the THEOplayer API. Through the API, you can subscribe to events, and attach a callback. For example, when the `ended` event is triggered (meaning: someone completely watched the video), your callback could be that when this happens, you do a request to a remote video analytics service.

Events are organized across interfaces and subinterfaces, as illustrated by the image below. For example, the player contains general video player events like `play`, `pause` and `ended`. The ads interface contains events related to advertisements, like `adbreakbegin` and `adend`.

![THEOplayer API Interfaces and Events](/pr-932/assets/images/analytics-events-185d6ab52b556af08d8300b545ae5876.png "THEOplayer API Interfaces and Events")

When creating a custom analytics implementation, you must familiarize yourself with the relevant interfaces and events. Below is an (incomplete) list of some common interfaces and their event maps.

* [Player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/PlayerEventTypes): general video events, like a play, a pause, and so on.
* [Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Ads%20Events): to detect when an ad starts and stops.
* [AudioTrackList](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/AudioTrackListEventTypes): to detect when a new audio track is added, or when another audio track becomes active.
* [TextTrackList](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/TextTrackListEventTypes): comparable to AudioTrackList, but for subtitles, closed captions and metadata (e.g. id3, emsg, EventStream, EXT-X-DATERANGE).
* Cast: [AirPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/AirPlayEventTypes) and [Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/ChromecastEventTypes) events.

Video quality events are unavailable on iOS due to Apple limitations.

Note that maintaining the above list manually is unfortunately a no-go because our interfaces evolve. This means that you should research your events through our [API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios).

When doing a custom analytics integration, you should also check our articles on [error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/error/introduction.md).

### Video analytics metrics and events

Let's discuss some popular metrics, and how you could track them with video player events.

Plays (or Impressions). This metric represents the amount of plays. You can calculate this event by identifying the first `playing` event after every `sourcechange` event.

Video Startup Time (or Time-to-First-Frame or Join Latency). This metric represents the time it takes your video to start. You can calculate this event by calculating the difference between the timestamps of the first `playing` and the first `play` event after every `sourcechange` event.

Seek Time (or Seek Latency). This metric represents the time it takes for your video to resume when you scrub to another position. You can calculate this event by calculating the difference between the timestamps of the `seeking` and the `seeked` event.

Watch Time. This metric represents how much time is spent watching content by your viewers. You calculate this value by tracking the `playing` event, and halting it when the `waiting`, `pause`, `ended` or `error` event occurs.

Rebuffer Ratio (or Stalls). This metric represents how often the viewer is watching the "spinner icon" versus the actual video. This metric is closely related to the Watch Time. You can calculate this event by tracking the `waiting` event, which is triggered when the video starts to stall, and the `playing` event.

Average Bitrate. This metric represents the average video quality that your viewers are watching. You can calculate this metric by tracking the `activequalitychanged` event of the active video track.

Average % Complete (or Watched Ratio). This metric represents the relative completion rate of your videos. This metric is related to the Watch Time, and related in a similar fashion. You could also use the player's `duration` to determine the length of the asset.

Exit Before Video Start. This metric represents how often your viewers aren't able to start the video, even though they had the intent to watch it. You can calculate this metric by tracking the first `play` event, and it never getting to the `playing` event.

Video Playback Failure. This metric represents how often your viewers have a problem with playback once a video starts. You can calculate this metric by tracking the `error` event after the first `playing` event.

Note that these proposed calculations are only loosely formulated to help you understand the relationship between video metrics and a video player API.

When talking about metrics, you often apply dimensions or filters to a metric. For example, when talking about the "Plays" metric (see above), the base metric would apply to all logs throughout all time. When analyzing your data, you might want to apply a filter (or dimension), such time (to consider all "Plays" for a specific period of time), asset (to research a specific asset), user (to check a specific user's activity), and so on. It is up to you (or your commercial analytics service) to associate certain dimensions with a raw video player event.

### Session management

It's important to note that THEOplayer doesn't associate a user ID or session ID with an event. (This is pretty normal, because THEOplayer is a client-side video player library. It's not aware of your "back-end" "CMS", "users" or "sessions".)

When you are implementing an analytics service, you usually want to associate a session or user with an event when forwarding the event to your remote analytics database. As an app developer, it is your responsibility to do this association.

## Integrating Google Analytics

Refer to Google Analytics' documentation at <https://developers.google.com/analytics/solutions/mobile> if you're interested in integrating Google Analytics. Similar to the Web SDK, developers would subscribe to events and properties emitted by THEOplayer and create a custom mapping to the Google Analytics library.

## Conclusion

A custom analytics integration gives you full control over your code, and the data you want to submit to your analytics system. This data is exposed through the THEOplayer API, and allows you to subscribe to events such as the start of an ad, or a direction change event in 360/VR playback.

Extra resources:

1. [THEOplayer API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios)
2. [THEOplayer Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/ios/getting-started.md)

---

# Adobe Analytics on iOS

[Adobe Streaming Media Collection Add-on](https://experienceleague.adobe.com/en/docs/media-analytics/using/media-overview) is a video analytics service, and is part of [Adobe Experience Cloud](https://business.adobe.com/products/analytics/adobe-analytics.html).

This product was formerly known as "Adobe Heartbeat".

Adobe Streaming Media Collection Add-on or older iterations of this product can be implemented on top of THEOplayer as a custom analytics integration.

Refer to the article on [building a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/custom-analytics-integration.md) for more information on how to build an integration on top of THEOplayer.

## Connecting Adobe Analytics to THEOplayer

You can use the [Adobe Experience Platform (AEP) Mobile SDKs](https://experienceleague.adobe.com/en/docs/media-analytics/using/implementation/analytics-only/media-sdk/mobile-implementation) for iOS and Android to integrate Adobe Analytics, as the Media Analytics SDK for iOS has been [deprecated since 31 August 2021](https://experienceleague.adobe.com/en/docs/media-analytics/using/getting-started/end-of-support/end-of-support-faqs).

The Media API reference is available [here](https://developer.adobe.com/client-sdks/solution/adobe-media-analytics/api-reference/).

Alternatively, you can consider using the [RESTful Media Collection API](https://experienceleague.adobe.com/en/docs/media-analytics/using/implementation/analytics-only/streaming-media-apis/mc-api-overview).

For more information about how to use Adobe Analytics on other platforms, please refer to the [Adobe Streaming Media Collection Add-on overview](https://experienceleague.adobe.com/en/docs/media-analytics/using/media-overview).

---

# MediaMelon SmartSight on iOS

MediaMelon SmartSight is an analytics service maintained by MediaMelon. The library is maintained by the MediaMelon team.

## Prerequisites

1. A valid THEOplayer license.
2. A MediaMelon SDK.
3. A MediaMelon Customer ID (**Note:** If you do not know your Customer ID contact MediaMelon at <support@mediamelon.com>.

## Connecting MediaMelon to THEOplayer

For the most up to date information on how to integrate MediaMelon SmartSight with THEOplayer iOS/tvOS SDK, please refer to their integration guide [here for iOS](https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/ios) and [here for tvOS](https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/tvos-sdk), where you can find step by step guidance as well as code examples.

---

# Wicket Labs on iOS

[Wicket Labs](https://www.wicketlabs.com/) is an audience insights platform for video, and offers products like the "[Wicket Scoreboard](https://www.wicketlabs.com/wicket-scorecard/)".

To generate these insights, a video player emits playback events to a third-party database service (e.g. Firebase). Wicket Labs provides [guidelines](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/) on how to format these playback events. Wicket Labs then pulls the data from the selected third-party database service, and integrates it into their platform.

## Connecting Wicket Labs with THEOplayer

An integration with Wicket Labs can be integrated on top of THEOplayer.

1. As a customer of Wicket Labs, you need to verify that Wicket Labs can ingest data from your selected database solution (e.g. Firebase). *(It should be noted that Wicket Labs does not provide its own database service to store playback events. Instead, Wicket Labs plugs into your database service.)*
2. As a customer of Wicket Labs and THEOplayer, you need to emit the playback events ([as defined per Wicket Labs](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/)) to your database service. In other words, you need to hook into certain events emitted by THEOplayer, reformat them, and re-emit them to your database service.

* To facilitate the implementation of Wicket Labs \[related to THEOplayer], Wicket Labs and THEOplayer collaborate on publicly available code samples. These code samples are published as Git repositories on <https://github.com/THEOplayer>.
* Developers are free to do their custom integration of Wicket Labs and THEOplayer, or may modify the publicly available code samples.
  * Wicket Labs' article on [How to Setup Firebase for OTT Video Services](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/) is a great starting point if you're interested in customizing.

- Our article on [Custom Analytics Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/custom-analytics-integration.md) may help developers out.

THEOplayer and Wicket Labs currently do not host a sample implementation for iOS or tvOS on GitHub.

Developers are encouraged to use our [sample implementation for the Web SDK](https://github.com/THEOplayer/samples-wicket-labs-html5-sdk) as a reference for the order and format of the playback events, together with Wicket Labs' [guidelines on setting up Firebase](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/), as a starting point. Additionally, developers are encouraged to reach out to their contacts at THEOplayer and/or Wicket Labs if they need assistance, which could prompt THEOplayer and Wicket Labs into publishing a sample implementation on GitHub.

## Related links

* wicketlabs.com: [How to Setup Firebase for OTT Video Services](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/)

---

# Tealium on iOS

Tealium is a [tag management system](https://tealium.com/resource/fundamentals/what-is-tag-management/) and offers [integrations](https://tealium.com/integrations/) with [Google Analytics](https://tealium.com/integrations/google-analytics/), [Adobe Analytics](https://tealium.com/integrations/adobe-analytics/), and others.

Tealium can be implemented on top of THEOplayer as a custom analytics integration.

Refer to the article on [building a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/custom-analytics-integration.md) for more information on how to build an integration on top of THEOplayer.

## Connecting Tealium to THEOplayer

The Tealium documentation includes articles that describe:

* [How to install Tealium for Swift](https://docs.tealium.com/platforms/ios-swift/install/).
* [How to implement tracking](https://docs.tealium.com/platforms/ios-swift/track/).
* [Basic video tracking](https://docs.tealium.com/platforms/getting-started-web/data-layer/definitions/basic-video-tracking/) on the data layer.
* [An introduction to the Data Layer](https://docs.tealium.com/platforms/getting-started-web/data-layer/an-introduction-to-the-data-layer/).

For other platforms, refer to the documentation at <https://docs.tealium.com/platforms/>.

---

# Segment on iOS

Segment is a [Customer Data Platform](https://segment.com/docs/guides/), and offers [integrations](https://segment.com/docs/connections/destinations/catalog/index-all/) with [Google Analytics](https://segment.com/docs/connections/destinations/catalog/google-analytics/), [Adobe Analytics](https://segment.com/docs/connections/destinations/catalog/adobe-analytics/), [Youbora](https://segment.com/docs/connections/destinations/catalog/youbora/), and others.

Segment sets up "[Connections](https://segment.com/docs/connections/)" between "[Sources](https://segment.com/docs/connections/sources/)" and "[Destinations](https://segment.com/docs/connections/destinations/)".

* Sources send messages into Segment (and other tools). They have JavaScript source, an Android source, and so on.
* Destinations (like Google Analytics, Adobe Analytics, Youbora) receive messages from Segment.

Segment can be implemented on top of THEOplayer as a custom analytics integration.

Refer to the article on [building a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/analytics/custom-analytics-integration.md) for more information on how to build an integration on top of THEOplayer.

## Connecting Segment to THEOplayer

You'll (most likely) use the "[Analytics for iOS SDK](https://segment.com/docs/connections/sources/catalog/libraries/mobile/ios/)" source to get access to the Segment API.

Then, for each of your destinations, you want to figure out whether you can use the "Video Spec", or whether you need to do something specific for some destinations (e.g. [Youbora](https://segment.com/docs/connections/destinations/catalog/youbora/)).

Segment describes a "Video Spec" at <https://segment.com/docs/connections/spec/video/>, but this article also mentions that "not all destinations support video tracking and you should always check with the individual destination documentation to confirm".

For other platforms, refer to the documentation at <https://segment.com/docs/>.

---

# Comscore on iOS

Comscore is an analytics service which provides audience measurement and content ratings. THEOplayer offers a connector which reports playback and ad events to the Comscore Streaming Tag.

## Usage

You need to set up [THEOplayer Comscore Connector for iOS](https://github.com/THEOplayer/iOS-Connector/tree/main/Code/Comscore). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/comscore) section to learn all about how to integrate and use the Comscore connector on iOS SDK.

## Resources

* [Comscore website](https://www.comscore.com/)

---

# Nielsen on iOS

Nielsen is an analytics service which provides audience measurement. THEOplayer offers a connector which reports playback and ad events to the Nielsen SDK.

## Usage

You need to set up [THEOplayer Nielsen Connector for iOS](https://github.com/THEOplayer/iOS-Connector/tree/main/Code/Nielsen). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/nielsen) section to learn all about how to integrate and use the Nielsen connector on iOS SDK.

## Resources

* [Nielsen website](https://www.nielsen.com/solutions/audience-measurement/)

---

# Chromecast on iOS

In this section you will learn everything about how THEOplayer works with Chromecast.

To use Google Cast, also known as Chromecast, with the THEOplayer iOS SDK, the **THEOplayer GoogleCast Integration** should be integrated. The integration is a lightweight module written in Swift, to enable casting playback from an iOS device to a receiver application.

## Installation

The THEOplayer GoogleCast integration is published on the following package managers:

### CocoaPods

Simply add the following to your project's Podfile:

```ruby
pod 'THEOplayer-Integration-GoogleCast'
```

The above entry automatically manages the fetching of the GoogleCast SDK dependency.

In case where the integrator would want to manage fetching a specific version of the GoogleCast SDK, then replace the Podfile entry with:

```ruby
pod 'THEOplayer-Integration-GoogleIMA/Base'
pod 'google-cast-sdk-dynamic-xcframework', '4.8.3' # specify the desired version
```

### Swift Package Manager

Please check the [installation instruction found here](https://github.com/THEOplayer/theoplayer-sdk-apple/README.md#installation)

> **Warning**
>
> This will not get the GoogleCast SDK, but only the THEOplayer GoogleCast integration. You need to manage fetching the GoogleCast SDK dependency.

## Import

Import the framework in the source files where it will be used:

```swift
import THEOplayerGoogleCastIntegration
```

You will also need the THEOplayer core SDK since the THEOplayer GoogleCast integration extends its functionality.

<br />

To import the THEOplayer core SDK framework add:

```swift
import THEOplayerSDK
```

## Usage

First set the context in your `AppDelegate` file's `didFinishLaunchingWithOptions` method:

```swift
THEOplayerGoogleCastIntegration.CastIntegrationHelper.setGCKCastContextSharedInstanceWithDefaultCastOptions()
```

> **Note**
>
> The above method will set the options for `GCKCastContext` with a CAF receiver application. If a custom context must be set, instead of calling the `setGCKCastContextSharedInstanceWithDefaultCastOptions` method, the implementation should specify an `GCKDiscoveryCriteria` in the context with an `applicationID` parameter. You can find the default THEOplayer CAF V3 default application ID at `CastIntegrationHelper.defaultV3ReceiverApplicationID`.

> **Info**
>
> The THEOplayer Google Cast integration only supports CAF receivers.

Second, you will need to provide some privacy permissions and network discovery allowances. For more information on this, please check the [following documentation about permissions and discovery.](https://developers.google.com/cast/docs/ios_sender/permissions_and_discovery)

After initializing your `THEOplayer` instance, initialize the integration and pass it to the `THEOplayer` instance:

```swift
let configBuilder = THEOplayerConfigurationBuilder()
configBuilder.license = "your_theoplayer_license"
let theoplayer = THEOplayer(configuration: configBuilder.build()

let castConfiguration: CastConfiguration = CastConfiguration(strategy: .auto)
let castIntegration: THEOplayerSDK.Integration = GoogleCastIntegrationFactory.createIntegration(on: theoplayer, with: castConfiguration)
theoplayer.addIntegration(castIntegration)
```

> **Info**
>
> Additional APIs can be found on the `castIntegration` or `theoplayer.cast.chromecast` endpoints.

<br />

For more extensive example on how to implement GoogleCast with THEOplayer, please check [this sample app](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Native-GoogleCast).

## API

As a developer, you might need to use the THEOplayer Chromecast API to build a custom Chromecast UI and UX, or to dispatch an event to an analytics service, or for workflow purposes.

For more information, see the API reference of [`Chromecast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/Chromecast), a sub-protocol of [`Cast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/Cast).

## Sender Applications vs Receiver Applications

When a viewer is streaming through a Chromecast device, they are actually casting content from a sender application (e.g. an Android application) to a receiver application. A sender application informs a physical Chromecast device which receiver application it should load through an application ID.

![Casting approaches](/pr-932/assets/images/casting-approaches-45dc2983f20d11409d27d3248b57a6ef.png "Casting approaches")

By specifying the application ID, you implicitly connect it with a type of receiver application. The following three types of receiver applications are common:

| Type                                    | Maintainer             | Info                                                                                                                                                                                                                        | Benefits                                                                                                                                                                                                      | Disadvantages                                                                                                                       |
| --------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Default THEOplayer Receiver Application | THEOplayer             | This is the default receiver application THEOplayer SDKs will connect with. The app ID of this default THEOplayer receiver application is `8E80B9CE`.                                                                       | You (i.e. the developer) do not need to do anything extra on the Chromecast receiver application side. You don't need to create a Chromecast receiver, you don't need to register it at, ... - it just works. | You are limited w\.r.t. customizing the UI and integrating custom logic.                                                            |
| Custom THEOplayer Receiver Application  | Developer + THEOplayer | This is a custom receiver application you can build, and where you integrate the [THEOplayer Chromecast SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md). | You (i.e. the developer) can adjust the look and feel, and integrate custom logic.                                                                                                                            | You need to create a Chromecast receiver, register it, maintain it, ...                                                             |
| Customer Receiver Application           | Developer              | This is a custom receiver application you can build, but without using the THEOplayer Chromecast SDK.                                                                                                                       | The THEOplayer Chromecast Receiver SDK is not a dependency.                                                                                                                                                   | You are responsible for building and maintaining the receiver application, and its connection with the various sender applications. |

If you have implemented THEOplayer in your sender application, you can [enable Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/enable-chromecast-on-the-sender.md). Furthermore, you can also [specify the application ID](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/enable-chromecast-on-the-sender.md#custom-receiver-app) in your sender application.

## Whitelisting Receiver Applications

Streaming services and products often require you to whitelist domain names to allow playback. When viewers are casting content to a Chromecast receiver application, your Chromecast device will actually stream the content on a domain name. In other words: CORS and whitelisting/blacklisting policies do apply to Chromecast sessions. Ensure that you've whitelisted the domain name which hosts your Chromecast receiver application. (You can look up the domain name of your receiver application at <https://cast.google.com/publish/#/overview>.)

If you're using the Default THEOplayer Receiver Application you may whitelist `https://d3ojqkc95d8mrd.cloudfront.net/`.

## Related articles

* [Connecting from custom Sender applications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/connecting-from-custom-sender-applications.md)
* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/how-to-configure-to-a-different-stream.md)
* [Sending messages from/to Sender to/from Receiver](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/sending-messages-from-to-sender-to-from-receiver.md)
* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)
* [Enable Chromecast on the Sender](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/enable-chromecast-on-the-sender.md)

---

# Connecting from custom Sender applications on iOS

In general, the following flow should be followed:

1. Set up Google Cast context with correct receiver application ID.
2. Connect to Chromecast device.
3. Set up Google Cast MediaInfo object with correct contentID and contentType.
4. Send Google Cast LoadRequest with a serialized THEOplayer SourceDescription object as a key in the customData of the LoadRequest. So something like `{sourceDescription: ${SourceDescription you want to cast}}`.

## Usage

When launching your application, start your Google Cast context using the following snippet:

```swift
let options = GCKCastOptions(receiverApplicationID: "8E80B9CE")
GCKCastContext.setSharedInstanceWith(options)
```

Once this is done, it’s necessary to start a session. This is usually done by creating a cast button somewhere in your UI using `GCKUICastButton`, which when pressed opens up a dialog allowing you to select a device and start a session.

Once a session is started, you can start playing back content. The THEOplayer Chromecast receiver is capable of playing back content easily using the default Google Cast APIs (with `GCKMediaInformationBuilder` and `LoadRequest`). However, to use the more advanced functionality, you will need to pass in custom data in the [`GCKMediaLoadOptions`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_load_options) object.

This custom data follows the structure of `SourceDescription` as used in the web version of THEOplayer, except we have to use `NSDictionary` notation.

```swift
let metadata = GCKMediaMetadata()
metadata.setString("Title", forKey: kGCKMetadataKeyTitle)
metadata.setString("Subtitle", forKey: kGCKMetadataKeySubtitle)

let contentURL = "https://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/manifest(format=mpd-time-csf)"
let contentID = "622b189f-ec39-43f2-93a2-201ac4e31ce1"

let informationBuilder = GCKMediaInformationBuilder(contentURL: contentURL)
informationBuilder.contentID = contentID
informationBuilder.streamType = .unknown
informationBuilder.contentType = "application/dash+xml"
informationBuilder.streamDuration = 0.0
informationBuilder.mediaTracks = nil
informationBuilder.metadata = metadata
let information = informationBuilder.build()

let sourceDescription = [
    "sources": [
        [
            "src": "https://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/manifest(format=mpd-time-csf)",
            "type": "application/dash+xml",
            "contentProtection": [
                "widevine": [
                    "licenseAcquisitionURL": "https://amssamples.keydelivery.mediaservices.windows.net/Widevine/?KID=1ab45440-532c-4399-94dc-5c5ad9584bac"
                ]
            ]
        ]
    ]
]

let loadOptions = GCKMediaLoadOptions()
loadOptions.autoplay = true
loadOptions.playPosition = 0.0
loadOptions.customData = ["sourceDescription": sourceDescription]

castSession!.remoteMediaClient?.loadMedia(mediaInfo, with: loadOptions)
```

Note that you should also adapt the contentID and contentType in the arguments for the `GCKMediaInformation` initializer.

You have to use the Chromecast API to implement additional logic such as pausing the Chromecast Receiver application, fetching the video's progress, ...

## Related articles

* [How can we track the first play(ing) event?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/player/track-first-playing-event.md)

* [How to start with a specific quality?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/start-with-specific-quality.md)

* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)

* [How to know whether a live stream is playing?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-know-when-livestream-is-playing.md)

* [Getting started on Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md)

---

# How to configure a different stream to Chromecast on iOS

Some streaming setups require you to cast a different stream to a Chromecast Receiver device than the one playing on a Chromecast Receiver device. For example, if you're playing HLS + FairPlay DRM on your iOS application, you need to cast a different source with DASH + Widevine DRM to your Chromecast application, because Chromecast applications aren't able to support FairPlay.

You can achieve this use case with the ChromecastConnection API.

## ChromecastConnection API

The ChromecastConnection API allows you to implement callbacks related to Chromecast playback. To achieve the described use case you can use the `onStart` (i.e. the start of a Chromecast session) to set a new stream, and `onStop` (i.e. the end of a Chromecast session) to (re)set your previous stream.

You may also be interested in `onJoin` (i.e. joining an existing Chromecast session with a new device) or `onLeave` (i.e. leaving an existing Chromecast session on a device).

To achieve this use case on the iOS SDK, you have to leverage the [`ChromecastConnectionDelegate`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/Chromecast_Objc#/c:@M@THEOplayerSDK@objc\(pl\)THEOplayerChromecast\(im\)setConnectionDelegate:) of your [`THEOplayer`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer) object.

The snippet below is an example of how your `ChromecastConnectionDelegate` could look like. This particular snippet has two [sources](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/SourceDescription):

1. `senderSource` is intended for playback on your sender device (i.e. your iOS app)
2. `chromecastSource` is intended for playback on your Chromecast application

The `ChromecastConnectionDelegate` is used to:

1. Set the `chromecastSource` when Chromecast playback starts through the `onStart` callback.
2. Revert to the `senderSource` when Chromecast playback stops through the `onStop` callback.

```swift
import UIKit
import THEOplayerSDK

class ChromecastController: ChromecastConnectionDelegate {

    weak var theoplayer : THEOplayer?

    private var senderSource: SourceDescription {
        let typedSource = TypedSource(
            src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8",
            type: "application/x-mpegurl"
        )
        return SourceDescription(source: typedSource)
    }

    private var chromecastSource: SourceDescription {
        let typedSource = TypedSource(
            src: "https://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/manifest(format=mpd-time-csf)",
            type: "application/dash+xml",
            drm: WidevineDRMConfiguration(licenseAcquisitionURL: "https://amssamples.keydelivery.mediaservices.windows.net/Widevine/?KID=1ab45440-532c-4399-94dc-5c5ad9584bac")
        )
        return SourceDescription(source: typedSource)
    }

    init(theo : THEOplayer) {
        self.theoplayer = theo
        self.theoplayer?.cast?.chromecast?.setConnectionDelegate(self)
    }

    func onStart(sourceDescription: SourceDescription?) -> SourceDescription? {
        return chromecastSource
    }

    func onStop(sourceDescription: SourceDescription?) -> SourceDescription? {
        return senderSource
    }

    func onJoin(sourceDescription: SourceDescription?) -> SourceDescription? {
        return sourceDescription
    }

    func onLeave(sourceDescription: SourceDescription?) -> SourceDescription? {
        return sourceDescription
    }

}
```

The `onJoin` and `onLeave` implementations in the above snippet adhere to the default behavior.

Once you've implemented your `ChromecastConnectionDelegate`, you have to initialize an instance of this near the code of your where you're setting your `player.source` (e.g. <https://github.com/THEOplayer/samples-ios-sdk/blob/master/Google-Cast/Google_Cast/PlayerViewController.swift>). The snippet below demonstrates this concept:

```swift
...
class PlayerViewController: UIViewController {

    ...
    var chromecastController : ChromecastController!
    var senderSource: SourceDescription {
        let typedSource = TypedSource(
            src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8",
            type: "application/x-mpegurl"
        )
        return SourceDescription(source: typedSource)
    }
    ...

    override func viewDidLoad() {

        ...
        player.source = senderSource
        chromecastController = ChromecastController(theo: theoplayer)
        ...

    }

    ...

}
...
```

---

# Sending messages from/to Sender to/from Receiver on iOS

This article will explain how to send data to an active receiver and how to respond on the receiver.

## Send data to the receiver

The Google Cast SDK has a global object that everyone can access. This global object is also being used by THEOplayer. The general idea is to retrieve the current active cast session and send a message on a specific namespace.

On iOS, we need a component that implements the GCKGenericChannelDelegate protocol.

```swift
// Retrieve the current cast session
let castSession = GCKCastContext.sharedInstance().sessionManager.currenCastSession
// Create the defined namespace channel
let channel = GCKGenericChannel(namespace: "namespace")
// Set the delegate for the namespace channel (GCKGenericChannelDelegate)
channel.delegate = self
// Add the channel to the current cast session
castSession?.add(channel)
// Send message on channel (the error parameter is a pointer at which to store the error result, this may be nil)
channel.sendTextMessage("message", error: nil)
```

Reference:

* <https://developers.google.com/cast/docs/reference/ios/protocol_g_c_k_generic_channel_delegate-p>
* <https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_cast_session>
* <https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_generic_channel>
* <https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_cast_session.html#a3514b6933a579d4255702375f542c16a>
* <https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_cast_channel.html#ab7f595487ce145f38b2e82e55126789b>

## Receive data from the receiver

The general idea is to retrieve the current active cast session and add an event listener on the specific namespace.

The delegate of the channel will handle the receiving of messages.

```swift
extension ChromecastController : GCKGenericChannelDelegate {
    func cast(_ channel: GCKGenericChannel, didReceiveTextMessage message: String, withNamespace protocolNamespace: String) {
        print("Channel didReceiveTextMessage", message)
    }
}
```

Reference:

* <https://developers.google.com/cast/docs/reference/ios/protocol_g_c_k_generic_channel_delegate-p>

## Receive data on the receiver

*This example is for receiver version 2.*

The general idea is to retrieve the receiver manager and add a message listener for the specific namespace. **This needs to be done before a THEOplayer instance is created. THEOplayer will call the start method of the receiverManager on initialization.**

```js
// Retrieve the cast receiver manager
var castReceiverManager = cast.receiver.CastReceiverManager.getInstance();
// Retrieve the message bus from the cast receiver manager
var messageBus = castReceiverManager.getCastMessageBus('namespace');
// Add message listener to the message bus
messageBus.onMessage = function (event) {
  console.log(event);
};
```

Reference:

* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus>
* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus#onMessage>
* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus.Event>

## Send data from the receiver

*This example is for receiver version 2.*

There are multiple possibilities to send data from the receiver:

1. When a message is received on the receiver, you can answer the sender

2. Broadcast to all connected senders

```js
// 1.
messageBus.onMessage = function (event) {
  messageBus.send(event.senderId, 'message');
};
// 2.
messageBus.broadcast('message');
```

Reference:

* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus#broadcast>
* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus#send>

## Related articles

* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)

* [Chromecast SDK Setup](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md)

* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/how-to-configure-to-a-different-stream.md)

* [Connecting from custom Sender applications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/connecting-from-custom-sender-applications.md)

---

# Pass subtitle selection on to Chromecast on iOS

Currently, it is intended behavior that when you start casting the player to a Chromecast device the subtitle selection setting isn't carried over. A new player is generated with the `SourceConfiguration` of the sender, but not any adjustments.

You can work around the default behavior by adding event listeners to the player.

The code adds an event on textTracks `change`. Whenever the subtitles change, this event is called and stores the current active textTrack in `currentTextTrack` by iterating over the textTracks array and checking whether `.mode` is `showing`. Once a Chromecast session is created, the code will check if the ID of the textTracks in the new player corresponds with the ID of the stored currentTextTrack. If so, it will activate that textTrack.

## Solution

Here is how you pass the current active subtitle track to the Chromecast session:

```swift
var currentTextTrack: TextTrack?

self.theoplayer.textTracks.addEventListener(type: TextTrackListEventTypes.CHANGE) { (result) in
    for i in 0..<self.theoplayer.textTracks.count {
        if self.theoplayer.textTracks[i].mode == .showing {
            currentTextTrack = self.theoplayer.textTracks[i]
        }
    }
}

self.theoplayer.cast?.chromecast?.addEventListener(type: ChromecastEventTypes.STATE_CHANGE) { (result) in
    if result.state == .connected {
        self.theoplayer.addEventListener(type: PlayerEventTypes.PLAYING) { (result) in
            for i in 0..<self.theoplayer.textTracks.count {
                var tt = self.theoplayer.textTracks[i]
                if tt.id == currentTextTrack?.id {
                    tt.mode = .showing
                }
            }
        }
    }
}
```

---

# Enable Chromecast on the Sender on iOS

This article explains how to enable the Chromecast Sender capabilities. This article also documents how you can connect with a custom Chromecast Receiver application.

## Prerequisites

1. Your Sender device needs to be on the same Wi-Fi network as your Chromecast Receiver device.

## Add the Chromecast integration

Add the THEOplayer GoogleCast integration and the Google Cast SDK to your project, as described in the [installation section of the Chromecast introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/introduction.md#installation).

Next, set up the Cast Framework, as documented at <https://developers.google.com/cast/docs/ios_sender_setup>.

> **Warning**
>
> Changes to iOS 14 local network access permissions have impacted the Google Cast iOS SDK in a number of ways. Please see the [iOS 14 Changes](https://developers.google.com/cast/docs/ios_sender/permissions_and_discovery#ios_14) document to see how your app is affected.

> **Note**
>
> Because the THEOplayer iOS SDK is a Dynamic Framework, it should not include any dependency frameworks on which it relies (e.g. the Chromecast SDK). Instead, developers should include the dependencies on which THEOplayer relies. Therefore, using a Dynamic Framework ensures that there are no symbol clashes.

## Set `GCKCastContext`

To enable Chromecast on iOS the `GCKCastContext` shared instance should be set with a `GCKCastOptions`.

```swift
let options = GCKCastOptions(receiverApplicationID: "A1B2C3D4")
GCKCastContext.setSharedInstanceWith(options)
```

Or use the default THEOplayer cast options, which connect with the default THEOplayer Chromecast Receiver application:

```swift
THEOplayerGoogleCastIntegration.CastIntegrationHelper.setGCKCastContextSharedInstanceWithDefaultCastOptions()
```

That's it. When Chromecast-enabled devices are discovered, the player will display a Chromecast button. The player also works nicely together with the Chromecast controls that are part of the Chromecast Framework, (e.g. [GCKUICastButton](https://developers.google.com/cast/docs/ios_sender_integrate#add_a_cast_button) or [the mini controller](https://developers.google.com/cast/docs/ios_sender_integrate#add_mini_controllers)).

## Connect with custom Chromecast Receiver application

The THEOplayer SDK on your Sender application connects with THEO Chromecast Receiver application by default, but you can connect it to a custom Chromecast Receiver application instead. The default Dolby OptiView Chromecast Receiver application has OptiView Player functionality, but uses Shaka for media playback. If you want to use Google's legacy Media Player Library (MPL) for playback, you will need to use either a custom application or connect to Dolby OptiView's MPL Receiver application, using the `appID` value of `44BAE7D1`. Note that the MPL receiver does not support HLS-CMAF streams.

By default, THEOplayer's Receiver app will be set when you call `CastIntegrationHelper.setGCKCastContextSharedInstanceWithDefaultCastOptions()`.

You can connect with a custom Receiver app by configuring its ID through `GCKCastContext.setSharedInstanceWith(GCKCastOptions(receiverApplicationID: "A1B2C3D4"))`.

This approach is further demonstrated at <https://github.com/THEOplayer/samples-ios-sdk/tree/master/Native-GoogleCast>.

---

# AirPlay on iOS

[AirPlay](https://www.apple.com/airplay/) is a casting technology developed by Apple. AirPlay allows viewers to mirror their videos between AirPlay-enabled sender and receiver devices.

* iPhones, iPads and MacBooks are possible AirPlay-enabled sender devices.
* Apple TVs or AirPlay–enabled smart TVs are possible AirPlay-enabled receiver devices.

THEOplayer offers support for AirPlay on AirPlay-enabled devices through its Web SDK and iOS SDK.

## How to enable AirPlay

Ensure that an AirPlay-enabled receiver device is connected to your network, because you might not see an AirPlay icon otherwise. Additionally, note that AirPlay is only supported by Apple on a limited set of devices and browsers. For example, you cannot do AirPlay on a Chrome browser on a macOS device, even though it's an Apple device.

## API

As a developer, you might need to use the THEOplayer AirPlay API to build a custom AirPlay UI and UX, or to dispatch an event to an analytics service, or for workflow purposes.

For more information, see the API reference of [`AirPlay`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/AirPlay), a sub-protocol of [`Cast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/Cast).

Use the API as demonstrated below:

```swift
private func setupTheoplayer() {
    // player = THEOplayer(...)
    let airPlayState = theoplayer.cast?.airPlay?.state
    let isCasting = theoplayer.cast?.airPlay?.casting
    // ...
    // if (want to start AirPlay)
        theoplayer.cast?.airPlay?.start()
    // if (want to stop AirPlay)
        theoplayer.cast?.airPlay?.stop()
    // ...
    theoplayer.cast?.airPlay?.addEventListener(type: AirPlayEventTypes.STATE_CHANGE, listener: onStateChange)
}

private func onStateChange(event: AirPlayStateChangeEvent) {
    if (event.state == PlayerCastState.available) {
        // show AirPlay available icon
    } else if (event.state == PlayerCastState.connected) {
        // show AirPlay connected icon
    }
    print(event.state)
    print(self.player.cast?.airPlay?.casting)
}
```

## Remarks

* [Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/introduction.md) and AirPlay are comparable technologies.

---

# DRM on iOS

THEOplayer supports FairPlay, PlayReady and Widevine by default. To use these DRM systems, you will need to pass a DRM configuration along with the `source` object. We are partnered with many multi-DRM vendors to make it as easy as possible to get your DRM streams running.

## Integrations

These DRM vendors can be used through an integration. An integration is not part of the SDK: it is added on top of it as a [custom DRM integration](#custom-integration). Ready-made integrations for many vendors are available in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration). Vendors which don't require custom license or certificate requests can be used with a plain key system configuration instead.

* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/arris-titanium.md)
* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/axinom.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/buydrm-keyos.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/castlabs-drmtoday.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/doverunner.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/microsoft-azure.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/uplynk.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/verimatrix-multirights.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/vimond.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/vualto-vudrm.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/xstream.md)

## Other guides

* [Offline DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/offline-drm.md): how to implement playback of downloadable content-protected streams.
* [Multi-key HLS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/multikey-hls.md): how to serve one HLS stream to all key systems.

## Custom configuration

Developers can use the generic DRM-functionalities in case in-house DRM-solutions are used, or services from DRM-vendors for which no integration is available.

To configure DRM on the iOS SDK, developers can put a FairPlayDRMConfiguration inside a SourceDescription.

```swift
// let headers = [["<KEY>": "<VALUE>"]]
let drmConfiguration = FairPlayDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>"
        // , headers: headers, licenseType: <LICENSE_TYPE>
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Custom integration

Developers can make their own custom DRM integration for any DRM vendor. This can be done by making use of the [DRM integration API repository](https://github.com/THEOplayer/samples-drm-integration).

A complete guide on how to create a new integration, and some example integrations can be found in the provided repository.

---

# Arris Titanium on iOS

This article describes how to configure Arris Titanium DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the iOS and tvOS SDKs.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Arris Titanium integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/blob/master/ios/ContentProtectionIntegration/integration/ArrisTitaniumDrmIntegration.swift).

## Code example

Please refer to [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) (custom configuration).

## Resources

* <https://www.arris.com/products/titanium-cas/>
* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/microsoft-azure.md)

---

# Axinom on iOS

This article describes how to configure Axinom DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the tvOS SDK.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Code example

Please refer to [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) (custom configuration).

## Resources

* <https://www.axinom.com/products/drm>

## Related articles

* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/vualto-vudrm.md)

---

# BuyDRM KeyOS on iOS

This article describes how to configure BuyDRM KeyOS DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The BuyDRM KeyOS integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/blob/master/ios/ContentProtectionIntegration/integration/KeyOsDRMIntegration.swift). It passes the Authentication XML generated from the BuyDRM platform as custom data on the license request.

## Resources

* <https://test.buydrm.com/sites/default/files/pdf/webinar/050217_DeployingKeyOSMulti-DRM_withTHEOPLayer_Webinar.pdf>
* [KeyOS BuyDRM](https://www.buydrm.com/keyosplayer)
* [ContentProtectionIntegration API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/ContentProtectionIntegration)

---

# castLabs DRMToday on iOS

This article describes how to configure castLabs DRMToday with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Code example

Please refer to [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) (custom configuration).

## Resources

* <https://castlabs.com/drmtoday/>

---

# EZDRM on iOS

This article describes how to configure [EZDRM](https://www.ezdrm.com/) with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the tvOS SDK.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The EZDRM integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/blob/master/ios/ContentProtectionIntegration/integration/EzdrmDRMIntegration.swift).

## Resources

* [EZDRM documentation](https://www.ezdrm.com/documentation)
* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/vualto-vudrm.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/vimond.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/verimatrix-multirights.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/doverunner.md)

---

# Intertrust ExpressPlay on iOS

This article describes how to configure Intertrust ExpressPlay DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the iOS and tvOS SDKs.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Code example

**Not verified.**

```swift
// let headers = [["<KEY>": "<VALUE>"]]
let drmConfiguration = FairPlayDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>"
        // , headers: headers, licenseType: <LICENSE_TYPE>
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Resources

* [Verimatrix ExpressPlay DRM and THEOplayer](https://www.verimatrix.com/partners/theoplayer/)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/microsoft-azure.md)

---

# Irdeto on iOS

This article describes how to configure Irdeto DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the tvOS SDK.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Code example

Please refer to [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) (custom configuration).

## Resources

* <https://irdeto.com/video-entertainment/multi-drm-and-rights-management/>

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/microsoft-azure.md)

---

# Microsoft Azure on iOS

> **Warning**
>
> Azure Media Services has been retired since June 30th, 2024.

This article describes how to configure Microsoft Azure DRM with THEOplayer. Head to [Azure Media Services 3rd Party Player Samples - THEOplayer](https://github.com/Azure-Samples/media-services-3rdparty-player-samples/tree/master/docs/THEOplayer) for an implementation reference sample.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the tvOS SDK.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Microsoft Azure integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/blob/master/ios/ContentProtectionIntegration/integration/AzureDRMIntegration.swift).

## Resources

* <https://azure.microsoft.com/nl-nl/services/media-services/content-protection/>

## Related articles

* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/vualto-vudrm.md)
* [Azure Media Services - THEOplayer Implementation Sample](https://github.com/Azure-Samples/media-services-3rdparty-player-samples/tree/master/docs/THEOplayer)

---

# Verimatrix MultiRights on iOS

This article describes how to configure Verimatrix MultiRights with THEOplayer. [MultiRights](https://www.verimatrix.com/solutions/multirights-ott) is a multi-DRM solution by [Verimatrix](https://www.verimatrix.com/).

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the tvOS SDK.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Verimatrix Core integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/blob/master/ios/ContentProtectionIntegration/integration/VerimatrixCoreDRMIntegration.swift).

## Resources

* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/vualto-vudrm.md)

---

# Vimond on iOS

This article describes how to configure Vimond DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the tvOS SDK.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Code example

Please refer to [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) (custom configuration).

## Resources

* [Vimond](https://www.vimond.com/)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/microsoft-azure.md)

---

# Vualto VuDRM on iOS

This article describes how to configure Vualto VuDRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the tvOS SDK.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The Vualto VuDRM integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/blob/master/ios/ContentProtectionIntegration/integration/VuDRMIntegration.swift).

## Resources

* <https://www.vualto.com/products/vudrm-drm/>
* <https://github.com/Vualto/vuplay-theoplayer>

## Related articles

* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/vualto-vudrm.md)

---

# Uplynk on iOS

This article describes how to configure Uplynk DRM with THEOplayer.

**Important:** Uplynk customers should configure DRM through the [THEOplayer Uplynk connector for iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/preplay.md). (The Uplynk connector provides an out-of-the-box integration with Uplynk's Preplay, Ping and Asset Info services, exposes additional APIs, and enhances your UI and UX.)

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

The [Uplynk connector for iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/preplay.md) takes care of the DRM configuration as part of its Preplay logic: when you request a content-protected asset with the [`contentProtected`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/preplay.md) flag, the connector sets up the DRM configuration of the resulting source for you. If you don't use the connector, the Uplynk integration can be found [here](https://github.com/THEOplayer/samples-drm-integration/blob/master/ios/ContentProtectionIntegration/integration/UplynkDRMIntegration.swift).

## Resources

* [Content Protection (Uplynk)](https://docs.uplynk.com/docs/content-protection)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/castlabs-drmtoday.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/microsoft-azure.md)

---

# Xstream on iOS

This article describes how to configure Xstream DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

> **Note**
>
> Support for this DRM system has not been verified on the tvOS SDK.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Code example

Please refer to [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) (custom configuration).

## Related articles

* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/buydrm-keyos.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/vualto-vudrm.md)

---

# DoveRunner on iOS

This article describes how to configure [DoveRunner Multi-DRM](https://doverunner.com/docs/content-security/multi-drm/) with THEOplayer. This content is based on DoveRunner's documentation.

**Note**: The details in the guide apply for DoveRunner (formerly known as "PallyCon"). While most details, API hostnames and variables have been updated to reflect DoveRunner, certain configurations such as the `pallycon-customdata-v2` HTTP request header will still apply.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

## Integration

We provide open-source DRM integrations which are easy to maintain and allow for a modular approach. You can find them in the [DRM integration samples repository](https://github.com/THEOplayer/samples-drm-integration), alongside guides on how to integrate and use them.

There currently is no ready-made integration for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Code example

```swift
let drmConfiguration = FairPlayDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>",
    headers: [["<CUSTOM_HEADER_NAME>": "<CUSTOM_HEADER_VALUE>"]] // e.g. "pallycon-customdata-v2": "eyJkYXRhIjoibWJLV1NjSUNIU25WMjZQWFB4cGlDQUJVbnZsOGxCOWRNZDhHZ3dhbjZqRDFwNFZoQk51VlhQY2RMaG9nNTNYbngyTjFaalwvQ3BxZ3RUS2k5Rzd3MUZ3PT0iLCJzaXRlX2lkIjoiREVNTyIsImRybV90eXBlIjoiUGxheVJlYWR5In0="
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Resources

* <https://doverunner.com/docs/content-security/multi-drm/>
* <https://doverunner.com/docs/content-security/multi-drm/clients/fairplay-ios/>

## Related articles

* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/vualto-vudrm.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/vimond.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/verimatrix-multirights.md)

---

# Multi-key HLS on iOS

There are multiple DRM key systems on the market to choose from. The most popular ones are Google Widevine, Microsoft PlayReady and Apple FairPlay. Under the hood, all these systems encrypt the media samples using the AES-128 encryption algorithm. AES-128 is a standardized block-cipher that allows for multiple ways of choosing the blocks. Widevine and PlayReady both use `CTR` and FairPlay uses `CBC`. Therefore, it was possible to share segments between Widevine and PlayReady protected streams, but not with FairPlay protected stream. However, support has been added for Widevine and PlayReady with AES-128 in `CBC` mode. Hence, it is now possible to create HLS streams compatible with all these key systems. Where you previously had to encode the stream twice, this is no longer needed.

A multi-key HLS stream will play on all iOS and tvOS platforms, using the FairPlay key from the playlist.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/drm/introduction.md) for more general information.

## The HLS playlist

A multi-key HLS playlist could look like this:

```text
#EXTM3U
#EXT-X-TARGETDURATION:6
#EXT-X-VERSION:5
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-KEY:METHOD=SAMPLE-AES,KEYFORMAT="urn:uuid:edef8ba9-79d6-4ace-a3c8-27dcd51d21ed",KEYFORMATVERSIONS="1",URI="WIDEVINE_INIT_DATA_URL"
#EXT-X-KEY:METHOD=SAMPLE-AES,KEYFORMAT="com.microsoft.playready",KEYFORMATVERSIONS="1",URI="PLAYREADY_INIT_DATA_URL"
#EXT-X-KEY:METHOD=SAMPLE-AES,KEYFORMAT="com.apple.streamingkeydelivery",KEYFORMATVERSIONS="1",URI="FAIRPLAY_INIT_DATA_URL"
#EXT-X-MAP:URI="init.mp4"
#EXTINF:6,
1.mp4
#EXTINF:6,
2.mp4
#EXTINF:6,
3.mp4
#EXTINF:6,
4.mp4
#EXTINF:6,
5.mp4
#EXT-X-ENDLIST
```

There is an `#EXT-X-KEY` tag for all the key systems which all have method `SAMPLE-AES`. The `KEYFORMAT` specifies the key system:

* `urn:uuid:edef8ba9-79d6-4ace-a3c8-27dcd51d21ed` for Widevine
* `com.microsoft.playready` for PlayReady
* `com.apple.streamingkeydelivery` for FairPlay

The `URI` is either a data URI containing the initialization data, or a URI pointing to the initialization data. For more information, please check out the specifications for [Widevine](https://www.academia.edu/36030972/Widevine_DRM_for_HLS), [PlayReady](https://docs.microsoft.com/en-us/playready/packaging/mp4-based-formats-supported-by-playready-clients?tabs=case4) and [FairPlay](https://developer.apple.com/streaming/fps/).

## Configuring THEOplayer

The iOS and tvOS SDKs play the FairPlay key from the playlist, so only the FairPlay key system has to be configured:

```swift
let drmConfiguration = FairPlayDRMConfiguration(
    licenseAcquisitionURL: "https://fairplay-server.com/license",
    certificateURL: "https://fairplay-server.com/certificate"
)
let typedSource = TypedSource(src: "https://yourdomain.com/playlist.m3u8", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

The `#EXT-X-KEY` tags of the other key systems are ignored.

---

# Offline DRM on iOS

This how-to guide describes how to implement playback of downloadable content-protected streams using THEOplayer.

*Currently, Widevine and FairPlay (respectively for Android SDK and iOS SDK) are each supported together with the Uplynk-Verizon, Azure DRM and DRMToday integrations.*

## Prerequisites

In order to do offline DRM on iOS, your license key must be downloadable and persistable. The SDK will not be able to decrypt your content once the persisted key expires.

DRM on iOS SDK is configured through a **DRM integration** (a `ContentProtectionIntegration`) In order to use a DRM integration, you need to:

1. Implement a `ContentProtectionIntegration` and its `ContentProtectionIntegrationFactory`.
2. Register the factory once at app startup with `THEOplayer.registerContentProtectionIntegration(...)`.
3. Reference the integration from a `FairPlayDRMConfiguration` via its `customIntegrationId`.

For offline playback, you additionally need to request a persistent license (`licenseType: .persistent`) and make the DRM integration's license request offline aware.

In order to cache without a player instance, a valid THEOplayer license must be present in your app's `Info.plist`.

**Known limitations**

1. If your manifest is redirected while caching, you need to save the redirected manifest URL (the one that is actually being cached) and provide that URL to the player when you want to play back from the cache.
2. Only completely cached videos can be played offline. When the `CachingTask` status is `done`, the video is playable without any internet connection.
3. HLS manifests can have a tag `#EXT-X-PLAYLIST-TYPE:VOD` ([see here for reference](https://developer.apple.com/documentation/http-live-streaming/video-on-demand-playlist-construction)). If this tag is not present in the playlist of the cached quality, the player will make an extra request for the playlist, even if the video is completely cached. To avoid these extra requests, provide `#EXT-X-PLAYLIST-TYPE:VOD` in your playlists.

## Code example

You can find code examples for the different calls below. For all the possible API calls, please take a look at [the API reference for iOS SDK](https://optiview.dolby.com/docs/theoplayer/v11/api-reference/ios/index.html).

You can also find a full sample application with a FairPlay HLS asset and a working DRM integration [here](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Offline-Playback).

For ready-made integrations covering a range of DRM providers (along with a guide on how to integrate them), see the [sample DRM integrations repository](https://github.com/THEOplayer/samples-drm-integration/tree/master/ios).

### Register a DRM integration

Before you can play or cache a protected stream, register your FairPlay integration once, for example in your `AppDelegate`. The integration is where you communicate with your DRM provider: fetching the certificate, extracting the FairPlay content ID, and exchanging the SPC for a CKC. For offline support, request a persistent license; for some providers this also means adding an `offline=true` flag to the license request.

```swift
import THEOplayerSDK

// A barebones FairPlay integration.
// Replace the placeholder logic with your DRM provider's requirements.
class MyDRMIntegration: ContentProtectionIntegration {
    static let integrationID = "MyDRMIntegration"

    let configuration: DRMConfiguration

    init(configuration: DRMConfiguration) {
        self.configuration = configuration
    }

    // Extract the FairPlay content ID from the skd:// URL in the manifest.
    func onExtractFairplayContentId(skdUrl: String, callback: ExtractContentIdCallback) {
        var contentId = skdUrl
        if skdUrl.hasPrefix("skd://") {
            contentId = String(skdUrl.dropFirst("skd://".count))
        }
        callback.respond(contentID: contentId.data(using: .utf8))
    }

    // Fetch the FairPlay certificate. `request.url` is prefilled with `certificateURL`.
    func onCertificateRequest(request: CertificateRequest, callback: CertificateRequestCallback) {
        // Add provider-specific headers here if needed, e.g.:
        // request.headers = ["x-custom-header": "..."]
        callback.request(request: request)
    }

    func onCertificateResponse(response: CertificateResponse, callback: CertificateResponseCallback) {
        callback.respond(certificate: response.body)
    }

    // Send the SPC to the license server and return the CKC.
    // `request.url` is prefilled with `licenseAcquisitionURL`.
    func onLicenseRequest(request: LicenseRequest, callback: LicenseRequestCallback) {
        // For offline/persistent licenses, some providers require an explicit flag.
        if var components = URLComponents(string: request.url) {
            var queryItems = components.queryItems ?? []
            queryItems.append(URLQueryItem(name: "offline", value: "true"))
            components.queryItems = queryItems
            if let updated = components.string {
                request.url = updated
            }
        }
        // Add provider-specific headers/body encoding here if needed.
        callback.request(request: request)
    }

    func onLicenseResponse(response: LicenseResponse, callback: LicenseResponseCallback) {
        // If your provider wraps the CKC (e.g. <ckc>...</ckc> or base64), unwrap it here.
        callback.respond(license: response.body)
    }
}

class MyDRMIntegrationFactory: ContentProtectionIntegrationFactory {
    func build(configuration: DRMConfiguration) -> ContentProtectionIntegration {
        return MyDRMIntegration(configuration: configuration)
    }
}
```

Register the factory once at app startup:

```swift
func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    THEOplayer.registerContentProtectionIntegration(
        integrationId: MyDRMIntegration.integrationID,
        keySystem: .FAIRPLAY,
        integrationFactory: MyDRMIntegrationFactory()
    )
    return true
}
```

For a complete, production-ready integration (including certificate/license headers, custom-data handling, and CKC unwrapping), see the `CastLabsDRMIntegration` in the [Offline-Playback sample app](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Offline-Playback), or the provider-specific integrations and integration guide in the [samples-drm-integration repository](https://github.com/THEOplayer/samples-drm-integration/tree/master/ios).

### Download

The snippet below builds a `SourceDescription` that references the registered DRM integration and downloads a FairPlay HLS asset. Note the use of `customIntegrationId` to bind the source to your DRM integration, and `licenseType: .persistent` so the license can be stored for offline playback.

```swift
import THEOplayerSDK

// Example source referencing the registered DRM integration.
var sourceToBeCached: SourceDescription {
    let drmConfig = FairPlayDRMConfiguration(
        customIntegrationId: MyDRMIntegration.integrationID,
        licenseAcquisitionURL: "<LICENSE_ACQUISITION_URL>",
        certificateURL: "<CERTIFICATE_URL>",
        licenseType: .persistent,
        integrationParameters: [
            // Any provider-specific parameters your DRM integration reads, e.g.:
            // "userId": "...", "sessionId": "...", "merchant": "..."
        ]
    )
    let typedSource = TypedSource(
        src: "<HLS_STREAM_URL>",
        type: "application/x-mpegurl",
        drm: drmConfig
    )
    return SourceDescription(source: typedSource)
}

// Example cache call.
var cachingTask: CachingTask?

func cacheSource(source: SourceDescription, expirationDate: Date) {
    guard let task = THEOplayer.cache.createTask(
        source: source,
        parameters: CachingParameters(expirationDate: expirationDate)
    ) else { return }
    cachingTask = task

    _ = task.addEventListener(type: CachingTaskEventTypes.STATE_CHANGE) { _ in
        print("State change on caching task \(task.source.sources[0].src) - status: \(task.status)")
    }
    _ = task.addEventListener(type: CachingTaskEventTypes.PROGRESS) { _ in
        print("Progress on caching task \(task.source.sources[0].src) - cached:")
        for timeRange in task.cached {
            print(timeRange.start, timeRange.end)
        }
    }
    task.start()
}
```

### Playback

To play cached material, set the cached task's source on the player from the cache. A common pattern is to check whether the requested stream is already cached and, if so, play from the cache; otherwise play online.

```swift
func play(onlineSource: SourceDescription) {
    let onlineSrc = onlineSource.sources.first?.src

    if let cachedTask = THEOplayer.cache.tasks.first(where: { $0.source.sources.first?.src == onlineSrc }),
       cachedTask.status == .done {
        // Play from cache using the source stored with the caching task.
        theoplayer.source = cachedTask.source
    } else {
        // Play online.
        theoplayer.source = onlineSource
    }
    theoplayer.play()
}
```

### Pause and restart

A caching task can be paused and restarted through the task object itself.

```swift
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl")
let sourceDescription = SourceDescription(source: typedSource)

let cachingTask = THEOplayer.cache.createTask(source: sourceDescription, parameters: nil)

// Starting a caching task
cachingTask?.start()

// Pausing a caching task
cachingTask?.pause()

// Resuming a caching task
cachingTask?.start()
```

### Check size and progression

After creating a caching task, you can inspect the estimated total size on disk and the current progression.

```swift
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl")
let sourceDescription = SourceDescription(source: typedSource)

let cachingTask = THEOplayer.cache.createTask(source: sourceDescription, parameters: nil)

// Starting a caching task
cachingTask?.start()

if let cachingTask = cachingTask {
    // Listen for state change events
    _ = cachingTask.addEventListener(type: CachingTaskEventTypes.STATE_CHANGE, listener: { _ in
        print(cachingTask.status)
    })
    // Listen for progress events
    _ = cachingTask.addEventListener(type: CachingTaskEventTypes.PROGRESS, listener: { _ in
        // percentage cached (0.0 - 1.0)
        print(cachingTask.percentageCached)
        // total bytes cached
        print(cachingTask.bytesCached)
        // the amount of seconds cached
        print(cachingTask.secondsCached)
        // the range that is cached
        for timeRange in cachingTask.cached {
            print(timeRange.start, timeRange.end)
        }
    })
}
```

To inspect caching errors, cast the `STATE_CHANGE` event to `CachingTaskErrorStateChangeEvent`:

```swift
_ = cachingTask?.addEventListener(type: CachingTaskEventTypes.STATE_CHANGE, listener: { event in
    if cachingTask?.status == .error,
       let errorEvent = event as? CachingTaskErrorStateChangeEvent,
       let error = errorEvent.error {
        print("Caching task error - code: \(error.code), message: \(error.message)")
    }
})
```

### Delete

The snippet below deletes all cached assets.

```swift
func cleanCache() {
    for cachingTask in THEOplayer.cache.tasks {
        print("Will remove caching task \(cachingTask.source.sources[0].src)")
        cachingTask.remove()
    }
}
```

### Renew a DRM license

The snippet below renews a stored (persistent) DRM license. You can renew with the original configuration, or provide an updated `FairPlayDRMConfiguration` that references the same DRM integration.

```swift
func renewLicense() {
    let newDrmConfig = FairPlayDRMConfiguration(
        customIntegrationId: MyDRMIntegration.integrationID,
        licenseAcquisitionURL: "<LICENSE_ACQUISITION_URL>",
        certificateURL: "<CERTIFICATE_URL>",
        licenseType: .persistent,
        integrationParameters: [
            // updated provider-specific parameters (e.g. a fresh auth token)
        ]
    )

    // Renew with the new configuration...
    cachingTask?.license.renew(newDrmConfig)
    // ...or renew with the configuration originally stored on the task:
    // cachingTask?.license.renew()
}
```

### Handle redirected manifest

If your master manifest URL redirects, cache the redirected URL and play back from that same URL.

```swift
// Cache source
let url = URL(string: "<MASTER_MANIFEST_URL_THAT_GETS_REDIRECTED>")!

let task = URLSession.shared.dataTask(with: url) { (_, response, _) in
    guard let redirectedURL = response?.url else { return }
    Streams.SAVED_REDIRECTED_URL = redirectedURL

    // Rebuild the source against the redirected URL, still referencing the DRM integration.
    let drmConfig = FairPlayDRMConfiguration(
        customIntegrationId: MyDRMIntegration.integrationID,
        licenseAcquisitionURL: "<LICENSE_ACQUISITION_URL>",
        certificateURL: "<CERTIFICATE_URL>",
        licenseType: .persistent
    )
    let typedSource = TypedSource(src: redirectedURL.absoluteString, type: "application/x-mpegurl", drm: drmConfig)
    let cachingTaskSource = SourceDescription(source: typedSource)

    guard let cachingTask = THEOplayer.cache.createTask(
        source: cachingTaskSource,
        parameters: CachingParameters(expirationDate: .distantFuture, bandwidth: cachingTaskBandwidth)
    ) else { return }
    self.cachingTask = cachingTask

    _ = cachingTask.addEventListener(type: CachingTaskEventTypes.STATE_CHANGE) { _ in
        print("State change on caching task \(cachingTask.source.sources[0].src) - status: \(cachingTask.status)")
    }
    _ = cachingTask.addEventListener(type: CachingTaskEventTypes.PROGRESS) { _ in
        for timeRange in cachingTask.cached {
            print(timeRange.start, timeRange.end)
        }
    }
    cachingTask.start()
}
task.resume()

// Playback of cached source (use the redirected URL)
let drmConfig = FairPlayDRMConfiguration(
    customIntegrationId: MyDRMIntegration.integrationID,
    licenseAcquisitionURL: "<LICENSE_ACQUISITION_URL>",
    certificateURL: "<CERTIFICATE_URL>",
    licenseType: .persistent
)
let typedSource = TypedSource(src: Streams.SAVED_REDIRECTED_URL!.absoluteString, type: "application/x-mpegurl", drm: drmConfig)
theoplayer.source = SourceDescription(source: typedSource)
theoplayer.play()
```

---

# Integrations on iOS

In this section, you can figure out how THEOplayer integrates with various partners.

## Related articles

* [Deliver Low-Latency HLS live streams](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/integrations/wowza-streaming-engine/low-latency-hls.md)

---

# Wowza Streaming Engine on iOS

[Wowza Streaming Engine™](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/) is a media server for live and on-demand streaming. THEOplayer can play back its streams, and integrates with a number of its features.

---

# Deliver Low-Latency HLS live streams with Wowza Streaming Engine on iOS

Wowza Streaming Engine™ media server software can deliver Low-Latency HLS (LL-HLS) live streams, which THEOplayer can play back on every platform.

Low-Latency HLS streams conform to [Apple's protocol extension to the HLS specification](https://developer.apple.com/documentation/http-live-streaming/enabling-low-latency-http-live-streaming-hls).

## Prerequisites

There are three prerequisites in order to continue with this guide:

1. In order to generate LL-HLS streams, you must first get a SSL certificate to secure your port and configure the port for HTTPS playback. LL-HLS playback does not work without an SSL secured port. For information on how to do this, refer to [How to Get an SSL Certificate from Wowza's Streamlock Service](https://www.wowza.com/docs/how-to-get-ssl-certificates-from-the-streamlock-service).

2. This guide expects that you have a THEOplayer license. If you are not using THEOplayer yet, you can start your free trial [here](https://portal.theoplayer.com/).

3. This guide expects that you are a Wowza Streaming Engine client and that you are integrated with their streaming infrastructure. Information on Wowza Streaming Engine can be found [here](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/). Be sure to have Wowza Streaming Engine media server software version 4.7.8 or higher.

**Please Note:** Wowza occasionally update their documentation, which can be accessed [here](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine).

## Configure a live application to deliver LL-HLS streams

You can use the default **live** application that installs with Wowza Streaming Engine or create and use a new **Live** or **Live HTTP Origin** application. Use the **Live** application type for sending streams from Wowza Streaming Engine to clients or Wowza Streaming Engine edges. Use the **Live HTTP Origin** application type to connect to a CDN edge, such as the Fastly CDN, that can pull streams from the Wowza Streaming Engine origin application.

The following steps use the default **live** application to enable LL-HLS live streaming by editing the **Application.xml** and **VHost.xml** configuration files.

**Please Note:** If you're trying to use the CMAF packetizer to deliver LL-HLS and HLS or MPEG-DASH streams, you must use two separate live applications: one configured specifically for LL-HLS and another for CMAF-packetized HLS and MPEG-DASH.

### Enable LL-HLS in Wowza Streaming Engine XML

The following steps enable transmuxing for CMAF packetization for LL-HLS delivery.

1. Navigate to **\[install-dir]/conf/live** or **\[install-dir]/conf/\[custom live application]** and open the **Application.xml** file in a text editor.
2. Add **cmafstreamingpacketizer** to the **LiveStreamPacketizers** property. You can add it to the prepopulated comma-separated list, or it can be the only packetizer specified. The XML looks like this:

```xml
<Streams>
    ...
    <LiveStreamPacketizers>cmafstreamingpacketizer</LiveStreamPacketizers>
    ...
</Streams>
```

**Please Note:** If you enable **cupertinostreamingpacketizer** and **cmafstreamingpacketizer**, Wowza Streaming Engine generates both MPEG-TS segments (using **cupertinostreamingpacketizer**) and fMP4 segments (using **cmafstreamingpacketizer**).

3. Add the **cmafLLEnableLowLatency** property to the **LiveStreamPacketizer** container element and set it to true.

```xml
<LiveStreamPacketizer>
    <Properties>
        <Property>
            <Name>cmafLLEnableLowLatency</Name>
            <Value>true</Value>
            <Type>Boolean</Type>
        </Property>
    </Properties>
</LiveStreamPacketizer>
```

4. For the **HTTPStreamers** property, make sure HLS (**cupertinostreaming**) is specified. The XML looks like this:

```xml
<HTTPStreamers>cupertinostreaming</HTTPStreamers>
```

5. Go to **\[install-dir]/conf/** and open the **VHost.xml** file in a text editor.

6. Add the `AllowHttp2` property to the `<SSLConfig>` container element in the `<HostPort>` you configured for SSL/TLS and set it to true.

```xml
<SSLConfig>
    ...
    <AllowHttp2>true</AllowHttp2>
    ...
</SSLConfig>
```

7. Save your changes.

Your live application is now configured to deliver LL-HLS streams.

### Configure optional low latency partial segment properties and media playlist property

Configuring the following properties is optional as Wowza Streaming Engine will use the property's default value for any of the properties that you do not configure. You can configure the optional LL-HLS properties by editing the **Application.xml** file for your LL-HLS live stream application. For information about configuring custom (optional) properties, see [Add custom properties](https://www.wowza.com/docs/add-a-custom-property#add-custom-properties).

#### Low latency CMAF property reference

You can configure any of these optional **LiveStreamPacketizer** properties for the LL-HLS segments and video and audio partial segments (chunks) in the **Application/LiveStreamPacketizer/Properties** container element.

**Please Note:** If partial segments are too small, servers can become overloaded with frequent media playlist requests and cause playback to be less reliable.

| Name                                                                                                                                                          | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **cmafLLChunkingScheme**                                                                                                                                      | String  | Specifies the chunking scheme for low latency CMAF-packetized streams. Valid values are **byFrame** or **byDuration**. The default is **byDuration**. If the value is **byDuration**, packetization is configured using the **cmafLLChunkDurationTargetAudio** and **cmafLLChunkDurationTargetVideo** properties. If the value is **byFrame**, packetization is configured using the **cmafLLChunkFrameCountTargetAudio** and **cmafLLChunkFrameCountTargetVideo** properties. |
| **cmafLLChunkDurationTargetAudio**                                                                                                                            | Integer | Specifies, in milliseconds, the target duration of each low latency CMAF **audio** chunk. The default is **1000** and is recommended. The duration cannot exceed the [cmafSegmentDurationTarget](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine#cmafsegmentdurationtarget) value. This property is only available if **cmafLLChunkingScheme** is **byDuration**.                                                           |
| **cmafLLChunkDurationTargetVideo**                                                                                                                            | Integer | Specifies, in milliseconds, the target duration of each low latency CMAF **video** chunk. The default is **1000** and is recommended. The duration cannot exceed the [cmafSegmentDurationTarget](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine#cmafsegmentdurationtarget) value. This property is only available if **cmafLLChunkingScheme** is **byDuration**.                                                           |
| **cmafLLChunkFrameCountTargetAudio**                                                                                                                          | Integer | Specifies the target number of audio frames to include in each low latency CMAF audio chunk. The default is **47** and is recommended. This property is only enabled if **cmafLLChunkingScheme** is **byFrame**.                                                                                                                                                                                                                                                               |
| **cmafLLChunkFrameCountTargetAudio**                                                                                                                          | Integer | Specifies the target number of audio frames to include in each low latency CMAF audio chunk. The default is **30** and is recommended. This property is only enabled if **cmafLLChunkingScheme** is **byFrame**.                                                                                                                                                                                                                                                               |
| **[cmafSegmentDurationTarget](https://www.wowza.com/docs/configure-cmaf-packetization-in-wowza-streaming-engine#cmaf-live-packetization-property-reference)** | Integer | Specifies, in milliseconds, the duration of the fMP4 segments in the stream. The default is **6000** (6 seconds) and is recommended. This property is configurable from the **CMAFStreamingPacketizer** properties section in Wowza Streaming Engine Manager.                                                                                                                                                                                                                  |

#### Advanced LL-HLS property reference

For advanced tuning, you can configure the following optional **HTTPStreamer** property in the **Application/HTTPStreamer/Properties** container element.

| Name                                    | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cupertinoPartHoldBack (4.8.0 and later) | Double | Specifies, in floating-point seconds, the server-recommended minimum distance from the live edge at which clients should begin to play or seek in a LL-HLS stream (the PART-HOLD-BACK attribute in media playlists). If you do not configure this property, Wowza Streaming Engine uses the default value, which is recommended. The default value is calculated as three times the maximum value of PART-TARGET out of all of a stream's variant media playlists. **Please Note:** PART-TARGET is an attribute of the EXT-X-PART-INF tag in media playlists and is based on the target values set with the **cmafLLChunkDurationTargetVideo** and **cmafLLChunkDurationTargetAudio** properties or the **cmafLLChunkFrameCountTargetVideo** and **cmafLLChunkFrameCountTargetAudio** properties. Wowza Streaming Engine will adjust the PART-HOLD-BACK value to be equal to the maximum value of PART-TARGET (across all variant media playlists) if you set this property to less than a partial segment duration. |

#### Transcoding considerations for LL-HLS

To bypass encoding streams with Transcoder, source streams should meet the following encoding recommendations. Otherwise, transcoding is recommended. Although a small amount of latency is introduced with transcoding, if your source stream does not meet the encoding recommendations, transcoding will ultimately improve reliability of LL-HLS streaming.

##### Encoding recommendations

* CMAF-supported codecs (required)

| Video          | Audio                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - H.264, H.265 | - AAC, AAC-LC, HE-AAC (AAC+ or aacPlus),<br />- HE-AACv2 (enhanced AAC+, aacPlus v2) - Dolby Digital 5.1 Surround Sound (AC-3) and Dolby Digital Plus (Enhanced AC-3 or E-AC-3) |

* GOP size: 1 or 2 seconds
* Closed GOPs
* H.264 and H.265 byte streams contain metadata about the GOP structure
* Constant frame rate video

A stream configured for transcoding and LL-HLS delivery cannot use **Passthrough** for the **Video Codec** of a stream rendition but not other renditions of the same stream. If you use **Passthrough** to pass a video source through to output without making any changes for any **Video Codec** in a stream's renditions, all of the video codecs must be set to **Passthrough**.

Stream name groups (NGRP) are not supported with LL-HLS. To group multiple stream renditions for LL-HLS, you need to create a SMIL file in accordance with CMAF HLS. See [Set up adaptive bitrate CMAF streaming](https://www.wowza.com/docs/create-adaptive-bitrate-cmaf-streams-using-wowza-streaming-engine#set-up-adaptive-bitrate-cmaf-streaming) for how to do this.

#### Scale LL-HLS with a CDN

Optionally, with your own CDN account, you can scale LL-HLS delivery by connecting a Wowza Streaming Engine **Live HTTP Origin** application to a CDN edge that can pull streams from the Wowza Streaming Engine origin application, such as the Fastly CDN.

To connect the **Live HTTP Origin** application to your CDN, provide the IP address or hostname of the Wowza Streaming Engine origin server in your CDN configuration. Also in your CDN configuration, enable connecting to the origin server over SSL/TLS using the port you configured for SSL/TLS in the Wowza Streaming Engine origin (default port 443).

#### Test stream playback

After your live application is configured to deliver an LL-HLS stream, complete the stream setup by connecting a source encoder or IP camera to Wowza Streaming Engine and publishing the live source stream to the server. When the camera or encoder is connected and the live stream is active, test LL-HLS playback using a supported test player.

To test LL-HLS live streams when only **cmafstreamingpacketizer** is enabled, specify the stream playback URL using one of the following formats:

**Single bitrate** https\://\[address]/\[application]/\[application-instance]/\[stream-name]/playlist.m3u8

If **cmafstreamingpacketizer** and **cupertinostreamingpacketizer** are enabled, specify the stream playback URL using one of the following formats:

**Single bitrate** https\://\[address]/\[application]/\[application-instance]/\[stream-name]/playlist\_sfm4s.m3u8

Where:

**\[address]** is the IP address or domain and port (default port 443) **\[application]** is the application name **\[application-instance]** is the name of the application instance (if omitted, defaults to ***definst***) **\[stream-name]** is the stream name So, for example, if only **cmafstreamingpacketizer** is enabled, the playlist URL for an adaptive bitrate LL-HLS stream that uses the address **example.com**, the default **live** application, and the default stream name **myStream** is:

<https://example.com/live/smil:myStream.smil/playlist.m3u8>

If **cmafstreamingpacketizer** and **cupertinostreamingpacketizer** are both enabled, the adaptive bitrate LL-HLS playlist URL for the same example is:

<https://example.com/live/smil:myStream.smil/playlist_sfm4s.m3u8>

and the playback URL for the Cupertino HLS stream is either:

<https://example.com/live/smil:myStream.smil/playlist.m3u8>

or

<https://example.com/live/smil:myStream.smil/playlist_sfts.m3u8>

where **\_sfts** indicates that the media playlist contains .ts segments.

## Configure THEOplayer to play your LL-HLS stream

1. Set up a basic app with THEOplayer. See "[Getting started on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/ios/getting-started.md)".
2. Specify the LL-HLS stream generated above as the `src` of your typed source.

On iOS and tvOS, HLS streams are played back by the operating system, which handles Low-Latency HLS without any additional configuration.

```swift
let source = SourceDescription(
    source: TypedSource(
        src: "https://5d6e17f1ca731.streamlock.net/LowLatencyBBB/myStream/playlist.m3u8",
        type: "application/x-mpegurl"
    )
)

theoplayer.source = source
```

## Resources

* [Getting Started with Wowza Streaming Engine](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/)
* [Deliver Apple Low-Latency HLS live streams using Wowza Streaming Engine](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine)

---

# Media tracks on iOS

The articles in this section describe how to implement common use-cases related to audio and video tracks, such as switching between audio languages, or selecting a specific video quality.

The MediaTrack API, and its AudioTrack and VideoTrack sub-APIs, allow you to programmatically enable and disable audio tracks, inspect the available video qualities, override the ABR algorithm and more.

## Related articles

* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/enable-disable-audio-tracks.md)
* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-audio-tracks.md)
* [How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-audio-track-changes.md)
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/select-video-track-quality.md)
* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-video-track-qualities.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-video-track-quality-changes.md)
* [How to reduce data usage on mobile devices](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/reduce-data-usage.md)

---

# How to programmatically enable or disable audio tracks on iOS

This article describes how you can use the AudioTrack API, a sub-API of the MediaTrack API, to enable or disable audio tracks. Implementing this functionality is a common use-case for developers who want to build their own UI to toggle audio languages on and off.

Once you have programmatically selected a track, you can set its `enabled` property (or method) to `true` or `false`. Because only one audio track can play at a time, enabling an audio track automatically disables all other audio tracks. Note that this does not apply to text tracks: multiple text tracks can be active at the same time.

## Usage

The iOS SDK exposes the audio tracks through [`player.audioTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C11audioTracksAA14AudioTrackList_pvp), which contains [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/MediaTrack) objects with an `enabled` property.

```swift
// enable a specific audio track
self.player.audioTracks[indexOfRequestedAudioTrack].enabled = true
```

## Related articles

* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-audio-tracks.md)
* [How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-audio-track-changes.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/build-chromeless-ui.md)

---

# How to programmatically detect audio tracks on iOS

This article describes how you can use the AudioTrack API, a sub-API of the MediaTrack API, to detect audio tracks. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available audio languages.

## Usage

Listen for the [`ADD_TRACK`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/AudioTrackListEventTypes) event on [`player.audioTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C11audioTracksAA14AudioTrackList_pvp) to detect every [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/MediaTrack) that is added to the player.

```swift
self.player.audioTracks.addEventListener(type: AudioTrackListEventTypes.ADD_TRACK, listener: { addTrackEvent in
    let audioTrack = addTrackEvent.track
})
```

## Related articles

* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/enable-disable-audio-tracks.md)
* [How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-audio-track-changes.md)
* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-video-track-qualities.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/build-chromeless-ui.md)

---

# How to programmatically select a video track quality on iOS

This article describes how you can use the VideoTrack API, a sub-API of the MediaTrack API, to select a video track quality. If you select a specific quality, you overrule the ABR algorithm.

Implementing this functionality is a common use-case for developers who want to build their own UI to toggle a specific video quality.

## Usage for HESP streams

For HESP streams, set the `targetQualities` of a [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/MediaTrack).

```swift
let videoTrack = player.videoTracks[0]
videoTrack.targetQualities = [videoTrack.qualities[indexOfRequestedVideoTrackQuality]]
// or
videoTrack.targetQualities = [videoTrack.qualities[0], videoTrack.qualities[1]]
```

## Usage for HLS streams

For HLS streams, the iOS SDK leverages the [ABR API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/ABRConfiguration). The underlying AVFoundation stack, which THEOplayer has to use, brings along the technical limitation that you cannot select a specific video quality. Instead, you can set a maximum resolution or bitrate.

```swift
// set preferred peak bitrate
self.theoplayer.abr.preferredPeakBitRate = 200000

// self.theoplayer.abr.preferredPeakBitRate = nil // removes any bitrate limitation

// preferredMaximumResolution supported starting from iOS 11 and above
// self.theoplayer.abr.preferredMaximumResolution = CGSize(width: 1280, height: 720)
// self.theoplayer.abr.preferredMaximumResolution = CGSize.zero // removes any resolution limitation
```

## Related articles

* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-video-track-qualities.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-video-track-quality-changes.md)
* [How to reduce data usage on mobile devices](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/reduce-data-usage.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/build-chromeless-ui.md)

---

# How to programmatically detect video track qualities on iOS

This article describes how you can use the VideoTrack API, a sub-API of the MediaTrack API, to detect video track qualities. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available video track qualities.

## Usage

The qualities of a video track are available as soon as the track is added to [`player.videoTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C11videoTracksAA14VideoTrackList_pvp).

```swift
player.videoTracks.addEventListener(type: VideoTrackListEventTypes.ADD_TRACK, listener: { addTrackEvent in
    guard let videoTrack = addTrackEvent.track as? VideoTrack else { return }
    for i in 0..<videoTrack.qualities.count {
        let quality = videoTrack.qualities[i]
        var msg = "Quality added: bandwidth = \(quality.bandwidth)"
        if let videoQuality = quality as? VideoQuality {
            msg.append(", width = \(videoQuality.width), height = \(videoQuality.height)")
        }
        print(msg)
    }
})
```

## Related articles

* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/select-video-track-quality.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-video-track-quality-changes.md)
* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-audio-tracks.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/build-chromeless-ui.md)

---

# How to reduce data usage on mobile devices on iOS

Customers who leverage THEOplayer's preloading capabilities (`preload = "auto"`), or who provide very high qualities, sometimes receive complaints about data usage on mobile devices. You can combat this by leveraging the ABR API and the MediaTrack API, as described in the steps below.

## 1. Lower the target buffer

The target buffer is the amount of seconds which the player buffers ahead of the current playback position. The standard buffer time is 20 seconds. Setting a lower number (e.g. 6 seconds) allows you to download less information in front of the playhead position. This value is also used when preloading content.

The iOS SDK does not allow you to change the target buffer. Its [ABR API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/ABRConfiguration) only allows you to change the ABR strategy, and to limit the bitrate and resolution of the renditions considered for ABR.

## 2. Manage preloading

Preloading is a powerful feature when trying to reduce the join time. It is more effective in some situations than others, and managing it correctly helps you reduce the data usage:

* preloading a live stream may entail appending information in the buffer that will never be played, if the user waits long enough before clicking "Play";
* in those situations when a user is not yet likely to be playing a stream (e.g. the player is not yet in view), preloading may also mean downloading information that the user will not consume.

So, based on your use case, you might decide whether to enable preloading.

```swift
theoplayer.setPreload(.auto)
```

## 3. Choose the renditions considered for ABR

On mobile devices, THEOplayer by default takes into account the player size for ABR: this lets it avoid selecting renditions too big to be appreciated on the current device, thus avoiding wasting data.

Leveraging the target quality of the MediaTrack API, you can refine the rendition choice further and indicate yourself to the player which qualities should be considered for ABR. For example, you could configure that THEOplayer should only do ABR on the lowest 3 qualities of a stream containing 5.

See [how to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/select-video-track-quality.md) to learn how to limit the qualities considered for ABR.

## Conclusion

There are several actions that can be taken to drastically reduce data usage on mobile devices, both in the player and at other levels. As far as the player is concerned, by leveraging its API as described you can filter different use cases and handle several aspects related to media download for each use case. This enables you to manage the precise behavior in each case and optimize data usage.

## Related articles

* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/select-video-track-quality.md)
* [Preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/preloading.md)

---

# How to programmatically detect video track quality changes on iOS

This article describes how you can use the VideoTrack API, a sub-API of the MediaTrack API, to detect video track quality changes. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the video track quality that is currently active.

## Usage

Listen for the [`ACTIVE_QUALITY_CHANGED`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/MediaTrackEventTypes) event of a [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/MediaTrack).

```swift
player.videoTracks.addEventListener(type: VideoTrackListEventTypes.ADD_TRACK, listener: { addTrackEvent in
    guard let videoTrack = addTrackEvent.track as? VideoTrack else { return }
    videoTrack.addEventListener(type: MediaTrackEventTypes.ACTIVE_QUALITY_CHANGED, listener: { qualityChangeEvent in
        let quality = qualityChangeEvent.quality
        var msg = "Quality changed: bandwidth = \(quality.bandwidth)"
        if let videoQuality = quality as? VideoQuality {
            msg.append(", width = \(videoQuality.width), height = \(videoQuality.height)")
        }
        print(msg)
    })
})
```

## Related articles

* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-video-track-qualities.md)
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/select-video-track-quality.md)
* [How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-audio-track-changes.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/build-chromeless-ui.md)

---

# How to programmatically detect audio track changes on iOS

This article describes how you can use the AudioTrack API to detect audio track changes. An audio track "change" is triggered by enabling (or disabling) an audio track.

Implementing this functionality is a common use-case for developers who want to build their own UI, and annotate the audio track that is currently active.

## Usage

The implementation of the iOS SDK applies to all iOS-based platforms, including iPadOS and tvOS.

The iOS SDK exposes the AudioTrack API through [`player.audioTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C11audioTracksAA14AudioTrackList_pvp). This `audioTracks` property is a [`MediaTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/MediaTrackList). This `MediaTrackList` dispatches the events from the [`AudioTrackListEventTypes`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/AudioTrackListEventTypes). The `AudioTrackListEventTypes` contains the [`CHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/AudioTrackListEventTypes#/s:13THEOplayerSDK24AudioTrackListEventTypesV6CHANGEAA0F4TypeCyAA0d6ChangeF0CGvpZ) event, as well as the `ADD_TRACK` and `REMOVE_TRACK` event.

The code below allows you to detect audio track changes.

```swift
player?.audioTracks.addEventListener(type: AudioTrackListEventTypes.CHANGE, listener: { event in
    let track: AudioTrack = event.track as! AudioTrack
    print(track.label, track.language, track.enabled)
})
```

The properties of a media `track` (e.g. `enabled`, `language`) are described in the [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/MediaTrack) and [`Track`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/Track) API references.

## Related articles

Are you reading this article because you are interested in audio tracks? Continue reading below.

* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-audio-tracks.md)
* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/enable-disable-audio-tracks.md)

Are you reading this article because you are implementing a custom UI? Then you will find the following articles interesting:

* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/build-chromeless-ui.md)
* [How to detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-video-track-quality-changes.md)
* [How to detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-text-track-changes.md)

---

# Miscellaneous on iOS

In this section, you can find guides on how to use many of the player features that are not addressed in the other sections of this documentation.

## [📄️Picture-in-Picture](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/picture-in-picture.md)

[iOS supports both in-app and out-of-app Picture-in-Picture. tvOS only supports in-app Picture-in-Picture.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/picture-in-picture.md)

## [📄️HLS date ranges](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/hls-date-range.md)

[Enabling date ranges](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/hls-date-range.md)

## [📄️Preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/preloading.md)

[Usage](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/preloading.md)

## [📄️Save caching task progress](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/save-caching-task-progress.md)

[The THEOplayer iOS SDK provides the capability to pause an ongoing caching task.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/save-caching-task-progress.md)

## [⚠️Error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/error/introduction.md)

[3 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/error/introduction.md)

---

# Picture-in-Picture on iOS

The Picture-in-Picture (PiP) feature allows you to create a floating player. This is commonly used to let the video remain playing on screen even if:

* The user scrolls to another section of the page (causing the original player to no longer be visible).
* The user sends the application to the background.
* The user opens a new page within the same application.

THEOplayer distinguishes two flavors of Picture-in-Picture:

* With **in-app** Picture-in-Picture, the visibility of the PiP window is contained to the inside of the app. In other words, it goes to background and foreground together with the application.
* With **out-of-app** Picture-in-Picture, the visibility of the PiP window is not contained to the inside of the app. It can remain visible while the user navigates to other views, pages or apps.

Picture-in-Picture is a presentation mode of the player. As such, you can listen for a `presentationmodechange` event, or read the player's presentation mode, to find out what the presentation mode is at a given moment or to detect a change.

iOS supports both in-app and out-of-app Picture-in-Picture. tvOS only supports in-app Picture-in-Picture.

## Enabling Picture-in-Picture

Instantiate the player with a `PiPConfiguration`, passed in the `THEOplayerConfiguration`. This configuration lets you configure whether the player should retain its presentation mode upon source change, and whether to make use of out-of-app PiP (`nativePictureInPicture`). Note that the minimum required iOS version for out-of-app PiP is 14.0.

```swift
/* Configure whether presentation mode should be retained on source changes and whether to use native PiP */
let pipConfig = PiPConfiguration(retainPresentationModeOnSourceChange: true, nativePictureInPicture: true)
let playerConfig = THEOplayerConfiguration(pip: pipConfig)
let theoplayer = THEOplayer(configuration: playerConfig)
```

Once Picture-in-Picture is enabled, the player's `pip` property can be accessed.

While using **in-app** PiP, you can use the `configure(movable:defaultCorner:)` method of the player's `pip` property to configure whether the PiP view is movable (defaults to `true`), and in which corner the PiP view is shown by default (defaults to the bottom right corner).

```swift
theoplayer.pip!.configure(movable: false, defaultCorner: .bottomLeft)
```

Notes:

* `configure` is only available when using in-app PiP.
* tvOS only supports in-app PiP, which is **enabled by default** if the OS version supports it (minimum tvOS 14.0).
* iPadOS 14.0 (and above) also supports in-app PiP.

## Observing in-app Picture-in-Picture

Using the notification center, you can listen to the `PictureInPictureMoved` notification. This notification is pushed every time the Picture-in-Picture view moves to a different corner.

In the callback, you can retrieve the previous and the new corner in the `userInfo` dictionary, respectively with the `PictureInPictureOldCornerUserInfoKey` and the `PictureInPictureNewCornerUserInfoKey` keys.

```swift
NotificationCenter.default.addObserver(self, selector: #selector(onPiPMoved), name: Notification.Name.PictureInPictureMoved, object: nil)

@objc func onPiPMoved(notif: Notification) {
    let userInfo = notif.userInfo as! [String: Any]
    let oldCorner: PictureInPictureCorner = userInfo[PictureInPictureOldCornerUserInfoKey]! as! PictureInPictureCorner
    let newCorner: PictureInPictureCorner = userInfo[PictureInPictureNewCornerUserInfoKey]! as! PictureInPictureCorner
    print("PiP has moved from \(oldCorner) to \(newCorner)")
}
```

## Observing out-of-app Picture-in-Picture

By implementing your own [AVPictureInPictureControllerDelegate](https://developer.apple.com/documentation/avkit/avpictureinpicturecontrollerdelegate), you are able to listen to a number of events. These contain, but are not limited to, when the player will enter or exit PiP, and when it has entered or exited PiP. To achieve this, set your implementation of the delegate as the one of the [PictureInPicture](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/PictureInPicture) controller.

```swift
class CustomPiPDelegate: NSObject, AVPictureInPictureControllerDelegate {
    func pictureInPictureControllerDidStartPictureInPicture(_ pictureInPictureController: AVPictureInPictureController) {
        // Custom action when picture in picture started
    }
    // ... Others here.
}

let customDelegate = CustomPiPDelegate()
let theoPiP = theoplayer.pip
theoPiP?.nativePictureInPictureDelegate = customDelegate
```

## Known limitations

* VR360 is not supported in combination with Picture-in-Picture.
* Only server-side ad insertion is supported, no client-side ad insertion.
* Sideloaded text tracks are not supported.

## Resources

* [PiPConfiguration API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/PiPConfiguration)
* [PictureInPicture API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/PictureInPicture)

---

# HLS date ranges on iOS

The `#EXT-X-DATERANGE` tag associates a date range (i.e. a range of time defined by a starting and ending date) with a set of attribute/value pairs. It is a way of providing timed metadata in an HLS manifest. A possible use case is defining timed metadata for interstitial regions such as advertisements, but it can be used for any timed metadata needed by your stream.

Date ranges are not parsed by default. To enable them, set `hlsDateRange` to `true`, either on the player configuration (for all sources) or on an individual source.

Once enabled, the player exposes the date ranges as cues on a metadata text track, which you can consume through the text tracks API.

## Enabling date ranges

```swift
// in the player configuration
let configBuilder = THEOplayerConfigurationBuilder()
configBuilder.setHlsDateRange(true)
let theoplayer = THEOplayer(configuration: configBuilder.build())

// or in the source description
let source = SourceDescription(
    source: TypedSource(
        src: "https://example.com/example-stream.m3u8",
        type: "application/x-mpegurl",
        hlsDateRange: true
    )
)
```

## Reading date range cues

Date ranges are exposed as cues on a metadata text track. See "[How to detect active text track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-active-text-track-cues.md)" to learn how to listen for those cues.

## Resources

* [HLS specification: EXT-X-DATERANGE](https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.2.7)

---

# Preloading on iOS

The aim of preloading is to improve the user experience by loading parts of the video before the play button is hit, when the user is likely to play the video.

Choosing to preload your video content reduces the start-up time of your videos. It also makes some data regarding the current source (video duration, timeline thumbnails, etc.) available before the user initiates playback. On the other hand, when the video is less likely to be played, or when it is less beneficial (live video, autoplay), you can configure the player to not preload it and save bandwidth.

## Preloading settings

| Value      | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none`     | Do not preload anything. After setting the source, the player does not load the manifest nor any media files until the play method is invoked on the player.                                                                                                                                                                                                                           |
| `metadata` | Preload the metadata of the video. After setting the source, the player automatically loads the manifest file and waits for loading media files until the play method is invoked on the player. For static videos (e.g. MP4 files), this translates to preloading data from the start of the video in order to acquire e.g. the video's width and height and the initial video frames. |
| `auto`     | Preload enough data to allow for smooth initial playback. After setting the source, the player loads both the manifest files and enough media files until a sufficient playback buffer has been obtained.                                                                                                                                                                              |

## Usage

In this example, we are preloading metadata only.

```swift
theoplayer.preload = .metadata
```

## Remarks

* THEOplayer always prefers downloading data for the currently playing video over downloading data for a preloading video. Only when the currently playing video has enough data to play to the end of the video, does the player start preloading other videos.
* When preloading the first segment(s) (preload `auto`), the first frame of the video is shown under the big play button, if there is no poster.

## Resources

* [What are the benefits of preloading?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-are-the-benefits-of-preloading.md)
* [Preload API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Enums/Preload)
* [`player.preload`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C7preloadAA7PreloadOvp)

---

# How to save the progress of a caching task on iOS

The THEOplayer iOS SDK provides the capability to pause an ongoing caching task. Doing so stores the file state of the partially downloaded stream to disk, and allows the task to be resumed even after the application runtime has been terminated. See [`CachingTask`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/CachingTask) for the `pause()` method.

## Usage

The code example below demonstrates how to save the progress of ongoing caching tasks upon app termination from the app delegate.

```swift
import THEOplayerSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func applicationWillTerminate(_ application: UIApplication) {
        for task in THEOplayer.cache.tasks {
            if task.status == .loading {
                task.pause()
            }
        }
    }
}
```

Alternatively, Apple's [NotificationCenter](https://developer.apple.com/documentation/foundation/notificationcenter) provides an observer to receive app termination events:

```swift
import THEOplayerSDK

NotificationCenter.default.addObserver(
    self,
    selector: #selector(willTerminate),
    name: UIApplication.willTerminateNotification,
    object: nil
)

@objc func willTerminate() {
    for task in THEOplayer.cache.tasks {
        if task.status == .loading {
            task.pause()
        }
    }
}
```

## Limitations

The THEOplayer iOS SDK allows the caching task to continue while running in the background. However, control in the background thread is limited, and the termination signal falls short as noted in [Apple's documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623111-applicationwillterminate).

---

# Errors on iOS

We live in an imperfect world, and sometimes things go wrong. A viewer might not be able to watch a video stream for a variety of reasons. Some example reasons are:

* The video stream is unavailable,
* The video stream is not supported on the selected platform,
* The THEOplayer license is incorrectly configured.

**When an issue occurs, an error should be triggered**.

When a fatal playback issue occurs, THEOplayer exposes information about the error through the THEOplayer API. This allows you to detect errors: as a developer, you can use an event handler to catch (and handle) `error` events. This feature (i.e. being able to intercept errors and act on it) may be mandatory to you to achieve a use-case:

* You want to log the error on an analytics stack,
* You want to show your own error message to the viewer,
* ...

THEOplayer associates error codes with errors to categorize types of issues. As a developer, these error codes may help you to log an error on an analytics stack, or may help you to generate a custom error message towards your viewer.

## Related resources

* [How to do error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/error/error-handling.md): this article explains how you use event listeners to intercept the `error` event.
* [Error codes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/error/error-codes.md): this article explains what error codes are, and why they are useful.

---

# How to do error handling on iOS

As a developer, you could be interested in error handling for any of the following reasons:

* You want to render human-friendly error messages inside the video player. Reading this error message,

  * the user can either remediate the issue by themselves (e.g. by refreshing the page, by checking again in some time, ...),
  * or contact a support service with this error code.

* You want to send error-data to an analytics service. (And this service helps you to identify frequent issues.)

* You want to self-remediate the issue. For example, if a stream is unavailable, you want to retry to load the stream, or load a different stream.

* ...

THEOplayer exposes different types of errors, and you can interact with them in two ways:

1. Through an event listener, and attaching an event handler to this listener.
2. Through a getter, which holds data when an error has occurred.

The sections below describe the "top-level", "generic", "player" `error` event. This event is fatal and prevents playback. There are also other `error` events, for example the one dispatched by the Chromecast API. You handle those `error` events in the same fashion.

## Event listener

Subscribe to the [`ERROR`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/PlayerEventTypes#/s:13THEOplayerSDK16PlayerEventTypesV5ERRORAA0D4TypeCyAA05ErrorD0CGvpZ) event of the player, and attach a listener which implements the error handling. The [`ErrorEvent`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/ErrorEvent) exposes both a textual representation of the error, and a more descriptive [`THEOError`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/THEOError).

```swift
let listener = theoplayer.addEventListener(type: PlayerEventTypes.ERROR) { event in
    print(event.error)
    print(event.errorObject)
}
```

## Getter

You can query the last encountered player error through [`player.error`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C5errorSSSgvp).

```swift
print(theoplayer.error)
```

## Types of errors

"[Which error related events does the player expose](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/which-error-related-events-does-player-expose.md)" lists which types of errors there are. Note that generally speaking only the "generic error event" is fatal. Other events, like the "Chromecast error event" and the "ad error event", are considered non-fatal because some type of playback can still continue.

"[Error codes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/error/error-codes.md)" lists which error codes are available for the "generic error event".

---

# Error codes on iOS

THEOplayer has different types of error events. One of those error events is the "generic player error event". This error event indicates a fatal error, and can be intercepted through the player.

This error event exposes an "error code" to explain the occurred error. An error code may be more interesting to track than a verbose error message. For example, if you are logging errors through an analytics service, it could be useful to filter them by their error code.

An error code is a number (e.g. 2001), and it belongs to a category. The format of an error code is "\[category]\[sub-code]". For example, error "2001" belongs to category 2, and has sub-code 001. If the error is a generic sub-code for its category, then the sub-code is `000`. In other words, error `11000` is the "catch-all" for category `11`.

## Categories

Each error code belongs to an error category. At the time of writing, there are 11 categories.

1. Configuration error: the integrator misconfigured the player.
2. License error: the player license is no longer valid, incorrect or not provided.
3. Source invalid: the source is not valid, or cannot be played on the current platform.
4. Manifest load error: the manifest cannot be loaded or parsed.
5. Media not supported: the media cannot be played on the current platform.
6. Network error: the network timed out, or is not available.
7. Content protection error: anything DRM related. Key system is not supported, invalid license, license expired, key missing, output restricted...
8. Subtitle load error: the subtitles cannot be loaded or parsed...
9. VR not supported: VR is not available on the current platform, VR presentation cannot be switched.
10. Ad blocker detected: an ad has been blocked (or the third party CSAI library was not loaded).
11. Fullscreen error: switching to fullscreen is not possible (note: this may be the case when fullscreen was not triggered by user interaction).

Refer to "[How to do error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/error/error-handling.md)" to learn how to detect the "generic player error event".

## API references

* [`ErrorCategory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Enums/ErrorCategory)
* [`ErrorCode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Enums/ErrorCode)
* [`THEOErrorCode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Enums/THEOErrorCode)

---

# Network on iOS

THEOplayer makes a number of network requests, and receives responses, while it is loading and playing a stream. The Network API allows you to intercept those requests and responses, so you can inspect them, modify them, redirect them, or respond with your own data.

Common use cases are adding authentication headers or query parameters to segment requests, redirecting requests to another CDN, or rewriting a manifest before the player parses it.

The iOS SDK exposes this API through [`NetworkAPI`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/NetworkAPI), available on `player.network`. It allows you to intercept the requests and responses of HLS playlists.

## Related articles

* [How to add and remove request and response interceptors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/network/request-response-interceptors.md)

---

# How to add and remove request and response interceptors on iOS

A *request interceptor* runs before the player opens the connection, so it can change properties of the request such as its URL, method, headers or body. It can also respond to the request immediately, without contacting the server.

A *response interceptor* runs before the player consumes the response, so it can change the status, the headers or the body of the response.

On iOS, you intercept the requests and responses of HLS playlists with a [`MediaPlaylistInterceptor`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/MediaPlaylistInterceptor). This guide uses a simple UIKit `UIViewController`.

## Set up THEOplayer

Add your interceptor to the Network API after creating the player:

```swift
class ViewController: UIViewController {
    private var player: THEOplayer?

    override func viewDidLoad() {
        super.viewDidLoad()
        let player = THEOplayer()
        self.player = player
        player.frame = view.bounds
        player.addAsSubview(of: self.view)
        player.network.addMediaPlaylistInterceptor(self)
    }
}
```

## Intercepting the requests and responses

Use the `type` parameter of each method below to filter for HLS playlist types, such as the master playlist, a video playlist or a subtitles playlist.

```swift
extension ViewController: MediaPlaylistInterceptor {
    // For modifications that you would make to the request, ie. add custom headers, query parameters, etc...
    func shouldInterceptPlaylistRequest(type: THEOplayerSDK.HlsPlaylistType) -> Bool { true }

    // For modifications that you would make to the response, ie. edit the m3u8 file content, vtt file content etc...
    func shouldInterceptPlaylistResponse(type: THEOplayerSDK.HlsPlaylistType) -> Bool { true }

    // Will be called if shouldInterceptPlaylistRequest returns true
    func didInterceptPlaylistRequest(type: THEOplayerSDK.HlsPlaylistType, request: URLRequest) async throws -> URLRequest {
        var modifiedRequest = request
        // modify
        // ...
        return modifiedRequest
    }

    // Will be called if shouldInterceptPlaylistResponse returns true
    func didInterceptPlaylistResponse(type: THEOplayerSDK.HlsPlaylistType, url: URL, response: URLResponse, data: Data) async throws -> Data {
        var modifiedResponseData = ""
        // customize the data string that you would like to return, should be a valid HLS playlist file
        // ...
        let customDataResponse = modifiedResponseData.data(using: .utf8)
        return customDataResponse ?? data // `customDataResponse` is empty so playback will fail in this demo; return `data` to play
    }

    // Handle failure.
    func failedToPerformURLRequest(request: URLRequest, response: URLResponse) {}
}
```

## DRM request interception

The `MediaPlaylistInterceptor` API does not intercept DRM requests. To intercept FairPlay DRM requests, take a look at [our DRM integration sample](https://github.com/THEOplayer/samples-drm-integration/blob/master/ios/README.md).

## Related articles

* [Network introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/network/introduction.md)

---

# Player on iOS

The Player API is the top-level API. This API exposes:

* basic functions to manipulate video playback, such as start and pause;
* properties to check states and values, such as the playhead position;
* events to track changes.

## Events

As a developer, you can programmatically attach event listeners to different APIs. Event listeners are often used to implement a custom UI, or to implement a custom analytics integration.

The THEOplayer API exposes many events across different interfaces, as can be seen in the graphic below. Furthermore, most events exist in all SDKs (Web, iOS-based, Android-based and Roku).

![THEOplayer API Interfaces and Events](/pr-932/assets/images/analytics-events-185d6ab52b556af08d8300b545ae5876.png "THEOplayer API Interfaces and Events")

Our APIs are continuously evolving, and so is our list of events. Refer to [the `PlayerEventTypes` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/PlayerEventTypes) to go through the latest set of player events, and to [the iOS SDK API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios) for the events of the other interfaces.

## Related articles

* [How do you know when a stream or an advertisement is playing?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/player/detect-stream-or-ad-playing.md)
* [How to measure the time-to-first-frame](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/player/measure-time-to-first-frame.md)
* [How to track the first play(ing) event](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/player/track-first-playing-event.md)
* [How to track player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/player/track-player-states.md)

---

# How do you know when a stream or an advertisement is playing on iOS?

This guide explains how to determine programmatically when the player is playing, and whether it is playing a stream or a client-side advertisement. This is useful when you want different behavior, or a different UI, for content and for advertisements.

The `playing` event tells you when content or an advertisement starts playing. Its event handler is the right place to check whether an advertisement is playing.

This approach only works for client-side advertisements, not for server-side advertisements.

## Usage

The iOS SDK exposes whether an advertisement is playing through [`player.ads.playing`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/Ads#/s:13THEOplayerSDK3AdsP7playingSbvp).

```swift
playingListener = player.addEventListener(type: PlayerEventTypes.PLAYING) { [weak self] event in
    guard let self else { return }
    let adIsPlaying = self.player.ads.playing
    print("PLAYING", adIsPlaying ? "Advertisement" : "Content", event)
}
```

## Related articles

* [How to track the first play(ing) event](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/player/track-first-playing-event.md)

---

# How to measure the time-to-first-frame on iOS

The time-to-first-frame, also known as the start-up time, is the time between the moment where playback is requested and the moment where the first frame is rendered.

To measure it, measure the time between the `play` event and the `playing` event.

## Usage

```swift
var playEventRegisteredAt: Date?
var playListener: EventListener?
var playingListener: EventListener?

playListener = player.addEventListener(type: PlayerEventTypes.PLAY) { [weak self] _ in
    guard let self, let playListener = self.playListener else { return }
    self.player.removeEventListener(type: PlayerEventTypes.PLAY, listener: playListener)
    self.playEventRegisteredAt = Date()
}

playingListener = player.addEventListener(type: PlayerEventTypes.PLAYING) { [weak self] _ in
    guard let self, let playingListener = self.playingListener, let playEventRegisteredAt = self.playEventRegisteredAt else { return }
    self.player.removeEventListener(type: PlayerEventTypes.PLAYING, listener: playingListener)
    let timeToFirstFrame = Date().timeIntervalSince(playEventRegisteredAt)
    print("Time-to-first-frame:", timeToFirstFrame, "second(s)")
}
```

---

# How to track the first play(ing) event on iOS

Sometimes you want to know when a new stream starts playing for the first time, for example to forward a `firstplay` event to an analytics back-end. THEOplayer does not expose such an event, but you can implement it yourself, which gives you more control over its logic.

The implementation below listens for the first `playing` event after every source change. If the viewer pauses and resumes the stream, the event is not dispatched again. If the viewer switches to another stream, it is dispatched once more.

You can swap out the `playing` event for a `play` event, or for any other event for that matter.

## Usage

```swift
var firstPlayingListener: EventListener?

func addFirstPlayingListener() {
    firstPlayingListener = player.addEventListener(type: PlayerEventTypes.PLAYING) { [weak self] _ in
        self?.removeFirstPlayingListener()
        print("First playing event!")
    }
}

func removeFirstPlayingListener() {
    if let firstPlayingListener {
        player.removeEventListener(type: PlayerEventTypes.PLAYING, listener: firstPlayingListener)
        self.firstPlayingListener = nil
    }
}

player.addEventListener(type: PlayerEventTypes.SOURCE_CHANGE) { [weak self] _ in
    self?.removeFirstPlayingListener()
    self?.addFirstPlayingListener()
}
```

Instead of `SOURCE_CHANGE`, you can also listen for `LOADED_META_DATA`, which is dispatched once the player has loaded the metadata of the new stream.

## Related articles

* [How do you know when a stream or an advertisement is playing?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/player/detect-stream-or-ad-playing.md)

---

# How to track player states on iOS

A video player has states. As a developer, you should understand these states, as each state grants you access to different data, and might imply a re-render of your UI. For example, if your video player is in the "Paused" state, you want to show a play-button instead of a pause-button.

The objective of this guide is to define some video player states, and how to track the transition between states.

Although there's no official list of video player states, we'll define 11 states for learning purposes. These 11 states are visualized in the state diagram below.

![Video Player States](/pr-932/assets/images/player-video-player-states-4f4f37f92d4b03a2c750ce7fe03d0a5a.png "Video Player States")

The table below provides the definitions of these 11 states.

| State                            | Description                                                                                                                                                                                                                                                                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A: Empty                         | A state where the player is created, but has no information or data retained on the source which is to be played. The player is idle and not undertaking any interaction with the system.                                                                                                                                                         |
| B: Initialized                   | A state where the player knows the source which is to be played, but no media data is loaded. The player is idle and not undertaking any interaction with the system.                                                                                                                                                                             |
| C: Playing - HAVE\_NOTHING       | A state where the player wants to start playing a source, but has no media data available. The player is actively loading media data in order to initiate playback.                                                                                                                                                                               |
| D: Paused - HAVE\_NOTHING        | A state where the player wants to fill its buffer without playing, but has no media data available. The player is actively loading media data in order to fill its buffer.                                                                                                                                                                        |
| E: Playing - HAVE\_METADATA      | A state where the player wants to start playing a source, but only metadata is available and the entire buffer is still empty. The player knows which tracks and qualities are available. The player is actively loading media data in order to initiate playback.                                                                                |
| F: Paused - HAVE\_METADATA       | A state where the player wants to fill its buffer without playing, but only metadata is available and the entire buffer is still empty. The player knows which tracks and qualities are available. The player is actively loading media data in order to fill its buffer.                                                                         |
| G: Playing - HAVE\_CURRENT\_DATA | A state where the player wants to start playing a source and has media data in its buffer for the current timestamp, but this data is insufficient to start playback and guarantee a smooth viewer experience. The player is actively loading media data in order to initiate playback.                                                           |
| H: Paused - HAVE\_CURRENT\_DATA  | A state where the player wants to fill its buffer without playing and has media data in the buffer for the current timestamp, but this data is insufficient to start playback and guarantee a smooth viewer experience. The player is actively loading media data in order to fill its buffer.                                                    |
| I: Playing                       | A state where the player is actively rendering out media data. The current timestamp is progressing at the speed of the current playback rate and media buffer data is being consumed and loaded in parallel. timeupdate events will be dispatched regularly during playback and progress events will be dispatched as additional data is loaded. |
| J: Paused                        | A state where the player has sufficient media data in its buffer in order to guarantee a smooth viewer experience when playback is started, but it is in a paused state. The player is not consuming any media data, but might be loading additional media data to grow its buffer in the background.                                             |
| K: Error                         | A state where the player has observed a fatal, non recoverable error. The player cannot continue playback and needs to be initialized again in order to restart playback. A player can get into this state from any state other than the Empty-state.                                                                                             |

The table below explains what triggers each of the 26 transitions between states, and what video player events are related.

| Transition | Triggers                                                                                                   | Events                                                                                                                                                    |
| ---------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1          | `new THEOplayer.Player`                                                                                    |                                                                                                                                                           |
| 2          | `player.source = X`                                                                                        | `sourcechange`, `currentsourcechange`                                                                                                                     |
| 3          | `player.play()`                                                                                            | `play`, `loadstart`                                                                                                                                       |
| 4          | `player.load()`                                                                                            | `loadstart`                                                                                                                                               |
| 5          | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 6          | `player.play()`                                                                                            | `play`                                                                                                                                                    |
| 7          | The stream manifest being loaded                                                                           | `readystatechange`, `loadedmetadata`, `durationchange`                                                                                                    |
| 8          | The stream manifest being loaded                                                                           | `readystatechange`, `loadedmetadata`, `durationchange`                                                                                                    |
| 9          | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 10         | `player.play()`                                                                                            | `play`                                                                                                                                                    |
| 11         | Stream media data is loaded                                                                                | `readystatechange`, `loadeddata`, `progress`, `canplay`                                                                                                   |
| 12         | Stream media data is loaded                                                                                | `readystatechange`, `loadeddata`, `progress`, `canplay`                                                                                                   |
| 13         | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 14         | `player.play()`                                                                                            | `play`                                                                                                                                                    |
| 15         | Sufficient media data is loaded to start playback fluently.                                                | `progress`, `canplaythrough`, `readystatechange`, `playing`<br />*A `seeked` event can be dispatched if the entrance of this state was caused by a seek.* |
| 16         | Sufficient media data is loaded to start playback fluently.                                                | `canplaythrough`, `readystatechange`<br />*A `seeked` event can be dispatched if the entrance of this state was caused by a seek.*                        |
| 17         | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 18         | `player.play()`                                                                                            | `play`, `playing`                                                                                                                                         |
| 19         | `player.currentTime = X` and there is some media data at the target time, but not enough to play fluently. | `seeking`, `readystatechange`                                                                                                                             |
| 20         | The player buffer is not being filled enough, causing a stall.                                             | `waiting`, `readystatechange`                                                                                                                             |
| 21         | `player.currentTime = X` and there is no media data at the target time.                                    | `seeking`, `readystatechange`                                                                                                                             |
| 22         | Playback has ended.                                                                                        | `ended`, `readystatechange`                                                                                                                               |
| 23         | `player.currentTime = X` and there is some media data at the target time, but not enough to play fluently. | `seeking`, `readystatechange`                                                                                                                             |
| 24         | `player.currentTime = X` and there is no media data at the target time.                                    | `seeking`, `readystatechange`                                                                                                                             |
| 25         | An error occurred.                                                                                         | `error`                                                                                                                                                   |
| 26         | `player.source = null`                                                                                     | `emptied`                                                                                                                                                 |

## Implementation

The code samples below demonstrate how you track some of the 18 events related to the state transitions.

* `sourcechange`
* `currentsourcechange`
* `play`
* `loadstart`
* `pause`
* `readystatechange`
* `loadedmetadata`
* `durationchange`
* `loadeddata`
* `progress`
* `canplay`
* `canplaythrough`
* `playing`
* `waiting`
* `seeking`
* `ended`
* `error`
* `emptied`

All 18 events are dispatched by the `Player` interface.

The snippet below demonstrates how you can track some of the related events through the iOS SDK. All other events can be tracked similarly. You can find the event names in [the `PlayerEventTypes` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/PlayerEventTypes), and the properties of the player in [the `THEOplayer` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer). This approach is valid for all iOS-based platforms, including iPadOS and tvOS.

```swift
player.addEventListener(type: PlayerEventTypes.SOURCE_CHANGE) { event in
    print(event)
}
// ...
player.addEventListener(type: PlayerEventTypes.ENDED) { event in
    print(event)
}
```

---

# Text tracks on iOS

The articles in this section describe how to implement common use-cases related to text tracks, subtitles, closed captions and metadata. These use-cases can range from programmatically detecting new metadata, to side-loading subtitles.

THEOplayer supports

* subtitle and closed caption formats like WebVTT, CEA-608, DVB Subs and TTML;
* metadata formats like ID3, emsg, EventStream and `EXT-X-DATERANGE`.

The TextTrack API allows you to programmatically switch between text tracks, detect events related to text tracks (e.g. a new active cue) and more.

## Related articles

* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/change-visible-captions.md)
* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-text-tracks.md)
* [How to programmatically detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-text-track-changes.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/enable-disable-text-tracks.md)
* [How to detect active text track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-active-text-track-cues.md)
* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/insert-subtitles.md)
* [How to implement preview thumbnails](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/preview-thumbnails.md)
* [How to track ID3 cues/tags](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/track-id3-cues.md)

---

# How to dynamically change the visible captions on iOS

This article describes how you can dynamically change the currently selected subtitle or closed captions language, or how you can set a default language.

This article assumes that you are using text tracks that are loaded with the manifest. If you add the text track separately, you can also mark it as the default track when you configure your source.

The examples below match tracks on their `language` property, which contains the ISO language code of the track. If that is not sufficient for your use case, for example when a stream contains multiple tracks with the same language, you can match on the track's `label` instead, which contains the human-readable name shown in your UI.

## Usage

The function below enables the text track with the requested language.

```swift
private func setLanguage(player: THEOplayer, language: String) {
    let list: TextTrackList = player.textTracks
    for i in 0..<list.count {
        let textTrack: TextTrack = list[i]
        textTrack.mode = textTrack.language == language ? .showing : .disabled
    }
}
```

## Related articles

* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-text-tracks.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/enable-disable-text-tracks.md)
* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/insert-subtitles.md)

---

# How to programmatically detect text tracks on iOS

This article describes how you can use the TextTrack API to detect text tracks, which can be subtitles, closed captions or metadata. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available subtitle languages.

## Usage

Listen for the [`ADD_TRACK`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/TextTrackListEventTypes) event on [`player.textTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C10textTracksAA13TextTrackList_pvp) to detect every [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/TextTrack) that is added to the player.

```swift
self.player.textTracks.addEventListener(type: TextTrackListEventTypes.ADD_TRACK, listener: { addTrackEvent in
    let textTrack = addTrackEvent.track
})
```

## Related articles

* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/enable-disable-text-tracks.md)
* [How to programmatically detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-text-track-changes.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/build-chromeless-ui.md)

---

# How to programmatically enable or disable text tracks on iOS

This article describes how you can use the TextTrack API to enable or disable subtitles, closed captions or metadata. Implementing this functionality is a common use-case for developers who want to build their own UI to toggle subtitles.

It is advised to disable the text tracks which you do not want to display, in order to avoid issues with overlapping text.

## Usage

Set the `mode` of a [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/TextTrack).

```swift
// disable all text tracks
for i in 0..<self.player.textTracks.count {
    self.player.textTracks[i].mode = .disabled
}
// enable a specific text track
self.player.textTracks[indexOfRequestedTextTrack].mode = .showing
```

## Related articles

* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/change-visible-captions.md)
* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-text-tracks.md)
* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/build-chromeless-ui.md)

---

# How to insert subtitles on iOS

This article describes how you can side-load subtitles or closed captions, i.e. how you can add text tracks which are not part of your HLS or MPEG-DASH manifest.

Every source description has a text tracks property, which accepts an array of side-loaded text tracks. All valid tracks are available for playback as long as the player's source is not set again.

Text track descriptions can also be used for other purposes, e.g. for including preview thumbnails and chapters.

## Prerequisites

On iOS and tvOS, playback goes through AVFoundation, which cannot sideload subtitles by itself. To insert subtitles that are not part of your stream, you need the [Sideloaded Subtitles connector](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/sideloaded-texttracks/getting-started.md) in addition to the THEOplayer iOS SDK.

Add the connector to your `Podfile` and install it:

```ruby
pod 'THEOplayer-Connector-SideloadedSubtitle'
```

Always use matching THEOplayer and connector versions, because the connector relies on an experimental API of the iOS SDK.

> **Note**
>
> The connector is only needed for subtitle text tracks. Metadata text tracks, such as WebVTT thumbnails, are sideloaded by the THEOplayer iOS SDK itself.

## Usage

Each text track is described by a `TextTrackDescription`.

```swift
var sampleSource: SourceDescription {
    let textTrack1 = TextTrackDescription(src: "https://your.webvtt", srclang: "en", isDefault: true, kind: .subtitles, label: "English", format: .WebVTT)
    let textTrack2 = TextTrackDescription(src: "https://your.webvtt", srclang: "ar", isDefault: false, kind: .subtitles, label: "Arabic", format: .WebVTT)

    return SourceDescription(
        source: TypedSource(
            src: "https://your.m3u8",
            type: "application/x-mpegurl"
        ),
        textTracks: [textTrack1, textTrack2]
    )
}
```

Then set the source on the player through the connector's `setSourceWithSubtitles` method, instead of assigning it to `player.source`:

```swift
import THEOplayerConnectorSideloadedSubtitle

self.theoplayer.setSourceWithSubtitles(source: sampleSource)
```

> **Warning**
>
> Replace every `player.source = source` call in your app with `setSourceWithSubtitles(source:)` if you sideload subtitles on at least one of your sources, even for sources without sideloaded subtitles. Mixing both approaches can lead to unexpected behavior.

Take note of the following limitations of sideloaded subtitles on iOS and tvOS:

* Only WebVTT (iOS-compatible) and SRT subtitles are supported.
* The label of the text track is generated by the operating system based on the language code, so the `label` you configure is disregarded.
* The `isDefault` flag is ignored. To show a sideloaded subtitle track by default, listen for the `ADD_TRACK` event and set the mode of the track to `showing`, as described in [how to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/enable-disable-text-tracks.md).

The connector documentation covers additional features, such as [shifting the presentation of cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/sideloaded-texttracks/getting-started.md#setting-a-time-offset) and [caching sideloaded subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/sideloaded-texttracks/getting-started.md#caching) for offline playback.

## Related articles

* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/change-visible-captions.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/enable-disable-text-tracks.md)
* [How to implement preview thumbnails](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/preview-thumbnails.md)

---

# How to implement preview thumbnails on iOS

This article describes how you can enable preview thumbnails, which THEOplayer implements through the TextTrack API. The thumbnails are loaded as a separate text track, by side-loading them as a text track in your source description.

A demo of the preview thumbnails on the THEOplayer Web SDK is available at [preview thumbnails](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/preview-thumbnails.md).

## Usage

You can add or edit your source description as follows.

```swift
player.source = SourceDescription(
    source: TypedSource(
        src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8",
        type: "application/x-mpegurl"
    ),
    textTracks: [
        TextTrackDescription(
            src: "https://cdn.theoplayer.com/dash/theoplayer/thumbnails/big_buck_bunny_thumbnails.vtt",
            srclang: "en",
            isDefault: true,
            kind: .metadata,
            label: "thumbnails"
        )
    ]
)
```

## Related articles

* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/insert-subtitles.md)

---

# How to track ID3 cues and tags on iOS

[ID3](https://en.wikipedia.org/wiki/ID3) is a type of metadata which can be inserted in HTTP live streams. Once an ID3 cue is inserted, it is added to a THEOplayer text track.

Developers commonly track ID3 cues because they want to introduce a certain behavior depending on the metadata contained by the ID3 cues, for example:

* to schedule advertisements dynamically by using information passed on by the ID3 metadata;
* to overlay certain text on top of the player (e.g. the score of a football match).

The demo at <https://demo.theoplayer.com/audio-id3-metadata> demonstrates a usage of ID3 metadata. Just before the song changes, an `enter` event is dispatched. The song information (title, album, etc.) is contained within this `enter` event, and can be used to update the UI.

This article describes how you can listen for timed metadata events, and how you can track the `enter` event.

## Listening for timed metadata events

Listen for the `CUE_CHANGE` event of a [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/TextTrack).

```swift
let cueChangeListener = { (event: CueChangeEvent) in
    // do something with the cues
}

let handleTrackCreation = { (event: AddTrackEvent) in
    if let textTrack = event.track as? TextTrack {
        _ = textTrack.addEventListener(type: TextTrackEventTypes.CUE_CHANGE, listener: cueChangeListener)
    }
}

_ = player.textTracks.addEventListener(type: TextTrackListEventTypes.ADD_TRACK, listener: handleTrackCreation)
```

## Tracking the enter event

The `enter` event, which is part of the TextTrack API, maps to the moment in time when the ID3 cue becomes relevant.

```swift
let enterListener = { (event: EnterCueEvent) in
    // do something with the cue
}

let handleTrackCreation = { (event: AddTrackEvent) in
    if let textTrack = event.track as? TextTrack {
        _ = textTrack.addEventListener(type: TextTrackEventTypes.ENTER_CUE, listener: enterListener)
    }
}

_ = player.textTracks.addEventListener(type: TextTrackListEventTypes.ADD_TRACK, listener: handleTrackCreation)
```

## Resources

* <https://demo.theoplayer.com/audio-id3-metadata>: a demo which illustrates the use of ID3 in production.
* <http://id3.org/>: ID3.org home page.
* <https://en.wikipedia.org/wiki/ID3>: Wikipedia - ID3.
* <https://dev.w3.org/html5/html-sourcing-inband-tracks/>: Sourcing In-band Media Resource Tracks from Media Containers into HTML.

## Related articles

* [How to detect active text track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-active-text-track-cues.md)
* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-text-tracks.md)

---

# How to programmatically detect text track changes on iOS

This article describes how you can use the TextTrack API to detect text track changes. A text track "change" is triggered by enabling (or disabling) a subtitle or closed captions track.

Implementing this functionality is a common use-case for developers who want to build their own UI, and annotate the subtitle (or closed captions) track that is currently active.

## Usage

The implementation of the iOS SDK applies to all iOS-based platforms, including iPadOS and tvOS.

The iOS SDK exposes the TextTrack API through [`player.textTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C10textTracksAA13TextTrackList_pvp). This `textTracks` property is a [`TextTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/TextTrackList). This `TextTrackList` dispatches the events from the [`TextTrackListEventTypes`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/TextTrackListEventTypes). The `TextTrackListEventTypes` contains the [`CHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/TextTrackListEventTypes#/s:13THEOplayerSDK23TextTrackListEventTypesV6CHANGEAA0F4TypeCyAA0d6ChangeF0CGvpZ) event, as well as the `ADD_TRACK` and `REMOVE_TRACK` event.

The code below allows you to detect text track changes.

```swift
player?.textTracks.addEventListener(type: TextTrackListEventTypes.CHANGE, listener: { event in
    let track: TextTrack = event.track as! TextTrack
    let isEnabled = track.mode == .showing
    print(track.label, track.kind, track.type, isEnabled)
})
```

The properties of a text `track` (e.g. `mode`, `kind`) are described in the [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/TextTrack) and [`Track`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/Track) API references.

## Related articles

Are you reading this article because you are interested in subtitles and closed captions? Continue reading below.

* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-text-tracks.md)
* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/change-visible-captions.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/enable-disable-text-tracks.md)
* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/insert-subtitles.md)

Refer to [how to track ID3 cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/track-id3-cues.md) if you are interested in timed metadata (ID3, emsg, EventStream, `EXT-X-DATERANGE`, ...).

Are you reading this article because you are implementing a custom UI? Then you will find the following articles interesting:

* [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/build-chromeless-ui.md)
* [How to detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-video-track-quality-changes.md)
* [How to detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-audio-track-changes.md)

---

# How to detect active text track cues on iOS

This article describes how you can use the TextTrack API to detect the active text track cues, by subscribing to the `enter` and `exit` events of a cue, or to the `cuechange` event of a text track.

Implementing this functionality can be a use-case for developers who want to build their own UI, and insert and style their subtitles with maximum freedom. Alternatively, you may need to access the active cues for analytics purposes, or to render them outside of the video player.

Another common use-case is to detect the active text track cue of timed metadata. This article also discusses this use-case.

## Implementation for subtitles and closed captions

Note that this section focuses on detecting active cues for subtitles and closed captions. Go to the section on ["implementation for timed metadata"](#implementation-for-timed-metadata) if you rather want to track timed metadata like ID3, emsg, `EXT-X-DATERANGE` and EventStream.

The iOS SDK exposes the TextTrack API through [`player.textTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C10textTracksAA13TextTrackList_pvp). This `textTracks` property is a [`TextTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/TextTrackList). This `TextTrackList` dispatches the events from the [`TextTrackListEventTypes`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/TextTrackListEventTypes). The `TextTrackListEventTypes` contains the [`ADD_TRACK`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/TextTrackListEventTypes#/s:13THEOplayerSDK23TextTrackListEventTypesV9ADD_TRACKAA0F4TypeCyAA03AdddF0CGvpZ) event, as well as the `CHANGE` and `REMOVE_TRACK` event.

In the callback of your `ADD_TRACK` event, you want to track the [`ADD_CUE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/TextTrackEventTypes#/s:13THEOplayerSDK19TextTrackEventTypesV7ADD_CUEAA0E4TypeCyAA06AddCueE0CGvpZ) event through the [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/TextTrack) interface. Then, in the callback of your `ADD_CUE` event, you want to track the [`ENTER`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/TextTrackCueEventTypes#/s:13THEOplayerSDK22TextTrackCueEventTypesV5ENTERAA0F4TypeCyAA0e5EnterF0CGvpZ) and [`EXIT`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/TextTrackCueEventTypes#/s:13THEOplayerSDK22TextTrackCueEventTypesV4EXITAA0F4TypeCyAA0e4ExitF0CGvpZ) events through the [`TextTrackCue`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/TextTrackCue) interface. The `ENTER` event is dispatched when a cue becomes active and the `EXIT` event is dispatched when a cue becomes inactive. You can fetch the actual content in the callback of your `ENTER` event through its [`content`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/TextTrackCue#/s:13THEOplayerSDK12TextTrackCueP7contentypSgvp) property.

Alternatively, in the callback of your `ADD_TRACK` event, you could track the [`CUE_CHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/TextTrackEventTypes#/s:13THEOplayerSDK19TextTrackEventTypesV10CUE_CHANGEAA0E4TypeCyAA09CueChangeE0CGvpZ) event through the `TextTrack` interface. Then, in the callback of your `CUE_CHANGE` event, you want to iterate over the active cues. For each active cue, you could also query its `content` property.

The code below allows you to detect the active text track cues.

```swift
player.textTracks.addEventListener(type: TextTrackListEventTypes.ADD_TRACK) { addTrackEvent in
    let track: TextTrack = addTrackEvent.track as! TextTrack
    track.addEventListener(type: TextTrackEventTypes.ADD_CUE) { addCueEvent in
        let cue = addCueEvent.cue
        cue.addEventListener(type: TextTrackCueEventTypes.ENTER) { enterEvent in
            print(enterEvent, enterEvent.cue.content)
        }
        cue.addEventListener(type: TextTrackCueEventTypes.EXIT) { exitEvent in
            print(exitEvent)
        }
    }
    track.addEventListener(type: TextTrackEventTypes.CUE_CHANGE) { cueChangeEvent in
        let textTrack: TextTrack = cueChangeEvent.track as! TextTrack
        textTrack.activeCues.forEach { cue in
            print("cuechange active cue", cue)
        }
    }
}
// ...
// player.source = ...
```

You should invoke these event handlers before you configure your stream, because the player might have already dispatched the event before you were able to subscribe to it.

## Implementation for timed metadata

The implementation for timed metadata is identical to the one for subtitles and closed captions, except for three things.

1. You do not necessarily use the `enter` event. For cues that span a period of time, for example `EXT-X-DATERANGE` cues, you might want to perform your action when the cue ends, so on the `exit` event instead.

2. You might need to set the `mode` of the relevant text track to `hidden`, as documented in [how to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/enable-disable-text-tracks.md). Some types of timed metadata, for example `EXT-X-DATERANGE` and EventStream, are `disabled` by default. You should add a condition to your `addtrack` callback to decide whether you want to set your track to `hidden`.

3. You should set [`hlsDateRange`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayerConfiguration) to `true` in your player configuration or stream configuration, if you want to detect `EXT-X-DATERANGE` tags in an HLS stream.

The article on [how to track ID3 cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/track-id3-cues.md) might be useful to learn more about detecting ID3 tags specifically.

## Related articles

* [How to programmatically detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-text-track-changes.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/enable-disable-text-tracks.md)
* [How to track ID3 cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/track-id3-cues.md)

---

# License on iOS

A THEOplayer license is required to use THEOplayer. The licensing schema was previously based on the built-in license from the SDK build, but THEOplayer now allows you to update the license without rebuilding or re-integrating the player SDK.

This article explains how to configure the license at runtime.

## Passing the license through the player configuration

Include the license in the player configuration, either by passing the license as a string or by passing a license URL:

```swift
// passing the license as a string
let playerConfig = THEOplayerConfiguration(license: "your_license_here")
let theoplayer = THEOplayer(configuration: playerConfig)
```

```swift
// passing the license as a URL
let playerConfig = THEOplayerConfiguration(licenseUrl: "your_licenseUrl_here")
let theoplayer = THEOplayer(configuration: playerConfig)
```

## Passing the license through the Info.plist

Define the same `license` or `licenseUrl` as a new key in the `Info.plist` file.

The iOS SDK allows configuring the license through the `THEOplayerLicense` or `THEOplayerLicenseUrl` keys.

* `THEOplayerLicense` must be a license string
* `THEOplayerLicenseUrl` must be a valid URL to a license server

The license defined in the player configuration has higher precedence than the license provided in the `Info.plist`. If neither of these are defined, then the player will throw a license error.

## FAQ

### Why do I have to configure a license?

In order to provide THEOplayer insights if a stream can be played, it needs to have access to an active license. You can choose to either configure this license, or configure a URL where this license can be retrieved. We recommend everyone to configure an active license or a license URL.

### How do I avoid introducing any dependencies on THEOplayer servers?

There are two important aspects which can introduce a dependency on THEOplayer servers:

1. **Loading a THEOplayer SDK from the THEOplayer CDN.** This issue is only relevant for the Web SDK. In order to avoid this dependency, we recommend to self-host your THEOplayer SDK. The easiest approach is to load the player through npm, or download the player SDK as a zip file from the developer portal. More information on how to self-host your player can be found in "[Self-hosting THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/self-hosting-theoplayer.md)".
2. **Loading a THEOplayer license from the THEOplayer license system.** In order to avoid this dependency, it is important to always keep your license up to date, either by configuring an updated license or by configuring your own license URL. When your THEOplayer license expires, a new player instance will actively check against THEOplayer's license system if there is an updated license available. This system should however only serve as a fallback for applications which cannot be updated.

### Should I pass a license string or a license URL?

We recommend our customers to use the license string whenever possible.

In special cases it is possible to use the license URL instead. Use cases include contractual or legal (for example privacy) requirements. For more information, please contact <support@theoplayer.com>.

If the player is configured with both a license string and a license URL, it will first try to validate the license string. If the license string is either not configured or expired, the player will attempt to request the license URL instead. If no license URL is defined, then a default license URL will be used. If no valid license can be found, the player will throw a license error.

### Should I update my application upon license renewal?

Yes. After renewing your license, you should make sure to include the new THEOplayer license in your next app update.

### What happens if I don't timely update the license in my application?

The player will attempt to update the license up to 72 hours before expiration. For this, the player will request a new license either from the configured license URL, or as a fallback (when there is no license URL configured) from `validate.theoplayer.com`. Either way, if the request is successful, the player will store the license locally. We highly recommend you to self-host the license using the license URL in the player configuration.

For self-hosting, the license file with the latest license string for your application should be hosted. The full URL to this file should then be configured as the license URL in the player configuration.

### Will I still be able to play offline content with my THEOplayer SDK if my license expires?

When your license expires, THEOplayer will attempt to load an updated license. If an updated license is available, offline playback will still function. If no valid license is available, and no license server can be reached (due to the client being offline), the player will throw an error and stop playback. For this reason, it is important to always keep your license up to date.

### What should I do to protect my license?

The THEOplayer license you get from THEOportal is already an obfuscated string. If you want to protect your license, you need to make sure to configure your [page and source domains](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/page-and-source-domains.md) to guarantee that your license string cannot be used anywhere other than the specified pages and/or with those source domains.

---

# Getting started with CMCD on iOS

Media player clients can transmit useful information to Content Delivery Networks (CDNs) with each object request. This implementation is planned to fully support Common Media Client Data (CMCD) as defined in [CTA-5004-B](https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html), published in April 2026.

CMCD supports two modes of transmission:

* **Request mode**: CMCD data is sent as HTTP headers or query parameters on manifest and media segment requests.
* **Event mode** (available since v11.4.0): CMCD events are POSTed to configured HTTP endpoints.

## Request Mode

To enable CMCD, developers can set the `cmcd` parameter inside a SourceDescription.

```swift
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", cmcd: true)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

### Remarks

Note that request mode is only supported on iOS 18.0+.

## Event Mode

Event mode allows posting CMCD events to configured HTTP endpoints.

> **Info**
>
> Event mode is supported starting from version 11.4.0.

### Player-level configuration

```swift
let cmcdConfig = CMCDConfiguration(
    externalSessionId: "YOUR-EXTERNAL-SESSION-ID", // optional
    userId: "YOUR-USER-ID", // optional
    eventEndpoints: [
        CMCDEndpointConfiguration(url: "https://example.com/cmcd-event-endpoint")
    ]
)
let config = THEOplayerConfigurationBuilder()
config.cmcd = cmcdConfig
let player = THEOplayer(configuration: config.build())
```

### Source-level configuration

```swift
let sourceConfig = CMCDSourceConfiguration(
    externalSessionId: "YOUR-EXTERNAL-SESSION-ID", // optional
    sessionId: "YOUR-SESSION-ID", // optional
    userId: "YOUR-USER-ID", // optional
    eventEndpoints: [
        CMCDEndpointConfiguration(url: "https://example.com/cmcd-event-other-endpoint")
    ]
)
player.source = SourceDescription(
    source: TypedSource(src: "<HLS_STREAM_URL>"),
    cmcdConfiguration: sourceConfig
)
```

### Merging behavior

* Source-level values take precedence for `externalSessionId` and `userId`.
* `eventEndpoints` from both levels are **merged** (both player and source endpoints receive events).

> **Warning**
>
> Event mode reporting currently only supports DRM and ad events.

---

# Getting started

## Usage

1. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/ios/getting-started.md) to set up THEOplayer in your iOS app.
2. Add an OptiView Live source to your player's source.

### Add an OptiView Live source

After setting up your THEOplayer in your app, set its source to a `SourceDescription` containing a `TheoLiveSource`. You'll need an OptiView Live channel ID:

```swift
theoplayer.source = SourceDescription(source: TheoLiveSource(channelId: "3aa5qylwwk7gijsobayq09yee"))
```

## More information

* [API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios)

---

# Metadata

Metadata that travels through your OptiView Live stream — whether [pushed via the API or embedded as SEI](https://docs-preview.optiview.dolby.com/pr-932/theolive/channel/metadata-insertion.md) — surfaces on the player as cues on a text track. The general approach is the same in every case:

1. Listen for `addtrack` on `player.textTracks` so you find out when a new metadata track shows up.
2. Subscribe to a cue event on that track.
3. Inspect the cue to make sure it carries the metadata you care about.
4. Read the payload from `cue.content`.

The properties you match on, the cue event you subscribe to, and the shape of `cue.content` all depend on which kind of metadata is being delivered.

## User-data-unregistered SEI and API push

UDU SEI and API-pushed payloads surface as ID3 `PRIV` frames inside an ID3 v2.4 tag embedded in an `emsg` box, carried by the CMAF segments of the stream.

* The owner identifier of the `PRIV` frame will be set to: `optiview.live:meta:<your-uuid>`
* The frame's private data will contain your metadata as raw binary data.

(See [section 4.27 of the ID3 v2.4 Native Frames specification](https://id3.org/id3v2.4.0-frames) and [ID3 in CMAF](https://aomediacodec.github.io/id3-emsg/) for more details.)

The OptiView Player iOS SDK exposes these ID3 frames on a text track with [`TextTrack.type`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/TextTrack) equal to `"id3"`. Listen for the cue event that matches when you want to react:

* `TextTrackEventTypes.ADD_CUE` fires as soon as a cue becomes available on the track, before playback reaches it — useful when you want to prefetch data or update application state ahead of time.
* `TextTrackEventTypes.ENTER_CUE` fires when playback enters the cue — useful when you want to act in sync with the video, for example to render an overlay at the moment the cue was inserted.

The ID3 frame will be contained in `cue.contentDictionary` with `id` equal to `"PRIV"` and `ownerIdentifier` equal to `optiview.live:meta:<your-uuid>`.

> **Important**
>
> Make sure to always check the frame's `id` and `ownerIdentifier` before using it, to avoid processing unrelated ID3 frames.

Suppose your UUID is `11111111-1111-1111-1111-111111111111`:

```swift
_ = theoplayer.textTracks.addEventListener(type: TextTrackListEventTypes.ADD_TRACK, listener: { (addTrackEvent) in
  guard let track = addTrackEvent.track as? TextTrack,
        track.type == "id3"
        else { return }
  // ID3 track was added. Listen for incoming ID3 cues.
  _ = track.addEventListener(type: TextTrackEventTypes.ADD_CUE, listener: { (addCueEvent) in
      guard let cue = addCueEvent.cue as? Id3Cue,
            let frame = cue.contentDictionary else { return }
      guard frame["id"] == "PRIV",
            frame["ownerIdentifier"] == "optiview.live:meta:11111111-1111-1111-1111-111111111111"
            else { return }
      print("Metadata: \(frame["data"])")
  })
})
```

Here the `frame["data"]` carries the binary payload exactly as it was sent — your application is responsible for parsing it (for example UTF-8 JSON, protobuf, or your own format).

## Source timecode

When the video you ingest carries SMPTE timecode in its picture timing SEI, the Low-Latency HLS and HLS (CMAF) output passes it on as ID3 timed metadata, so players can read the timecode of every frame without parsing the video bitstream. No channel configuration is needed. Channels whose source carries no timecode get no timecode events, and HLS (MPEG-TS) output does not carry them.

Timecode events travel the same way as the metadata above: an ID3 v2.4 tag in an `emsg` box with scheme `https://aomedia.org/emsg/ID3`, carried by the CMAF segments of the stream. The tag holds a `TXXX` (user defined text) frame:

* The description of the `TXXX` frame is `optiview.live:timecode`.
* Its value is the timecode as `HH:MM:SS:FF`, for example `10:00:00:12`. A drop-frame timecode has `;` before the frames instead: `10:00:00;12`.

(See [section 4.2.6 of the ID3 v2.4 Native Frames specification](https://id3.org/id3v2.4.0-frames) for the `TXXX` frame.)

### Where the events sit

There is one timecode event per segment and per partial segment. The event sits on the frame of that segment or partial segment that is presented first, and its `emsg` box declares a duration of exactly one frame. OptiView Player starts the cue at that frame's presentation time and keeps it active until the next timecode cue starts.

A segment and its first partial segment open on the same frame, so they carry the same event, with the same `emsg` id. If your player reports it twice, the two cues are identical.

### Timecode of any other frame

Only the first-presented frame of each segment or partial segment carries an event. To find the timecode of any other frame:

1. Take the latest timecode event that starts at or before the presentation time of the frame.
2. Count the frames presented since that event: multiply the time between the start of the event and the presentation time of the frame by the frame rate, which the multivariant playlist declares for each rendition as `FRAME-RATE`.
3. Add that many frames to the timecode of the event, counting with the frame rate rounded to a whole number (30 for 29.97 fps). For a drop-frame timecode, skip the frame numbers that drop-frame timecode leaves out: frames `00` and `01` at the start of every minute except every tenth minute at 29.97 fps, and frames `00` to `03` at 59.94 fps.

This assumes the rendition has the frame rate of the source. Every frame carries the timecode of the source frame it was encoded from, so on a rendition with a lower frame rate than the source, such as a 30 fps rendition of a 60 fps source, count at the frame rate of the source instead.

A jump in the source timecode, for example when the source switches to another timecode generator, only shows from the next segment or partial segment on. Until then, counting on from the previous event continues the old sequence.

### Reading the timecode with the iOS SDK

Timecode events surface on the same `"id3"` text track as the metadata above, as an `Id3Cue` whose `contentDictionary` has `id` equal to `"TXXX"` and `description` equal to `"optiview.live:timecode"`. The frame's `text` holds the timecode.

`TextTrackEventTypes.ENTER_CUE` fires when the frame carrying the timecode is presented, and `TextTrackEventTypes.EXIT_CUE` when the next timecode cue starts:

```swift
_ = theoplayer.textTracks.addEventListener(type: TextTrackListEventTypes.ADD_TRACK, listener: { (addTrackEvent) in
  guard let track = addTrackEvent.track as? TextTrack,
        track.type == "id3"
        else { return }
  _ = track.addEventListener(type: TextTrackEventTypes.ENTER_CUE, listener: { (enterCueEvent) in
      guard let frame = (enterCueEvent.cue as? Id3Cue)?.contentDictionary,
            frame["id"] == "TXXX",
            frame["description"] == "optiview.live:timecode"
            else { return }
      print("Timecode: \(frame["text"] ?? "")")
  })
  _ = track.addEventListener(type: TextTrackEventTypes.EXIT_CUE, listener: { (exitCueEvent) in
      guard let frame = (exitCueEvent.cue as? Id3Cue)?.contentDictionary,
            frame["id"] == "TXXX",
            frame["description"] == "optiview.live:timecode"
            else { return }
      print("Timecode ended: \(frame["text"] ?? "")")
  })
})
```

---

# Discovery URLs

Before the player can play an OptiView Live channel, it sends a discovery request to find the stream details of that channel (such as its manifest URLs and token security settings). OptiView Live channels are served by one of three discovery API versions:

| API version | Channels                                          |
| ----------- | ------------------------------------------------- |
| V1 (legacy) | Channels created with the legacy THEOlive API.    |
| V2          | Distributions created with the OptiView Live API. |
| V3          | Distributions served by the newest discovery API. |

The player does not know in advance which API version serves your channel. If you do not configure a discovery URL, the player tries its built-in discovery URLs one by one, in this order:

1. V2
2. V1 (legacy)
3. V3

The player stops at the first discovery URL that returns the channel. If your channel is not served by V2, the earlier requests fail before the right one succeeds. These failed requests add a small delay before playback starts, and they show up as `404` responses in the network tab of your browser or in a network proxy. The `404` responses are expected and do not mean that playback failed.

## Why configure a discovery URL

When you configure the discovery URL that serves your channel, the player sends its first discovery request to that URL. This removes the failed requests and the extra startup delay.

Configured discovery URLs do not replace the built-in discovery URLs. The player tries them first, and continues with the built-in discovery URLs (V2, V1, V3) if the configured ones do not return the channel. A wrong discovery URL therefore costs one extra request, but it does not break playback.

On platforms that support both `discoveryUrl` and `discoveryUrls`, the player tries `discoveryUrl` first, then each URL of `discoveryUrls` in the order of the list, and then the built-in discovery URLs.

## Which discovery URL to use

The player derives the API version from the path of the discovery URL, so use the URL exactly as listed for your platform, including the trailing `/`. The URL for V1 channels is different on Web than on the other platforms.

| API version | Web                                             | Android, iOS, Roku                              |
| ----------- | ----------------------------------------------- | ----------------------------------------------- |
| V2          | `https://discovery.theo.live/v2/distributions/` | `https://discovery.theo.live/v2/distributions/` |
| V1 (legacy) | `https://discovery.theo.live/`                  | `https://discovery.theo.live/v2/publications/`  |
| V3          | `https://discovery.theo.live/v3/`               | `https://discovery.theo.live/v3/`               |

React Native and Flutter apps pass the discovery URL to the underlying Web, Android or iOS SDK, so the same rules apply per platform.

> **Find the API version of your channel**
>
> Play your channel without a discovery URL and open the network tab of your browser (or a network proxy for a native app). The discovery request that returns `200` shows the discovery URL that serves your channel. For example, a request to `https://discovery.theo.live/v2/distributions/<your-channel-id>` means that your channel is served by V2.

## Configure the discovery URL

Create a `THEOliveConfiguration` with the discovery URL and add it to the player configuration with `setTHEOliveConfiguration`. For example, for a channel served by V2:

```swift
import THEOplayerSDK
import THEOplayerTHEOliveIntegration

let builder = THEOplayerConfigurationBuilder()
builder.license = "your-license"
builder.setTHEOliveConfiguration(
    THEOliveConfiguration(
        externalSessionId: nil,
        discoveryUrl: "https://discovery.theo.live/v2/distributions/"
    )
)
let player = THEOplayer(configuration: builder.build())
```

If your channels are served by different API versions, list the discovery URLs in the order you want the player to try them:

```swift
builder.setTHEOliveConfiguration(
    THEOliveConfiguration(
        externalSessionId: nil,
        discoveryUrls: [
            "https://discovery.theo.live/v2/distributions/",
            "https://discovery.theo.live/v2/publications/",
        ]
    )
)
```

The player derives the API version from the URL path:

* A URL that contains `/v3/` is a V3 discovery URL.
* A URL that contains `/v2/distributions/` is a V2 discovery URL.
* Any other URL, including `https://discovery.theo.live/v2/publications/`, is a V1 discovery URL.

Because of these rules, `https://discovery.theo.live/v2/` without `distributions/` is treated as a V1 discovery URL on iOS.

## Configuration reference

[`THEOliveConfiguration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/THEOlive/Structs/THEOliveConfiguration) has the following properties, which you set with its initializer.

| Property            | Type       | Description                                                                                                                             |
| ------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `externalSessionId` | `String?`  | An ID used to report usage analytics. If `nil`, a random UUID is used.                                                                  |
| `discoveryUrl`      | `String?`  | A discovery URL that the player tries before the built-in discovery URLs. Takes precedence over `discoveryUrls`. Defaults to `nil`.     |
| `discoveryUrls`     | `[String]` | A list of discovery URLs that the player tries in order, after `discoveryUrl` and before the built-in discovery URLs. Defaults to `[]`. |

The default discovery order V2, V1, V3 applies from THEOplayer 11.13.0. Earlier versions try V1 first.

---

# UI on iOS

Choose the approach that fits your requirements:

* Use Open Video UI when you want a custom experience without building common player components yourself.
* Use the chromeless player when you want to start with no UI and build every control and interaction from scratch.
* Use the basic default UI when its ready-made controls meet your needs and one is available.

| Approach      | Starting point                 | Flexibility | Development effort |
| ------------- | ------------------------------ | ----------- | ------------------ |
| Open Video UI | Ready-made, modular components | High        | Moderate           |
| Chromeless    | Player API without a UI        | Complete    | Highest            |
| Default UI    | Complete basic player UI       | Basic       | Lowest             |

Building a chromeless UI means using the OptiView Player API and your own application code without a ready-made UI. You are responsible for adding every control, such as a play button, and connecting it to the player API, such as `player.play()`. This approach gives you total control over the UI and UX, but requires an understanding of video playback and the OptiView Player API.

## Open Video UI

If you're building a React Native application, you can customize the player with [Open Video UI for React Native](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native/open-video-ui.md), a set of ready-made, open-source components which you can use as is or compose and style to match your application.

## Chromeless

For complete control, use the chromeless player and build every control and interaction with the native technologies and programming languages of the platform. The OptiView Player API exposes all the events and properties that you need to implement a custom design from scratch.

Refer to our article on [how to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/build-chromeless-ui.md) for more information.

## Default UI

As of THEOplayer 5, the iOS SDK no longer ships a default UI.

## Related articles

* [How to change how a video should fit inside a container](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/change-video-fit.md)

---

# Chromeless UI on iOS and tvOS

A chromeless player renders video without playback controls. Your application creates every control with native Apple UI technologies and connects each interaction to the OptiView Player API.

Choose this approach when you need complete control over the interface. Building from scratch requires an understanding of playback states, tracks, accessibility, errors, casting, presentation modes, and application lifecycle behavior.

Continue with [Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/build-chromeless-ui.md) to create a Player instance and connect it to your interface.

---

# Getting started with a chromeless UI on iOS and tvOS

Building a chromeless UI means building a brand-new video player UI from scratch. You achieve this by implementing your own custom UI components, and by associating those components with the appropriate THEOplayer API. The screenshot below visualizes such a chromeless UI -- albeit not the most pretty one.

![Chromeless UI Layout](/pr-932/assets/images/chromeless-ui-7-4025542f4b233096015b9e6ecce5bcd5.png "Chromeless UI Layout")

A chromeless UI gives you complete control over your full UI and UX, but it also means that you are responsible for implementing your full UI and UX. Achieving this feat requires you to have an adequate grasp on the video player architecture and its underlying API.

The goal of this guide is to advance your understanding on how to connect the dots between custom components and the THEOplayer API. For example, this guide will explain to which THEOplayer APIs you could map your custom play button.

## Create a chromeless player instance

The iOS and tvOS SDKs do not ship a default UI. A [`THEOplayer`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer) instance renders video, and your application adds native controls on top.

```swift
let config = THEOplayerConfiguration(license: "your_license_string")
let player = THEOplayer(configuration: config)
```

The following guides refer to this `player` variable.

## Track player states

Before adding controls, learn how to [track player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/player/track-player-states.md). Your UI should respond correctly when playback starts, pauses, buffers, ends, or encounters an error.

![Video Player States](/pr-932/assets/images/player-video-player-states-4f4f37f92d4b03a2c750ce7fe03d0a5a.png "Video Player States")

## Next steps

## [📄️Map UI components](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/chromeless/mapping-components.md)

[Connect native controls and displays to the appropriate Player APIs.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/chromeless/mapping-components.md)

## [📄️Add UX enhancements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/chromeless/ux-enhancements.md)

[Plan loading, poster, next-content, intro-skip, and advertising experiences.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/chromeless/ux-enhancements.md)

## [📄️Handle errors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/chromeless/error-handling.md)

[Make failures visible and actionable in your custom UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/ios/chromeless/error-handling.md)

---

# Mapping components in a chromeless UI on iOS and tvOS

A chromeless UI is made up of native controls and displays that must reflect player state and call the appropriate OptiView Player APIs. This guide maps common components to the APIs and supporting guides used to implement them.

![Chromeless UI Layout](/pr-932/assets/images/chromeless-ui-layout-3642d810cba7de946ee7cb69b7ab238b.png "Chromeless UI Layout")

## Play and pause

Show the appropriate control for the current state, as described in [tracking player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/player/track-player-states.md). Call [`play()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/c:@M@THEOplayerSDK@objc\(cs\)THEOplayer\(im\)play) or [`pause()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/c:@M@THEOplayerSDK@objc\(cs\)THEOplayer\(im\)pause) when the viewer selects it.

## Mute and volume

Use the Player's [`muted`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C5mutedSbvp) property for mute controls. Apple platforms delegate volume-level changes to hardware controls, so the application should not provide an independent software volume slider.

## Current time and duration

Use [`requestCurrentTime()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C18requestCurrentTime17completionHandleryySdSg_s5Error_pSgtc_tF) and [`setCurrentTime()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C14setCurrentTime_17completionHandlerySd_yypSg_s5Error_pSgtcSgtF) for the playback position. Use [`duration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C8durationSdSgvp) for duration.

For live streams, `duration` is `Infinity`. Use `currentProgramDateTime` when the interface needs an absolute program time.

## Scrub bar and buffered ranges

Only seek within the ranges exposed by `seekable`. Update the scrubber in response to [`TIME_UPDATE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Structs/PlayerEventTypes#/s:13THEOplayerSDK16PlayerEventTypesV11TIME_UPDATEAA0D4TypeCyAA010TimeUpdateD0CGvpZ), and represent downloaded portions using the Player's buffered ranges.

Display a loading state between seeking and seek completion when appropriate.

## Audio, subtitle, and quality selection

Use the platform guides to build track selectors:

* [Detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-audio-tracks.md)
* [Enable and disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/enable-disable-audio-tracks.md)
* [Detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-text-tracks.md)
* [Enable and disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/enable-disable-text-tracks.md)
* [Detect video-track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/detect-video-track-qualities.md)
* [Select a video-track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/select-video-track-quality.md)

## Fullscreen and picture-in-picture

Use `presentationMode` to switch between inline and fullscreen modes. Keep custom controls within the Player view hierarchy so they remain visible during presentation changes. Use `fullscreenOrientationCoupling` when fullscreen should follow device orientation.

You can also implement presentation handling independently when the application needs more control. Picture-in-picture availability and behavior depend on the target Apple platform; see the [picture-in-picture guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/picture-in-picture.md).

## Casting

Use the [Chromecast guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/introduction.md) and [AirPlay guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/airplay/introduction.md) to detect availability and start or stop casting sessions.

## Subtitle and advertisement overlays

You can use the SDK's subtitle rendering or [detect active text-track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/text-tracks/detect-active-text-track-cues.md) and render them yourself.

For advertising controls such as countdowns, skip buttons, and scrub-bar markers, subscribe to the relevant [ad events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/ads/subscribe-to-ad-events.md) and update your interface from their callbacks.

---

# How to change how a video should fit inside a container on iOS

You may want to alter how a video is sized inside the player's frame. By default, a video player respects the aspect ratio of the video. This means that black bars can appear on the sides of the player, or above and below the video, when its aspect ratio differs from the player's aspect ratio.

Instead, you may want the video to cover the entire player. Note that this either

* cuts off the content that falls outside of the player, or
* deforms the content, so it no longer matches its original aspect ratio.

## Implementation

Use the [`aspectRatio`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C11aspectRatioAA06AspectD0Ovp) property to change how the video is fitted inside the player, using one of the [`AspectRatio`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Enums/AspectRatio) values:

* `fit`: fit the video inside the player, preserving its aspect ratio. This is the default.
* `fill`: fill the player with the video, deforming the video if needed.
* `aspectFill`: fill the player with the video, preserving its aspect ratio and cropping the video if needed.

The snippet below demonstrates how you could use this API:

```swift
player.aspectRatio = .aspectFill
```

---

# UX enhancements for a chromeless UI on iOS and tvOS

A functional player still needs clear feedback and convenient interactions. Plan these experiences alongside the core playback controls:

1. **Loading spinner:** Indicate when the player is waiting for video data.
2. **Poster:** Show an image before initial playback and after the video ends.
3. **Up next:** Offer the next stream near the end of playback and optionally start it automatically.
4. **Skip intro:** Let viewers skip the current introduction.
5. **Ad countdown:** Display the remaining duration of an ad break.
6. **Ad markers:** Indicate ad-break positions on the scrub bar.

Drive each enhancement from Player events and state. Start with [tracking player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/player/track-player-states.md), then account for application lifecycle and presentation-mode transitions.

---

# Error handling in a chromeless UI on iOS and tvOS

A chromeless UI must present its own error state because the SDK does not render controls or viewer-facing error messages for you.

Decide how to present recoverable and terminal failures, whether viewers can retry, and which details should be retained for diagnostics. Clear loading indicators when an error occurs so the interface does not appear to buffer indefinitely.

See the [iOS and tvOS error-handling guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/miscellaneous/error/introduction.md) to detect Player errors and map them to messages and recovery actions.

---

# Connectors for THEOplayer iOS & tvOS SDK

## [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/comscore)

[Integrate with Comscore for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/comscore)

## [![](/pr-932/img/conviva.svg)![](/pr-932/img/conviva_dark.svg)Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/conviva)

[Integrate with Conviva for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/conviva)

## [Nielsen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/nielsen)

[Integrate with Nielsen for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/nielsen)

## [![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAy0SURBVHgB7d1PbhRJFsfxiLIxs+iW2DbuaZVvwNzASGB6iU+AOQGuHd2YwSVhYId9AsMJYNmYkewb2DdwafjjWXoBEvUvYzKqSMqmjV1ZlZnxIuL7kVpqoZaM6M5f53svMp5SAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAORwt3q8fpn8pAKXQSij78Ju5S7tKmXr6m1z/0vm0tbC3eawAFEZkABwurl6Zm/tpN/3NXRv9qm4lpt/89e2TFwpAIcQFwNkP/ykH7U5veWHvWUsBmIqoABjj4f/GaP2i0+42CQJgcmICIM/DP6JbSidbV99sbCoAuYkIgMke/pPoDwCTcB4A0z/8I5QFQD5OA6DIh/+k4diw95IgAM7nLADKevhHKAuAizgJgPIf/pN0q93pXudtAPi7ygOg2od/hP4A8HeVBoCrh/+E4/Rnb/6y87ipAFQXAAIe/hPoDwBWJQEg6+EfoSxA7EoPAKkP/ylab7bb3S2CALEpNQC8ePi/oSxAfEoNgPc31zZrWt1TXhkEwXIaBAcKCFxNlUhrc0V5x9Rrurb/4dbDbW4jQuhKDQCfaWNWLs/NHh4trT1SQKAIgAsYpdY/Lj08fH/zzxUFBIYAGMugLNj+uLT2irIAISEA8rltywL6AwgFATCBYX/g0i5lAXxHAEwsKwseHr67sbaoAA8RAFMz9Zma2qUsgI8IgIIwNoSPCICCMTaETwiAUnwbG+5TFkAyAqBc1xgbQjICoALZ2PDjrQerChCEAKiMqSujn9v+wIelP24rQAACoHJ23fnMK8oCSEAAOHJybGgvTlGAAwSAY3ZseHnu533GhnCBABBhdKyYsgBVIgBEMXXGhqgSASBQNjbkWDHKRgCIZeocK0bZCADxhv0BygKUgQDwRDY2/Hjr4XOCAEUhAHxjzCq3EaEoBICXRmPDNAg82LoEqQgAr7HEBNMhAALwtT+wz9gQeREA4bjC2BB5EQDBYYkJxkcAhIslJrgQARA4lpjgPARAFFhigrMRAFFhiQlOIwAixBITZAiAiDE2BAEQPZaYxIwAQIYlJhEiAHAKY8O4EAA4w2hsyBKTsBEAOAdLTEJHAOBCLDEJFwGAsbHEJDwEAHJiiUlICABMiCUmISAAMBWWmPiNAEABWGLiKwIABWKJiW8IABTu9NiQIJCMAEBphmNDjhVLRgCgZIwNJSMAUBHGhhIRAKgUS0xkIQDgAktMhCAA4BBLTFwjACABS0wcIQAgBrcRVY8AgDCjsWEaBNcUSkUAQKhBEOxTFpSLAIBoLDEpFwEALzA2LAcBAI8M+wNHN9d2KQuKQQDAO0arRcaGxSAA4C3GhtMjAOA5lphMgwBAIFhiMgkCAEFhiUk+pQaASdSBAhxgicl4tCrZ0e/36yaZ2U1/VF0Bbhy0O73lhb1nLYVTSg+AjE3imtaPCAK4YrR+0Wl3mwTBSGUBYB0url+Zm+utpj+UY51wRLeUTrauvtnYVKg2ADK2LEiSmXWt9B0FOKFbiek3f3375IWKmJMAyLy7sbY4UzPblAVwJfaywGkAZOgPwLX0QVj/0um9jC0IRASAZcuCfn92tabVPQU4EV9ZICYAMvQH4J5utTvd6zG8DYgLgAxlAVyLoT8gNgAyBAEcO04fks1fdh43VYDEB4BFWQD3wuwPeBEAmeGx4tnn6d/y2Sdced3u9BqhlAVeBUCGsgDOab3Zbne3fA8CLwMg82FpLS0LzB2CAG74XxZ4HQAW/QG4NwiC5TQIvPv83fsAyHztD7xK/5ZtMnDCx7FhMAGQoT8A1+yxYl/GhsEFQGbYHxgcK+ZaKDjgR38g2ACw6A/ANW3U3pdu767UsiDoAMhwLRlck9ofiCIAMvQH4Ja8siCqALC4lgzu6ZZRvcb8ztPXyrHoAiBDfwCuSSgLog2ATFoWXEvLgleUBXDF5dgw+gDI0B+AW276AwTACcOyYHaF/gAcqnSJCQFwBvoDcK2q/gDLQc/wy1/PWvM7Gyumr5bTfxUtBVRssOT08kzp917wBjAG+gOolFF77Zne3YW/yi8DCIAxURagfKbVT/Tdf/7n8Z6qCAGQE0GAEhwbpbY6nU+bC3ubx6pCBMCEKAtQBKNN2uz73Kj6wc8QAFN6f+PBaq1mPzvWdQWMK63z+0Y1q3zdPwsBUADKAuRwnLb4m1LWkxMABRp8dtyf3U7/VBcV8J20zm+6qPPPQwCUgP4ATqlwrJcXAVAiriWLXfVjvbwIgJLRH4jSYKw3v/N4XQkXVAC8u7G2OKvVo6SmW9KuX+La8ji4HuvlFUQAHC3er6vLlx4ZY1ZO/rrE65npDwRKyFgvL68D4HBx9co/5n66l75uraof1tkyr2f+2h/gs2P/HScmafi6HszbAPjv0h+3Z5XdFGzq4/zzEq9npj/gN4ljvby8C4CszjcTztolXs/MtWSeETzWy8ubALCv+5fnfk5fmc2qmppuKZ1sSTmNlaE/IJ38sV5eXgTA0dLao/Pr/EnJ6w9wbblI3oz18hIdAPZ1f6amt8et8yclsSygPyBDYtRWt/tp3ec6/zwiA2Aw1rs0u22qPlOv9Wa73d2SFATDEDTblAUV83Ssl5eoACi2zp+UzLEh/YHKeD3Wy0tMAPzv5r/vJTpZV2LOzeu04WNENXxsWdDvz67W9OD7AhTL2a08LjkPAPuKW6up51roEVn6AxEIaKyXl7MAcFbnT8geK/7S+bQl6f8OlAXTCm+sl1flATDe8V2p6A8EItixXl6VBsDwP9Tac+X99/G61e50r1MW+Cf0sV5elQTAtMd3pZLaHzCJ/UZClb5VxiuRjPXyKjUAfvSZbmCO0z/ETT47lsqkZZsRV7ZJUWoAfFh68CKeV1Kh/YF4ry2PcqyXFwFQvNftTq9Bf8ChiMd6eREAJRHbHwj62nLGenmxHrwkg/XOc5d2bS2uhLBrz6++fXw9McndwNae22Ubjas7Gws8/PnwBlAJ3TKq15jfefpaCRLCteWM9aZDAFSIY8UFYqxXCALAgeGx4t5LeecHZnblTwtMq6eSxm/C3qZ8RQ/AgXQ8tS6yP5DW0IL7A3as12x3Pv+Lh784vAE4Nzg/sPzr2ycHShBR15Yz1isNbwDOmXpN1/Y/3Hq4fWhPTgphP5TRtd6CUealciT92Qf9RF23kwse/nLwBiCM0G1GVV9bbsd6TWm3NoeINwBhbH/g49LDQ0n9AVueVNUfsGO9dufTAg9/NXgDkO2g3ektyxsbzq4U3h9grOcEAeCBsM8PMNZziRLAA9mx4o+3Hji8Lfk0Ozac39lYMX21PGFZwFhPAN4AvBPEtWSv27Veg86+ewSAp6SWBeddW27HekmiG9T5chAAvhO4zeiM/gBjPaEIgCDILQu0rtW5lUcuAiAo8rYZQTamAEEx9Zma2pV2rBhyEQABGo4NZw+PltYe2UUsCvgBAiBgw8+Of96XdKwYshAAwRt8bbhtvy+gLMD3CIBomLotC+gP4CQCIDJf+wP7tj+gED0CIE5XJH52jOoRAFEb9geObq7tUhbEiQCAslub6Q/EiQDAN9lnx4e/EwKxIAAwYtSevaGYz3TjMasAlmpGiwCIm72VZ6vT+czXepEiAOLFrTwgAKLD7bs4gQCIx/BWnh1u5cEIARABu2yj2/20Tp2P7xEAIWOpJi5AAASJsR7GQwCEhbEeciEAAmG0edFpf27w4CMPAsB338Z6G3sKyIkA8NdxYpKGtF0A8AsB4CG7VJNlGygCAeATxnooGAHgBcZ6KAcBINtgrDe/s7GugBIQAEJxfBdVIACk4Ws9VIgAkIOxHipHALj39fguYz1UjwBwibEeHCMAnGCsBxkIgGoNb+V5w608kIEAqAhjPUhEAJSNsR4EIwBKY1o9lTR+e/v0tQKEIgCKx6088AYBUCyWbcArBEABjDIHSaIb1PnwDQEwncFYb56xHjxFAEyIsR5CQADklY71EjX4aOdAAZ4jAMbG8V2EhwC4GGM9BIsAOMdg2YbuNxnrIVQEwFlYtoFIlBoAxpg9rfUd5Y/h13o7jPUQB61K9v7mnys1XdtWwrFsAzEqPQAs0SHArTyIWCUBYMkLAcZ6QGUBYAkJAS7hBL6qNAAslyEwGOu1Pzd48IGhygPAqjwEuJUHOJOTALAqCgGWbQDncBYAVpkhwFgPuJjTALAKDwHGesDYnAeAVUwIMNYD8hIRANYUITAY683vPF5XAHIREwBW3hDgVh5gOqICwBorBBjrAYUQFwDWj0PAtBJjmoz1gGKIDADruxDg+C5QArEBYA1CQNXuMNYDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABALP4PxPhKst9YjwYAAAAASUVORK5CYII=)Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/yospace)

[Integrate with Yospace for server-side ad insertion (SSAI).](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/yospace)

## [💬Sideloaded Subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/sideloaded-texttracks)

[Add support for sideloaded subtitles to your player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/sideloaded-texttracks)

## [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk)

[Add support for Uplynk CMS to your player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/changelog.md)

[Find out what's new.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/changelog.md)

---

# THEOPlayer 🤝 Comscore

THEOplayer-Connector-Comscore provides an integration between the THEOplayerSDK and ComScore.

## Installation

### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add links to the registry of Cocoapods: `source 'https://cdn.cocoapods.org/'`. If this fails, bypass their CDN by using `source 'https://github.com/CocoaPods/Specs.git'`
3. To your Podfile, add the connector pods that you want to use in your app: `pod 'THEOplayer-Connector-Comscore'`
4. Install the pods using `pod install` , then open your `.xcworkspace` file to see the project in Xcode.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.
2. Use a [local override](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine) of the `THEOplayerSDK-basic` pod by adding the following line to your projects Podfile: `pod 'THEOplayerSDK-basic', :path => 'iOS-Connector/Helpers/TheoPod'` and make sure the path points to the [TheoPod folder](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoPod).

## Usage

Import the `THEOplayerConnectorComscore` module

```swift
import THEOplayerConnectorComscore
```

Create a ComScoreConfiguration that contains your publisherId (also referred to as customer or c2 id), app name, an indication of whether the user has granted his/her consent for tracking, an adIdProcessor (if you want to extract and manipulate ad id's that will be reported to ComScore, by default we use THEOplayerSDK.Ad.id) and a debugging flag (for extra logging) :

```swift
let configuration = ComScoreConfiguration(
    publisherId: "<your id>",
    applicationName: "<your application name>",
    usagePropertiesAutoUpdateMode: .foregroundOnly,
    userConsent: .granted,
    adIdProcessor: nil,
    debug: true
)
```

Create a `ComscoreConnector` that uses this `configuration`, your `THEOplayer` instance and a valid `ComScoreMetadata` instance for the first content you will load to the player. You can change the metadata dynamically later on if necessary:

```swift
let connector = ComscoreConnector(
    configuration: configuration,
    player: yourTHEOplayer,
    metadata: ComScoreMetadata(
        mediaType: .shortFormOnDemand,
        uniqueId: "0123ABC",
        length: 596,
        stationTitle: "THEO TV",
        programTitle: "Big Buck Bunny",
        episodeTitle: "Example Title",
        genreName: "animation",
        classifyAsAudioStream: false)
)
```

Note that if you are using Google IMA connector, you must make sure it's registered before you initialize the `ComscoreConnector`. Otherwise it will fail to hook into the ad related events.

## Which metadata do I need to provide?

### ComscoreMetadata fields

Based on the `ComScoreMetadata` constructor, you can tell which fields are mandatory and which aren't. Note that this is purely for the integration to work correctly. Depending on the Comscore solution you are using, different fields are required/optional. The mandatory fields in the `ComScoreMetadata` type are the ones that are mandatory for all three Comscore solutions:

* Video Metrix (V)
* Cross Platform Product Suite (X)
* Cross Media Audience Measurement (C)

| Property                           | Required | Optional |
| ---------------------------------- | -------- | -------- |
| `mediaType`                        | All      |          |
| `uniqueId`                         | All      |          |
| `length`                           | All      |          |
| `c3?`                              | V        |          |
| `c4?`                              | V        |          |
| `c6?`                              | V        |          |
| `stationTitle`                     | All      |          |
| `stationCode?`                     |          | All      |
| `networkAffiliate?`                |          | All      |
| `publisherName?`                   | X C      | V        |
| `programTitle`                     | All      |          |
| `programId?`                       |          | V C      |
| `episodeTitle`                     | All      |          |
| `episodeId?`                       |          | X C      |
| `episodeSeasonNumber?`             | X C      |          |
| `episodeNumber?`                   | X C      |          |
| `genreName`                        | All      |          |
| `genreId?`                         |          | All      |
| `carryTvAdvertisementLoad?`        | X        |          |
| `classifyAsCompleteEpisode?`       | X        |          |
| `dateOfProduction?`                |          | C        |
| `timeOfProduction?`                |          | C        |
| `dateOfTvAiring?`                  | X C      |          |
| `timeOfTvAiring?`                  |          | X C      |
| `dateOfDigitalAiring?`             | X C      |          |
| `timeOfDigitalAiring?`             |          | X C      |
| `feedType?`                        | X        |          |
| `classifyAsAudioStream`            | Al       |          |
| `deliveryMode?`                    |          | All      |
| `deliverySubscriptionType?`        |          | All      |
| `deliveryComposition?`             |          | All      |
| `deliveryAdvertisementCapability?` |          | All      |
| `mediaFormat?`                     |          | All      |
| `distributionModel?`               |          | All      |
| `playlistTitle?`                   |          | C        |
| `totalSegments?`                   |          | V C      |
| `clipUrl?`                         |          | V C      |
| `videoDimension?`                  |          | C        |
| `customLabels?`                    |          | All      |

---

# THEOPlayer 🤝 Comscore Samples

We provide source code of two sample applications that illustrate how to use the connector with different package managers:

* [Sample using **Cocoapods**](https://github.com/THEOplayer/iOS-Connector/blob/-/Code/Comscore-Examples/Cocoapod) (requires Cocoapods installation through terminal)

---

# THEOPlayer 🤝 Conviva

THEOplayer-Connector-Conviva for iOS provides an integration between the THEOplayerSDK and ConvivaSDK. It connects to the Conviva backend and reports events fired from THEOplayer instances.

For example xcode projects with this connector see [Conviva-Examples](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/conviva/examples.md).

## Installation

### [Swift Package Manager](https://swift.org/package-manager/)

1. In Xcode, install the Conviva libraries by navigating to **File > Add Packages**
2. In the prompt that appears, select the iOS-Connector GitHub repository: `https://github.com/THEOplayer/iOS-Connector`
3. Select the version you want to use.
4. Choose the Connector libraries you want to include in your app.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.

2. Use a [local override](https://developer.apple.com/documentation/xcode/editing-a-package-dependency-as-a-local-package) of the `theoplayer-sdk-ios` package by selecting the folder `../../Helpers/TheoSPM/theoplayer-sdk-ios` in Finder and dragging it into the Project navigator of your Xcode project.

3. Place your custom THEOplayerSDK.xcframework at `../../Helpers/TheoSPM/theoplayer-sdk-ios/THEOplayerSDK.xcframework`. (It is also possible to place your xcframework somewhere else. In that case make sure to update the [Package.swift](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoSPM/theoplayer-sdk-ios/Package.swift) manifest inside the your local override so that it points to your custom THEOplayer build)

4. If Xcode complains about a missing xcframework

   1. Choose `File` > `Packages` > `Reset Package Caches` from the menu bar.
   2. If it is still not working, make sure to remove any `THEOplayerSDK.xcframework` inclusions that you manually installed before installing this THEOplayer-Connector-Conviva package.

### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add the Conviva connector pods that you want to use in your app: `pod 'THEOplayer-Connector-Conviva'`
   * When using THEOads, also add the THEOads subspec so that failed THEOads ad breaks (e.g. an empty VAST response) are reported to Conviva: `pod 'THEOplayer-Connector-Conviva/THEOads'`
3. Install the pods using `pod install` , then open your `.xcworkspace` file to see the project in Xcode.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.
2. Use a [local override](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine) of the `THEOplayerSDK-basic` pod by adding the following line to your projects Podfile: `pod 'THEOplayerSDK-basic', :path => 'iOS-Connector/Helpers/TheoPod'` and make sure the path points to the [TheoPod folder](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoPod).

## Usage

Import the `THEOplayerConnectorConviva` module

```swift
import THEOplayerConnectorConviva
```

Create a `ConvivaConfiguration` that contains the info on how to connect to your conviva endpoint:

```swift
let configuration = ConvivaConfiguration(
    customerKey: "put your customer key here",
    gatewayURL: " put your  gateway URL here ",
    logLevel: .LOGLEVEL_FUNC
)
```

Create a `ConvivaConnector` that uses this `configuration` and your `THEOplayer` instance:

```swift
let connector = ConvivaConnector(
    configuration: configuration,
    player: yourTHEOplayer
)
```

For each asset you play, the **asset name** needs to be reported to Conviva which you can do by providing the asset name as a `title` field inside your `SourceDescription's metadata`:

```swift
let mySource = SourceDescription(source: source, metadata: MetadataDescription(metadataKeys: ["title": "your_asset_name"]))
```

Alternatively, the **asset name** can be provided as contentInfo (`CIS_SSDK_METADATA_ASSET_NAME`) using the setContentInfo method, along with other metadata. For example to report the **viewer's ID**:

```swift
let contentInfo = [ 
   CIS_SSDK_METADATA_VIEWER_ID: "your_viewer_id"
]
connector.setContentInfo(contentInfo)
```

**Important note**: setting a new source on the player will reset previously set contentInfo. Make sure to use the `setContentInfo` method after receiving the SOURCE\_CHANGE event.

## Lifecycle

Hold a reference to your connector. Once the connector is released from memory it will clean up itself and stop reporting to Conviva.

---

# THEOPlayer 🤝 Conviva Samples

We provide source code of two sample applications that illustrate how to use the connector with different package managers:

* [Sample using **Swift Package Manager**](https://github.com/THEOplayer/iOS-Connector/blob/-/Code/Conviva-Examples/SPM) (works out of the box with Xcode 12 and above)

* [Sample using **Cocoapods**](https://github.com/THEOplayer/iOS-Connector/blob/-/Code/Conviva-Examples/Cocoapod) (requires Cocoapods installation through terminal)

---

# THEOPlayer 🤝 Nielsen

THEOplayer-Connector-Nielsen provides an integration between the THEOplayerSDK and NielsenAppSDK & NielsenTVOSAppSDK. It connects to the Nielsen backend and reports events fired from THEOplayer instances.

## Installation

### [Swift Package Manager](https://swift.org/package-manager/)

1. In Xcode, install the Nielsen connector by navigating to **File > Add Packages**
2. In the prompt that appears, select the iOS-Connector GitHub repository: `https://github.com/THEOplayer/iOS-Connector`
3. Select the version you want to use.
4. Choose the Connector libraries you want to include in your app.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.

2. Use a [local override](https://developer.apple.com/documentation/xcode/editing-a-package-dependency-as-a-local-package) of the `theoplayer-sdk-ios` package by selecting the folder `../../Helpers/TheoSPM/theoplayer-sdk-ios` in Finder and dragging it into the Project navigator of your Xcode project.

3. Place your custom THEOplayerSDK.xcframework at `../../Helpers/TheoSPM/theoplayer-sdk-ios/THEOplayerSDK.xcframework`. (It is also possible to place your xcframework somewhere else. In that case make sure to update the [Package.swift](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoSPM/theoplayer-sdk-ios/Package.swift) manifest inside the your local override so that it points to your custom THEOplayer build)

4. If Xcode complains about a missing xcframework

   1. Choose `File` > `Packages` > `Reset Package Caches` from the menu bar.
   2. If it is still not working, make sure to remove any `THEOplayerSDK.xcframework` inclusions that you manually installed before installing this connector package.

### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add links to the registries of Cocoapods and Nielsen: `source 'https://cdn.cocoapods.org/'` and `source 'https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-specs-dynamic.git'`
3. To your Podfile, add the connector pods that you want to use in your app: `pod 'THEOplayer-Connector-Nielsen'`
4. Install the pods using `pod install` , then open your `.xcworkspace` file to see the project in Xcode.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.
2. Use a [local override](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine) of the `THEOplayerSDK-basic` pod by adding the following line to your projects Podfile: `pod 'THEOplayerSDK-basic', :path => 'iOS-Connector/Helpers/TheoPod'` and make sure the path points to the [TheoPod folder](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoPod).

## Usage

Import the `THEOplayerConnectorNielsen` module

```swift
import THEOplayerConnectorNielsen
```

Create a Dictionary that contains the info on how to connect to your Nielsen endpoint:

```swift
let configuration = [
  "appid": "XXYnnnnnn-XnnX-nXXn-nXnn-XnnnnXnnnXnX",
  "appversion": "n.n",
  "appname": "Theo Nielsen Sample App",
  "nol_devDebug": "DEBUG"
]
```

Create a `NielsenConnector` that uses this `configuration` and your `THEOplayer` instance:

```swift
let connector = NielsenConnector(
    configuration: configuration,
    player: yourTHEOplayer
)
```

Hold a reference to your connector. Once the connector is released from memory it will clean up itself and stop reporting to Nielsen.

## What events does this connector report to Nielsen?

### Basic playback events

| THEOplayer event                    | NielsenAppApi report func       |
| ----------------------------------- | ------------------------------- |
| PlayerEventTypes.LOADED\_META\_DATA | loadMetadata(\_ metadata: Any?) |
| PlayerEventTypes.PAUSE              | stop()                          |
| PlayerEventTypes.SOURCE\_CHANGE     | end()                           |
| PlayerEventTypes.ENDED              | end()                           |
| PlayerEventTypes.DESTROY            | end()                           |
| TextTrackEventTypes.ENTER\_CUE      | sendID3(\_ data: String)        |

---

# THEOPlayer 🤝 Yospace

THEOplayer-Connector-Yospace provides an integration between the THEOplayerSDK and Yospace to allow playback of server-side ad inserted streams.

## Installation

### [Swift Package Manager](https://swift.org/package-manager/)

1. In Xcode, install the Yospace connector by navigating to **File > Add Packages**
2. In the prompt that appears, select the iOS-Connector GitHub repository: `https://github.com/THEOplayer/iOS-Connector`
3. Select the version you want to use.
4. Choose the Connector libraries you want to include in your app.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.

2. Use a [local override](https://developer.apple.com/documentation/xcode/editing-a-package-dependency-as-a-local-package) of the `theoplayer-sdk-ios` package by selecting the folder `../../Helpers/TheoSPM/theoplayer-sdk-ios` in Finder and dragging it into the Project navigator of your Xcode project.

3. Place your custom THEOplayerSDK.xcframework at `../../Helpers/TheoSPM/theoplayer-sdk-ios/THEOplayerSDK.xcframework`. (It is also possible to place your xcframework somewhere else. In that case make sure to update the [Package.swift](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoSPM/theoplayer-sdk-ios/Package.swift) manifest inside the your local override so that it points to your custom THEOplayer build)

4. If Xcode complains about a missing xcframework

   1. Choose `File` > `Packages` > `Reset Package Caches` from the menu bar.
   2. If it is still not working, make sure to remove any `THEOplayerSDK.xcframework` inclusions that you manually installed before installing this connector package.

### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add the Yospace connector pod that you want to use in your app: `pod 'THEOplayer-Connector-Yospace'`
3. Add the following post-install hook in your Podfile:

```ruby
post_install do |installer|
    custom_framework_path = "#{installer.sandbox.root}/YOAdManagement-Release/YOAdManagement.xcframework"

    installer.pods_project.targets.each do |target|
      if target.name == 'THEOplayer-Connector-Yospace'
        framework_build_phase = target.frameworks_build_phase
        file_ref = installer.pods_project.new_file(custom_framework_path)

        framework_build_phase.add_file_reference(file_ref)
      end
    end
end
```

Check the Dependencies section below to get information on how to obtain the `YOAdManagement.xcframework` as a pod. 4. Install the pods using `pod install` , then open your `.xcworkspace` file to see the project in Xcode.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.
2. Use a [local override](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine) of the `THEOplayerSDK-basic` pod by adding the following line to your projects Podfile: `pod 'THEOplayerSDK-basic', :path => 'iOS-Connector/Helpers/TheoPod'` and make sure the path points to the [TheoPod folder](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoPod).

## Dependencies

The THEOPlayer Yospace connector has two dependency frameworks: THEOplayerSDK and YOAdManagement.

THEOplayerSDK is added as a dependency on both Cocoapods and SPM and will be fetched by each dependency manager. YOAdManagement is published as a private pod hosted on Artifactory by jfrog. In order to get the framework you will need to:

1. Setup a Yospace developer account at <https://www.yospace.com/developer>
2. Login to the Yospace Apple docs at <https://docs.yospace.com/library/technical/sdks/en/ad-management-sdks-v3/apple.html>
3. Follow the instructions to setup the artifactory, authenticate, and fetch the framework at <https://docs.yospace.com/library/technical/sdk-api/ad-management/apple/previous/index.html>

## Usage

Import the `THEOplayerConnectorYospace` module

```swift
import THEOplayerConnectorYospace
```

Create a `SourceDescription` that defines the Yospace stream:

```swift
let streamType: YospaceStreamType = .live
let typedSource: TypedSource = .init(
    src: "yospace_live_stream_url",
    type: "application/x-mpegurl",
    ssai: YospaceServerSideAdInsertionConfiguration(streamType: streamType)
)
let source: SourceDescription = SourceDescription(source: typedSource)
```

Create a `YospaceConnector` that uses a `THEOplayer` instance:

```swift
let theoplayer: THEOplayer = .init()
let connector: YospaceConnector = .init(player: theoplayer)
```

**Note:** Hold a reference to your connector instance by storing it as a property. Keeping it inline will get it auto-released from memory. Once the connector is released from memory it will reset and unload autonomously.

Set the source and play. There are 2 ways to set a Yospace source:

1. Through the API provided by the YospaceConnector:

```swift
connector.setupYospaceSession(sourceDescription: source)
```

The connector will then fire a `SESSION_AVAILABLE` event once the setup is successful. The client can track this event to start playback:

```swift
_ = connector.addEventListener(type: YospaceEventTypes.SESSION_AVAILABLE, listener: { event in
    theoplayer.play()
})
```

When using the `setupYospaceSession` API, the connector will throw an error in case the `TypedSource` is not of type `YospaceServerSideAdInsertionConfiguration`.

2. Through the player:

```swift
theoplayer.source = source
theoplayer.play()
```

---

# THEOplayer ❤️ Sideloaded Subtitles

THEOplayer-Connector-SideloadedSubtitle brings sideloaded subtitle support to iOS SDK.

By using an experimental API from THEOplayer, this library aims to achieve sideloaded text track support across all Apple devices and all media playback scenarios.

The presented technique is superior to any other similar options as it brings sideloading support to AirPlay, Picture-in-Picture and DRM playback (and their combinations) and is out-of-the-box compatible with the `TextTrackStyling` API from THEOplayer.

This connector is intended to be used for subtitle text tracks specific with the `kind` `.subtitles`. For `.metadata` text tracks, such as WebVTT thumbnails, starting from v7.10 the iOS SDK handles the sideloading without the help of this connector.

## Installation

### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add links to the registry of Cocoapods: `source 'https://cdn.cocoapods.org/'`. If this fails, bypass their CDN by using `source 'https://github.com/CocoaPods/Specs.git'`
3. To your Podfile, add the connector pods that you want to use in your app: `pod 'THEOplayer-Connector-SideloadedSubtitle'`
4. Install the pods using `pod install`, then open your `.xcworkspace` file to see the project in Xcode.

## Usage

Import the `THEOplayerConnectorSideloadedSubtitle` module.

```swift
import THEOplayerConnectorSideloadedSubtitle
```

After importing the module, a new API will be available on the THEOplayer instance called `setSourceWithSubtitles(source: SourceDescription?)`

If you use this method to set a source, the player will be able to present sideloaded subtitles via the `TextTrackDescription` configured with your `SourceDescription`, e.g.:

```swift
public static var sourceWithSideloadedTextTrack : SourceDescription {
    let typedSource = TypedSource(src: "https://sourceURL.com/manifest.m3u8, type: "application/x-mpegurl")
    let textTrack = TextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
    return SourceDescription(source : typedSource, textTracks :[textTrack])
}
```

```swift
theoplayer.setSourceWithSubtitles(source: sourceWithSideloadedTextTrack)
```

**NOTE:** Replace every `theoplayer.source = newSource` call with `theoplayer.setSourceWithSubtitles(source: newSource)` in your application if you intend to use (at least once) subtitle sideloading. Even if you don't have sideloaded subtitles on some of your sources. **Combining both approaches could lead to unexpected behavior.**

## Limitations

1. THEOplayer-Connector-SideloadedSubtitle relies on an experimental API from the player which is subject to change. **Always use compatible player and connector versions.** Any major version of the connector is intended to be compatible with any player version within the same major version (e.g. connector 11.0.3 is compatible with player 11.5.0).
2. **Supported formats are: iOS-compatible WebVTT subtitles and SRT** via this connector today.
3. The presented **label within THEOplayer is auto-generated by the operating system** based on the language code and **the configured label will be disregarded**. (e.g. "eng" -> "English" (if the device language is English; "eng" -> "Engels", if the device language is Dutch). If an invalid language code is specified, the system will use that one as label. (e.g. "MyCustomLanguageCode" -> "MyCustomLanguageCode")
4. The `isDefault: true` setting will be not taken into account on sideloaded text tracks as it could lead to invalid source (if the stream already contains default subtitles). Enabling the desired sideloaded subtitle can be achieved via `ADD_TRACK` listener.

```swift
theoplayer.textTracks.addEventListener(type: TextTrackListEventTypes.ADD_TRACK) { ev in
    var texttrack = ev.track as! TextTrack
    if texttrack.language == "sideloaded_language_code" {
        tt.mode = .showing
    }
}
```

5. Loading thumbnail metadata through sideloaded WebVTT subtitles is not supported.
6. HTTP range requests for HLS playlists are ignored. The connector removes `Range` and `If-Range` headers because it requires complete playlist data. Media segment range requests are unaffected.

## Setting a time offset

It is possible to shift the presentation of the cues by using the extended `SSTextTrackDescription` class instead of `TextTrackDescription`. It will provide an additional property `vttTimestamp` which allows to specify a [X-TIMESTAMP-MAP](https://datatracker.ietf.org/doc/html/draft-pantos-http-live-streaming-22#section-3.5).

The `X-TIMESTAMP-MAP` is optional and can be omitted from the WebVTT file and in general, it is not required. It is **only necessary if you use a WebVTT file inside an HLS subtitle rendition** and you try to achieve subtitle synchronization. And this is exactly the way how this connector operates.

The APIs below provide a way of adding or modifying the timestamp in case it is required by **mapping the PTS** (e.g. from a video rendition) **to a local time within the WebVTT** file.

When converting different formats to WebVTT, this module does not add the timestamp by default.

The API usage remains mostly the same, with the exception of adding the timestamp:

```swift
public static var sourceWithSideloadedTextTrack : SourceDescription {
    let typedSource = TypedSource(src: "https://sourceURL.com/manifest.m3u8, type: "application/x-mpegurl")
    let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
    textTrack.vttTimestamp = .init(pts: "900000", localTime: "00:00:00.000")
    return SourceDescription(source : typedSource, textTracks :[textTrack])
}
```

```swift
theoplayer.setSourceWithSubtitles(source: sourceWithSideloadedTextTrack)
```

If the source WebVTT file specified in the `SSTextTrackDescription` already contains the `X-TIMESTAMP-MAP` timestamp, then it can be accessed by using the `extractSourceTimestamp` method:

```swift
let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
textTrack.extractSourceTimestamp { timestamp, error in
    print(timestamp.pts, timestamp.localTime)   // outputs the values from "https://sideloadedurl.com/subtitle.vtt"
}
```

**Note:** The `extractSourceTimestamp` method does not set the `vttTimestamp` property, but only reads the timestamp value from the source. You will need this if you want to modify the timestamp according to the initial values.

### More examples:

A sample WEBVTT file:

```text
WEBVTT

1
00:00:11.000 --> 00:00:12.000
- Never drink liquid nitrogen.

2
00:00:13.000 --> 00:15:00.000
- It will perforate your stomach.
- You could die.
```

Using the sample file mentioned above, if your PTS is `900000` in the video rendition, then mapping `900000` to `00:00:00.000` will show the first subtitle cue exactly when you would expect it, at 11 seconds in the movie.

```swift
let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
textTrack.vttTimestamp = .init(pts: "900000", localTime: "00:00:00.000")
```

#### (Experimental) Shifting the presentation of the cues forward (later) by 5 seconds.

You can achieve this by adding values to the first digit of the PTS timestamp with `localTime` set to `0`:

```swift
let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
// we assume here that the PTS in the video rendition is 900000, so 900000 + 500000 = 1400000
textTrack.vttTimestamp = .init(pts: "1400000", localTime: "00:00:00.000")
```

The timestamp is relative to the `localTime`, so the following settings will cancel each other out:

```swift
let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
textTrack.vttTimestamp = .init(pts: "1400000", localTime: "00:00:05.000")
```

#### (Experimental) Shifting the presentation of the cues backwards (earlier) by 5 seconds.

You can achieve this by subtracting values to the first digit of the PTS timestamp with `localTime` set to `0`:

```swift
let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
// we assume here that the PTS in the video rendition is 900000, so 900000 - 500000 = 400000
textTrack.vttTimestamp = .init(pts: "400000", localTime: "00:00:00.000")
```

or set the `localTime` to 5 seconds while keeping the timestamp value the same:

```swift
let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
// we assume here that the PTS in the video rendition is 900000
textTrack.vttTimestamp = .init(pts: "900000", localTime: "00:00:05.000")
```

**Note:** Every 100000 of PTS timestamp results in roughly 1 second in time mapping. Use this carefully as it is not officially documented.

#### Warnings

1. You should always use HLS subtitle rendition-compliant WebVTT files which are in sync with your streams and you should not be using the time-shifting functionality.
2. Shifting cues backwards is only possible until the timestamp of the first cue (e.g. if your first cue has to be rendered at 10 sec, you should not shift the subtitle by 15 sec).
3. Shifting forward is possible, but considered as hack, and it is not a specification-compliant manifest entry. Use it at your own risk!

## Automatic synchronization

In case the presentation timestamp is not known, or it cannot be obtained, the `automaticTimestampSyncEnabled` property can be enabled to estimate the value of the PTS and automatically set the `X-TIMESTAMP-MAP` in the WebVTT file. This property is defined on the class `SSTextTrackDescription`. Since the value is calculated retrospectively, it will cause a re-toggle of the enabled text track. This might cause a brief flash when a cue is present while the syncing takes effect.

## Caching

The caching feature of this connector allows you to download a source alongside a sideloaded subtitle to store it locally on the device and play it offline. To make this happen, the connector provides an API extension.

All that is needed is a source with a text track description:

```swift
public static var sourceWithSideloadedTextTrack: SourceDescription {
    let typedSource = TypedSource(src: "https://sourceURL.com/manifest.m3u8, type: "application/x-mpegurl")
    let textTrack = TextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: true, kind: .subtitles, label: "Label", format: .WebVTT)
    return SourceDescription(source: typedSource, textTracks: [textTrack])
}
```

and to call the aforementioned API which creates a new caching task, and finally calling the start method:

```swift
let parameters = CachingParameters(expirationDate: .distantFuture)
let task = THEOplayer.cache.createTaskWithSubtitles(source: sourceWithSideloadedTextTrack, parameters: parameters)
task?.start()
```

For more information on how to implement offline playback with caching, please refer [to our guide](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Offline-Playback/Guides/howto-offline-stream-caching).

### Limitations

1. Caching is only available on iOS.

---

# THEOplayer 🤝 Uplynk

THEOplayer-Connector-Uplynk for iOS provides an integration between the THEOplayerSDK and the Uplynk CMS. It allows the `THEOplayerSDK` to playback uplynk sources.

For example xcode projects with this connector see [Uplynk-Examples](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/examples.md).

## Installation

### [Swift Package Manager](https://swift.org/package-manager/)

1. In Xcode, install the THEOplayer iOS-Connector package by navigating to **File > Add Packages**
2. In the prompt that appears, select the iOS-Connector GitHub repository: `https://github.com/THEOplayer/iOS-Connector`
3. Select the version you want to use.

> the Uplynk connector is available for versions >= 8.11 only.

4. Choose the Connector libraries you want to include in your app.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.

2. Use a [local override](https://developer.apple.com/documentation/xcode/editing-a-package-dependency-as-a-local-package) of the `theoplayer-sdk-ios` package by selecting the folder `../../Helpers/TheoSPM/theoplayer-sdk-ios` in Finder and dragging it into the Project navigator of your Xcode project.

3. Place your custom THEOplayerSDK.xcframework at `../../Helpers/TheoSPM/theoplayer-sdk-ios/THEOplayerSDK.xcframework`. (It is also possible to place your xcframework somewhere else. In that case make sure to update the [Package.swift](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoSPM/theoplayer-sdk-ios/Package.swift) manifest inside the your local override so that it points to your custom THEOplayer build)

4. If Xcode complains about a missing xcframework

   1. Choose `File` > `Packages` > `Reset Package Caches` from the menu bar.
   2. If it is still not working, make sure to remove any `THEOplayerSDK.xcframework` inclusions that you manually installed before installing this THEOplayer-Connector-Uplynk package.

### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add the Uplynk connector pods that you want to use in your app: `pod 'THEOplayer-Connector-Uplynk'`
3. Install the pods using `pod install` , then open your `.xcworkspace` file to see the project in Xcode.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.
2. Use a [local override](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine) of the `THEOplayerSDK-basic` pod by adding the following line to your projects Podfile: `pod 'THEOplayerSDK-basic', :path => 'iOS-Connector/Helpers/TheoPod'` and make sure the path points to the [TheoPod folder](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoPod).

## Related articles

Learn more about Uplynk and how to use the connector in the following list of articles:

* [Introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/introduction.md): this article provides information on what Uplynk provides as a service.
* [Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/preplay.md): this article provides information on how to configure a Uplynk source.
* [Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/ads.md): this article provides information on which APIs can be leveraged to track and enhance the ad-viewing experience.
* [Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/ping.md): this article provides information on how to leverage the Ping service and which THEOplayer APIs you should use.

---

# Introduction

THEOplayer and Uplynk are partners in the streaming industry. The [Uplynk Platform](https://www.uplynk.com/) offers services like encoding, transcoding, server-side ad-insertion, a CDN and more.

> Uplynk was previously known as EdgeIO or Verizon Media. The iOS and Android connector will refer to the new name which is Uplynk.

Uplynk offers services which can enhance the API, UI and UX of video players and applications. The most popular services are called Preplay, Ping and Asset Info. THEOplayer integrates these services so that developers and viewers can benefit from them.

For example,

* Viewers can skip over ads;
* Viewers can see when an ad is playing (and stopping);
* Developers can define the behavior when viewers try to seek over an ad;
* Developers can query metadata to render a playlist in their application.

A live demo of THEOplayer's integration of Uplynk on the Web is available [here](https://cdn.theoplayer.com/demos/verizon-media/index.html).

Once the connector is added to your project, you can import it like so:

```swift
import THEOplayerConnectorUplynk
```

To instantiate the connector, we first need to create a configuration for it, to describe how the connector should be behave when it comes to Ads:

```swift
let uplynkConfiguration = UplynkConfiguration(defaultSkipOffset: ..., skippedAdStrategy: ...)
```

> `defaultSkipOffset` describes how many seconds the user has to wait before an ad is skippable. `skippedAdStrategy` controls how the connector behaves when seeking over ads. There are three values: `playAll`, `playLast` and `playNone`. The first option forces playback of all the unwatched ads before the seek point. `playLast` forces playback of the last ad before the seek point.

We can now instantiate the `UplynkConnector` provided that you have an available `THEOplayer` instance:

```swift
let connector = UplynkConnector(player: yourTHEOplayer,
                                configuration: uplynkConfiguration
                                eventListener: nil)
```

Here, the event listener refers to an implementation of the `UplynkEventListener` protocol which gives the client access to the Uplynk API responses. We will touch on what these responses are in the following articles. If you are not interested in receiving those callbacks, you can pass `nil` like above.

For more information on the connector and available APIs, continue to read on the pages below.

* [Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/preplay.md): this article provides information on how to configure a Uplynk source.
* [Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/ads.md): this article provides information on which APIs can be leveraged to track and enhance the ad-viewing experience.
* [Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/ping.md): this article provides information on how to leverage the Ping service and which THEOplayer APIs you should use.

---

# Preplay

This article explains how to leverage the Uplynk Preplay API through THEOplayer. This API allows developers to pre-integrate with Uplynk Preplay service.

Uplynk users can use an API (i.e. Preplay) to generate a streaming playlist given 1 or more assets or advertisements. The back-end of Uplynk stitches the content together and allows for server-side ad-insertion (SSAI) when applicable. This document describes how THEOplayer users should configure their source to leverage this Preplay service.

Assumptions:

* THEOplayer assumes the availability of the Preplay API and Uplynk content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
* THEOplayer assumes that developers who are interested in this feature have a basic understanding of the Preplay API. Uplynk documents this service at <https://api-docs.uplynk.com/#Develop/Preplayv2.htm>
* THEOplayer assumes that developers provide correct asset identifiers, as well as the proper content protection level.

## Stream Configuration (without ads)

The examples below demonstrate how to configure a stream through the Uplynk connector.

We start by creating an `UplynkSSAIConfiguration` object that describes how to configure an Uplynk source.

```swift
    let ssaiConfiguration = UplynkSSAIConfiguration(
                                id: .asset(ids: [ your list of asset IDs]),
                                assetType: .asset or .channel,
                                prefix: "https://content.uplynk.com", 
                                preplayParameters: [ Dictionary of parameters ]
                                contentProtected: true or false)
```

* `id`: The ID field identifies the asset. Instead of a single string, developers can also specify an array of asset IDs as strings, which will be stitched into a continuous stream. Assets can also be identified by `externalIds` and a `userId`. In that case, you can instantiate a `.external(ids: [list of channel IDs], userID: your user ID)` instead.

* `preplayParameters`: The `preplayParameters` object should have string-key-string-value combinations, which will be used as query parameters for the Preplay API call. Nested objects are not supported.

* `orderedPreplayParameters`: The `orderedPreplayParameters` object should have string-key-string-value combinations, which will be used as query parameters for the Preplay API call. Nested objects are not supported. Unlike `preplayParameters`, `orderedPreplayParameters` preserves the order of parameters while making a request, which is neccessary to prevent unsigned parameters that could break signature validation.

* `contentProtected`: Boolean value which will internally set any necessary content-protection information. No content-protection details have to be specified by the customer.

* **A Preplay request must include all parameters defined within the playback request, hence these parameters must be included in the THEOplayer source**. This request must also include a digital signature if the 'Require a token for playback' option is enabled in the back-end on the corresponding live channel. (See also : [Signing a Playback URL Tutorial](https://docs.uplynk.com/docs/sign-playback-url))

* Uplynk specific documentation on the available playback URL query parameters can be found on the Uplynk documentation site under [Customizing Playback via Parameters](https://docs.uplynk.com/docs/customize-playback-via-parameters)

* Some parameters can be excluded from the digital signature calculation. These parameters may enable certain use cases (e.g. DVR) and would for this reason be excluded from the digital signature.

Now, you can create a typed source, and attach the `UplynkSSAIConfiguration` object to the `ssai` property of the source

```swift
// Swift examples
let myTypedSource = TypedSource(src: "",
                                type: "application/x-mpegurl",
                                ssai: ssaiConfiguration)

let sourceDescription = SourceDescription(source: typedSource)
yourTHEOplayer.source = sourceDescription
```

## Stream Configuration (with ads)

Ad specific parameters can be passed in the `preplayParameters` argument of the `UplynkSSAIConfiguration`. An example of that is:

```swift
    let ssaiConfiguration = UplynkSSAIConfiguration(
                                id: ...
                                assetType: ...,
                                prefix: ..., 
                                preplayParameters: [
                                    // Parameters here should specify the necessary ad parameters for the Preplay API. Use `orderedPreplayParameters` instead to pass these in the order given.
                                    "ad.param1": "param_val1",
                                    "ad.param2": "param_val2" 
                                ],
                                contentProtected: ...)
```

## Preplay Response

THEOplayer automatically interprets the response returned by the Preplay service. However, if a developer wants to perform their own logic with the Preplay API response, then they can register their implementation of the `UplynkEventListener` protocol through the `UplynkConnector` constructor. There, you can get access to the `PrePlayLiveResponse` or `PrePlayVODResponse` objects through:

```swift
    func onPreplayLiveResponse(_ response: PrePlayLiveResponse) { ... }
    func onPreplayVODResponse(_ response: PrePlayVODResponse) { ... }
```

## Using Tokens

Uplynk users often leverage URL signatures (i.e. tokens) to further secure their content -- on top of AES-128 encryption or studio DRM.

A token is (typically) generated on back-end using an API key and a set of parameters. (The documentation at [Signing a Playback URL Tutorial](https://docs.uplynk.com/docs/sign-playback-url) describes this process.) This set of parameters should also be passed along to the `playbackURLParameters` in a `UplynkSSAIConfiguration`.

If you do not configure the `playbackURLParameters` correctly in relation to your signature parameters, then the Preplay request made by THEOplayer will most likely return an invalid Preplay response, preventing THEOplayer from setting up your stream.

# Related articles

* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/ads.md)
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/ping.md)

---

# Uplynk Ads

Uplynk offers support for server-side ad-insertion or in-short SSAI.

This article explains how to use the THEOplayer's Ads APIs to interact with the Uplynk Ads service

## Global Configuration

The examples below demonstrate how to pass along global configuration for Uplynk Ads in the Connector.

```swift
let uplynkConfiguration = UplynkConfiguration(defaultSkipOffset: ..., skippedAdStrategy: ...)
```

> `defaultSkipOffset` describes how many seconds the user has to wait before an ad is skippable. `skippedAdStrategy` controls how the connector behaves when seeking over ads. There are three values: `playAll`, `playLast` and `playNone`. The first option forces playback of all the unwatched ads before the seek point. `playLast` forces playback of the last ad before the seek point.

## Uplynk Ads API

Specifying a source which contains server-side ads configured through Uplynk will have the THEOplayer instance report such ads through its Ads API.

Users can use the THEOplayer Ads events to interact with Uplynk Ads:

```swift
 func addAdsEventListeners() {
        listeners["ADD_AD_BREAK"] = player.ads.addEventListener(type: AdsEventTypes.ADD_AD_BREAK) { [weak self] in
            os_log("--------------------------------------->")
            os_log("--> Add Ad Break Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_BREAK_BEGIN"] = player.ads.addEventListener(type: AdsEventTypes.AD_BREAK_BEGIN) { [weak self] in
            os_log("--------------------------------------->")
            os_log("--> Ad break begin Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_BREAK_END"] = player.ads.addEventListener(type: AdsEventTypes.AD_BREAK_END) { [weak self] in
            os_log("--------------------------------------->")
            os_log("--> Ad break end Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["ADD_AD"] = player.ads.addEventListener(type: AdsEventTypes.ADD_AD) {
            os_log("--------------------------------------->")
            os_log("--> Add Ad Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_BEGIN"] = player.ads.addEventListener(type: AdsEventTypes.AD_BEGIN) {
            os_log("--------------------------------------->")
            os_log("--> Ad Begin Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_FIRST_QUARTILE"] = player.ads.addEventListener(type: AdsEventTypes.AD_FIRST_QUARTILE) {
            os_log("--------------------------------------->")
            os_log("--> Ad First Quartile Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_MIDPOINT"] = player.ads.addEventListener(type: AdsEventTypes.AD_MIDPOINT) {
            os_log("--------------------------------------->")
            os_log("--> Ad Mid Point Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_THIRD_QUARTILE"] = player.ads.addEventListener(type: AdsEventTypes.AD_THIRD_QUARTILE) {
            os_log("--------------------------------------->")
            os_log("--> Ad Third Quartile Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_END"] = player.ads.addEventListener(type: AdsEventTypes.AD_END) {
            os_log("--------------------------------------->")
            os_log("--> Ad End Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_ERROR"] = player.ads.addEventListener(type: AdsEventTypes.AD_ERROR) {
            os_log("--------------------------------------->")
            os_log("--> Ad Error Event occured: \($0.error ?? "")")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_SKIP"] = player.ads.addEventListener(type: AdsEventTypes.AD_SKIP) {
            os_log("--------------------------------------->")
            os_log("--> Ad Skip Event occured: \($0)")
            os_log("--------------------------------------->")
        }
```

Users can also skip Ads through the `skip` API in THEOplayer:

```swift
player.ads.skip()
```

> Calling the `player.ads.skip()` function on a live stream will not have any effect.

## Related articles

* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/preplay.md)
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/ping.md)

---

# Ping

This article explains how to use the Uplynk Ping API.

The Ping API for Uplynk allows users of their CMS to receive updates about SSAI on running live-streams or provide better playback position beaconing for Video on demand. The Ping API is used together with the Preplay API because the latter provides a session to be used with the Ping API.

This connector allows the user to specify a source for Preplay, and enable or disable certain features of the Ping API. The player will then perform these Ping calls internally, without the user having to write their own Ping client. The response of Ping calls will be exposed for external handling if necessary.

**Feature Assumptions** We assume the SSAI information returned through the Ping API to be of a certain format, which we compile from examples and our own testing. The documentation does not define the structure of this payload very well and only states that it is "like the object returned in Preplay requests", though the formats are not a one-on-one match.

**Assumptions**

* THEOplayer assumes the availability of the Ping API and Uplynk content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
* THEOplayer assumes application developers have a notion of the Ping API, namely any extra parameters to be appended to the requests to Uplynk (e.g. for correct ad insertion). As documented in <https://api-docs.uplynk.com/#Develop/Preplayv2.htm>
* THEOplayer assumes application developers provide proper ID's of the Assets they want to play back, as well as the proper content protection level.

## Configuring Ping

The connector allows specification of the desired features of the Ping API as listed [in the official Ping API documentation](https://api-docs.uplynk.com/#Develop/Preplayv2.htm#Features).

In the THEOplayer-Connector-Uplynk, these features can be activated through the `uplynkPingConfiguration` property in the SSAI configuration:

```swift
let ssaiConfiguration = UplynkSSAIConfiguration(
                                id: .asset(ids: [ your list of asset IDs]),
                                assetType: .asset or .channel,
                                prefix: "https://content.uplynk.com",
                                preplayParameters: [ Dictionary of parameters ]
                                contentProtected: true or false,
                                uplynkPingConfiguration: UplynkPingConfiguration(adImpressions: true or false, // Defaults to false
                                                                                 freeWheelVideoViews: true or false, // Defaults to false
                                                                                 linearAdData: true or false)) // Defaults to false
```

By default, the ping API is disabled for all sessions. To enable it, the `ad.cping=1` parameter must be added to your preplay request. In addition to enabling the API, you must also notify the server of the features you want to support for this viewing session. To specify which features you'd like to enable, you add the`ad.pingf={some value}` parameter to the playback token. The value of the parameter is detailed in the official Ping Documentation.

Ping is enabled and `ad.pingf` is set to a proper value when the `uplynkPingConfiguration` has one or more of the `adImpressions`, `freeWheelVideoViews` or `linearAdData` configuration set to `true`.

If you attempt to call the API without passing in the `ad.cping` parameter, you can throw off the server's ability to make ad event calls correctly.

Sample Preplay URL with `ad.cping`:

`https://content.uplynk.com/preplay/cc829785506f46dda4c605abdf65392b.json?ad=adserver&ad.cping=1&ad.pingf=3`

The default value for `uplynkPingConfiguration` has `adImpressions`, `freeWheelVideoViews` and `linearAdData` all set to false, ie, Ping API will not be used.

## Ping requests

When the Ping API is enabled, THEOplayer will call the Ping URL located at:

```text
{prefix}/session/ping/{sessionID}.json?v=3&pt={currentTime}&ev={event}&ft={freeWheelTime}
```

Where:

* `{prefix}`: Is the prefix URL from the Preplay response.

* `{sessionID}`: Is the session ID from the Preplay response.

* `{currentTime}`: Mandatory parameter. This is the current player time in seconds.

* `{event}`: Is the current Ping event. An event should only be passed when playback starts or when a viewer seeks to a new position. Valid values are:

  * **start**: Pass this event, along `withpt=0`, when the player starts playback. This lets the server know where playback starts and allows the server to fire start events as needed.
  * **seek**: Pass this event when a viewer seeks. This resets the timeline to prevent inadvertently firing events for skipped ads.

* `{freeWheelTime}`: Indicates the playback position, in seconds, right before a viewer seeks to a different position in the timeline. This property is mandatory when the freeWheelVideoViews is used.

## Ping Response

When performed correctly, a Ping request will return a JSON response which is decoded into a `PingResponse`.

The ping response includes:

* next\_time: A new beacon will be scheduled when the player's currentTime passes this value. In case the value is -1, no further beacons will be scheduled.

* ads: Will be interpreted in order to create AdBreak's and Ad's as well as expose Ad information through the THEOplayer instance's `ads.scheduledAds` property.

  * ads.breaks.timeOffset will be used in order to determine the start time of the ad break (in seconds).

  * ads.breaks.ads will be looped in order to extract the list of ad's in an UplynkAdBreak:

    * apiFramework - Indicates the API Framework for the ad (e.g., VPAID).
    * companions - List of companion ads that go with the ad.
    * mimeType - Indicates the ad's Internet media type (aka mime-type)
    * creative - If applicable, indicates the creative to display.
    * events - Object containing all of the events for this ad. Each event type contains an array of URLs.
    * width - If applicable, indicates the width of the creative.
    * height - If applicable, indicates the height of the creative.
    * duration - Indicates the duration, in seconds, of an ad's encoded video.
    * extensions - Contains the custom set of VAST extensions returned by the ad server.
    * fwParameters - If the ad response provided by FreeWheel contains creative parameters, they will be reported as name-value pairs within this object.

  * ads.breaks.duration - Indicates the duration of the ad break.

  * ads.breaks.position - Indicates the position of the ad break. Valid values are: preroll | midroll | postroll | pause | overlay.

  * ads.breaks.events - Object containing all of the events for this ad break.

The ping response can be retrieved from the `onPingResponse(:)` delegate method by setting an `eventListener` to the `UplynkConnector` instance.

| Delegate method | Description                             | Arguments                                       |
| --------------- | --------------------------------------- | ----------------------------------------------- |
| onPingResponse  | Fired when a Ping response is received. | `response` argument contains the `PingResponse` |

## Related articles

* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/preplay.md)
* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/uplynk/ads.md)

---

# THEOPlayer 🤝 Uplynk Samples

A sample application that illustrate how to use the connector:

* [Sample using **Cocoapods**](https://github.com/THEOplayer/iOS-Connector/blob/-/Code/Uplynk-Examples/Cocoapod) (requires Cocoapods installation through terminal)

---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## Unreleased

## \[11.0.6] - 2026-09-14

### Fixed

* SideloadedSubtitle
  * Fixed an issue where partial playlist responses could cause playback to fail.

## \[11.0.5] - 2026-08-28

### Fixed

* Conviva
  * Fixed an issue where a THEOads ad break that failed before any ad was available, for example on an empty VAST response, was not reported as an ad attempt.

## \[11.0.4] - 2026-05-29

### Changed

* Conviva
  * Bumped the Conviva SDK dependency to 4.3.1.

## \[11.0.3] - 2026-05-19

### Fixed

* SideloadedSubtitle
  * Fixed an issue where internal network requests would cause a user agent mismatch.

## \[11.0.1] - 2026-04-21

### Fixed

* SideloadedSubtitle
  * Fixed an issue where switching between sideloaded subtitle tracks would get stuck after the first switch due to cached subtitle responses.

## \[11.0.0] - 2026-04-16

### Added

* The connectors will now be additionally published to a [THEOplayer hosted Cocoapods spec repo](https://github.com/THEOplayer/cocoapods-specs). We will continue publishing to the main trunk until EOL. For more info, please check [the SDK changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-1100-20260416).

### Removed

* Dropped support for iOS/tvOS 13 & 14.

## \[10.14.0] - 2026-04-09

### Added

* Uplynk
  * Added `orderedPreplayParameters` to `UplynkSSAIConfiguration`, which can be used to maintain the order of preplay parameters when making a request.

### Fixed

* Uplynk
  * Improved URL encoding for characters such as `%`, `&`, `=`, `+` and `,` to preserve pre-encoded values and prevent server-side double decoding issues.

### Changed

* Uplynk

  * When ping feature is not configured, the player will now send an empty string instead of `"&ad.pingc=0"` to prevent unsigned parameters that could break signature validation.
  * Deprecated the old `preplayParameters` in favor of the new `orderedPreplayParameters`

## \[10.8.0.1] - 2026-01-20

### Fixed

* SideloadedSubtitle
  * Fixed an issue where a bad http response code for subtitle sources would cause playback issues.

## \[10.8.0] - 2026-01-15

### Added

* SideloadedSubtitle

  * Added support for simultaneous multi-source caching with sideloaded subtitles. Previously there was a limitation of caching only a single task at a time.
  * Added support to make a sideloaded subtitle selected for caching by default. Use the `isDefault` property in `SSTextTrackDescription` or `TextTrackDescription`. Only one default track can be added.

### Fixed

* Conviva

  * Fixed an issue where the initial metadata passed to the convivaConnector was not persistent across Conviva sessions.
  * Fixed an issue where the session's assetName was not configurable by setContentInfo, which has higher precedence than source.metadata.title.
  * Fixed an issue with the encodingType, where sometimes the encodingType of the previous session was reported

## \[10.7.0] - 2025-12-18

### Changed

* Conviva
  * Bumped the Conviva SDK dependency to 4.2.4.

### Fixed

* SideloadedSubtitle
  * Fixed an issue where the stream would not play if an invalid subtitle source is passed and activated.

## \[10.4.0] - 2025-11-05

### Fixed

* Conviva
  * Fixed an issue where the session was automatically started with a stopAndStartNewSession request, even when the player was in a paused state.

### Changed

* Conviva
  * Report droppedFrames and renderedFramerates from player metrics, making the AVPlayer accesslog usage obsolete.
* Nielsen
  * Bumped minimum Nielsen SDK Dependency to 10.0.0

### Added

* Conviva

  * Report average bitrate from activeQualityChange event.
  * Report streamActivityMonitorId from theoads AdDescription and GoogleDAIConfiguration.

## \[10.2.0] - 2025-10-09

### Added

* Conviva

  * Pass podTechnology as custom field in reportAdBreakStarted.
  * Report DRM events.
  * Report intentToFallback event to Conviva as custom event.
  * Report encoding\_type (HLS or HESP) to conviva
  * Report cdn for THEOlive sources to conviva

### Fixed

* SideloadedSubtitle
  * Fixed an issue where enabling a `TextTrack` on the `ADD_TRACK` event would cause an error.

## \[10.0.0] - 2025-09-12

### Removed

* Conviva
  * Removed the `setErrorCallback`. The same behaviour can be achieved in THEOplayer 10 by calling `addEventListener` on THEOplayer with a type of `PlayerEventTypes.ERROR`

## \[9.6.1] - 2025-06-23

### Fixed

* Conviva
  * Fixed an issue where the ad duration of a THEOad was not reported.

## \[9.3.2] - 2025-05-13

### Fixed

* Conviva
  * Fixed a crash on tvOS, caused by a change to the player reference count.

## \[9.1.1] - 2025-04-15

### Fixed

* Conviva
  * Fixed a memory leak on iOS, caused by a dangling bitrate change observer on the AppEventForwarder.

## \[9.0.0] - 2025-04-03

### Added

* Conviva
  * Added average bitrate reporting

### Fixed

* Conviva
  * Improved the VPF detection for iOS and tvOS.

### Removed

* Conviva

  * Removed Objective-C API support.

* Yospace

  * Removed Objective-C API support.

## \[8.13.0] - 2025-03-13

### Fixed

* Conviva
  * Fixed an issue where the bitrate change events were reported to the incorrect Conviva endpoint.

## \[8.12.0] - 2025-02-26

### Changed

* Nielsen
  * Allow bumping minor and patch versions of the Nielsen SDK dependency.

## \[8.11.1] - 2025-02-21

### Added

* Uplynk
  * Added Uplynk integration with THEOplayer to allow integrating Uplynk CMS into THEOplayer.

## \[8.8.0] - 2025-01-02

### Added

* Comscore

  * Added `usagePropertiesAutoUpdateMode` and `usagePropertiesAutoUpdateInterval` to `ComScoreConfiguration`.
  * Exposed `notifyUxActive`, `notifyUxInactive`, `notifyEnterForeground` and `notifyExitForeground` methods.

## \[8.7.0] - 2024-12-18

### Added

* Conviva
  * Added compatibility for reporting playback bitrate metrics with THEOlive sources.

### Fixed

* Conviva
  * Fixed an issue where the playback bitrate metrics were not reported.

## \[8.0.1.1] - 2024-09-18

### Fixed

* Conviva
  * Fixed an issue where the vpfDetector was not firing a VPF due to a missing player reference.

## \[7.10.0] - 2024-08-13

### Fixed

* Conviva

  * Fixed an issue where multiple fatal errors were reported to the Conviva backend, resulting in multiple sessions being created.
  * Fixed an issue where VPF was not detected for VOD when the player has enough buffered data to get passed the detection interval.

## \[7.9.0] - 2024-08-01

### Fixed

* Comscore
  * Fixed an issue where converting `Double.infinity` values would crash on some analytics events.

## \[7.8.0] - 2024-07-18

### Added

* Yospace
  * Added Yospace integration with THEOplayer to allow playback of server-side ad inserted streams.

## \[7.5.0] - 2024-06-06

### Fixed

* SideloadedSubtitle
  * Fixed an issue that prevented `automaticTimestampSyncEnabled` to sync cues properly.

## \[7.4.0] - 2024-05-23

### Fixed

* SideloadedSubtitle
  * Prevent using HTTP redirects on media requests.

## \[7.3.0] - 2024-05-08

### Added

* SideloadedSubtitle
  * Added `automaticTimestampSyncEnabled` API on `SSTextTrackDescription`.

### Fixed

* Conviva

  * Fixed an issue where reported contentInfo was not cleaned up correctly when starting a new viewing session.
  * Fixed an issue where c3.ad.technology was reported as an integer value instead of a string.

## \[7.2.0] - 2024-04-24

### Fixed

* SideloadedSubtitle

  * Fixed an issue where playlists that contain urls with percentEncoding got an extra percentEncoding pass resulting in erronneous urls.
  * Fixed an issue where variant playlists with additional tags between EXTINF and the segment url, where not properly processed.

## \[7.0.0] - 2024-04-03

### Changed

* Conviva

  * Aligned the API to THEOplayer's Android and Web Conviva connectors.
  * Shield Conviva analytics endpoints. All data reporting now happens via the API.
  * Removed the 'report' methods for AssetName and ViewerID. These are replaced by using the setcontentInfo method (for viewerId) and by passing metadata to the sources (for AssetName).

### Added

* Conviva
  * VPF (Video Playback Failure) detection

## \[6.8.1] - 2024-01-18

### Fixed

* Conviva
  * Updated deprecated name for access log notification to fix broken bitrate reporting.
* Comscore
  * Prevent Comscore connector crash when reporting ad info for a DAI stream

### Changed

* Conviva
  * Dropped the protocol dependency for the external event dispatcher.

## \[6.1.1] - 2023-10-06

### Fixed

* SideloadedSubtitle
  * Add iOS 17 compatibility

## \[6.0.1] - 2023-09-27

### Fixed

* SideloadedSubtitle
  * adjust content string encoder in transformer

## \[6.0.0] - 2023-09-26

### Fixed

* SideloadedSubtitle

  * urlDecode the contentUrl string before downloading the track
  * resolve relative uri params in quality playlists

## \[5.11.0] - 2023-09-14

### Fixed

* SideloadedSubtitle
  * Take into account playlist redirects

## \[5.9.1] - 2023-08-24

### Added

* SideloadedSubtitle
  * Sideloaded subtitle connector now supports: SRT text tracks, specifying a time offset and caching for offline playback.

## \[5.7.0] - 2023-07-28

### Added

* Conviva
  * Added additional Ad metadata properties

## \[5.5.1] - 2023-06-29

### Fixed

* Conviva
  * Reset stored bitrate value on source changes

### Added

* Conviva
  * Send c3.csid and contentAssetName as adMetadata on AdBegin event

## [5.4.2](https://github.com/THEOplayer/iOS-Connector/compare/5.2.0...5.4.2) - 2023-06-21

### Fixed

* Conviva
  * Reporting bitrates after start and stop new session.

## [5.2.0](https://github.com/THEOplayer/iOS-Connector/compare/5.1.0...5.2.0) - 2023-05-31

### Added

* SideloadedSubtitle
  * Added new connector to sideload subtitles on tvOS and iOS

## [5.1.0](https://github.com/THEOplayer/iOS-Connector/compare/5.0.5...5.1.0) - 2023-05-15

### Fixed

* Conviva

  * Do not use ads API when there is no ad integration on the THEOplayer
  * Fix example with custom built framework

## [5.0.5](https://github.com/THEOplayer/iOS-Connector/compare/5.0.4...5.0.5) - 2023-04-27

### Added

* Conviva
  * Reporting bitrates for ads (0af67a3c)

### Fixed

* Comscore
  * Prevent crash that sometimes happened during playback (75e9eacb)
* Conviva
  * Fixed a bug that would cause the connector to not report bitrates when using manifest interception on the THEOplayer via the developer settings. (6ee5e519)

### Changed

* Conviva

  * Report bitrates from iOS in kbps to conviva (a231831a)
  * Do not report empty sessions (4257d803)

## [5.0.4](https://github.com/THEOplayer/iOS-Connector/compare/5.0.3...5.0.4) - 2023-04-21

### Changed

* Conviva
  * Report false as default for `CIS_SSDK_METADATA_IS_LIVE` (6bb45c17)

## [5.0.3](https://github.com/THEOplayer/iOS-Connector/compare/5.0.2...5.0.3) - 2023-04-17

### Added

* Conviva
  * Report ad resourceURI’s (a6b158d9)

## [5.0.2](https://github.com/THEOplayer/iOS-Connector/compare/5.0.1...5.0.2) - 2023-04-14

### Added

* Conviva

  * Report rendered framerate (c5e272d1)
  * Report ended when deinitialised (f49d2bb0)
  * Report network errors (02930576)

## [5.0.1](https://github.com/THEOplayer/iOS-Connector/compare/5.0.0...5.0.1) - 2023-04-13

### Changed

* Conviva
  * Do not report duration if no source is set (64db6846)

## [5.0.0](https://github.com/THEOplayer/iOS-Connector/compare/4.6.0...5.0.0) - 2023-04-07

### Fixed

* Comscore

  * Call notifyPlay when playback resumes after seek (9420ec5f)
  * Don't pause the player on background move (df92e0ff)

### Changed

* Comscore

  * Changed THEOplayer cocoapod dependency from `THEOplayerSDK-basic` to `THEOplayerSDK-core`
  * Changed minimum version requirement of ComScore from `6.7.1` to `6.10.0`

* Nielsen
  * Changed THEOplayer cocoapod dependency from `THEOplayerSDK-basic` to `THEOplayerSDK-core`

* Conviva
  * Changed THEOplayer cocoapod dependency from `THEOplayerSDK-basic` to `THEOplayerSDK-core`

## [4.6.0](https://github.com/THEOplayer/iOS-Connector/compare/4.5.1...4.6.0) - 2023-04-05

### Added

* Conviva

  * Report player framework info for ads (ececcab0)
  * Read duration of ads from THEOplayer instance (54a51109)

### Changed

* Conviva
  * Report a default value of `"NA"` for `CIS_SSDK_METADATA_ASSET_NAME` (6c4ba003)

* Nielsen

  * Only report ended if played to Nielsen (639c08c1)
  * Remove length metadata reporting (c53642b9)

### Removed

* Conviva
  * Removed backgrounding logs from stdout (ccb64d05)

## [4.5.1](https://github.com/THEOplayer/iOS-Connector/compare/4.5.0...4.5.1) - 2023-03-30

### Fixed

* Comscore
  * Fixed a crash that happened when removing the connector (36c30950)

### Removed

* Nielsen

  * removed the following DCR reports (cc14c08c):

    * playheadPosition
    * play
    * loadMetadata

## [4.5.0](https://github.com/THEOplayer/iOS-Connector/compare/4.4.0...4.5.0) - 2023-03-24

### Added

* Comscore
  * Added Comscore connector

## [4.4.0](https://github.com/THEOplayer/iOS-Connector/compare/4.3.1...4.4.0) - 2023-03-21

### Added

* Nielsen
  * Readme (62afa92c)

### Changed

* Nielsen
  * Use `NielsenAppSDK` and `NielsenTVOSAppSDK` dependencies for cocoapod instead of `NielsenAppSDK-XC` (ded687d0)

## [4.3.1](https://github.com/THEOplayer/iOS-Connector/compare/4.3.0...4.3.1) - 2023-03-17

### Added

* Nielsen

  * Report play, stop and end events (b737b336)
  * Report ID3 tags, metadata and duration changes (f4118e19)
  * Report Ad events (47ab93e6)

* Utilities
  * Shared package with utilities that can be reused for multiple connectors

## [4.3.0](https://github.com/THEOplayer/iOS-Connector/compare/4.2.0...4.3.0) - 2023-03-02

### Added

* Nielsen
  * Setup target for SPM (33b5ff6c)
* Conviva
  * Added tvOS platform to cocoapod (d4ea17dc)

### Changed

* Conviva

  * Round `CIS_SSDK_METADATA_DURATION` to closest integer (105ddf96)

  * Report metrics in milliseconds instead of seconds (105ddf96):

    * `CIS_SSDK_PLAYBACK_METRIC_PLAY_HEAD_TIME`
    * `CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED`
    * `CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED`

  * Only report non-linear ad types. (39edc330)

  * Report “NA” for `CIS_SSDK_METADATA_ASSET_NAME` when no title is provided. (90c86a4c)

  * Close session after fatal error (ce6bcd27)

  * Report `THEOplayer.version` instead of `.playerSuiteVersion` for Conviva's `CIS_SSDK_PLAYER_FRAMEWORK_VERSION` metric (9e1eb3c8)

### Removed

* Conviva
  * Removed unneeded playing report during ads (51670e42)

## [4.2.0](https://github.com/THEOplayer/iOS-Connector/compare/4.1.1...4.2.0) - 2023-02-21

### Added

* Conviva
  * Automatic reporting of `CIS_SSDK_METADATA_ASSET_NAME` from THEOplayer's `metadata.title` inside the current source's `SourceDescription` (f4c59570)

## [4.1.1](https://github.com/THEOplayer/iOS-Connector/releases/tag/4.1.1) - 2022-10-19

### Added

* Conviva connector
* Conviva-VerizonMedia connector

---

# OptiView Player React Native SDK

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Dolby OptiView Player is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/getting-started.md)

[Set up your first THEOplayer in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/react-native.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/react-native.md)

## [🎨UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native.md)

[Customize with Open Video UI or build from scratch.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native.md)

## [🔌Connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native.md)

[Integrate third-party solutions with THEOplayer using our pre-built connectors.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog/react-native.md)

[Find out what's new in the OptiView Player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog/react-native.md)

## [\*️⃣API references](https://theoplayer.github.io/react-native-theoplayer/api/)

[Discover all properties and functions of THEOplayer.](https://theoplayer.github.io/react-native-theoplayer/api/)

## [![](/pr-932/img/github.svg)![](/pr-932/img/github_dark.svg)GitHub](https://github.com/THEOplayer/react-native-theoplayer)

[Browse the source code or report issues on GitHub.](https://github.com/THEOplayer/react-native-theoplayer)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

## \[11.7.0] - 18-09-26

### Added

* Added the `Metrics` API, accessible through `player.metrics`, with `currentBandwidthEstimate` returning the player's estimated available bandwidth in bits per second. On iOS/tvOS this value is only reported for THEOlive/HESP streams.
* Added `THEOplayer.manageContentMatching` to let the player match the display mode (frame rate and dynamic range) of the TV to the content before playback starts on tvOS.
* Added a `testID` property on `THEOplayerView` to allow locating the player view from UI automation tools.

### Fixed

* Fixed media track kind typings to accept audio descriptions and other stream- or platform-specific values without type overrides.
* Fixed an issue on Android where destroying the player during a pending `MediaPlaybackService` bind could cause a crash.
* Fixed an issue on Android where the player could remain black when its view was attached after React Native had already assigned the layout.
* Fixed an issue where `player.paused` remained `true` between the `play` and `playing` events.

### Changed

* Removed the `RCTRootContentView` import from the iOS bridging header, as it is removed in React Native 0.87.
* Upgraded example app to support React Native v0.87.1.

## \[11.6.0]

### Added

* Added the `MediaControl` API for controlling the media session and lock screen controls with custom handlers.
* Added support for the `contentprotectionsuccess` event on all platforms

### Changed

* Upgraded example app to support React Native v0.86.2.

## \[11.5.0]

### Fixed

* Fixed an issue on iOS where fetching the artwork for the `NowPlayingInfo` could cause a crash due to unsafe thread usage.

### Added

* Added `contentprotectionerror` player event on Web and Android platforms.

## \[11.4.1] - 26-07-22

### Changed

* Added RCTBridgeModule extension on iOS, with helper methods to resolve the view and native player APIs.

### Fixed

* Fixed an issue on iOS where sideloaded texttracks were not stored for cached playout.

## \[11.4.0] - 26-07-06

### Fixed

* Fixed an issue on iOS where the `volumeChange` listener was not correctly removed on player desctruction.

### Added

* Added `externalId` property to `TheoLiveDistribution` on Android and iOS.
* Added `hlsMpegTsSrc` and `daiAssetKey` properties to `TheoLiveEndpoint` on Android and iOS.
* Added `targetLatency` property to `TheoLiveEndpoint` on Android.
* Added V3 discovery response properties (`src`, `srcType`, `provider`, `distribution`) to `TheoLiveEndpoint` on Web.

## \[11.3.0] - 26-06-18

### Added

* Added Android support for `ABRConfiguration.preferredMaximumResolution`, mirroring the existing iOS behaviour. Set to `(0,0)` to remove the cap.
* Added basic support for CMCD event mode reporting of DRM and ad events.
* Added bridging of the `hlsDateRange` property from `PlayerConfiguration` to Android's `THEOplayerConfig`.

### Fixed

* Fixed an issue on Android where `GoogleImaConfiguration.sessionId` was not properly passed.

## \[11.2.1] - 26-06-09

### Fixed

* Fixed an issue on iOS where setting the targetVideoQuality uids was causing a crash due to an unsafe bounds-check.

## \[11.2.0] - 26-06-04

### Added

* Added support for `CustomAdIntegrationKind`, allowing custom ad integrations on top of the player API.
* Added support for `breakManifestUrl` for OptiView Ads streams.

## \[11.1.0] - 26-05-27

### Added

* Added `useSystemCaptionStyle` flag to `PlayerConfiguration` on Android. When set to `true`, the player will apply the caption styles as configured in the system settings.
* Added support on iOS for controlling the targetQualities on THEOlive streams.

### Fixed

* Fixed an issue where on iOS the contentProtection queryParameters were not converted to string values, resulting in missing parameters in the urls.

## \[11.0.0] - 26-04-16

### Added

* Added support for player SDK v11. More info on the [migration documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/migrating-to-react-native-theoplayer-11.md) page.
* Enabled core library desugaring for Android to support version 3.39.0 of the Google IMA SDK.
* Added `TextTrack.captionChannel` to retrieve the CEA-608 channel and/or CEA-708 service numbers of closed caption text tracks.

### Changed

* Upgraded example app to React-Native v0.84.1.
* Changed the minimum supported iOS/tvOS version to 15.0, dropping support for iOS/tvOS 13 and 14.

### Fixed

* Fixed an issue on Web where Google IMA could fail to initialize when used with `react-reverse-portal` due to the player container not being attached to the document yet.

### Removed

* Removed deprecated `ResizeEvent` in favor of `DimensionChangeEvent`.
* Removed deprecated `player.theolive` property in favor of `player.theoLive`.
* Removed deprecated `source.integration` property in favor of `source.type`.

## \[10.13.0] - 26-03-27

### Fixed

* Fixed an issue on Android where the Ads API would sometimes return an empty map instead of an array when querying the list of current ads or scheduled ad breaks.
* Fixed an issue on iOS where the transition from PiP to fullscreen was not smooth.

## \[10.12.1] - 26-03-19

### Fixed

* Fixed an issue on Android where play-out of a Google DAI stream would crash the app.

## \[10.12.0] - 26-03-12

### Added

* Added `currentsourcechange` event to the player API, which is dispatched when the current source, chosen from the source description's sources, changes.
* Added `debugLogsEnabled` flag to `PlayerConfiguration` to allow enabling all debug logs from the underlying Android SDK.
* Added the `id` property to `AdBreak`, representing the identifier of the ad break.

### Fixed

* Fixed an issue on Android where the build process would pick up version from the snapshot repository instead of the release repository, causing build failures.
* Fixed an issue on iOS & Android where, when using `<StrictMode>`, the player's list of text tracks would be empty.

## \[10.11.0] - 26-03-10

### Fixed

* Fixed an issue on Android where transitioning from picture-in-picture presentation mode would fail when using Expo Router.
* Fixed an issue where the player would remove all listeners when using `<StrictMode>` on mobile platforms.

### Changed

* Updated `NativeAdBreak` to prevent iOS build failure caused by changed `AdBreak` protocol.

## \[10.10.0] - 26-02-17

### Fixed

* Fixed an issue on iOS where the `onPlayerStateSync` callback was not called from the main thread.

### Added

* Added the `DistributionLoaded` event for THEOlive.
* Added contentProtection extraction for THEOlive endpoints on iOS.

## \[10.9.0] - 26-01-29

### Fixed

* Fixed an issue on Android where the player could disrupt the layout by sending an unexpected dimension change event.
* Fixed an issue on Android where the default properties of the player's `backgroundAudioConfiguration` would not be properly applied.

### Added

* Added functionality to synchronize the player state from the native mobile players to React Native.
* Added a bypass property on iOS to control the THEOplayerView's ability to detach from its superView.
* Trigger an update for the iOS control centers (nowPlayingInfo and remoteCommands) to reflect a player state sync.

### Changed

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-theoplayer/blob/-/LICENSE) file for more information.

## \[10.8.0] - 26-01-22

### Added

* Added support on iOS to push the initial state of the player from the iOS bridge to the React native adapter.
* Added RNRepo support for Android to the example app. More info on the official [documentation](https://rnrepo.org/) page.

### Fixed

* Fixed an issue on iOS where the integrationParameters from the contentProtection section of the source were not processed correctly, resulting in failures for DRM connectors that depend on them.
* Fixed an issue on iOS where the player could crash when terminating the app while the player is backgrounded in fullscreen.
* Fixed an issue on Android where `player.ads.currentAds` would not return an array of ads due to a native error.
* Fixed an issue on Android where the player would sometimes have wrong dimensions after transitioning to fullscreen presentation mode.
* Fixed an issue on Android where the `useEMSG` property was not included when setting a TheoAds source description.

## \[10.7.1] - 26-01-06

### Added

* Added a `multiSession` property to `DRMConfiguration` to enable multi-key content on Android platforms.

## \[10.7.0] - 25-12-19

### Added

* Added a webrtc configuration property `webrtc` in `TheoLiveSource`, to enable configuring the playout delay for Millicast streams consumed through OptiView Live.

## \[10.6.1] - 25-12-18

### Fixed

* Fixed an issue on AndroidTV and FireTV devices, where pressing the center D-pad button during play-out of an ad configured with a click-through URL would cause the player to pause, without the ability to resume playback.

### Added

* Added `useExperimentalPipeline` to `CastConfiguration` for iOS, that controls the usage of an experimental, alternative implementation of the chromecast pipeline with a different feature set.

## \[10.6.0] - 25-12-02

### Added

* Added support for personalized discovery call responses by configuring the `profile` property on an OptiView Live source.

## \[10.5.1] - 25-11-28

### Added

* Support for contentProtection query parameters on THEOlive sources.
* Added `LatencyConfiguration` to `SourceDescription` for Android and Web.

### Fixed

* Fixed an issue on tvOS where unsupported pip logic was used on older tvOS target versions (< 14.0).

## \[10.5.0] - 25-11-24

### Fixed

* Fixed an issue on iOS where the scrim of an IMA ad was in a wrong position due to incorrect `safeAreaInsets`.

### Added

* Added `stopOnBackground` property to `BackgroundAudioConfiguration` to control whether playback should stop when the app goes to the background.
* Added `millicastSrc` to `TheoLiveEndpoint` for Web and Android.
* Added support for configuring query parameters that are common to multiple key system configurations. The parameters defined in `contentProtection.queryParameters` will be merged with any query parameters that are explicitly defined on a key system configuration, whereby the latter takes precedence.

### Changed

* Updated the active quality info extraction on iOS to use the activeQualityChange event data instead of player API.
* On iOS, we now also pass all available qualities and the current active quality when bridging video- and audio track data.

## \[10.4.0] - 25-11-13

### Fixed

* Fixed an issue on Android, where the app could crash when a `THEOads` error event was dispatched.
* Fixed an issue on Web, where the contents of the `reason` property of the THEOads `intenttofallback` event did not conform to its declared `PlayerError` type.

### Added

* Pass `streamActivityMonitorId` property for `THEOAdDescription` on iOS and Android.
* Added `allowLivePlayPause` and `seekToLiveOnResume` properties to `PlayerConfiguration.mediaControl` to control pausing and resuming behavior on live streams from the lockscreen controls.

### Changed

* Upgraded example app to React-Native v0.82.

## \[10.3.0] - 25-10-27

### Fixed

* Fixed an issue on Web, where adbreak related AdEvents did no longer contain the adBreak info.

### Changed

* When the player's `currentTime` is set to `Infinity` on mobile platforms, the player will seek to the live edge rather than the end of the `seekable` range.
* Added `useHttpEngine` to `PlayerConfiguration` to allow toggling the use of HttpEngine for network requests on Android.

## \[10.2.2] - 25-10-23

### Fixed

* Fixed a build issue on iOS/tvOS due to a breaking change on the THEOplayerSDK.Ad protocol in iOS SDK 10.3.0 .

## \[10.2.1] - 25-10-21

### Fixed

* Fixed an issue on web where the `<THEOplayerView>` would be re-rendered non-stop.

## \[10.2.0] - 25-10-20

### Added

* React Native THEOplayer now supports [React Compiler](https://react.dev/learn/react-compiler).
  * For Expo users: refer to the [Expo docs](https://docs.expo.dev/guides/react-compiler/) to set up React Compiler in your app.

### Fixed

* Fixed an issue on iOS where the player crashed when it was destroyed while in fullscreen.
* Fixed an issue on Android where creating a caching task with `MediaCache.createTask` would not return the created `task`.
* Fixed an issue where setting `player.theoLive.authToken = undefined` would cause a crash on Android.

### Changed

* Added `THEOplayer.theoLive` and deprecated `THEOplayer.theolive`, to be consistent with the THEOplayer SDKs for other platforms.
* Moved the `hlsDateRange` property from `SourceConfiguration` to its correct location in `TypedSource`.

## \[10.1.0] - 25-10-06

### Added

* Added an explicit clearing of the NowPlayingInfo on iOS, when the app receives a `willTerminateNotification`, to make sure all NowPlayingInfo is removed from the lock screen when an app is closed.
* Added `videoWidth` and `videoHeight` properties to `THEOplayer` containing the active video's resolution in pixels.
* Added `videoresize` player event enabling monitoring of video rendition resizes.
* Added `dimensionchange` player event enabling monitoring of player resizes. This event is set to replace the now deprecated `resize` player event.
* Added `fontPath` to `TextTrackStyle` to allow loading custom fonts from the Android assets folder.

### Fixed

* Fixed an issue on Android where play-out of Millicast sources in the example app would fail. The Android NDK version needs to be at least v28.
* Fixed an issue on Web where on older devices the `display: contents` style property is sometimes not supported.
* Fixed an issue on Android where the `MediaPlaybackService` could be restarted after the app was closed, in some cases causing a `ForegroundServiceDidNotStartInTimeException`. A conditional receiver makes sure the service is never restarted.
* Fixed an issue on iOS where a setup with multiple players could cause a view index NSInternalInconsistencyException after moving players in and out of fullscreen.
* Fixed an issue on Android where some event listeners were not properly disposed of after destroying the player.
* Fixed an issue on Web where the `width` and `height` properties on `THEOplayer` would show the active video rendition's resolution width and height instead of the width and height of the video element.

## \[10.0.0] - 25-09-15

### Added

* Added support for player SDK v10. More info on the [migration documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/migrating-to-react-native-theoplayer-10.md) page.
* Added iOS and Android support for THEOads API and THEOads events.

### Fixed

* Fixed an issue on Android where the app could still enter picture-in-picture presentation mode after closing the player.

### Changed

* Upgraded the example app to React-Native v0.81.
* All child views of `<THEOplayerView>` are being hidden when transitioning to picture-in-picture presentation mode on Android.

## \[9.10.0] - 25-08-19

### Fixed

* Fixed an issue on Android where transitioning into picture-in-picture presentation mode with the `THEOplayer_reparent_on_PiP` flag enabled would sometimes break the lay-out.
* Fixed an issue where the player's `currentTime` would not be immediately updated when dispatching `seeking` and `seeked` events.
* Fixed an issue on iOS where a listener for `seeked` events was not properly created.

## \[9.9.1] - 25-07-31

### Fixed

* Fixed an issue on Web in case the `aspect-ratio` CSS property is not supported on older browsers.
* Prevented passing infinite or NaN for intializationDelay in TheoAdDescription, on the Android bridge.
* Fixed and issue on Android where transitioning automatically into PiP presentation mode would fail on Android 16+.
* Fixed sources without an explicit `type` not being correctly recognized on Android when the URL contains query parameters.

### Added

* Added support for Clearkey DRM on Android.
* Added `endpoint` property to THEOlive `EndpointLoaded` event.
* Added support for `ABRStrategyConfiguration` on iOS.

## \[9.9.0] - 25-07-14

### Added

* Added initializationDelay to TheoAdsDecription, to delay THEOads session creation for more optimal ads monetisation.

### Fixed

* Fixed an issue on iOS where on iPads the fullscreen dimensions were not correctly updated after the first device orientation change.

## \[9.8.0] - 25-07-08

### Changed

* Deprecated the `BaseSource.integration` property in favor of `TypedSource.type`.

### Added

* Added support for `THEOlive` events.

### Fixed

* Fixed an issue on Android where, depending on the project structure, the Maven repository list would be incorrect.

## \[9.7.1] - 25-07-03

### Fixed

* Fixed a build issue on Android when using player SDK v9.7.0.

## \[9.7.0] - 25-07-01

### Added

* Added the theolive discoveryUrl to the PlayerConfiguration's theolive properties.
* Added focusguides (@THEOplayer/react-native-ui feature) to the example app for tvOS.

## \[9.6.0] - 25-06-27

### Added

* Added, for HLS on iOS, the `unlocalizedLabel` to the text-, audio- and videoTracks API, which contains the unmodified label as extracted from the manifest.
* Added a flag `focusSkipButtonWhenAvailable` to `GoogleImaConfiguration`.

## \[9.5.0] - 25-06-20

### Added

* Added Expo plugin support for iOS. More info on the [documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/expo.md) page.
* Added `currentProgramDateTime` to player API.

### Fixed

* Fixed an issue where a delayed `PresentationModeChange` event on Android could cause lay-out issues when going in to fullscreen mode.

## \[9.4.0] - 25-06-12

### Fixed

* Fixed an issue with the Expo plugin where Android extensions would not be properly enabled.

### Added

* Added `theoads` and `millicast` support for Android Expo plugin.
* Added support for the new `TextTrackStyle.marginBottom` and `TextTrackStyle.marginRight` API's on THEOplayer Android SDK v9.5.0.

## \[9.3.0] - 25-06-02

### Fixed

* Fixed an issue on iOS where the fullscreen dimensions could become wrong when the device is Flat Up or Flat Down on the table, or in an angle close to these.
* Fixed an issue on Android where switching to the PiP window during an IMA ad caused a crash on Android 8-11.

### Added

* Added `currentTime` property to `SeekingEvent` and `SeekedEvent`, indicating the player time to which is being seeked.

## \[9.2.0] - 25-05-20

### Added

* Added support for Millicast on iOS, Android and Web.
* Added support for `TextTrackStyle.edgeColor` on Android.
* Added support for THEOads on tvOS.

### Fixed

* Fixed an issue where the last cue of a VTT was not parsed if there is no newline after it.
* Fixed an issue on Android where a conversion build error would occur when targeting SDK version 9.4.

### Changed

* Changed the fullscreen dimensions calculation on iOS to make use of the native screen width and height, while taking into account the device orientation.

## \[9.1.2] - 25-05-14

### Fixed

* Prevented a possible crash on iOS/tvOS by deallocating the player instance without calling an explicit 'destroy' that brings the native player API at risk. The erroneous destroy method will be deprecated on the native SDK.

## \[9.1.1] - 25-04-24

### Fixed

* Fixed an issue on Android where a muted player would still be paused by the `AudioFocusManager`.

## \[9.1.0] - 25-04-23

### Added

* Added iOS support for `sseEndpoint` property to `TheoAdDescription`.
* Added iOS support for side-loaded chapter TextTracks.

### Changed

* Changed the `playbackPipeline` parameter in `SourceConfiguration` to be an optional parameter.

## \[9.0.1] - 25-04-08

### Fixed

* Fixed an issue on Android where an app would sometimes crash while receiving the license response when using a custom DRM integration.

### Added

* Added supported for multimedia tunneling on Android using the Media3 playback pipeline. More info on the [documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/media3.md#multimedia-tunneling) page.

## \[9.0.0] - 25-04-04

### Removed

* Removed `chromeless` property from `PlayerConfiguration`. Only React Native based UIs are supported.
* Removed ad integration kind `theo`.
* Removed `enableTHEOlive` property from `PlayerConfiguration` as THEOlive is always enabled.

### Added

* Added `liveOffset` property to `SourceDescription` for Web and Android platforms.
* Added `description` property for Google IMA ads on Web and Android platforms.
* Added `networkCode` property for Google DAI configuration on Web platforms.
* Added `segmentRelativeVttTiming` property on `DashPlaybackConfiguration` for Web to indicate whether segmented WebVTT files' timestamps should be considered relative to the segment start time.
* Added `storageType` to `CachingTaskParameters` to allow writing to either the legacy cache or Media3 cache on Android.

### Changed

* Reverted DataRangeCue timings calculation on iOS (based on programDateTime offset). Correct values are provided by the native SDK.

## \[8.18.0] - 25-04-02

### Changed

* No longer showing poster after setting the source when the player has been configured to use autoplay. With autoplay enabled, displaying the poster will only result in a brief flash of the image.
* Changed the fullscreen screen dimension calculation on Android, taking into account edgeToEdge layouts.

### Added

* Exposed THEOads API through the Player API.
* Added support for Common Media Client Data (CMCD) on all platforms. More info on the [documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/cmcd.md) page.

### Fixed

* Fixed an issue on Android where the transition to a PiP window would not focus on the player window.

## \[8.17.0] - 25-03-20

### Fixed

* Fixed an issue on Web where the metadata on the lockscreen was not showing correctly or missing occasionally.
* Fixed a crash on Android when setting a source with THEOads without the Media3 extension being enabled.
* Fixed an issue on iOS where the AdTapped and AdClicked events were not correctly cleaned up.
* Fixed an issue on Android where the player would sometimes crash when passing a DRM protected source without an `integration` property.

### Added

* Added SeekTo functionality to the web lockscreen controls, allowing to drag the lockscreen slider and seek to a specific time value.
* Added the IMA DAI `streamActivityMonitorId` property as a configuration on the SGAI `TheoAdDescription` for web.
* Added the THEOads API for Web.
* Added `retrievePodIdURI` property to `TheoAdsDescription` for Android and iOS.

## \[8.16.0] - 25-02-28

### Changed

* Delegating the autoplay functionality to the underlying native Android and iOS SDKs, making that logic independent from player events.
* On Android, sources with THEOads will always use the media3 player pipeline.

### Fixed

* Fixed an issue on iOS where `hlsDateRange` was not passed from RN towards iOS native
* Fixed an issue on Android, where the player would sometimes not initialise correctly in case New Architecture was not being used, resulting in a black screen.
* Fixed an issue on iOS Safari browsers, where the `presentationmodechange` event would not be dispatched when entering or exiting fullscreen.

## \[8.15.0] - 25-02-12

### Changed

* Transitioning to `fullscreen` presentation mode on Web platforms now puts only the `THEOplayerView` element and its child elements, such as the UI, in fullscreen. Previously, the whole page would transition to fullscreen.
* Changed `presentationmodechange` event dispatching on iOS to take into account if the change actually happened on the native player.

### Fixed

* Fixed an issue on iOS Safari where transitioning to `fullscreen` presentation mode would not work.
* Fixed an issue on Web where `presentationmodechange` events would sometimes be dispatched more than once.
* Fixed an issue on iOS where the view origin in fullscreen presentationMode was wrong when running under the RN new architecture / interop layer

## \[8.14.0] - 25-02-10

### Added

* Added a `theoLive` property to `PlayerConfiguration` to enable THEOlive configuration.

### Fixed

* Fixed an issue on iOS where the `currentTime` on `NowPlayingInfoCenter` would go out of sync or reset when changing playback rate.
* Fixed an issue on Android where the player would crash in case resolving the `THEOplayerView` instance fails.

## \[8.13.1] - 25-01-27

### Fixed

* Fixed an issue on iOS where fullscreen-inline transitions would cause a UIViewControllerHierarchyInconsistency when the current view's viewcController has sibling viewControllers that manage views that don't descend of the moving view.

## \[8.13.0] - 25-01-15

### Added

* Added support for New Architecture's through the Interop Layer. More info on the [React Native developer pages](https://reactnative.dev/architecture/landing-page).

### Fixed

* Fixed an issue on Web where picture-in-picture presentation mode would sometimes fail.

### Changed

* Upgraded the example app to use react-native-tvos\@0.76.5-0.

## \[8.12.0] - 25-01-09

### Fixed

* Fixed a memory leak on iOS, where the presentationModeManager was holding a strong reference to the fullscreen's target and return views
* Fixed an issue on iOS where the destruction of the THEOplayerView was not always propagated correctly over the iOS Bridge, resulting in an occasional memory leak.
* Fixed an issue where, when requesting a text track's cues, the time properties would sometimes be in seconds instead of milliseconds.
* Fixed a rare crash on Android due to a `java.lang.NullPointerException` when creating the THEOplayerView.
* Fixed an issue on Android where R8 minification would obfuscate some API class names, which could lead to a crash.

### Added

* Added a `adLoadTimeout` property to `GoogleImaConfiguration` to control the amount of time that the SDK will wait before moving onto the next ad or main content.

## \[8.11.1] - 24-12-18

### Fixed

* Fixed the picture-in-picture presentationMode for THEOlive sources on Web.

### Changed

* Deprecated the use of the `enableTHEOlive` flag in `PlayerConfiguration` as THEOlive support is always enabled.

## \[8.11.0] - 24-12-13

### Added

* Added support for THEOlive on tvOS.

## \[8.10.0] - 24-12-06

### Added

* Added support for THEOlive on iOS.

## \[8.9.1] - 24-12-04

### Added

* Added a `enableTHEOlive` flag to `PlayerConfiguration` to enable play-out of THEOlive sources.

## \[8.9.0] - 24-11-29

### Added

* Added support for the `SURFACE_CONTROL` rendering target on Android, which improves switching from/to fullscreen presentation mode. Rendering target `SURFACE_CONTROL` will be selected instead of `SURFACE_VIEW` on API level 29+.

### Fixed

* Fixed a memory leak on iOS, caused by the wrapping ViewController that was keeping a strong reference to the THEOplayerRCTView.

### Added

* Added support for the experimental media3 player pipeline on Android.

### Changed

* **BREAKING**: Changed the `view` parameter in the `Omid` API from a ref container to a native node handle when registering "friendly" obstructions.

## \[8.8.1] - 24-11-20

### Fixed

* Fixed build issue on tvOS caused by HomeIndicatorViewController

## \[8.8.0] - 24-11-19

### Added

* Added `HomeIndicatorViewController` to iOS, which can be used as an alternative `rootViewController` for the native App. It will automatically show/hide the home indicator when transitioning from/to fullscreen presentationMode.

### Changed

* Simplified the `viewController` reparenting mechanism on iOS that is applied when changing the presentationMode to/from fullscreen.
* The `MediaPlaybackService` on Android is never restarted if a MediaButton event is received after the app was closed.
* Added a consumer R8 config file on Android, telling R8 not to throw errors or warnings because of classes that are expected to be missing.

## \[8.7.0] - 24-11-05

### Fixed

* Fixed an issue on iOS where the dynamic island (iphone 14 plus and higher) briefly disappeared when updating the nowPlayingInfo on for example backgrounding the app.
* Fixed an issue on Android when using Expo, where the Expo plugin would not add THEOplayer's Maven repo to the project's repositories list.

### Added

* Added the `Omid` API for ads, which can be used to manage friendly video controls overlay obstructions.

## \[8.6.0] - 24-10-25

### Added

* Added `AdEvent.AD_CLICKED` and `AdEvent.AD_TAPPED` ad events for iOS and Android. The events are dispatched when a user taps or clicks on an ad that has a `clickThrough` link.

### Changed

* Upgraded example app to support React Native v0.75.

## \[8.5.0] - 24-10-21

### Added

* Added `SdkVersion` interface to be used by the sdk and its connectors to report version info.
* Added the `THEOads` SGAI ad integration for Android. See [THEOads](https://www.theoplayer.com/product/theoads) for more details.

### Fixed

* Fixed an issue on Web where all text tracks other than the selected would be set to `disabled` when enabling a text track.
* Fixed an issue on iOS where the player would crash when changing the presentationMode from fullscreen to picture-in-picture during ad playout.

### Changed

* On iOS, after closing picture-in-picture the player returns back to the previous presentationMode instead of always returning to inline.

## \[8.4.0] - 24-10-10

### Added

* Added a `posterStyle` property on `THEOplayerView` to allow overriding the default 16:9 poster style.
* Added a `theoads` property on `PlayerConfiguration.ads` to allow play-out of THEOads sources on Web platforms.
* Added a `hlsDateRange` property on `SourceDescription` to enable parsing and exposing date ranges from HLS playlists. This flag was already available on `PlayerConfiguration`, which applies for all HLS sources.

### Fixed

* Added support for a breaking change to `ContentProtectionIntegrationFactory`'s signature in THEOplayer Android 8.2.0.

## \[8.3.1] - 24-10-07

### Fixed

* Fixed an issue on Android where on some Android SDK versions controlling playback with the notification buttons would not work.
* Fixed an issue on Web and Android where a text track with attribute `DEFAULT` was not set as the player's `selectedTextTrack` property.

### Added

* Added `sdkVersions` to react-native-theoplayer, which contains the current RN SDK version and the version of the underlying native THEOplayer SDK.

## \[8.3.0] - 24-09-30

### Added

* Added the option to specify the AVAudioSession mode for iOS (moviePlayback versus spokenAudio).

## \[8.2.2] - 24-09-28

* Fixed a build issue on iOS for applications that run without the GOOGLE\_IMA feature flag

## \[8.2.1] - 24-09-27

### Fixed

* Fixed a build issue on Android when pinning a specific Android player SDK version, while also disabling the Google IMA extension.

## \[8.2.0] - 24-09-26

### Added

* Added the `PlaybackSettings` API for Android, allowing control of playback behaviour across all THEOplayer instances.

## \[8.1.0] - 24-09-23

### Added

* Added support for `bitrate` config on the GoogleIMAConfiguration, to be passed to the IMA SDK rendering settings.
* Added support on iOS and Android for `allowedMimeTypes` config on the AdsConfiguration, to be passed to the IMA SDK rendering settings.

### Fixed

* Fixed an issue where cast events were not forwarded from the native Android SDK.
* Fixed an issue where presentationMode changes on iOS would cause a UIViewControllerHierarchyInconsistency when an ad is playing.
* Fixed an issue where some ad event types could not be resolved at runtime when excluding the IMA integration on Android.

## \[8.0.3] - 24-09-14

### Fixed

* Fixed an issue on Android where the THEO Maven repository would not be picked up by all dependencies.

## \[8.0.2] - 24-09-14

### Fixed

* Fixed an issue on Android where not all dependencies would be correctly resolved.

## \[8.0.1] - 24-09-11

### Fixed

* Fixed an issue on Android where registering a content protection integration would fail.

## \[8.0.0] - 24-09-11

### Added

* Added support for THEOplayer 8.0.

### Changed

* Deprecated Jitpack.io in favor of the THEOplayer Maven repository on Android.

### Fixed

* Fixed an issue on iOS where the initial `duration` property of the player would be `0` instead of `NaN`.

## \[7.9.0] - 24-09-06

### Added

* Added THEOlive source integration type to `SourceDescription`.
* Added THEOads as `AdIntegrationKind`.
* Added a `headers` property to `TypedSource`. The player will add the headers to the HTTP requests for the given resource.

## \[7.8.2] - 24-08-21

### Changed

* Modified the poster behavior on iOS and Android to remain visible until the first frame is displayed.

## \[7.8.1] - 24-08-14

### Fixed

* Fixed an issue on Android where the notification background would be displayed in low resolution on recent Android versions.

### Added

* Added support on iOS for 'album' and 'artist' in the nowPlayingInfo.

## \[7.8.0] - 24-08-09

### Added

* Added shouldResumeAfterInterruptions to the BackgroundAudioConfiguration which toggles playback resume after an interruption (e.g. phone call) on the lockscreen.
* Added the option to set a nil source on the iOS Bridge, to 'unset' the previous source.
* Added the fast-forward & rewind buttons for the Android notification when `mediaControl.mediaSessionEnabled` is set to `true`.
* Added a `mediaControl.convertSkipToSeek` player config property to allow seeking with the `NEXT` and `PREVIOUS` media buttons. Its default value is `false`.

### Fixed

* Fixed an issue where the Lockscreen showed enabled controls when the player has no valid source.
* Fixed an issue on Android where the notification would not disappear when setting an undefined source.

### Changed

* Replaced the `MediaBrowserService` with a regular `Service` to facilitate background playback on Android.

## \[7.7.1] - 24-07-29

### Fixed

* Fixed an issue on tvOS where native cache functionality was not excluded correctly resulting in build errors.

## \[7.7.0] - 24-07-25

### Added

* Added ActiveQualityChanged event support for iOS.

### Fixed

* Fixed an issue where on iOS a cached asset would not play when setting the tasks's source on the player.
* Fixed an issue where on iOS the createTask method (CacheAPI) was not returning the created task.
* Fixed an issue where on iOS the Ad and AdBreak protocols where extended in the underlying native SDK and required some modifications.
* Fixed an issue where on Android the native module preparation would fail due to a change in the Android SDK 7.8.0 on eventDispatching.

## \[7.6.0] - 24-07-01

### Added

* Added `'root'` as an alternative id for the root div element in Web applications, supporting fullscreen presentation mode in Expo-based apps.
* Added `renderingTarget` property to `THEOplayer` API for Android, enabling the option to choose between either rendering to a `SurfaceView` (default) or `TextureView`.

### Changed

* Lowered the required node version to v16+.

## \[7.5.1] - 24-06-20

### Added

* Added ad event support for custom SSAI integrations.

## \[7.5.0] - 24-06-18

### Fixed

* Fixed an issue where the Cast API wouldn't be initialized yet when in the `onPlayerReady` callback.
* Added support for THEOplayer Android v7.6.0.

## \[7.4.0] - 24-06-11

### Added

* Added support for `SourceDescription.poster` for Android & iOS.
* Made the intervals for the forward and backward skip buttons on the iOS lockScreen configurable.
* Added preferredPeakBitRate and preferredMaximumResolution to ABRConfiguration for iOS

## \[7.3.0] - 24-06-03

### Changed

* Disabled skip forward/backward remote control buttons by default for Live content on Android TV platforms.

### Added

* Added support for React Native 0.74 and upgraded the example application to depend on `react-native-tvos` 0.74.1.

### Fixed

* Fixed an issue where on the iOS bridge the wrong value was extracted from the CachingParameters to configure the bandwidth setting on the MediaCache.

## \[7.2.0] - 24-05-12

### Added

* Added `resize` player event enabling monitoring of player resizes.
* Added `width` and `height` properties to `THEOplayer` containing the player's current dimensions in pixels.
* Added the possibility to set the player volume on iOS programmatically via the player API.
* Added `AD_CLICKED`, `AD_TAPPED`, `AD_ICON_TAPPED` and `AD_ICON_FALLBACK_IMAGE_CLOSED` ad events for Android platforms.

### Fixed

* Fixed an issue on Android where the `scheduledAdBreaks` list did not include the pre-roll ad on play-out of a Google DAI stream.

## \[7.1.1] - 24-04-26

### Fixed

* Fixed an issue where the selectedAudioTrack and selectedVideoTrack were not in sync with the actual selected mediatracks on the native player.

## \[7.1.0] - 24-04-23

### Fixed

* Fixed a build issue on tvOS example app due to the deprecated `prepare` method.

### Added

* Added multiple configuration options to `GoogleImaConfiguration` for both iOS and Android. These map to the corresponding IMASettings from the underlying native Google IMA SDKs.
* Added `skipForwardInterval` and `skipBackwardInterval` properties to `MediaControlConfiguration` for Android and Web, enabling configurable skip intervals for media sessions.
* Added ios bridging code to make 'forced' property available from native iOS TextTrack API.

### Removed

* Removed support for the web-based native iOS SDK on the RN iOS Bridge.

## \[7.0.0] - 24-04-10

### Fixed

* Fixed an issue where the player had the wrong layout in fullscreen presentationMode, after changing the source.
* Fixed an issue where not enabling autoplay would explicitly pause the stream, reverting a possible play() request right after setting up the source.

### Added

* Added support for THEOplayer native SDK 7.0.
* Aligned SDK major version with native player SDKs.

### Changed

* Raise minimal ios deployment target to 13.4, to match react native 0.73's minimal deployment target

## \[3.10.3] - 24-03-22

### Fixed

* Fixed a crash on iOS when playing an IMA Ad after reparenting the THEOplayerView to a different native Viewcontroller.

## \[3.10.2] - 24-03-22

### Changed

* Downgraded default `androidx.core:core-ktx` dependency version to support Android target sdk 33.

## \[3.10.1] - 24-03-19

### Changed

* Updated ios sdk version to 6.12.1

## \[3.10.0] - 24-03-15

### Changed

* Updated dependencies and example app to support ReactNative v0.73.
* Updated ios sdk version to 6.11

### Fixed

* Improved NowPlayingInfo updates for iOS by setting playbackRate on pause/playing events and processing the final info on player desctruction.
* Fixed an issue with misinterpretation of `targetVideoQuality = 0` (use video track with `uid == 0`) as `targetVideoQuality = undefined` (use ABR across all video qualities).
* Fixed an issue where the `srclang` property of a `textTrack` passed to a `SourceDescription` would not be parsed on Android.

### Added

* Added an optional `THEOplayer_reparent_on_fullscreen` build property on Android to disable `THEOplayerView` reparenting when transitioning to fullscreen presentation mode.

## \[3.9.2] - 24-03-06

### Changed

* Never pause play-out when losing audio focus while playing an advertisement.

## \[3.9.1] - 24-03-05

### Changed

* Bumped google-cast-sdk dependency to v4.8.0 for iOS.

## \[3.9.0] - 24-03-04

### Changed

* Reduce audio volume (duck) on Android when another app gains transient audio focus and ducking is allowed. In other cases the player will pause, and optionally resume if the audio focus loss was transient.

### Fixed

* Fixed an issue on iOS where the lockscreen controls and displayed asset metadata would remain visible after the player has been destroyed.
* Fixed an issue on iOS where the castState was not initialized correctly.

## \[3.8.0] - 24-02-23

### Changed

* Renamed native modules to avoid name collisions with external packages.

### Added

* Added `adbreakbegin` and `adbreakend` events for Google IMA on Android.
* Added `liveOffset` property to `PlayerConfiguration`, allowing to set a custom offset from the live point.
* Added a second, alternative config filename to the iOS podspec setup to prevent a react-native-theoplayer module resolving clash.

## \[3.7.1] - 24-02-09

### Fixed

* Fixed a dependency issue on iOS when using chromecast or Google IMA features.

## \[3.7.0] - 24-02-09

### Added

* Added fullscreen presentation mode support for iOS and Android. More info on the [documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/fullscreen.md) page.

## \[3.6.0] - 24-02-02

### Fixed

* Fixed a build issue on the iOS bridge caused by the deprecated DispatchDispatch protocol.
* Fixed an issue on Android where the `MediaPlaybackService` would sometimes crash with a `ForegroundServiceDidNotStartInTimeException` exception.

### Added

* Added the ability to override both small and large notification icons in Android with `ic_notification_small` and `ic_notification_large` resources respectively.

## \[3.5.0] - 24-01-30

### Added

* Added the ability to toggle `keepScreenOn` on Android. By default, screen timeout is disabled while the player is visible.

## \[3.4.2] - 23-12-22

### Fixed

* Fixed an issue in the Expo plugin for Android where it would fail to execute when no properties are passed.

## \[3.4.1] - 23-12-21

### Changed

* Take the Kotlin Gradle plugin version from the root project, if specified.

## \[3.4.0] - 23-12-21

### Added

* Added `ui` configuration object to `PlayerConfiguration` to configure the ads UI language.
* Added support for Android 14.
* Added Expo plugin to support Android dependency configuration.

### Changed

* Changed the Android notification channel name to `Notification channel`. It can be renamed by defining the `notification_channel_name` resource string.

## \[3.3.2] - 23-12-12

### Fixed

* Fixed an issue on iOS & Android where timestamps in ad events were not consistently defined in seconds.
* Fixed an issue on tvOS where unknown AdIntegrationKind values resulted in build issues.

## \[3.3.1] - 23-12-11

### Fixed

* Fixed an issue on Android where a `ContentResumeRequested` ad event was never broadcasted.
* Fixed an issue on iOS where the ad duration was provided in milliseconds instead of seconds.

## \[3.3.0] - 23-12-11

### Changed

* Extended event dispatching mechanism with broadcast functionality.

## \[3.2.1] - 23-12-07

### Fixed

* Fixed an issue on Android where `EnterCue` and `ExitCue` text track events did not contain the `trackUid` property.

## \[3.2.0] - 23-11-29

### Fixed

* Fixed an issue on iOS and Android were selecting an audio, video or text track that has a `uid` with value `0`, would fail.

### Added

* Added support for HLS #EXT-X-DATERANGE timed metadata tags. The tags appear as cues in a dedicated text track with type `daterange`.

## \[3.1.0] - 23-10-27

### Changed

* Revised audio focus protocol on Android. When resuming an app, audio focus is retrieved only if the player is not paused.
* Changed the behaviour of the Android component supporting background playback. It is stopped but not disabled when setting `backgroundAudioConfiguration.enabled = true`.

### Fixed

* Fixed an issue on Android where during play-out of a locally stored media asset the `seekable` property would not update.
* Fixed an issue on iOS where the error was not forwarded to theoplayer if a drm request fails on the iOS bridge

## \[3.0.2] - 23-10-17

### Fixed

* Fixed an issue on Android where compilation would fail when depending on player SDK 6.2.0.

## \[3.0.1] - 23-10-12

### Fixed

* Fixed compilation issues caused by Caching API not being supported on tvOS

## \[3.0.0] - 23-10-06

### Fixed

* Fixed sourceDescription processing on iOS for offline playback.

### Changed

* Added support for THEOplayer 6.0. See [THEOplayer's changelog](https://www.theoplayer.com/docs/theoplayer/changelog/) for details.
* Bumped minimal version for SideloadedTextTracks connection on iOS to v6.1.1 which contains fix for iOS 17.0.

### Added

* Added `MediaCache` API, enabling download of media assets for offline playback.

## \[2.16.1] - 23-09-27

### Added

* For iOS, added a subtitlePTS property to the TextTrackDescription that syncs a sideloaded textTrack with the video content.

## \[2.15.0] - 23-09-26

### Changed

* Upgraded the iOS side-loaded text track connector.

### Fixed

* Fixed an issue where the Android mediaSession connector would still process media button events when the app was in the background, and `enableBackgroundPlayback` was false.
* Fixed an issue on Android where play-out would still start when the app was put to the background during initial buffering, and `enableBackgroundPlayback` was false.
* Fixed an issue on Android where the MediaButtonReceiver would crash the app when it did not find a registered MediaBrowserService instance, when setting `enableBackgroundPlayback` to false while backgrounding the app.

## \[2.14.0] - 23-09-25

### Fixed

* Fixed an issue on Android where the MediaButtonReceiver would crash the app when it did not find a registered MediaBrowserService instance.

### Added

* Added support for side-loaded metadata tracks on iOS.

## \[2.13.0] - 23-09-15

### Fixed

* Fixed an issue where setting a new source on iOS, during DRM handling, would crash the application due to unsafe array access by different threads.

## \[2.12.1] - 23-09-14

### Fixed

* Fixed an issue on Android where the player SDK dependency could resolve to version 6.+.
* Fixed an issue on iOS where the player integration dependencies could resolve to version 6.+.

## \[2.12.0] - 23-09-04

### Added

* Added an `AnalyticsDescription` property to `SourceDescription` to configure additional source-specific properties for analytics connectors.
* Added support for sideloaded webVTT and SRT texttracks on iOS.
* Added Audio Focus for Android, pausing play-out on audio focus loss and resuming play-out once focus has been regained.
* Added Audio Focus and Audio Becoming Noisy manager for Android.

### Fixed

* Fixed an issue on Android that would cause the player not to reset when setting an empty source.
* Fixed an issue where a text track cue was not properly removed from the cue list on a TextTrackEventType.REMOVE\_CUE event.
* Fixed an issue on tvOS that allowed the user to pause a CSAI ad using the apple remote control.
* Fixed an issue on iOS where the cue event listeners were not cleanup up when destroying the player instance, resulting in memory build-up.

## \[2.11.0] - 23-08-10

### Added

* Added DAI support through iOS Native pipeline, using new THEOplayerGoogleIMAIntegration functionality
* Added `TextTrackStyle` API for iOS and Android.

### Fixed

* Fixed an issue on Android where the player would sometimes crash when requesting the current active video track.

### Changed

* Switched to 'displayIconUri' in sourceDescription.metadata as primary field for artwork selection in NowplayingInfo/MediaSession, 'poster' in sourceDescription is now the fallback.
* Removed the play/pause icon in the PiP window on Android while playing an ad.

## \[2.10.0] - 23-07-25

### Fixed

* Fixed an issue on Android where the media button receiver would not accept button events in case multiple receivers are registered.
* Fixed an issue on Android where `react-native-theoplayer` would not build when depending on Android player SDK v5.6.0.
* Fixed an issue on Android where a `pause` event would not be dispatched when putting the app to the background during play-out of an ad, while background playback is enabled. The ad would also restart when bringing the app back to the foreground.

### Changed

* Removed restrictions on media session playback actions for AndroidTV.
* Upgraded `react-native` version of the example app to `react-native-tvos@0.71.12-0`.

### Added

* Added a `version` property to `THEOplayer` for querying the `player` version (e.g., `'5.5.0'`) and `playerSuite` (e.g., `'2023.3.0'`) versions.

## \[2.9.0] - 23-06-16

### Changed

* Moved React Native UI to separate `@theoplayer/react-native-ui` package.

### Removed

* Removed `react-native-theoplayer` dependencies on packages `@react-native-community/slider`, `react-native-google-cast`, `react-native-svg`, `react-native-svg-web`, `react-native-url-polyfill` and `url-polyfill`.

### Added

* Added an overview of the available React Native connectors.

### Fixed

* Fixed an issue on Android where the background media service would crash the app in case it was started from the background.
* Fixed an issue on iOS where the delayed contentId extraction resulted in an incorrect value being passed to the license request setup.

## \[2.8.0] - 23-06-01

### Added

* Added `ignoreAvailabilityWindow` property to `SourceDescription.dash` for Android and Web.
* Added `needsTimescaleShifting`, `desiredTimescale` and `forceSeekToSynchronize` properties to `SourceDescription.dash` for Web.

### Fixed

* Fixed an issue where text track cue changes were not applied to the TextTrack's `cue` property.
* Fixed an issue on Android where play-out of an MP4 stream would sometimes crash the player.
* Fixed an issue on Android where a `pause` event would not be dispatched while pausing during play-out of an ad.
* Fixed an issue on Android where hardware buttons, such as `play` and `pause`, were not handled anymore after toggling background audio support.
* Fixed an issue on Android where the app would crash when toggling background playback while multiple `MediaBrowserServiceCompat` instances are registered.

### Changed

* Improved fullscreen support to use non-native fullscreen on Safari for iPad and Mac.
* Limited the set of available media session actions on Android when an ad or live stream is playing.
* Removed pausing the stream when disabling background playback on Android.

## \[2.7.0] - 23-05-15

### Changed

* Approved player behaviour on iOS and Android when doing player operations such as `play` and `pause` in case no source was set.

### Fixed

* Fixed an issue on Android where if an invalid view tag is passed to the native bridge, it would crash the player.
* Fixed an issue on Web where preview thumbnails would fail to load.

### Added

* Updated UI documentation with necessary dependencies.
* Added improved debug logging on iOS.

## \[2.6.0] - 23-05-05

### Fixed

* Fixed an issue on Android where the `currentProgramDateTime` property of `TimeUpdateEvent` would not be formatted in milliseconds.
* Fixed an issue on Android where the order of text and media tracks would change when adding tracks.
* Fixed an issue on Web where an exception would be thrown when accessing the player API after the player had been destroyed.
* Fixed an issue with Google IMA where the main content wasn't resumed after a pre-roll ended.

### Changed

* Use `enum` instead of a string union for `ABRStrategyType`.
* Changed the way artwork is fetched for NowPlayingInfo on the iOS Lockscreen, to prevent a crash caused by threading issues.

## \[2.5.0] - 23-04-26

### Added

* Added an `aspectRatio` property on the `THEOplayer` instance that can be either `FIT` (default), `FILL` or `ASPECT_FILL`.

### Changed

* Set `theoplayer` Web SDK as optional peer dependency.

## \[2.4.0] - 23-04-21

### Fixed

* Fixed an issue on iOS and Android where cue event properties `startTime` and `endTime` with value `Infinity` or `NaN` were not passed correctly.
* Fixed an issue on iOS Safari where switching to fullscreen presentation during an ad would not work.
* Fixed an issue on iOS Safari where an ad could be skipped during unmuted autoplay.
* Fixed a memory leak on iOS where the player would be allocated after being destroyed.
* Fixed an issue on Android where building the SDK would require IMA to be enabled.

### Changed

* Changed Web media session controls to only show trick-play buttons if the player is in foreground, or `backgroundAudioEnabled` is `true`, and never for ads and live stream.
* Changed Web media session controls to only show a play/pause button if the player is in foreground, or `backgroundAudioEnabled` is `true`, and never for ads.

### Added

* Added the `crossOrigin` property to `SourceDescription` for requesting CORS access to content.

## \[2.3.0] - 23-04-14

### Changed

* Updated picture-in-picture controls on Android to include forward/rewind buttons and disabled pause button for ads.

## \[2.2.0] - 23-04-12

### Fixed

* Fixed an issue on Android and iOS where error codes were not correctly formatted.

### Added

* Added `RetryConfiguration` on `PlayerConfiguration` for Web and Android.

### Changed

* Set minimum THEOplayer dependency version to 5.0.1 for Web, iOS and Android.
* Set `MediaPlaybackService` disabled by default on Android.

## \[2.1.0] - 23-04-09

### Fixed

* Fixed invalid location of the typescript declaration file.
* Fixed an issue on Android where the player would not pause when closing the app while background playback is disabled.

### Changed

* Removed `backgroundAudioConfiguration.mediaPlaybackServiceEnabled` property on Android. Disabling background playback disables the service as well.

## \[2.0.0] - 23-04-06

### Added

* Released 2.0.0 version.

## \[Unreleased 2.0.0-pre9]

### Changed

* Set the player container on Web to by default have a width and height not larger than the devices width and height.
* Use `enum` type for `PresentationMode`, `CastState` and`AdIntegrationKind`.
* Changed the methods of the Cast API, such as `casting` and `state`, to be synchronous.
* Applied `backgroundAudioConfig` properties on Android when closing picture-in-picture window.
* Applied `backgroundAudioConfig` properties on Android when showing Notifications.
* Disable iOS lockscreen controls when backgroundAudioConfig is set to `disabled`.

### Added

* Added `enableMediaPlaybackService` option to `backgroundAudioConfiguration` to optionally disable the MediaBrowserService that provides background audio support on Android.
* Added support for the `enabled` flag of `BackgroundAudioConfiguration` for Web.
* Added serviceId and contentId to NowPlayingInfo
* Feature flag extraction from custom iOS builds

### Fixed

* Fixed an issue on Android where the media session would become inactive when going to picture-in-picture mode, removing all transport controls.
* Fixed an issue where removing a player listener within a listener callback would sometimes result in events not being dispatched.

## \[Unreleased 2.0.0-pre7]

### Fixed

* Fixed an issue where the media session connector for Web would report an error when passing an Infinite duration for live streams.
* Fixed an issue on iOS where ID3 metadata content would not be correctly passed to cue instances.
* Fixed an issue on Android where the `'picture-in-picture'` permission was not checked.
* Fixed an issue on Android where the aspect ratio of the `'picture-in-picture'` window could be outside the valid range.
* Fixed an issue on iOS and Android where for a live stream the `duration` property of a `loadedmetadata` event was not properly passed as being `Infinite`.

### Changed

* Replaced deprecated systemUiVisibility code in Android's PresentationManager.
* Use `enum` types for `TextTrackMode`, `TextTrackType` and `TextTrackKind`.
* Allow go-to-live on iOS and Android by setting `currentTime` to `Infinity`.

### Added

* Added a `mediaControl` property to `PlayerConfiguration` to configure Media Session, Now Playing and Remote Command Center functionality across all platforms. It currently only contains a media session toggle for Web.
* Added a `backgroundAudioConfiguration` property to `THEOplayer` to allow dynamically configuring background audio functionality.
* Added a `pipConfiguration` property to `THEOplayer` to allow dynamically configuring picture-in-picture behavior.
* Added support for background audio playback on iOS and Android.
* Added `keepScreenOn` as a default player view property on Android to keep the device awake.

## \[Unreleased 2.0.0-pre6]

### Fixed

* Fixed an issue where the IMA player container would be rendered collapsed on Web.
* Fixed a missing check for picture-in-picture permission on Android.

### Added

* Added media session connector for Web.

## \[Unreleased 2.0.0-pre5]

### Added

* Added `onPlayerReady` callback on `THEOplayerView` to pass a `THEOplayer` instance once it is ready for access. More info on the [migration documentation](https://github.com/THEOplayer/react-native-theoplayer/blob/v7.0.0/doc/migrating-v2.md) page.
* Added `canplay` event, which is dispatched when the player can start play-out.
* Added `waiting` event, which is dispatched when the player has stopped play-out because of a temporary lack of data.
* Added `nativeHandle` property on `THEOplayer` to access the native player instance on web, and view id on mobile.
* Added `entercue` and `exitcue` events for text tracks, which are dispatched when a cue becomes (in)active.
* Added `ratechange` event, which is dispatched when the player's playback rate was changed.
* Added `seekable` property on `THEOplayer`, containing the time ranges of the media the player is able to seek to.
* Added `buffered` property on `THEOplayer`, containing the time ranges of the media the player has currently buffered.
* Added `buffered` property to the payload of the `onprogress` event.
* Added `duration`, `seeking`, `preload`, `textTrack`, `videoTracks` and `audioTracks` properties to `THEOplayer`.
* Added `libraryLocation` property to `PlayerConfiguration` to allow passing custom location for web workers.
* Added `mutedAutoplay` property to `PlayerConfiguration` to allow autoplay on web browsers with different autoplay policies.
* Added mode `hidden` as a value for a text track's `TextTrackMode` property, which is typically used for metadata tracks.
* Added `TextTrackStyle` API to support text track styling. This feature is currently supported on web only.
* Added support for 'picture-in-picture' presentation mode. More information on the [documentation page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/pip.md)
* Added `muted` state in `volumechange` event payload.
* Added media session connector for Android.
* Added public accessor on the `THEOplayerRCTView` that exposes the underlying iOS `THEOplayer` instance. So you can use the underlying THEOplayer from other packages.

### Changed

* Moved all player properties such as `paused`, `muted` and `volume`, from `THEOplayerView` component to `THEOplayer` instance. More info on the [migration documentation](https://github.com/THEOplayer/react-native-theoplayer/blob/v7.0.0/doc/migrating-v2.md) page.
* Removed `onEventName` callback methods from `THEOplayerView` component in favor of `THEOplayer` event listener's interface. More info on the [migration documentation](https://github.com/THEOplayer/react-native-theoplayer/blob/v7.0.0/doc/migrating-v2.md) page.
* Changed documentation sample code to reflect API changes.
* Exposed the `activeQuality` of a `MediaTrack` as a `Quality` instance instead of the quality's `uid`.
* Set the default container style for web to let the player cover the whole container.

### Removed

* Removed `seek` method on `THEOplayer`. It is replaced with a `currentTime` setter.
* Removed `fullscreen` setter and getter in favor of `presentationMode`.

### Fixed

* Fixed an issue on Android where an exception is thrown when an empty source description would be passed.
* Fixed the Webpack configuration in the sample application to copy web workers to `libraryLocation`.
* Fixed an issue on web where in case multiple player instances are created, the players would overlap.
* Fixed an issue on iOS Safari where switching to fullscreen presentation would not work.
* Fixed an issue on Android where passing an invalid empty source description would result in a crash.
* Fixed an issue on Android where the `framerate` property of a `VideoQuality` instance would not be filled in.
* Fixed an issue on iOS where the `TextTrackMode` property of a text track would be incorrect.
* Fixed an issue on iOS where after enabling/disabling a text track, metadata tracks would be set to `disabled` as well.
* Fixed missing `volumechange` events on mobile platforms.
* Fixed an issue on iOS where after toggling the mute state during an ad playout, succeeding mute toggles had no effect.

## \[1.8.4] - 23-04-27

### Fixed

* Fixed an issue on Android where the `pause` event was not dispatched during play-out of an ad.

### Added

* Added a `videoAspectRatio` property on the `THEOplayerView` for iOS and Android.
* Added a `PlayerEventTypes.WAITING` event that is dispatched when play-back stops due to lack of media data.

## \[1.8.3] - 23-04-06

### Fixed

* Fixed an issue on Android where building the SDK would fail when depending on player SDK v5.x.

## \[1.8.2] - 23-04-05

### Fixed

* Fixed an issue on Android where building the SDK would fail when depending on player SDK v4.12.0.

## \[1.8.1] - 23-02-09

### Changed

* Restructured iOS bridge code to extensions based on features.

### Fixed

* Fixed an issue on Android where the system UI would not be restored when unmounting THEOplayerView with `fullscreen` enabled.
* Fixed an issue with the availability of the cast button and play buttons in the example application.
* Fixed an issue on iOS where the player was not destroyed correctly on the iOS bridge.
* Added support for `DRMConfig` through `SourceDescription` for SSAI sources on iOS.

## \[1.8.0] - 23-01-16

### Added

* Support for Chromecast and Airplay.

### Fixed

* Fixed an issue where moving the sender app to the background while playing a DAI source on an Airplay device, would pause playback.

### Changed

* Upgraded Web SDK to v4.6.0.
* Updated the custom build setup to support both iOS and tvOS.

## \[1.7.2] - 22-12-05

### Fixed

* Fixed an issue on tvOS where a feature flag was incorrectly used for ads-related code.

## \[1.7.1] - 22-11-28

### Fixed

* Fixed an issue on Android where the player would consider unusable custom drm integrations.
* Fixed missing kotlin classpath property on Android.

## \[1.7.0] - 22-11-23

### Added

* Support for content protection integration (DRM connectors).
* Support for subscribing to ad events.
* Support for Google DAI ads.
* Support for Google IMA ads.
* Support for ABR configuration on Android and Web.
* Support for video quality selection on Android and Web.

### Fixed

* Fixed an issue where the player would not be correctly released when destroying the view on Android.
* Fixed a warning during debugging when a stream would have duration INF or NaN.
* Fixed an issue in the example app where it would not be possible to select a specific text track.
* Fixed conflicting npm dependencies in the example app.

## \[1.6.1] - 22-10-07

### Added

* Improved source handling for iOS.

## \[1.6.0] - 22-09-28

### Fixed

* Fixed jitpack.io repository url for Android.
* Fixed an issue where play-out of HLS streams would fail on Android.

### Changed

* Excluded folders from bob build config.
* Upgraded gradle versions for Android.

## \[1.5.0] - 22-09-26

### Fixed

* Fixed disabling all debug logs for iOS/tvOS release builds.
* Fixed duration from seconds to milliseconds on iOS/tvOS.

### Added

* Support for DRM pre-integrations on Android.
* Support for additional source properties on Android: `liveOffset`, `hlsDateRange`, `timeServer` and `hls`.

## \[1.4.0] - 22-08-11

### Fixed

* Fixed an issue on iOS where subtitles upon disappearing would sometimes leave a thin black line on the image.
* Fixed an issue on iOS where the player would not be destroyed after going to fullscreen.

### Added

* Improved determination of the stream source type on Android.

## \[1.3.0] - 22-07-26

### Fixed

* Fixed an issue where the app would crash due to the configured Flipper version.
* Fixed duplicate classes issue for Android when having dependencies on local libs folder.
* Fixed documentation feature matrix.
* Fixed duration scale in loadedmetadata event properties for Web.

## \[1.2.0] - 22-06-30

### Fixed

* Fixed a crash when removing text tracks event listeners on iOS.
* Fixed a number of broken links in the documentation.
* Removed unused files.

## \[1.1.0] - 22-06-06

### Added

* Initial release.

---

# Getting started with React Native THEOplayer

The `react-native-theoplayer` package provides a `THEOplayerView` component supporting video playback on the following platforms:

* Android, Android TV & FireTV
* iOS & tvOS (Apple TV)
* HTML5, Tizen & webOS (web, mobile web, smart TVs, set-top boxes and gaming consoles).

This document covers the creation of a minimal app including a `THEOplayerView` component, and an overview of the accompanying example app with a user interface provided by the `@theoplayer/react-native-ui` package.

It also gives a description of the properties of the `THEOplayerView` component, and a list of features and known limitations.

## Prerequisites

For each platform, a dependency to the corresponding THEOplayer SDK is included through a dependency manager:

* Gradle & Maven for Android
* Cocoapods for iOS
* npm for Web

In order to use one of these THEOplayer SDKs, it is necessary to obtain a valid THEOplayer license for that specific platform, i.e. HTML5, Android, and/or iOS. You can sign up for a THEOplayer SDK license through [our portal](https://portal.theoplayer.com/).

If you have no previous experience in React Native, we encourage you to first explore the [React Native Documentation](https://reactnative.dev/docs/getting-started), as it gives you a good start on one of the most popular app development frameworks.

## How to use these guides

These are guides on how to use the THEOplayer React Native SDK in your React Native project(s) and can be used linearly or by searching the specific section. It is recommended that you have a basic understanding of how React Native works to speed up the way of working with THEOplayer React Native SDK.

## Features

Depending on the platform on which the application is deployed, a different set of features is available.

If a feature missing, additional help is needed, or you need to extend the package, please reach out to us for support.

| Feature                                               | Android, Android TV, Fire TV                                                                                          | Web                                    | iOS, tvOS                                                         |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------- |
| **Streaming**                                         | MPEG-DASH (fmp4, CMAF), HLS (TS, CMAF), Progressive MP4, MP3, M4A                                                     |                                        | HLS (TS, CMAF), Progressive MP4, MP3, M4A                         |
| **Content Protection**                                | Widevine                                                                                                              | Widevine, PlayReady, Fairplay          | Fairplay                                                          |
| **DRM Connectors**                                    | BuyDRM, EZDRM, Anvato, Titanium, Axinom, Irdeto, VuDRM, Comcast, Verimatrix, Azure, …                                 |                                        |                                                                   |
| **Analytics Connectors**                              | Adobe, Agama, Comscore, Conviva, Mux, Nielsen, Youbora                                                                |                                        |                                                                   |
| **Other Connectors**                                  | Yospace SSAI                                                                                                          |                                        |                                                                   |
| **Subtitles & Closed Captions**                       | CEA-608/708, SRT, TTML, WebVTT                                                                                        |                                        |                                                                   |
| **Metadata**                                          | Event stream, emsg, ID3, EXT-X-DATERANGE, EXT-X-PROGRAM-DATE-TIME                                                     |                                        |                                                                   |
| **Advertising Integration**                           | Google IMA, Google DAI, THEOads                                                                                       |                                        |                                                                   |
| **Cast Integration**                                  | Chromecast                                                                                                            | Chromecast, Airplay                    |                                                                   |
| **Presentation Mode**                                 | Inline, Picture-in-Picture, Fullscreen                                                                                |                                        |                                                                   |
| **Audio Control Management**                          | Audio focus & Audio-Becoming-Noisy mgmt                                                                               | (Audio control management by platform) |                                                                   |
| **Advanced APIs**                                     | Background playback,<br />Media Session,<br />Media Cache (offline playback)                                          |                                        | Background playback,<br />NowPlaying,<br />Media Cache (iOS only) |
| **User Interface**<br />`@theoplayer/react-native-ui` | Basic playback, media & text track selection, progress bar, live & vod, preview thumbnails, customisable & extensible |                                        |                                                                   |

## Available connectors

The `react-native-theoplayer` package can be combined with any number of connectors to provide extra functionality. Currently, the following connectors are available:

| Connector                                                 | npm package                                                                                                                                                                                                                                                            | Source                                                                                           |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Adobe Heartbeat analytics using the Media Collections API | [![%40theoplayer/react-native-analytics-adobe](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-adobe?label=%40theoplayer/react-native-analytics-adobe)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-adobe)                | [`Adobe`](https://github.com/THEOplayer/react-native-connectors/tree/main/adobe)                 |
| Adobe Media Edge analytics                                | [![%40theoplayer/react-native-analytics-adobe-edge](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-adobe-edge?label=%40theoplayer/react-native-analytics-adobe-edge)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-adobe) | [`Adobe Edge`](https://github.com/THEOplayer/react-native-connectors/tree/main/adobe-edge)       |
| Agama analytics                                           | [![%40theoplayer/react-native-analytics-agama](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-agama?label=%40theoplayer/react-native-analytics-agama)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-agama)                | [`Agama`](https://github.com/THEOplayer/react-native-connectors/tree/main/agama)                 |
| Comscore analytics                                        | [![%40theoplayer/react-native-analytics-comscore](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-comscore?label=%40theoplayer/react-native-analytics-comscore)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-comscore)    | [`Comscore`](https://github.com/THEOplayer/react-native-connectors/tree/main/comscore)           |
| Conviva analytics                                         | [![%40theoplayer/react-native-analytics-conviva](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-conviva?label=%40theoplayer/react-native-analytics-conviva)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-conviva)        | [`Conviva`](https://github.com/THEOplayer/react-native-connectors/tree/main/conviva)             |
| Mux analytics                                             | [![%40theoplayer/react-native-analytics-mux](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-mux?label=%40theoplayer/react-native-analytics-mux)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-mux)                        | [`Mux`](https://github.com/THEOplayer/react-native-connectors/tree/main/mux)                     |
| Nielsen analytics                                         | [![%40theoplayer/react-native-analytics-nielsen](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-nielsen?label=%40theoplayer/react-native-analytics-nielsen)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-nielsen)        | [`Nielsen`](https://github.com/THEOplayer/react-native-connectors/tree/main/nielsen)             |
| Youbora analytics                                         | [![%40theoplayer/react-native-analytics-youbora](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-youbora?label=%40theoplayer/react-native-analytics-youbora)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-youbora)        | [`Youbora`](https://github.com/THEOplayer/react-native-connectors/tree/main/youbora)             |
| Yospace SSAI                                              | [![%40theoplayer/react-native-yospace](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-yospace?label=%40theoplayer/react-native-yospace)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-yospace)                                                | [`Yospace`](https://github.com/THEOplayer/react-native-connectors/tree/main/yospace)             |
| Content protection (DRM)                                  | [![%40theoplayer/react-native-drm](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-drm?label=%40theoplayer/react-native-drm)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-drm)                                                                | [`DRM`](https://github.com/THEOplayer/react-native-theoplayer-drm)                               |
| React Native Open UI                                      | [![%40theoplayer/react-native-ui](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-ui?label=%40theoplayer/react-native-ui)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-ui)                                                                    | [`Open UI`](https://github.com/THEOplayer/react-native-theoplayer-ui)                            |
| A template for<br />`react-native-theoplayer` connectors. | [![%40theoplayer/react-native-connector-template](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-connector-template?label=%40theoplayer/react-native-connector-template)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-connector-template)    | [`Connector template`](https://github.com/THEOplayer/react-native-theoplayer-connector-template) |

## Creating your first app

This section starts with creating a minimal demo app that integrates the `react-native-theoplayer` package, followed by an overview of the available properties and functionality of the THEOplayerView component. An example application including a basic user interface and demo sources is included in the [git repository](https://github.com/THEOplayer/react-native-theoplayer/tree/develop/example), and discussed in the next section.

* [Creating a minimal demo app](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/creating-minimal-app.md)

  * [Getting started on Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/creating-minimal-app.md#getting-started-on-android)
  * [Getting started on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/creating-minimal-app.md#getting-started-on-ios-and-tvos)
  * [Getting started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/creating-minimal-app.md#getting-started-on-web)

* [The THEOplayerView component](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/theoplayerview-component.md)

* [The example application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/example-app.md)

## Knowledge Base

This section gives an overview of features, limitations and known issues:

* [Adaptive Bitrate (ABR)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/abr.md)
* [Advertisements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/ads.md)
* [Android Media3 Pipeline](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/media3.md)
* [Audio Control Management](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/audio-control.md)
* [Background playback and notifications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/background.md)
* [Casting with Chromecast and Airplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/cast.md)
* [Common Media Client Data (CMCD)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/cmcd.md)
* [Content matching on tvOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/content-matching.md)
* [Digital Rights Management (DRM)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/drm.md)
* [Expo](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/expo.md)
* [Fullscreen presentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/fullscreen.md)
* [Media Caching](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/media-caching.md)
* [Migrating to THEOplayer 9.x](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/migrating-to-react-native-theoplayer-9.md)
* [Migrating to THEOplayer 10.x🔥](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/migrating-to-react-native-theoplayer-10.md)
* [Millicast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/millicast.md)
* [Picture-in-Picture (PiP)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/pip.md)
* [Subtitles, Closed Captions and Metadata tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/texttracks.md)
* [Limitations and known issues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/limitations.md)

## API Reference

See the [API Reference](https://theoplayer.github.io/react-native-theoplayer/api/) for detailed documentation about all available components and functions.

---

# Creating a minimal demo app

In this section we start from an empty React Native template, include a dependency to `react-native-theoplayer`, and deploy it on an Android or iOS device.

A user interface is added using the `@theoplayer/react-native-ui` package.

## Setting up a new project

In the following steps we will be using `npm` as the Node.js package manager.

First initialize a new project with a React Native app template:

```bash
npx @react-native-community/cli init rntheodemo
cd rntheodemo
```

Alternatively use a template that also provides support for tvOS, as it will create a dependency to `react-native-tvos`, a fork of the main React Native branch:

```bash
npx @react-native-community/cli init rntheodemo --template=react-native-template-typescript-tv@6.5.8-0
cd rntheodemo
```

Next, include the dependency to `react-native-theoplayer`.

```bash
npm i
npm i react-native-theoplayer
```

or optionally specifying a specific version of the package:

```bash
npm i react-native-theoplayer@<version>
```

Note: depending on your node version, an extra `--legacy-peer-deps` option has to be added:

```bash
npm i react-native-theoplayer --legacy-peer-deps
```

Finally, replace the `App.tsx` with this minimal code:

```tsx
import React from 'react';
import {View} from 'react-native';
import {PlayerConfiguration, SourceDescription, PlayerEventType, THEOplayer, THEOplayerView} from 'react-native-theoplayer';

const playerConfig: PlayerConfiguration = {
  license: undefined,     // insert THEOplayer React Native license here
};

const source: SourceDescription = {
  sources: [
    {
      src: "https://cdn.theoplayer.com/video/elephants-dream/playlist-single-audio.m3u8",
      type: "application/x-mpegurl"
    },
  ],
};

const onReady = (player: THEOplayer) => {
  player.autoplay = true
  player.source = source;
  player.addEventListener(PlayerEventType.ERROR, console.log);
}

const App = () => {
  return (
    <View style={{position: 'absolute', top: 0, left: 0, bottom: 0, right: 0}}>
      <THEOplayerView config={playerConfig} onPlayerReady={onReady}/>
    </View>
  );
};

export default App;
```

When configuring a stream that is hosted on another server than `cdn.theoplayer.com`, a license for the React Native SDK needs to be obtained through the 'Licenses' built in the [THEOplayer portal](https://portal.theoplayer.com/).

![license\_portal](/pr-932/assets/images/license_portal-b7f8c3d779e5f1ad28c8e3f1f3f2d6ad.png)

## Getting started on Android

After completing the [initial project setup](#setting-up-a-new-project), which is shared for all platforms, the following Gradle buildConfig fields can be used in your `gradle.properties` file to override or set various Android-specific react-native-theoplayer options:

```groovy
# Version of the (Android) THEOplayer SDK, if not specified, the latest available version is set.
#THEOplayer_sdk=9.6.1

# Override Android sdk versions
#THEOplayer_compileSdkVersion = 35
#THEOplayer_minSdkVersion = 21
#THEOplayer_targetSdkVersion = 35

# Toggle player event logging using tag 'VideoPlayer' (default: false)
#THEOplayer_logPlayerEvents = true

# Toggle playerView event logging using tag 'ReactTHEOplayerView' (default: false)
#THEOplayer_logViewEvents = true

# Toggle media session event logging (default: false)
#THEOplayer_logMediaSessionEvents = true

# Enable THEOplayer Extensions (default: disabled)
#THEOplayer_extensionGoogleIMA = true
#THEOplayer_extensionGoogleDAI = true
#THEOplayer_extensionCast = true
#THEOplayer_extensionMediaSession = true
#THEOplayer_extensionTHEOads = true
#THEOplayer_extensionMediaSession = true
#THEOplayer_extensionMillicast = true

# Optionally limit timeUpdate rate, which could improve performance.
# Possible values: (default: UNLIMITED)
# - com.theoplayer.TimeUpdateRate.UNLIMITED
# - com.theoplayer.TimeUpdateRate.LIMITED_ONE_HZ
# - com.theoplayer.TimeUpdateRate.LIMITED_TWO_HZ
# - com.theoplayer.TimeUpdateRate.LIMITED_THREE_HZ
#THEOplayer_timeUpdateRate = com.theoplayer.TimeUpdateRate.LIMITED_TWO_HZ

# Toggle whether to use a media service for background playback
#THEOplayer_usePlaybackService = true

# Toggle whether to reparent the playerView to the top-most node of the view hierarchy when going
# into fullscreen.
# See https://github.com/THEOplayer/react-native-theoplayer/blob/develop/doc/fullscreen.md.
#THEOplayer_reparent_on_fullscreen = true

# Toggle whether to reparent the playerView to the top-most node of the view hierarchy when going
# into PiP.
#THEOplayer_reparent_on_PiP = false
```

For optimal performance, make sure to build your app in release mode, and optionally limit the number of `timeupdate` events send by the player as shown in the config above. A `timeupdate` event typically triggers a number of React Native component updates and could affect performance in negative way.

## Getting started on iOS and tvOS

To define which extra THEOplayer integrations need to be loaded for additional features, a config file needs to be added to you application folder:

Create a json file **\[YourApplicationFolder]/react-native-theoplayer.json**, or **\[YourApplicationFolder]/theoplayer-config.json**, on the same level as the node\_modules folder (both alternatives offer the same functionality).

Edit the file to reflect the features required for your application. The following example adds Google IMA and DAI, Chromecast, THEOads, Millicast and Sideloaded textTracks to the setup. If one of these is out of your applications scope, you can leave it out to reduce the app's size. When using only basic functionality, leave the features array empty.

Example:

```text
{
	"ios": {
		"features": [
			"GOOGLE_IMA",
			"CHROMECAST",
			"THEO_ADS",
			"MILLICAST",
			"SIDELOADED_TEXTTRACKS"
		]
	}
}
```

* **GOOGLE\_IMA**: adds an additional dependency to the THEOplayer-Integration-GoogleIMA cocoapod that delivers the IMA and DAI functionality
* **CHROMECAST**: adds an additional dependency to the THEOplayer-Integration-GoogleCast cocoapod that delivers the chromecast functionality
* **THEO\_ADS**: adds an additional dependency to the THEOplayer-Integration-TheoAds cocoapod that delivers Server Guided Ad Insertion (SGAI) functionality
* **MILLICAST**: adds an additional dependency to the THEOplayer-Integration-Millicast cocoapod that delivers the Millicast functionality
* **SIDELOADED\_TEXTTRACKS**: adds an additional dependency to the THEOplayer-Connector-SideloadedSubtitle cocoapod that delivers the sideloaded texttracks functionality

Once the project has been setup correctly, define a valid HLS, Millicast or THEOlive source, eg.

```typescript
const source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
      type: 'application/x-mpegurl',
    },
  ],
};
```

Some RN templates miss a specific Swift version setting for tvOS. To fix this add a custom build setting to your tvOS app target:

```text
SWIFT_VERSION 5.0
```

Run pod install in your app's ios folder

```bash
pod install
```

## Getting started on Web

Make sure to first complete the [initial project setup](#setting-up-a-new-project), which is shared for all platforms. Deploying a web app requires a little more work. The example uses [react-native-web](https://necolas.github.io/react-native-web/) to support web-based platforms, which translates React Native components to React DOM components. In addition, the project relies on webpack to create the bundle that is loaded in the hosting web page.

We refer to the [example application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/example-app.md) and its [code](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/example/web/) for a full demonstration.

### libraryConfiguration

When passing the `PlayerConfiguration` object while creating the player, the [`libraryConfiguration`](https://www.theoplayer.com/docs/theoplayer/v10/api-reference/web/interfaces/PlayerConfiguration.html#libraryLocation) parameter specifies where the THEOplayer web worker files are located. The worker files are dynamically loaded and necessary to play-out MPEG-TS based HLS streams. By default it is set to the location where npm installed THEOplayer ('./node\_modules/theoplayer').

## Building and running the app

Finally, build and deploy the app. Make sure an emulator is available, or there is a physical device connected to deploy to.

```bash
$ npm run android
$ npm run ios
$ npm run web
```

## Adding a user interface

The `react-native-theoplayer` package does not contain a user interface by default. There is however a separate package that builds a UI on top of the `THEOplayerView` component, `@theoplayer/react-native-ui`.

We refer to the [documentation](https://github.com/THEOplayer/react-native-theoplayer-ui) of `@theoplayer/react-native-ui` on how to install and use it.

---

# The `THEOplayerView` Component

THEOplayer React native SDK is an NPM package, which exposes the THEOplayerView component that can be added to your React Native projects.

![react-native-theoplayer](/pr-932/assets/images/react-native-theoplayer-50e1e6e2dbf74294addbeeed5baa8e36.png)

This section will discuss the most important properties of `THEOplayerView`. The component's properties are also described in detail in its [THEOplayerViewProps interface](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/THEOplayerView.ts).

THEOplayer React Native SDK uses HTML5/ Tizen/ webOS SDK, Android/ Fire TV SDK, and iOS/ tvOS SDK under the hood through bridges that map each THEO SDK API to the THEOplayerView component.

## Properties

The `THEOplayerView` component supports the following list of properties.

| Property          | Description                                                                                                                                                                 | Platforms |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `config`          | The player configuration containing the THEOplayer license and other player-setup related properties                                                                        | All       |
| `style`           | The style applied to the player view.                                                                                                                                       | All       |
| `onPlayerReady`   | A callback that provides the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts) when the player instance is ready. | All       |
| `onPlayerDestroy` | A callback is called when the internal player instance will be destroyed.                                                                                                   | All       |

## Configuration

The `THEOplayerView` component accepts a `config` property that contains basic player configuration.

```typescript
const player: PlayerConfiguration = {
  license: undefined, //'insert THEOplayer license for react-native here'
  chromeless: true,
};
```

The `license` is an obfuscated string that contains the THEOplayer license needed for play-out, and which can be found in your THEOplayer Portal account. You can generate a license specifically for react-native, but if separate licenses per platform are needed, `Platform.select()` could be used to configure them:

```typescript
const license = Platform.select(
  {
    'android': undefined, // insert Android THEOplayer license here
    'ios': undefined,     // insert iOS THEOplayer license here
    'web': undefined,     // insert Web THEOplayer license here
  });
```

If no license is provided, only sources hosted on the `theoplayer.com` domain can be played. On Web platforms, CORS rules applied on `theoplayer.com` will also prohibit playing sources from this domain.

### Adaptive Bitrate (ABR) configuration

On Android and Web platforms, you can control the ABR configuration using `player.abr` on the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts). We refer to the [Adaptive Bitrate (ABR)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/abr.md) page for detailed information, including examples.

### Chromeless vs. Chromefull

`PlayerConfiguration.chromeless` relates to whether the underlying *native* SDK provides the UI or not. If `chromeless = true`, the player does not include the native UI provided by the SDK and it is expected the UI is created in React Native. The accompanying example application provides a basic UI created in React Native.

### Native UI language

`PlayerConfiguration.ui` has a configuration property 'language' that allows you to set the language for localisation when native UI elements (e.g. 'skip ad' being displayed on the skip butten in the ad UI) are presented to the user. This only applies to UI elements rendered by the native SDK's and not to other UI elements added via your react-native view stack.

## Setting a source

You can set a source using the `source` property on the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts). The type definition of `SourceDescription` maps to the type used in the [Web SDK's documentation](https://www.theoplayer.com/docs/theoplayer/v10/api-reference/web/interfaces/SourceDescription.html).

```typescript
player.source = {
    "sources": {
        "src": "https://cdn.theoplayer.com/video/elephants-dream/playlist-single-audio.m3u8",
        "type": "application/x-mpegurl"
    }
}
```

## Seeking to a position in a stream

Changing the player's current time, or seeking to a specific timestamp, is done by setting `currentTime` on the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts). Timestamps are measured in milliseconds.

```typescript
player.currentTime = 20_000; // msec
```

## Text tracks and media tracks

The text tracks and media tracks available in the stream are provided by the `PlayerEventType.LOADED_METADATA` event, which is dispatched by the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts).

```typescript
import { PlayerEventType } from "./PlayerEventMap";
import { LoadedMetadataEvent } from "./PlayerEvent";

const onLoadedMetadata = (event: LoadedMetadataEvent) => {
  console.log(TAG, 'loadedmetadata', JSON.stringify(event));
};

player.addEventListener(PlayerEventType.LOADED_METADATA, onLoadedMetadata)
```

The `PlayerEventType.TEXT_TRACK_LIST` event can be used to dynamically listen to text tracks that are being added, removed or changed. Similarly, for text track cues, the `PlayerEventType.TEXT_TRACK` event provides knowledge on cues being added or removed.

The `PlayerEventType.MEDIA_TRACK_LIST` event can be used to dynamically listen to audio and video tracks (being added, removed or changed). On Android and Web, media tracks trigger the `PlayerEventType.MEDIA_TRACK` callback with information on quality changes. This information is not available on iOS systems.

## Preview thumbnails

Preview thumbnails are contained in a dedicated thumbnail track, which is a text track of kind `metadata` with label `thumbnails`. The track can be either side-loaded to the stream source, or contained in a stream manifest, as the demo sources in the [example application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/example-app.md) demonstrate. The example also contains an implementation of a thumbnail viewer.

## Buffering state changes

The `PlayerEventType.WAITING` event is dispatched to indicate that the player has stopped playback because the next frame's data is currently unavailable, but is expected to come in soon. It could be coupled to an activity indicator that is part of the UI. The `PlayerEventType.PLAYING` event is dispatched once playback continues.

Alternatively, changes in `readyState` could be observed through the `PlayerEventType.READYSTATE_CHANGE` event. Since this value can sometimes switch radically, it is advised to add a time-out when using `PlayerEventType.READYSTATE_CHANGE` in combination with a UI loading indicator.

The UI of the [example application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/example-app.md) illustrates a possible implementation.

---

# Example Application

The example application on our `react-native-theoplayer` [git repository](https://github.com/THEOplayer/react-native-theoplayer/tree/develop/example) demonstrates how the use the player with the `THEOplayerView` component and the UI components from `@theoplayer/react-native-ui`.

The example app depends on [`react-native-tvos`](https://github.com/react-native-tvos/react-native-tvos), a fork of the main `react-native` repository, to properly include support for Apple TV.

In this section we cover building and running the example app. If you would like to know more about the `DefaultTHEOplayerUi` and all the other UI components, visit [our React Native UI project](https://github.com/THEOplayer/react-native-theoplayer-ui).

| ![basic-ui](/pr-932/assets/images/example-app-player-ui-028fd4ae776c8d714aa787cd82c253ab.png) | ![basic-ui-source](/pr-932/assets/images/example-app-source-selection-979c83bc37ef94a4fcbb927019a82470.png) | ![basic-ui-source](/pr-932/assets/images/example-app-thumbnails-c6e829c4ae972be8051033369e3d3629.png) |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| The `DefaultTHEOplayerUi` in action.                                                          | Choosing a demo source from a custom UI component.                                                          | Preview thumbnails.                                                                                   |

## Building the example application

Clone the repository and install the dependencies for the `react-native-theoplayer` package:

```bash
$ git clone react-native-theoplayer
$ cd react-native-theoplayer
$ npm i
```

Install dependencies for the example application:

```bash
$ (cd example && npm i)
```

For iOS and tvOS, also make sure to install pod dependencies

```bash
$ (cd example/ios && pod install)
```

Make sure to configure your [THEOplayer license](https://portal.theoplayer.com/) in the [app config](https://github.com/THEOplayer/react-native-theoplayer/blob/-/example/src/App.tsx).

Finally, after making sure the necessary development tools are installed, build & deploy the example:

```bash
$ cd example
$ npm run android
$ npm run ios
$ npm run web
```

---

# Adaptive Bitrate (ABR)

## Overview

The playback quality during play-out of a stream is determined by the ABR algorithm. On starting play-out of a stream, the ABR `strategy` determines which quality to prefer, while during play-out the network's bandwidth is monitored to select an optimal quality.

More information on ABR can be found on our [THEOplayer website](https://www.theoplayer.com/blog/abr-bandwidth-usage) and [demo page](https://www.theoplayer.com/theoplayer-demo-optimized-video-abr).

In this document we will outline how to affect the ABR algorithm, setting a preferred quality or set of qualities and subscribe to related events.

## ABR Configuration

The [ABR Configuration](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/abr/ABRConfiguration.ts) determines which initial quality the player will download, depending on the chosen strategy, as well as various parameters of the playback buffer.

```tsx
 const onPlayerReady = (player: THEOplayer) => {
  player.abr.strategy = ABRStrategyType.quality;
  player.abr.targetBuffer = 20;
  player.abr.bufferLookbackWindow = 30;
  player.abr.maxBufferLength = 30;
}

<THEOplayerView
  config={playerConfig}
  onPlayerReady={onPlayerReady}
/>
```

| Property                     | Description                                                                                                                                                      | Supported Platforms |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `strategy`                   | The adaptive bitrate strategy. Possible values are `'performance'`, `'quality'`, `'bandwidth'` or a `ABRStrategyConfiguration` object. Default is **bandwidth**. | Android/Web/iOS\*   |
| `targetBuffer`               | The amount that the player should buffer ahead of the current playback position, in seconds. Default is **20**s.                                                 | Android/Web/iOS     |
| `bufferLookbackWindow`       | The amount of data which the player should keep in its buffer before the current playback position, in seconds. Default is **30**s.                              | Web                 |
| `maxBufferLength`            | The maximum length of the player's buffer, in seconds.                                                                                                           | Web                 |
| `preferredPeakBitRate`       | A preferred upper limit on the bandwidth of the video to be downloaded, in bits per second. Defaults to `0`, which indicates there is no limit.                  | iOS                 |
| `preferredMaximumResolution` | A preferred upper limit on the resolution of the video to be downloaded. `(0,0)` (the default) removes the cap.                                                  | Android & iOS       |

\* On native iOS/tvOS, `strategy` will only work with THEOlive and Millicast streams, and will not have any effect for other types of streams.

When specifying the strategy, apart from the values `'performance'`, `'quality'`, `'bandwidth'`, an `ABRStrategyConfiguration` object can be set with an estimate for the initial bitrate value (in bits per second):

```typescript
const strategyConfig: ABRStrategyConfiguration = {
  type: ABRStrategyType.bandwidth,
  metadata: {
    'bitrate': 1200000
  }
}
player.abr.strategy = strategyConfig;
```

To cap the resolution of the variant the player downloads, set `preferredMaximumResolution` to a `Resolution` (`{width, height}`). Pass `(0, 0)` to remove the cap.

```typescript
player.abr.preferredMaximumResolution = { width: 1280, height: 720 };
```

## Setting Target Video Quality

By default, the ABR algorithm will choose, depending on the available bandwidth, from all the video qualities that are available in the manifest or playlist.

It is possible to set a specific quality, or subset of qualities, that should be retained as a source set by passing the `uid` to the `targetVideoQuality` property on the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts).

```tsx
const selectedVideoQuality: number | number[] | undefined = [33, 34, 35]
player.targetVideoQuality = selectedVideoQuality;
```

## Subscribing to track events

The `onMediaTrackListEvent` and `onMediaTrackEvent` callback properties on `THEOplayerView` provide a way to perform actions when the track list is modified, or when a track's current quality changes:

| Event name              | Event                                                                                                                                                         | Supported Platforms |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `onMediaTrackListEvent` | when a media track list event occurs, for `trackType` with value `Audio` or `Video`, and event `type` with values `AddTrack`, `RemoveTrack` or `ChangeTrack`. | Android & Web       |
| `onMediaTrackEvent`     | when a media track event occurs, for `trackType` with value `Audio` or `Video`, and event `type`, which currently is only `ActiveQualityChanged`.             | Android & Web       |

### Setting a preferred video quality across period switches and discontinuities

Subscribing to the `AddTrack` event on `onMediaTrackListEvent` for video tracks makes it possible set a fixed preferred video quality, even when a stream's track list changes due to a DASH period switch or an HLS discontinuity (for example during an ad break).

```tsx
const onMediaTrackListEvent = (event: MediaTrackListEvent) => {
  const {subType, trackType} = event;
  if (trackType === MediaTrackType.VIDEO && subType === TrackListEventType.ADD_TRACK) {
    const {qualities, activeQuality: currentActiveQuality} = event.track;

    // Try to set a preferreed quality
    const targetQuality = qualities.find(q => q.bandwidth === preferredBandwidth);
    if (targetQuality) {
      const {uid} = targetQuality;
      this.player.targetVideoQuality = uid;
    }
  }
};

const onPlayerReady = (player: THEOplayer) => {
  this.player = player;
  this.player.addEventListener(PlayerEventType.MEDIA_TRACK_LIST, onMediaTrackListEvent)
}

<THEOplayerView
  config={playerConfig}
  onPlayerReady={onPlayerReady}
/>
```

---

# Advertisements

## Overview

A good starting point to get acquainted with THEOplayer's advertising features is THEOplayer's [Knowledge Base](https://www.theoplayer.com/docs/theoplayer/knowledge-base/advertisement/user-guide/).

While THEOplayer supports a wide range of different [ad types](https://www.theoplayer.com/docs/theoplayer/knowledge-base/advertisement/user-guide/#an-overview-of-theoplayers-different-ad-types), `react-native-theoplayer` currently supports:

* client-side ad insertion (CSAI) through [Google IMA](#getting-started-with-google-ima)
* server-side ad insertion (SSAI) through [Google DAI](#getting-started-with-google-dai).
* server-guided ad insertion (SGAI) through [THEOads](#getting-started-with-theoads).

In the next section we discuss how to integrate them on each platform.

Additional functionality, such as scheduling ads at runtime, is provided by the [ads API](#using-the-ads-api).

The final section describes how to subscribe and add custom logic to [ad events](#subscribing-to-ad-events).

## Getting started with Google IMA

### Configuration

First enable Google IMA support, which requires a different approach on each platform.

Android/AndroidTV

The Android SDK is modular-based, so enabling Google IMA is limited to including the ima extension in gradle by setting this flag in your `gradle.properties`:

```text
# Enable THEOplayer Extensions (default: disabled)
THEOplayer_extensionGoogleIMA = true
```

iOS/tvOS

To enable Google IMA you can add the "GOOGLE\_IMA" [feature flag](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/creating-minimal-app.md#getting-started-on-ios-and-tvos) to `react-native-theoplayer.json` (or `theoplayer-config.json`)

Web

To enable Google IMA on web, it suffices to add this script in the web page's header section, as shown in the example app's [index.html](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/example/web/public/index.html):

```html

<head>
  <!-- Optionally load Google IMA/DAI libraries -->
  <script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
</head>
```

### Source description

When providing the player with a source that includes a list of ads, make sure to set the `integration` property to `"google-ima"`, as shown in one of the sources of the example app:

```typescript
const imaSource = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/dash/webvtt-embedded-in-isobmff/Manifest.mpd',
      type: 'application/dash+xml',
    },
  ],
  ads: [
    {
      integration: 'google-ima' as AdIntegrationKind,
      sources: {
        src: 'https://cdn.theoplayer.com/demos/ads/vast/dfp-preroll-no-skip.xml',
      },
    },
  ],
};
```

The API's [`AdSource`](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/source/ads/Ads.ts) description provides additional information on the configurable properties.

It is also possible to pass a configuration to the IMA SDK via the `ads` API. For more information see the [GoogleImaConfiguration API](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/src/api/ads/GoogleImaConfiguration.ts).

## Getting started with Google DAI

First enable Google DAI support, which requires a different approach on each platform.

Android/AndroidTV

The Android SDK is modular-based, so enabling Google DAI is limited to including the dai extension in gradle by enabling this flag in your `gradle.properties`:

```text
# Enable THEOplayer Extensions (default: disabled)
THEOplayer_extensionGoogleDAI = true
```

Note that DAI support for Android is available as of SDK version 4.3.0.

iOS

Google DAI is part of the Google IMA SDK. To enable it, you add the "GOOGLE\_IMA" [feature flag](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/creating-minimal-app.md#getting-started-on-ios-and-tvos) to react-native-theoplayer.json (or theoplayer-config.json)

Web

To enable Google DAI on web, it suffices to add this script in the web page's header section, as shown in the example app's [index.html](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/example/web/public/index.html):

```html

<head>
  <!-- Optionally load Google IMA/DAI libraries -->
  <script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
</head>
```

### Source description

Providing a Google DAI source description to the player requires providing an `ssai` object and specifying `"google-dai"` as integration type:

```typescript
const daiSource = {
  sources: {
    ssai: {
      integration: 'google-dai',
      availabilityType: 'vod',
      contentSourceID: '2528370',
      videoID: 'tears-of-steel',
    } as GoogleDAIVodConfiguration,
  },
};
```

A full description of the available source properties can be found in the [API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/source/ads/ssai/GoogleDAIConfiguration.ts) definition.

## Getting started with THEOads

THEOads is an ad-insertion service for both VOD and LIVE content, created by THEO Technologies, utilizing Server-Guided Ad-Insertion (SGAI). For more information we refer to the [THEOads](https://www.theoplayer.com/docs/theoads/) documentation.

## Using the Ads API

[THEOplayer](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts) provides an [AdsAPI](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/ads/AdsAPI.ts) that enables additional features such as:

* Querying whether an ad is currently playing;
* Skipping the current ad (if possible);
* Getting the ad break that is currently playing;
* Getting a list of ads that are currently playing (only available for web);
* Getting a list of ad breaks that are still scheduled. Once an ad break starts, it is removed from the list;
* Manually scheduling a client-side ad.

The `THEOplayer` is provided with a callback on the `THEOplayerView` component:

```tsx
const onPlayerReady = (player: THEOplayer) => {
  this.player = player;
}

<THEOplayerView onPlayerReady={onPlayerReady}/>
```

After which the AdsAPI can be used:

```typescript
const isPlayingAd = () => {
  return this.player.ads.playing();
};
```

Google DAI has its own [API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/ads/GoogleDai.ts), which includes DAI-specific features, such as converting time stamps between stream time and content time, and manipulating the `snapback` flag that prevents users from seeking across ad breaks.

```typescript
// Convert timestamps using the DAI ads api.
const streamTimeForContentTime = (contentTime: number): Promise<number> | undefined => {
  return this.player.ads.dai?.streamTimeForContentTime(contentTime);
};
```

### Manually scheduling a client-side ad

The Ad API allows you to manually schedule an ad break at runtime:

```tsx
player.ads.schedule({
  integration: AdIntegrationKind.google_ima,
  timeOffset: 1e-3 * (player?.currentTime ?? 0) + 3, // in 3 seconds from now
  // timeOffset: 10,    // at 10 seconds in the content
  // timeOffset: '50%', // at 50% of the content duration
  sources: {
    src: 'https://cdn.theoplayer.com/demos/ads/vast/dfp-preroll-no-skip.xml',
  },
});
```

## Subscribing to ad events

[THEOplayer](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts) allows you to subscribe to ad events:

```typescript
const onAdEvent = (event: AdEvent) => {
  console.log(event)
}
player.addEventListener(PlayerEventType.AD_EVENT, onAdEvent);
```

See [AdEvent](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/event/AdEvent.ts), [Ad](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/ads/Ad.ts) and [AdBreak](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/ads/AdBreak.ts) for more information.

Note that the availability of the events being dispatched depends on the platform.

---

# Audio Control Management on Android

## Overview

Android allows multiple apps to play audio concurrently, but this can lead to a disruptive user experience due to mixed audio streams. To enhance user experience, Android offers an API for apps to control **audio focus**, ensuring only one app possesses audio focus, thus delivering a more favorable user experience.

This section details how `react-native-theoplayer` addresses changes in audio focus, which is available as of version 2.12.0.

References:

* [Android for Developers: Audio focus](https://developer.android.com/reference/android/media/AudioFocusRequest)
* [Android for Developers: "Don't be Noisy"](https://developer.android.com/guide/topics/media/platform/output#becoming-noisy)

## Audio Focus

The `react-native-theoplayer` package is equipped with inherent audio focus management. It initiates an audio focus request upon the start of playback and responds to the loss of audio focus by pausing playback.

If the loss was *transient*, i.e. lasting only for a short while such as during an incoming phone call, the player will regain audio focus afterward and play-out while resume.

### Audio "ducking"

When another app seeks audio focus, it can optionally indicate that the current audio focus holder can lower its playback volume to continue playing (`AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK`). The new focus holder does not require other apps to be silent. This behavior is known as "ducking."

In summary:

| Event                                          | Action                            |
| ---------------------------------------------- | --------------------------------- |
| `AUDIOFOCUS_LOSS`, `AUDIOFOCUS_LOSS_TRANSIENT` | Pause play-out                    |
| `AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK`           | Lower volume                      |
| `AUDIOFOCUS_GAIN`                              | Resume play-out or restore volume |

## Audio Becoming Noisy

When headphones are unplugged or a Bluetooth device is disconnected, the audio stream automatically reroutes to the device's built-in speaker. This can lead to an abrupt increase in volume, which is an undesired outcome.

The "Audio Becoming Noisy" situation is also managed by pausing playback for the `react-native-theoplayer` package.

---

# Background Playback and Notifications

## Overview

One of the key features of `react-native-theoplayer` is its support for background playback, notifications, and lock-screen controls. This feature allows your users to continue listening to audio when the app is not in the foreground, and control playback using notifications and lock-screen controls.

## Configuration

The `backgroundAudioConfiguration` player configuration affects the play-out behaviour when the app is moved to the background: in case the `enabled` property is set to `true`, the current media asset will continue playing when the app is moved to the background, otherwise play-out will pause.

The configuration can be modified at run-time, allowing the player to pause depending on the current media asset's properties, or whether an ad is playing or not.

```typescript
player.backgroundAudioConfiguration = { enabled: true };
```

Other properties of the `backgroundAudioConfiguration` can be used to further customize the background playback:

| Field                           | Platform           | Purpose                                                                                                                                                               | Default                           |
| ------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `enabled`                       | Web, iOS & Android | If enabled, playback continues when transitioning to background.                                                                                                      | `false`                           |
| `stopOnBackground`              | Web, iOS & Android | If enabled, fully stop playback when the app goes to the background. The player will need to be provided with a new source when the app comes back to the foreground. | `false`                           |
| `shouldResumeAfterInterruption` | iOS                | Controls whether playback should automatically resume after an interruption, such as an incoming phone call.                                                          | `false`                           |
| `audioSessionMode`              | iOS                | Specifies the [AVAudioSession.Mode](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode)                                                           | `AudioSessionMode.MOVIE_PLAYBACK` |

A use case for enabling `stopOnBackground` could be a live stream that should not be allowed to continue in the background, neither in paused nor playing state. The app should be designed to reload the source or the player page when coming back to the foreground.

Picture-in-picture is an exception to `stopOnBackground`: when the player transitions to a PiP window while the app goes to the background, play-out is not stopped. Instead, the stop is postponed until the PiP window is closed while the app is still in the background. There is no need to modify the `backgroundAudioConfiguration` on `presentationmodechange` events to achieve this behaviour. In case play-out should stop when the PiP window is closed, but continue when the app is backgrounded without PiP, keep `stopOnBackground` disabled and clear the player's source from the `presentationmodechange` event instead, as described in [Picture-in-Picture](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/pip.md).

### Android

On Android, a [service](https://developer.android.com/guide/components/services) is used to continue playback in the background while the user is not interacting with the app.

It is possible to disable the service at build time by setting the build config field `'THEOplayer_usePlaybackService = false'`. In that case the background playback feature is always disabled, no notifications are displayed, and the player will always pause when the hosting app goes to the background.

## Notifications, Metadata and Lockscreen Controls

During play-out of a media asset, a notification is displayed that provides some metadata and enables basic control. The source description passed to the player should provide the necessary metadata properties:

```typescript
const source = {
  // ...
  poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
  metadata: {
    title: 'My stream title',
    subtitle: 'A subtitle or artist',
    nowPlayingServiceIdentifier: 'serviceId',
    nowPlayingContentIdentifier: 'contentId',
    displayIconUri: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
  }
}
```

The following fields from the source description are used to display information in the lockscreen:

| Field                                                                | Purpose           |
| -------------------------------------------------------------------- | ----------------- |
| `source.metadata.title`                                              | Lockscreen title  |
| `source.metadata.artist` with fallback to `source.metadata.subtitle` | Lockscreen artist |
| `source.metadata.displayIconUri` with fallback to `source.poster`    | Lockscreen image  |

The following fields allow additional configuration for the lockscreen behaviour on iOS:

| Field                                         | Purpose                          |
| --------------------------------------------- | -------------------------------- |
| `source.metadata.nowPlayingServiceIdentifier` | Info property service identifier |
| `source.metadata.nowPlayingContentIdentifier` | Info property content identifier |

| ![notification\_android](/pr-932/assets/images/notification_android-d782297b7b92dc30e196b0000efdd7a7.png) | ![notification\_ios](/pr-932/assets/images/notification_ios-3ac8d1563482c7b4728aa098f9034dbc.png) | ![notification\_web](/pr-932/assets/images/notification_web-9e1124ac683eb295ff71adea39052c50.png) |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Android                                                                                                   | iOS                                                                                               | Web                                                                                               |

### Configuration

The `mediaControl` property of `PlayerConfiguration` hosts properties that affect the notifications, media sessions and controls on each platform. The following table describes the available configuration options:

| Field                  | Platform           | Purpose                                                                                                                                                                         | Default                         |
| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `mediaSessionEnabled`  | Web, iOS & Android | If disabled, no media session properties or actions will be set. On iOS this means no Now Playing info is published and no remote command (including custom action) is handled. | `true`                          |
| `skipForwardInterval`  | Web, iOS & Android | The amount of seconds the player will skip forward.                                                                                                                             | `5` (Web & Android), `15` (iOS) |
| `skipBackwardInterval` | Web, iOS & Android | The amount of seconds the player will skip backward.                                                                                                                            | `5` (Web & Android), `15` (iOS) |
| `convertSkipToSeek`    | iOS & Android      | A flag that allows next/previous track commands to be interpreted as skip forward/backward commands, according to the configured skip intervals.                                | `false`                         |
| `allowLivePlayPause`   | iOS & Android      | A flag that indicates whether play/pause controls for live streams are enabled.                                                                                                 | `true` (iOS), `false` (Android) |
| `seekToLiveOnResume`   | iOS & Android      | A flag that controls whether to seek to the live edge when resuming a paused live stream. Note that `allowLivePlayPause` needs to be enabled for this property to have effect.  | `false`                         |

---

# Casting with Chromecast and Airplay

## Overview

The basics of both Chromecast and Airplay are well-described in THEOplayer's [Knowledge Base](https://www.theoplayer.com/docs/theoplayer/how-to-guides/cast/chromecast/introduction/). The `react-native-theoplayer` package has support for both.

This page first outlines the setup needed for Chromecast and Airplay, and then describes the player's cast API and events subscription, which is common for both.

## Chromecast

### Setup

To enable Chromecast, react-native-theoplayer provides a cast module on the player (player.cast) that allows you to start/stop/join/leave chromecast sessions. The THEOplayer SDK will take care of the interactions with the cast receiver (communicating source updates, seeking, play/pause, ...) and route all cast events through its API.

We can also recommend the [`react-native-google-cast`](https://github.com/react-native-google-cast/react-native-google-cast) package, which comes with native support for both iOS and Android. It is fully-featured and provides the possibility to manage devices and cast sessions, send new source descriptions and listen for cast events. It also includes a `<CastButton>` component that can be added to the app's UI, as demonstrated in the [example app](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/example-app.md).

```tsx
<CastButton
  style={styles.castButton}
  tintColor={chromecastConnected ? '#ffc50f' : 'white'}
/>
```

This button represents a native media route button that shows the connection state and opens a device dialog when tapped. Using `react-native-google-cast`'s functionality does require some extra steps, such as communicating source updates, managing player status on both sender and receiver and handling the cast events. Our react-native-theoplayer integration already takes care of these tasks. The [installation instructions](https://react-native-google-cast.github.io/docs/getting-started/installation) for `react-native-google-cast` cover the steps to enable support for Chromecast in your app through that component.

For the rest of this document we assume that THEOplayer handles this logic. Enabling the player with Chromecast support requires a different approach on each platform.

Android

The Android SDK is modular-based, so enabling Chromecast is limited to:

1. Including the cast extension in gradle by setting this flag in your `gradle.properties`:

```bash
# Enable THEOplayer Extensions (default: disabled)
THEOplayer_extensionCast = true
```

2. Adding a native `CastOptionsProvider` class and referring to it from the app's Android manifest:

```xml
<meta-data
  android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
  android:value="com.reactnativetheoplayer.cast.CastOptionsProvider" />
```

Check the example app for details on this setup.

3. Initializing the `CastContext` in your app's MainActivity:

```java
@Override
public void onCreate(Bundle savedInstanceState) {
    CastContext castContext = CastContext.getSharedInstance(this);
}
```

iOS

#### Add feature flag to config

To enable Chromecast you need to add the "CHROMECAST" [feature flag](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/creating-minimal-app.md#getting-started-on-ios-and-tvos) to react-native-theoplayer.json (or theoplayer-config.json)

#### iOS Configuration

Specify NSBonjourServices in your Info.plist to allow local network discovery to succeed on iOS 14. You will need to add both \_googlecast.\_tcp and \_\[your-app-id].\_googlecast.\_tcp as services for device discovery to work properly.

Update your applications info.plist with the following example NSBonjourServices definition, replacing "ABCD1234" with your appID.

```xml

<key>NSBonjourServices</key>
<array>
<string>_googlecast._tcp</string>
<string>_ABCD1234._googlecast._tcp</string>
</array>
```

We also recommend that you customize the message shown in the Local Network prompt by adding an app-specific permission string in your app's Info.plist file for the NSLocalNetworkUsageDescription such as to describe Cast discovery and other discovery services.

```xml

<key>NSLocalNetworkUsageDescription</key>
<string>${PRODUCT_NAME} uses the local network to discover Cast-enabled devices on your WiFi
network.
</string>
```

#### Combining with react-native-google-cast

When using react-native-google-cast to render the CastButton, their documentation suggest to setup the CastContext as soon as possible. We noticed that waiting to prepare this context to a later point in time (i.e. till the AppId is bridged from RN) fails to display that CastButton. To prevent this follow the [instructions](https://react-native-google-cast.github.io/docs/getting-started/setup#ios) (or check our example application) to setup the GCKCastContext in the AppDelegate.

The following options on the GCKCastOptions can be set as desired:

1. options.startDiscoveryAfterFirstTapOnCastButton = false; (set up how/when the castbutton is shown)
2. options.suspendSessionsWhenBackgrounded = false; (set up the connection response be when backgrounding the app)

In addition, react-native-google-cast currently does not include a full featured (guest mode combined with Apple M1 support) setup of the Google Cast SDK. Our THEOplayerCastIntegration however does, but combining both results in a clash of dependencies (both delivering a GoogleCast.xcframework). To overcome this double dependency we suggest to use a [fork of react-native-google-cast](https://github.com/Danesz/react-native-google-cast/tree/feature/guestmode_apple_silicon) that depends on the same GoogleCast.xcframework. To achieve this:

1. Add the following to your applications podFile:

```ruby
pod 'react-native-google-cast', :git => 'https://github.com/Danesz/react-native-google-cast.git', branch: 'feature/guestmode_apple_silicon'
```

2. Prevent the autolinking of the original by updating your react-native.config.js with:

```json
'react-native-google-cast': {
	platforms: {
		ios: null,
	},
},
```

Web

The `react-native-google-cast` package has no support for Web yet. If the THEOplayer Web SDK's default UI is used however, the cast button will be included here and there is no need to install `react-native-google-cast`.

The web page hosting the player just needs to load the Google cast sender module:

```html

<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
```

### THEOplayerView configuration

In the configuration of a `THEOplayerView` component you can set the receiver's appID. This only makes sense on a Web platform, as for mobile platforms this value is already set natively through `CastOptionsProvider` on Android and `AppDelegate` on iOS:

```javascript
const playerConfig: PlayerConfiguration = {
  cast: {
    chromecast: {
      appID: '<receiverAppID>'
    },
    strategy: 'auto'
  }
}
```

The [example app](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/example-app.md) sets appID to `'CC1AD845'`, which refers to Google's default V3 receiver. This receiver implementation will know how to play the manifest/playlist URL sent by THEOplayer, but it does not have knowledge on how to handle any additional information from the source description provided through the `MediaInfo.customData` [field](https://developers.google.com/android/reference/com/google/android/gms/cast/MediaInfo.Builder#public-mediainfo.builder-setcustomdata-jsonobject-customdata). As a consequence, to enable playback of for example DRM-protected streams or ads, a custom receiver needs to be created that also handles these parts of the source description.

We refer to our [sample-google-cast-v3-receiver](https://github.com/THEOplayer/samples-google-cast-v3-receiver/) repository for an example on how to interpret a THEOplayer source description and handle a custom DRM flow.

### Cast strategy

The `strategy` property indicates the *join strategy* that will be used when starting/joining sessions:

* `auto`: The player will automatically join a cast session if one exists when play is called.
* `manual` (**default**): The player needs to start or join the session manually using its cast API. See next section for details.
* `disabled`: The player is not affected by cast sessions and is not castable.

In case the join strategy `manual` is chosen and a cast session is started by `react-native-google-cast`, it is necessary to explicitly let the player either join or take over the current session. This can be done by listening to the cast state and using the player's cast API to either start or join:

```typescript
import CastContext, {CastState} from "react-native-google-cast";

useEffect(() => {
  const subscription = CastContext.onCastStateChanged((castState) => {
    if (castState === CastState.CONNECTED) {
      // Let the player either start or join the session.
      player.cast.chromecast?.start();
    }
  })
  return () => subscription.remove()
}, [])
```

The [example app](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/example-app.md) uses strategy `auto` so the player will automatically send its source description when a session is created.

### Providing metadata

The `metadata` object, as part of the source configuration, is used to send additional information to the receiver. Common fields include `poster`, `title`, `subtitle`, `album` and `artist`.

```json
{
  "sources": [
    {
      "src": "https://cdn.theoplayer.com/video/dash/bbb_30fps/bbb_with_multiple_tiled_thumbnails.mpd",
      "type": "application/dash+xml"
    }
  ],
  "poster": "https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg",
  "metadata": {
    "title": "Big Buck Bunny",
    "subtitle": "a Peach Open Movie Project",
    "album": "React-Native THEOplayer demos",
    "artist": "THEOplayer"
  }
}
```

| ![Chromecast](/pr-932/assets/images/chromecast-7c3da07d98fad160f3f582a8b7459607.png) |
| ------------------------------------------------------------------------------------ |
| Casting a stream with metadata.                                                      |

## AirPlay

On iOS and Web Safari, along with Chromecast, AirPlay is also supported. Similar to Chromecast, you can listen to or check the AirPlay cast state and use the player's AirPlay API to either start or join an AirPlay session. When implementing a simple AirPlay button you can toggle AirPlay using:

```typescript
player.cast.airplay?.state().then((airplayCastState) => {
  const inConnection = airplayCastState === 'connected' || airplayCastState === 'connecting'
  if (inConnection) {
    player.cast.airplay?.stop()
  } else {
    player.cast.airplay?.start()
  }
})
```

## Cast API

The `THEOplayerView` provides the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts) using the `onPlayerReady` callback, where you can access the [CastAPI](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/event/CastEvent.ts) to control or start cast sessions, either Chromecast or AirPlay.

## Subscribing to Cast Events

The `THEOplayerView` provides the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts) using the `onPlayerReady` callback, where you can subscribe to cast events:

```tsx
const onCastEvent = (event: CastEvent) => {
    console.log(event);
}

const onReady = (player: THEOplayer) => {
    player.addEventListener(PlayerEventType.CAST_EVENT, onCastEvent);
}

<THEOplayerView onPlayerReady={onReady}/>
```

---

# Getting started with CMCD on React Native

Media player clients can transmit useful information to Content Delivery Networks (CDNs) with each object request. This implementation is planned to fully support Common Media Client Data (CMCD) as defined in [CTA-5004-B](https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html), published in April 2026.

CMCD supports two modes of transmission:

* **Request mode**: CMCD data is sent as HTTP headers or query parameters on manifest and media segment requests.
* **Event mode** (available since v11.4.0): CMCD events are POSTed to configured HTTP endpoints.

## Request mode

To enable CMCD request mode, developers need to explicitly set the `transmissionMode` parameter inside a SourceDescription.

```tsx
const source = {
  sources: [ /* ... */ ],
  /* ... */
  cmcd: {
    transmissionMode: CmcdTransmissionMode.SDK_DEFAULT
    /* ... */
  }
} as SourceDescription;
player.source = source;
```

By specifying the `transmissionMode` as `SDK_DEFAULT`, we let each SDK decide which transmission mode to use:

* Web: HTTP query argument
* iOS: custom HTTP request header (only option)
* Android: HTTP query argument

On Web and Android, you can force a specific transmission mode by providing a different value, e.g.

```tsx
const source = {
  sources: [ /* ... */ ],
  /* ... */
  cmcd: {
    transmissionMode: CmcdTransmissionMode.HTTP_HEADER
    /* ... */
  }
} as SourceDescription;
player.source = source;
```

On Web, there are additional configuration options. For more details, visit the API references.

### Remarks

* Note that CMCD request mode is only supported on iOS 18.0+.
* Note that using a custom HTTP header from a web browser user-agent will trigger a preflight OPTIONS request before each unique media object request. This will lead to an increased request rate against the server. As a result, for CMCD transmissions from web browser user-agents that require CORS-preflighting per URL, the preferred mode of use is query arguments.

## Event mode

Event mode allows posting CMCD events to configured HTTP endpoints.

> **Info**
>
> Event mode is supported starting from version 11.4.0.

### Player-level configuration

```javascript
const player = new THEOplayer.Player(element, {
  cmcd: {
    externalSessionId: 'YOUR-EXTERNAL-SESSION-ID', // optional
    userId: 'YOUR-USER-ID', // optional
    eventEndpoints: [{ url: 'https://example.com/cmcd-event-endpoint' }],
  },
});
```

### Source-level configuration

```javascript
player.source = {
  sources: [ /* ... */ ],
  /* ... */
  cmcd: {
    externalSessionId: 'YOUR-EXTERNAL-SESSION-ID', // optional
    sessionID: 'YOUR-SESSION-ID', // optional
    userId: 'YOUR-USER-ID', // optional
    eventEndpoints: [{ url: 'https://example.com/cmcd-event-other-endpoint' }],
  },
};
```

### Merging behavior

* Source-level values take precedence for `externalSessionId` and `userId`.
* `eventEndpoints` from both levels are **merged** (both player and source endpoints receive events).

> **Warning**
>
> Event mode reporting currently only supports DRM and ad events.

---

# Matching the TV display to the content

On tvOS, a television often supports several display modes: a range of refresh rates and dynamic range formats such as SDR, HDR10 or Dolby Vision. By default the app renders in the mode that tvOS was configured with, which means content is converted to that mode: a 24fps Dolby Vision movie played on a 60Hz SDR output loses both its cadence and its dynamic range.

Setting `manageContentMatching` to `true` lets the player pick the display mode that fits the content it is about to play, before playback starts:

```typescript
player.manageContentMatching = true;
```

The property defaults to `false`, and can be changed at any time during the lifetime of the player.

## Remarks

* The property is only supported on tvOS. On all other platforms, setting it has no effect.
* The player only applies the display criteria while it is presented in `PresentationMode.fullscreen`.
* The display only follows these criteria when the viewer enabled content matching on the TV in **Settings > Video and Audio > Match Content**.
* Switching display mode can briefly blank the screen, so only enable it on a single, fullscreen player, and preferably not while another player is producing frames.

## Use case: a movie kiosk with auto-playing trailers

Consider a movie catalogue where selecting an item auto-starts its trailer in an inline preview player, and tapping the item opens the movie fullscreen.

The trailer is a preview next to the catalogue UI: it is short, it is interrupted every time the viewer moves to another item, and a display mode switch would blank the screen on every selection. So content matching stays disabled for it. Once the viewer commits to the movie and the player goes fullscreen, content matching is enabled so the TV switches to the movie's frame rate and dynamic range - the Dolby Vision presentation the movie was mastered in.

Because the flag only needs to be correct before playback starts, it can be flipped together with the presentation mode:

```typescript
const playTrailer = (trailer: SourceDescription) => {
  // A preview next to the catalogue: keep the display mode as it is.
  player.manageContentMatching = false;
  player.presentationMode = PresentationMode.inline;
  player.source = trailer;
  player.autoplay = true;
};

const playMovie = (movie: SourceDescription) => {
  // The main feature: let the TV match the frame rate and dynamic range of the movie.
  player.manageContentMatching = true;
  player.presentationMode = PresentationMode.fullscreen;
  player.source = movie;
  player.autoplay = true;
};
```

If the app instead lets the viewer expand the running trailer to fullscreen, keep the flag in sync with the presentation mode. Note that the display criteria are applied when a source starts loading, so an already playing stream keeps its current display mode until the next source:

```typescript
player.addEventListener(PlayerEventType.PRESENTATIONMODE_CHANGE, (event: PresentationModeChangeEvent) => {
  player.manageContentMatching = event.presentationMode === PresentationMode.fullscreen;
});
```

---

# Digital Rights Management (DRM)

## Overview

This section outlines how play-out of DRM protected content can be achieved with `react-native-theoplayer`. A detailed explanation on how DRM (Digital Rights Management) works can be found in [THEOplayer's knowledge base](https://www.theoplayer.com/docs/theoplayer/knowledge-base/content-protection/introduction/).

## Configuration

THEOplayer supports Fairplay, PlayReady and Widevine by default. Configuring a DRM protected stream source with `react-native-theoplayer` is very similar to how it is done for the Web SDK, by providing a `contentProtection` object in the source description.

```javascript
const source = {
  src: "<manifest>",
  type: "application/dash+xml",
  contentProtection: {
    widevine: {
      licenseAcquisitionURL: "https://widevine-dash.ezdrm.com/proxy?pX=..."
    },
    playready: {
      licenseAcquisitionURL: "https://playready.ezdrm.com/cency/preauth.aspx?pX=..."
    },
    fairplay: {
      certificateURL: 'https://fps.ezdrm.com/demo/video/eleisure.cer',
      licenseAcquisitionURL: 'https://fps.ezdrm.com/api/licenses/...'
    }
  }
}
const onReady = (player: THEOplayer) => {
  player.source = source;
}

<THEOplayerView onPlayerReady={onReady}/>
```

## Content Protection Integrations

### Pre-integrations

THEOplayer is [pre-integrated](https://www.theoplayer.com/docs/theoplayer/how-to-guides/drm/introduction/#pre-integrations) with a number of commercial multi-DRM vendors, which means support for these vendors is already included and enabled in the SDK.

In addition to these pre-integrations, the `react-native-theoplayer` SDK as well as all native THEOplayer SDKs, come with the ability to create and register a custom DRM integration.

### Creating a custom protection integration

The implementation of a custom DRM integration for `react-native-theoplayer` is almost identical to the implementation for the Web SDK, and is explained in detail on our [THEOplayer DRM integrations](https://github.com/THEOplayer/samples-drm-integration) repository. This repository also contains a number of examples for well-known multi-DRM vendors.

### Registering a custom protection integration

Once the custom DRM integrations is created, it needs to be registered up-front as follows:

```text
import { ContentProtectionRegistry } from 'react-native-theoplayer';
import { MyCustomFairplayContentProtectionIntegrationFactory } from './drm/MyCustomFairplayContentProtectionIntegrationFactory';

ContentProtectionRegistry.registerContentProtectionIntegration(
  'myCustomDRM',
  'fairplay',
  new MyCustomFairplayContentProtectionIntegrationFactory()
);
```

Finally, the `integrationId` used on registration (in this case `"myCustomDRM"`) should be added to the sourceDescription so that THEOplayer knows which integration to use for this source. Any additional `integrationParameters` needed by the custom integration can be passed here as well.

```javascript
const source = {
  src: "<manifest>",
  type: "application/dash+xml",
  contentProtection: {
    fairplay: {
      certificateURL: 'https://example.domain.com/Certificate.cer',
      licenseAcquisitionURL: 'https://example.domain.com/FairPlay'
    },
    integration: "myCustomDRM",
    integrationParameters: {
      authToken: "<token>",
    }
  }
}
```

---

# Expo

## Overview

[Expo](https://expo.dev/) is an open-source platform built around React Native that simplifies the development of cross-platform mobile applications. It provides a powerful set of tools, libraries, and services that handle much of the native configuration and boilerplate typically required when working directly with React Native.

React Native THEOplayer integrates with Expo through a **dedicated plugin** that allows you to configure the app **without modifying native files**. Currently, the plugin is focused on enabling configuration of THEOplayer extensions.

### THEOplayer Extensions

The `react-native-theoplayer` package includes an Expo plugin that enables THEOplayer extensions through configuration in your app’s `app.json`.

You can configure it globally for all platforms:

```json
{
  "expo": {
    "plugins": [
      [
        "react-native-theoplayer",
        {
          "extensions": ["cast", "dai", "ima", "millicast", "theoads"]
        }
      ]
    ]
  }
}
```

Or specify extensions per platform:

```json
{
  "expo": {
    "plugins": [
      [
        "react-native-theoplayer",
        {
          "ios": {
            "extensions": ["cast", "ima", "millicast", "sideloaded-texttracks","theoads"]
          },
          "android": {
            "extensions": ["cast", "dai", "ima", "millicast", "theoads"]
          }
        }
      ]
    ]
  }
}
```

---

# A Fullscreen Video Player Component

## Fullscreen Video on Web platforms

Transitioning to fullscreen on Web platforms varies depending on the browser.

Browsers that support the [Fullscreen API](https://fullscreen.spec.whatwg.org/) (Chrome, Firefox, Edge, etc.), allow any element to enter fullscreen mode. However, some - like Safari on iOS - restrict fullscreen access to `<video>` elements only.

While this mechanism is hidden from users of the `react-native-theoplayer` SDK, it does affect the resulting user interface.

On browsers that support the Fullscreen API, the player view together with its UI (a child component) will enter fullscreen mode. On the others, a UI with limited **native controls** will be displayed instead.

| ![](/pr-932/assets/images/fullscreen_chrome-6083662fda8a3afc00c6b8e6fa28cb3d.png) | ![](/pr-932/assets/images/fullscreen_ios_safari-5f157710d5ae0aed7fb8584e7fcd22c3.png) |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Fullscreen presentation mode in a Chrome browser.                                 | Fullscreen presentation mode with native controls in iOS Safari.                      |

## Fullscreen Video on iOS and Android

Presenting a fullscreen video player on iOS and Android through React Native poses challenges due to the need to seamlessly transition between the regular view and fullscreen mode, while maintaining playback continuity. This involves managing UI layers, native view hierarchies, and minimizing disruptions during the transition process.

In this section we will present two ways of presenting a fullscreen player component. One that **opens a new screen to present the player**, and a second that **transitions to fullscreen from an inline player**. We will also discuss the related concept of "React Portals", which, when paired with a video player component, offer versatile applications beyond fullscreen display.

### Presenting a fullscreen video player

A native iOS or Android video player that transitions into fullscreen typically creates another activity or view that *overlays the existing view stack*, while activating an immersive mode to maximize screen size. This also introduces a new user interface layer that includes essential playback controls and a method for exiting fullscreen mode.

React Native, as a UI framework, makes it possible to create a screen with UI elements such a buttons and text elements, and provides a means to create stacked views with packages such as [react-native-navigation](https://reactnavigation.org/). It manages the lifecycle of the native UI elements, and may encounter issues when elements are generated outside its control.

When an app integrates a video player that needs the ability to present itself in fullscreen mode, there are typically two possibilities to transition to the fullscreen player:

### 1. A separate player screen

Navigate to a *separate player screen* that contains only the video player presented in an immersive mode.

The first option has the advantage that it is simple and straightforward to implement. The main disadvantage is that transitioning to another screen means recreating (remounting) the player, causing a visual interruption in playback. Typically, this option is used when the first screen has an inline preview image that transitions to a fullscreen player screen when tapped.

### 2. An inline video player

Make the current *inline video player* component stretch itself while covering all elements in the current screen.

The second option is able to let a video play inline with the other screen elements. The player is a part of the view hierarchy and will need to cover the whole screen without remounting the player component.

| ![](/pr-932/assets/images/fullscreen_android-f913c5b9498410bbd0d02e4a622cdff2.gif) | ![](/pr-932/assets/images/fullscreen_ios-eff1f4d528cc8f9f413d3e9ff2d3ddaf.gif) |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Transitioning from an inline player to fullscreen on Android.                      | Transitioning from an inline player to fullscreen on iOS.                      |

The `react-native-theoplayer` SDK supports this option on iOS and Android by **re-parenting** the native view to the top-most node of the view hierarchy when the player's presentation mode is set to `fullscreen`, creating a seamless experience.

```ts
import { PresentationMode } from './PresentationMode';

player.presentationMode = PresentationMode.fullscreen;
```

When the player transitions back to inline mode, the view hierarchy will be restored.

Any child of the`THEOplayerView` component, typically the user interface, will move as well through the view hierarchy.

### Disable re-parenting on Android

On Android, it is possible to disable the re-parenting mechanism by setting build flag `THEOplayer_reparent_on_fullscreen=false` in the app's gradle properties. This could be useful if your app wants to implement its own logic, or re-parent to a different node than the top-most one. [Immersive mode](https://developer.android.com/develop/ui/views/layout/immersive) will still be enabled in this case.

### iOS home indicator

On iOS, a visual bar at the bottom of the screen called the home indicator, allows the user to return to the device's home screen when dragging it up. This is often preceived as a disturbing visual element when viewing a stream in fullscreen mode. To hide the home indicator, The rootViewController of the application needs to be setup accordingly, via inheritance. As part of react-native-theoplayer we've prepared a basic ViewController setup (HomeIndicatorViewController) that takes care of this. To hide the home indicator you change the default rootViewcontroller from a basic UIViewController to our HomeIndicatorViewController:

Import the react-native-theoplayer swift code:

```swift
@import react_native_theoplayer;
```

And, when using RCTAppDelegate in the native app:

```swift
- (UIViewController *)createRootViewController {
  return [HomeIndicatorViewController new];
}
```

or otherwise:

```swift
HomeIndicatorViewController *rootViewController = [HomeIndicatorViewController new];
...
self.window.rootViewController = rootViewController;
```

Our iOS presentationMode changing code checks if the `rootViewController` is of type `HomeIndicatorViewController` and will, in that case, automatically take care of showing/hiding the home indicator.

## Portals for iOS and Android

A [Portal](https://react.dev/reference/react-dom/createPortal#usage) is a well-known concept in React that enables rendering a component in a different location in the DOM view hierarchy. Normally, when a component is rendered, it is mounted into the DOM as a child of the nearest parent node. Sometimes, however, it is useful to let the child mount at a different location in the DOM tree. Internally, the portal will also re-parent the view to a different node in the view hierarchy, similar to the approach `react-native-theoplayer` takes when going to fullscreen.

A typical use case is when the child component needs to "break out" of its container. Examples are dialogs, tooltips, and floating or fullscreen video components. In the next section we will outline the creation of an in-app mini player.

### Using Portals to transition to an in-app mini player

This section introduces a basic example illustrating how Portals facilitate the creation of an inline video component capable of transitioning to a mini player at the bottom of the screen, overlaying the other components.

There are many packages available that bring Portal functionality to React Native. However, we will use [a package](https://www.npmjs.com/package/@alexzunik/rn-native-portals-reborn) that not only renders the component to an alternate location in the DOM tree, but also *relocates the native view to a different parent in the native view hierarchy*. This approach aims to prevent the remounting of the complex video component.

```tsx
export default function App() {
  const [isMiniPlayer, setMiniPlayer] = useState(false);

  const onPlayerReady = (player: THEOplayer) => {
    // set-up player
  }

  return (
    <View style={styles.container}>
      <PortalOrigin destination={isMiniPlayer ? 'miniplayer' : null}>
        <View style={isMiniPlayer ? styles.videoContainerMini : styles.videoContainer}>
          <THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}>
            {player !== undefined && (<UiContainer>{/*left out for clarity*/}</UiContainer>)}
          </THEOplayerView>
        </View>
      </PortalOrigin>

      <View style={styles.contentContainer}>
        <Text style={{ color: '#ffffff' }}>This text will remain on screen when play-out continues into the mini-player.</Text>
      </View>

      <View style={isMiniPlayer ? styles.miniContainer : styles.miniContainerInactive}>
        <PortalDestination name="miniplayer" />
      </View>
    </View>);
}
```

The player component along with its UI container in the example above is wrapped in a `PortalOrigin`. Its destination is left `null` as long as the player is presented inline.

When the `isMiniPlayer` state property is set to `true`, the screen is re-rendered with destination set to `'miniplayer'`. The player component will become a child of the `PortalDestination` with the same name. On a native level the view will also be re-parented to the miniPlayer container at the bottom of the screen.

| ![](/pr-932/assets/images/miniplayer_android-717e2a8d9844bf570d423d5dfe954ff8.gif) | ![](/pr-932/assets/images/miniplayer_ios-0682a98a45d38d6ff021b3aa2b39c82f.gif) |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| A mini-player using Portals on Android                                             | A mini-player using Portals on iOS                                             |

Variants of the approach discussed above put the `PortalDestination` on a dedicated route in a [`NavigationContainer`](https://reactnavigation.org/docs/navigation-container/). This is especially useful in a more complex app that has different routes towards showing the player component.

---

# Limitations and Known Issues

This sections lists any limitations and known issues in the current package version.

## Custom-built THEOplayer SDKs

Dependencies to the underlying THEOplayer SDKs are currently configured in the `react-native-theoplayer` package using various dependency managers:

* Android: Gradle & Maven
* iOS & tvOS: Cocoapods
* Web: npm

This currently poses a limitation on the ability to include a SDK that is custom-built through [THEOplayer Portal](https://portal.theoplayer.com/). A custom-built library (an .aar of Android, framework for iOS and JavaScript library for web) including a specific set of features currently still needs to be configured inside `react-native-theoplayer` package itself.

---

# Media Cache

## Overview

The Media Cache API is available as of v3.0.0 and facilitates the download of media assets for offline playback. This section provides an overview of how to utilize the Media Caching API, create caching tasks, and control the media cache.

The process of caching a media asset involves several steps to enable offline playback. It starts with the creation and initiation of a CachingTask, which downloads the media content for local storage. Once cached, the asset can be played offline seamlessly.

The Media Cache feature is accessible on all platforms except for tvOS.

This page is structured as follows:

* [Caching Workflow](#caching-workflow)
* [Creating a CachingTask](#creating-a-cachingtask)
* [Controlling the CachingTask](#controlling-the-cachingtask)
* [Listening for Cache events](#listening-for-cache-events)
* [Using React hooks](#using-react-hooks)
* [The Example App](#the-example-app)

### Caching Workflow

Caching a media asset encompasses the following stages:

* CachingTask creation: The caching process commences by creating a CachingTask, which orchestrates the downloading of the media content for offline access.

* Starting the CachingTask: Once the CachingTask is established, the download process is initiated using the start() method. This triggers the download of the complete media stream to the device's local storage.

* Offline Playback: After successful caching, the cached media asset can be played offline. This is accomplished by providing the original source to the player. The player checks if the asset is available offline; if it is, playback occurs from the local cache. If not, the player fetches the content from the network.

## Creating a CachingTask

To initiate the download process of a media asset, you need to create a `CachingTask`. This task requires two essential parameters: a `SourceDescription` specifying the asset to be cached, and `CachingTaskParameters` that define caching settings.

Below is an example of creating a caching task:

```typescript
// The source we want to cache.
const source = {
    sources: [
        {
            src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8",
            type: "application/x-mpegurl"
        }
    ],
    metadata: {
        title: "Big Buck Bunny"
    }
} as SourceDescription;

// Caching parameters
const parameters = {
    // Cache the whole stream
    amount: '100%',

    // Cache for 24 hours
    expirationDate: new Date(Date.now() + 24 * 60 * 60 * 1000),

    // Cache quality
    bandwidth: 2000000,
} as CachingTaskParameters;

// Create a caching task
const task = await MediaCache.createTask(source, parameters);
```

## Controlling the CachingTask

Once the `CachingTask` is created, it enters the `idle` state. To initiate the download process:

```typescript
task.start();
```

Additionally, you can pause or remove the task from the media cache using these methods:

```typescript
task.pause();
task.remove();
```

## Listening for Cache events

Both `MediaCache` and `CachingTask` instances dispatch events to notify about changes and status updates.

### MediaCache events

The `MediaCache` dispatches the following events:

| Event name    | Purpose                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------ |
| `statechange` | Dispatched if the status of the Media Cache changes from `uninitialised` to `initialised`. |
| `addtask`     | Dispatched if a new `CachingTask` is added to the `MediaCache.tasks` list.                 |
| `removetask`  | Dispatched if `CachingTask` is removed from the `MediaCache.tasks` list.                   |

As an example, listening to the `addtask` event is done as follows:

```typescript
MediaCache.addEventListener(CacheEventType.addtask, (event: AddCachingTaskEvent) => {
    console.log('[MediaCache] a new task was added: ', event.task.id);
  }
);
```

### CachingTask events

Each individual `CachingTask` also dispatches events to advertise changes in `progress` or `status`.

| Event name    | Purpose                                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| `statechange` | Dispatched if the status of the task changes. Possible values are `idle`, `loading`, `done`, `error` or `evicted`. |
| `progress`    | Dispatched on a regular interval while `loading`.                                                                  |

As an example, listening for `progress` events is done as follows:

```typescript
task.addEventListener(CachingTaskEventType.progress, () => {
    console.log('[MediaCache]', `Progress for task ${task.id}: ${task.percentageCached}`);
});
```

## Using React hooks

For convenience, React hooks are available to simplify handling caching tasks without the need to subscribe or unsubscribe to listeners.

### useCachingTaskList

This hooks listens for updates in the `MediaCache.tasks` list, and returns the updated list.

```jsx
function TaskListView(props: {debug: boolean}) {
    const tasks = useCachingTaskList(props.debug);
    return <View style={styles.container}>
        {tasks.map((task, index) => <Text key={index} style={styles.taskListItem}>{task.id}</Text>)}
    </View>
}
```

### useCachingTaskProgress and useCachingTaskStatus

These hooks listen for updates in both progress and status of a `CachingTask`.

```jsx
function CachingTaskView(props: {task: CachingTask, debug: boolean}) {
    const { task, debug } = props;
    const status = useCachingTaskStatus(task, debug);
    const progress = useCachingTaskProgress(task, debug);
    return <View>
        <Text>{`status: ${status}`}</Text>
        <Text>{`progress: ${progress}`}</Text>
    </View>
}
```

## The Example App

The example app that is part of this repository demonstrates the Media Cache features through a basic user interface. It provides a menu with options to start caching the currently selected source, and show a list of the currently available caching tasks.

| ![main](/pr-932/assets/images/media_caching_1-291dc509ba26ee47cc721f8bd89e0e30.png) | ![main](/pr-932/assets/images/media_caching_2-980927a546367feead24e464ea8aaa0e.png) |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |

---

# Android Media3 Pipeline

## Overview

The THEOplayer Android Media3 pipeline is an integration for the THEOplayer Android SDK that serves as a **new and rebuilt base layer for playback of video and audio files**. It is based on [Jetpack Media3](https://developer.android.com/media/media3) components, and it provides more stable playback covering a broader range of use cases, all while being lighter in size and more performant.

For more information, refer to the [Getting started with Media3 on Android](https://www.theoplayer.com/docs/theoplayer/how-to-guides/android/media3/getting-started/) section in our Android SDK documentation.

The Media3 pipeline is available as of `react-native-theoplayer` v8.9.0.

### Usage

> \[!IMPORTANT] As of THEOplayer 9.0, Media3 is the default playback pipeline on Android. In this version, it is still possible to opt-out and use the legacy pipeline with the `playbackPipeline` parameter in the `SourceDescription`.

> \[!IMPORTANT] As of THEOplayer 10.0, the legacy pipeline has been removed.

The rest of this section **applies to THEOplayer 8.x only**.

Except for **THEOads sources**, where Media3 is **enabled by default**, the "legacy" pipeline remains the default on THEOplayer v8.x.

To enable the new Media3 extension, set the `THEOplayer_extensionMedia3` in the app's gradle configuration, such as the `gradle.properties` file:

```text
THEOplayer_extensionMedia3=true
```

Additionally, pass the `useMedia3` flag in the [player configuration](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/config/PlayerConfiguration.ts) as shown below:

```tsx
const playerConfig: PlayerConfiguration = {
  // ...
  useMedia3: true
};
```

### Multimedia tunneling

The Media3 pipeline provides support for multimedia tunneling, as described in the [Android documentation](https://source.android.com/docs/devices/tv/multimedia-tunneling). This is disabled by default.

To enable multimedia tunneling, pass the `tunnelingEnabled` flag in the [player configuration](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/config/PlayerConfiguration.ts) as shown below:

```tsx
const playerConfig: PlayerConfiguration = {
  // ...
  tunnelingEnabled: true
};
```

---

# Media Control API

Our [Media Control API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/media/MediaControlAPI.ts) provides a unified way to customise the behaviour of the different media playback controls and media sessions across platforms (iOS, Android, and Web). It enables integration with platform-level media controls such as lock screen controls, notification controls, media session, ...

## What is it used for?

* **Remote Control Actions:** Handle play, pause, seek, skip, and track switching from system UI (lock screen, notifications, etc.).
* **Media Session Integration:** Display media state and respond to hardware/media key events.
* **Custom Playlist Navigation:** Enable playlist navigation using system controls.

## Platform Support

* **Android:** Integrates with [Media Session](https://developer.android.com/guide/topics/media-apps/working-with-a-media-session) and media notifications.
* **iOS:** Integrates with [Now Playing](https://developer.apple.com/documentation/mediaplayer/mpnowplayinginfocenter) and [Remote Command Center](https://developer.apple.com/documentation/mediaplayer/mpremotecommandcenter).
* **Web:** Integrates with the [Media Session API](https://www.w3.org/TR/mediasession/).

## MediaControl API and MediaControl Action Reference

The [Media Control API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/media/MediaControlAPI.ts) allows you to override the default player's behaviour, by defining a handler for one of the MediaControl Actions:

```typescript
setHandler(action: MediaControlAction, handler: MediaControlHandler | undefined): void;
```

Passing `undefined` as handler removes any previously set handler for that action, restoring the player's default behaviour.

The [MediaControlAction](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/media/MediaControlAPI.ts) enum defines all actions that can be controlled by the Media Control API:

* `PLAY`: Triggered when the user presses play.
* `PAUSE`: Triggered when the user presses pause.
* `SKIP_TO_NEXT`: Triggered when the user requests to go to the next track or playlist item.
* `SKIP_TO_PREVIOUS`: Triggered when the user requests to go to the previous track or playlist item.

Play and pause are only enabled for VOD and when the stream is not displaying an ad. For LIVE streams this can be configured through `allowLivePlayPause` in the player's [MediaControlConfiguration](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/media/MediaControlConfiguration.ts).

If no handler is defined for an action, the player's default behaviour is applied.

### iOS: Track Control vs. Seek Behavior

On iOS, when you set handlers for `SKIP_TO_NEXT` or `SKIP_TO_PREVIOUS`, these handlers will take precedence over the seek behavior. This means:

* **If you provide next/previous track handlers:**

  * System controls (e.g., lock screen) will display and trigger your handlers for track navigation.
  * Seeking forward/backward via next/previous is not shown as seperate controls. (Platform limitation)

* **If you do not provide next/previous handlers:**
  * The system will display and use the seek forward/backward functionality with the configured or default intervals.

This allows you to customize whether system controls are used for playlist navigation or for seeking within the current track.

Note: In both cases, you can always use the system's time slider to adjust the playhead to seek to a location in the stream.

## Multiple players: single media-session owner

Each platform exposes a **single, process-wide** media session and set of remote controls (iOS `MPNowPlayingInfoCenter` / `MPRemoteCommandCenter`, Android `MediaSession` + notification, Web `navigator.mediaSession`). When your app renders **more than one** `THEOplayerView` at the same time, they all share this single system session.

Because of that, **only one player should own the media session at any given time**. It is the **application's responsibility** to designate that single owner and to ensure no other player simultaneously publishes Now Playing info or handles remote commands. If multiple players are allowed to take control at once:

* **Now Playing info** (title, artwork, position) from the different players will overwrite each other.
* **Remote commands** (play/pause/seek/skip) become last‑writer‑wins: the most recent player to claim the controls keeps them, and control can flip between players as each one updates its state.

### Recommended approach

Keep a single "active" player and toggle ownership so that exactly one player has the media session enabled at a time. You can update ownership across players using:

```typescript
// Give this player exclusive ownership of the media session / remote commands.
player.mediaControl?.setEnabled(isActive);
```

where `isActive` is true for the player that should own the media session and false for all other players. The owner will have its state reflected on the media session widgets.

### iOS: lock screen and Control Center play/pause state with multiple playing players

As a good practice, make sure only one player is actively playing at any given time. Shift the media session ownership (as demonstrated above) whenever a player starts playing (e.g. on a `PLAY` or `PLAYING` event) and pause all other players. On iOS, Control Center reflects the application's overall audio session state, not that of a specific player, so if multiple players are playing at once its controls will act on all of them.

## Configuration

You can add additional media control configuration using the [MediaControlConfiguration](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/media/MediaControlConfiguration.ts) interface:

```typescript
export interface MediaControlConfiguration {
  mediaSessionEnabled?: boolean; // (Web/Android) Enable/disable media session (default: true)
  skipForwardInterval?: number;  // (Web/Android/iOS) Skip forward interval (defaults: 5s on Web, Android / 15s on iOS)
  skipBackwardInterval?: number; // (Web/Android/iOS) Skip backward interval (defaults: 5s on Web, Android / 15s on iOS)
  allowLivePlayPause?: boolean;  // (Android/iOS) Enable play/pause for live (defaults: false on Android / true on iOS)
}
```

## Example Usage: Playlist Navigation

The Media Control API can be used to handle playlist navigation via system controls. For example, in a component that owns the playlist:

```typescript
import { MediaControlAction } from 'react-native-theoplayer';

// ...
useEffect(() => {
  if (!player) return;

  const handleNext = () => { /* update player source ... */ };
  const handlePrevious = () => { /* update player source ... */ };

  player.mediaControl?.setHandler(MediaControlAction.SKIP_TO_NEXT, handleNext);
  player.mediaControl?.setHandler(MediaControlAction.SKIP_TO_PREVIOUS, handlePrevious);

  return () => {
    player.mediaControl?.setHandler(MediaControlAction.SKIP_TO_NEXT, undefined);
    player.mediaControl?.setHandler(MediaControlAction.SKIP_TO_PREVIOUS, undefined);
  };
}, [player, filteredSources]);
```

This enables users to skip tracks using lock screen or Bluetooth controls. If you do not set these handlers, the controls will perform seek actions instead.

## Demo

As a demonstration, see the the `PlaylistProvider` in our [example app](https://github.com/THEOplayer/react-native-theoplayer/blob/-/example/).

---

# Metrics

## Overview

The [Metrics API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/metrics/MetricsAPI.ts) exposes playback metrics gathered by the player. It is available on the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts) through `player.metrics`.

Metrics are **poll-based**: there is no change event, so you read a value on demand (for example on an interval, or piggy-backing on an existing event such as a time update).

## Current bandwidth estimate

`player.metrics.currentBandwidthEstimate()` returns the bandwidth, in **bits per second**, that the player estimates is currently available. This is the value the player uses to make adaptive bitrate (ABR) decisions.

```tsx
const onPlayerReady = (player: THEOplayer) => {
  // Poll the estimate every second.
  setInterval(async () => {
    const bps = await player.metrics.currentBandwidthEstimate();
    console.log(`Estimated bandwidth: ${bps} bps`);
  }, 1000);
};

<THEOplayerView
  config={playerConfig}
  onPlayerReady={onPlayerReady}
/>
```

> **Note:** A value of `0` means the estimate is **not available yet** (e.g. before playback, after a reset, or on a platform/source that does not populate it — see below). It does **not** mean the available bandwidth is literally zero.

## Platform specifics

The access path (`player.metrics.currentBandwidthEstimate()`, in bits/s) is identical on every platform, but the *behaviour* is not uniform:

| Platform | Populated for                                                                            | Value when unsupported                         |
| -------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------- |
| Android  | All streams, via the Media3/ExoPlayer estimate (HLS, DASH, SmoothStreaming, progressive) | `0.0` when no playback backend is attached     |
| Web      | All streams driven by THEOplayer's MSE/ABR pipeline (HLS, DASH, HESP)                    | `0` during native HTML5 playback               |
| iOS/tvOS | THEOlive/HESP streams **only** in practice                                               | `0` for regular `AVPlayer` playback (HLS, MP4) |

* On **iOS/tvOS** the value is only meaningful for THEOlive/HESP sources. For ordinary HLS/MP4 played it stays `0`.
* On **Android** and **Web** the estimate is reported for regular adaptive streams as well; it is not HESP-specific.

---

# Migrating to THEOplayer React Native SDK 10.x

This article will guide you through updating to THEOplayer React Native SDK version 10 (from version 9), and the changes needed in your code.

## Update React Native THEOplayer

Run the following command to install THEOplayer React Native SDK version 10:

```bash
npm install react-native-theoplayer@10
```

## Breaking Changes on Web

The breaking changes for the native Web SDK are listed in the v10 [changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-breaking-changes).

## Breaking Changes on iOS

The breaking changes for the native Web SDK are listed in the v10 [changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-breaking-changes-2).

## Breaking Changes on Android

The breaking changes for the native Android SDK are listed in the v10 [changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-breaking-changes-1).

The following updates in particular impact the React Native SDK on Android.

### Media3 became the only available playback pipeline on Android

On Android platforms, the Media3 playback pipeline is now the only available pipeline. **The legacy pipeline has been removed.**

### Cache storage type `legacy` removed

With the removal of the legacy pipeline, the option to cache media content for this pipeline by setting `CachingTaskParameters.storageType` was also removed.

### PlaybackSettingsAPI removed on Android

The `PlaybackSettingsAPI`, which allowed to control start-up and lip sync correction on the legacy pipeline, has been removed.

### Update `compileSdk` to 36 or higher

The underlying Android SDK depends on the AndroidX Core library, which requires `compileSdk 36` as of version 1.17.0.

Update the `compileSdk` to be `36` (or higher) in your module-level `build.gradle` file.

We also recommend updating the Android Gradle Plugin to the latest version. In Android Studio, go to Tools → AGP Upgrade Assistant and follow the steps to update AGP in your project.

### Updated `minSdk` to API 23 on Android

This aligns with [other Android Jetpack libraries requiring API 23 as of June 2025](https://developer.android.com/jetpack/androidx/versions#version-table).

---

# Migrating to THEOplayer React Native SDK 11.x

This article will guide you through updating to THEOplayer React Native SDK version 11 (from version 10), and the changes needed in your code.

## Update React Native THEOplayer

Run the following command to install THEOplayer React Native SDK version 11:

```bash
npm install react-native-theoplayer@11
```

## Breaking API changes

* Removed deprecated `ResizeEvent` in favor of `DimensionChangeEvent`.
* Removed deprecated `player.theolive` property in favor of `player.theoLive`.
* Removed deprecated `source.integration` property in favor of `source.type`.

## Breaking Changes on Web

The breaking changes for the native Web SDK are listed in the v11 [changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-breaking-changes), none of which impact the React Native SDK on Web.

## Breaking Changes on iOS

The breaking changes for the native Web SDK are listed in the v11 [changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-breaking-changes-2).

The following updates in particular impact the React Native SDK on iOS.

* The minimum supported iOS/tvOS version is now 15.0, dropping support for iOS/tvOS 13 and 14.

## Breaking Changes on Android

The breaking changes for the native Android SDK are listed in the v11 [changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-breaking-changes-1).

The following updates in particular impact the React Native SDK on Android.

* The Google IMA SDK integration now requires [core library desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) to be enabled. See [our updated guide for Google IMA](https://optiview.dolby.com/docs/theoplayer/how-to-guides/ads/google-ima/#android-sdk) for instructions, or the React Native THEOplayer [example app](https://github.com/THEOplayer/react-native-theoplayer/tree/develop/example) for a sample implementation.

---

# Migrating to THEOplayer React Native SDK 9.x

This article will guide you through updating to THEOplayer React Native SDK version 9 (from version 8), and the changes needed in your code.

## Update React Native THEOplayer

Run the following command to install THEOplayer React Native SDK version 9:

```bash
npm install react-native-theoplayer@9
```

## Removed `chromeless` config parameter

To extend React Native THEOplayer with a user interface, it's recommended to either use the [`@theoplayer/react-native-ui`](https://github.com/THEOplayer/react-native-theoplayer-ui) package or create a custom UI in React Native. Support for the native `chromefull` UI has been removed.

## Removed `enableTHEOlive` config parameter

THEOlive is now always enabled, eliminating the need for an additional configuration parameter.

## Media3 as default playback pipeline on Android

On Android platforms, the Media3 playback pipeline is now enabled by default. This new pipeline is built on top of [Jetpack Media3](https://developer.android.com/media/media3), which aims to provide more stable playback on a wider range of devices. See [our Media3 guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/android/media3/getting-started.md) for more information.

We highly recommend using the Media3 playback pipeline. However, if you need some more time to make the switch, you can still revert to the legacy playback pipeline from version 8.x by setting `playbackPipeline` to `PlaybackPipeline.LEGACY` in the [`SourceDescription`](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/source/SourceDescription.ts) passed to the player.

### Warning

The legacy playback pipeline is scheduled to be removed in THEOplayer version 10.

If you run into an issue that prevents you from switching to Media3, please contact our Service Desk.

## Media3 as default backend for caching

Newly created caching tasks now use the Media3 backend by default. Sources cached with this backend can only be played using the Media3 playback pipeline.

If you need some more time to make the switch, you can still revert to the legacy cache storage from version 8.x by setting `CachingParameters.storageType` to `CacheStorageType.LEGACY` during creation of a caching task.

### Warning

The legacy cache storage is scheduled to be removed in THEOplayer version 10.

If you run into an issue that prevents you from switching to Media3, please contact our Service Desk.

## Removed Media3 integration package on Android

The Media3 playback pipeline now ships with the THEOplayer Android SDK, and is no longer published as an extension. This means the build flag `THEOplayer_extensionMedia3` can be dropped from your app's `gradle.properties`.

---

# Getting started with Millicast on React Native

[Dolby Millicast](https://dolby.io/products/real-time-streaming/) delivers broadcast quality live streaming at sub-second latency, enabling interactivity and fan engagement. Using the THEOplayer Millicast integration, you can play your Millicast streams directly through THEOplayer.

## Usage

1. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/getting-started.md) to set up THEOplayer in your React Native app. The Millicast integration is available in the main [react-native-theoplayer](https://www.npmjs.com/package/react-native-theoplayer) package on npm.
2. Add a Millicast source to your player's source.

### Add a Millicast source

After setting up THEOplayer in your app, set its source to a `SourceDescription` containing a `MillicastSource`. You'll need a Millicast account ID and stream name to identify your Millicast stream:

```tsx
const source: MillicastSource = {
  type: 'millicast',
  src: 'multiview',
  streamAccountId: 'k9Mwad',
  subscriberToken: '<token>', // This is only required for subscribing to secure streams and should be omitted otherwise.
  apiUrl: 'https://director.millicast.com/api/director/subscribe' // Required for support on Android
};
player.source = source;
```

### Add configuration

Optionally, you can provide additional configuration to the source, specific for working with Millicast streams. To configure these settings, add a `connectOptions` property to the source object and specify the options.

In the example below, the configuration is used to disable any audio from the Millicast stream. For an exhaustive list of these options, visit the [API documentation](https://theoplayer.github.io/react-native-theoplayer/api/interfaces/MillicastConnectOptions.html).

```tsx
const source: MillicastSource = {
  type: 'millicast',
  /* ... */
  connectOptions: {
    disableAudio: true
    /* ... */
  }
};
```

## More information

* [API references](https://theoplayer.github.io/react-native-theoplayer/api/interfaces/MillicastSource.html)
* [Millicast documentation](https://docs.dolby.io/streaming-apis/docs/)

---

# Picture-in-Picture (PiP)

## Overview

The Picture-in-Picture feature allows you to watch a stream in a floating window that is always on top of other apps or windows.

Transitioning the player to a PiP window can be done in two ways:

* Explicitly, using the player API
* Automatically, when transitioning to background in mobile apps.

This page describes how to configure PiP with react-native-theoplayer.

## Configuration

### Transitioning to PiP automatically

The `pipConfiguration` property that is set on the player instance allows native mobile apps on iOS and Android to automatically transition into PiP presentation mode when the app goes to the background. The property can be changed at run-time, allowing to change the behaviour depending on the active media asset.

```typescript
player.pipConfiguration = { startsAutomatically: true }
```

### Using presentationMode

The picture-in-picture presentation mode can also be triggered explicitly using the `THEOplayer` API:

```typescript
// Change presentation mode (inline, fullscreen or pip).
player.presentationMode = PresentationMode.pip;
```

### Listening for presentationMode changes

Each time the player transitions from one presentationMode to another, either automatically or manually through the API, the player dispatches a `presentationmodechange` event that can be used to update the user-interface.

```typescript
player.addEventListener(
  PlayerEventType.PRESENTATIONMODE_CHANGE,
  (event: PresentationModeChangeEvent) => {
    const newPresentationMode = event.presentationMode;
  }
);
```

### Reacting to a closed PiP window

When the player leaves the picture-in-picture presentation mode, the `context.pip` property of the `presentationmodechange` event indicates whether the PiP window was closed by the user, or restored to the app:

```typescript
player.addEventListener(
  PlayerEventType.PRESENTATIONMODE_CHANGE,
  (event: PresentationModeChangeEvent) => {
    if (
      event.previousPresentationMode === PresentationMode.pip &&
      event.context?.pip === PresentationModeChangePipContext.CLOSED
    ) {
      // The user closed the PiP window: stop play-out by clearing the source.
      player.source = undefined;
    }
  }
);
```

Clearing the source pauses play-out and unloads the current media resource, similar to the play-out stop that is applied by `backgroundAudioConfiguration.stopOnBackground`. It allows background playback to continue in case the app is backgrounded without transitioning to PiP. Note that the `backgroundAudioConfiguration.stopOnBackground` property is not suited for this purpose, as it also stops play-out when the app goes to the background without a PiP window; see [Background Playback](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/background.md).

Additional configuration is necessary depending on the platform the app runs on.

## Android

Picture-in-picture support for Android was added in Android 8.0 (API level 26).

A react-native app on Android is typically a single-activity application. Launching picture-in-picture mode means the whole activity transitions to an *out-of-app* PiP window.

### Enabling PiP support

To enable PiP support, make sure to set `android:supportsPictureInPicture=true` in the app's manifest, and specify that the activity handles layout configuration changes so that it does not relaunch when layout changes occur during PiP mode transitions.

```xml
<activity
  android:name=".MainActivity"
  android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation"
  android:supportsPictureInPicture="true">
</activity>
```

Also, add these methods to the `MainActivity` to let react-native know when the app makes PiP, background and foreground transitions:

```kotlin
public override fun onUserLeaveHint() {
    // Notify the app is backgrounded in case the user taps home or back, and
    // the app needs to transition to PiP automatically.
    this.sendBroadcast(Intent("onUserLeaveHint"))
    super.onUserLeaveHint()
}

override fun onPictureInPictureModeChanged(
    isInPictureInPictureMode: Boolean,
    newConfig: Configuration
) {
    // Notify that the app is changing its picture-in-picture mode.
    super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)
    val intent = Intent("onPictureInPictureModeChanged")
    intent.putExtra("isInPictureInPictureMode", isInPictureInPictureMode)
    this.sendBroadcast(intent)
}
```

### Enabling early transitioning to PiP event

You might want to enable [transitioning to PiP](https://developer.android.com/reference/android/app/PictureInPictureUiState#isTransitioningToPip\(\)) event for Android 15+ (API 35+). To enable it make sure that the compile SDK version is set to 35 in your build.gradle `compileSdkVersion = 35`. Also the appropriate intent should be sent from the `MainActivity` to let react-native know when the app starts the PiP animation:

```kotlin
override fun onPictureInPictureUiStateChanged(pipState: PictureInPictureUiState) {
    super.onPictureInPictureUiStateChanged(pipState)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM &&
        pipState.isTransitioningToPip
    ) {
        Intent("onPictureInPictureModeChanged").also {
            it.putExtra("isTransitioningToPip", true)
            sendBroadcast(it)
        }
    }
}
```

Then it should set the `context?.pip` to `PresentationModeChangePipContext.TRANSITIONING_TO_PIP` in the event `PlayerEventType.PRESENTATIONMODE_CHANGE`.

### PiP controls

The PiP window will show the default controls to configure, maximize and close the PiP window. In addition, the active media session enables a play/pause toggle button and (disabled) play-list navigator buttons.

| ![pip1](/pr-932/assets/images/pip_android_1-c2cde1b49f69cfe79a441bbaf8cb47ee.png) | ![pip2](/pr-932/assets/images/pip_android_2-a34aebe9117fe159534751493076b242.png) | ![pip3](/pr-932/assets/images/pip_android_3-715cef9dba8c741424f9b0f8247bc56d.png) |
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |

### User interface

As mentioned before, when choosing `picture-in-picture` presentation mode on Android the whole activity moves to the PiP window, including the react-native UI that potentially lies on top. For this reason it is necessary to disable the UI on Android in PiP mode, as opposed to iOS and web where the video view is separated from the rest

More information on Android PiP support can be found on the [Android developer pages](https://developer.android.com/develop/ui/views/picture-in-picture).

## iOS

No additional configuration is required to support picture-in-picture on iOS.

## Web

On web platforms, only the "out-of-app" PiP presentation mode is supported, allowing the PiP window to float independently from the browser window on the desktop. The THEOplayer Web SDK refers to this as [native-picture-in-picture](https://www.theoplayer.com/docs/theoplayer/v10/api-reference/web/types/PresentationMode.html) , distinguishing it from the "in-app" floating player window used in picture-in-picture mode. Note that except for the native PiP controls, any user interface defined in React Native will not be shown in the PiP window.

---

# Subtitles, Closed Captions and Metadata tracks

THEOplayer's `TextTrack` api gives developers the capability to manage and manipulate various types of text-based content. Some of its key functionalities include text track selection, styling, and listening to track and cue events.

## Types of text tracks

In this document we will differentiate between the following kinds of text tracks:

* **Subtitles**, which are text-based translations of the dialogue or narrative of a video;
* **Closed Captions (CC)**, which go beyond subtitles by providing additional information about sound effects, music, and other audio cues;
* **Metadata tracks**, which are used for providing non-textual information about the video, such as thumbnail urls or program boundaries in a live stream.

In addition, a distinction can be made between how a text track is delivered to the player:

* **In-band** refers to text tracks that are embedded within the video or audio media stream itself.
* **Out-band**, or *out-of-band*, is used to describe text tracks that are delivered separately from the media file. They are typically described in the playlist or manifest.
* **Side-loaded** text tracks are those that are manually added or loaded by the user through the source description.

## Side-loaded text tracks

In contrast to in-band and out-band text tracks, which are delivered to the player through the media content itself, the side-loaded text tracks can be configured by the user when setting a source to the player:

```typescript
player.source = {
  "sources": [
    {
    "src": "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8",
    "type": "application/x-mpegurl"
    }
  ],
  "textTracks": [
    {
      "default": true,
      "src": "https://cdn.theoplayer.com/dash/theoplayer/thumbnails/big_buck_bunny_thumbnails.vtt",
      "label": "thumbnails",
      "kind": "metadata",
      "format": "webvtt",
      "srclang": "en"
    }
  ]
}
```

### iOS/tvOS

On iOS and tvOS, support for side-loaded tracks is provided by a separate connector, which is enabled by adding the feature to the `react-native-theoplayer.json` (or `theoplayer-config.json`) file in your app folder.

```json
{
  "ios": {
    "features": ["SIDELOADED_TEXTTRACKS"]
  }
}
```

## Listening to text track events

Out-band and side-loaded text tracks become accessible via the text track API once the player has loaded the media source. This event is signaled by the `PlayerEventType.LOADED_METADATA` event, which is dispatched by the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts):

```typescript
player.addEventListener(PlayerEventType.LOADED_METADATA, (event: LoadedMetadataEvent) => {
  console.log(TAG, 'loadedmetadata', JSON.stringify(event));
})
```

Alternatively, the `PlayerEventType.TEXT_TRACK_LIST` event can be used to dynamically listen to text tracks that are being added, removed or changed. In-band text tracks, in particular, are created when their first cue is loaded, which can occur at any point during playback.

```typescript
player.addEventListener(PlayerEventType.TEXT_TRACK_LIST, (event: TextTrackListEvent) => {
  const { subType, track } = event;
  switch (subType) {
    case TrackListEventType.ADD_TRACK: /*A text track has been added*/ break;
    case TrackListEventType.REMOVE_TRACK: /*A text track has been removed*/ break;
    case TrackListEventType.CHANGE_TRACK: /*A text track has changed*/ break;
  }
});
```

Similarly for text track cues, the `PlayerEventType.TEXT_TRACK` event provides knowledge on cues being added or removed. The cue contains a reference to the track it belongs too.

```typescript
player.addEventListener(PlayerEventType.TEXT_TRACK, (event: TextTrackEvent) => {
  const { subType, cue } = event;
  switch (subType) {
    case TextTrackEventType.ADD_CUE: /*A text track cue has been added to the text track*/ break;
    case TextTrackEventType.ENTER_CUE: /*A text track cue has entered; it became active*/ break;
    case TextTrackEventType.EXIT_CUE: /*A text track cue has exited; it became inactive*/ break;
    case TextTrackEventType.REMOVE_CUE: /*A text track cue has been removed from the text track*/ break;
  }
})
```

## Enabling a text track

A subtitle or closed caption can be enabled by setting the player's `selectedTextTrack` property to the `uid` of the track, or `undefined` to select none.

```typescript
const track: TextTrack;
player.selectedTextTrack = track.uid;
```

Note that [THEOplayer React-Native UI](https://github.com/THEOplayer/react-native-theoplayer-ui) package provides a visual representation of the list of available text tracks, as well as the ability to enable/disable them.

Metadata tracks are by default 'hidden', as they do not visually represent a textTrack but contain valuable data (e.g. id3 cues, HLS DataRange cues, ...). While 'hidden', these metadata tracks will actively 'enter' and 'exit' their cues.

## Preview thumbnails

Preview thumbnails is a feature that allows users to see a visual representation of different points or scenes within a video, making it easier to navigate and locate specific content of interest.

The thumbnails are typically contained in a dedicated thumbnail track, which is a text track of kind `metadata` with label `thumbnails`. The track can be either be side-loaded to the stream source, or contained in a stream manifest, as the demo sources in the [example application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/example-app.md) demonstrate:

```json
{
  "sources": [
    {
    "src": "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8",
    "type": "application/x-mpegurl"
    }
  ],
  "textTracks": [
    {
      "default": true,
      "src": "https://cdn.theoplayer.com/dash/theoplayer/thumbnails/big_buck_bunny_thumbnails.vtt",
      "label": "thumbnails",
      "kind": "metadata",
      "format": "webvtt"
    }
  ]
}
```

The [`@theoplayer/react-native-ui`](https://github.com/THEOplayer/react-native-theoplayer-ui) package provides a thumbnail viewer the interprets thumbnail cues and displays them above the progress bar.

![thumbnails](/pr-932/assets/images/thumbnails-c17c05ef4018a5a2ad04327f820ed6be.png)

## Styling subtitles and closed captions

In this section, we showcase the functionality of THEOplayer's `TextTrackStyle` API, which enables the customization of subtitles and closed captions' appearance. We will illustrate the practical implementation of this API through some examples.

### Style properties

| Property          | Purpose                                                           | Value                                                                                   | Support                                                            |
| ----------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `fontFamily`      | The font of the text track.                                       | A string, e.g. `'serif'`, `'monospace'`, `'arial'`.                                     | All platforms,                                                     |
| `fontColor`       | The font color of the text track.                                 | A string, e.g.`'red'`, `'#ff0000'`, `'#ffc50f'` or `'rgba(255, 0, 0, 1)`.               | All platforms. The `rgba()` formatting is supported on Web only.   |
| `fontSize`        | The font size of the text track.                                  | A percentage string, e.g.`'50%'`, `'100%'` (default), `'175%'`.                         | All platforms,                                                     |
| `backgroundColor` | The color of the area directly behind the text.                   | A string, e.g.`'red'`, `'#ff0000'`, `'#ffc50f'` or `'rgba(255, 0, 0, 1)`.               | All platforms. The `rgba()` formatting is supported on Web only.   |
| `windowColor`     | The color of the area covering the full width of the text track.  | A string, e.g.`'red'`, `'#ff0000'`, `'#ffc50f'` or `'rgba(255, 0, 0, 1)`.               | Web and Android. The `rgba()` formatting is supported on Web only. |
| `edgeStyle`       | The edge style of the text.                                       | An enum value, either `none` (default), `dropshadow`, `raised`, `depressed`, `uniform`. | All platforms.                                                     |
| `marginTop`       | The top margin of the area where subtitles are being rendered.    | A positive numeric value specifying the number of pixels.                               | All platforms.                                                     |
| `marginLeft`      | The left margin of the area where subtitles are being rendered.   | A positive numeric value specifying the number of pixels.                               | All platforms.                                                     |
| `marginBottom`    | The bottom margin of the area where subtitles are being rendered. | A positive numeric value specifying the number of pixels.                               | Web and Android.                                                   |
| `marginRight`     | The right margin of the area where subtitles are being rendered.  | A positive numeric value specifying the number of pixels.                               | Web and Android.                                                   |

### Examples

|                                                                                                     |                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| ![background](/pr-932/assets/images/texttrackstyle_background-c95e54ee5b2a2bc17a69cc40d280344f.png) | ```typescript
player.textTrackStyle.backgroundColor = 'red';
player.textTrackStyle.marginLeft = 45;
```                                               |
| ![size](/pr-932/assets/images/texttrackstyle_size-cba477b68686174a985054911bb4b474.png)             | ```typescript
player.textTrackStyle.windowColor = 'black';
player.textTrackStyle.fontColor = '#ffff00ff';
player.textTrackStyle.fontSize = '250%';
``` |
| ![size](/pr-932/assets/images/texttrackstyle_family-4ec69c505c8ee26bc7fa89802503ca25.png)           | ```typescript
player.textTrackStyle.fontFamily = 'monospace';
```                                                                                    |

---

# How-to guides for OptiView Player React Native SDK

Want to start implementing features to your SDK? Our how-to-guides will help you with all kind of integrations!

## [🔌Integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/react-native/integrations/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/react-native/integrations/introduction.md)

## [🔑License](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/react-native/license/introduction.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/react-native/license/introduction.md)

## [🚀OptiView Live](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/react-native/theolive/getting-started.md)

[Integrate OptiView Live streaming into your React Native app.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/react-native/theolive/getting-started.md)

---

# Integrations on React Native

In this section, you can figure out how THEOplayer integrates with various partners.

## Related articles

* [Deliver Low-Latency HLS live streams](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/react-native/integrations/wowza-streaming-engine/low-latency-hls.md)

---

# Wowza Streaming Engine on React Native

[Wowza Streaming Engine™](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/) is a media server for live and on-demand streaming. THEOplayer can play back its streams, and integrates with a number of its features.

---

# Deliver Low-Latency HLS live streams with Wowza Streaming Engine on React Native

Wowza Streaming Engine™ media server software can deliver Low-Latency HLS (LL-HLS) live streams, which THEOplayer can play back on every platform.

Low-Latency HLS streams conform to [Apple's protocol extension to the HLS specification](https://developer.apple.com/documentation/http-live-streaming/enabling-low-latency-http-live-streaming-hls).

## Prerequisites

There are three prerequisites in order to continue with this guide:

1. In order to generate LL-HLS streams, you must first get a SSL certificate to secure your port and configure the port for HTTPS playback. LL-HLS playback does not work without an SSL secured port. For information on how to do this, refer to [How to Get an SSL Certificate from Wowza's Streamlock Service](https://www.wowza.com/docs/how-to-get-ssl-certificates-from-the-streamlock-service).

2. This guide expects that you have a THEOplayer license. If you are not using THEOplayer yet, you can start your free trial [here](https://portal.theoplayer.com/).

3. This guide expects that you are a Wowza Streaming Engine client and that you are integrated with their streaming infrastructure. Information on Wowza Streaming Engine can be found [here](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/). Be sure to have Wowza Streaming Engine media server software version 4.7.8 or higher.

**Please Note:** Wowza occasionally update their documentation, which can be accessed [here](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine).

## Configure a live application to deliver LL-HLS streams

You can use the default **live** application that installs with Wowza Streaming Engine or create and use a new **Live** or **Live HTTP Origin** application. Use the **Live** application type for sending streams from Wowza Streaming Engine to clients or Wowza Streaming Engine edges. Use the **Live HTTP Origin** application type to connect to a CDN edge, such as the Fastly CDN, that can pull streams from the Wowza Streaming Engine origin application.

The following steps use the default **live** application to enable LL-HLS live streaming by editing the **Application.xml** and **VHost.xml** configuration files.

**Please Note:** If you're trying to use the CMAF packetizer to deliver LL-HLS and HLS or MPEG-DASH streams, you must use two separate live applications: one configured specifically for LL-HLS and another for CMAF-packetized HLS and MPEG-DASH.

### Enable LL-HLS in Wowza Streaming Engine XML

The following steps enable transmuxing for CMAF packetization for LL-HLS delivery.

1. Navigate to **\[install-dir]/conf/live** or **\[install-dir]/conf/\[custom live application]** and open the **Application.xml** file in a text editor.
2. Add **cmafstreamingpacketizer** to the **LiveStreamPacketizers** property. You can add it to the prepopulated comma-separated list, or it can be the only packetizer specified. The XML looks like this:

```xml
<Streams>
    ...
    <LiveStreamPacketizers>cmafstreamingpacketizer</LiveStreamPacketizers>
    ...
</Streams>
```

**Please Note:** If you enable **cupertinostreamingpacketizer** and **cmafstreamingpacketizer**, Wowza Streaming Engine generates both MPEG-TS segments (using **cupertinostreamingpacketizer**) and fMP4 segments (using **cmafstreamingpacketizer**).

3. Add the **cmafLLEnableLowLatency** property to the **LiveStreamPacketizer** container element and set it to true.

```xml
<LiveStreamPacketizer>
    <Properties>
        <Property>
            <Name>cmafLLEnableLowLatency</Name>
            <Value>true</Value>
            <Type>Boolean</Type>
        </Property>
    </Properties>
</LiveStreamPacketizer>
```

4. For the **HTTPStreamers** property, make sure HLS (**cupertinostreaming**) is specified. The XML looks like this:

```xml
<HTTPStreamers>cupertinostreaming</HTTPStreamers>
```

5. Go to **\[install-dir]/conf/** and open the **VHost.xml** file in a text editor.

6. Add the `AllowHttp2` property to the `<SSLConfig>` container element in the `<HostPort>` you configured for SSL/TLS and set it to true.

```xml
<SSLConfig>
    ...
    <AllowHttp2>true</AllowHttp2>
    ...
</SSLConfig>
```

7. Save your changes.

Your live application is now configured to deliver LL-HLS streams.

### Configure optional low latency partial segment properties and media playlist property

Configuring the following properties is optional as Wowza Streaming Engine will use the property's default value for any of the properties that you do not configure. You can configure the optional LL-HLS properties by editing the **Application.xml** file for your LL-HLS live stream application. For information about configuring custom (optional) properties, see [Add custom properties](https://www.wowza.com/docs/add-a-custom-property#add-custom-properties).

#### Low latency CMAF property reference

You can configure any of these optional **LiveStreamPacketizer** properties for the LL-HLS segments and video and audio partial segments (chunks) in the **Application/LiveStreamPacketizer/Properties** container element.

**Please Note:** If partial segments are too small, servers can become overloaded with frequent media playlist requests and cause playback to be less reliable.

| Name                                                                                                                                                          | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **cmafLLChunkingScheme**                                                                                                                                      | String  | Specifies the chunking scheme for low latency CMAF-packetized streams. Valid values are **byFrame** or **byDuration**. The default is **byDuration**. If the value is **byDuration**, packetization is configured using the **cmafLLChunkDurationTargetAudio** and **cmafLLChunkDurationTargetVideo** properties. If the value is **byFrame**, packetization is configured using the **cmafLLChunkFrameCountTargetAudio** and **cmafLLChunkFrameCountTargetVideo** properties. |
| **cmafLLChunkDurationTargetAudio**                                                                                                                            | Integer | Specifies, in milliseconds, the target duration of each low latency CMAF **audio** chunk. The default is **1000** and is recommended. The duration cannot exceed the [cmafSegmentDurationTarget](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine#cmafsegmentdurationtarget) value. This property is only available if **cmafLLChunkingScheme** is **byDuration**.                                                           |
| **cmafLLChunkDurationTargetVideo**                                                                                                                            | Integer | Specifies, in milliseconds, the target duration of each low latency CMAF **video** chunk. The default is **1000** and is recommended. The duration cannot exceed the [cmafSegmentDurationTarget](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine#cmafsegmentdurationtarget) value. This property is only available if **cmafLLChunkingScheme** is **byDuration**.                                                           |
| **cmafLLChunkFrameCountTargetAudio**                                                                                                                          | Integer | Specifies the target number of audio frames to include in each low latency CMAF audio chunk. The default is **47** and is recommended. This property is only enabled if **cmafLLChunkingScheme** is **byFrame**.                                                                                                                                                                                                                                                               |
| **cmafLLChunkFrameCountTargetAudio**                                                                                                                          | Integer | Specifies the target number of audio frames to include in each low latency CMAF audio chunk. The default is **30** and is recommended. This property is only enabled if **cmafLLChunkingScheme** is **byFrame**.                                                                                                                                                                                                                                                               |
| **[cmafSegmentDurationTarget](https://www.wowza.com/docs/configure-cmaf-packetization-in-wowza-streaming-engine#cmaf-live-packetization-property-reference)** | Integer | Specifies, in milliseconds, the duration of the fMP4 segments in the stream. The default is **6000** (6 seconds) and is recommended. This property is configurable from the **CMAFStreamingPacketizer** properties section in Wowza Streaming Engine Manager.                                                                                                                                                                                                                  |

#### Advanced LL-HLS property reference

For advanced tuning, you can configure the following optional **HTTPStreamer** property in the **Application/HTTPStreamer/Properties** container element.

| Name                                    | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cupertinoPartHoldBack (4.8.0 and later) | Double | Specifies, in floating-point seconds, the server-recommended minimum distance from the live edge at which clients should begin to play or seek in a LL-HLS stream (the PART-HOLD-BACK attribute in media playlists). If you do not configure this property, Wowza Streaming Engine uses the default value, which is recommended. The default value is calculated as three times the maximum value of PART-TARGET out of all of a stream's variant media playlists. **Please Note:** PART-TARGET is an attribute of the EXT-X-PART-INF tag in media playlists and is based on the target values set with the **cmafLLChunkDurationTargetVideo** and **cmafLLChunkDurationTargetAudio** properties or the **cmafLLChunkFrameCountTargetVideo** and **cmafLLChunkFrameCountTargetAudio** properties. Wowza Streaming Engine will adjust the PART-HOLD-BACK value to be equal to the maximum value of PART-TARGET (across all variant media playlists) if you set this property to less than a partial segment duration. |

#### Transcoding considerations for LL-HLS

To bypass encoding streams with Transcoder, source streams should meet the following encoding recommendations. Otherwise, transcoding is recommended. Although a small amount of latency is introduced with transcoding, if your source stream does not meet the encoding recommendations, transcoding will ultimately improve reliability of LL-HLS streaming.

##### Encoding recommendations

* CMAF-supported codecs (required)

| Video          | Audio                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - H.264, H.265 | - AAC, AAC-LC, HE-AAC (AAC+ or aacPlus),<br />- HE-AACv2 (enhanced AAC+, aacPlus v2) - Dolby Digital 5.1 Surround Sound (AC-3) and Dolby Digital Plus (Enhanced AC-3 or E-AC-3) |

* GOP size: 1 or 2 seconds
* Closed GOPs
* H.264 and H.265 byte streams contain metadata about the GOP structure
* Constant frame rate video

A stream configured for transcoding and LL-HLS delivery cannot use **Passthrough** for the **Video Codec** of a stream rendition but not other renditions of the same stream. If you use **Passthrough** to pass a video source through to output without making any changes for any **Video Codec** in a stream's renditions, all of the video codecs must be set to **Passthrough**.

Stream name groups (NGRP) are not supported with LL-HLS. To group multiple stream renditions for LL-HLS, you need to create a SMIL file in accordance with CMAF HLS. See [Set up adaptive bitrate CMAF streaming](https://www.wowza.com/docs/create-adaptive-bitrate-cmaf-streams-using-wowza-streaming-engine#set-up-adaptive-bitrate-cmaf-streaming) for how to do this.

#### Scale LL-HLS with a CDN

Optionally, with your own CDN account, you can scale LL-HLS delivery by connecting a Wowza Streaming Engine **Live HTTP Origin** application to a CDN edge that can pull streams from the Wowza Streaming Engine origin application, such as the Fastly CDN.

To connect the **Live HTTP Origin** application to your CDN, provide the IP address or hostname of the Wowza Streaming Engine origin server in your CDN configuration. Also in your CDN configuration, enable connecting to the origin server over SSL/TLS using the port you configured for SSL/TLS in the Wowza Streaming Engine origin (default port 443).

#### Test stream playback

After your live application is configured to deliver an LL-HLS stream, complete the stream setup by connecting a source encoder or IP camera to Wowza Streaming Engine and publishing the live source stream to the server. When the camera or encoder is connected and the live stream is active, test LL-HLS playback using a supported test player.

To test LL-HLS live streams when only **cmafstreamingpacketizer** is enabled, specify the stream playback URL using one of the following formats:

**Single bitrate** https\://\[address]/\[application]/\[application-instance]/\[stream-name]/playlist.m3u8

If **cmafstreamingpacketizer** and **cupertinostreamingpacketizer** are enabled, specify the stream playback URL using one of the following formats:

**Single bitrate** https\://\[address]/\[application]/\[application-instance]/\[stream-name]/playlist\_sfm4s.m3u8

Where:

**\[address]** is the IP address or domain and port (default port 443) **\[application]** is the application name **\[application-instance]** is the name of the application instance (if omitted, defaults to ***definst***) **\[stream-name]** is the stream name So, for example, if only **cmafstreamingpacketizer** is enabled, the playlist URL for an adaptive bitrate LL-HLS stream that uses the address **example.com**, the default **live** application, and the default stream name **myStream** is:

<https://example.com/live/smil:myStream.smil/playlist.m3u8>

If **cmafstreamingpacketizer** and **cupertinostreamingpacketizer** are both enabled, the adaptive bitrate LL-HLS playlist URL for the same example is:

<https://example.com/live/smil:myStream.smil/playlist_sfm4s.m3u8>

and the playback URL for the Cupertino HLS stream is either:

<https://example.com/live/smil:myStream.smil/playlist.m3u8>

or

<https://example.com/live/smil:myStream.smil/playlist_sfts.m3u8>

where **\_sfts** indicates that the media playlist contains .ts segments.

## Configure THEOplayer to play your LL-HLS stream

1. Set up a basic app with THEOplayer. See "[Getting started on React Native](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/getting-started.md)".
2. Specify the LL-HLS stream generated above as the `src` of your typed source.
3. Set `lowLatency` to `true` on that source.

```typescript
const source: SourceDescription = {
  sources: [
    {
      src: 'https://5d6e17f1ca731.streamlock.net/LowLatencyBBB/myStream/playlist.m3u8',
      type: 'application/x-mpegurl',
      lowLatency: true,
    },
  ],
};
```

## Resources

* [Getting Started with Wowza Streaming Engine](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/)
* [Deliver Apple Low-Latency HLS live streams using Wowza Streaming Engine](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine)

---

# License on React Native

A THEOplayer license is required to use THEOplayer. The licensing schema was previously based on the built-in license from the SDK build, but THEOplayer now allows you to update the license without rebuilding or re-integrating the player SDK.

This article explains how to configure the license at runtime.

## Passing the license through the player configuration

Include the license in the player configuration, either by passing the license as a string or by passing a license URL:

```typescript
const config: PlayerConfiguration = {
  license: 'your_license_here',
};
```

```typescript
const config: PlayerConfiguration = {
  licenseUrl: 'your_licenseUrl_here',
};
```

Pass this configuration to the `<THEOplayerView>` component:

```tsx
<THEOplayerView config={config} />
```

If no valid license can be found, the player will throw a license error.

## FAQ

### Why do I have to configure a license?

In order to provide THEOplayer insights if a stream can be played, it needs to have access to an active license. You can choose to either configure this license, or configure a URL where this license can be retrieved. We recommend everyone to configure an active license or a license URL.

### How do I avoid introducing any dependencies on THEOplayer servers?

There are two important aspects which can introduce a dependency on THEOplayer servers:

1. **Loading a THEOplayer SDK from the THEOplayer CDN.** This issue is only relevant for the Web SDK. In order to avoid this dependency, we recommend to self-host your THEOplayer SDK. The easiest approach is to load the player through npm, or download the player SDK as a zip file from the developer portal. More information on how to self-host your player can be found in "[Self-hosting THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/self-hosting-theoplayer.md)".
2. **Loading a THEOplayer license from the THEOplayer license system.** In order to avoid this dependency, it is important to always keep your license up to date, either by configuring an updated license or by configuring your own license URL. When your THEOplayer license expires, a new player instance will actively check against THEOplayer's license system if there is an updated license available. This system should however only serve as a fallback for applications which cannot be updated.

### Should I pass a license string or a license URL?

We recommend our customers to use the license string whenever possible.

In special cases it is possible to use the license URL instead. Use cases include contractual or legal (for example privacy) requirements. For more information, please contact <support@theoplayer.com>.

If the player is configured with both a license string and a license URL, it will first try to validate the license string. If the license string is either not configured or expired, the player will attempt to request the license URL instead. If no license URL is defined, then a default license URL will be used. If no valid license can be found, the player will throw a license error.

### Should I update my application upon license renewal?

Yes. After renewing your license, you should make sure to include the new THEOplayer license in your next app update.

### What happens if I don't timely update the license in my application?

The player will attempt to update the license up to 72 hours before expiration. For this, the player will request a new license either from the configured license URL, or as a fallback (when there is no license URL configured) from `validate.theoplayer.com`. Either way, if the request is successful, the player will store the license locally. We highly recommend you to self-host the license using the license URL in the player configuration.

For self-hosting, the license file with the latest license string for your application should be hosted. The full URL to this file should then be configured as the license URL in the player configuration.

### Will I still be able to play offline content with my THEOplayer SDK if my license expires?

When your license expires, THEOplayer will attempt to load an updated license. If an updated license is available, offline playback will still function. If no valid license is available, and no license server can be reached (due to the client being offline), the player will throw an error and stop playback. For this reason, it is important to always keep your license up to date.

### What should I do to protect my license?

The THEOplayer license you get from THEOportal is already an obfuscated string. If you want to protect your license, you need to make sure to configure your [page and source domains](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/page-and-source-domains.md) to guarantee that your license string cannot be used anywhere other than the specified pages and/or with those source domains.

---

# Getting started

## Usage

1. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/getting-started.md) to set up THEOplayer in your React Native app.
2. Add an OptiView Live source to your player's source.

### Add an OptiView Live source

After setting up your THEOplayer on your web page, set its source to a `SourceDescription` containing a `THEOliveSource`. You'll need an OptiView Live channel ID:

```javascript
player.source = {
  sources: {
    type: 'theolive',
    src: 'your-channel-id',
  },
};
```

## More information

* [API references](https://theoplayer.github.io/react-native-theoplayer/api/)

---

# Discovery URLs

Before the player can play an OptiView Live channel, it sends a discovery request to find the stream details of that channel (such as its manifest URLs and token security settings). OptiView Live channels are served by one of three discovery API versions:

| API version | Channels                                          |
| ----------- | ------------------------------------------------- |
| V1 (legacy) | Channels created with the legacy THEOlive API.    |
| V2          | Distributions created with the OptiView Live API. |
| V3          | Distributions served by the newest discovery API. |

The player does not know in advance which API version serves your channel. If you do not configure a discovery URL, the player tries its built-in discovery URLs one by one, in this order:

1. V2
2. V1 (legacy)
3. V3

The player stops at the first discovery URL that returns the channel. If your channel is not served by V2, the earlier requests fail before the right one succeeds. These failed requests add a small delay before playback starts, and they show up as `404` responses in the network tab of your browser or in a network proxy. The `404` responses are expected and do not mean that playback failed.

## Why configure a discovery URL

When you configure the discovery URL that serves your channel, the player sends its first discovery request to that URL. This removes the failed requests and the extra startup delay.

Configured discovery URLs do not replace the built-in discovery URLs. The player tries them first, and continues with the built-in discovery URLs (V2, V1, V3) if the configured ones do not return the channel. A wrong discovery URL therefore costs one extra request, but it does not break playback.

On platforms that support both `discoveryUrl` and `discoveryUrls`, the player tries `discoveryUrl` first, then each URL of `discoveryUrls` in the order of the list, and then the built-in discovery URLs.

## Which discovery URL to use

The player derives the API version from the path of the discovery URL, so use the URL exactly as listed for your platform, including the trailing `/`. The URL for V1 channels is different on Web than on the other platforms.

| API version | Web                                             | Android, iOS, Roku                              |
| ----------- | ----------------------------------------------- | ----------------------------------------------- |
| V2          | `https://discovery.theo.live/v2/distributions/` | `https://discovery.theo.live/v2/distributions/` |
| V1 (legacy) | `https://discovery.theo.live/`                  | `https://discovery.theo.live/v2/publications/`  |
| V3          | `https://discovery.theo.live/v3/`               | `https://discovery.theo.live/v3/`               |

React Native and Flutter apps pass the discovery URL to the underlying Web, Android or iOS SDK, so the same rules apply per platform.

> **Find the API version of your channel**
>
> Play your channel without a discovery URL and open the network tab of your browser (or a network proxy for a native app). The discovery request that returns `200` shows the discovery URL that serves your channel. For example, a request to `https://discovery.theo.live/v2/distributions/<your-channel-id>` means that your channel is served by V2.

## Configure the discovery URL

Set the discovery URL in the `theoLive` property of the player configuration. For example, for a channel served by V2:

```tsx
import { THEOplayerView, type PlayerConfiguration } from 'react-native-theoplayer';

const playerConfig: PlayerConfiguration = {
  license: 'your-license',
  theoLive: {
    discoveryUrl: 'https://discovery.theo.live/v2/distributions/',
  },
};

<THEOplayerView config={playerConfig} />;
```

React Native supports one configured discovery URL, which is passed to the Web, Android or iOS SDK. The V2 and V3 discovery URLs are the same on all platforms. For V1 channels, the URL is different on Web (`https://discovery.theo.live/`) than on Android and iOS (`https://discovery.theo.live/v2/publications/`), so use `Platform.OS` to select the right one:

```tsx
import { Platform } from 'react-native';

const playerConfig: PlayerConfiguration = {
  license: 'your-license',
  theoLive: {
    discoveryUrl: Platform.OS === 'web' ? 'https://discovery.theo.live/' : 'https://discovery.theo.live/v2/publications/',
  },
};
```

## Configuration reference

All properties of [`TheoLiveConfiguration`](https://theoplayer.github.io/react-native-theoplayer/api/interfaces/TheoLiveConfiguration.html) are optional.

| Property            | Type      | Platforms         | Description                                                                                                                                                                                                                     |
| ------------------- | --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `discoveryUrl`      | `string`  | Web, Android, iOS | A discovery URL that the player tries before the built-in discovery URLs.                                                                                                                                                       |
| `externalSessionId` | `string`  | Web, Android, iOS | An ID used to report usage analytics.                                                                                                                                                                                           |
| `discoveryHeader`   | `string`  | Web               | A value that the player sends in the `x-theolive-discovery` HTTP header of every discovery request. Only use this if a discovery URL that you configured expects this header, for example your own proxy in front of discovery. |
| `fallbackEnabled`   | `boolean` | Web               | Whether the player plays the fallback stream when a V1 channel has a fallback configured. Defaults to `true`.                                                                                                                   |
| `analyticsDisabled` | `boolean` | Android           | Whether OptiView Live analytics is disabled. Defaults to `false`.                                                                                                                                                               |

The default discovery order V2, V1, V3 applies when the app uses THEOplayer 11.13.0 or later.

---

# Token based security

OptiView Live offers the option to enable JWT token security on channel distribution level. This can be interesting if you only want valid users to access your stream. Read more about the feature and configuring it on your channels on the [token based security guide](https://docs-preview.optiview.dolby.com/pr-932/theolive/distribution/security/token-based-security.md).

This page will demonstrate how to configure the React Native Player SDK for playback of channels with token based security enabled.

## Setting up the React Native THEOplayer SDK for OptiView Live

Refer to the [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/react-native/theolive/getting-started.md) for the prerequisite steps in getting the React Native SDK up and running for OptiView Live playback.

## Configuring THEOplayer to pass the token

The OptiView Live API provides a simple property to configure your token:

```javascript
const token = getToken(); // Generate or request your token, for more information check the token based security guide linked above.
player.theolive.authToken = token;
```

This will ensure the player includes your token in the authorization header on all subsequent requests it performs for playback of your OptiView Live channel.

## Dealing with token expiry and rotation

If your tokens are short-lived, you want to make sure to update the token being passed to the player and requests before it expires, to allow playback to continue beyond expiry. This can simply be done by updating the header on the player in the same way. For example, one could check on an interval that makes sense for your token lifespan whether the token is about to expire and update when necessary, for example:

```javascript
let token;

// Helper function to check whether your token will expire within one minute from now
function tokenWillExpireSoon() {
  const payload = JSON.parse(atob(token.split('.')[1]));
  const exp = payload.exp; // in seconds
  const now = Math.floor(Date.now() / 1000); // current time in seconds
  return exp - now <= 60;
}

function maybeUpdateToken() {
  if (!token || tokenWillExpireSoon(token)) {
    token = getToken(); // Generate or request your token, for more information check the token based security guide linked above.
    player.theolive.authToken = token;
  }
}

maybeUpdateToken();
setInterval(maybeUpdateToken, 30000); // Check every 30 seconds
```

## Clearing the token

If the token isn't needed anymore, e.g. when switching to an unprotected channel or a non-OptiView Live source altogether, the header can be simply removed as follows:

```javascript
player.theolive.authToken = undefined;
```

## Enabling Token Based Security for Safari browsers on iOS <17

Apple devices running an iOS version lower than 17.1 do not support MSE, therefore there are limitations with what is possible when playing an OptiView Live stream. One such limitation is that the above network API approach does not work on those devices. Instead, a service worker needs to be registered to support playback of JWT enabled streams.

The service worker needs to intercept the `fetch` requests originating from the app, to be able to include the `Authorization` header to the requests.

A code snippet for the service worker code is shared below.

> **Note**
>
> Service worker registration is only possible in a secure environment (`https://`) or on `localhost`. There can also only be one service worker active, so if your environment or application already has a service worker active, you will need to include the additional functionality in that service worker.

iOS Safari service worker

```javascript
self.addEventListener('install', () => {
  console.log('Service worker installed!');
  self.skipWaiting();
});

self.addEventListener('activate', (event) => {
  console.log('Service Worker activated');
  // Claim clients so the service worker is in effect immediately
  event.waitUntil(self.clients.claim());
});

// Intercept the fetch event and add in your JWT
self.addEventListener('fetch', (event) => {
  event.respondWith(
    (async function () {
      try {
        const url = new URL(event.request.url);
        if (!url.origin.endsWith('theo.live')) {
          // Requests not made by the player for playback of the OptiView Live channel should not be modified.
          return fetch(event.request);
        }
        const token = getToken(); // Generate or request your token, for more information check the token based security guide linked above.
        // Clone the request and add the JWT header
        const modifiedRequest = new Request(event.request, {
          headers: {
            ...Object.fromEntries(event.request.headers.entries()),
            Authorization: `Bearer ${token}`,
          },
        });
        return fetch(modifiedRequest);
      } catch (error) {
        console.error('Error in fetch handler:', error);
        return new Response('Service Worker Error', { status: 500 });
      }
    })()
  );
});
```

> **Note**
>
> In order for the service worker to be able to intercept requests made from the player library, its scope must include the player SDK files. That means the player and service worker must be hosted on the same path or the player must be hosted in a subfolder of the path where the service worker is hosted.

To register this service worker in to your code, you can attach it this way.

Register service worker

```javascript
function registerServiceWorker() {
  if (!('serviceWorker' in navigator)) {
    console.error('Service worker not supported!');
    return;
  }
  const serviceWorkerScope = "/service/worker/path" // Replace with your own path to the service worker location.
  const serviceWorkerPath = "${root}/service-worker.js"; // Replace with the filename of your service worker.

  // We recommend unregistering actively before (re-)registering as we've seen issues where hard reloads could cause issues if the service worker wasn't unregistered.
  const registration = await navigator.serviceWorker.getRegistration(serviceWorkerPath);
  await registration?.unregister();

  navigator.serviceWorker
    .register(serviceWorkerPath, {
      scope: serviceWorkerScope,
    })
    .then((reg) => {
      if (reg.active) console.log('Service worker registered!');
    })
    .catch((err) => {
      console.error('Could not register service worker!', err);
    });
};

// Initialise the service worker some time early in the process.
if (!(window.MediaSource || window.ManagedMediaSource)) {
  registerServiceWorker();
}
```

---

# UI on React Native

Choose the approach that fits your requirements:

* Use Open Video UI when you want a custom experience without building common player components yourself.
* Use the chromeless player when you want to start with no UI and build every control and interaction from scratch.
* Use the basic default UI when its ready-made controls meet your needs and one is available.

| Approach      | Starting point                 | Flexibility | Development effort |
| ------------- | ------------------------------ | ----------- | ------------------ |
| Open Video UI | Ready-made, modular components | High        | Moderate           |
| Chromeless    | Player API without a UI        | Complete    | Highest            |
| Default UI    | Complete basic player UI       | Basic       | Lowest             |

Building a chromeless UI means using the OptiView Player API and your own application code without a ready-made UI. You are responsible for adding every control, such as a play button, and connecting it to the player API, such as `player.play()`. This approach gives you total control over the UI and UX, but requires an understanding of video playback and the OptiView Player API.

## Open Video UI

Use [Open Video UI for React Native](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native/open-video-ui.md) to customize the player with ready-made, open-source components that you can compose and style to match your application.

## Chromeless

For complete control, build every control and interaction with React Native components and connect them directly to the OptiView Player API.

## Default UI

The React Native SDK does not ship a default UI.

---

# Open Video UI for React Native

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Open Video UI is the OptiView Player customization toolkit. It provides open-source, out-of-the-box components that you can compose and style to create a player UI that matches your product and brand.

Open Video UI has dedicated libraries for each supported platform, so your customized player feels native in your app. These pages explain how to get started and tailor the components to your requirements.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native/open-video-ui/getting-started.md)

[Start building your UI in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native/open-video-ui/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native/open-video-ui/localization.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native/open-video-ui/localization.md)

## [🛝Examples](https://github.com/THEOplayer/react-native-theoplayer-ui/tree/main/example)

[See the player in action!](https://github.com/THEOplayer/react-native-theoplayer-ui/tree/main/example)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native/open-video-ui/changelog.md)

[Find out what's new in Open Video UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native/open-video-ui/changelog.md)

## [\*️⃣API reference](https://theoplayer.github.io/react-native-theoplayer-ui/api/)

[Discover all components and functions provided by Open Video UI for React Native.](https://theoplayer.github.io/react-native-theoplayer-ui/api/)

## [![](/pr-932/img/github.svg)![](/pr-932/img/github_dark.svg)GitHub](https://github.com/THEOplayer/react-native-theoplayer-ui/)

[Browse the source code or report issues on GitHub.](https://github.com/THEOplayer/react-native-theoplayer-ui/)

---

# Getting started with the Open Video UI for React Native

The [`@theoplayer/react-native-ui`](https://www.npmjs.com/package/@theoplayer/react-native-ui) package provides a collection of UI components for [`react-native-theoplayer`](https://www.npmjs.com/package/react-native-theoplayer), the official THEOplayer React Native video player. The following platforms are supported:

* Android, Android TV & FireTV
* iOS & tvOS (Apple TV)
* Web

This guide covers how to set up the React Native UI, and how to add a UI to your `THEOplayerView` component.

![basic-ui](/pr-932/assets/images/example-app-player-ui-028fd4ae776c8d714aa787cd82c253ab.png)

## Prerequisites

If you have no previous experience in React Native, we encourage you to first explore the [React Native Documentation](https://reactnative.dev/docs/getting-started), as it gives you a good start on one of the most popular app development frameworks.

## Installation

Using `npm`, `yarn`, or any other package manager, add `@theoplayer/react-native-ui` to your project's dependencies.

The UI components will depend on a `THEOplayerView` instance provided by `react-native-theoplayer`, so make sure this package is installed.

The UI components also have a few non-transitive dependencies that are required to be installed manually.

```bash
npm install \
  @theoplayer/react-native-ui \
  react-native-theoplayer \
  react-native-svg
```

The package contains a number of transitive dependencies that contain native iOS and Android platform code as well. These are not auto-linked if your project does not already have them as a dependency, so they need to be explicitly defined in the [`react-native.config.js`](https://github.com/react-native-community/cli/blob/main/docs/configuration.md) file in project's root:

react-native.config.js

```typescript
module.exports = {
  dependencies: {
    'react-native-google-cast': {},
    'react-native-svg': {},
  },
};
```

## Using the THEOplayerDefaultUi

The `THEOplayerDefaultUi` can be used to provide basic playback controls to the viewer. As the default UI also includes Chromecast & Airplay support, make sure to configure these first as explained in the [cast documentation](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/doc/cast.md).

```tsx
const App = () => {
  return (
    <THEOplayerDefaultUi
      style={StyleSheet.absoluteFill}
      config={playerConfig}
      onPlayerReady={onPlayerReady}
    />
  );
};
```

The UI can be styled with a `theme: THEOplayerTheme` prop, to give it your own look and feel.

Additional components can be passed as properties to be added to the top/bottom control bars of the UI. These can be components from the `react-native-theoplayer` package, or they could be your own custom components:

```tsx
const App = () => {
  return (
    <THEOplayerDefaultUi
      style={StyleSheet.absoluteFill}
      config={playerConfig}
      {/* A UI component provided by react-native-theoplayer.*/}
      bottomSlot={<PipButton/>}
      {/* A custom component.*/}
      topSlot={<MyCustomComponent/>}
    />
  );
};
```

## Available components

The API documentation of all available components can be found [here](https://theoplayer.github.io/react-native-theoplayer-ui/api/). Their source code can be found [here](https://github.com/THEOplayer/react-native-theoplayer-ui/tree/develop/src/ui).

## Creating your own custom UI

All components inside the `THEOplayerDefaultUi` are available through the `react-native-theoplayer` package and can be used to create your own custom layout. Since `THEOplayerDefaultUi` is our version of a "custom" UI, you could use this as a starting point for your own custom layout.

This use-case is implemented in the [example app](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/doc/example-app.md) that is included in the `react-native-theoplayer` repository, which adds a custom [SourceMenuButton](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/example/src/custom/SourceMenuButton.tsx).

During ad playback the UI probably needs to be different compared to during content. This can include disabling seeking, showing the ad break duration and when the user can skip to content.

Similarly to content playback, the ad UI can be customized by adding components to their respective slots: `adTop`, `adCenter` and `adBottom`.

The customized ad UI is only available for web at this moment. Android and iOS will have a play/pause interaction in the middle of the screen together with the default Google IMA ad layout.

The following example shows a UI layout with only basic playback controls:

```tsx
export default function App() {
  const [player, setPlayer] = useState<THEOplayer | undefined>(undefined);
  const onPlayerReady = (player: THEOplayer) => {
    setPlayer(player);
  };
  return (
    <View style={StyleSheet.absoluteFill}>
      <THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}>
        {player !== undefined && (
          <UiContainer
            theme={DEFAULT_THEOPLAYER_THEME}
            player={player}
            behind={<CenteredDelayedActivityIndicator size={50} />}
            center={
              <CenteredControlBar
                left={<SkipButton skip={-10}/>}
                middle={<PlayButton/>}
                right={<SkipButton skip={30}/>}
              />
            }
            bottom={
              <>
                <ControlBar>
                  <SeekBar />
                </ControlBar>
                <ControlBar>
                  <MuteButton />
                  <TimeLabel showDuration={true} />
                  <Spacer />
                  <FullscreenButton />
                </ControlBar>
              </>
            }
            adTop={
              <ControlBar>
                <AdClickThroughButton />
              </ControlBar>
            }
            adCenter={<CenteredControlBar middle={<PlayButton />} />}
            adBottom={
              <>
                <ControlBar style={{ justifyContent: 'flex-start' }}>
                  <AdDisplay />
                  <AdCountdown />
                  <Spacer />
                  <AdSkipButton />
                </ControlBar>
                <ControlBar>
                  <MuteButton />
                  <SeekBar />
                </ControlBar>
              </>
            }
          />
        )}
      </THEOplayerView>
    </View>
  );
}
```

---

# Localization

The Open Video UI for React Native package supports full localization, allowing you to customize UI text to match the language and tone of your application. You can override default labels—such as menu titles, button text, and indicators—by supplying your own translations using the `locale` prop.

This is especially useful for building internationalized apps or tailoring the viewing experience for a specific audience.

## Example

Here's a simple example that sets Dutch translations for several UI elements:

```tsx
const App = () => {
  const myCustomLocale: Partial<Locale> = {
    backButton: 'Terug',
    settingsTitle: 'Instellingen',
    qualityTitle: 'Videokwaliteit',
    audioTitle: 'Taal',
    subtitleTitle: 'Ondertitels',
    playbackRateTitle: 'Afspeelsnelheid',
    liveLabel: 'LIVE',
    // For a full list of available keys, see the Locale interface.
  };
  return (
    <THEOplayerDefaultUi
      style={StyleSheet.absoluteFill}
      config={playerConfig}
      locale={myCustomLocale}
    />
  );
};
```

---

# Limitations and Known Issues

The Open Video UI for React Native is still being actively developed. These are the current limitations and known issues:

* Support for remote control navigation on TV platforms
* Mobile Ad UI customization
* Interaction with Google IMA elements on web
* TextTrack styling

---

# @theoplayer/react-native-ui

## 0.23.6

### 🐛 Issues

* Fixed seekbar clicks and dragging selecting a different time than an edge-to-edge time preview, especially on long streams.
* Fixed the buffering indicator remaining visible after playback ends or pauses, or reappearing after playback ends or fails.

## \[Unreleased]

### Fixed

* Fixed seekbar clicks and dragging selecting a different time than an edge-to-edge time preview, especially on long streams.
* Fixed the buffering indicator remaining visible after playback ends or pauses, or reappearing after playback ends or fails.

## 0.23.5

### 🐛 Issues

* Fixed TV action buttons notifying user activity after their press callback, which could reveal controls again when entering Picture-in-Picture.
* Fixed action button focus navigation and remote activation on TV platforms while preserving touch gesture handling on mobile and web.

## 0.23.4

### 🐛 Issues

* Fixed skip buttons not appearing for MP4 sources whose `seekable` range stays empty even when a duration is known. `SkipButton` now remains visible when the media has a finite duration (mirroring `SeekBar`'s fallback).

## 0.23.3

### 🐛 Issues

* Fixed an issue on Web where the live indicator was rendered as a corrupted character (mojibake) in release builds.
* Fixed an issue on mobile platforms where the Chromecast button would not be tappable.

## 0.23.2

### 🐛 Issues

* Fixed an issue where the playhead on the `<SeekBar>` would occasionally snap back after scrubbing on iOS Safari.

## 0.23.1

### 🐛 Issues

* Improve labels for text tracks and audio tracks in the `<LanguageMenuView>`.

## 0.23.0

### ✨ Features

* Added support for React Native THEOplayer v11.

## 0.22.0

### ✨ Features

* Exposed `onUserAction()` via a ref in `UiContainer`, enabling parent components to programmatically trigger the UI fade-in animation.

## 0.21.3

### 🐛 Issues

* Resolved an issue where button presses occasionally failed to register in fullscreen presentation mode on iOS and Android.

## 0.21.2

### 🐛 Issues

* Fixed an issue where the `<SeekBar>` would occasionally jump back after seeking.

## 0.21.1

### 🐛 Issues

* Fixed an issue where the `GoToLiveButton` was not available as an exported component.

## 0.21.0

### ✨ Features

* Added a `<GoToLiveButton>` component that only renders itself while playing a DVR stream and being behind the live point.

## 0.20.2

### 🐛 Issues

* Fixed an issue on Web where it was not possible to dismiss the UI by clicking or tapping.
* Fixed an issue on iOS where the UI would not reappear when tapping the screen.

## 0.20.1

### 🐛 Issues

* Fixed an issue where the `<SeekBar>` would be disabled for live content.

## 0.20.0

### ✨ Features

* Fixed an issue where the clickthough of an ad could not be tapped/clicked.
* Added usage of `adTop`, `adCenter` and `adBottom` UI slots to define a custom ad lay-out on both Web and mobile platforms.

## 0.19.0

### ✨ Features

* Added support for feature exclusion in `<THEOplayerDefaultUI>` using the `excludedFeatures` property.

### 🐛 Issues

* Fixed an issue where the seekable ranges passed to the Seekbar could contain NaN values

## 0.18.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 0.17.0

### 🐛 Issues

* Fixed an issue on Android where the controls would not be visible when returning from PiP in paused state.
* Fixed an issue where the skip buttons would sometimes not be visible.
* Fixed an issue where buttons in the `center` slot would not be tappable on smaller player views.
* Optimized UI performance by disabling component rendering while the UI is not visible.

## 0.16.0

### 🐛 Issues

* Fixed an issue where the `<CenteredDelayedActivityIndicator>` was not shown in all platforms when the `waiting` was fired.
* Fixed an issue where high-frequency `progress` events would trigger excessive re-renders and cause memory buildup.
* Fixed an issue on iOS and Android where the `<SeekBar>` time would sometimes jump while seeking to a new position.
* Fixed an issue where menu items with long labels would not be properly displayed.

## 0.15.0

### 🐛 Issues

* Prevent a fade out of the UI while the skip buttons are being used.
* Fixed an issue where the playback rate setting label text didn't fit in its `Text` component.
* Fixed the `useEnded` hook to take into account a `currentTime` that can become slightly larger than the expected stream duration.
* Fixed an issue on Android where a thumbnail preview would contain multiple tiles when the tile image was larger than 2048px.
* Fixed an issue where `<TimeLabel>` would briefly show an invalid duration when playing a live stream.
* Fixed an issue on iOS where both Chromecast and AirPlay buttons were shown as "connected" when connecting to a Chromecast receiver.

### ✨ Features

* Added a `renderAboveThumbComponent` property to the `SeekBar` component that allows customizing an optional component that is rendered above the `SeekBar`'s thumbnail. The `ThumbnailView` remains the default component.

## 0.14.0

### 🐛 Issues

* Fixed an issue where the UI would fade-out while scrubbing the seekbar.

### ✨ Features

* Added `onScrubbing` callback for the Slider component.
* Added `scrubTime` property to the `ChapterLabel` component.
* Added a `<ConditionalPlayButton>` component that only renders itself while the player is not waiting on media content.

## 0.13.0

### ✨ Features

* Added an AutoFocusGuide component to be used on tvOS as a wrapper around for example a controlBar. It catches the focus while navigating the UI with the Apple TV remote.

### 🐛 Issues

* Fixed an issue where the UI became unreponsive for a short while after switching the presentationMode or after the stream has ended.

## 0.12.0

### ✨ Features

* Added localization support.
* Added support for rendering chapter markers & label.

### 🐛 Issues

* Fixed an issue where the play button would stay in the paused state after starting the stream.

## 0.11.0

### ✨ Features

* Added `testID` properties on button and seekBar components to support automated testing.
* Added support for THEOplayer 9.0.

## 0.10.1

### 🐛 Issues

* Fixed an issue for Web where the `SeekBar` component would throw an infinite loop error on Safari browsers.

## 0.10.0

### 📦 Dependency Updates

* Replaced slider component as a dependency of the seek bar.

### 🐛 Issues

* Fixed an issue where an app using the UI would crash when using the `SeekBar` component while streaming a live asset.

## 0.9.0

### ✨ Features

* Ad play-out is resumed when the app is foregrounded again after tapping the ad `clickthrough`. This feature requires `react-native-theoplayer` v8.6.0.

## 0.8.0

### ✨ Features

* Added support for THEOplayer 8.0.

### 🐛 Issues

* Fixed a deprecation warning by removing `defaultProps`.

## 0.7.2

### 🐛 Issues

* Fixed an issue where the `SeekBar`'s seekable state was not updated when switching to a MP4 source.
* Fixed an issue where the `SkipButton` components are not rendered when switching sources while casting.

## 0.7.1

### 🐛 Issues

* Fixed an issue where the mute button sometimes did not update its icon after toggling.

## 0.7.0

### ✨ Features

* Added support for THEOplayer 7.0 and React Native THEOplayer 7.0.

### 🐛 Issues

* Fixed TypeScript type definitions to export interfaces describing the props for all components.

## 0.6.0

### 🐛 Issues

* Fixed an issue where the skip buttons would remain disabled for MP4 sources.

## 0.5.0

### ✨ Features

* Added support for CSAI.

### 🐛 Issues

* Fixed connected state for chromecastButton to not take into account the casting state in general (e.g. airplay should not influence this state).

## 0.4.0

### ✨ Features

* Added support for overriding button icons.

## 0.3.0

### 🐛 Issues

* Fixed several transitioning issues related to PiP state changes and closing menus.

## 0.2.0

### 🐛 Issues

* Fixed an issue where components were still tappable after the UI had faded out.

### ✨ Features

* Assume `PlayerConfiguration.chromeless` to be `true` if not specified.

## 0.1.1

### 🐛 Issues

* Fixed an issue on Web where using the `ChromecastButton` component would result in a crash.

## 0.1.0

### ✨ Features

* Initial release.

---

# Chromeless UI on React Native

A chromeless React Native integration renders the `THEOplayerView` without adding the Open Video UI package. Your application creates the controls and connects them directly to the Player exposed by the view.

Choose this approach when you need complete control over the interface or cannot use the ready-made React Native components. Your implementation must account for playback state, platform differences, accessibility, lifecycle changes, and errors.

Continue with [Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native/chromeless/getting-started.md) for the basic setup.

---

# Getting started with a chromeless UI on React Native

First, follow the [React Native SDK getting-started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/getting-started.md) to install `react-native-theoplayer` and render a minimal `THEOplayerView`.

Do not add `@theoplayer/react-native-ui` when you want a chromeless implementation. Instead:

1. Obtain the Player instance exposed by `THEOplayerView`.
2. Subscribe to playback events and store the state required by your interface.
3. Render your own React Native controls over or around the video view.
4. Call Player methods from those controls.
5. Handle loading, errors, accessibility, and platform lifecycle changes in your application.

Start with play and pause controls, then add seeking, tracks, fullscreen behavior, casting, and advertising controls as your product requires.

If you prefer ready-made components, use [Open Video UI for React Native](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/react-native/open-video-ui.md).

---

# Connectors for THEOplayer React Native SDK

## [Adobe](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/adobe)

[Integrate with Adobe analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/adobe)

## [Adobe Edge](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/adobe-edge)

[Integrate with Adobe Edge analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/adobe-edge)

## [Adscript](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/adscript)

[Integrate with Adscript analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/adscript)

## [![](/pr-932/assets/images/agama-4f500b478e23a543d4eb189b5168dd78.png)Agama](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/agama)

[Integrate with Agama analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/agama)

## [Bitmovin](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/bitmovin)

[Integrate with Bitmovin analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/bitmovin)

## [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/comscore)

[Integrate with Comscore analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/comscore)

## [![](/pr-932/img/conviva.svg)![](/pr-932/img/conviva_dark.svg)Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/conviva)

[Integrate with Conviva analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/conviva)

## [🔒DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/drm)

[Integrate with the DRM connector.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/drm)

## [Engage](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/engage)

[Integrate with the Engage connector.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/engage)

## [![](/pr-932/img/gemius.svg)![](/pr-932/img/gemius_dark.svg)Gemius](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/gemius)

[Integrate with Gemius analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/gemius)

## [![](/pr-932/assets/images/mux-1d56b7f17d515324f1547519db52c2ba.png)Mux](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/mux)

[Integrate with Mux analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/mux)

## [Nielsen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/nielsen)

[Integrate with Nielsen analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/nielsen)

## [![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAy0SURBVHgB7d1PbhRJFsfxiLIxs+iW2DbuaZVvwNzASGB6iU+AOQGuHd2YwSVhYId9AsMJYNmYkewb2DdwafjjWXoBEvUvYzKqSMqmjV1ZlZnxIuL7kVpqoZaM6M5f53svMp5SAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAORwt3q8fpn8pAKXQSij78Ju5S7tKmXr6m1z/0vm0tbC3eawAFEZkABwurl6Zm/tpN/3NXRv9qm4lpt/89e2TFwpAIcQFwNkP/ykH7U5veWHvWUsBmIqoABjj4f/GaP2i0+42CQJgcmICIM/DP6JbSidbV99sbCoAuYkIgMke/pPoDwCTcB4A0z/8I5QFQD5OA6DIh/+k4diw95IgAM7nLADKevhHKAuAizgJgPIf/pN0q93pXudtAPi7ygOg2od/hP4A8HeVBoCrh/+E4/Rnb/6y87ipAFQXAAIe/hPoDwBWJQEg6+EfoSxA7EoPAKkP/ylab7bb3S2CALEpNQC8ePi/oSxAfEoNgPc31zZrWt1TXhkEwXIaBAcKCFxNlUhrc0V5x9Rrurb/4dbDbW4jQuhKDQCfaWNWLs/NHh4trT1SQKAIgAsYpdY/Lj08fH/zzxUFBIYAGMugLNj+uLT2irIAISEA8rltywL6AwgFATCBYX/g0i5lAXxHAEwsKwseHr67sbaoAA8RAFMz9Zma2qUsgI8IgIIwNoSPCICCMTaETwiAUnwbG+5TFkAyAqBc1xgbQjICoALZ2PDjrQerChCEAKiMqSujn9v+wIelP24rQAACoHJ23fnMK8oCSEAAOHJybGgvTlGAAwSAY3ZseHnu533GhnCBABBhdKyYsgBVIgBEMXXGhqgSASBQNjbkWDHKRgCIZeocK0bZCADxhv0BygKUgQDwRDY2/Hjr4XOCAEUhAHxjzCq3EaEoBICXRmPDNAg82LoEqQgAr7HEBNMhAALwtT+wz9gQeREA4bjC2BB5EQDBYYkJxkcAhIslJrgQARA4lpjgPARAFFhigrMRAFFhiQlOIwAixBITZAiAiDE2BAEQPZaYxIwAQIYlJhEiAHAKY8O4EAA4w2hsyBKTsBEAOAdLTEJHAOBCLDEJFwGAsbHEJDwEAHJiiUlICABMiCUmISAAMBWWmPiNAEABWGLiKwIABWKJiW8IABTu9NiQIJCMAEBphmNDjhVLRgCgZIwNJSMAUBHGhhIRAKgUS0xkIQDgAktMhCAA4BBLTFwjACABS0wcIQAgBrcRVY8AgDCjsWEaBNcUSkUAQKhBEOxTFpSLAIBoLDEpFwEALzA2LAcBAI8M+wNHN9d2KQuKQQDAO0arRcaGxSAA4C3GhtMjAOA5lphMgwBAIFhiMgkCAEFhiUk+pQaASdSBAhxgicl4tCrZ0e/36yaZ2U1/VF0Bbhy0O73lhb1nLYVTSg+AjE3imtaPCAK4YrR+0Wl3mwTBSGUBYB0url+Zm+utpj+UY51wRLeUTrauvtnYVKg2ADK2LEiSmXWt9B0FOKFbiek3f3375IWKmJMAyLy7sbY4UzPblAVwJfaywGkAZOgPwLX0QVj/0um9jC0IRASAZcuCfn92tabVPQU4EV9ZICYAMvQH4J5utTvd6zG8DYgLgAxlAVyLoT8gNgAyBAEcO04fks1fdh43VYDEB4BFWQD3wuwPeBEAmeGx4tnn6d/y2Sdced3u9BqhlAVeBUCGsgDOab3Zbne3fA8CLwMg82FpLS0LzB2CAG74XxZ4HQAW/QG4NwiC5TQIvPv83fsAyHztD7xK/5ZtMnDCx7FhMAGQoT8A1+yxYl/GhsEFQGbYHxgcK+ZaKDjgR38g2ACw6A/ANW3U3pdu767UsiDoAMhwLRlck9ofiCIAMvQH4Ja8siCqALC4lgzu6ZZRvcb8ztPXyrHoAiBDfwCuSSgLog2ATFoWXEvLgleUBXDF5dgw+gDI0B+AW276AwTACcOyYHaF/gAcqnSJCQFwBvoDcK2q/gDLQc/wy1/PWvM7Gyumr5bTfxUtBVRssOT08kzp917wBjAG+gOolFF77Zne3YW/yi8DCIAxURagfKbVT/Tdf/7n8Z6qCAGQE0GAEhwbpbY6nU+bC3ubx6pCBMCEKAtQBKNN2uz73Kj6wc8QAFN6f+PBaq1mPzvWdQWMK63z+0Y1q3zdPwsBUADKAuRwnLb4m1LWkxMABRp8dtyf3U7/VBcV8J20zm+6qPPPQwCUgP4ATqlwrJcXAVAiriWLXfVjvbwIgJLRH4jSYKw3v/N4XQkXVAC8u7G2OKvVo6SmW9KuX+La8ji4HuvlFUQAHC3er6vLlx4ZY1ZO/rrE65npDwRKyFgvL68D4HBx9co/5n66l75uraof1tkyr2f+2h/gs2P/HScmafi6HszbAPjv0h+3Z5XdFGzq4/zzEq9npj/gN4ljvby8C4CszjcTztolXs/MtWSeETzWy8ubALCv+5fnfk5fmc2qmppuKZ1sSTmNlaE/IJ38sV5eXgTA0dLao/Pr/EnJ6w9wbblI3oz18hIdAPZ1f6amt8et8yclsSygPyBDYtRWt/tp3ec6/zwiA2Aw1rs0u22qPlOv9Wa73d2SFATDEDTblAUV83Ssl5eoACi2zp+UzLEh/YHKeD3Wy0tMAPzv5r/vJTpZV2LOzeu04WNENXxsWdDvz67W9OD7AhTL2a08LjkPAPuKW6up51roEVn6AxEIaKyXl7MAcFbnT8geK/7S+bQl6f8OlAXTCm+sl1flATDe8V2p6A8EItixXl6VBsDwP9Tac+X99/G61e50r1MW+Cf0sV5elQTAtMd3pZLaHzCJ/UZClb5VxiuRjPXyKjUAfvSZbmCO0z/ETT47lsqkZZsRV7ZJUWoAfFh68CKeV1Kh/YF4ry2PcqyXFwFQvNftTq9Bf8ChiMd6eREAJRHbHwj62nLGenmxHrwkg/XOc5d2bS2uhLBrz6++fXw9McndwNae22Ubjas7Gws8/PnwBlAJ3TKq15jfefpaCRLCteWM9aZDAFSIY8UFYqxXCALAgeGx4t5LeecHZnblTwtMq6eSxm/C3qZ8RQ/AgXQ8tS6yP5DW0IL7A3as12x3Pv+Lh784vAE4Nzg/sPzr2ycHShBR15Yz1isNbwDOmXpN1/Y/3Hq4fWhPTgphP5TRtd6CUealciT92Qf9RF23kwse/nLwBiCM0G1GVV9bbsd6TWm3NoeINwBhbH/g49LDQ0n9AVueVNUfsGO9dufTAg9/NXgDkO2g3ektyxsbzq4U3h9grOcEAeCBsM8PMNZziRLAA9mx4o+3Hji8Lfk0Ozac39lYMX21PGFZwFhPAN4AvBPEtWSv27Veg86+ewSAp6SWBeddW27HekmiG9T5chAAvhO4zeiM/gBjPaEIgCDILQu0rtW5lUcuAiAo8rYZQTamAEEx9Zma2pV2rBhyEQABGo4NZw+PltYe2UUsCvgBAiBgw8+Of96XdKwYshAAwRt8bbhtvy+gLMD3CIBomLotC+gP4CQCIDJf+wP7tj+gED0CIE5XJH52jOoRAFEb9geObq7tUhbEiQCAslub6Q/EiQDAN9lnx4e/EwKxIAAwYtSevaGYz3TjMasAlmpGiwCIm72VZ6vT+czXepEiAOLFrTwgAKLD7bs4gQCIx/BWnh1u5cEIARABu2yj2/20Tp2P7xEAIWOpJi5AAASJsR7GQwCEhbEeciEAAmG0edFpf27w4CMPAsB338Z6G3sKyIkA8NdxYpKGtF0A8AsB4CG7VJNlGygCAeATxnooGAHgBcZ6KAcBINtgrDe/s7GugBIQAEJxfBdVIACk4Ws9VIgAkIOxHipHALj39fguYz1UjwBwibEeHCMAnGCsBxkIgGoNb+V5w608kIEAqAhjPUhEAJSNsR4EIwBKY1o9lTR+e/v0tQKEIgCKx6088AYBUCyWbcArBEABjDIHSaIb1PnwDQEwncFYb56xHjxFAEyIsR5CQADklY71EjX4aOdAAZ4jAMbG8V2EhwC4GGM9BIsAOMdg2YbuNxnrIVQEwFlYtoFIlBoAxpg9rfUd5Y/h13o7jPUQB61K9v7mnys1XdtWwrFsAzEqPQAs0SHArTyIWCUBYMkLAcZ6QGUBYAkJAS7hBL6qNAAslyEwGOu1Pzd48IGhygPAqjwEuJUHOJOTALAqCgGWbQDncBYAVpkhwFgPuJjTALAKDwHGesDYnAeAVUwIMNYD8hIRANYUITAY683vPF5XAHIREwBW3hDgVh5gOqICwBorBBjrAYUQFwDWj0PAtBJjmoz1gGKIDADruxDg+C5QArEBYA1CQNXuMNYDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABALP4PxPhKst9YjwYAAAAASUVORK5CYII=)Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/yospace)

[Integrate with Yospace analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/yospace)

## [![](/pr-932/assets/images/youbora-0b7d7160409d9f3e1c31532385bf7698.png)Youbora](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/youbora)

[Integrate with Youbora analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native/youbora)

---

# THEOplayer React-Native Adobe Connector

An Adobe analytics connector for `@theoplayer/react-native`.

## Installation

The `@theoplayer/react-native` package has a peer dependency on `react-native-device-info`, which has to be installed as well:

```sh
npm install \
  react-native-device-info \
  @theoplayer/react-native-analytics-adobe
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, the Media Collection API's end point, Visitor Experience Cloud Org ID, Analytics Report Suite ID and the Analytics Tracking Server URL.

```tsx
import { useAdobe } from '@theoplayer/react-native-analytics-adobe';

const uri = "<Media Collection API's end point>";
const ecid = "<Visitor Experience Cloud Org ID>";
const sid = "<Report Suite ID>";
const trackingUrl = "<Tracking Server URL>";
const metadata = {}; // Optionally provide initial metadata
const userAgent = "<Custom User-Agent>"; // Optionally provide a custom user-agent header value.
const debug = true; // Optionally provide a debug flag for extra logging.
const useNative = true; // Use a native connector on iOS & Android; `false` by default.

const App = () => {
  const [adobe, initAdobe] = useAdobe(uri, ecid, sid, trackingUrl, metadata, userAgent, debug, useNative);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize Adobe connector
    initAdobe(player);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

The Adobe connector will dispatch player events to Adobe with standard metadata the player has access to, such as duration or whether it is a live or vod.

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
import { AdobeMetaData } from "./Types";

const onUpdateMetadata = () => {
  const metadata: AdobeMetaData = {
    "params": {
      "media.channelName": "channelName",
      "media.id": "mediaId"
    },
    "customMetadata": {
      "customTag1": "customValue1",
      "customTag2": "customValue2"
    }
  };
  adobe.current?.updateMetadata(metadata);
};
```

---

# @theoplayer/react-native-analytics-adobe

## 1.17.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.17.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.16.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.15.1

### 🐛 Issues

* Fixed an issue where heart-beat requests could continue after destroying a session on Web.

## 1.15.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/adobe/LICENSE) file for more information.

## 1.14.3

### 🐛 Issues

* Fixed an issue on Android where the playhead for Live events would exceed the maximum value.

## 1.14.2

### 🐛 Issues

* Fixed an issue on Android where the properties from the passed metadata was not included with the `sessions` request.
* Fixed an issue where the required `visitor.marketingCloudUserId` property was not included with the `sessions` request.

## 1.14.1

### 🐛 Issues

* Fixed an issue on Android where the connector could crash when adding new events because of a `ConcurrentModificationException`.

## 1.14.0

### ✨ Features

* Fixed an issue on Android where the event payload would be partially obfuscated when enabling minification with R8.
* Fixed an issue on Android where the `playhead` and `contentLength` payload properties should be integers.

## 1.13.0

### ✨ Features

* Fixed an issue on Android where chapter events would not be properly reported.
* Updated Android's target SDK version to 36.

## 1.12.2

### 🐛 Issues

* Fixed an issue where player API was used on the wrong thread, resulting in a crash due to concurrent access of player internals.

## 1.12.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.12.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.11.0

### ✨ Features

* Added optional native connector implementations for iOS and Android.

## 1.10.0

### ✨ Features

* Bumped dependency on react-native-device-info

## 1.9.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.8.0

### ✨ Features

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors

## 1.7.1

### 🐛 Issues

* Fixed a build issue where the `Settings` object would not be found when using the connector with react-native-web.

## 1.7.0

### ✨ Features

* Dropped usage of the NativeModules import to make the connector ready for the new architecture

### 📦 Dependency Updates

* Updated dependency `react-native-device-info` to version `>=10.0.0 <14.0.0`.

## 1.6.0

### ✨ Features

* Added support for THEOplayer 8.0

## 1.5.0

### 🐛 Issues

* Fixed an issue on Web where an asset with a pre-roll ad would report an invalid media duration.

### ✨ Features

* Added `debug` flag for extra logging.

## 1.4.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

## 1.3.1

### 🐛 Issues

* Fixed an issue where the `media.length` would be not be correctly converted to seconds for VOD and Live streams.

## 1.3.0

### 🐛 Issues

* Fixed an issue where the `media.length` would be wrong when starting a session for a stream with a pre-roll ad.

## 1.2.1

### 📦 Dependency Updates

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.2.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.1.0

### ✨ Features

* Added a `userAgent` property to the connector's constructor to allow setting a custom `User-Agent` header value when doing requests.
* Changed the default `User-Agent` header value on Android to custom value that contains `Mozilla/5.0 (Linux; U; ${operatingSystem}; ${localeString}; ${deviceName} Build/${deviceBuildId})`.
* Changed the default `User-Agent` header value on iOS to custom value that contains `Mozilla/5.0 (${model}; CPU OS ${osVersion} like Mac OS X; ${localeIdentifier})`.

## 1.0.0

### ✨ Features

* Added `useAdobe` hook to create and initialize an Adobe connector. See README.md for usage.

## 0.7.0

### 🐛 Issues

* Fixed sending play/pause on program boundaries.
* Fixed sending ad ping events if a program boundary occurs mid ad.

## 0.6.0

### ✨ Features

* Add `media.name` to `sessionStart` request if `player.source.metadata.title` is set.
* Add functionality to stop the current session and start a new one.

## 0.5.0

### ✨ Features

* Removed numeric separators for constants.

## 0.4.0

### ✨ Features

* Optional metadata field to the constructor.

## 0.3.0

### 🐛 Issues

* Fixed correctly passing the `playHead` property.
* Fixed correctly passing custom metadata to the session request.
* Fixed an issue where the `chapterStart` parameters would be missing.
* Fixed some http issues during `sendEventRequest`.

### ✨ Features

* Improved sending error event.
* Improved property typing.

## 0.2.0

### 🐛 Issues

* Removed a `postinstall` script from package.json.
* Fixed an issue where the session would not be ended when destroying the connector.

## 0.1.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Adobe Edge Connector

An Adobe analytics connector for `@theoplayer/react-native` using the [Media Edge API](https://developer.adobe.com/client-sdks/edge/media-for-edge-network/).

Media Edge API is the third generation of solution for tracking Media Events. It features more analytics data, and the delay before the data can be analysed is much shorter: \~15 minutes compared to \~45 minutes with Media Heartbeats.

To set up terminology, in chronological order, media tracking solutions were:

1. Media Heartbeats solution
2. Media Collection API
3. Media Edge API

## Installation

```sh
npm install @theoplayer/react-native-analytics-adobe-edge
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance and a configuration object with separate parts for Web and mobile platforms.

```tsx
import {useAdobe} from '@theoplayer/react-native-analytics-adobe-edge';

const config = {
  web: {
    datastreamId: 'abcde123-abcd-1234-abcd-abcde1234567',
    orgId: 'ADB3LETTERSANDNUMBERS@AdobeOrg',
    edgeBasePath: 'ee',
    edgeDomain: 'my.domain.com',
    debugEnabled: true,
  },
  mobile: {
    environmentId: 'abcdef123456/abcdef123456/launch-1234567890abcdef1234567890abcdef12',
    debugEnabled: true,
  },
}

/**
 * An optional custom identity map to associate the media session with user identities.
 */
const customIdentityMap = {
  EMAIL: [
    {
      id: 'user@example.com',
      authenticatedState: 'authenticated',
      primary: false,
    },
  ],
}

const App = () => {
  const [adobe, initAdobe] = useAdobe(config, /* optional */ customIdentityMap);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize Adobe connector
    initAdobe(player);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

The Adobe connector will dispatch player events to Adobe with standard metadata the player has access to, such as duration or whether it is a live or vod.

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
import {AdobeCustomMetadataDetails} from "@theoplayer/react-native-analytics-adobe-edge";

const onUpdateMetadata = () => {
  const metadata: AdobeCustomMetadataDetails[] = [
    {name: 'title', value: 'test'},
    {name: 'custom1', value: 'value1'},
  ]
  adobe.current?.updateMetadata(metadata);
};
```

### Setting an custom identity map

Besides passing a custom identity map during initialization, you can also set or update the identity map at any time:

```typescript
import {AdobeIdentityMap} from "@theoplayer/react-native-analytics-adobe-edge";

const onUpdateIdentityMap = () => {
  const identityMap: AdobeIdentityMap = {
    CUSTOMER_ID: [
      {
        id: 'customer-12345',
        authenticatedState: 'authenticated',
        primary: true,
      },
    ],
  };
  adobe.current?.setIdentityMap(identityMap);
};
```

### Starting a new session during a live stream

By default, the connector will start a new session when a new asset is loaded. However, during live streams, you might want to start a new session periodically when a new program starts. You can do this by calling `stopAndStartNewSession` with the new program's metadata:

```typescript
const onNewProgram = () => {
  adobe.current?.stopAndStartNewSession({
    'friendlyName': 'Evening News',
  });
};
```

---

# @theoplayer/react-native-analytics-adobe-edge

## 1.3.4

### 🐛 Issues

* On web, retire potentially stale Adobe media sessions after prolonged suspension and restart tracking when content playback resumes. Preserve custom metadata, discard stale queued events, and ignore late confirmations from retired sessions. Keep Alloy's automatic tracking API; reliable cancellation of its retired-session pings requires the paired Alloy cleanup fix.

## 1.3.3

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.3.2

### 🐛 Issues

* Upgraded @adobe/alloy dependency to v2.35.0.

## 1.3.1

### 🐛 Issues

* Fixed an issue on Web where media events (e.g. `media.bitrateChange`) would fail with "Session ID is not available for playerId" when the media session start was not yet confirmed by the edge network. The session is now only marked as started after confirmation, failed session starts are retried, and tracker promise rejections no longer surface as unhandled promise rejections.
* Fixed an issue on Web where a playback session would not be tracked at all if the player's `loadedmetadata` event fired before the Adobe media tracker was initialized.
* Fixed an issue on Web where a media session would be left open on the edge network when the viewer changed source before the session start was confirmed.
* Fixed an issue where the Adobe VA Edge API would reject media events such as `adStart` and `adComplete` with a 400 Bad Request ("Playhead must be in range \[0, 86400] seconds") during live playback on platforms that report the playhead as an absolute presentation timestamp (e.g. Samsung Tizen). The playhead is now always clamped to the range accepted by the API.

## 1.3.0

### ✨ Features

* Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.2.1

### 🐛 Issues

* Bumped @adobe/alloy dependency to v2.34.1.

## 1.2.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.1.1

### 🐛 Issues

* Fixed an issue on Web where the `bitRate` property would not be passed as an integer value.
* Fixed an issue where the metadata set with `updateMetadata` would not be passed when starting a session.

## 1.1.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/adobe-edge/LICENSE) file for more information.

## 1.0.0

### 💥 Breaking Changes

* Updated the connector to use the latest Adobe Experience Platform Mobile and Web SDKs.

## 0.7.0

### ✨ Features

* Added optional native connector implementations for iOS and Android.

## 0.6.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 0.5.0

### ✨ Features

* Bumped dependency on react-native-device-info

## 0.4.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 0.3.2

### 🐛 Issues

* Fixed a build issue where the `Settings` object would not be found when using the connector with react-native-web.

## 0.3.1

### 📦 Dependency Updates

* Updated dependency `react-native-device-info` to version `>=10.0.0 <14.0.0`.

## 0.3.0

### ✨ Features

* Added support for THEOplayer 8.0

## 0.2.0

### ✨ Features

* Fixed an issue where ad duration was reported as a floating-point value instead of an integer.

## 0.1.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native AdScript Connector

A [Nielsen AdScript](https://adscript.admosphere.cz/) analytics connector for `@theoplayer/react-native`.

## Installation

```sh
npm install @theoplayer/react-native-analytics-adscript
```

## Prerequisites

### Android

On Android, the connector requires downloading the private [AdScript client library](https://adscript.admosphere.cz/download/AdScriptApiClient_v1.0.10.aar.gz) module into the app's `libs/` folder. Pass the SDK location to the connector by setting the `adScriptSdkDir` in your app's `gradle.properties` file:

```bash
# Location of the AdScript SDK
adScriptSdkDir=./app/libs/
```

### iOS & tvOS

On Apple platforms, the connector requires downloading the private `AdScriptAPIClient` archive.

Create a `Frameworks` folder in your app's `ios` folder, copy the Adscript SDK XCFramework in it and add this `AdScriptApiClient.podspec` file inside, which describes the structure and metadata of Adscript's CocoaPod:

```ruby
Pod::Spec.new do |spec|
  spec.name         = "AdScriptApiClient"
  spec.version      = "1.0.8"
  spec.summary      = "The Adscript Api Client for iOS"

  spec.homepage     = 'https://github.com/THEOplayer/iOS-Connector'
  spec.license      = { :type => 'MIT', :file => 'LICENSE' }
  spec.author       = "Dolby Laboratories, Inc."
  spec.source       = { :git => 'https://github.com/THEOplayer/iOS-Connector.git', :tag => spec.version.to_s }

  spec.source_files  = "Classes", "Classes/**/*.{h,m}"
  spec.ios.vendored_frameworks = "AdScriptApiClient.xcframework"
end
```

To enable IDFA (Identifier for Advertisers), replace the framework reference:

```text
spec.ios.vendored_frameworks = "AdScriptApiClient.xcframework"
```

with

```text
spec.ios.vendored_frameworks = "AdScriptApiClient_withidfa.xcframework"
```

Finally, include the AdScript SDK as dependency in your app's `Podfile`:

```ruby
  pod 'AdScriptApiClient', :path => 'Frameworks/'
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, an `implementationId`, and a `metadata` object.

```tsx
import { useAdScript, AdScriptMetadata } from '@theoplayer/react-native-analytics-adscript';

const adscriptImplementationId = "myImplementionId";
const adscriptContentMetadata: AdScriptMetadata = {
  assetId: "abc98731568435405",
  type: "content"
};

const App = () => {
  const [adscript, initAdScript] = useAdScript(adscriptImplementationId, adscriptContentMetadata, true /*debug*/);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize AdScript connector
    initAdScript(player);
  };

  return <THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady} />;
};
```

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
const onUpdateMetadata = () => {
  adscript.current?.updateMetadata({
    assetId: 'updatedId',
    type: "content",
    // ...
  });
}
```

### Passing additional information

Additional information about the logged-in user from the client database:

```typescript
const onUpdateUser = () => {
  adscript.current?.updateUser([
    "866d3a3c-aa87-4fe7-9066-8286641edd17",     // client-side user identifier (customerId)
    "cf895a00-a987-4501-ac00-6adb57014129",     // client-side user device identifier (Android_ID)
    "9530321a-d3d0-4bda-8704-1eb94a5940c3",     // client-side profile identifier of the logged-in user (profileId)
    "jsg75682-k276t-kw82-k8d5-8926sh6528j2",    // optional - SW device identifier for a situation where there are multiple device IDs in the client DB (typically a) HW ID - fill in i2, b) SW ID - fill in i4).
    "ef3c6dc72a26912f07f0e733d51b46c771d807bf"  // fingerprint of the user's email address
  ]);
}
```

---

# @theoplayer/react-native-analytics-adscript

## 1.5.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.5.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.4.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.3.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/adscript/LICENSE) file for more information.

## 1.2.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.1.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.1.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Agama Connector

An Agama analytics connector for `@theoplayer/react-native`. Currently only the Android/Android TV platforms is supported.

## Installation

### Dependencies

The `@theoplayer/react-native` package has peer dependencies on these packages, which have to be installed as well:

* `react-native-device-info` to obtain extra device information;
* `@react-native-async-storage/async-storage` to persistently store a unique deviceId across sessions;
* `@react-native-community/netinfo` to obtain information on network connection and quality.

```sh
npm install \
  react-native-device-info \
  @react-native-async-storage/async-storage \
  @react-native-community/netinfo \
  @theoplayer/react-native-analytics-agama
```

Some of these dependencies explicitly rely on `react-native` as a peer dependency. If you are using the `react-native-tvos` fork, it is necessary to specify this override in your package.json:

```json
  "overrides": {
    "react-native": "npm:react-native-tvos@^0.76.5-0"
  }
```

### Agama library

The Agama libraries need to be provided by the hosting app. Since they are privately hosted, you need to download them from [Agama's support site](https://support.agama.tv/). Put the libraries next to the source and load them at the start of the app, along with the necessary polyfills:

```typescript
import { AgamaPolyfills } from "@theoplayer/react-native-analytics-agama";

AgamaPolyfills.install();
require('./static/empclient.min');
require('./static/empclient.compat5.min');
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance and a [configuration object](https://github.com/THEOplayer/react-native-connectors/blob/-/agama/src/api/AgamaConfiguration.ts). A `useAgama` React hook is provided for convenience. It takes care of initialization and clean-up of the connector. It is also possible to create the connector explicitly by creating an instance of `AgamaConnector`, in which case the `destroy()` method must be called when destroying either the connector or the player.

```tsx
import { useAgama, AgamaConfiguration } from '@theoplayer/react-native-analytics-agama';

const config: AgamaConfiguration = {
  config: 'emp_service=http://127.0.0.1:8191/report;report_interval=60;id_report_interval=240;operator_id=fooSoo',
  logLevel: 'debug',
  application: 'React-Native THEOplayer',
  applicationVersion: '1.0.0'
}

const App = () => {
  const [agama, initAgama] = useAgama(config);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize Agama connector
    initAgama(player);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

### Source description

Source-related [analytics properties](https://github.com/THEOplayer/react-native-connectors/blob/-/agama/src/api/AgamaSourceConfiguration.ts) can be passed in the source description as follows:

```typescript
player.source = {
  "sources": {
    "src": "https://cdn.theoplayer.com/video/adultswim/clip.m3u8",
    "type": "application/x-mpegurl"
  },
  "analytics": [{
    "integration": "agama",
    "asset": "The Venture Bros",
    "cdn": "theoplayer",
    "serviceName": "svod",
    "contentTitle": "The Venture Bros",
    "streamType": "vod",
    "contentType": "movie",
    "contentDescription": "Agama demo movie"
  }]
}
```

As it is possible to configure more than one analytics integration, it is important to include the `integration: 'agama'` property to let the connector known which object to use.

---

# @theoplayer/react-native-analytics-agama

## 1.13.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.13.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.12.1

### 🐛 Issues

* Fixed an issue where the measuring network interceptor would cause ABR to break and make the player stall during play-out.

## 1.12.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.11.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/agama/LICENSE) file for more information.

## 1.10.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.9.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.8.0

### ✨ Features

* Bumped dependency on react-native-device-info

## 1.7.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.6.1

### 📦 Dependency Updates

* Updated dependency `react-native-device-info` to version `>=10.0.0 <14.0.0`.

## 1.6.0

### ✨ Features

* Added support for THEOplayer 8.0

## 1.5.0

### 🐛 Issues

* Fixed an issue where the player would jump to a different time stamp as result of a test left-over.

## 1.4.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

## 1.3.0

### ✨ Features

* Added optional `deviceType` property to `AgamaConfiguration` to overwrite the physical device type. By default, the `deviceType` is derived from the platform.

## 1.2.1

### 📦 Dependency Updates

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.2.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.1.1

### ✨ Features

* Added `SourceConfiguration` and `AgamaConfiguration` types to package exports.

### 🐛 Issues

* Fixed the location of `manifest.json` in order to make it discoverable for web platforms.

## 1.1.0

### 📦 Dependency Updates

* Set upper boundary on THEOplayer's Android SDK version.

## 1.0.3

### 🐛 Issues

* Fixed an issue where creating a build manifest would fail due to a missing dependency.

## 1.0.2

### 🐛 Issues

* Fixed an issue where creating a build manifest would fail due to a missing dependency.

## 1.0.1

### 🐛 Issues

* Fixed the keywords list in `package.json`.
* Fixed missing `manifest` script in npm package.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Bitmovin Connector

A Bitmovin analytics connector for `@theoplayer/react-native`.

## Installation

Using npm:

```sh
npm install @theoplayer/react-native-analytics-bitmovin
```

Using yarn:

```sh
yarn add @theoplayer/react-native-analytics-bitmovin
```

## Usage

### Configuring the connector

Create the connector using the `useBitmovin` hook with the initial configuration.

Once the player is ready, initialize the connector by calling the `initBitmovin` function with the `THEOplayer` instance and the **default metadata**, which contains properties that do not change during the session.

Finally, before the player source is set, update first the **source metadata** by calling the `updateSourceMetadata` function.

> **IMPORTANT:** Call `updateSourceMetadata` before setting the player source, otherwise the source metadata will not be included in the analytics events.

```tsx
import {
  useBitmovin,
  AnalyticsConfig,
  DefaultMetadata,
  SourceMetadata
} from '@theoplayer/react-native-analytics-bitmovin';

const bitmovinConfig: AnalyticsConfig = {
  licenseKey: 'license-key-here',
  logLevel: 'DEBUG'
}

const defaultMetadata: DefaultMetadata = {
  cdnProvider: 'akamai',
  customUserId: 'custom-user-id-1234',
  customData: {
    customData1: 'value1',
    customData2: 'value2'
  }
};

const sourceMetadata: SourceMetadata = {
  title: 'Sample Video',
  videoId: 'video-1234',
  cdnProvider: 'akamai',
  path: '/home/videos/sample-video',
  isLive: false,
  customData: {
    customData10: 'value10',
    customData11: 'value11'
  }
}

const App = () => {
  const [bitmovin, initBitmovin] = useBitmovin(bitmovinConfig);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize connector with player & default metadata.
    initBitmovin(player, defaultMetadata);

    // Update source metadata.
    bitmovin.updateSourceMetadata(sourceMetadata);

    // Set player source after updating source metadata.
    player.source = {/*...*/}
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

### Dynamically updating custom data

The connector allows updating the **custom data** at any time during the playback session, which will cause the new custom data to be merged with the existing custom data and included in all subsequent analytics events:

```tsx
bitmovin.updateCustomData({
  customData0: 'newValue0',
  customData1: 'newValue1'
});
```

### Updating source metadata during a live stream

The connector allows dynamically updating the **source metadata**, for example during a live stream when the program changes:

```tsx
bitmovin.programChange({
  title: 'New Live Program',
  videoId: 'live-program-5678',
  customData: {
    customData10: 'newValue10'
  }
});
```

### Getting the current impression ID

The current impression ID can be retrieved asynchronously. The promise resolves to `undefined` when there is no active impression or analytics session:

```tsx
const impressionId = await bitmovin.getImpressionId();
```

---

# @theoplayer/react-native-analytics-bitmovin

## 1.6.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.6.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.5.0

### ✨ Features

* Added a getter for the current Bitmovin `impressionId`.

## 1.4.1

### 🐛 Issues

* Fixed an issue on Android where R8 would obfuscate `setCustomData` methods of the Bitmovin collector API.

## 1.4.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.3.0

### ✨ Features

* Relax iOS Bitmovin collector dependency lock to major versions

## 1.2.0

### ✨ Features

* Updated `updateCustomData` to merge incoming `customData` with the existing data on iOS and Android.

## 1.1.0

### ✨ Features

* Added `sendCustomDataEvent` for Web.
* Upgraded Bitmovin Web SDK to GA release v2.51.

## 1.0.1

### 🐛 Issues

* Fixed an issue on iOS where the updateCustomData method was not correctly bridged.

## 1.0.0

### ✨ Features

* Updated Android Bitmovin player SDK dependency to version range `[3.24.0, 4.0.0)`.
* Changed `customData` to allow up to 100 custom fields.

## 1.0.0-alpha.12

### 🐛 Issues

* Fixed an issue where a wrong value for `customUserId` would be set on Android.

### 📦 Dependency Updates

* Upgraded iOS Bitmovin collector to GA release to prevent app store validation rejections.
* Upgraded Android Bitmovin collector to GA release v3.23.0.

## 1.0.0-alpha.11

### ✨ Features

* Added `programChange` method to allow passing new source metadata during a live stream.
* Added support for Web and iOS platforms.

## 1.0.0-alpha.10

### ✨ Features

* Initial release.

---

# THEOplayer React-Native Comscore Connector

A Comscore analytics connector for `@theoplayer/react-native`.

## Installation

```sh
npm install @theoplayer/react-native-analytics-comscore
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, a ComscoreConfiguration (which contains your publisher id) and the ComscoreMetadata of the first source you will set to the player (you can change it dynamically throughout the entire lifecycle of the connector):

```jsx
import { useComscore } from '@theoplayer/react-native-analytics-comscore';

export const comscoreMetadata: ComscoreMetadata = {
    mediaType: ComscoreMediaType.longFormOnDemand,
    uniqueId: 'testuniqueId',
    length: 634.566,
    stationTitle: 'THEOTV',
    programTitle: 'Big Buck Bunny',
    episodeTitle: 'Intro',
    genreName: 'Animation',
    classifyAsAudioStream: false,
    customLabels: {
        testcustomlabel: 'testcustomvalue'
    }
};

const comscoreConfig: ComscoreConfiguration = {
    publisherId: '<your publisher id (aka c2 id)',
    applicationName: '<your app name>',
    userConsent: ComscoreUserConsent.granted,
    usagePropertiesAutoUpdateMode: ComscoreUsagePropertiesAutoUpdateMode.foregroundOnly,
    debug: true
};

const App = () => {
    const [comscore, initComscore] = useComscore(COMSCORE_METADATA, comscoreConfig);

    const onPlayerReady = (player: THEOplayer) => {
        // Initialize Comscore connector
        initComscore(player);
    };

    return <THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady} />;
};
```

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
const onUpdateMetadata = () => {
    comscore.current.update({
        mediaType: ComscoreMediaType.longFormOnDemand,
        uniqueId: 'testuniqueId',
        length: 634.566,
        stationTitle: 'THEOTV',
        programTitle: 'Big Buck Bunny',
        episodeTitle: 'Intro',
        genreName: 'Animation',
        classifyAsAudioStream: false,
        customLabels: {
            testcustomlabel: 'testcustomvalue'
        }
    });
};
```

### ComscoreMetadata fields

Based on the `ComscoreMetadata` type, you can tell which fields are mandatory and which aren't. Note that this is purely for the integration to work correctly. Depending on the Comscore solution you are using, different fields are required/optional. The mandatory fields in the `ComscoreMetadata` type are the ones that are mandatory for all three Comscore solutions:

* Video Metrix (V)
* Cross Platform Product Suite (X)
* Cross Media Audience Measurement (C)

| Property                           | Required | Optional |
| ---------------------------------- | -------- | -------- |
| `mediaType`                        | All      |          |
| `uniqueId`                         | All      |          |
| `length`                           | All      |          |
| `c3?`                              | V        |          |
| `c4?`                              | V        |          |
| `c6?`                              | V        |          |
| `stationTitle`                     | All      |          |
| `stationCode?`                     |          | All      |
| `networkAffiliate?`                |          | All      |
| `publisherName?`                   | X C      | V        |
| `programTitle`                     | All      |          |
| `programId?`                       |          | V C      |
| `episodeTitle`                     | All      |          |
| `episodeId?`                       |          | X C      |
| `episodeSeasonNumber?`             | X C      |          |
| `episodeNumber?`                   | X C      |          |
| `genreName`                        | All      |          |
| `genreId?`                         |          | All      |
| `carryTvAdvertisementLoad?`        | X        |          |
| `classifyAsCompleteEpisode?`       | X        |          |
| `dateOfProduction?`                |          | C        |
| `timeOfProduction?`                |          | C        |
| `dateOfTvAiring?`                  | X C      |          |
| `timeOfTvAiring?`                  |          | X C      |
| `dateOfDigitalAiring?`             | X C      |          |
| `timeOfDigitalAiring?`             |          | X C      |
| `feedType?`                        | X        |          |
| `classifyAsAudioStream`            | Al       |          |
| `deliveryMode?`                    |          | All      |
| `deliverySubscriptionType?`        |          | All      |
| `deliveryComposition?`             |          | All      |
| `deliveryAdvertisementCapability?` |          | All      |
| `mediaFormat?`                     |          | All      |
| `distributionModel?`               |          | All      |
| `playlistTitle?`                   |          | C        |
| `totalSegments?`                   |          | V C      |
| `clipUrl?`                         |          | V C      |
| `videoDimension?`                  |          | C        |
| `customLabels?`                    |          | All      |

---

# @theoplayer/react-native-analytics-comscore

## 1.15.2

### 🐛 Issues

* Fixed Android builds failing with `Dependency 'com.comscore:android-analytics:6.16.0' requires ... compile against version 37 or later of the Android APIs` on apps compiled against android-36. The connector's floating `6.+` dependency now defaults to `6.15.+`, staying below the version that declares `minCompileSdk=37`, which is unsupported by current Android Gradle plugin releases. Apps that already target a newer compileSdk can still override via `THEOplayerComscore_comscoreVersion`.

## 1.15.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.15.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.14.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.13.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/comscore/LICENSE) file for more information.

## 1.12.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.11.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.11.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.10.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.9.0

### ✨ Features

* Passing the usagePropertiesAutoUpdateMode configuration property to the native iOS connector.

## 1.8.2

### 🐛 Issues

* Fixed an issue on iOS where the podspec files did not contain all references when not using the New Architecture.

## 1.8.1

### 🐛 Issues

* Fixed an issue on iOS where the project would not build when used in a project that has New Architecture enabled.

## 1.8.0

### ✨ Features

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors

## 1.7.1

### 🐛 Issues

* Deleted dependency on the removed ad module for Android.

## 1.7.0

### ✨ Features

* Added support for THEOplayer 8.0

## 1.6.0

### 📦 Dependency Updates

* Removed setup for Mux connector on tvOS. The Mux pod is only available for iOS.
* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

## 1.5.0

### 🐛 Issues

* Fixed an issue on Android where `notifyPlay()` was not called when the player would resume play-out.
* Fixed an issue on Android where the user consent variables were not properly passed.
* Fixed an issue on Web where the player position is reported as a decimal value instead of an integer.

### ✨ Features

* Added the `usagePropertiesAutoUpdateMode` option to `ComscoreConfiguration` to indicate whether background playback is supported.

## 1.4.1

### ✨ Features

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.4.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.3.0

### 🐛 Issues

* Fixed an issue on Web where some `duration` and `currentTime` values were reported wrong.

## 1.2.0

### 🐛 Issues

* Fixed an issue on Android where the usage properties would not update when the app transitions to the background.

## 1.1.0

### 📦 Dependency Updates

* Updated Web dependency to Comscore SDK v7.7.0

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Conviva Connector

A Conviva analytics connector for `@theoplayer/react-native`.

## Installation

```sh
npm install @theoplayer/react-native-analytics-conviva
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, some initial metadata and a config object:

```jsx
import { useConviva } from '@theoplayer/react-native-analytics-conviva';

const convivaMetadata: ConvivaMetadata = {
  ['Conviva.applicationName']: 'THEOplayer',
  ['Conviva.viewerId']: 'your_viewer_id'
};

const convivaConfig: ConvivaConfiguration = {
  customerKey: 'your_customer_key',
  debug: true,
  gatewayUrl: 'https://[account]-test.ts-testonly.conviva.com'
};

const App = () => {
  const [conviva, initConviva] = useConviva(convivaMetadata, convivaConfig);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize connector
    initConviva(player);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

The `convivaMetada` object contains key-value pairs that are passed directly to the Conviva SDK. Most media related properties, such as its streamURL, duration or whether it is a live or vod stream, are passed by the connector itself. Any metadata related properties can be passed through the open key-value map:

| Key                   | Value                           |
| --------------------- | ------------------------------- |
| `'Conviva.assetName'` | Asset name of the next program. |
| `'customTag'`         | Any custom value.               |

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
const onUpdateMetadata = () => {
  const metadata: ConvivaMetadata = {
    ['customTag1']: "customValue1",
    ['customTag2']: "customValue2",
  };
  conviva.current?.setContentInfo(metadata);
};
```

---

# @theoplayer/react-native-analytics-conviva

## 1.15.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.15.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

### 🐛 Issues

* * Bumped the default Conviva Core SDK version on Android to v4.0.51.

## 1.14.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.13.1

### 🐛 Issues

* Fixed an issue on iOS where the native ios connector version was locked to 10.8 patch updates.

## 1.13.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/conviva/LICENSE) file for more information.

## 1.12.0

### ✨ Features

* Passing initial metadata as persistent conviva metadata on iOS

## 1.11.1

### 🐛 Issues

* Fixed an issue where a platform-based import could cause compilation issues on Android and iOS platforms.

## 1.11.0

### ✨ Features

* Added support for Amazon Vega OS.
* Updated Android's target SDK version to 36.

### 🐛 Issues

* Fixed an issue where on iOS the stopAndStartNewSession was blocked when the player was in a paused state.

## 1.10.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.10.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.9.1

### 🐛 Issues

* Fixed an issue where the connector would output a `HashMap` conversion build error for Android platforms.

## 1.9.0

### ✨ Features

* Added support for THEOplayer 9.0.

### 🐛 Issues

* Fixed an issue on Android where an app would crash when accessing the connector's `stopAndStartNewSession` method.

## 1.8.3

### 🐛 Issues

* Fixed an issue on Android where the optional `debug` property in `ConvivaConfiguration` was treated as being required.

### ✨ Features

* Added the option on Android to allow setting a different connector version using `THEOplayerName_connectorVersion`.

## 1.8.2

### 🐛 Issues

* Fixed an issue on iOS where the podspec files did not contain all references when not using the New Architecture.

## 1.8.1

### 🐛 Issues

* Fixed an issue on iOS where the project would not build when used in a project that has New Architecture enabled.

## 1.8.0

### ✨ Features

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors

## 1.7.1

### 🐛 Issues

* Deleted dependency on the removed ad module for Android.

## 1.7.0

### ✨ Features

* Added support for THEOplayer 8.0

## 1.6.0

### ✨ Features

* Added support for broadcasted ad events.

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

### 🐛 Issues

* Fixed an issue where on iOS (^17.2) bitrate reporting was broken due to a deprecated iOS notification name.

## 1.5.1

### 📦 Dependency Updates

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.5.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.4.0

### 📦 Dependency Updates

* Upgraded connector for Web to 1.2.0.

## 1.3.0

### 📦 Dependency Updates

* Upgraded connector for Android to 5.10.0-1 with dependency on Conviva sdk 4.0.33.
* Upgraded Android compileSdk and targetSdk versions to 33.

### ✨ Features

* Updated example app to use @theoplayer/react-native-ui.

## 1.2.1

### 📦 Dependency Updates

* Updated connector for Web to v1.1.7.

## 1.2.0

### 📦 Dependency Updates

* Updated connector for Web to v1.1.6.
* Updated connector for Android to v5.6.0-1.

## 1.1.0

### 🐛 Issues

* Fixed an issue on iOS where the bitrate was not reported after a stop and start new session action.

## 1.0.0

### ✨ Features

* Initial release

---

# React Native THEOplayer DRM

The `@theoplayer/react-native-drm` package provides a set of connectors for [react-native-theoplayer](https://github.com/THEOplayer/react-native-theoplayer), allowing playback of DRM-protected content.

## Installation

```sh
npm install @theoplayer/react-native-drm
```

## Usage

The connector needs to be registered to the `ContentProtectionRegistry`, providing both `integrationId` and `keySystemId`:

```typescript
import { ContentProtectionRegistry } from 'react-native-theoplayer';
import { EzdrmFairplayContentProtectionIntegrationFactory } from 'react-native-theoplayer-drm';

ContentProtectionRegistry.registerContentProtectionIntegration(
  'ezdrm',   // integrationId
  'fairplay', // keySystemId
  new EzdrmFairplayContentProtectionIntegrationFactory()
);
```

The combination of both `integrationId` and `keySystemId` points the player towards the connector for a specific source, in this case the `ezdrm` connector for `fairplay`:

```typescript
const source = {
  "sources": {
    "src": "<source_url>",
    "contentProtection": {
      "integration": "ezdrm",
      "fairplay": {
        "certificate": "<base64encoded_certificate>",
        "licenseAcquisitionURL": "<license_url>"
      },
    }
  }
};
```

## Connectors

The [THEOplayer DRM integrations repository](https://github.com/THEOplayer/samples-drm-integration) contains a list of integrations for native Web, Android & iOS THEOplayer SDKs.

As the content protection API of `react-native-theoplayer` is very similar to that of THEOplayer's native Web SDK, the available Web connectors can mostly be reused as-is. These connectors are not available as npm packages however, and sometimes have dependencies on web-specific utilities. Because of this, the `@theoplayer/react-native-drm` package provides the following connectors, readily available to be used by `react-native-theoplayer`:

| Vendor                       | Widevine | Playready | FairPlay |
| ---------------------------- | -------- | --------- | -------- |
| BuyDRM KeyOS                 | ✓        | ✓         | ✓        |
| EZDRM                        | ✓ (\*)   | ✓ (\*)    | ✓        |
| Verimatrix MultiDRM Core DRM | ✓        | ✓         | ✓        |
| Anvato                       | ✓        | ✗         | ✓        |
| Axinom                       | ✓        | ✗         | ✓        |
| CastLabs                     | ✓        | ✓         | ✓        |
| PallyCon                     | ✗        | ✗         | ✓        |
| MediaKind                    | ✓ (\*)   | ✓ (\*)    | ✓        |

(\*) No connector is needed for these DRM vendors; it is handled by the player's default DRM flow.

---

# @theoplayer/react-native-drm

## 1.14.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.13.0

### ✨ Features

* Added integration for MediaKind DRM.

## 1.12.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.11.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/drm/LICENSE) file for more information.

## 1.10.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.9.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.8.1

### 🐛 Issues

* Prevent warning on named export for version API

## 1.8.0

### ✨ Features

* Add sdkVersions to connector API

## 1.7.1

### 🐛 Issues

* Fixed an issue where the npm package would not contain the proper build files.

## 1.7.0

### ✨ Features

* Added support for THEOplayer 8.0.

## 1.6.0

### ✨ Features

* Changed the BuyDRM KeyOS connector to work without the `x-keyos-authorization` header.

## 1.5.0

### ✨ Features

* Added BuyDRM KeyOS connector for fairplay, widevine and playready.
* Added support for `react-native-theoplayer` v7.0.0.

## 1.4.0

### ✨ Features

* Added Axinom connector for fairplay and widevine.

## 1.3.1

### 🐛 Issues

* Fixed an issue where the PallyCon connector was not included in the module exports.

## 1.3.0

### ✨ Features

* Added CastLabs connector.
* Added PallyCon connector.
* Optimized `readStreamAsArrayBuffer` method.

## 1.2.0

### 🐛 Issues

* Fixed an issue in the Anvato DRM connector where the license request response body was not correctly processed.

## 1.1.0

### ✨ Features

* Added license request error result for Anvato connector.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Engage Connector

An Engage connector for `@theoplayer/react-native`. Currently only Android platforms are supported.

## Overview

The Engage connector aims to **re-engage users** with your app by offering interesting content, promotions and deals. Users can be driven directly to a relevant page within your app using **deep links**.

Typical use-cases are the **"Continue Watching"** feature, which allows users to continue media play-back from where they left off bookmarks, **(personalized) recommendations** promoting content that might be of interest to the user, or a **sign-in** option that navigates users to the sign-in page of your app.

Currently, the engage connector only supports the [Android Engage SDK](https://developer.android.com/guide/playcore/engage).

### Terminology

In this document, we will refer to the following concepts:

* **Entity**: A content asset, which can be a "*movie*", "*tvShow*", "*tvSeason*", "*tvEpisode*", "*liveStream*", "*videoClip*", "*signIn*" or "*subscription*".

* **Cluster**: A collection of entities grouped together in single UI view. Available types are:

  * "*Continuation*" or "*Continue Watching*": Contains unfinished videos and relevant newly released episodes.
  * "*Featured*": Showcases a selection of entities.
  * "*Recommendation*": Shows personalized content suggestions.

## Installation

In addition to installing the engage connector module, it is also necessary to add a dependency to `react-native-mmkv` to allow persistently storing engage data.

```sh
npm install \
  @theoplayer/react-native-engage \
  react-native-mmkv
```

The Engage SDK is set as a peer dependency, so the Android app using it still has to add an explicit dependency in Gradle, for mobile applications:

```text
implementation "com.google.android.engage:engage-core:1.5.4"
```

or, for Android TV:

```text
implementation "com.google.android.engage:engage-tv:1.0.0"
```

## Usage

### Creating a connector instance

Create an instance of an Engage client, using either the convenient `useEngage` hook or by creating a direct instance of the connector:

```tsx
const engageConfig = {
  debug: true,
  recommendationTitle: "Because you enjoyed",
};

// Creating a client instance using the connector
const client = await EngageConnector.createClient(engageConfig);

// ... or, alternatively, by using a hook
const engage = useEngage(engageConfig);
```

### Creating clusters

Using the Engage connector API, a *cluster* can be created, or requested if it already exists on the device. A cluster is a grouped set of data which can be of type "Continuation" (or "Continue Watching"), "Featured" or "Recommendation".

```tsx
import { ClusterType, ContinuationClusterConfig } from "@theoplayer/react-native-engage";

const continuationConfig: ContinuationClusterConfig = {
  accountProfile: {
    accountId: 'accountId',
    profileId: 'profileId'
  },
  syncAcrossDevices: false
}

// Create or get the "Continuation" cluster.
const continuation = client.getCluster(ClusterType.Continuation, continuationConfig);
```

Alternatively, the `useCluster` hook can be used:

```tsx
const continuation = useCluster(engage, ClusterType.Continuation, continuationConfig);
```

### Updating or "publishing" cluster data

The cluster data can be updated either **manually** by manipulating its entities:

```tsx
// Add or remove continuation entities.
continuation.addEntity({
  id: "id0",
  name: "The Dark Knight",
  posters: [/**/],
  // ...
});
```

or when requested **by the connector**. For example, on Android platforms when a broadcast message is sent to the app, or when a scheduled update request is set (e.g., each 12 hours).

### Persisting cluster data

The cluster data is persistently stored on the device each time it is changed. When the app reopens and creates a new Engage client, the stored that will be loaded first.

### Personalized experience

#### SignIn entity

An optional "*signIn*" entity can be displayed on the engage surface, which directs users to a sign-in page of the app.

```typescript
const signIn: SignIn = {
  type: EntityType.SignIn,
  name: "Sign In Demo",
  subtitle: "Demonstrates usage of sign-in card",
  actionUri: "https://xyz.com/signin",
  actionText: "Sign In",
  posters: [
    {
      uri: "https://xyz.com/signin.png",
      width: 320,
      height: 180,
      theme: ImageTheme.Light
    }
  ]
}

engage?.setSignInEntity(signIn);
```

#### Subscription and entitlement data

In addition, it is possible to share app subscription and entitlement data via the Engage SDK, allowing users to easily find content they are entitled to and enable Google TV to deliver highly relevant content recommendations to users, directly within their Google TV experiences on TV, mobile and tablet.

Subscription information can be published whenever the user performs one of the following actions:

* The user logs in to the app;
* The user switches between profiles, if the app supports single account with multiple profiles;
* The user purchases a new subscription;
* The user upgrades an existing subscription;
* An existing user subscription or tiered subscription expires;

```typescript
const accountProfile = {
  accountId: 'testAccountId',
  profileId: 'testProfileId'
}

const subscription: Subscription = {
  type: EntityType.Subscription,
  providerPackageName: 'testProviderPackage',
  subscriptionType: SubscriptionType.Active
}

engage?.setSubscription(accountProfile, subscription);
```

The "*subscription*" entity that contains one or more entitlements.

## Validating the published items

On Android, the [Verification App ](https://developer.android.com/guide/playcore/engage/workflow#shared-files)can be used to check the state and contents of all published clusters. Warnings are shown in case the published data does not satisfy the requirements.

| ![](/pr-932/assets/images/verification_app_1-ae90dab88fff325e81c2ea7f8fc6daa9.png) | ![](/pr-932/assets/images/verification_app_2-b2a56fe09fe65b7c138c71903eb21a86.png) |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Published Continuation cluster**                                                 | **Published Feature cluster with warnings**                                        |

## Example application

The example app showcases the integration of the Engage connector in a React Native application.

### Manipulating clusters

Tapping items (or entities) will add them to the "Continuation" cluster, while tapping items in the Continuation cluster will remove them again. On each update the cluster is persistently stored and published to the platform.

### Unpublished clusters

Tapping the bin icon results in removing and unpublishing (deleting) the cluster from the platform.

| ![](/pr-932/assets/images/example_app_1-bb6d1f16fc649a29ec6467ff7999ace3.png) | ![](/pr-932/assets/images/example_app_2-6fed560d9d0480fc9d1407dbb4bf0afc.png) |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Continuation and Featured clusters**                                        | **Swimlanes with entities**                                                   |

---

# @theoplayer/react-native-engage

## 0.6.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 0.6.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/engage/LICENSE) file for more information.

## 0.5.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 0.4.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 0.3.0

### ✨ Features

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors

## 0.2.1

### 🐛 Issues

* Enforced mandatory entity attributes.

## 0.2.0

### ✨ Features

* Added support for React Native v0.75.

## 0.1.2

### 🐛 Issues

* Fixed an issue where bundling the connector for Web would result in a recursive import error.

## 0.1.1

### ✨ Features

* Downgraded to default Kotlin dependency to version 1.8.22.
* Upgraded to version 1.5.4 of the Android Engage SDK.
* Made the engage SDK a peer dependency by using `compileOnly` in Gradle.
* Added the `Subscription` and `SignIn` entities with an API to set the current user subscription and signIn card.

### 📦 Dependency Updates

* Replaced async-storage with react-native-mmkv for persistent key-value storage.

## 0.1.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Gemius Connector

A Gemius analytics connector for `@theoplayer/react-native`.

## Installation

```sh
npm install @theoplayer/react-native-analytics-gemius
```

## Prerequisites

### Android

The Gemius Android SDK is not publicly available as a Maven module, so additional work is needed to include it as connector dependency. It requires downloading the private `GemiusSDK_2.0.8.aar` module into the app's `libs/` folder. The SDK location needs to be passed to the connector by setting the `gemiusSdkDir` in your app's `gradle.properties` file:

```bash
# Location of the Gemius SDK
gemiusSdkDir=./app/libs/
```

If a different version of the Gemius SDK is used than the default (v2.0.8), make sure to update the version in the `gradle.properties` file accordingly:

```text
THEOplayerGemius_gemiusVersion=2.0.8
```

### iOS & tvOS

On Apple platforms, the connector requires downloading the private `GemiusSDK_iOS` archive, which contains a multiplatform binary platform module for both iOS and tvOS.

Create a `Frameworks` folder in your app's `ios` folder, copy the Gemius SDK XCFrameworks in it and add this `GemiusSDK.podspec` file inside, which describes the structure and metadata of Gemius's CocoaPod:

```ruby
Pod::Spec.new do |spec|
  spec.name         = "GemiusSDK"
  spec.version      = "2.0.6"
  spec.summary      = "The Gemius SDK for iOS"

  spec.homepage     = 'https://github.com/THEOplayer/iOS-Connector'
  spec.license      = { :type => 'MIT', :file => 'LICENSE' }
  spec.author       = "Dolby Laboratories, Inc."
  spec.source       = { :git => 'https://github.com/THEOplayer/iOS-Connector.git', :tag => spec.version.to_s }

  spec.source_files  = "Classes", "Classes/**/*.{h,m}"
  spec.ios.vendored_frameworks = "GemiusSDK.xcframework"
  spec.tvos.vendored_frameworks = "GemiusSDKtvOS.xcframework"
end
```

Finally, include the Gemius SDK as dependency in your app's `Podfile`:

```ruby
  pod 'GemiusSDK', :path => 'Frameworks/'
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance and a `GemiusConfiguration` object.

```tsx
import { useGemius, GemiusConfiguration, ProgramType } from '@theoplayer/react-native-analytics-gemius';

const gemiusConfig: GemiusConfiguration = {
  applicationName: "Demo",
  applicationVersion: "1.0",
  hitCollectorHost: "your_hit_collector_host",
  gemiusId: "your_gemius_id",
  debug: true
}

const App = () => {
  const [gemius, initGemius] = useGemius(gemiusConfig);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize Gemius connector
    initGemius(player);
  };

  return <THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady} />;
};
```

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
const onUpdateMetadata = () => {
  gemius.current?.update('programId', {
    name: 'Demo asset',
    duration: 1200,
    programType: ProgramType.VIDEO,
    customKey: 'customValue',
    // ...
  });
}
```

---

# @theoplayer/react-native-analytics-gemius

## 1.5.2

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.5.1

### 🐛 Issues

* Fixed a compilation error on iOS with THEOplayer SDK 11, where the `Ad.adBreak` property became optional.

## 1.5.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.4.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.3.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/gemius/LICENSE) file for more information.

## 1.2.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.1.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.1.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Mux Connector

A Mux analytics connector for `@theoplayer/react-native`, supporting Web, iOS and Android.

## Installation

```sh
npm install @theoplayer/react-native-analytics-mux
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, some initial metadata and a config object:

```jsx
import { useMux } from '@theoplayer/react-native-analytics-mux';

const muxOptions = {
  debug: true,
  data: {
    env_key: 'ENV_KEY', // required
    // Site Metadata
    viewer_user_id: '12345',
    experiment_name: 'player_test_A',
    sub_property_id: 'cus-1',
    // Player Metadata
    player_name: 'My Main Player',
    player_version: '1.0.0',
    player_init_time: 1451606400000,
    // Video Metadata
    video_id: 'abcd123',
    video_title: 'My Great Video',
    video_series: 'Weekly Great Videos',
    video_duration: 12000, // in milliseconds
    video_stream_type: 'on-demand', // 'live' or 'on-demand'
    video_cdn: 'Akamai'
  }
};

const App = () => {
  const [mux, initMux] = useMux();

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize connector
    initMux(player, muxOptions);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

### Change program within a stream

In some cases, you may have the program change within a stream, and you may want to track each program as a view on its own. An example of this is a live stream that streams multiple programs back to back.

For this purpose, the `changeProgram` method can signal the start of a new program and pass updated metadata to the connector.

```typescript
mux.current?.changeProgram({
  video_title: 'New program',
  video_duration: 160000
});
```

---

# @theoplayer/react-native-analytics-mux

## 1.14.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.14.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.13.1

### 🐛 Issues

* * Bumped Mux SDK version to v0.8.0 to support OptiView player SDK v11.

## 1.13.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.12.0

### ✨ Features

* Updated Mux SDK to support OptiView player v10.

## 1.11.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/mux/LICENSE) file for more information.

## 1.10.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.9.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.9.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.8.0

### 📦 Dependency Updates

* Updated iOS Mux dependency to v0.13.

## 1.7.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.6.3

### 📦 Dependency Updates

* Updated dependencies on Android, allowing THEOplayer v8 and using latest Mux connector version.

## 1.6.2

### 🐛 Issues

* Fixed an issue on iOS where the podspec files did not contain all references when not using the New Architecture.

## 1.6.1

### 🐛 Issues

* Fixed an issue on iOS where the project would not build when used in a project that has New Architecture enabled.

## 1.6.0

### ✨ Features

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors

## 1.5.0

### 📦 Dependency Updates

* Updated the mux connector on Android to be compatible with THEOplayer v8 versions.

### 🐛 Issues

* Changed the `useMux` hook to allow the `MuxOptions` to be passed with the initialize instead of directly passing it into the hook itself.
* Fixed an issue on iOS where an incorrect THEOplayer version would be passed.

## 1.4.1

### 🐛 Issues

* Deleted dependency on the removed ad module for Android.

## 1.4.0

### ✨ Features

* Fixed a issue where the connector would crash when using Mux-Stats-THEOplayer 0.7 in combination with recent react-native-theoplayer releases.

## 1.3.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

## 1.2.0

### 🐛 Issues

* Fixed and issue on Android where Mux's Maven repository was not included in the root repository list.

## 1.1.1

### 📦 Dependency Updates

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.1.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Nielsen Connector

A Nielsen analytics connector for `@theoplayer/react-native`.

## Installation

```sh
npm install @theoplayer/react-native-analytics-nielsen
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, the `appId` provided by Nielsen, and `instanceName` that describes the player or site, and an optional set of `NielsenOptions`:

```tsx
import { useNielsen, NielsenOptions } from '@theoplayer/react-native-analytics-nielsen';

const appId = 'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX';

const instanceName = 'THEOplayer demo';

const nielsenOptions: NielsenOptions = {
  // Enables Debug Mode which allows output to be viewed in console
  nol_sdkDebug: 'debug'

  // HTML DOM element id of the player container (if implementing Viewability/Audibility)
  // containerId: 'player1',

  // Optout on initialization of the SDK
  // optout: false,
};

const App = () => {
  const [nielsen, initNielsen] = useNielsen(appId, instanceName, nielsenOptions);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize Nielsen connector
    initNielsen(player);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
const onUpdateMetadata = () => {
  nielsen.current?.updateMetadata({
    'title': 'Episode Title',
    'assetid': 'unique_id_500291'
  });
};
```

---

# @theoplayer/react-native-analytics-nielsen

## 1.13.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.13.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.12.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.11.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/nielsen/LICENSE) file for more information.

## 1.10.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.9.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.9.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.8.1

### 🐛 Issues

* Fixed an issue where the connector would output a `HashMap` conversion build error for Android platforms.

## 1.8.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.7.3

### 🐛 Issues

* Fixed an issue where the `NielsenOptions` type would not be properly provided by the package.

### ✨ Features

* Added the option on Android to allow setting a different connector version using `THEOplayerName_connectorVersion`.

## 1.7.2

### 🐛 Issues

* Fixed an issue on iOS where the podspec files did not contain all references when not using the New Architecture.

## 1.7.1

### 🐛 Issues

* Fixed an issue on iOS where the project would not build when used in a project that has New Architecture enabled.

## 1.7.0

### ✨ Features

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors

## 1.6.0

### ✨ Features

* Apply correct update mechanism for nielsen options dictionary

## 1.5.1

### 🐛 Issues

* Deleted dependency on the removed ad module for Android.

## 1.5.0

### ✨ Features

* Added support for THEOplayer 8.0

## 1.4.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

## 1.3.0

### 📦 Dependency Updates

* Upgraded Nielsen Android SDK to v9.2.0.0.
* Depend on latest Nielsen Android connector from Maven repository.
* Upgraded Nielsen web connector to v1.1.2.

## 1.2.0

### ✨ Features

* Removed any existing connector from the player on Android before attaching a new instance, avoiding duplicates.

## 1.1.1

### 📦 Dependency Updates

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.1.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Yospace Connector

A Yospace Server-Side Ad Insertion (SSAI) connector for `@theoplayer/react-native`. The connector only supports Android platforms for now.

## Installation

```sh
npm install @theoplayer/react-native-yospace
```

The connector uses the **private Yospace SDK**, for which credentials need to be configured.

### Android

On Android, configure the Maven repository credentials either setting project properties, for example in the `gradle.properties` file:

```text
YOSPACE_USERNAME=myUserName
YOSPACE_PASSWORD=myPassword
```

or, alternatively, by setting both `YOSPACE_USERNAME` and `YOSPACE_PASSWORD` as environment variables on your build system. Make sure not to expose them!

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, some initial metadata and a config object:

```tsx
import { useYospace, YospaceSSAIConfiguration } from '@theoplayer/react-native-yospace';

const App = () => {
  const [yospace, initYospace] = useYospace();

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize connector
    initYospace(player);

    // Set source with ssai integration 'yospace', and optional session properties.
    player.source = {
      sources: [
        {
          src: 'https://csm-e-sdk-validation.bln1.yospace.com/csm/extlive/yospace02,hlssample42.m3u8?yo.br=true&yo.av=4',
          type: 'application/x-mpegurl',
          ssai: {
            integration: 'yospace',

            // Optional, the default is 'live'.
            streamType: 'live',

            // Optional session properties
            //
            // @see YospaceSessionProperties.ts for available properties.
            sessionProperties: {
              prefetchResources: true
            }
          } as YospaceSSAIConfiguration
        }
      ]
    }
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

---

# @theoplayer/react-native-yospace

## 1.8.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.8.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.7.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.6.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/yospace/LICENSE) file for more information.

## 1.5.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.4.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.4.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.3.1

### 🐛 Issues

* Fixed an issue where the connector would throw an error while building on Android.

## 1.3.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.2.3

### 🐛 Issues

* Fixed an issue on iOS where the podspec files did not contain all references when not using the New Architecture.

## 1.2.2

### 🐛 Issues

* Fixed an issue on iOS where the project would not build when used in a project that has New Architecture enabled.

## 1.2.1

### 🐛 Issues

* Deleted dependency on the removed ad module for Android.

## 1.2.0

### ✨ Features

* Added support for THEOplayer 8.0

## 1.1.0

### ✨ Features

* Passed default debug flags to disable any logging.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Youbora Connector

A Youbora analytics connector for `@theoplayer/react-native`.

## Installation

```sh
npm install @theoplayer/react-native-analytics-youbora
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, the `appId` provided by Youbora, and `instanceName` that describes the player or site, and an optional set of `YouboraOptions`:

```tsx
import { useYoubora, youbora } from '@theoplayer/react-native-analytics-youbora';

const youboraOptions: youbora.Options = {
  'accountCode': 'powerdev',
  // 'username': 'dev',
  // 'parse.HLS': true,
  // 'parse.CDNNode': true,
  // 'network.ip': '1.1.1.1',
  // 'network.isp': 'MyISP',
  // 'network.connectionType': 'dialup',
  // 'content.transactionCode': 'myTransCode',
  // 'content.resource': 'mysrc.mp4',
  'content.isLive': true,
  'content.title': 'My Title',
  // 'content.title2': 'My Title2',
  // 'content.duration': 100,
  // 'content.fps': '100',
  // 'content.bitrate': 1000000,
  // 'content.throughput': 8000000,
  // 'content.rendition': 'My Rendition',
  // 'content.cdn': 'NICE264',
  // 'content.metadata': {
  //   custom_info: 'info'
  // },
  // 'ad.metadata': {
  //   custom_info: 'info'
  // },
  // 'extraparam.1': 'myExtraParam1',
  // 'extraparam.2': 'myExtraParam2'
};

const App = () => {
  const [_youboraConnector, initYoubora] = useYoubora(youboraOptions, youbora.Log.Level.DEBUG);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize Youbora connector
    initYoubora(player);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

### Configuration on iOS

As outlined on the native iOS connector's [git repository](https://bitbucket.org/npaw/theoplayer-adapter-ios), the app's Podfile still needs to include a dependency to the THEOplayerSDK by adding a pre-install script:

```ruby
  pre_install do |installer|
    ios_youbora_target = installer.pod_targets.find { |t| t.name == "YouboraTHEOPlayerAdapter-iOS" }
    ios_theoplayer_target = installer.pod_targets.find { |t| t.name == "THEOplayerSDK-core-iOS"}
    puts "Adding THEOplayerSDK-core-iOS as a target dependency to YouboraTHEOPlayerAdapter-iOS"
    ios_youbora_target.dependent_targets <<= ios_theoplayer_target
    tvos_youbora_target = installer.pod_targets.find { |t| t.name == "YouboraTHEOPlayerAdapter-tvOS"}
    tvos_theoplayer_target = installer.pod_targets.find { |t| t.name == "THEOplayerSDK-core-tvOS"}
    puts "Adding THEOplayerSDK-core-tvOS as a target dependency to YouboraTHEOPlayerAdapter-tvOS"
    tvos_youbora_target.dependent_targets <<= tvos_theoplayer_target
  end
```

If you are using a single target project this reduces to

```ruby
  pre_install do |installer|
    youbora_target = installer.pod_targets.find { |t| t.name == "YouboraTHEOPlayerAdapter" }
    theoplayer_target = installer.pod_targets.find { |t| t.name == "THEOplayerSDK-core"}
    puts "Adding THEOplayerSDK-core as a target dependency to YouboraTHEOPlayerAdapter"
    youbora_target.dependent_targets <<= theoplayer_target
  end
```

---

# @theoplayer/react-native-analytics-youbora

## 1.8.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.8.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.7.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.6.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/youbora/LICENSE) file for more information.

## 1.5.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.4.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.4.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.3.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.2.4

### 🐛 Issues

* Fixed an issue on iOS where the podspec files did not contain all references when not using the New Architecture.

## 1.2.3

### 🐛 Issues

* Fixed an issue on iOS where the project would not build when used in a project that has New Architecture enabled.

## 1.2.2

### 🐛 Issues

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors
* Added THEOplayer 8.x to peerDependency setup

## 1.2.1

### 🐛 Issues

* Deleted dependency on the removed ad module for Android.

## 1.2.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

### ✨ Features

* Simplified pre-install step in podFile to setup THEOplayer dependency for iOS/tvOS.
* Updated setup documentation.

## 1.1.1

### 📦 Dependency Updates

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.1.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.0.0

### ✨ Features

* Initial release

---

# OptiView Player Flutter SDK

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Dolby OptiView Player is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀 Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/flutter/getting-started.md)

[Set up your first OptiView Player in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/flutter/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/flutter.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/flutter.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/changelog.md)

[Find out what's new in the OptiView Player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/changelog.md)

## [![](/pr-932/img/github.svg)![](/pr-932/img/github_dark.svg)GitHub](https://github.com/THEOplayer/flutter-theoplayer-sdk)

[Browse the source code or report issues on GitHub.](https://github.com/THEOplayer/flutter-theoplayer-sdk)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

![](https://raw.githubusercontent.com/THEOplayer/flutter-theoplayer-sdk/main/doc/theoplayer_flutter_sdk_logo.png)

# THEOplayer Flutter SDK

## Table of Contents

1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [How to use these guides](#how-to-use-these-guides)
4. [Features](#features)
5. [Getting Started](#getting-started)
6. [Contributing](#contributing)

## Overview

The `theoplayer` package provides a `THEOplayer` component supporting video playback on the following platforms:

* Android, Android TV & FireTV
* iOS
* HTML5 (web, mobile web)
* **OUT OF SCOPE**: Tizen and WebOS (smart TVs, set-top boxes and gaming consoles).

This document covers the creation of a minimal app including a `THEOplayer` component, and an overview of the accompanying example app.

It also gives a description of the properties of the `THEOplayer` component, and a list of features and known limitations.

## Prerequisites

For each platform, a dependency to the corresponding THEOplayer SDK is included through a dependency manager:

* Gradle & Maven for Android
* Cocoapods for iOS
* npm for Web \*

\**the initial version of the SDK relies on a local copy of `THEOplayer.chromeless.js` (and additional modules), so adding it manually is required!*

In order to use one of these THEOplayer SDKs, it is necessary to obtain a valid THEOplayer license for that specific platform, i.e. HTML5, Android, and/or iOS. You can sign up for a THEOplayer SDK license through [our portal](https://portal.theoplayer.com/).

If you have no previous experience in Flutter, we encourage you to first explore the [Flutter Documentation](https://docs.flutter.dev/), as it gives you a good start on one of the most popular app development frameworks.

## How to use these guides

These are guides on how to use the THEOplayer Flutter SDK in your Flutter project(s) and can be used linearly or by searching the specific section. It is recommended that you have a basic understanding of how Flutter works to speed up the way of working with THEOplayer Flutter SDK.

## Features

Depending on the platform on which the application is deployed, a different set of features can be available.

If a feature is missing, additional help is needed, or you need to extend the package, please reach out to us for support.

| Feature                                                                                                            | Android, Android TV, Fire TV                                                                                                                                                                                          | Web                                             | iOS, tvOS                                                     |
| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------- |
| **Streaming**                                                                                                      | MPEG-DASH (fmp4, CMAF), HLS (TS, CMAF), Progressive MP4, MP3                                                                                                                                                          |                                                 | HLS (TS, CMAF), Progressive MP4, MP3                          |
| **Content Protection**                                                                                             | Widevine                                                                                                                                                                                                              | Widevine, Fairplay                              | Fairplay                                                      |
| **DRM Connectors**                                                                                                 | Through hooking into native implementation… check guides!                                                                                                                                                             |                                                 |                                                               |
| **Subtitles & Closed Captions**                                                                                    | In-stream subtitles supported by the platform.<br />Note: If you use Texture-based rendering (SURFACE\_TEXTURE and SURFACE\_PRODUCER) on Android, you need to implement the subtitle rendering based on track events. |                                                 |                                                               |
| **Metadata**                                                                                                       | Event stream, emsg, ID3, EXT-X-DATERANGE                                                                                                                                                                              |                                                 |                                                               |
| **Fullscreen**                                                                                                     | Supported through `player.presentationMode` API                                                                                                                                                                       |                                                 |                                                               |
| **[Picture-in-Picture](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/picture-in-picture.md)** | Supported through `player.allowAutomaticPictureInPicture` API                                                                                                                                                         | Supported through `player.presentationMode` API | Supported through `player.allowAutomaticPictureInPicture` API |
| **Advertising Integration**                                                                                        | Coming soon… (Can not wait? [Check our in-app integration branches](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/custom-branches.md))                                                           |                                                 |                                                               |
| **Analytics Connectors**                                                                                           | Coming soon…                                                                                                                                                                                                          |                                                 |                                                               |
| **Cast Integration**                                                                                               | Coming soon… (Can not wait? [Check our in-app integration branches](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/custom-branches.md))                                                           |                                                 |                                                               |
| **[THEOlive](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/theolive.md)**                     | Supported through `THEOliveSource` and `player.theolive` API                                                                                                                                                          |                                                 |                                                               |
| **[Adaptive Bitrate (ABR)](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/abr.md)**            | Supported through `player.abr` API                                                                                                                                                                                    |                                                 |                                                               |

## Getting Started

This section starts with creating a minimal demo app that integrates the `theoplayer` package, followed by an overview of the available properties and functionality of the THEOplayer component. A minimal example application including a basic user interface and demo sources is included in [this repository](https://github.com/THEOplayer/flutter-theoplayer-sdk/tree/main/flutter_theoplayer_sdk/flutter_theoplayer_sdk/example), and discussed in the next section. Finally, an overview of features, limitations and known issues is listed.

* [Creating a minimal demo app](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/creating-minimal-app.md)

  * [Getting started on Android](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/creating-minimal-app.md#getting-started-on-android)
  * [Getting started on iOS](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/creating-minimal-app.md#getting-started-on-ios)
  * [Getting started on Web](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/creating-minimal-app.md#getting-started-on-web)

* [The THEOplayer component](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/theoplayer-component.md)

* Knowledge Base

  * [Using custom DRM connectors](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/custom_drm.md)
  * [Limitations and known issues](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/limitations.md)
  * [Picture-in-picture](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/picture-in-picture.md)
  * [Adaptive Bitrate (ABR)](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/abr.md)
  * [HLS date ranges (EXT-X-DATERANGE)](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/daterange.md)
  * [Debug Flags](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/debug-flags.md)
  * [Custom branches](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/custom-branches.md): custom forks to expose native functionality

## Contributing

All contributions are welcomed!

Please read our [Contribution guide](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/CONTRIBUTING.md) on how to get started!

---

# Changelog

## 11.12.0

* Updated THEOplayer to 11.12.0.

* Added source-level live latency configuration through `TypedSource.latencyConfiguration` (`SourceLatencyConfiguration`), including OptiView Live (THEOlive) sources.

  * iOS: only `targetOffset` is supported, the other offsets and the playback-rate bounds are ignored.

* Added `TypedSource.lowLatency` to enable the player's low-latency mode, required for Low-Latency CMAF with ABR.

  * Supported only on Web.

## 11.10.2

* Updated THEOplayer to 11.10.2.

## 11.10.0

* Updated THEOplayer to 11.10.0.
* Added support for HLS `EXT-X-DATERANGE` tags: a new `hlsDateRange` flag on `THEOplayerConfig` and `TypedSource` (source-level overrides player-level), exposing the parsed date ranges as `DateRangeCue`s on the TextTracks API.
* Forwarded native daterange cue updates to Flutter: `DateRangeCue` fields are now refreshed and a `CueUpdateEvent` is dispatched when a daterange cue updates.

## 11.1.0

* Updated THEOplayer to 11.1.0.

* **BREAKING CHANGE**:

  * iOS: the minimum supported iOS version is now 15.0, dropping support for iOS 13 and 14:
  * iOS: the native THEOplayer SDK and its integrations are built with Xcode 26 instead of Xcode 16, so building an app that uses this SDK requires **Xcode 26 or later** (CI is validated on `macos-15` with Xcode 26.3 and an iOS 18.5+ simulator).
  * **Removed**: OptiView Live preloading API on all platforms, following its removal from the native SDKs (`preloadChannels` on Android and iOS, `preloadPublications` on web). Remove these calls, streams are loaded when the source is set on the player

For native SDK changes please consult with the [THEOplayer SDK 11.0.0 changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-1100-20260416) and the [THEOplayer SDK 11.1.0 changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-1110-20260428).

## 10.12.4

* Added an `authToken` property to the THEOlive API (`player.theoLive.authToken`) to authenticate OptiView Live (THEOlive) streams.

## 10.12.3

* Updated THEOplayer to 10.12.3.

## 10.12.2

* Fixed an issue when playing OptiView Live streams (THEOlive) the player did not jump to the live point after a fallback.

## 10.12.1

* Updated THEOplayer to 10.12.1.
  * For underlying native SDK changes please consult with the [THEOplayer SDK 10.12.1 changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-10121-20260317)).

## 10.12.0

* Updated THEOplayer to 10.12.0.
* Added `AbrStrategyConfiguration` API to configure initial ABR selection on `player.abr`.
* Added `DebugFlags` API to help debugging underlying native SDK issues via `player.debugFlags` and `player.showDebugPanel(context)`

## 10.6.1

* Updated THEOplayer to 10.6.1.
  * iOS: minimum required XCode version is 16.2 [from THEOplayer iOS SDK 10.x](https://optiview.dolby.com/docs/theoplayer/changelog/#-breaking-changes-3)
* Android: Fixed an issue where calling `player.dispose()` did not destroy the native player completely.

## 10.3.0

* Updated THEOplayer to 10.3.0.

## 10.0.0

* Updated THEOplayer to 10.0.0.

  * For underlying native SDK changes please consult with the [THEOplayer SDK 10.0.0 changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-1000-20250912)).
  * Android: Updated Kotlin version to 2.2.10 (to match with THEOplayer Android SDK).
  * Android: Updated Gradle version to 8.13.0.
  * Android: Update minSdkVersion to 23.
  * Android: Update compileSdkVersion to 36.

* Added **experimental** WASM compilation support for web builds.

* **BREAKING CHANGE**: Renamed all "publication"-related APIs to "distribution" for consistency with THEOplayer native SDKs:

  * **State Management**: `PublicationState` → `DistributionState`, `publicationState` → `distributionState`
  * **Event Types**: `PUBLICATIONLOADSTART` → `DISTRIBUTIONLOADSTART`, `PUBLICATIONLOADED` → `ENDPOINTLOADED`, `PUBLICATIONOFFLINE` → `DISTRIBUTIONOFFLINE`
  * **Event Classes**: `PublicationLoadStartEvent` → `DistributionLoadStartEvent`, `PublicationLoadedEvent` → removed (replaced by `EndpointLoadedEvent`), `PublicationOfflineEvent` → `DistributionOfflineEvent`
  * **Event Parameters**: `event.publicationId` → `event.distributionId` in distribution events

* **BREAKING CHANGE**: Removed Android PlaybackPipeline configuration support:

  * **Removed**: `PlaybackPipeline` enum (`media3`, `legacy` options)
  * **Removed**: `AndroidTypedSourceConfiguration.playbackPipeline` parameter
  * **Default**: Media3 is now the only supported playback pipeline (legacy pipeline removed)

### Migration Notes

This release contains significant breaking changes that require code updates:

1. **THEOlive API Renaming**: All publication-related APIs have been renamed to distribution equivalents
2. **Android Configuration Simplification**: PlaybackPipeline configuration is no longer needed (Media3 is default)
3. **Event Parameter Changes**: Event handlers need to use `distributionId` instead of `publicationId`
4. **Class Name Updates**: Some event classes have been renamed for consistency

**Migration Required**: Existing code using THEOlive APIs will need updates to compile and function correctly.

For detailed migration instructions, automated find/replace patterns, and complete examples, see the [Migration Guide](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/migrations/migration_from_9.x_to_10.x.md).

## 9.11.0

* Updated THEOplayer to 9.11.0.

## 9.7.1

* Added `TypedSource.type` property.
* Added `WebConfig.libraryLocation` to specify a different path for THEOplayer WEB SDK through `THEOplayerConfig`.

## 9.7.0

* Updated THEOplayer to 9.7.0.
* Added `TheoLiveConfiguration.discoveryUrl` to support custom discovery URLs for OptiView live streams (formerly known as THEOlive).

## 9.3.1

* Updated THEOplayer to 9.3.1.

## 9.3.0

* Updated THEOplayer to 9.3.0.
  * Fixed an issue where `THEOplayer.allowAutomaticPictureInPicture` was not respected after setting a source.

## 9.2.0

* Updated THEOplayer to 9.2.0.
* Added `TypedSource.headers` to set custom headers for requests (Applied on master playlist, media playlist and segment requests).
  * Supported only on Android (PlaybackPipeline.MEDIA3) and iOS.
* Fixed an issue where calling `player.dispose()` would not release resources properly on iOS.

## 9.0.0

* Updated THEOplayer to 9.0.0.

* Added `TypedSource.androidSourceConfiguration` to change playback pipelines on Android (legacy/media3)

* **BREAKING CHANGE**: Changed default media playback pipeline on Android

  * Starting from THEOplayer 9.0, the new Media3 Playback pipeline is now the default for all [Android SDK playback](https://www.theoplayer.com/docs/theoplayer/changelog/#-900-20250403).
  * The legacy playback pipeline from version 8.x is still available, and can be activated by setting `TypedSource.androidSourceConfiguration.playbackPipeline` to `PlaybackPipeline.LEGACY`.
  * The legacy playback pipeline is scheduled to be removed in version 10.

* Known issues:

  * Combining `AndroidViewComposition.SURFACE_PRODUCER` or `AndroidViewComposition.SURFACE_TEXTURE` with the new default pipeline doesn't play DRM (content protected) sources.
  * As a workaround please use `PlaybackPipeline.LEGACY` with these rendering engines, or `AndroidViewComposition.HYBRID_COMPOSITION` with `PlaybackPipeline.MEDIA3`.

## 8.14.0

* Updated THEOplayer to 8.14.0.

## 8.13.2

* Updated THEOplayer to 8.13.2.
* Added [THEOlive support](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/theolive.md) for Android and iOS.
* Added `THEOplayer.isWaiting` state.
* Added experimental `THEOplayer.addAllEventListener(...)` to listen on all player events at once.

## 8.11.0

* Updated THEOplayer to 8.11.0.
* Added support for Flutter 3.29.0.

## 8.4.0

* Updated THEOplayer to 8.4.0.

## 8.3.0

* Updated THEOplayer to 8.3.0.
* Added [THEOlive support](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/theolive.md) for Flutter WEB.
* Deprecated getX and setX methods on THEOplayer API in favor of properties.
* Added new properties on THEOplayer API. (`muted`, `played`, `buffered`, `videoTracks`, etc... for the full list check the API.)
* **BREAKING CHANGE**: Changed `THEOplayer.allowBackgroundPlayback()` to `THEOplayer.allowBackgroundPlayback`.
* **BREAKING CHANGE**: Changed `THEOplayer.allowAutomaticPictureInPicture()` to `THEOplayer.allowAutomaticPictureInPicture`.
* **BREAKING CHANGE**: Changed `THEOplayer.isEnded()` to `THEOplayer.isEnded`.
* **BREAKING CHANGE**: Changed `THEOplayer.isPlaying()` to `THEOplayer.isPlaying`.
* **BREAKING CHANGE**: Changed `THEOplayer.isSeeking()` to `THEOplayer.isSeeking`.

## 8.2.0

* Fixed an issue where play/pause buttons were not connected in the Picture-in-Picture window on Android.
* Updated THEOplayer to 8.2.0.
* Updated Kotlin version to 1.9.25 (to match with THEOplayer Android SDK)

## 8.0.0

* Updated THEOplayer to 8.0.0.
* Added Picture-in-Picture support with `THEOplayer.setPresentationMode(PresentationMode.PIP)` API for WEB and `THEOplayer.setAllowAutomaticPictureInPicture(bool)` for Android and iOS.
* Removed iOS 12 support. The minimum supported iOS version is now iOS 13.

## 7.12.0

* Updated THEOplayer to 7.12.0.

## 7.3.1

* Fixed an issue where playback failed with license error when using Texture-based (SURFACE\_TEXTURE, SURFACE\_PRODUCER) rendering.
* Fixed an issue where player lifecycle callbacks were triggered multiple times when using Texture-based (SURFACE\_TEXTURE, SURFACE\_PRODUCER) rendering.

## 7.3.0

* Updated THEOplayer to 7.3.0.

* Added `AndroidConfig.viewComposition` to support Texture-based rendering.

* Added `AndroidViewComposition.SURFACE_TEXTURE` to use SurfaceTexture on native Android (instead of PlatformViews).

* Added `AndroidViewComposition.SURFACE_PRODUCER` to use SurfaceProducer on native Android (instead of PlatformViews).

  * Only works from [Flutter 3.22.0](https://docs.flutter.dev/release/breaking-changes/android-surface-plugins#timeline)
  * Supports [Texture-based rendering with Impeller](https://docs.flutter.dev/release/breaking-changes/android-surface-plugins#summary) rendering engine

* Added Support for continuing playback when transitioning the app into background with `THEOplayer.setAllowBackgroundPlayback(boolean)`.

* Added Fullscreen support with `THEOplayer.setPresentationMode(PresentationMode)`.

* Deprecated `AndroidConfig.useHybridComposition` in favor of `AndroidConfig.viewComposition` (use `AndroidViewComposition.HYBRID_COMPOSITION` for the previous behaviour).

## 7.0.0

* Updated THEOplayer to 7.0.0.

### Versioning changes

We are updating the version numbering for THEOplayer Flutter SDK to more closely match the underlying native THEOplayer SDKs.

Here are the notable changes:

* The **major** version will be matching the underlying native SDK major version.
* The **minor** version will reflect new features added in THEOplayer Flutter SDK.
* The **patch** version will be increased when there is a need for a hotfix on top of the minor version bump.

> Note: Breaking changes in THEOplayer Flutter SDK will only occur while increasing the **major** version.

## 1.0.3

* Updated THEOplayer to 6.10.1.
* Added and coupled application lifecycle listener.

## 1.0.2

* Service release, no new features.

## 1.0.1

* Updated minimum Dart version to 3.3.0.
* Updated minimum Flutter version to 3.19.0.

## 1.0.0

* Initial release.

---

# How-to guides for OptiView Player Flutter SDK

Want to start implementing features to your SDK? Our how-to-guides will help you with all kind of integrations!

## [📄️Adaptive Bitrate (ABR)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/abr.md)

[Overview](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/abr.md)

## [📄️Creating a minimal demo app](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/creating-minimal-app.md)

[In this section we start from an empty Flutter project, include a dependency to fluttertheoplayersdk, and deploy it on an Android or iOS device.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/creating-minimal-app.md)

## [📄️Custom branches](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/custom-branches.md)

[THEOplayer Flutter SDK is built on top of the existing THEOplayer iOS, Android, and Web SDKs. However, not all native SDK features are available in Flutter from the start.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/custom-branches.md)

## [📄️Using a custom DRM integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/custom_drm.md)

[The initial version of the THEOplayer Flutter SDK only support generic Widevine and Fairplay DRM playback.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/custom_drm.md)

## [📄️HLS date ranges (EXT-X-DATERANGE)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/daterange.md)

[The native THEOplayer SDKs can parse EXT-X-DATERANGE tags from HLS playlists and expose them as DateRangeCues on a dedicated text track. This is available in the Flutter SDK on Android, iOS and Web.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/daterange.md)

## [📄️Debug Flags (Experimental)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/debug-flags.md)

[Overview](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/debug-flags.md)

## [📄️Limitations and Known Issues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/limitations.md)

[This sections lists any limitations and known issues in the current package version.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/limitations.md)

## [🗃migrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/migrations/migration_from_10.x_to_11.x.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/migrations/migration_from_10.x_to_11.x.md)

## [📄️Picture-in-Picture support](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/picture-in-picture.md)

[THEOplayer Flutter SDK supports native Picture-in-Picture on iOS, Android and Web platforms.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/picture-in-picture.md)

## [📄️THEOlive support](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/theolive.md)

[High-quality synchronized video streaming at scale for providers of large sports broadcasting, sports betting, and interactive entertainment](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/theolive.md)

## [📄️The THEOplayer component](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/theoplayer-component.md)

[Architecture](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/theoplayer-component.md)

## [📄️WASM support (experimental)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/wasm_support.md)

[When compiling the THEOplayer Flutter SDK for WEB, you can now specify WASM support.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/wasm_support.md)

## [🚀OptiView Live](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/flutter/theolive/getting-started.md)

[Integrate OptiView Live streaming into your Flutter app.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/flutter/theolive/getting-started.md)

---

# Adaptive Bitrate (ABR)

## Overview

The playback quality during play-out of a THEOlive stream is determined by the ABR algorithm. On starting play-out, the ABR **strategy** determines which quality to prefer, while during play-out the network's bandwidth is monitored to select an optimal quality.

More information on ABR can be found on the [THEOplayer website](https://www.theoplayer.com/blog/abr-bandwidth-usage) and [demo page](https://www.theoplayer.com/theoplayer-demo-optimized-video-abr).

## ABR Configuration

The ABR configuration is accessible through `player.abr`. It allows you to control the ABR strategy, target buffer, and preferred peak bitrate.

### Setting the ABR Strategy

The strategy determines which quality the player initially selects when starting playback:

| Strategy      | Description                                                                 |
| ------------- | --------------------------------------------------------------------------- |
| `performance` | Prefer the **lowest** quality for faster startup and lower bandwidth usage. |
| `quality`     | Prefer the **highest** quality for the best visual experience.              |
| `bandwidth`   | Estimate available bandwidth and select the best matching quality.          |

The default strategy is **bandwidth**.

```dart
// Set the ABR strategy to "quality" (prefer highest quality)
player.abr.setStrategy(
  AbrStrategyConfiguration(type: AbrStrategyType.quality),
);

// Set the ABR strategy to "performance" (prefer lowest quality)
player.abr.setStrategy(
  AbrStrategyConfiguration(type: AbrStrategyType.performance),
);

// Read the current strategy
final config = await player.abr.strategy;
print("Current ABR strategy: ${config.type}");
```

### Setting an Initial Bitrate Cap

You can pass optional `metadata` with a `bitrate` value (in bits per second) to cap the initial quality selection:

```dart
player.abr.setStrategy(
  AbrStrategyConfiguration(
    type: AbrStrategyType.bandwidth,
    metadata: AbrStrategyMetadata(bitrate: 1200000), // 1.2 Mbps
  ),
);
```

This is useful when you have an estimate of the user's available bandwidth and want to avoid buffering on startup.

### Target Buffer

The target buffer controls how many seconds of video the player should buffer ahead of the current playback position. This only applies to HLS (non-THEOlive) streams.

```dart
// Get the current target buffer (default: 20 seconds)
final buffer = await player.abr.targetBuffer;

// Set the target buffer to 10 seconds
player.abr.setTargetBuffer(10.0);
```

### Preferred Peak Bitrate (iOS only)

On iOS you can set the desired limit for network bandwidth consumption. This only applies to HLS (non-THEOlive) streams and is a no-op on other platforms.

```dart
// Cap bandwidth to 2 Mbps
player.abr.setPreferredPeakBitRate(2000000);

// Remove the cap (default: 0 = no limit)
player.abr.setPreferredPeakBitRate(0);
```

## Setting Target Video Quality

By default, the ABR algorithm will choose from all the video qualities available in the stream. You can pin the player to a specific quality or a subset of qualities using the `targetQuality` / `targetQualities` properties on a video track:

```dart
final videoTrack = player.videoTracks.first;

// Pin to a single quality (disables ABR)
videoTrack.targetQuality = videoTrack.qualities.first;

// Pin to a subset of qualities (ABR selects among these)
videoTrack.targetQualities = [
  videoTrack.qualities[0],
  videoTrack.qualities[1],
];

// Reset to automatic (let ABR choose freely)
videoTrack.targetQuality = null;
```

## Subscribing to Quality Change Events

You can listen for quality changes on video and audio tracks:

```dart
// Listen for new video tracks
player.videoTracks.addEventListener(VideoTracksEventTypes.ADDTRACK, (event) {
  final track = (event as AddVideoTrackEvent).track;
  print("Video track added: ${track.uid}");

  // Print all available qualities
  for (final quality in track.qualities) {
    print("  quality: ${quality.width}x${quality.height}, "
        "bandwidth: ${quality.bandwidth}");
  }

  // Listen for active quality changes on this track
  track.addEventListener(
    VideoTrackEventTypes.ACTIVEQUALITYCHANGED,
    (event) {
      final q = (event as VideoActiveQualityChangedEvent).quality;
      print("Active quality changed: ${q.width}x${q.height}, "
          "bandwidth: ${q.bandwidth}");
    },
  );
});
```

## Supported Platforms

| Property               | Android | iOS | Web |
| ---------------------- | ------- | --- | --- |
| `strategy`             | ✅      | ✅  | ✅  |
| `targetBuffer`         | ✅      | ✅  | ✅  |
| `preferredPeakBitRate` | ❌      | ✅  | ❌  |
| `targetQuality`        | ✅      | ✅  | ✅  |
| Quality change events  | ✅      | ✅  | ✅  |

**Notes**: On **iOS**, the ABR strategy configuration only affects **THEOlive** (HESP) streams. For other stream types, the player uses the platform-native ABR algorithm that cannot be configured through this API.

On **Android** and **Web**, the ABR strategy is applied to all adaptive streams.

---

# Creating a minimal demo app

In this section we start from an empty Flutter project, include a dependency to `flutter_theoplayer_sdk`, and deploy it on an Android or iOS device.

## Table of Contents

* [Setting up a new project](#setting-up-a-new-project)
* [Getting started on Android](#getting-started-on-android)
* [Getting started on iOS](#getting-started-on-ios)
* [Getting started on Web](#getting-started-on-web)

## Setting up a new project

### Getting a new project ready

After [setting up your Flutter development environment](https://docs.flutter.dev/get-started/install) you can run the following command to create a new project from Terminal. (You can use Android Studio too)

```bash
$ flutter create -a kotlin -i swift -t app --org com.theoplayer --description "New THEOplayer project" --project-name "flutter_theoplayer_sample_app" --platform web,ios,android flutter_theoplayer_sample_app
```

This will generate a basic project as a starting point for Android, iOS and Web development.

```text
Signing iOS app for device deployment using developer identity: "Apple Development: XXXXXXXXXXX"
Creating project flutter_theoplayer_sample_app...
Resolving dependencies in flutter_theoplayer_sample_app... 
Got dependencies in flutter_theoplayer_sample_app.
Wrote 81 files.

All done!
You can find general documentation for Flutter at: https://docs.flutter.dev/
Detailed API documentation is available at: https://api.flutter.dev/
If you prefer video documentation, consider: https://www.youtube.com/c/flutterdev

In order to run your application, type:

  $ cd flutter_theoplayer_sample_app
  $ flutter run

Your application code is in flutter_theoplayer_sample_app/lib/main.dart.
```

Following the guidance from the script you can have your basic app running:

```bash
$ cd flutter_theoplayer_sample_app
$ flutter run
```

### Adding THEOplayer Flutter SDK

#### Option 1: Adding THEOplayer Flutter SDK as dependency (Recommended)

To add THEOplayer Flutter SDK as a dependency, you can simply fetch it from [pub.dev](https://pub.dev) using:

```bash
$ flutter pub add theoplayer
```

##### Option 1/b (optional) Referencing a custom branch from the official THEOplayer Flutter SDK repository

In certain scenarios (e.g. you would like to test an un-released feature), you can reference any commit/branch/tag from the [THEOplayer Flutter SDK repository](https://github.com/THEOplayer/flutter-theoplayer-sdk).

In your `package.yaml` file you need to change the way you reference the `theoplayer` package with Dart's `dependency_override` feature:

From:

```yaml
dependencies:
  flutter:
    sdk: flutter

  theoplayer: ^8.11.0
```

To:

```yaml
dependencies:
  flutter:
    sdk: flutter

  theoplayer: ^8.11.0

dependency_overrides:
  theoplayer:
    git:
      url: https://github.com/THEOplayer/flutter-theoplayer-sdk.git
      ref: feature/NEW_UNRELEASED_FEATURE
      path: flutter_theoplayer_sdk/flutter_theoplayer_sdk

  theoplayer_ios:
    git:
      url: https://github.com/THEOplayer/flutter-theoplayer-sdk.git
      ref: feature/NEW_UNRELEASED_FEATURE
      path: flutter_theoplayer_sdk/flutter_theoplayer_sdk_ios

  theoplayer_android:
    git:
      url: https://github.com/THEOplayer/flutter-theoplayer-sdk.git
      ref: feature/NEW_UNRELEASED_FEATURE
      path: flutter_theoplayer_sdk/flutter_theoplayer_sdk_android

  theoplayer_platform_interface:
    git:
      url: https://github.com/THEOplayer/flutter-theoplayer-sdk.git
      ref: feature/NEW_UNRELEASED_FEATURE
      path: flutter_theoplayer_sdk/flutter_theoplayer_sdk_platform_interface
```

As you can see, removing `theoplayer: ^8.11.0` is not necessary as `dependency_override` takes precedence over standard `dependencies`.

You can even move this new piece into a separate `dependency_overrides.yaml` file too, if you wish. (and you can use it during development and not commit the file into the repository)

Dependency override makes sure that `theoplayer` and its dependencies `theoplayer_ios`, `theoplayer_android`, and `theoplayer_platform_interface` are pulled from the correct branch.

After running `pub get` you will see that the overrides are in place:

```bash
...
! theoplayer 8.11.0 from git https://github.com/THEOplayer/flutter-theoplayer-sdk.git at d292cf in flutter_theoplayer_sdk/flutter_theoplayer_sdk (overridden)
! theoplayer_android 8.11.0 from git https://github.com/THEOplayer/flutter-theoplayer-sdk.git at d292cf in flutter_theoplayer_sdk/flutter_theoplayer_sdk_android (overridden)
! theoplayer_ios 8.11.0 from git https://github.com/THEOplayer/flutter-theoplayer-sdk.git at d292cf in flutter_theoplayer_sdk/flutter_theoplayer_sdk_ios (overridden)
! theoplayer_platform_interface 8.11.0 from git https://github.com/THEOplayer/flutter-theoplayer-sdk.git at d292cf in flutter_theoplayer_sdk/flutter_theoplayer_sdk_platform_interface (overridden)
  vm_service 14.3.0 (15.0.0 available)
  web 1.1.0 (1.1.1 available)
...
```

#### Option 2: Adding THEOplayer Flutter SDK as submodule

As an alternative, you can add the SDK as a submodule in your git project. This can be useful if you are trying to fork the project to [contribute](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/CONTRIBUTING.md) with us.

```bash
$ git submodule add https://GITHUB_USERNAME:GITHUB_PASSWORD@github.com/THEOplayer/flutter-theoplayer-sdk flutter-theoplayer-sdk
```

Then, your project structure will look like this:

```bash
➜  flutter_theoplayer_sample_app git:(master) ✗ ls
README.md                         flutter-theoplayer-sdk            pubspec.lock
analysis_options.yaml             flutter_theoplayer_sample_app.iml pubspec.yaml
android                           ios                               test
build                             lib                               web
```

After the submodule added, you can add the THEOplayer Flutter SDK as a dependency in your project's `pubspec.yaml` file manually, or just by running this command:

```bash
$ flutter pub add 'theoplayer:{"path":"./flutter-theoplayer-sdk/flutter_theoplayer_sdk/flutter_theoplayer_sdk"}' --directory .
```

You should get an output like this after executing the command, meaning `flutter` found and added the SDK as a dependency, and fetched the necessary packages too.

```diff
Resolving dependencies... 
  collection 1.17.2 (1.18.0 available)
  flutter_lints 2.0.3 (3.0.1 available)
+ theoplayer_sdk_android 1.0.0 from path ../flutter-theoplayer-sdk/flutter_theoplayer_sdk/flutter_theoplayer_sdk_android
+ theoplayer_sdk_ios 1.0.0 from path ../flutter-theoplayer-sdk/flutter_theoplayer_sdk/flutter_theoplayer_sdk_ios
+ theoplayer_sdk_platform_interface 1.0.0 from path ../flutter-theoplayer-sdk/flutter_theoplayer_sdk/flutter_theoplayer_sdk_platform_interface
+ theoplayer_sdk_web 1.0.0 from path ../flutter-theoplayer-sdk/flutter_theoplayer_sdk/flutter_theoplayer_sdk_web
+ flutter_web_plugins 0.0.0 from sdk flutter
+ js 0.6.7
  lints 2.1.1 (3.0.0 available)
  material_color_utilities 0.5.0 (0.8.0 available)
  meta 1.9.1 (1.11.0 available)
+ plugin_platform_interface 2.1.6
  stack_trace 1.11.0 (1.11.1 available)
  stream_channel 2.1.1 (2.1.2 available)
  test_api 0.6.0 (0.6.1 available)
+ theoplayer 1.0.0 from path ../flutter-theoplayer-sdk/flutter_theoplayer_sdk/flutter_theoplayer_sdk
  web 0.1.4-beta (0.4.0 available)
Changed 8 dependencies!
```

To make sure the submodule references the platform-specific SDKs from within the repository run `melos bootstrap`.

If your main project doesn't pick up the changes, it is possible you need to configure `melos` to include your project too.

You can do it in 2 ways.

1. Create your `melos.yaml` file in your root project and configure it according to your setup (including the `theopalyer` submodule and its packages).
2. Or, modifiy the `flutter-theoplayer-sdk/melos.yaml` to include your project by adding `../` into the `packages` section of the melos file.

Don't forget to run `melos bootstrap` again in the directory according to your choice from above.

### Adding THEOplayer to your view hierarchy

1. Initialize THEOplayer (e.g. in your StatefulWidget)

```dart
  late THEOplayer player;

  @override
  void initState() {
    super.initState();

    player = THEOplayer(
        theoPlayerConfig: THEOplayerConfig(
          license: "YOUR_LICENSE_STRING",
        ),
        onCreate: () {
          print("THEOplayer is created and ready to use");
        });
  }
```

Keep in mind, you need to have a valid license from [THEOportal](https://portal.theoplayer.com).

Without a license you can only play sources hosted on `theoplayer.com` domain. (If you want to try this, just delete the `license` String from the `THEOplayerConfig`)

2. Adding THEOplayer to the view hierarchy

```dart
SizedBox(
    height: 300,
    // player.getView() is now deprecated. Use 'view' like below
    child: player.view,
),
```

3. Setting a source and start playback on a button press:

```dart
FilledButton(
    onPressed: () {
      // player.setSource() is now deprecated. Use 'source' like below
        player.source = SourceDescription(sources: [
            TypedSource(src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"),
        ]);
        player.play();
    },
    child: const Text("Play BBB source"),
),
```

***

You are (almost) ready to play with THEOplayer 😉

Is there anything else to configure on the specific platforms?

Check it below ⬇️

## Getting started on Android

The generated sample project doesn't have Internet permission by default (only in debug/profile mode).

By declaring the `INTERNET` the `AndroidManifest.xml`, your app can reach the Internet.

```xml
<uses-permission android:name="android.permission.INTERNET"/>
```

As noted in the [limitations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/limitations.md), THEOplayer on Android supports Android 5 (API level 21) and above, so defining this in the `android/app/build.gradle` is necessary:

```java
defaultConfig {
    // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html).
    applicationId "com.theoplayer.theoplayer_example"
    // You can update the following values to match your application needs.
    // For more information, see: https://docs.flutter.dev/deployment/android#reviewing-the-gradle-build-configuration.
    minSdkVersion 21
    targetSdkVersion flutter.targetSdkVersion
    versionCode flutterVersionCode.toInteger()
    versionName flutterVersionName
}
```

By using the `flutter run android` command, you can try out your application on an Android device.

## Getting started on iOS

No changes are required.

By using the `flutter run ios` command, you can try out your applicaiton on an iOS device.

## Getting started on Web

You need to acquire THEOplayer HTML5 SDK from [THEOportal](https://portal.theoplayer.com/) (or from an NPM package, e.g. from [6.9.0](https://registry.npmjs.org/theoplayer/-/theoplayer-6.9.0.tgz)).

**The current iteration of the THEOplayer Flutter SDK is not able to automatically pull THEOplayer HTML5 SDK from NPM, so this is now a manual procedure.**

If you have all the files at your hand (`THEOplayer.chromeless.js`, `common` and `transmux` files) copy them into the root of your Web project. (Next to the `index.html`, which is the entry point of your Flutter Web application)

Load the `THEOplayer.chromeless.js` Javascript in the `<HEAD>` of your `index.html` page:

```html
<!-- This script adds the flutter initialization JS code, don't change it -->
<script src="flutter.js" defer></script>

<!-- Loading THEOplayer -->
<script src="THEOplayer.chromeless.js" type="application/javascript"></script>
```

After these steps, you are good to go.

By using the `flutter run chrome` command, you can try out your application in the Chrome browser.

### Custom path for THEOplayer WEB SDK

You can also place the THEOplayer WEB SDK files on a custom path. (not in the root).

For that you will need some extra steps:

1. Place the files in the desired directory within your Flutter Web project. (e.g. `web/theoplayer_lib/`)
2. Reference THEOplayer in the `index.html` from that path:

```html
<!-- Loading THEOplayer -->
<script src="theoplayer_lib/THEOplayer.chromeless.js" type="application/javascript"></script>
```

3. Setup THEOplayer in Flutter with the custom library location through `THEOplayerConfig.webConfiguration`:

```dart
    player = THEOplayer(
      theoPlayerConfig: THEOplayerConfig(
        license: PLAYER_LICENSE,
        webConfiguration: WebConfig(libraryLocation: "/theoplayer_lib")
      ),
      onCreate: () {
        print("THEOplayer - loaded");
      }
    );
```

---

# Custom branches

THEOplayer Flutter SDK is built on top of the existing THEOplayer iOS, Android, and Web SDKs. However, not all native SDK features are available in Flutter from the start.

These features will be gradually introduced to the Flutter SDK based on thoughtful prioritization.

We understand that sometimes you may need these features before they are fully implemented on the Flutter side and require a working solution as soon as possible.

To address this need, we introduced custom branches prefixed with `poc/`, showcasing sample implementations of existing native features in a custom Flutter SDK fork. These versions are stable enough to start experimenting with and making necessary modifications if needed.

(Please note that these branches may not always be up-to-date with the latest releases.)

These versions also serve as a starting point for custom integration needs. By examining the source code and reviewing changes commit by commit, you can gain a basic understanding of how to expose additional native THEOplayer APIs to Flutter, especially if you are already familiar with the underlying SDKs.

## Available custom branches

| Branch                              | Description                                              |
| ----------------------------------- | -------------------------------------------------------- |
| `poc/in-sdk-chromecast-support-7.x` | Exposing Chromecast capabilities on Android, iOS and Web |
| `poc/in-sdk-google-ima-support-7.x` | Exposing Google IMA capabilities on Android and iOS      |

## How to make and use your own custom fork?

1. Create a fork of the THEOplayer Flutter SDK repo on [GitHub](https://github.com/THEOplayer/flutter-theoplayer-sdk/).
2. Configure your project to use your forked custom [THEOplayer SDK as a submodule](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/creating-minimal-app.md#option-2-adding-theoplayer-flutter-sdk-as-submodule) in your project.
3. Import THEOplayer and start using it in your application.

---

# Using a custom DRM integration

The initial version of the THEOplayer Flutter SDK only support generic Widevine and Fairplay DRM playback.

In a later release the Flutter SDK will also add functionality to utilize the well-known [THEOplayer Custom DRM Integration](https://github.com/THEOplayer/samples-drm-integration/tree/master) on the Flutter/Dart level.

The good news is that **the underlying platforms already support this functionality, so if you need to play a custom DRM stream, you can leverage this knowledge, and you can implement a *(temporary)* hybrid solution**.

## Configuration in Flutter

The current Flutter API is already taking into account the future custom extension of the DRM configurations. It already contains a `customIntegrationID` and an `integrationParameters` property to pass custom data:

```dart
SourceDescription(sources: [
    TypedSource(
        src: "https://fps.ezdrm.com/demo/video/ezdrm.m3u8",
        drm: DRMConfiguration(
            customIntegrationId: "YourCustomDRMIntegrationID",
            integrationParameters: {
                "custom_key": "custom_value",
            },
            fairplay: FairPlayDRMConfiguration(
                licenseAcquisitionURL: "https://yourlicenseurl.com",
                certificateURL: "https://yourcertificateurl.com",
                headers: null,
            ),
            widevine: WidevineDRMConfiguration(
                licenseAcquisitionURL: "https://yourlicenseurl.com",
            ),
        )),
    ])
)
```

By specifying these values the underlying platform knows it has to use a custom DRM logic. Somehow we just have to make sure that the custom DRM logic is available on the native side.

## Registering a custom DRM connector on Android

You can rely on any existing native Java/Kotlin implementation you have already, or take one from our [samples repository](https://github.com/THEOplayer/samples-drm-integration/tree/master).

After you copied over the code into your Android application project (`projectRoot/android/app/src/main`), you can hook it up when the application gets initialized.

For example, you can use the `MainActivity` class as a starting point (if you don't have any other platform-specific code).

```kotlin
import com.theoplayer.android.api.THEOplayerGlobal
import com.theoplayer.android.api.contentprotection.KeySystemId
import io.flutter.embedding.android.FlutterActivity

class MainActivity: FlutterActivity() {
    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        THEOplayerGlobal.getSharedInstance(context).registerContentProtectionIntegration(
            "YourCustomDRMIntegrationID",
            KeySystemId.WIDEVINE,
            YourCustomWidevineContentProtectionIntegrationFactory()
        )
    }
}
```

By using the exact same `customIntegrationId` on the native side, the underlying THEOplayer will know what to do when it sees a source with the same custom DRM ID.

## Registering a custom DRM connector on iOS

You can rely on any existing native Swift/ObjC implementation you have already, or take one from our [samples repository](https://github.com/THEOplayer/samples-drm-integration/tree/master).

After you copied over the code into your Android application project (`projectRoot/ios/Runner`), you can hook it up when the application gets initialized.

For example, you can use the `AppDelegate` class as a starting point (if you don't have any other platform-specific code).

```swift
import UIKit
import Flutter
import THEOplayerSDK

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    
    THEOplayer.registerContentProtectionIntegration(integrationId: "YourCustomDRMIntegrationID" , keySystem: .FAIRPLAY, integrationFactory: YourCustomFairplayContentProtectionIntegrationFactory())
      
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}
```

By using the exact same `customIntegrationId` on the native side, the underlying THEOplayer will know what to do when it sees a source with the same custom DRM ID.

## Registering a custom DRM connector on Web

You can rely on any existing native Javascript/Typescript implementation you have already, or take one from our [samples repository](https://github.com/THEOplayer/samples-drm-integration/tree/master).

After you copied over the code into your Android application project (`projectRoot/web/`), you can hook it up when the application gets initialized.

For example, you can use the `index.html` class as a starting point (if you don't have any other platform-specific code).

```html
<head>
  <!-- ... -->
  <script src="THEOplayer.chromeless.js" type="application/javascript"></script>
  <!-- after THEOplayer is loaded, you can load your custom DRM code/file -->
  <script src="customdrm.js" type="application/javascript"></script>
  <!-- and connect it with THEOplayer -->
  <script type="application/javascript">
    THEOplayer.registerContentProtectionIntegration(
        'YourCustomDRMIntegrationID',
        'widevine',
        new ContentProtectionIntegrations.YourCustomContentProtectionIntegrationFactory()
    );
  </script>

</head>
```

By using the exact same `customIntegrationId` on the native side, the underlying THEOplayer will know what to do when it sees a source with the same custom DRM ID.

---

# HLS date ranges (EXT-X-DATERANGE)

The native THEOplayer SDKs can parse `EXT-X-DATERANGE` tags from HLS playlists and expose them as `DateRangeCue`s on a dedicated text track. This is available in the Flutter SDK on Android, iOS and Web.

## Enabling date range parsing

Date range parsing is opt-in. Enable it either for the whole player or per source:

```js
// player-level: applies to every source
player = THEOplayer(
    theoPlayerConfig: THEOplayerConfig(
      license: PLAYER_LICENSE,
      hlsDateRange: true,
    ),
    onCreate: () {},
);

// source-level: overrides the player-level setting for this source
player.source = SourceDescription(sources: [
    TypedSource(
        src: "https://example.com/stream-with-dateranges.m3u8",
        hlsDateRange: true),
]);
```

When `TypedSource.hlsDateRange` is `null` (the default), the player-level `THEOplayerConfig.hlsDateRange` setting applies.

## Consuming DateRangeCues

Date range cues arrive on a `TextTrack` with `type == TextTrackType.daterange`. Listen for the track and its cues through the regular TextTracks API:

```js
player.textTracks.addEventListener(TextTracksEventTypes.ADDTRACK, (event) {
    final track = (event as AddTextTrackEvent).track;
    if (track.type != TextTrackType.daterange) {
      return;
    }
    track.addEventListener(TextTrackEventTypes.ADDCUE, (cueEvent) {
      final cue = (cueEvent as TextTrackAddCueEvent).cue;
      if (cue is DateRangeCue) {
        print("Daterange: id=${cue.id}, startDate=${cue.startDate}, endDate=${cue.endDate}");
      }
    });
});
```

`DateRangeCue` exposes the parsed tag attributes:

| Field                                  | Description                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------ |
| `id`                                   | The `ID` attribute of the date range.                                          |
| `cueClass`                             | The `CLASS` attribute, if present.                                             |
| `startDate` / `endDate`                | The `START-DATE` / `END-DATE` attributes as `DateTime`.                        |
| `duration` / `plannedDuration`         | The `DURATION` / `PLANNED-DURATION` attributes in seconds.                     |
| `endOnNext`                            | Whether the `END-ON-NEXT` attribute is present.                                |
| `customAttributes`                     | The `X-` prefixed client attributes. Binary values are base64-encoded strings. |
| `scte35Cmd` / `scte35Out` / `scte35In` | The raw SCTE-35 payloads as `Uint8List`, if present.                           |

For open-ended date ranges (no end date or duration yet), `cue.endTime` is `double.infinity`.

## Limitations

* Updates to an already-added date range cue (e.g. an `END-DATE` arriving on a later playlist refresh) are not yet forwarded to Flutter.
* Date range parsing only applies to HLS sources; THEOlive sources do not use it.

## Example

The example app contains a "Daterange source" button that plays a stream with date ranges and logs the incoming cues.

---

# Debug Flags (Experimental)

## Overview

**Note**: This is an experimental API. It may change in future releases.

THEOplayer exposes internal debug flags that control verbose logging for various subsystems of the player. These flags can be toggled at runtime through the `player.debugFlags` API, making it easy to enable detailed logging for specific areas without recompiling.

A built-in UI panel is also provided so you can toggle flags interactively during development.

## Programmatic API

The debug flags API is available through `player.debugFlags`:

### Listing Available Flags

```dart
final flags = await player.debugFlags.getAvailableFlags();
for (final flag in flags) {
  print("${flag.key}: enabled=${flag.isEnabled} (default=${flag.defaultValue})");
  print("  ${flag.description}");
}
```

Each `DebugFlag` contains:

| Property       | Type   | Description                                 |
| -------------- | ------ | ------------------------------------------- |
| `key`          | String | Unique identifier for the flag.             |
| `description`  | String | Human-readable description of what it logs. |
| `defaultValue` | bool   | Compile-time default (usually `false`).     |
| `isEnabled`    | bool   | Current runtime state.                      |

### Toggling Individual Flags

```dart
// Enable a specific flag
await player.debugFlags.enableFlag("some_flag_key");

// Disable it
await player.debugFlags.disableFlag("some_flag_key");
```

### Bulk Operations

```dart
// Enable all flags
await player.debugFlags.enableAll();

// Disable all flags
await player.debugFlags.disableAll();

// Reset all flags to their compile-time defaults
await player.debugFlags.resetAll();
```

### File Logging (iOS only)

On iOS, you can enable file logging which writes debug output to a log file in addition to the console. This is a no-op on Android.

```dart
await player.debugFlags.enableFileLogging();
```

## Built-in Debug Panel

The SDK includes a ready-to-use `DebugFlagsPanel` widget that provides a full UI for managing debug flags, including search, individual toggles, and bulk actions.

### Showing the Panel

The simplest way is to use the convenience method on the player:

```dart
// Push the debug panel as a full-screen route
player.showDebugPanel(context);
```

Alternatively, you can use the panel widget or its static helper directly:

```dart
// Using the static helper
DebugFlagsPanelNavigation.show(context, player.debugFlags);

// Or embed it in your own layout
DebugFlagsPanel(api: player.debugFlags);
```

### Panel Features

* **Search** — filter flags by key or description
* **Toggle switches** — enable/disable individual flags
* **Status bar** — shows how many flags are currently enabled
* **Overflow menu** — Enable All, Disable All, Reset to Defaults, Enable File Logging (iOS)
* **Visual indicators** — overridden flags (different from default) are highlighted in bold

## Platform Differences

| Feature          | Android                             | iOS                                        |
| ---------------- | ----------------------------------- | ------------------------------------------ |
| Available flags  | Logger tags from the native SDK     | `DebugConfig.availableFlags` from THEOlive |
| Enable / Disable | `Logger.enableTags` / `disableTags` | `DebugConfig.enable` / `disable`           |
| Reset            | Disables all tags                   | Resets to compile-time defaults            |
| File logging     | No-op                               | Writes to OS log + file via `DebugConfig`  |

---

# Limitations and Known Issues

This sections lists any limitations and known issues in the current package version.

## Platform support

THEOplayer Flutter SDK is capable of running on

* iOS 13 and above
* Android 5 and above
* Mainstream web browsers (Firefox 120+, Chrome 119+, Safari 17+, Microsoft Edge 119+)

However, it is not optimized for those devices.

**For the best experience, we suggest to target**

* iOS 14 and above
* Android 10 and above

In a later phase, we will optimize the SDKs for lower operating system versions as much as possible.

### Smart TV support

THEOplayer Flutter SDK **officially doesn't support Smart TVs**. However, if your application is compiled for WEB, it should be able to run on modern Smart TVs (like Tizen 7+ and WebOS 23+) with smaller modifications on how the webapp loads the Flutter library.

Supporting Smart TVs is not a priority for the THEOplayer Flutter SDK (yet).

## Platform differences

The underlying native platform SDKs have different feature set. First check the Dart documentation if you see behaviour differences on certain platforms. We try to keep the documentation in sync as much as possible. If you see no difference mentioned in behaviour, please consult with the [native SDK documentations](https://www.theoplayer.com/docs/theoplayer/).

### Live latency configuration

`TypedSource.latencyConfiguration` configures live playback when the source is loaded. All offsets are expressed in seconds.

| Option                                              | Android   | iOS       | Web       |
| --------------------------------------------------- | --------- | --------- | --------- |
| `targetOffset`                                      | Supported | Supported | Supported |
| `minimumOffset`, `maximumOffset`, `forceSeekOffset` | Supported | Ignored   | Supported |
| `minimumPlaybackRate`, `maximumPlaybackRate`        | Supported | Ignored   | Supported |
| `lowLatency`                                        | Ignored   | Ignored   | Supported |

On iOS, `targetOffset` is passed to AVPlayer as its configured time offset from live. AVPlayer will not use a configured offset below its recommended time offset, so very small targets might not be reached.

On iOS, `latencyConfiguration` is applied when setting a source, but is `null` in source getters and source-change event payloads for regular sources. OptiView Live sources retain their target latency in these readbacks.

The `lowLatency` option enables the player's low-latency mode on Web and is required for Low-Latency CMAF with ABR. It is not required to play Low-Latency HLS.

## Version limitations

THEOplayer Flutter SDK only compatible with THEOplayer 6.x and above.

## UI

Currently, THEOplayer Flutter SDK is completely chromeless, the UI needs to be implemented on top of the public APIs on the Flutter level.

The `example` project within the SDK package contains a sample UI.

## Missing features

THEOplayer Flutter SDK is not in feature parity yet with the native SDKs, new features will be added continuously.

For the current feature list, please visit the [README](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/flutter/getting-started.md) page.

---

# Migration Guide: From THEOplayer Flutter SDK 10.x to 11.x

This guide covers the breaking changes introduced by updating the underlying native THEOplayer SDKs to 11.1.0.

## Overview

Most of the Dart API surface is unchanged. Migrating consists of:

1. Removing the OptiView Live preloading calls (removed from the native SDKs).
2. Raising the iOS deployment target of your app to 15.0.
3. Building your iOS app with Xcode 26 or later.

## Breaking Changes

### 1. OptiView Live (THEOlive) preloading removed

`preloadChannels` (Android, iOS) and `preloadPublications` (web) were removed from the native OptiView Live APIs, so the Flutter wrapper drops the corresponding methods as well. There is no replacement: the stream is loaded when the source is set on the player.

**Before:**

```dart
// preload channels for faster startup
player.theoLive?.preloadChannels(["38yyniscxeglzr8n0lbku57b0"]);

player.source = SourceDescription(sources: [
    TheoLiveSource(src: "38yyniscxeglzr8n0lbku57b0"),
]);
```

**After:**

```dart
player.source = SourceDescription(sources: [
    TheoLiveSource(src: "38yyniscxeglzr8n0lbku57b0"),
]);
```

### 2. Update iOS toolchain

* THEOplayer iOS SDK 11.0.0 dropped support for iOS 13 and 14. Set the deployment target to 15.0 or higher.
* Building an app that uses this Flutter SDK therefore requires **Xcode 26 or later** and a macOS version supporting it.

## What Remains Unchanged

* The rest of the THEOlive API

## Rationale

These changes were made to:

* **Align with THEOplayer 11.1.0**: the Flutter SDK version is locked to the native SDK version
* **Follow Apple's tooling requirements**: iOS 15+ and Xcode 26 are required by the native iOS SDK
* **Drop unsupported APIs**: the THEOlive preloading APIs no longer exist in the native SDKs

## Need Help?

If you encounter issues during migration or have questions about the new API, please:

1. Check the updated documentation in `doc/theolive.md`
2. Review the example app for working code samples
3. Consult the [THEOplayer 11.0.0](https://optiview.dolby.com/docs/theoplayer/changelog/#-1100-20260416) and [11.1.0](https://optiview.dolby.com/docs/theoplayer/changelog/#-1110-20260428) native changelogs
4. Open an issue in the repository with specific migration questions

---

# Migration Guide: From THEOplayer Flutter SDK 9.x to 10.x

This guide covers the breaking changes introduced when renaming "publication"-related APIs to "distribution" for consistency and clarity.

## Overview

The THEOplayer Flutter SDK has renamed all "publication"-related APIs to use "distribution" terminology instead. This change affects state management, event types, and property names.

## Breaking Changes

### 1. State Enum Renamed

**Before:**

```dart
enum PublicationState { idle, loading, loaded, intentToFallback, offline }
```

**After:**

```dart
enum DistributionState { idle, loading, loaded, intentToFallback, offline }
```

### 2. State Property Renamed

**Before:**

```dart
PublicationState state = player.theoLive?.publicationState;
```

**After:**

```dart
DistributionState state = player.theoLive?.distributionState;
```

### 3. Event Types Updated

**Before:**

```dart
player.theoLive?.addEventListener(THEOliveApiEventTypes.PUBLICATIONLOADSTART, (e) {
    print("Publication load started");
});

player.theoLive?.addEventListener(THEOliveApiEventTypes.PUBLICATIONLOADED, (e) {
    print("Publication loaded");
});

player.theoLive?.addEventListener(THEOliveApiEventTypes.PUBLICATIONOFFLINE, (e) {
    print("Publication offline");
});
```

**After:**

```dart
player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONLOADSTART, (e) {
    print("Distribution load started");
});

player.theoLive?.addEventListener(THEOliveApiEventTypes.ENDPOINTLOADED, (e) {
    print("Endpoint loaded");
});

player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONOFFLINE, (e) {
    print("Distribution offline");
});
```

### 4. Event Class Renamed

**Before:**

```dart
// In custom event handling code
if (event is PublicationLoadedEvent) {
    print("Publication loaded.");
}

if (event is PublicationLoadStartEvent) {
    print("Publication load started.");
}

if (event is PublicationOfflineEvent) {
    print("Publication offline.");
}
```

**After:**

```dart
// In custom event handling code
if (event is EndpointLoadedEvent) {
    print("Endpoint loaded.");
}

if (event is DistributionLoadStartEvent) {
    print("Distribution load started.");
}

if (event is DistributionOfflineEvent) {
    print("Distribution load started.");
}
```

### 5. Android Source Configuration Simplified

**Before:**

```dart
import 'package:theoplayer/theoplayer.dart';

// PlaybackPipeline enum and configuration
enum PlaybackPipeline { media3, legacy }

AndroidTypedSourceConfiguration config = AndroidTypedSourceConfiguration(
    playbackPipeline: PlaybackPipeline.media3
);

TypedSource source = TypedSource(
    src: "https://example.com/stream.m3u8",
    androidSourceConfiguration: config
);
```

**After:**

```dart
import 'package:theoplayer/theoplayer.dart';

// PlaybackPipeline enum removed - Media3 is now the default
AndroidTypedSourceConfiguration config = AndroidTypedSourceConfiguration();

TypedSource source = TypedSource(
    src: "https://example.com/stream.m3u8",
    androidSourceConfiguration: config
);
```

## Migration Steps

### Step 1: Update Import Statements

No changes needed - all imports remain the same.

### Step 2: Update State References

Replace all instances of:

* `PublicationState` → `DistributionState`
* `publicationState` → `distributionState`

**Example:**

```dart
// Before
void handleStateChange() {
  PublicationState currentState = player.theoLive?.publicationState;
  if (currentState == PublicationState.loaded) {
    // Handle loaded state
  }
}

// After
void handleStateChange() {
  DistributionState currentState = player.theoLive?.distributionState;
  if (currentState == DistributionState.loaded) {
    // Handle loaded state
  }
}
```

### Step 3: Update Event Listeners

Replace event type constants:

* `THEOliveApiEventTypes.PUBLICATIONLOADSTART` → `THEOliveApiEventTypes.DISTRIBUTIONLOADSTART`
* `THEOliveApiEventTypes.PUBLICATIONLOADED` → `THEOliveApiEventTypes.ENDPOINTLOADED`
* `THEOliveApiEventTypes.PUBLICATIONOFFLINE` → `THEOliveApiEventTypes.DISTRIBUTIONOFFLINE`

**Example:**

```dart
// Before
void setupEventListeners() {
  player.theoLive?.addEventListener(THEOliveApiEventTypes.PUBLICATIONLOADSTART, (e) {
    print("Starting to load publication");
  });

  player.theoLive?.addEventListener(THEOliveApiEventTypes.PUBLICATIONLOADED, (e) {
    print("Publication has loaded");
  });

  player.theoLive?.addEventListener(THEOliveApiEventTypes.PUBLICATIONOFFLINE, (e) {
    print("Publication went offline");
  });
}

// After
void setupEventListeners() {
  player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONLOADSTART, (e) {
    print("Starting to load distribution");
  });

  player.theoLive?.addEventListener(THEOliveApiEventTypes.ENDPOINTLOADED, (e) {
    print("Endpoint has loaded");
  });

  player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONOFFLINE, (e) {
    print("Distribution went offline");
  });
}
```

### Step 4: Update Event Class References

If you have custom event handling code that checks event types:

**Before:**

```dart
void handleEvent(Event event) {
    if (event is PublicationLoadedEvent) {
        print("Publication has loaded.");
    }
    ...
    
    if (event is PublicationLoadStartEvent) {
        print("Publication loading started.");
    }
    ...
    
    if (event is PublicationOfflineEvent) {
        print("Publication went offline.");
    }
}
```

**After:**

```dart
void handleEvent(Event event) {
    if (event is EndpointLoadedEvent) {
        print("Endpoint has loaded.");
    }
    ...
    
    if (event is DistributionLoadStartEvent) {
        print("Distribution loading started.");
    }
    ...
    
    if (event is DistributionOfflineEvent) {
        print("Distribution went offline.");
    }
}
```

### Step 5: Update Integration Tests

If you have integration tests that check publication state:

**Before:**

```dart
expect(player.theoLive?.publicationState == PublicationState.loaded, isTrue);
```

**After:**

```dart
expect(player.theoLive?.distributionState == DistributionState.loaded, isTrue);
```

### Step 6: Update Android Source Configuration

Remove PlaybackPipeline configurations from Android sources:

**Before:**

```dart
AndroidTypedSourceConfiguration config = AndroidTypedSourceConfiguration(
    playbackPipeline: PlaybackPipeline.media3
);
```

**After:**

```dart
AndroidTypedSourceConfiguration config = AndroidTypedSourceConfiguration();
```

### Step 7: Update Event Parameter Access

Change event parameter names in custom event handlers:

**Before:**

```dart
void onDistributionEvent(DistributionLoadStartEvent event) {
    String id = event.publicationId;  // Old parameter name
}
```

**After:**

```dart
void onDistributionEvent(DistributionLoadStartEvent event) {
    String id = event.distributionId;  // New parameter name
}
```

## Automated Migration

You can use find-and-replace in your IDE to automate most of the migration:

1. **Find:** `PublicationState` **Replace:** `DistributionState`
2. **Find:** `publicationState` **Replace:** `distributionState`
3. **Find:** `PUBLICATIONLOADSTART` **Replace:** `DISTRIBUTIONLOADSTART`
4. **Find:** `PUBLICATIONLOADED` **Replace:** `ENDPOINTLOADED`
5. **Find:** `PUBLICATIONOFFLINE` **Replace:** `DISTRIBUTIONOFFLINE`
6. **Find:** `PublicationLoadedEvent` **Replace:** `EndpointLoadedEvent`
7. **Find:** `PublicationLoadStartEvent` **Replace:** `DistributionLoadStartEvent`
8. **Find:** `PublicationOfflineEvent` **Replace:** `DistributionOfflineEvent`
9. **Find:** `event.publicationId` **Replace:** `event.distributionId`
10. **Find:** `PlaybackPipeline.media3` **Replace:** *(remove - no longer needed)*
11. **Find:** `PlaybackPipeline.legacy` **Replace:** *(remove - no longer supported)*
12. **Find:** `playbackPipeline: PlaybackPipeline.` **Replace:** *(remove entire parameter)*

## What Remains Unchanged

* All other THEOlive APIs
* Event listener registration/removal methods
* Source configuration (`TheoLiveSource`)
* Player initialization and setup

## Rationale

These changes were made to:

* **Align with THEOplayer 10.0.0**: Update to the latest native SDK with improved APIs
* **Consistent terminology**: Match THEOplayer's native SDK distribution/endpoint terminology
* **Simplified configuration**: Remove deprecated PlaybackPipeline options (Media3 is now the standard)
* **Clearer parameter names**: `distributionId` better represents the actual data than `publicationId`
* **Improved developer experience**: More intuitive and predictable API surface

## Need Help?

If you encounter issues during migration or have questions about the new API, please:

1. Check the updated documentation in `doc/theolive.md`
2. Review the example app for working code samples
3. Open an issue in the repository with specific migration questions

---

# Picture-in-Picture support

THEOplayer Flutter SDK supports native Picture-in-Picture on iOS, Android and Web platforms. However, there are some differences and limitations.

## Android and iOS

Entering Picture-in-Picture (PiP) is possible through the `THEOplayer.setAllowAutomaticPictureInPicture(bool)` API.

This will not put the player into Picture-in-Picture mode immediately, but enables the player to enter PiP when the application moves to the background.

### Necessary configurations on app-level

#### Android

Enable [Picture-in-Picture support](https://developer.android.com/develop/ui/views/picture-in-picture#declaring) for your main Activity in the `AndroidManifest.xml` file.

```xml
<activity android:name=".MainActivity"
    android:supportsPictureInPicture="true"
    android:configChanges=
        "screenSize|smallestScreenSize|screenLayout|orientation|..."
    ...
```

#### iOS

Enable `Background Audio mode` for your application target in [XCode](https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/MediaPlaybackGuide/Contents/Resources/en.lproj/ConfiguringAudioSettings/ConfiguringAudioSettings.html#//apple_ref/doc/uid/TP40016757-CH9-SW4).

![](https://raw.githubusercontent.com/THEOplayer/flutter-theoplayer-sdk/main/doc/xcode_background_modes.png)

### Limitations

* Picture-in-Picture is only supported from Android O (Oreo, API level 26).

* Picture-in-Picture is only supported from iOS 14.

* In multi-player scenarios there can be only one player that has `allowAutomaticPictureInPicture` set to `true`. Failing to do so might lead to unpredictable behaviour.

* On iOS paused player can not enter PiP mode.

* Calling `THEOplayer.setPresentationMode(PresentationMode.PIP)` API to explicitly enter PiP mode doesn't work on iOS and Android.

  * This limitation is due to the differences on how native iOS and Android handles the PiP mode.

    * iOS moves the player into PiP, while keeping the ViewController on the screen.
    * Android moves the whole Activity into PiP.

  * Aligning these will be investigated in the next iterations of the THEOplayer Flutter SDK.

  * You can try use the [`go_home`](https://pub.dev/packages/go_home) package to simulate "Home button press" on Android and iOS to trigger application backgrounding (which will start the automatic PiP mode).
    * **NOTE**: there could be issues in the App Stores with the way this plugin simulates the "Home button press", use it on your own risk.

## Web

Entering Picture-in-Picture (PiP) is possible through the `THEOplayer.setPresentationMode(PresentationMode.PIP)` API.

### Limitations

* Picture-in-Picture is not supported in Firefox.
* `THEOplayer.setAllowAutomaticPictureInPicture(bool)` API is not supported.

---

# THEOlive support

High-quality synchronized video streaming at scale for providers of large sports broadcasting, sports betting, and interactive entertainment

## Platform support

THEOlive playback is supported on Android, iOS and Web as part of the THEOplayer Flutter SDK.

## THEOlive playback

THEOlive playback is part of THEOplayer's playback engine instead of being available as a separate SDK.

### Setting a THEOlive source

```js
player.source = SourceDescription(sources: [
    TheoLiveSource(src: "2vqqekesftg9zuvxu9tdme6kl"),
]);
```

Instead of using a remote HTTPS url, you can just specify your `channelID` from the [THEOlive Console](https://console.theo.live/) and you can start the playback.

### Overriding the target latency

A source-level latency target overrides the target configured in the THEOlive Console:

```dart
player.source = SourceDescription(sources: [
    TheoLiveSource(
        src: "2vqqekesftg9zuvxu9tdme6kl",
        latencyConfiguration: SourceLatencyConfiguration(targetOffset: 2.0),
    ),
]);
```

Android and Web also support the optional minimum and maximum offsets, force-seek offset and playback-rate bounds. iOS applies only `targetOffset`.

**NOTE:** your THEOplayer license has to contain the `HESP` feature to make it work. (HESP is the underlying technology of THEOlive).

Once the playback starts, you can listen to playback-specify events on THEOplayer.

#### Additional configuration options on `THEOPlayerConfig`

By setting a `THEOliveConfiguration` object on `THEOplayerConfig` you are able to specify extra configuration for THEOlive (e.g. a custom sessionId to follow the requests on the backend)

```js
    player = THEOplayer(
        theoPlayerConfig: THEOplayerConfig(
          license: PLAYER_LICENSE,
          theolive: TheoLiveConfiguration(externalSessionId: "mySessionID"),
        ),
        onCreate: () {
          print("player is created, ready to use");
    
        });
```

### Listening for THEOlive-specific events

```js
    player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONLOADSTART, (e) {
        print("DISTRIBUTIONLOADSTART");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONOFFLINE, (e) {
        print("DISTRIBUTIONOFFLINE");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.ENDPOINTLOADED, (e) {
        print("ENDPOINTLOADED");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.INTENTTOFALLBACK, (e) {
        print("INTENTTOFALLBACK");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.ENTERBADNETWORKMODE, (e) {
        print("ENTERBADNETWORKMODE");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.EXITBADNETWORKMODE, (e) {
        print("EXITBADNETWORKMODE");
    });
```

## Migration from THEOlive Flutter SDK to THEOplayer Flutter SDK

### setStateListener

From

```js
theoLive.setStateListener(...)
```

to

```js
player.theoLive.setStateListener(...)
```

### loadChannel

From

```js
theoLive.loadChannel("2vqqekesftg9zuvxu9tdme6kl")
```

to

```js
player.source = SourceDescription(sources: [
    TheoLiveSource(src: "2vqqekesftg9zuvxu9tdme6kl"),
]);
```

### addEventListener

From

```js
theoLive.addEventListener(this)
```

to THEOlive-related events

```js
    player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONLOADSTART, (e) {
        print("DISTRIBUTIONLOADSTART event");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONOFFLINE, (e) {
        print("DISTRIBUTIONOFFLINE event");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.ENDPOINTLOADED, (e) {
        print("ENDPOINTLOADED event");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.INTENTTOFALLBACK, (e) {
        print("INTENTTOFALLBACK event");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.ENTERBADNETWORKMODE, (e) {
        print("ENTERBADNETWORKMODE event");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.EXITBADNETWORKMODE, (e) {
        print("EXITBADNETWORKMODE event");
    });
```

and to playback-related events

```js
    player.addEventListener(PlayerEventTypes.PLAY, (e) {
        print("PLAY event");
    });
    player.addEventListener(PlayerEventTypes.PLAYING, (e) {
        print("PLAYING event");
    });
    player.addEventListener(PlayerEventTypes.PAUSE, (e) {
        print("PAUSE event");
    }););
```

### Playback-related actions

From

```js
theoLive.play()
```

to

```js
player.play()
```

### Channel events

The channel related events:

```js
ChannelLoadStart,
ChannelLoaded,
ChannelOffline
```

are renamed to `Publication` events

```js
PublicationLoadStart,
PublicationLoaded,
PublicationOffline
```

### Anything missing?

Please reach out to us!

---

# The THEOplayer component

## Architecture

![](https://raw.githubusercontent.com/THEOplayer/flutter-theoplayer-sdk/main/doc/theoplayer_flutter_sdk_arch.png)

THEOplayer Flutter SDK utilizes the well-known THEOplayer native SDKs under the hood and exposes the APIs on a single API layer in Flutter to speed up prototyping and development.

## Available APIs

* Basic player APIs (play, pause, seek, etc...) on the `THEOplayer` instance
* `SourceDescription`-related classes
* Player events (`CANPLAY, PLAYING, TIMEUPDATE`, etc..)
* Track APIs (acive tracks, cues, enable, disable) on the `THEOplayer.[audio|video|text]track` objects
* `Track`-related classes
* Track events (`ADD_TRACK, REMOVE_TRACK, ADD_CUE, ENTER_CUE`, etc..)

## API Reference

*To be completed.*

Please use your IDE's features to discover the available APIs.

Read [`theoplayer.dart`](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/-/flutter_theoplayer_sdk/flutter_theoplayer_sdk/lib/theoplayer.dart) for all the details.

---

# WASM support (experimental)

When compiling the THEOplayer Flutter SDK for WEB, you can now specify [WASM support](https://docs.flutter.dev/platform-integration/web/wasm).

## Flutter Compatibility

Use **Flutter 3.35.3 or later** for the best performance and compatibility. (earlier versions could have rendering issues with the video element)

## Run or build your app

To run the app with Wasm for development or testing, use the `--wasm` flag with the `flutter run` command.

```bash
flutter run -d chrome --wasm
```

To build a web application with Wasm, add the `--wasm` flag to the existing `flutter build web` command.

```bash
flutter build web --wasm
```

The command produces output into the `build/web` directory relative to the package root, just like `flutter build web`.

## Changes required in your app

### Bootstrapping

Make sure your app's `web/index.html` is updated to the [latest Flutter web app initialization](https://docs.flutter.dev/platform-integration/web/initialization) (it was introduced from Flutter 3.22).

It depends on your project structure, but most of the times this only means you need to make sure that `flutter_bootstrap.js` is properly included in your `index.html`.

### Include THEOplayer WEB SDK as asset

Define the path of the folder that contains THEOplayer Web SDK as an `asset` in your `pubspec.yaml` file to make sure the Javascript files will be included.

For example, if the THEOplayer WEB SDK is located under `web/theoplayer`, then

```yaml
  assets:
    - web/theoplayer/
```

## Browser support

Not all browsers support the Flutter WASM renderer. Please always check the status of the compatibility [here](https://docs.flutter.dev/platform-integration/web/wasm#learn-more-about-browser-compatibility).

## Host it on a compatible server

Extra [configuration is needed](https://docs.flutter.dev/platform-integration/web/wasm#serve-the-built-output-with-an-http-server) on the server-side to make sure WebAssembly runs properly.

During debugging the `flutter run -d chrome --wasm` command will serve your webapp properly, but once you build a release version and host it on your own server, you need to make sure the server is configured properly.

For example don't expect that any basic web serving command e.g. (`python3 -m http.server 8000`) will just to run with WebAssembly support.

On the other hand most of the hosting solutions (e.g. Netlify or [Netlify Drop](https://app.netlify.com/drop)) will have this configured out of the box.

Always consult with your hosting provider first!

---

# Getting started

## Usage

We have migrated OptiView Live Flutter support to be a feature of the THEOplayer Flutter SDK.

To use Flutter for OptiView Live playback, you must use the [THEOplayer Flutter SDK](https://pub.dev/packages/theoplayer) which now supports Web, Android, and iOS devices. The following steps will ensure your project is setup optimally:

1. Review the [THEOplayer Flutter SDK limitations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/limitations.md) to ensure your use case needs are supported before starting development.
2. Follow along with the [THEOplayer Flutter SDK minimal setup guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/creating-minimal-app.md) to setup a basic OptiView Live project.
3. Check the [THEOlive support guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/theolive.md) for the latest OptiView Live Flutter updates.

For customers currently using the now deprecated OptiView Live SDK for playback, please migrate to using the THEOplayer SDK with the following [THEOlive migration guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/theolive.md#migration-from-theolive-flutter-sdk-to-theoplayer-flutter-sdk) to always have the latest updates.

### Flutter project setup

Run the following script to generate boilerplate code for your Flutter project:

```bash
$ flutter create -a kotlin -i swift -t app --org com.theoplayer --description "New THEOlive project" --project-name "theolive_sample_app" --platform ios,android theolive_sample_app
```

### Initializing a THEOplayer instance

Configure the THEOplayer by setting your THEOplayer license on the `license` property and optionally providing a `theolive` property for custom configuration:

```dart
late THEOplayer player;

@override
void initState() {
  super.initState();

  player = THEOplayer(
      theoPlayerConfig: THEOplayerConfig(
        license: "YOUR_PLAYER_LICENSE_STRING",
        // Extra THEOlive configuration - set a custom sessionId to follow the requests on the backend
        theolive: TheoLiveConfiguration(externalSessionId: "mySessionID"),
      ),
      onCreate: () {
        print("THEOplayer is created and ready to use");
      });
}
```

### Add an OptiView Live source

After initializing a THEOplayer instance in your Flutter project, set its source with a `SourceDescription` containing a `TheoLiveSource`:

```text
// a THEOlive channel ID is entered for the theoLiveSource 'src' property
player.source = SourceDescription(sources: [
    TheoLiveSource(src: "2vqqekesftg9zuvxu9tdme6kl"),
]);
```

### Next steps

If you've followed the steps above, you should now have a boilerplate OptiView Live Flutter application to further develop your project from.

Use Flutter documentation along with our [basic playback guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/flutter/theolive/basic-playback-guide.md) for Flutter to develop your project.

## More information

* [THEOplayer Flutter SDK GitHub](https://github.com/THEOplayer/flutter-theoplayer-sdk/tree/main)

---

# Basic Playback Guide

After following our [Getting Started with Flutter guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/flutter/theolive/getting-started.md) or the [Player Setup](#player-setup) section below, you will be ready to programmatically perform common playback actions. These include increasing/decreasing the volume, playing/pausing the stream, enabling full screen, and selecting quality layers.

## Player Setup

To get started with OptiView Live playback using Flutter, you must first initialize a THEOplayer instance and set an OptiView Live source.

Here is example code of initializing a THEOplayer instance with Flutter:

```dart
late THEOplayer player;

@override
void initState() {
  super.initState();

  player = THEOplayer(
      theoPlayerConfig: THEOplayerConfig(
        license: "YOUR_PLAYER_LICENSE_STRING",
        // Extra THEOlive configuration - set a custom sessionId to follow the requests on the backend
        theolive: TheoLiveConfiguration(externalSessionId: "mySessionID"),
      ),
  )
}

player.source = SourceDescription(sources: [
    TheoLiveSource(src: "2vqqekesftg9zuvxu9tdme6kl"),
]);
```

## Adjust Volume

To adjust the volume of your stream during playback, you can set the `volume` property to a floating point number in the range of 0.0 (0%) minimum and 1.0 (100%) maximum.

The following code sets the player's volume to 50%:

```dart
// the stream's volume will now be 50%
player.volume = 0.5;
```

## Play/Pause Stream

To play or pause your stream, you can use the `play` and `pause` methods available on your player variable.

To pause your stream:

```dart
player.pause();
```

To play your stream:

```dart
player.play();
```

## Enable Full Screen

To make your stream take up the full screen of the device it is being viewed upon, you must use the `setPresentationMode` method.

The `setPresentationMode` method can accept the following arguments:

* `'INLINE'`: The player is shown in its original location on the page. (default presentation mode)
* `'FULLSCREEN'`: The player fills the entire screen.
* `'PIP'`: (Picture-in-picture) The player is shown on top of the page (see PiPConfiguration for more options).

To make the current stream take up the full screen, pass a presentationMode of 'fullscreen' to the requestMode method with the following code:

```dart
// stream will take up the full screen which it is being viewed on
player.setPresentationMode('FULLSCREEN');
```

To confirm that the change has occurred, check the `getPresentationMode` property to ensure it now returns `fullscreen` as its value:

```dart
// should return a value of 'fullscreen' to the console
print('this is the current presentation mode being used --> ${player.getPresentationMode()}');
```

## Select Quality Layer

To select a specific quality layer during the playing of your stream, you must set the `targetQuality` property of your player's `videoTracks` property.

The `videoTracks` property leverages the Video Tracks API and will allow you to see all quality layers available, the current active quality layer, and set a new target quality layer.

To see what qualities you have available, use the following code:

```dart
// import needed to use the 'inspect' function
import 'dart:developer';

// inspect all available quality layers
var qualities = player.videoTracks.first.qualities.innerList;
inspect("this is an array containing all available qualities --> ${qualities}");
```

Once you know what options you have available, you can set the stream to be a specific quality with the following:

```dart
// set the first quality layer in the array to be the target quality layer
player.videoTracks.first.targetQuality = player.videoTracks.first.qualities.first;
```

## More information

* [THEOplayer Flutter SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter.md)

---

# Discovery URLs

Before the player can play an OptiView Live channel, it sends a discovery request to find the stream details of that channel (such as its manifest URLs and token security settings). OptiView Live channels are served by one of three discovery API versions:

| API version | Channels                                          |
| ----------- | ------------------------------------------------- |
| V1 (legacy) | Channels created with the legacy THEOlive API.    |
| V2          | Distributions created with the OptiView Live API. |
| V3          | Distributions served by the newest discovery API. |

The player does not know in advance which API version serves your channel. If you do not configure a discovery URL, the player tries its built-in discovery URLs one by one, in this order:

1. V2
2. V1 (legacy)
3. V3

The player stops at the first discovery URL that returns the channel. If your channel is not served by V2, the earlier requests fail before the right one succeeds. These failed requests add a small delay before playback starts, and they show up as `404` responses in the network tab of your browser or in a network proxy. The `404` responses are expected and do not mean that playback failed.

## Why configure a discovery URL

When you configure the discovery URL that serves your channel, the player sends its first discovery request to that URL. This removes the failed requests and the extra startup delay.

Configured discovery URLs do not replace the built-in discovery URLs. The player tries them first, and continues with the built-in discovery URLs (V2, V1, V3) if the configured ones do not return the channel. A wrong discovery URL therefore costs one extra request, but it does not break playback.

On platforms that support both `discoveryUrl` and `discoveryUrls`, the player tries `discoveryUrl` first, then each URL of `discoveryUrls` in the order of the list, and then the built-in discovery URLs.

## Which discovery URL to use

The player derives the API version from the path of the discovery URL, so use the URL exactly as listed for your platform, including the trailing `/`. The URL for V1 channels is different on Web than on the other platforms.

| API version | Web                                             | Android, iOS, Roku                              |
| ----------- | ----------------------------------------------- | ----------------------------------------------- |
| V2          | `https://discovery.theo.live/v2/distributions/` | `https://discovery.theo.live/v2/distributions/` |
| V1 (legacy) | `https://discovery.theo.live/`                  | `https://discovery.theo.live/v2/publications/`  |
| V3          | `https://discovery.theo.live/v3/`               | `https://discovery.theo.live/v3/`               |

React Native and Flutter apps pass the discovery URL to the underlying Web, Android or iOS SDK, so the same rules apply per platform.

> **Find the API version of your channel**
>
> Play your channel without a discovery URL and open the network tab of your browser (or a network proxy for a native app). The discovery request that returns `200` shows the discovery URL that serves your channel. For example, a request to `https://discovery.theo.live/v2/distributions/<your-channel-id>` means that your channel is served by V2.

## Configure the discovery URL

Set the discovery URL in the `theolive` property of `THEOplayerConfig`. For example, for a channel served by V2:

```dart
player = THEOplayer(
  theoPlayerConfig: THEOplayerConfig(
    license: "your-license",
    theolive: TheoLiveConfiguration(
      discoveryUrl: "https://discovery.theo.live/v2/distributions/",
    ),
  ),
);
```

Flutter supports one configured discovery URL, which is passed to the Web, Android or iOS SDK. The V2 and V3 discovery URLs are the same on all platforms. For V1 channels, the URL is different on Web (`https://discovery.theo.live/`) than on Android and iOS (`https://discovery.theo.live/v2/publications/`), so use `kIsWeb` to select the right one:

```dart
import 'package:flutter/foundation.dart' show kIsWeb;

final theoLiveConfig = TheoLiveConfiguration(
  discoveryUrl: kIsWeb ? "https://discovery.theo.live/" : "https://discovery.theo.live/v2/publications/",
);
```

## Configuration reference

All properties of `TheoLiveConfiguration` are optional.

| Property            | Type      | Platforms         | Description                                                                                                   |
| ------------------- | --------- | ----------------- | ------------------------------------------------------------------------------------------------------------- |
| `discoveryUrl`      | `String?` | Web, Android, iOS | A discovery URL that the player tries before the built-in discovery URLs.                                     |
| `externalSessionId` | `String?` | Web, Android, iOS | An ID used to report usage analytics.                                                                         |
| `fallbackEnabled`   | `bool?`   | Web               | Whether the player plays the fallback stream when a V1 channel has a fallback configured. Defaults to `true`. |

The default discovery order V2, V1, V3 applies when the app uses THEOplayer 11.13.0 or later.

---

# OptiView Player Chromecast SDK

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Dolby OptiView Player is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md)

[Set up your first THEOplayer in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md)

[Find out what's new in the OptiView Player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

# Getting started on Chromecast

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

This how-to guide describes how to set up a Chromecast Receiver application using the Dolby OptiView Player SDK.

> **Info**
>
> This guide is intended for developing a Chromecast Receiver application with Google Cast SDK v2. Since Google Cast SDK v2 is deprecated by Google, we highly recommend developing your Chromecast SDK with CAF instead of v2. You can find the THEOplayer Cast Receiver Reference app [here](https://github.com/THEOplayer/samples-google-cast-v3-receiver).

## Prerequisite:

You need to build a THEOplayer Chromecast Receiver SDK from THEOportal.

## Set up a web project

A Chromecast Receiver application is a web project. Create a sample project, add a `_receiver_` folder, and create an index.html file in this folder with the following skeleton code.

## Integrate the Google Cast Receiver SDK

By including the Google Cast Receiver SDK, you have access to the Receiver API. The THEOplayer Receiver SDK leverages this API.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Chromecast Receiver Sample Application</title>
    <script src="//www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js"></script>
  </head>
  <body></body>
</html>
```

## Integrate the THEOplayer Chromecast Receiver SDK

By including the THEOplayer Chromecast Receiver SDK, you have access to the THEOplayer Receiver SDK. This SDK consists of a JavaScript library (consisting of four files) and a CSS file. Create a *release* folder, and put the 5 files belonging to the THEOplayer Chromecast Receiver SDK in this folder.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Chromecast Receiver Sample Application</title>
    <script src="//www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js"></script>
    <script src="../release/THEOplayer-cast-receiver.js"></script>
    <link rel="stylesheet" type="text/css" href="../release/ui.css" />
  </head>
  <body></body>
</html>
```

## Set up THEOplayer instance

Setting up a THEOplayer instance in a Chromecast Receiver application is similar to our Web SDK. More information on setting up the THEOplayer Web SDK can be found at [Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md).

You need to add a DOM-element which will contain the user interface of THEOplayer, and you need to initialize the THEOplayer instance through JavaScript code.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Chromecast Receiver Sample Application</title>
    <script src="//www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js"></script>
    <script src="../release/THEOplayer-cast-receiver.js"></script>
    <link rel="stylesheet" type="text/css" href="path/to/theoplayer/ui.css" />
  </head>
  <body>
    <div id="my-player"></div>
    <script>
      var player = new THEOplayer.Player(document.getElementById('my-player'), {
        libraryLocation: 'path/to/theoplayer/',
        license: 'your-license-here',
      });
    </script>
  </body>
</html>
```

## Optional: alter default UI

The CSS snippet added to the code-block below have the following effect:

1. `.THEO-cast-receiver-player .THEO-cast-receiver-logo`: Change the default splash image when your receiver app is loading. This default splash image will show a THEOplayer-branded image, but you might want to replace it with a different image.
2. `.THEO-cast-receiver-player .THEO-cast-receiver-watermark`: Change the default watermark logo which is shown when pausing (or buffering). This default watermark logo will show a THEOplayer-branded image, but you might want to replace it with a different image.

In each of the examples, be sure to set the image source correctly, by replacing the '...'.

Note that you can also use the easy UI skinning colors to modify the UI as described in <http://demo.theoplayer.com/ui-skinning>. You can reuse the CSS you use in the THEOplayer Web SDK in your Chromecast receiver as well!

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Chromecast Receiver Sample Application</title>
    <script src="//www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js"></script>
    <script src="../release/THEOplayer-cast-receiver.js"></script>
    <link rel="stylesheet" type="text/css" href="../release/ui.css" />
    <style>
      .THEO-cast-receiver-player .THEO-cast-receiver-logo {
        position: static;
        margin: 0 auto;
        width: 100%;
        height: 100%;
        background:
          url('...') no-repeat,
          no-repeat center;
        background-size: cover;
      }

      .THEO-cast-receiver-player .THEO-cast-receiver-watermark {
        width: 124px;
        height: 65px;
        background-image: url('...');
      }
    </style>
  </head>
  <body>
    <div id="my-player"></div>
    <script>
      var player = new THEOplayer.Player(document.getElementById('my-player'), {
        libraryLocation: '../release/',
      });
    </script>
  </body>
</html>
```

## Publish the application

Before you can deploy your application, you should upload your web project to an HTTPS location. (e.g. [https://cdn.your-website.com/cast/chromecast/sample-project/)](https://cdn.your-website.com/cast/chromecast/sample-project/)) Ensure that your folder structure respects the aforementioned structure.

## Deploy the application

This has to be done through the [Google Cast SDK Developer Console](https://developers.google.com/cast/docs/registration)

Your Chromecast Receiver sample application is now in a state where it can be deployed as a real application. If you have a Google Cast SDK Developer Console, you can log in to <https://cast.google.com/u/1/publish/#/overview>.

![](/pr-932/assets/images/image2018-5-25_15-31-6-f47e2f0c62571237adcdd11a2395b28d.png)

![](/pr-932/assets/images/image2018-5-25_15-31-19-7317abb73b4c3cb9e2e6ebdd98181107.png)

![](/pr-932/assets/images/image2018-5-25_15-31-26-cb0e373616c71ae98bf52259fe449ad6.png)

You have to go through the following steps:

1. Click "ADD NEW APPLICATION".
2. Select "Customer Receiver".
3. Enter information and refer to the HTTPS location of your web project.
4. Press start and wait.

## Test it

Once your application is published, you can start casting from your THEOplayer Web SDK, iOS SDK or Android SDK. You need to set the correct [appID](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/CastConfiguration), enable Chromecast and press the Chromecast icon. Additionally, you can start casting through the [Cast API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/GlobalCast).

## Related articles

* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)
* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/how-to-configure-to-a-different-stream.md)
* [Chromecast on my webplayer does not work any longer despite no change in my implementation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/chromecast-on-weblayer-does-not-longer-work.md)
* [Connecting from custom Sender applications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/connecting-from-custom-sender-applications.md)

---

# Chromecast Application Customization

This article provides information on how to customize the look and feel of a Chromecast [Sender application](https://developers.google.com/cast/glossary#sender) or a Chromecast [Receiver Application](https://developers.google.com/cast/glossary#receiver). ![Casting approaches](/pr-932/assets/images/casting-approaches-45dc2983f20d11409d27d3248b57a6ef.png "Casting approaches")

## Background

This section provides background information on Google, THEOplayer SDKs, Sender apps and Receiver apps. Feel free to skip directly to the sections on [Customizing a Sender Application](#customizing-a-sender-application) or [Customizing a Receiver application](#customizing-a-receiver-application) if you are already familiar with these background topics.

### Google, Chromecast and THEOplayer

Google's point of entry to Chromecast is located at <https://developers.google.com/cast/docs/developers>. In this article, they write about sender applications and their three Cast APIs, and about receiver applications and their four options.

#### Sender applications

Google describes three Cast APIs: the Android API, the iOS API and the Web Sender API. The THEOplayer SDKs integrate these Cast APIs and expose a wrapper API for developers to use instead.

1. The THEOplayer Android SDK implements the [Android API](https://developers.google.com/android/reference/com/google/android/gms/cast/package-summary).
2. The THEOplayer iOS SDK implements the [iOS API](https://developers.google.com/cast/docs/reference/ios).
3. The THEOplayer Web SDK implements the [Web Sender API](https://developers.google.com/cast/docs/reference/web_sender).

#### Receiver applications

Google describes four types of receiver applications:

1. [Default Media Receiver](https://developers.google.com/cast/docs/web_receiver#default_media_web_receiver)
2. [Styled Media Receiver](https://developers.google.com/cast/docs/styled_receiver)
3. [Custom Receiver](https://developers.google.com/cast/docs/web_receiver#custom_web_receiver)
4. [Android TV Receiver](https://developers.google.com/cast/docs/android_tv_receiver)

The THEOplayer Chromecast Receiver SDK fits in the category of a "Custom Receiver". You integrate this THEOplayer SDK in your HTML5 Chromecast Receiver application.

### Sender application vs Receiver application

When talking about customizing a Chromecast application, one needs to make a distinction between customizing [a Sender application versus a Receiver application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/introduction.md).

A **Chromecast Sender application** is the application on a "sender device" (e.g. smartphone, browser, ...) which initiates the Chromecast session. You use the Sender application to start (and stop) Chromecast playback, to pause the video or to mute it, to seek to a different position in the scrub bar, and so on. The unique UI components related to Chromecast in a Sender application are limited to a Chromecast button which starts/stops a Chromecast session. The default controls (e.g. play, pause, scrub bar) are used to control the Receiver application.

**In a Sender application, you use either the THEOplayer [Web](https://www.theoplayer.com/sdk/html5), [iOS](https://www.theoplayer.com/sdk/ios) or [Android](https://www.theoplayer.com/sdk/android) SDK.**

A **Chromecast Receiver application** is the application which is loaded on your Chromecast-enabled device (e.g. Chromecast Ultra, Android TV, ...). The UI of a Receiver application is typically quite simple:

1. When a video is playing, the video is playing fullscreen without any elements overlaying it.
2. When a video is paused, there is timeline indicating the playhead position and an element (e.g. a pause button) indicating that the playback is paused. Sometimes, when a video is paused, a poster image (i.e. thumbnail) and some text are shown to describe the active content.
3. When an app and/or stream starts to load, you might see a brand logo and/or a spinning wheel.

**In a Receiver application, you use the THEOplayer [Chromecast Receiver SDK](https://www.theoplayer.com/sdk/chromecast).**

## Customizing a Sender application

*If you are using the THEOplayer Web, iOS or Android SDK in your Sender application, confirm that the `chromecast` [module is enabled](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/theoplayer-features-modules.md) for your SDK. This feature exposes a Chromecast API you can benefit from. Additionally, ensure that you [include the Chromecast library](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/enable-chromecast-on-the-sender.md).*

*Please refer to ["Connecting from custom Sender applications"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/connecting-from-custom-sender-applications.md) if you are not using THEOplayer's `chromecast` feature.*

Generally speaking, there are three types of user interfaces:

1. Default UI: you use THEOplayer's default UI, and you're happy with it.
2. Chromeless UI: you've build a Chromeless UI from scratch on top of THEOplayer.
3. Altering Default UI: you use THEOplayer's default UI, but you've changed some things around. (e.g. different colors, a new button, ....)

### Default UI

THEOplayer automatically inserts a Chromecast button in its default video player UI if you are using THEOplayer's default UI. ![Chromecast button](/pr-932/assets/images/chromecast-active-53e1680cf7234d5d0c029e99356dd548.png "Chromecast button") The UI of this button changes when the [Chromecast state](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/CastState) changes. Please see below if you want to alter this default UI.

### Chromeless UI

You are in charge of all UI components if you are using THEOplayer's Chromeless UI. Typically, you want to insert a Chromecast button, and connect that button with our Cast API to start (e.g. `player.cast.chromecast.start()`) and stop (`player.cast.chromecast.stop()`) a Chromecast session. Additionally, you might want to change the appearance of this button when the state of your casting session transitions (e.g. `player.cast.chromecast.addEventListener('statechange', function() {...});`).

* Web: [Chromecast API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Chromecast), [Cast API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VendorCast), [Cast Events API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/VendorCastEventMap)
* iOS: [Chromecast API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/Protocols/Chromecast), [Chromecast Events API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios/ChromeCast%20Events#/s:13THEOplayerSDK16StateChangeEventC)
* Android: [Chromecast API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/cast/chromecast/Chromecast), [Chromecast Events API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android/com/theoplayer/android/api/event/chromecast/CastStateChangeEvent)

Familiarize yourself with the above APIs if you want to change the appearance of your Chromeless UI and its relation to Chromecast.

### Altering Default UI

If you are using THEOplayer's default UI, but want to use your own button instead, then you can hide THEO's default button, and [insert a new one](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/insert-a-button.md) instead. You also need to use our Cast API described in the above "Chromeless UI" section.

## Customizing a Receiver application

[Three Receiver application set-ups](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/introduction.md) are common:

1. You connect with THEOplayer's default Receiver application.
2. You connect with a custom Receiver application powered by the THEOplayer Chromecast Receiver SDK.
3. You connect with a custom Receiver application which doesn't contain any THEOplayer SDK or code.

You can provide Chromecast metadata in all three set-ups. Providing [Chromecast metadata](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/SourceDescription#metadata) will make your Receiver application show relevant info (e.g. a title, a thumbnail, ...) when your application is buffering or paused.

### Default Receiver application

If you are connected to OptiView Player's default Receiver application, you cannot modify its appearance. It is an application with OptiView Player functionality that uses Shaka for media playback.

If you want to change the UI, you need to [connect your sender application with a different Receiver application ID](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/connecting-from-custom-sender-applications.md). Also if you need to use Google's legacy Media Player Library (MPL) for playback, you will need to change the Receiver application ID to `44BAE7D1`.

### Custom Receiver application with THEOplayer Chromecast SDK

You can build a custom Receiver application by using our [Chromecast Receiver SDK](https://www.theoplayer.com/sdk/chromecast). Once you went through its [Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md), you'll notice that the UI is similar to the default UI. However, through this approach, you have the option to alter the UI as described by the [Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md#optional-alter-default-ui).

### Custom Receiver application without THEOplayer Chromecast SDK

You can [connect your sender application with a custom Receiver application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/connecting-from-custom-sender-applications.md) which does not use the THEOplayer Chromecast SDK. Naturally, you're responsible for the look and feel of this custom Receiver application.

## Conclusion

Identify whether you want to adjust the UI and UX of the Sender application or the Receiver application.

* If it's the Sender application, determine whether you are changing a Sender app which leverages the THEOplayer Web, iOS or Android SDK to enable casting.
* If it's the Receiver application, determine whether you are changing our default Receiver application, a custom Receiver application using the THEOplayer Chromecast SDK or 3) a custom Receiver application which is not using the THEOplayer Chromecast.

Then, decide which states and which components you want to customize. Finally, identify which THEOplayer APIs are relevant for your use-cases.

## Notes

* Google describes their Chromecast UX guidelines at <https://developers.google.com/cast/docs/ux_guidelines/>.
* This article is currently categorized under the "Getting Started" guides of our Chromecast SDK, which is also known as our Chromecast Receiver SDK. Naturally: you leverage a Chromecast Receiver SDK in a Chromecast Receiver application. In result, this categorization might be confusing to some readers, because we have discussed concepts and APIs which relate to a Sender application. However, we do feel that it's valuable to discuss the bigger picture surrounding a Chromecast Receiver SDK, and that includes its relationship with a Sender application, and how to customize both.

## Resources

* [Getting started on Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/chromecast/getting-started.md). This article contains sample code. Note that the THEOplayer Chromecast SDK also contains a sample Receiver application.
* [Enable Chromecast on the Sender](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/enable-chromecast-on-the-sender.md)
* [Chromecast Introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/introduction.md)
* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/how-to-configure-to-a-different-stream.md)

---

# OptiView Player Roku SDK

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

Dolby OptiView Player is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/roku/getting-started.md)

[Set up your first THEOplayer in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/roku/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku.md)

## [🎨UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/roku.md)

[Use Roku native controls or build a SceneGraph interface from scratch.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/roku.md)

## [🔌Connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/roku.md)

[Integrate third-party solutions with THEOplayer using our pre-built connectors.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/roku.md)

## [\*️⃣API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/api-reference/roku.md)

[Discover all properties and functions of THEOplayer.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/api-reference/roku.md)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

# Player API

The attributes, methods and events.

## Enums

| Name          | Type               | Description                                                       |
| ------------- | ------------------ | ----------------------------------------------------------------- |
| ErrorCategory | roAssociativeArray | Provides a dictionary of Error category names and integer values. |
| ErrorCode     | roAssociativeArray | Provides a dictionary of Error code names and integer values.     |
| Event         | roAssociativeArray | Provides a dictionary of Event type names and string values.      |

## Attributes

| Name                         | Type                           | Default | Access Permission | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ---------------------------- | ------------------------------ | ------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ads                          | Ads                            | Ads     | read              | Provides events, properties and methods relating to ad playback in the player. See below for more info.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| audioTracks                  | roArray of roAssociativeArrays | \[]     | read              | Provides information about audio tracks detected automatically in video. Each Associative array has the following fields: id - track identifier, label - track name, language - track language, enabled - true if track is current track                                                                                                                                                                                                                                                                                                                   |
| autoplay                     | boolean                        | false   | read,write        | Whether the player should play the video as soon as it is able after the source has been set.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| controls                     | boolean                        | true    | read,write        | Allows to enable or disable player controls (`true` to show controls, `false` to hide controls).                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| currentTime                  | integer                        |         | read,write        | Current timestamp of video.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| duration                     | integer                        |         | read              | Duration of video.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| enableTrickPlay              | boolean                        | true    | read,write        | Whether trick playback of the media is enabled, and whether the remote buttons will allow trickplay. NOTE: `controls` must be set to `true` for this to have any effect.                                                                                                                                                                                                                                                                                                                                                                                   |
| subtitleSelectionPreferences | roAssociativeArray             |         | write             | The significance and priority order of the attributes and values for the subtitle tracks available in the video stream. The selected subtitle track is reflected in the `textTracks` with `mode` as "showing" when visible in full screen or "hidden" when not in full screen. Refer to `subtitleSelectionPreferences` section of Roku's [video node](https://developer.roku.com/en-au/docs/references/scenegraph/media-playback-nodes/video.md) documentation. To select a subtitle track, based on user input, use the `mode` field of the `textTracks`. |
| ended                        | boolean                        | false   | read              | Whether playback of the media is ended.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| errorObject                  | roAssociativeArray             |         | read              | The last error that occurred for the current source, if any.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| loop                         | boolean                        | false   | read,write        | Whether playback of the media is looped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| muted                        | boolean                        | false   | read,write        | Set `true` to mute and `false` to un-mute the currently playing video                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| network                      | NetworkApi                     |         | read              | API node for network operations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| paused                       | boolean                        | true    | read              | Whether the player is paused.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| poster                       | string                         |         | read,write        | The poster of the current source.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| seeking                      | boolean                        |         | read              | `true` when player is seeking, `false` when player is not seeking now.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| source                       | Source Description             |         | read,write        | Describes source of current video.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| src                          | string                         |         | read              | The current URL of the media resource.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| theolive                     | THEOlive API                   |         | read              | API node for THEOlive operations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| textTracks                   | roArray of roAssociativeArrays | \[]     | read,write        | Provides information about text and metadata tracks detected automatically in video. Each Associative array has the following fields: id - track identifier, label - track description, language - track language, mode - determines track state, available values: disabled, showing, hidden, activeCues: the current cue for this track                                                                                                                                                                                                                  |
| version                      | string                         |         | read              | The version of the THEOplayer Roku SDK.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

### Source Description

The following key/value pairs are supported on the `source` attribute of the `THEOsdk:THEOplayer` :

| Name                | Type                                    | Description                                                                                                                                                                                                                                                                                                                                    |
| ------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sources             | roArray or roAssociativeArray or string | A Typed Source or an array of Typed Sources or URLs or a URL. When specifying multiple source descriptions, the `sources` attribute will be interpreted as a playlist where the first typed source will play first and subsequent sources will play when its preceding typed source has ended.                                                 |
| title               | string                                  | The title of the media resource.                                                                                                                                                                                                                                                                                                               |
| description         | string                                  | The description of the media resource.                                                                                                                                                                                                                                                                                                         |
| poster              | string                                  | The URL of an image to optionally use as the poster for the media source. This is used for SDPosterUrl, HDPosterUrl, and FHDPosterUrl.                                                                                                                                                                                                         |
| live                | boolean                                 | Whether the asset is live or not.                                                                                                                                                                                                                                                                                                              |
| drmHttpAgentHeaders | roAssociativeArray                      | *Deprecated* Optional. A key-value dictionary that contains additional HTTP headers that will be sent for DRM key/license requests. The keys represent the HTTP header names and the values represent their corresponding values. Use either `contentProtection.drmHeaders` or the `headers` property of the Key System Configuration instead. |
| ads                 | roArray                                 | An optional array of AdDescriptions.                                                                                                                                                                                                                                                                                                           |
| headers             | roArray                                 | An optional array of strings representing headers to include on the content requests. The strings follow the format of `"headerName:headerValue"`. Defaults to an empty array to clear any headers that were set on HttpAgent.                                                                                                                 |
| streamType          | string                                  | Optional. Whether the stream is `"vod"`, `"live"`, or `"dvr"`. Will override `live` if set.                                                                                                                                                                                                                                                    |
| textTracks          | roArray of TextTrackDescriptions        | Optional. An array of descriptions representing external text track files. If specified at this level, it will be applied to all sources in the `sources` array                                                                                                                                                                                |
| cmcd                | CmcdSourceConfiguration                 | Optional. CMCD configuration for this source. Overrides player-level CMCD configuration. See [CMCD Configuration](#cmcd-configuration).                                                                                                                                                                                                        |

### Typed Source

The following key/value pairs are supported on the `sources` attribute of a Source Description:

| Name              | Type                             | Description                                                                                                                            |
| ----------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| src               | string                           | The URL of the media resource.                                                                                                         |
| type              | string                           | The content type (MIME type) of the media resource. Possible values are `application/dash+xml`, `application/x-mpegURL` and `theolive` |
| playStart         | number                           | The position in the stream the user starts playback at. Use negative numbers to offset from the live edge.                             |
| contentProtection | Content Protection               | Parameters for DRM playback                                                                                                            |
| SDBifUrl          | string                           | "Base Index Frames" URL for SD trick mode.                                                                                             |
| HDBifUrl          | string                           | "Base Index Frames" URL for HD trick mode.                                                                                             |
| FHDBifUrl         | string                           | "Base Index Frames" URL for FHD trick mode.                                                                                            |
| ads               | roArray of AdDescriptions        | Array of the ad description for the ads to play during the content.                                                                    |
| profile           | string                           | Optional. The profile to use when making the discovery call for THEOlive streams.                                                      |
| ssai              | GoogleDaiConfiguration           | Optional. The configuration for playing this as a dynamic ad insertion asset.                                                          |
| embeddedTextTrack | string                           | Name of the embedded text track in the asset. Not necessary if the track is explicitly defined in the manifest.                        |
| textTracks        | roArray of TextTrackDescriptions | Optional. An array of descriptions representing external text track files.                                                             |

"Base Index Frames" or BIF, is an archive file format that contains a set of still images, also known as "trick play thumbnails", supporting enhanced fast-forward and rewind modes during video playback.

### Text Track Descriptions

| Name    | Type    | Description                                                                                                                           |
| ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| default | boolean | Optional. Is this the default text track. If true and no track is currently selected, this will be used over the Roku system default. |
| format  | string  | Optional. The format of the text track. Valid values are "ttml" and "webvtt". Use "ttml" for SMPTE-TT files.                          |
| kind    | string  | Optional. The kind of text track. Supported values are "captions" and "subtitles".                                                    |
| label   | string  | Optional. The label to show in menus for the text track.                                                                              |
| src     | string  | The URL for the text track file.                                                                                                      |
| srclang | string  | Optional. The language used in the text track. Can be the language name or an ISO 2 or 3 letter abbreviation.                         |

See [Roku's caption support guide](https://developer.roku.com/docs/developer-program/media-playback/closed-caption.md#closed-caption-support-summary) for what is supported for different stream and text track combinations.

### Ad Descriptions

| Name            | Type               | Description                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sources         | AdSource or string | Either an AdSource or the URL of the ad XML to load.                                                                                                                                                                                                                                                                                                                                                                       |
| integration     | string             | The kind of ad integration this uses. Supported values are `csai`, `google-dai`, `theoads`, and `mediakind`.                                                                                                                                                                                                                                                                                                               |
| timeOffset      | string or number   | An optional value determining when to show the ad. It can either be the number of seconds representing the timecode in the video when the ad should play, or it can be `start` or `end` to play the ad either before or after the video. Additionally it could be a percent of the content's duration, like `25%`, or a timecode in the format `HH:MM:SS`. NOTE: This is for VAST ads only. Do not use this with VMAP ads. |
| replaceContent  | boolean            | An optional value for whether this ad tag should replace content when the ad plays. Valid only for midrolls. Defaults to false.                                                                                                                                                                                                                                                                                            |
| adTagParameters | roAssociativeArray | Optional. Map of ad tag parameters configurable for ad targeting. Used for SSAI ad configurations.                                                                                                                                                                                                                                                                                                                         |

NOTE: when scheduling ads, VAST ads cannot be scheduled in the middle of the time covered by a VMAP ad tag. For instance, if you have a VMAP preroll and postroll in a single ad tag, you could not schedule midrolls in between them. However, if you had separate VMAP preroll and postroll tags, you could place a VAST midroll tag in between the two.

#### Ad Sources

| Name | Type   | Description                                                                                                                                                        |
| ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| src  | string | The URL of the XML file to load for the ad break.                                                                                                                  |
| type | string | The optional type of the ad. Supported values are either `vast` or `vmap`. Otherwise the default value is inferred from the AdDescription's `timeOffset` property. |

### SSAI/DAI Configuration

The player supports Dynamic Ad Insertion (DAI) using Google DAI. This integration currently supports doing Server Side Ad Insertion (SSAI) on live streams. To enable this, add the `ssai` property to your source with your Google DAI information. You can listen for ad events emitted by Google DAI on the Ads API.

The following key/value pairs are supported on the `ssai` attribute of a Typed Source:

| Name             | Type               | Description                                                                      |
| ---------------- | ------------------ | -------------------------------------------------------------------------------- |
| integration      | string             | The type of DAI integration. The supported values are "google-dai" or "theoads". |
| apiKey           | string             | The API key for your DAI account.                                                |
| availabilityType | string             | The type of asset you are playing ("live" or "vod").                             |
| networkCode      | string             | The network code for your DAI account.                                           |
| assetKey         | string             | Optional. The asset key for your live asset. Not required for VOD assets.        |
| adTagParameters  | roAssociativeArray | Optional. Map of ad tag parameters configurable for ad targeting.                |

NOTE: It is not supported to use SSAI through this API at the same time as Client-side Ad Insertion (CSAI) through the Ad Sources configuration.

### Content Protection

The following key/value pairs are supported on the `contentProtection` attribute of a Typed Source:

| Name                | Type               | Description                                                                                                                                                                                                                                                              |
| ------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| integration         | string             | Optional. The type of DRM integration this is. Previously, this was the key system the player should use ("widevine" or "playready"). That is a deprecated usage, but currently supported. Ignored if the `drmParams` property is used.                                  |
| licenseUrl          | string             | *Deprecated* The license acquisition URL. Use either `contentProtection.widevine.licenseAcquisitionURL` or `contentProtection.playready.licenseAcquisitionURL` instead.                                                                                                  |
| certificate         | string             | *Deprecated* The actual certificate string for Widevine purposes, which must be obtained out-of-band (OOB) by the channel. Use `contentProtection.widevine.certificate` instead.                                                                                         |
| drmParams           | DRM Parameters     | Optional. An alternative way to set parameters for DRM playback that maps to the Roku Content Node's `drmParams` property. *If specified, this is used over the `integration` route.*                                                                                    |
| drmHeaders          | roAssociativeArray | Optional. A key-value dictionary that contains additional HTTP headers that will be sent for DRM key/license requests. The keys represent the HTTP header names and the values represent their corresponding values. This should only be used together with `drmParams`. |
| widevine            | Key System Config  | Optional. The configuration for Widevine DRM for this source. If both `widevine` and `playready` are specified, the order specified in `preferredKeySystems` will be used.                                                                                               |
| playready           | Key System Config  | Optional. The configuration for Playready DRM for this source. If both `widevine` and `playready` are specified, the order specified in `preferredKeySystems` will be used.                                                                                              |
| preferredKeySystems | Array of strings   | Optional. The preferred key systems to use. The key systems will be tried in the order specified. If not specified, `widevine` will be preferred over `playready`.                                                                                                       |

NOTE: PlayReady is not supported with HLS streams on Roku, so even if set to be preferred, it will be ignored for HLS streams.

### Key System Config

The following key/value pairs are supported on the `widevine` and `playready` attributes of the `contentProtection` configuration:

| Name                  | Type               | Description                                                                                                                                                                                                          |
| --------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| licenseAcquisitionURL | string             | The license acquisition URL.                                                                                                                                                                                         |
| certificate           | string             | Optional. The actual certificate string for Widevine purposes, which must be obtained out-of-band (OOB) by the channel. It can be either base64 or hex encoded.                                                      |
| headers               | roAssociativeArray | Optional. A key-value dictionary that contains additional HTTP headers that will be sent for DRM key/license requests. The keys represent the HTTP header names and the values represent their corresponding values. |

### DRM Today Configuration

A `DRMTodayDRMConfiguration` extends Content Protection with the following properties. Set `integration` to `"drmtoday"` to enable this behavior.

| Name      | Type   | Description                                                                                  |
| --------- | ------ | -------------------------------------------------------------------------------------------- |
| merchant  | string | Optional. The DRM Today merchant identifier used to generate license-request custom data.    |
| userId    | string | Optional. The DRM Today user identifier included in generated custom data when non-empty.    |
| sessionId | string | Optional. The DRM Today session identifier included in generated custom data when non-empty. |

When a non-empty `merchant` and a Widevine configuration are supplied without an existing DRM Today authentication header, the SDK adds an `x-dt-custom-data` header containing base64-encoded JSON with the merchant and optional user/session identifiers. Existing `x-dt-auth-token`, `x-dt-custom-data`, and `dt-custom-data` headers take precedence and are not replaced. Other configured headers are preserved.

The Widevine license URL is updated with `specConform=true` so Roku's native CDM receives an unwrapped license response. To use DRM Today's token authentication, provide `x-dt-auth-token` through `contentProtection.widevine.headers`; Roku does not expose a separate `token` property.

```brightscript
drmTodaySource = {
  sources: {
    src: "https://example.com/stream.m3u8",
    type: "application/x-mpegurl",
    contentProtection: {
      integration: "drmtoday",
      merchant: "your-merchant-id",
      userId: "your-user-id",
      sessionId: "your-session-id",
      widevine: {
        licenseAcquisitionURL: "https://lic.drmtoday.com/license-proxy-widevine/cenc/"
      }
    }
  }
}
```

**Example DRM source with VuDRM specific headers**

To play videos protected using VUDRM, you need to supply a token. Replace the token `vualto-demo|2018-06-19T09:18:24Z|YSnJPmEceo` in the code below with your own token as well as the associated values of the keys `src` and `licenseUrl`.

```brightscript
vuDrmSource = {
  sources: [
    {
      src: "https://d1chyo78gdexn4.cloudfront.net/vualto-demo/big-buck-bunny/big-buck-bunny.ism/manifest.mpd",
      type: "application/dash+xml",
      contentProtection: {
        integration: "vudrm",
        widevine: {
          licenseAcquisitionURL: "https://widevine-proxy.drm.technology/proxy"
        }
      }
    }
  ]
  drmHttpAgentHeaders: {
    "x-vudrm-token": "vualto-demo|2018-06-19T09:18:24Z|YSnJPmEceo",
    "Content-Type": "application/json"
  }
}
```

### DRM Parameters

The `drmParams` attribute of the `contentProtection` is an associative array that represents the `drmParams` property of the Roku Content Node metadata. For a full list of the available properties and which versions of Roku they are available for, please visit [the Roku documentation for `drmParams`](https://developer.roku.com/docs/developer-program/getting-started/architecture/content-metadata.md#digital-rights-management-drm-control-attributes). The following key/value pairs have been available for a while on the `drmParams` attribute. Note that, unlike most properties in BrightScript, *these property names are case sensitive*:

| Name             | Type   | Description                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| keySystem        | string | Can be set to either "playready" or "widevine".                                                                                                                                                                                                                                                                                                                                |
| licenseRenewURL  | string | Optional. A URL location for sending license renewal requests. If not specified, the Roku OS will send renewal requests to the URL specified in the licenseServerURL. This only works with Widevine.                                                                                                                                                                           |
| licenseServerURL | string | A URL location of a license server. This URL may include CGI parameters.                                                                                                                                                                                                                                                                                                       |
| serializationURL | string | Optional. A server address used for device provisioning.                                                                                                                                                                                                                                                                                                                       |
| serviceCert      | string | Optional. The actual certificate string for Widevine purposes, which must be obtained out-of-band (OOB) by the channel. Leave this unset unless Widevine is used for DRM. If used, this must be hex-encoded.                                                                                                                                                                   |
| lic\_acq\_window | string | Optional. The maximum amount of time (in milliseconds) that a channel waits before rotating its Widevine DRM keys. The channel can generate a random wait time between 0 and the value specified in the **lic\_acq\_window** field, and use the random wait time to instruct when the Video node should make its next Widevine license request. *Available since Roku OS 10.5* |

### Ads API

The Ads API exposes the following properties, methods, and events.

| Property          | Type                           | Access Permission | Description                                                                                                   |
| ----------------- | ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------- |
| currentAdBreak    | AdBreak                        | read              | The current AdBreak if ads are playing, or invalid if they are not playing.                                   |
| currentAds        | roArray of Ads                 | read              | Array of the current Ads in the current AdBreak, or invalid if ads are not playing.                           |
| dai               | DAI API                        | read              | API exposing some methods for SSAI playback.                                                                  |
| events            | roAssociativeArray             | read              | Map of the event types the Ads API will emit.                                                                 |
| playing           | boolean                        | read              | Whether an ad is currently playing.                                                                           |
| rafProxy          | RafProxyNode                   | read              | roSGNode that exposes data from the internal RAF library.                                                     |
| scheduledAdBreaks | roArray of roAssociativeArrays | read              | Array of the scheduled breaks that haven't played. These may either be a source object or a resolved AdBreak. |
| scheduledAds      | roArray of Ads                 | read              | Array of the ads that are scheduled and have not played. Only shows one break's ads with VAST.                |

| Method                                                                                       | Description                                                                                                |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| addEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string)    | Add a listener for the specified player event.                                                             |
| removeEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string) | Remove a listener for the specified player event.                                                          |
| schedule(adDescription as AdDescription, sourceDescription as roAssociativeArray)            | Schedule an ad break. Optionally, pass a source description for use in custom server-side ad integrations. |

| Event            | Class        | Description                                                   |
| ---------------- | ------------ | ------------------------------------------------------------- |
| adbegin          | AdEvent      | The current creative has begun playing.                       |
| adbreakbegin     | AdBreakEvent | The player is entering an ad break.                           |
| adbreakend       | AdBreakEvent | The player is exiting an ad break.                            |
| adbuffering      | AdEvent      | The current ad is buffering during playback.                  |
| addadbreak       | AdBreakEvent | An ad break has been manually added.                          |
| adend            | AdEvent      | The current ad has completed playing.                         |
| aderror          | Event        | There was an error loading or playing an ad.                  |
| adexitrequested  | Event        | The user pressed the back button while a CSAI ad was playing. |
| adfirstquartile  | AdEvent      | The viewer has watched the first quartile of the current ad.  |
| adimpression     | AdEvent      | The ad has begun playing.                                     |
| adloaded         | Event        | The XML for an ad has been loaded.                            |
| admidpoint       | AdEvent      | The viewer has watched the half of the current ad.            |
| adsmanagerloaded | Event        | When the RAF ad manager has been initialized.                 |
| adthirdquartile  | AdEvent      | The viewer has watched the third quartile of the current ad.  |

NOTE: when playing CSAI ads, if the user presses the back button on the remote, the back button press will not be captured by `onKeyEvent` listeners. To allow your application to handle this back button press, the application should listen for the `adexitrequested` event on the Ads API and handle the exit logic there. Otherwise, it takes a second back button press to exit the player.

#### AdEvent and AdBreakEvent

The AdEvent is an event object with the follow properties:

| Property | Type    | Description                                                                 |
| -------- | ------- | --------------------------------------------------------------------------- |
| type     | string  | The current AdBreak if ads are playing, or invalid if they are not playing. |
| date     | integer | The current epoch time in milliseconds.                                     |
| ad       | Ad      | The ad associated with the event.                                           |

The AdBreakEvent exposes the same properties as the AdEvent, but adds in a property with the current ad break:

| Event   | Class   | Description                        |
| ------- | ------- | ---------------------------------- |
| adBreak | AdBreak | The ad break the event relates to. |

#### AdBreak

The AdBreak object is an associative array that can have the following properties:

| Property    | Type               | Description                                                                                                          |
| ----------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| ads         | roArray            | An array containing the Ads in the AdBreak.                                                                          |
| customData  | roAssociativeArray | An associative array with any additional information for this ad break.                                              |
| id          | string             | The identifier of the ad break. For Google DAI, this is the pod index of the ad break.                               |
| integration | string             | The integration that generated the AdBreak. Currently the only supported value is `csai`.                            |
| maxDuration | integer            | The length of the break in seconds.                                                                                  |
| timeOffset  | integer            | The time in the video at which the ad break should play, in seconds. 0 indicates preroll, and -1 indicates postroll. |

The Ad object is an associative array that can have the following properties:

| Property     | Type               | Description                                                                          |
| ------------ | ------------------ | ------------------------------------------------------------------------------------ |
| adBreak      | AdBreak            | The AdBreak this Ad belongs to.                                                      |
| adSystem     | string             | The ad system used to load this ad.                                                  |
| clickThrough | string             | The clickthrough URL for this ad.                                                    |
| companions   | roArray            | An array of any CompanionAds associated with this ad.                                |
| creativeId   | string             | The creative ID for this ad.                                                         |
| customData   | roAssociativeArray | An associative array with any additional information for this ad.                    |
| duration     | integer            | The duration of this ad.                                                             |
| height       | integer            | The height of the creative for this ad.                                              |
| id           | string             | The ad ID for this ad.                                                               |
| integration  | string             | The integration that generated the ad. Currently the only supported value is `csai`. |
| resourceUri  | string             | The URI for the creative played in this Ad.                                          |
| type         | string             | The type of ad. Currently only `linear` is supported.                                |
| width        | integer            | The width of the creative for this ad.                                               |

The CompanionAd object is an associative array that can have the following properties:

| Property     | Type    | Description                                         |
| ------------ | ------- | --------------------------------------------------- |
| adSlotId     | string  | The ad slot id for this companion ad, if any.       |
| clickthrough | string  | The clickthrough URL for this companion ad, if any. |
| height       | integer | The height of the creative.                         |
| resourceUri  | string  | The URI of the creative.                            |
| provider     | string  | The provider of the companion ad, if any.           |
| width        | integer | The width of the creative.                          |

#### RafProxyNode

The RAF proxy node has several fields that can be observed to consume data generated by the internal RAF library. This way, an application can access information traditionally available via the `getLibVersion`, `setRafTrackingCallback` and `setAdBufferRenderCallback` methods on RAF. You can also set some content metadata on RAF by calling the methods on the proxy node.

| Property           | Type               | Access Permission | Description                                                               |
| ------------------ | ------------------ | ----------------- | ------------------------------------------------------------------------- |
| bufferRenderUpdate | roAssociativeArray | read              | An associative array with the properties `adUrl`, `eventType`, and `ctx`. |
| libVersion         | string             | read              | The string indicating the version of the RAF library.                     |
| trackingUpdate     | roAssociativeArray | read              | An associative array with the properties `adUrl`, `eventType`, and `ctx`. |

| Method                                                    | Description                                                                                                                                                                                 |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| setContentGenre(genres as string, kidsContent as boolean) | Set the content genre and whether the content is for kids on RAF. Equivalent to calling `Roku_Ads().setContentGenre(genres, kidsContent)`.                                                  |
| setContentId(id as string)                                | Set the content ID on RAF. Equivalent to calling `Roku_Ads().setContentId(id)`.                                                                                                             |
| setContentLength(length as integer)                       | Set the content length on RAF. Equivalent to calling `Roku_Ads().setContentLength(length)`. The content length for RAF is set automatically to the content duration if not called manually. |

#### DAI API

The DAI API is accessed via `player.ads.dai` and exposes the following methods for Google DAI streams.

| Method                                                                                       | Description                                             |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| addEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string)    | Add a listener for the specified DAI ad event.          |
| removeEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string) | Remove a listener for the specified DAI ad event.       |
| setRafMetadata(contentId, contentGenre, kidsContent, contentLength)                          | Set metadata about the content on RAF for ad targeting. |

##### setRafMetadata

Sets metadata about the playing content on RAF (Roku Advertising Framework) for ad targeting. This should be called before playback begins.

| Parameter     | Type    | Default | Description                            |
| ------------- | ------- | ------- | -------------------------------------- |
| contentId     | string  | —       | The ID of the content that is playing. |
| contentGenre  | string  | ""      | A CSV list of genres for this content. |
| kidsContent   | boolean | false   | Whether this content is aimed at kids. |
| contentLength | integer | 0       | The length of the content in seconds.  |

**Example:**

```brightscript
player.ads.dai@.setRafMetadata("movie-123", "action,adventure", false, 7200)
```

##### Events

The DAI API emits the following ad events, which can be listened to via `addEventListener`. These events are also dispatched through the main Ads API for DAI streams.

| Event            | Class        | Description                                                  |
| ---------------- | ------------ | ------------------------------------------------------------ |
| adbegin          | AdEvent      | The current ad has begun playing.                            |
| adbreakbegin     | AdBreakEvent | The player is entering an ad break.                          |
| adbreakend       | AdBreakEvent | The player is exiting an ad break.                           |
| adend            | AdEvent      | The current ad has completed playing.                        |
| aderror          | Event        | There was an error loading or playing an ad.                 |
| adfirstquartile  | AdEvent      | The viewer has watched the first quartile of the current ad. |
| admidpoint       | AdEvent      | The viewer has watched half of the current ad.               |
| adsmanagerloaded | Event        | The DAI stream manager has been initialized.                 |
| adthirdquartile  | AdEvent      | The viewer has watched the third quartile of the current ad. |

## Methods

| Method                                                                                       | Description                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| addEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string)    | Add a listener for the specified player event.                                                                                                                                     |
| addIntegration(integration as object)                                                        | Adds an Integration.                                                                                                                                                               |
| configure(configuration as THEOPlayerConfiguration)                                          | Configure the SDK, passing in the license (`{license: "MY_THEO_LICENSE"}`).                                                                                                        |
| destroy                                                                                      | Destroy the player.                                                                                                                                                                |
| getVideoNode                                                                                 | Returns the interior Roku video node.                                                                                                                                              |
| pause                                                                                        | Pause playback.                                                                                                                                                                    |
| play                                                                                         | Start playback.                                                                                                                                                                    |
| removeEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string) | Remove the specified listener for the specified player event.                                                                                                                      |
| removeIntegration(integration as object)                                                     | Removes an Integration.                                                                                                                                                            |
| setCopyGuardManagementSystem(cgms as Integer)                                                | Sets Copy Guard Management System. Acceptable Values: `0` - No Copy Restriction,`1` - Copy No More,`2` - Copy Once Allowed,`3` - No Copying Permitted.                             |
| setDestinationRectangle(w as Integer, h as Integer, x as Integer, y as Integer)              | Sets width, height, x, y of player.                                                                                                                                                |
| setMaxVideoResolution(width as Integer, height as Integer)                                   | Sets maximum video resolution.                                                                                                                                                     |
| setPlayerFocus(focused as Boolean, focusReceiver (optional) as roSGNode)                     | Gives or removes the focus from the internal player. If passing `false`, you may pass an optional roSGNode to receive the focus. If not passed, the THEOplayer SDK receives focus. |

### Player Configuration

The PlayerConfiguration object is passed to the configure method. It is an associative array with the following properties:

| Property   | Type               | Description                                                                          |
| ---------- | ------------------ | ------------------------------------------------------------------------------------ |
| license    | string             | Your THEO license. Optional if `licenseUrl` is specified.                            |
| licenseUrl | string             | The URL from which to load your THEO license. Optional if `license` is specified.    |
| theolive   | roAssociativeArray | The configuration for THEOlive. Optional.                                            |
| cmcd       | CmcdConfiguration  | The configuration for CMCD. Optional. See [CMCD Configuration](#cmcd-configuration). |

#### THEOlive Configuration

| Property          | Type               | Description                                                                                                                                                                                                                                                                                                        |
| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| discoveryUrl      | string             | Optional. The discovery URL for your THEOlive deployment. If present, it will be tried before `discoveryUrls`.                                                                                                                                                                                                     |
| discoveryUrls     | roArray of strings | Optional. Array of discovery URLs for your THEOlive deployment, tried in order after `discoveryUrl`. The player always tries its built-in discovery URLs after the configured ones. See [Discovery URLs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/theolive/discovery-urls.md). |
| externalSessionId | string             | A session ID to use for your THEOlive session. This can tie an application session to a THEOlens session.                                                                                                                                                                                                          |

#### CMCD Configuration

The CMCD configuration enables Common Media Client Data reporting. It can be set at the player level (in `PlayerConfiguration.cmcd`) or at the source level (in `SourceDescription.cmcd`). Request mode (CMCD headers on media requests) will be used for all OptiView Live (THEOlive) streams. CMCDv2 events will also be used if `eventEndpoints` is set.

**CmcdConfiguration** (player-level):

| Property          | Type                                 | Description                                          |
| ----------------- | ------------------------------------ | ---------------------------------------------------- |
| externalSessionId | string                               | Optional. External session identifier for CMCD.      |
| userId            | string                               | Optional. User identifier for CMCD reporting.        |
| eventEndpoints    | roArray of CmcdEndpointConfiguration | Optional. Array of endpoints to send CMCD events to. |

**CmcdSourceConfiguration** (source-level, extends CmcdConfiguration):

| Property          | Type                                 | Description                                                                                                                         |
| ----------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| externalSessionId | string                               | Optional. External session identifier for CMCD. This is recommended to use to join request mode and event mode sessions together.   |
| userId            | string                               | Optional. User identifier for CMCD reporting.                                                                                       |
| eventEndpoints    | roArray of CmcdEndpointConfiguration | Optional. Array of endpoints to send CMCD events to.                                                                                |
| sessionId         | string                               | Optional. Session identifier for this source. Only used for CMCDv2 event mode. A Roku-generated ID is used for CMCDv1 request mode. |

**CmcdEndpointConfiguration**:

| Property | Type   | Description                                     |
| -------- | ------ | ----------------------------------------------- |
| url      | string | The URL of the endpoint to send CMCD events to. |

**Merge Behavior**: When CMCD is configured at both the player and source level, the source configuration takes precedence for scalar properties (`externalSessionId`, `userId`, `sessionId`). The `eventEndpoints` arrays from both configurations are combined, with duplicates removed based on URL (source endpoints take priority).

## THEOlive API

The THEOlive API exposes the following property.

| Property  | Type   | Description                                                                                                |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| authToken | string | Optional. The JWT to be included on THEOlive media requests in the Authorization header as a bearer token. |

## Network API

The Network API exposes the following methods.

| Method                                                 | Description                                                                                      |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| setHeader(headerName as string, headerValue as string) | Adds or overwrites a header for all media requests. Returns true if successful, false if not.    |
| removeHeader(headerName as string)                     | Sets the value of the named header to an empty string. Returns true if successful, false if not. |
| getHeaders() as roAssociativeArray                     | Returns a map of all headers currently configured through the network API.                       |

## Events

The event consists of:

* `date`: (string) ISO timestamp for when the event was emitted.
* `type`: (string) of the event.
* Extra properties depending on the event type.

There are several player events being emitted.

* `activequalitychanged`: Fired when the playing rendition changes. The event data includes the rendition's quality.
* `addedaudiotrack`: Fired when audio track has been added. The event data includes the added track.
* `addedtexttrack`: Fired when text track has been added. The event data includes the added track.
* `canplay`: Fired when the player can start playback of the media data. The event data includes the current time.
* `canplaythrough`: DEPRECATED: Fired when the player can finish playback of the media data and buffering is unlikely. The event data includes the current time.
* `currentsourcechange`: Fired when the current source playing on the video node changes. The event data includes the new source.
* `destroy`: Fired when the the player is destroyed. There is no extra data on the event.
* `durationchange`: Fired when the duration changes. The event data includes the duration.
* `emptied`: Fired when the player's source is cleared. There is no extra data on the event.
* `ended`: Fired when playback has stopped because the end of the media resource was reached. The event data includes the current time.
* `error`: Fired when an error occurs. The event data contains an associative array e.g.:
  ```brightscript
  {
      "error": "<string:error>",
      "errorObject": {
          "code": <integer:code>,
          "message": <string:message>
      }
  }
  ```
* `intenttofallback`: Fired when the player has encountered an error playing a THEOlive stream and is going to try to playback a different stream. It also includes data about the error that is triggering fallback.
* `loadeddata`: Fired when the player can render the media data at the current playback position for the first time. The event data includes the current time.
* `loadedmetadata`: Fired when the player determines the duration and dimensions of the media resource. The event data includes the current time.
* `pause`: Fired when the `paused` property changes to `true`. The event data includes the current time.
* `play`: Fired when the `play` method is called. The event data includes the current time.
* `playing`: Fired when playback is ready to start after having been paused or delayed due to lack of media data. The event data includes the current time.
* `endpointloaded`: Fired when the player has loaded the data for a THEOlive source and is ready to begin loading the stream. The event data includes information about the endpoint.
* `distributionloadstart`: Fired when the player begins to load the data for a THEOlive source. The event data includes the distribution ID.
* `distributionloaded`: Fired when a THEOlive distribution has been successfully loaded. The event data includes information about the distribution.
* `distributionoffline`: Fired when a THEOlive stream is not available for playback. The event data includes the distribution ID.
* `seeked`: Fired when the `seeking` property changes to `false` after the current playback position was changed. The event data includes the current time.
* `seeking`: Fired when `seeking` changes to `true`, and the player has started seeking to a new position. The event data includes the current time.
* `sourcechange`: Fired when the player's source changes. The event data is the source as an associative array e.g.:
  ```brightscript
  {
      "source": {
          "sources": [
              {
                  "contentProtection": {
                      "drmParams": {
                          "keySystem": "widevine"
                          "licenseServerURL": "https://example.com/license"
                      }
                  },
                  "src": "https://example.com/stream.mpd",
              }
          ]
      }
  }
  ```
* `timeupdate`: Fired when the current playback position changed as part of normal playback or in an especially interesting way, for example discontinuously. The event data is the currentTime.

### THEOlive Data

The THEOlive events provide additional information about the THEOlive distribution and endpoint. The `distributionloadstart` event has the distribution ID as the `src` property. The `distributionoffline` event has the distribution ID as the `distributionId` property. The `intenttofallback` event contains the reason for the fallback as the `reason` property. However, the other THEOlive events contain more detailed information about the distribution and endpoint.

For the `distributionloaded` event, the following properties are available on the Distribution object:

| Property       | Type                 | Description                                          |
| -------------- | -------------------- | ---------------------------------------------------- |
| deleted        | boolean              | Optional. Whether the distribution has been deleted. |
| endpoints      | roArray of Endpoints | An array of endpoints.                               |
| externalId     | string               | Optional. The distribution's external ID.            |
| id             | string               | The distribution's ID.                               |
| maxBitrate     | integer              | Optional. The maximum bitrate of the distribution.   |
| name           | string               | The distribution's name.                             |
| organizationId | string               | Optional. The organization's THEOlive ID.            |

The `endpointloaded` event comes with the following properties:

| Property       | Type               | Description                                       |
| -------------- | ------------------ | ------------------------------------------------- |
| channelName    | string             | The channel/distribution's name.                  |
| distributionId | string             | The ID used as the `src` for the THEOlive source. |
| endpoint       | roAssociativeArray | The Endpoint that loaded.                         |

The `endpoint` property contains an Endpoint object with the following information:

| Property     | Type   | Description                                                                          |
| ------------ | ------ | ------------------------------------------------------------------------------------ |
| cdn          | string | Optional. The CDN used for this endpoint.                                            |
| provider     | string | Optional. The provider of this endpoint.                                             |
| src          | string | The URL of the stream for this endpoint.                                             |
| srcType      | string | The type of the stream for this endpoint.                                            |
| adSrc        | string | *Deprecated* Optional. The URL for the ad stream. Only for v1/v2 endpoints.          |
| daiAssetKey  | string | *Deprecated* Optional. The DAI identifier for this stream. Only for v1/v2 endpoints. |
| hlsMpegTsSrc | string | *Deprecated* Optional. The HLS MPEG-TS stream URL. Only for v1/v2 endpoints.         |
| hlsSrc       | string | *Deprecated* Optional. The HLS stream URL. Only for v1/v2 endpoints.                 |

# Capabilities API

The THEO SDK now also exposes a couple of helper methods for getting the capabilities of the Roku device. These methods are available on the `Capabilities` object, which can be accessed via `THEOsdk:Capabilities`, separate from the THEOplayer.

The Capabilities object has the following methods

| Method             | Description                                                                          |
| ------------------ | ------------------------------------------------------------------------------------ |
| getWidevineLevel() | Returns an object with information about the Widevine level supported by the device. |
| getHevcSupport()   | Returns an object with information about the HEVC support on the device.             |

The `getWidevineLevel` method returns an object with the following properties:

| Property | Type    | Description                                                                           |
| -------- | ------- | ------------------------------------------------------------------------------------- |
| level    | string  | A string of a number representing the Widevine level supported by the device.         |
| multikey | boolean | A boolean indicating whether the device supports multiple keys.                       |
| tee      | boolean | A boolean indicating whether the device supports Trusted Execution Environment (TEE). |
| version  | string  | A string representing the Widevine version supported by the device.                   |

The `getHevcSupport` method returns an object with the following properties:

| Property              | Type    | Description                                                           |
| --------------------- | ------- | --------------------------------------------------------------------- |
| isSupported           | boolean | A boolean indicating whether the device supports HEVC.                |
| supportsMain10Profile | boolean | A boolean indicating whether the device supports the Main 10 profile. |
| videoMode             | string  | A string representing the video mode supported by the device.         |

Example usage:

```brightscript
m.capabilities = createObject("roSgNode", "THEOsdk:Capabilities")
widevineLevel = m.capabilities.callFunc("getWidevineLevel")
hevcSupport = m.capabilities.callFunc("getHevcSupport")
```

---

# Getting Started on Roku

> **OptiView Rebranding**
>
> OptiView Player is the new name for THEOplayer as part of the OptiView product suite. During the transition, you may still see references to THEOplayer. OptiView Player and THEOplayer refer to the same product.

This getting started guide gets you familiar with Roku and the Dolby OptiView Player Roku SDK. Upon completion of this guide, you'll have integrated the Player SDK in Roku's Hello World! sample project, configured a video, and used an event listener.

If you're looking for our Roku API reference, you can find them [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/api-reference/roku.md).

Consider using the [quickstart guide](#quickstart) if you're looking for a recap because you already went through this article.

## Introduction

The THEOplayer Roku SDK is designed specifically for the Roku platform. It is a custom video component allowing your channel to embed the video player easily.

### Purpose

This guide is created to help you get started with including the THEOplayer Roku SDK inside a Roku channel. This article will show you how to include, load, and create an instance of the THEOplayer Roku SDK. It will also explain how to play a video, and how you can add an event listener.

### Prerequisites

To start this guide you need the following items:

1. A Roku account ([read more about Roku account](https://support.roku.com/en-gb/article/115004382968)) linked with a Roku device ([see how to activate and link a Roku device](https://support.roku.com/en-gb/article/235180868)).

2. A Roku device with development mode activated ([read more about how to enable roku developer mode](https://blog.roku.com/developer/developer-setup-guide)). It is worth mentioning that you need to enroll for a developer program in order to activate the development mode on a Roku device ([you can enroll for a developer program here](https://developer.roku.com/enrollment/standard)).

3. A television/screen which supports an HDMI input.

4. Development workstation with an IDE and a web browser (Firefox, Chrome, Safari etc.).

5. Make sure that the Roku device and workstation are on the same local network (you should be able to ping the Roku device from your workstation).

6. An internet connection.

7. A Roku development environment which is needed to create a sample Roku channel and sideload it to a Roku device ([How to setup a Roku development environment](https://developer.roku.com/en-gb/docs/developer-program/getting-started/developer-setup.md)).

## System requirements

Roku keeps all devices up-to-date by issuing automatic updates. We aim to support all the up to date Roku devices.

## Certification changes

There are certification updates that may affect THEOplayer and channels using THEOplayer. Updates regarding certification are announced two times a year. Every update is announced 6 months before the date of implementation.

After announcing changes, we may need to update the THEOplayer Roku SDK to fulfill these new certification criteria.

## Support Roku OS

Our main focus is to support the two latest versions of Roku OS. Support for older versions might be limited.

# Building your own channel using the THEOplayer SDK

In this section, we will go through the process of creating a Roku channel and using the THEOplayer Roku SDK.

## Starting point

First of all, we need to create a Roku channel. You can either [create a new Roku project in eclipse](https://www.youtube.com/watch?v=suQ0qxFs0jw) or [VS Code](https://rokucommunity.github.io/vscode-brightscript-language/index.html) or start from the [Roku “Hello world” channel example](https://github.com/rokudev/hello-world) (Here is some [extra documentation](https://developer.roku.com/en-gb/docs/developer-program/getting-started/hello-world.md) about the “hello world” example).

When you have created a Roku channel, you can copy the THEOplayer Roku SDK ("THEOplayerSDK.pkg") into the directory of your project. You can download the most recent THEOplayer SDK from <https://portal.theoplayer.com>.

## Project structure:

![Roku Project Structure](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAARkAAAGlCAIAAABBehVOAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAAEnQAABJ0Ad5mH3gAACH2SURBVHhe7Z3xryVXdaXnX4lFLEQsDxmEkkaR0agzjgUOaiABYUAOCcjqZKR2RklLo9c/mCayWzZu23QTt+0mpmMgiaMhCckfOJ9Zysp2Vd269d49995T9y3pU2nXrn32OfXeXu/Uu/1q93/7jd/8rRDC7kRLIbQhWgqhDdFSCG2IlkJoQ7QUQhuipRDaEC2F0IZoKYQ2REshtOEiWvrtz/7ea/ce/eTn/1G5++MPPvO7nx9EhnB5uIiWrjz1v1770U85zniW8OxXvvnOT/9FUsTgdBAwD/FvvP3zc0365P+4wjo144s3bw+utoJZXn79Xd9OnXR+3pdeuT+4Okg14Jvf+QunZezg6ibGs4QmfExLj3/q0/X0E5988rHHn6geQfnef+9DfxdnmNmsqAOSWAmcgq9WqCTqiaoa2BegltH1G2fkWZ5wvqwrNVJfK98ap399647sJcxPSlpLaE8KIe2m70sY8F9a+tJXv/XDe4+euvpFnfIg98rdh89/74YDzHItVbVUcC7fx2q5Ly/9MZN1uTzhfFlXauSOtTg/adVStRsSLS3nv7R07WvPP3j/l28++AVyQkh33nj43ge/+s4LfznemnbX0sw3nurxExFhlJGfA//P//0b27okGfDz+OatOxrFEQ95vEiOZ7fv6mc2x7qkmpyEINsPnMQzliE/ePVtr0ord7BntIdVSQBMxNXJr0CtUds2xqlwDr4yCvOX0TZHvhrcAouvQxzpWcYJdVUehtv2PYYZPvaMx9aEnF679+gHrz5ASJObErhMt1ILt8L3CWwrmG8n3zCXjguRU5z6Xk7aZFD1YzNEeTA0hVbr6bjKXC6OmtAQo8pjlG+BGK/NAYoB/PcffuirWk9Nji3daiBHwpTBtozJVHV2f2W4qmxc1Y0rie5OTt84ftmaZTIhAUpoFFw9YRPDzx4kpxkhAV/0HbXkIjB8F3EOMk9W5NhmrCtGtoujOmXbo4KrCTni1NS6Wgdy6uLD6UWCCm4cOVgG4GSjw6g1alvGplTjrwyR9niIszEEmwzyE687VcA44R89913foHG2sJWhluAL177x9W+/MHBWBt+GGTZpiW/Y4CM4SkHf4EHxgYtgk81YV5LsGmanbMEl1Y0jgalVN5OZPQR7nHAysuYUOLdqaTLV5FeGYIZUDzgbwdhkkN83pYBxwskpnC1sZUJLW+HLvaOWgHLhO+fvNKd8z1R8riThIthk1+KTrTwuKZYhJ79IaCxOxEwGJ7FHSbQ2ZVNmTolUAJkHt4bfPx24qn1Dfj+w6VRaIi1liqHlaakq3MlUzD7+ynBVSSqu/sEQ/LIVMJmQS4OEzha2cjQtAd9IR6p2cdbkcuq7zqkrQDYVtklLGFylCokkmz97YJQyKwOempAYXSLtODMoQNXmYFCqwXAWoFFeCVhjvk2OLEAZXLiTqcZfGYIHpQ+1+usQRzpg5ksNunEifVXDwyaOqaWDUcsr5KuxJy6ipcm/IZqEMIIHww8MP9QHv5tdZvg6sMnkq7EPLqKlVcBPX+nZj1WXHD+/6eEtNOdktRTCgYmWQmhDtBRCG6KlENoQLYXQhmgphDZESyG0IVoKoQ3RUghtiJZCaEO0FEIboqUQ2hAthdCGaCmENhxIS2mbHE6eA2lp/ApaXkoLJ8auWjpk2+S18GTpshIuDztp6ZBtk1dEtHQ52UlLh2ybDFSnWwspxi+iu1HOi6UfMrba6IA773Dp+o0zOf22tjNvinSzESfUjOMwvwoOLK+eOkk4SXZ9xjtY22Sc7l8nqFSQjSpkY6jBg2aUkyJ26dvphOAWdnZODseQB5gIJsPA+1IdEk6bBp89HKVtMvXKqSMxqGOOKnEFuKA5YuNxmEYpmMwaUp010jb+ulQtYBw2mBpt1/zhVGmgJThA22SVuE+PpaUaWS9Vu04tGMWtMZE94fRoo6WtUGE7aonSrM2EAS2BbIpVtst9k5bIr5rGnn/GG4uEgYPlTYaNtQSM9WrDSbIaLQHlWGMoWWpXHgxOidmqJSI9yhuFM9upSK2k2iSvkfNhiGewZi6FU2VNWtqdWu4htOVAWuqkbXK0FPbHgbTUCdFS2B+XS0sh7I9oKYQ2REshtCFaCqEN0VIIbYiWQmhDtBRCG6KlENoQLYXQhmgphDZESyG0oV8tpaVeWBdH09Inn/jMZPcvM/471PP+ZapecBq/gYdn02t5JB90lajUN6b0llQI5jha+sOvfPPHD/95smORoawXvvK0abPS64AD+aGTN9/++dntu/YsBwVaQtdvnJHfl0I4jpYo/Vffen9TAzCxXEubXh+UlqDuIdg3b925gJaUbdOWFcLRnvHm++lBKy2xgXDUHkIY2xQePePVKaQ3BXDUa+2ojktqEsZVYsZzcWlT1z7lnEw1Dgtr55ifPXzu839w791/orx45Btcglro88xridqlatXFgSOFy1FaMgyXhGxIIapyjo5X/wZiLM7B71eey7NPphqHYYdVc/r7EmUq8QxOFUNxK4l2jKolgiWYanuU5FRTAR78XhgQME515amnx2FOElbK6f++RPnK4NFOvyZZAN4lHLlQS44nA4z99sA4FVoah4W1cxwttf0cb6uWsLX/6Me/tcRRSiBGLfJmtIQA+J1HHgLGvfUEOZXcjFNhj8PC2jnaM96Sf19qqCUCqF0VtLXEJR7tyIAwkBCnhM3sSwz0pJKlssmjZRDm5zd5JlONw5QtrJdjfvYwD+W1o5ZCOCT9aqmTlnohLKRfLYWwLqKlENoQLYXQhmgphDZESyG0IVoKoQ3RUghtiJZCaEO0FEIboqUQ2hAthdCGaCmENhxIS2l2F06eA2npyn++FzTjmYfImc51IRydXbX0+Kc+XU8/8cknd2zekM0qrJSdtPSlr37rh/cePXX1izrlQe6Vuw+f/94NB5jlWsqLfWGl7KSla197/sH7v3zzwS+Q03xfod21hFPPhDKu3zhT8NVnrullb456D1ytHWoqjpqd49ntu+528tLHO9Q5TD2JFBPCQnZ9xmNrQk6v3Xv0g1cfIKTJTQlcpluxAAbgtJaIUcMGNKC6V/sE92AQXAVdqmqRTQbFE6C2EIrX2BDOS4PPHiSnGSGBinggm0mWaEkGTsQgUYG1wSXPhbPGgwRTW5cIxoIMRYZwLhpoCb5w7Rtf//YLA2el1vc8O2oJvz/u01VstwECa0l7kZwVhuQZL1yANlraCiV+GC2hAbSkq3hAWxCXlIT8epDTVY0dIL0NnCHMc2pakqFUVgsCUx88kvuzh/qYp0nx6xS/97EQFrIaLbXCkguhLQfSUifN7uoTYAhtOZCWjouf+vKhQtgfl0JLIRyAaCmENkRLIbQhWgqhDdFSCG2IlkJoQ7QUQhuipRDaEC2F0IZoKYQ29KulmT/h+9E7/+gmEyF0Qr9aulLerag89vgTN25+/613/iFyCl2xPi3BQjkxtnlLPb/1tL8XN7a+ibg1IByFVWoJJKc3/vZnB26mV98+3BPR0kpZk5aw77/3oV8WHAccgGgpbOKUtVQD6mvq8vilJmL0RjoFevPWHU6rs4KQNERJnBP8yDeYqL7Ga5uJNGpSlpPLIBUJlba2+NMlwtQwEHRp4PQaPDVJCCBM/rA7a33Gg+UBMPjFiSJ2HVNesjH0sqB+KXL9VXAqmLD7Dz9UTuefnGigJa/KMQPGy5BhkSAn2UIercoLqE4yMJwkGDg1NRlshyasQ0vP/cmf/9Fzf1avQg2YxAHUkKpKUFWceqDDKC/XaLUrToVRAxQ/mAg4xVltCQMwHFapU8tmbYx1fA0Ar79erU7bdWANCE1YgZY+87uff/3HH7z8+nuf+u+fnQyozooDag3B/rQ0HjXWkmy2DjYfpRpQk8gmeNziTzZ4/fVqddquC6gBoQkr0BKVwfP9ex/86uvffuGjj+/++vuAsbUaHEAt+nlMUFWuY/LLVhXaabtiLdWcTKEnq/FETk4Mz1QuZXkm1z9ehrYyjVUeOdUus2bG9jOek9smBkOaJEOe8drSu5bQz9t/9//06/Irdx/+1dkrP/nZv8ONm9//3Of/wOUyiWsImzJSEhWQqlOeWl6gsdWukMcidE5QKVenJgIMnTIRV+2poyqTy0Ae/khDnz1ULZHZt6OccnIc2CxeYfnsoTlda+n1+3//6lvv63s/5Gf//lE13HuUaqhSWQ4irM+NYXe61pJ/fm+CgL1qyT/FxeQ2siPsMHUK70jLuZiWuLULzBVm6FdLS9pT7rUx5VpYriU/KIKfVEMr+tVSCOsiWgqhDdFSCG2IlkJoQ7QUQhuipRDaEC2F0IZoKYQ2REshtCFaCqEN/Wop/fHCuuhXS5v+zCz98UKfrE9LcNr98WZg0vxNaresUktwwv3xZoiWemZNWsK+fwn6480QLfXMKWupBtR3vOWhKPVJBjF+R72H/nieRWvwUyVpWd5gCKfXb5wxl+MHTsc77cuvv6uX2+UPrVjrMx4sD4Bx2zoXGZUtG4N6JUzlaw1UcCqYsH30x2PqQaEzSjNqVbLr1frTQa/K2un1gFfLGnSbyhBasQ4tXar+eIRZHoOlzudHHmrhUJ2y60ACsi/tgxVo6bL1xwMWg5xY1dVnvlzvsUpCDHJu0lJdWLS0J1agJYqAp/zL0x9PuOIZrpXgIV7ZOCoVhjyyFemrtsnDCjUXp3nG2we9a+my9cerC9MCHF8/e7BaMEDxXpivVptsCkOi2Zf2QddaSn+8rVTZLISvmH/EhIZ0rSX//N4EAXutCf/IF+et2iV4uxCTm+EMF9ASUzBq4Ay706+W0h9vCQu1VH8w+Zk2tKVfLYWwLqKlENoQLYXQhmgphDZESyG0IVoKoQ3RUghtiJZCaEO0FEIboqUQ2tCvltIfL6yLfrW06c+Z0x8v9Mn6tARH7I834KWp/40cz8I/994auTxVODqr1BIcqz/eEpYLYGvk8lTh6KxJS9j3j90fbwnLBbA1cnmqcHROWUs1gCe9d3bujwfEaJRep/PrQ+QkM36OZ7fvSgD1hfPJt4wmZ5xMJXRH12+cKacuDZyeCEOevJR+GNb6jAfLA2Dctk5iACpSNoaaikgD4+ofzygtKd6VjQawcbqCxwPFeMbJVI6XR6vF1k1VJxkYThL8aYh3YNahpU7646nQAUMeaYmxGHZqLE5KXDsDTFZzncWjxqlkg5dar1an7XrLZMu+dABWoKWu+uMBRYkwVKkcqVo8FOtYS/PLgzqL7MlUsmGQU1er03YdGC0dhhVoiZrg53on/fGEM0tLFCunGLrkZzycM0mgziJ7MhW2JpLHV/2Mp8XIKRt/GuIdmN611FV/PAb6sU0FrRLHoFKpV+X3BwY13rNUJmecTGUtkccr19RychzYDFQYm1L2pQPQtZbSH29AlcpyLjYqnJeuteQf6psgYK8lwm5Qp9M+cGG8UQhtOOfiYqpgIm5k4AzN6VdL6Y83ZrmWiJl/vAzN6VdLIayLaCmENkRLIbQhWgqhDdFSCG2IlkJoQ7QUQhuipRDaEC2F0IZoKYQ29Kul9McL66JfLW3627P0xwt9sj4twcn0x5th5vZDn6xSS3Aa/fFmiJZWx5q0hH3/tPrjzdDt3YVNnLKWakB98Vsev+dHjN9RP3B/PJy6Wtcgz0dvDX/87pjr+o0zzVLjz9VhL+yPtT7jwfIA6LA/Xg0QpGKswshgWzCXPdiabrzmycUoQ9gr69DSqfbHY1QVDKPIJtur0iloLtmkQofMWNfpeevAGhD2ygq0dML98YAA5ESkVrW7liYXIzvslRVoiVLg5/pJ9scTROphjwwMkQwYqC0Lp5ZX14yhzBw9hezJxSgg7JXetXTC/fHqGjwXCeXxZw8DLemqPFDXaXtyMWHfdK2l9MeroB/p9lxcbFS4AF1ryT/UN0HAXrXkfUDsWJTsDzXbebeLC6iCDcqdkMO+6VdL6Y83YLmW/CNg8sPDsCf61VII6yJaCqEN0VIIbYiWQmhDtBRCG6KlENoQLYXQhmgphDZESyG0IVoKoQ39ain98cK66FdLVza8npT+eKFP1qclWN4fb1OGEJqzSi3Bkv540VI4JGvSEvb9i/b0CmHfXBYt+bVt8FtAGPK8/Pq76riwKVJwibCbt+7Uq9Xp94X8/jkeLr30n6+UhxNmrc94sDyA+nbvFE7VK686UYVkUJ2OVDbAJsw9FfTKanVylGw4ypCooqXLwDq0tHt/vPpCODbgdIlT8e4ENI70KQGEuQUKw4mvTtlXnnpa2RRWJwonzAq0tHt/vEmFVJ201dLVZ75cFxYtXRJWoCWqmV88WvXH49TPeO4rQrnPPOOB1FKvcvQz3kBL2IhHIsRmDdHSZaB3LTXvjwfYCpBKAQGARDKOtEIwSIiEuCTt1avVZtL7v26iRFg+e7gkdK2lg/XHq6qbocpmOYMHxXCqdK0l/WifwZ+P7wi1vmTruICWWJ4eFAf+cHr0q6V998erWmVTWqKQ5Vry0yP4kTKcNv1qKYR1ES2F0IZoKYQ2REshtCFaCqEN0VIIbYiWQmhDtBRCG6KlENoQLYXQhn61lP54YV30q6UrG/52O/3xQp+sT0vQVk4vnef/VN4a+eyv2z/cf+/Db/3p/57/Q1hSDf44ndO8nbFeVqklWNIfbyFtteSYrX9UPtZSWDVr0hI2P+/9ztI44GJES6EJp6wl6pgAfVxB4Sr++o0zefw0peqvwS5xv4YkD0eGs4AaU8HpeGnpXH3zOJUOMTwR8RKkbh8Px7Pbd/M02BtrfcaDrQGDH/yqRXmw/bqrK1hQuGiAS+P8RJIBTx0+wNm4imBU8Rw1L0cZEpVs47EYmkg2wxWvbPi5Gi31xjq0dLH+eLWaYRCPX5dcwRz5qS+wVb6gbaFGDuyK/czuZzzZV556mqteAGGcyhYeW5Nr7KBPmBcf+mEFWrpwfzxBzUkbg/iBlsCyGZQyglTRV3+1K/aPtbS1b57H1uQa+8fPfdfZIFrqkBVoSWK4QH88o6olkkcj1Sj24BmPWVTZNUx4olri1a7YP9YSNlelAWxyakbiZXgshjyyGaJ4XdUKo6Xe6F1Lu/THo/I0UL97KCHIqboEVbAKVMGqWnsc7Fof2BX7J7XknPWzB+JleCwGaGpdUhJG4SFDPnvokK611LY/HpHz2js6VUuTQjVbA8Lh6VpL3hY2QcARtTRY4bkWM6Yub14qbFA8oDa8kdCEfrXUvD9eLdau0O9C3I4f2ya1hFN3zZMechpcDUenXy2FsC6ipRDaEC2F0IZoKYQ2REshtCFaCqEN0VIIbYiWQmhDtBRCG6KlENrQr5bSHy+si361tOnP59IfL/TJ+rQE3fbHm1mzGAe8uOy/cA/9s0otQZ/98ebXDFsDwnpZk5aw7/fdH2/rklqtOXTIKWvJ7wUBGlD8XvvjDaaw8Jzno3eBP75mLmklHG/euqM1+B69qvpOe+iTtT7jwdYASrkWH5HUqDzY++iPh99TkJPhZMOwNhCMbVG15Jf8sJWEowyJSnbok3VoaS398eoUtpnFkTVAeBk2QGFXn7kmVctJkmipZ1agpRX1x6tT2K6RNUB4GTZAYc9+5bkaTBItI/TJCrREhSGGVfTHc2S1CcOQSplFz3hMrS5flhDHGqbFcNRV/FyVM/RJ71paV388TcFxYBOsPP7sYVJLeNgDCSNGoiJSa8hnD/3TtZYuQ3+8qiUZm9gaEI5L11rytrAJAo6opcEKz7UYwebjTxfmpULmyU8OQz/0q6WT74+nBz8/tk1qCY9vdvxIGbqiXy2FsC6ipRDaEC2F0IZoKYQ2REshtCFaCqEN0VIIbYiWQmhDtBRCG6KlENrQr5bSHy+si361tOnP59IfL/TJ+rQE3fbHm6H+SbjAzn+HfkqsUkvQZ3+8GcZaCifGmrSEfb/v/ngzREsnzylrifIlQB9XoAHF77U/3mBGPBx1ipDGz3h4GCLj5q07dSB49nFXvdAha33Gg60BFGWteCKRgTzY++iPN5iRgPsPP1QYl9z+zletJfcew9YvUcT7pwaXbIduWYeW1tIfbzAjAbYtUZ0Cdt2XBrN4ebD1TkMPrEBLK+qPJzyjp4DzaqnmX3in4bisQEsqzVX0xzNcIoD8/tQbj57xLCpLCMOPghz9jGdts7Y84/VP71paV388PIp36esHASAbSWhSS8yIhAiT3pSNKTQ2nz2sgq61dNr98aqWZAwCzNaA0ANda8nbwib8438JzbU0WOG5FgNsWYCxVSpsUIoMPdOvlk64P54eBa29SS3h5HlPt4mW6qXQJ/1qKYR1ES2F0IZoKYQ2REshtCFaCqEN0VIIbYiWQmhDtBRCG6KlENoQLYXQhmgphDYcSEuTf1x398cf7N5FKIROOJCWxn9X2s9fmobQhF219PinPl1PP/HJJx97/InqEWhm6wsUIptVWCk7aelLX/3WD+89cvNUHuReufvw+e/dcIBZrqXzvgUUQifspKVrX3v+wfu/fPPBL5ATQrrzxsP3PvjVd174y/HWtLuWnhy1nqtv+NjjF4Fsk42BZ7fv6vVvj/JEfrGcsJkX8kKYZ9dnPLYm5PTavUc/ePUBQprclGB3LVHx9ZU4JOF+I8SrEQpMaomcei/VkUoCNa1fdA3hAjT47EFymhES7K4lBMB+4lpHA7XuJYNNWvKHHANBAqPq7IOrISyngZbgC9e+8fVvvzBwVnbXklDpI4mLaUlhHjXpCeFitNHSVlppCbS3IJXxM54NnChEv//gtJbqKEG2rTOGsITVaImiHwTYA9gKQ0LysCmN96XJPB4CzhPCeVnfvhRCnxxIS0sadIlztekKoR8OpKUQTp5oKYQ2REshtCFaCqEN0VIIbYiWQmhDtBRCG6KlENoQLYXQhmgphDZESyG0oV8tzfwJ34/e+Uc3mQihE/rV0uBdCfPY40/cuPn9t975h8gpdMX6tAT7k9OLN29vfU392fL2bgimdy198cvP+cWn+mqT5PTG3/7s8M30oqUwySr3JbE1YE9ES2GSU9aSAq7fONOedvWZa5xic5QS/Ha6dzw8gMGTHgO1JQ6e+qSlm7fuaKxea5cT6kS+Gi4Da3rGMyp9BUgDk3CJSCkBhajXJCpi1KDELaGqJc8yaKmH7e5i2FwlRk6l5bj1l65wepz+vqSAWt8YKnouWaiWnLVkvVUbkE19xtPV6qxiC5eHE9+XZrSE3xuOrzbRkiAPS60Dw2lzefclql+PZ/Lo6oyW0AlqYRS4yZ6TYAy0BHXScPJc3n1JhhJi6OpCLZEWCTFQv4MRU7VEcF2nkoST55T3pRAOSbQUQhv61dKS9pRpTBn6oV8thbAuoqUQ2hAthdCGaCmENkRLIbQhWgqhDdFSCG2IlkJoQ7QUQhuipRDacCAtpdldOHkOpKX6d6jVTrO7cDIcQUuD09OW0+DGx3DJr/eGVXPkfUkcsdndvhnfbDhVjr8vbfKcBqd6X2FMF/vSJucAHoTe+em//KS8++2XzBmr98NfvHn75q07nOLE9uvieuFcs6hjngLsPLt9Vy+ck0fDPcpJNMvgtC5DCQFDHtIS5vvCqK/cE6bZOeot90HbvbAiVrMvcWnwewUVDLIpStkYkgTxVK2c1CXJqfvqdEI5JQNi1NRBAYy6+sw1ewYBgmyqe1/i1Gonre0KYQRrSbpxPO4Ehq2WLHVI6JzV7EsUqDQgqEJOHe/h1OJYFePC1SgFVydHSt/7hmTJRFUP9ZScjHU8sE5ySl1KOL6vungHeJGKIcBJwio4gpYokXcf/eu7f/9vf/7irccef2IcMIlFImo5goc7jICLaWlyGXjQD5dU6z698tTTnsVUGUwmnAyIltbOobX02c/9z1fuPsSAV996/3d+7/cHAR4ygFJzVzpBtYFsJCF7q5bQgGoU2894npoYbGUYUBPW07oMQX6SEIBNKm1iXoNXKDw7AeO2ew4L/XNoLQG1pcchFdkgwEPGUKN1oOpenlq7qlTXOrbrWLN4lEVVp8bwCn/tf9rxZK6TeiJ7fEeoSx5/9qA1/PFz39XHJ4Iwz04ABhLCr2dLrSesheN89jBma0ATDjPLxbDgB/6wFqKlXoiW1s6BtNRJs7toKeyPA2kphJMnWgqhDdFSCG2IlkJoQ7QUQhuipRDaEC2F0IZoKYQ2REshtCFaCqENB9JS+uOFk+dAWtr0h3DpjxdOhiNrCQ4sp5deuT947yivr4YmHFRLX/zyc5MvAh6lPx4SGrwPO8O5gsPl5Pj7ktga0JxoKbRlNVpSgFrbsaddfeYap9gc9c4PT26DHQ+Pe+U5DEkgDKjBz4467zmb4mXn1fEww9Ge8YzKVwGq40m4RKQ2BwpdZa3feaj1GslV2BQmbWBwVLb6Ep6c48U4OIRNrGxfUkCtbGuDSxaqrlpU1Xa8k2BY2PDrWT7qlwISWA0OYRNr2pccUCtb2sCvBl316nItOVuFbGxr8zEhmBPZl6h7N5TDo6sLtcTYQec940mjpbCVE9mXZCghhq4u1JJsr4cwZvE6FSxPPnsIM6xmXwqhc6KlENpwIC110h8vhP1xIC2FcPJESyG0IVoKoQ3RUghtiJZCaEO0FEIboqUQ2hAthdCGaCmENkRLIbThQFpKf7xw8hxIS5v+dDX98cLJcGQtwRI5qWFD3c30KlF9QwnwnN2+i8FEfgGpvnREsDPUgWNmFnwBmEuvaVXnN7/zF3L6lSrBzb78+rusub5V5VetZmBI/vfoI3JQLe3eH4/yqlU1o6WxEojE6VIjz0yBTma4MEz95ts/HwtGUwxuypKofox6p5NES8fl+PuSWFi7F9YSl/wSu1A147ensnA9C2GRzFULnXm5EWCKwVy+qXqzgxufJFo6LpdFS5O1iAe/gtV5D5TQGShNDF0iXqeMUgaClRaPYrhKjIazGD+L3rx1p0qXUcyoKXSqnIx1WF1ztUGyIacm1Vg5yYDBvLoRjophMZ4u7IOjPeMZPewpYOt3elBSLhSjq+QZPEwSqdqqyKlgD1Q/I4zBelzlXsPYAzWnZ5TTYVzFULtMTeFL1kN1ckokp9iiqgVbW67Gkra2ZNLtYxNsO+yDS70vqb4HwcpZncRYqzVetUuhE+8AYKI6fJxzPMXgkkbVee0UnlqnzEgwTn4rqz2VarY6XdgHq9+XapHNaIlLm35fGgQrp53MiKGqVckqBkNHD9FwMZlTBg9mEtsgBuefXf8rXZJncLMVlj2pJYQEWpX9sgfTheZcln0JGIhT9ccRW6kIQ8+qOezBMx75x2EE4AScnOIcPD55uE69TgbybOaENeajJA8/1PrtUaSx/sH7D8fBM57XydG3zAIGiwxtOdl9qU6kwgKC7fRATQ012OtxKo54dFVSrFPXzMR4uK86mBVKA4MYTeSlAvaMlhiLhJjO/4DGUZuVUmksR62Keet0oTkr25f2wQWmdk0P/AfDshn4Z7jAkHAuoqWLTM2OwZAj1uUFhMEGVTfS0JwDaann/njn0hLlSzBPUEeRvVmoJcJ4AtSXd/C4GJpzIC2FcPJESyG0IVoKoQ3RUghtiJZCaEO0FEIboqUQ2hAthdCGaCmENkRLIbQhWgqhBb/5W/8fqTLANob0B9oAAAAASUVORK5CYII=)

1. **Components**: Contains all your components ( ".brs" and ".xml" files ). This folder should contain all UI and logic elements.

2. **"Images"**: The folder that contains channel artworks like splash screens, icons, logos etc.

3. **"Source"**: Typically only contains the "Main.brs" file. Roku starts running the channel from this file.

4. **"Manifest"**: This file should contain all the necessary information about the channel, like name, version, URI to splash screen etc. ([read more about the manifest file](https://developer.roku.com/en-gb/docs/developer-program/getting-started/architecture/channel-manifest.md))

5. **"THEOplayer.pkg"**: This is the packaged THEOplayer SDK. This package does not have to be here if you wish to load the THEOplayer SDK via HTTPS. In this case you have to pass the link to the packaged THEOplayer SDK instead of the relative path while loading the component library.

### Include THEOplayer SDK

To include the THEOplayer SDK into the channel, follow these steps:

1. Load the THEOplayer SDK as a component library.

   To do this we have to add the following line into the `helloworld.xml` file, between the `<children>` tags.

   ```xml
   <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayer.pkg"/>
   ```

   It is worth mentioning that the "URI" field can also be an HTTPS link to the THEOplayer package. (In our case, we will add it to the: "pkg:\components\MainScene\MainScene.xml" file.)

2. Add the THEOplayerContainer group.

   We will need this group to append THEOplayer into our channel. In our case, we will add it to the `helloworld.xml` file, next to the `<ComponentLibrary>` node.

   ```xml
   <Group id="THEOplayerContainer"></Group>
   ```

3. Wait until THEOplayer SDK is loaded.

   We just want to be sure that THEOplayer is loaded correctly. We add the following code to our BrightScript `<script>`.

   ```brightscript
   function init()
     m.THEOsdk = m.top.findNode("THEOsdk")
     m.THEOsdk.observeField("loadStatus", "THEOsdkLoaded")
   end function

   function THEOsdkLoaded()
     ' this is the moment when THEOplayer is fully included on your channel
   end function
   ```

   It is worth mentioning that "m" works like the "this" keyword from other languages. "m" keyword points to the current component local namespace. So if you want to have access to variables across different functions inside the same component, use "m" to do so.

After these 3 steps, your `helloworld.xml` should resemble the following snippet:

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="HelloWorld" extends="Scene">
  <children>
    <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayer.pkg"/>
    <Group id="THEOplayerContainer"></Group>
  </children>
<script type="text/brightscript" >
<![CDATA[
  function init()
    m.THEOsdk = m.top.findNode("THEOsdk")
    m.THEOsdk.observeField("loadStatus", "THEOsdkLoaded")
  end function

  function THEOsdkLoaded()
    ' this is moment when theo player is fully included to Your channel
  end function
]]>
</script>
</component>
```

When you deploy this app to your local Roku device, it should still be an empty, gray channel.

### Create an instance of the THEOplayer SDK using BrightScript

In this simple example we will create an instance inside the `THEOsdkLoaded` function, but remember that once the component library is loaded, you can use it across the whole channel.

There is also no need to load this component again. (In our case we will add it to the "pkg:\components\MainScene\MainScene.brs" file.)

```brightscript
function THEOsdkLoaded()
  m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
  m.playerContainer = m.top.findNode("THEOPlayerContainer")
  m.playerContainer.appendChild(m.THEOplayer)
end function
```

When you deploy your project to your local Roku device, the channel should now be a plain black background. (It's now black because it's an empty video player container.)

Make sure your files resemble this:

* pkg:/source/main.brs:

  ```brightscript
  sub Main()
      print "in showChannelSGScreen"
      'Indicate this is a Roku SceneGraph application'
      screen = CreateObject("roSGScreen")
      m.port = CreateObject("roMessagePort")
      screen.setMessagePort(m.port)

      'Create a scene and load /components/helloworld.xml'
      scene = screen.CreateScene("HelloWorld")
      screen.show()

      while(true)
          msg = wait(0, m.port)
          msgType = type(msg)
          if msgType = "roSGScreenEvent"
              if msg.isScreenClosed() then return
          end if
      end while
  end sub
  ```

* pkg:/manifest file:

  ```brightscript
  ##   Channel Details
  title=Hello World
  major_version=1
  minor_version=0
  build_version=00001

  ##   Channel Assets
  ###  Main Menu Icons / Channel Poster Artwork
  #### Image sizes are FHD: 540x405px | HD: 290x218px | SD: 214x144px
  mm_icon_focus_fhd=pkg:/images/channel-poster_fhd.png
  mm_icon_focus_hd=pkg:/images/channel-poster_hd.png
  mm_icon_focus_sd=pkg:/images/channel-poster_sd.png

  ###  Splash Screen + Loading Screen Artwork
  #### Image sizes are FHD: 1920x1080px | HD: 1280x720px | SD: 720x480px
  splash_screen_fhd=pkg:/images/splash-screen_fhd.jpg
  splash_screen_hd=pkg:/images/splash-screen_hd.jpg
  splash_screen_sd=pkg:/images/splash-screen_sd.jpg

  splash_color=#000000
  splash_min_time=1
  ```

* pkg:/components/helloworld.xml:

  ```xml
  <?xml version="1.0" encoding="utf-8" ?>
  <component name="HelloWorld" extends="Scene">
    <children>
      <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayerSDK.pkg"/>
      <Group id="THEOplayerContainer"></Group>
    </children>
  <script type="text/brightscript" >
  <![CDATA[
    function Init()
      m.THEOsdk = m.top.findNode("THEOsdk")
      m.THEOsdk.observeField("loadStatus", "THEOsdkLoaded")
    end function

    function THEOsdkLoaded()
      m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
      m.playerContainer = m.top.findNode("THEOplayerContainer")
      m.playerContainer.appendChild(m.THEOplayer)
    end function
  ]]>
  </script>
  </component>
  ```

Great! You have included the THEOplayer SDK into your channel now! If you run this channel, you will only see a black screen because we did not set any source and we did not start the playback. Follow the next sections to start video playback.

### Create an instance of the THEOplayer SDK using XML

There is an alternative way to include the THEOplayer SDK. You can include the component library using only XML. In this approach, you want to make sure that the component library is fully loaded before including the component into the scene graph.

An example of this approach is demonstrated through our [basic-playback-app project on GitHub](https://github.com/THEOplayer/samples-roku-sdk/tree/master/basic-playback-app). In this project, `MainScene.xml` loads the SDK, and the instance is created through (for example) `<THEOsdk:THEOplayer id="VideoPlayerChromefull" controls="true" />` in `ChromefullView.xml`.

### Configure license

You need to configure your THEOplayer Roku SDK license value through the following snippet:

```brightscript
m.THEOplayer.callFunc("configure", {license: "your-license"})
```

Add these 3 lines after `m.playerContainer.appendChild(m.THEOplayer)`.

Note that you have to replace `your-license` with your actual license value as specified on the [THEOplayer Development Portal](https://portal.theoplayer.com/) for your THEOplayer Roku SDK.

![](/pr-932/assets/images/roku-portal-sdk-82cbb1f9e8d639efd2c8924109f29d73.png)

### Video playback example

To play videos using the THEOplayer SDK, we need to take a few steps:

1. Include the THEOplayer SDK and create an instance of it. (described in above section)

2. Set a player source. To accomplish this we will edit the `THEOsdkLoaded` function. (Added later in the "Using the THEOplayer SDK" section.)

   ```brightscript
   function THEOsdkLoaded()
     m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
     m.playerContainer = m.top.findNode("THEOplayerContainer")
     m.playerContainer.appendChild(m.THEOplayer)
     m.THEOplayer.callFunc("configure", {license: "your-license"})
     m.THEOplayer.source = {
       "sources": [
         {
           "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
           "type": "application/x-mpegURL"
         }
       ]
     }
   end function
   ```

3. Set focus to the THEOplayer SDK to make sure that remote controls will work properly.

   ```brightscript
   function THEOsdkLoaded()
     m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
     m.playerContainer = m.top.findNode("THEOplayerContainer")
     m.playerContainer.appendChild(m.THEOplayer)
     m.THEOplayer.callFunc("configure", {license: "your-license"})
     m.THEOplayer.source = {
       "sources": [
         {
           "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
           "type": "application/x-mpegURL"
         }
       ]
     }
     m.THEOplayer.setFocus(true)
   end function
   ```

4. Play a video with the "play" method.

   ```brightscript
   function THEOsdkLoaded()
     m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
     m.playerContainer = m.top.findNode("THEOplayerContainer")
     m.playerContainer.appendChild(m.THEOplayer)
     m.THEOplayer.callFunc("configure", {license: "your-license"})
     m.THEOplayer.source = {
       "sources": [
         {
           "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
           "type": "application/x-mpegURL"
         }
       ]
     }
     m.THEOplayer.setFocus(true)
     m.THEOplayer.callFunc("play")
   end function
   ```

After these 4 steps, your `helloworld.xml` file should resemble the following snippet:

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="HelloWorld" extends="Scene">
  <children>
    <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayerSDK.pkg"/>
    <Group id="THEOplayerContainer"></Group>
  </children>
<script type="text/brightscript" >
<![CDATA[
  function Init()
    m.THEOsdk = m.top.findNode("THEOsdk")
    m.THEOsdk.observeField("loadStatus", "THEOsdkLoaded")
  end function

  function THEOsdkLoaded()
    m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
    m.playerContainer = m.top.findNode("THEOplayerContainer")
    m.playerContainer.appendChild(m.THEOplayer)
    m.THEOplayer.callFunc("configure", {license: "your-license"})
    m.THEOplayer.source = {
      "sources": [
        {
          "src": "https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
          "type": "application/x-mpegURL"
        }
      ]
    }
    m.THEOplayer.setFocus(true)
    m.THEOplayer.callFunc("play")
  end function
]]>
</script>
</component>
```

Deploying this app should result in the start-up of your configured video, as demonstrated by the screenshot below.

![](/pr-932/assets/images/roku-loading-source-89d4166a78190aad5683764e487da9f3.jpg)

### Add a player event listener

Adding an event listener in the Roku THEOplayer SDK is straightforward. All you have to do is follow these steps:

1. Create Callback function

   This code will be executed when the event will be propagated. (In this example we will add the function to the `helloworld.xml` file.)

   ```brightscript
   function onPlaying(params)
     print("I am playing")
     print(params)
   end function
   ```

2. Add the callback function to the component interface. (In this example we will edit the `helloworld.xml` file.)

   ```xml
   <?xml version="1.0" encoding="utf-8" ?>
   <component name="HelloWorld" extends="Scene">
     <interface>
       <function name="onPlaying"/>
     </interface>
     <children>
       <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayerSDK.pkg"/>
       <Group id="THEOplayerContainer"></Group>
     </children>
   </component>
   ```

3. Set a listener and call the `addEventListener` method. (In this example we will edit the `helloworld.xml` file, and add a line inside the `THEOsdkLoaded` function.)

   ```brightscript
   m.THEOplayer.callFunc("addEventListener", "playing", m.top, "onPlaying")
   ```

4. Now You will be able to see the following output in the debug console. ([How to use the debug console in Roku.](https://developer.roku.com/en-gb/videos/courses/rsg/debugging.md))

   ```brightscript
   I am playing
   <Component: roAssociativeArray> =
   {
       currentTime: 0
       date: "2020-09-08T11:06:09Z"
       type: "playing"
   }
   ```

5. Check your code and make sure `pkg:/components/helloworld.xml` resembles the following snippet:

   ```xml
   <?xml version="1.0" encoding="utf-8" ?>
   <component name="HelloWorld" extends="Scene">
     <interface>
       <function name="onPlaying"/>
     </interface>
     <children>
       <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayerSDK.pkg"/>
       <Group id="THEOplayerContainer"></Group>
     </children>
   <script type="text/brightscript">
   <![CDATA[
     function Init()
       m.THEOsdk = m.top.findNode("THEOsdk")
       m.THEOsdk.observeField("loadStatus", "THEOsdkLoaded")
     end function

     function THEOsdkLoaded()
       m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
       m.playerContainer = m.top.findNode("THEOplayerContainer")
       m.playerContainer.appendChild(m.THEOplayer)
       m.THEOplayer.callFunc("configure", {license: "your-license"})
       m.THEOplayer.source = {
         "sources": [
           {
             "src": "https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
             "type": "application/x-mpegURL"
           }
         ]
       }
       m.THEOplayer.setFocus(true)
       m.THEOplayer.callFunc("addEventListener", "playing", m.top, "onPlaying")
       m.THEOplayer.callFunc("play")
     end function

     function onPlaying(params)
       print("I am playing")
       print(params)
     end function

   ]]>
   </script>
   </component>
   ```

### Remove a player event listener

In order to remove an event listener, call the line below:

```brightscript
 m.THEOplayer.callFunc("removeEventListener", "playing", m.top, "onPlaying")
```

You can put this line anywhere you want. Just make sure that `m.THEOplayer` is used in the proper context. For example, in `pkg:/components/helloworld.xml` you can do something like this:

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="HelloWorld" extends="Scene">
  <interface>
    <function name="onPlaying"/>
  </interface>
  <children>
    <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayerSDK.pkg"/>
    <Group id="THEOplayerContainer"></Group>
  </children>
<script type="text/brightscript">
<![CDATA[
  function Init()
    m.THEOsdk = m.top.findNode("THEOsdk")
    m.THEOsdk.observeField("loadStatus", "THEOsdkLoaded")
  end function

  function THEOsdkLoaded()
    m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
    m.playerContainer = m.top.findNode("THEOplayerContainer")
    m.playerContainer.appendChild(m.THEOplayer)
    m.THEOplayer.callFunc("configure", {license: "your-license"})
    m.THEOplayer.source = {
      "sources": [
        {
          "src": "https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
          "type": "application/x-mpegURL"
        }
      ]
    }
    m.THEOplayer.setFocus(true)
    m.THEOplayer.callFunc("addEventListener", "playing", m.top, "onPlaying")
    m.THEOplayer.callFunc("play")
  end function

  function onPlaying(params)
    print("I am playing")
    print(params)
    m.THEOplayer.callFunc("removeEventListener", "playing", m.top, "onPlaying")
  end function

]]>
</script>
</component>
```

In this example, the `onPlaying` callback will be executed only once, because we have called `removeEventListener` inside of the `onPlaying` function.

### Quickstart

Use this section if you are already familiar with setting up the THEOplayer Roku SDK.

1. Build a THEOplayer Roku SDK at <https://portal.theoplayer.com>.
2. Setup Roku's [`hello-world` sample project](https://github.com/rokudev/hello-world).
3. Add (and rename) your THEOplayer Roku SDK to the `hello-world` project.
4. Replace the code in `source/components/helloworld.xml` with the codeblock above.
5. Update the value of `license` in your updated `source/components/helloworld.xml` with your actual license value according to <https://portal.theoplayer.com>.
6. Confirm playback by deploying this project to your local Roku device.

## Next steps

Consider the following actions to improve your knowledge on the THEOplayer Roku SDK:

* Clone (or download) our sample Roku applications at <https://github.com/THEOplayer/samples-roku-sdk>. These applications provide an alternative perspective on using THEOplayer in Roku.
* Go through the [how-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku.md). We try to provide the "Roku implementation" in as many articles as we can. (e.g. ["How to programmatically enable or disable text tracks"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/text-tracks/enable-disable-text-tracks.md))

---

# Migrating to THEOplayer Roku SDK 11.x

This article will guide you through updating to THEOplayer Roku SDK version 11 (from version 10.x), and the changes needed in your code. If you are upgrading from a version before 10.x, please follow the [migration guide for 10.x](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/roku/migrating-to-theoplayer-10.md) first.

## Update THEOplayer

Download the new pkg file from [the THEOplayer portal](https://portal.theoplayer.com). If you're including the pkg file when packaging your application, replace the previous pkg file with the new pkg file. If you're loading the pkg from the remote URL at runtime, change the URL in your ComponentLibrary node to point to the new SDK's URL.

```xml
<ComponentLibrary id="THEOsdk" uri="pkg:/components/THEOplayerSDK.pkg" />
```

## Update Connectors to the 11.x version

If you are using any of the connectors for Roku, update them to the 11.x version as well. Either download them from [the THEOplayer portal](https://portal.theoplayer.com) and add them to your application, or load them directly from a URL.

```xml
<ComponentLibrary id="THEOConvivaConnector" uri="pkg:/components/THEOConvivaConnector.pkg" />
<ComponentLibrary id="THEOComscoreConnector" uri="pkg:/components/THEOComscoreConnector.pkg" />
<ComponentLibrary id="THEOAEPConnector" uri="pkg:/components/THEOAEPConnector.pkg" />
<ComponentLibrary id="THEOMuxConnector" uri="pkg:/components/THEOMuxConnector.pkg" />
```

## Replace or remove usages of deprecated APIs

Some properties and methods that were previously deprecated have been removed from the API. Update your code to use the new APIs instead.

* Removed the `THEOplayer.events.bitratechange` event type. Use the `THEOplayer.events.activequalitychanged` event type instead.

---

# Playing ads with THEOplayer Roku SDK

This article will provide the steps needed to play video ads with your content using the THEOplayer Roku SDK. The THEOplayer Roku SDK currently only supports Client-side Ad Insertion (CSAI) for VOD assets and some Server-side Ad Insertion (SSAI) using Google Ad Manager or THEOads. It does not yet support Client-side Ad Stitching (CSAS), Server Guided Ad Insertion (SGAI) or live CSAI ads.

## First Steps

* Make sure you are using a version of the SDK that supports ads. CSAI is available for VOD content in v9.3 and higher of the SDK. SSAI with Google IMA is available starting in v10.3.
* Include the RAF advertising library in your application's manifest file by adding this line: `bs_libs_required=roku_ads_lib`
* To support Google DAI, include the Google IMA library as well by adding `googleima3` after the RAF ads library: `bs_libs_required=roku_ads_lib,googleima3`

## Client-side Ad Insertion

The THEOplayer Roku SDK supports CSAI by using the Roku Advertising Framework (RAF), which is provided by Roku. It supports VMAP and VAST ad tags. For more information about specific features of VAST or VMAP supported by RAF, please visit their [support page](https://developer.roku.com/docs/developer-program/advertising/roku-advertising-framework.md).

### Create your ad descriptions

Ads are added to your content by adding ad sources to your source descriptions that are set on the `source` property of the THEOplayer. Here is an example for VAST ad tags:

```brightscript
m.player.source = {
    "title": "My VOD Asset",
    "live": false,
    "sources": {
        "src": "https://example.com/my_vod_asset.m3u8",
        "type": "application/x-mpegurl"
    },
    "ads": [
        {
            integration: "csai",
            sources: "https://exampleadserver.com/preroll.xml",
            timeOffset: "start"
        },
        {
            integration: "csai",
            sources: "https://exampleadserver.com/midroll.xml",
            timeOffset: 30
        },
        {
            integration: "csai",
            sources: "https://exampleadserver.com/midroll2.xml",
            timeOffset: 190
        },
        {
            integration: "csai",
            sources: "https://exampleadserver.com/postroll.xml",
            timeOffset: "end"
        }
    ]
}
```

For VMAP ads, the timing is contained within the VMAP file itself, so the configuration is simpler:

```brightscript
m.player.source = {
    "title": "My VOD Asset",
    "live": false,
    "sources": {
        "src": "https://example.com/my_vod_asset.m3u8",
        "type": "application/x-mpegurl"
    },
    "ads": [
        {
            integration: "csai",
            sources: "https://exampleadserver.com/vmap.xml",
        }
    ]
}
```

Note that the `timeOffset` property must be omitted for VMAP ads.

You may also specify the timings for VAST ads either by using a timecode or by specifying the percent of the asset that should play before displaying the ad. Timecodes should be in the format `HH:MM:SS`.

```brightscript
m.player.source = {
    "title": "My VOD Asset",
    "live": false,
    "sources": {
        "src": "https://example.com/my_vod_asset.m3u8",
        "type": "application/x-mpegurl"
    },
    "ads": [
        {
            integration: "csai",
            sources: "https://exampleadserver.com/midroll.xml",
            timeOffset: "00:05:30"
        },
        {
            integration: "csai",
            sources: "https://exampleadserver.com/midroll2.xml",
            timeOffset: "25%"
        }
    ]
}
```

#### Mixing VAST and VMAP Ads

Mixing VAST and VMAP ads is supported to an extent. A VMAP tag may contain multiple ad breaks. VAST tags may not be scheduled in between any of the breaks in a single VMAP tag. So, for instance, if you have a VMAP tag that contains a preroll and a postroll, you could not schedule any VAST midrolls between those breaks. However, if the preroll and postroll were in separate VMAP tags, you could schedule a midroll in between them.

### Listen for ad events

To detect events emitted for the ads, you can call the `addEventListener` method on the Ads API. You can see the list of ad events on [the API reference page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/api-reference/roku.md#ads-api). Note that the method used for the listener needs to be exposed through the interface of the node that owns the listener function.

```brightscript
adEvents = m.player.ads.events
m.player.ads.callFunc("addEventListener", adEvents.adbreakbegin, m.top, "onAdBreakBegin")
m.player.ads.callFunc("addEventListener", adEvents.adbreakend, m.top, "onAdBreakEnd")
```

To clean up, you can simply call `removeEventListener` the same way.

```brightscript
m.player.ads.callFunc("removeEventListener", adEvents.adbreakbegin, m.top, "onAdBreakBegin")
m.player.ads.callFunc("removeEventListener", adEvents.adbreakend, m.top, "onAdBreakEnd")
```

Also, if you just want to see whether ads are playing or not, observe the `playing` field on the Ads API. You can see the other fields available on [the API reference page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/api-reference/roku.md#ads-api).

```brightscript
m.player.ads.observeField("playing", "onAdsPlayingChange")

sub onAdsPlayingChange( event as object )
    adsPlaying = event.getData()
end sub
```

> **Info**
>
> When playing CSAI ads, if the user presses the back button on the remote, the back button press will not be captured by `onKeyEvent` listeners. To allow your application to handle this back button press, the application should listen for the `adexitrequested` event on the Ads API and handle the exit logic there. Otherwise, it takes a second back button press to exit the player.

### Monitoring RAF

The THEOplayer Roku SDK does not expose RAF directly. However, you can still get the data from RAF's callbacks for tracking, buffering, and library version. On the Ads API, there is the `rafProxy` node. This field exposes data from RAF on fields of its own. To substitute for the output from RAF's `setTrackingCallback` method, you could do the following:

```brightscript
m.player.ads.rafProxy.observeField("trackingUpdate", "onRafTrackingUpdate")

sub onRafTrackingUpdate(event as object)
    update = event.getData()
    m.myRafObserver.rafTrackingCallback(m.myRafObserver, update.eventType, update.ctx)
end sub
```

Similarly, you can listen for RAF's `setAdBufferRenderCallback` output by observing the `bufferRenderUpdate` field on the Ads API.

```brightscript
m.player.ads.rafProxy.observeField("bufferRenderUpdate", "onRafBufferUpdate")

sub onRafBufferUpdate(event as object)
    update = event.getData()
    m.myRafObserver.rafBufferingCallback(m.myRafObserver, update.eventType, update.ctx)
end sub
```

The `rafProxy` field also exposes the library version of RAF via its own `libVersion` field.

### Scheduling Ads at Runtime

If you need to add an ad break to your asset when the asset has already begun playing, you can use the `schedule` method on the Ads API. It takes an ad description as the parameter. It will return a true or false value, based on whether adding the ad appears to have succeeded. In some cases when adding VMAP, it may not be able to report accurately whether the ad break was added or not. In that case you can observe the `scheduledAdBreaks` property to see if the ad break was correctly added.

```brightscript
adDesc = {
    integration: "csai",
    sources: "https://exampleadserver.com/midroll.xml",
    timeOffset: "00:05:30"
}
success = m.player.ads.callFunc("schedule", adDesc)
```

There are some restrictions on what you can schedule:

1. You cannot schedule preroll ads via the `schedule` method.
2. You cannot schedule an ad at the same time as an already scheduled ad.
3. You cannot schedule a VMAP before any previously scheduled breaks, unless that previously scheduled break is a VAST postroll.
4. If you schedule a VMAP midroll after it would have already played, it will play immediately.
5. You cannot schedule a midroll in between ad breaks that are in the same VMAP tag.
6. You cannot schedule a midroll before a previously scheduled VMAP tag.

### Limitations

Currently the Ads API does not support:

* Playing VAST tags in the middle of breaks from a VMAP tag.
* Reporting the exact media file that is being played for a creative.

## Server-side Ad Insertion

The THEOplayer Roku SDK supports SSAI by using the Google IMA library, which is provided by Roku and can be added in your application's manifest file. It supports SSAI through two methods: Google-registered streams and THEOlive streams with THEOads.

### Google IMA Streams

To play a DAI stream that is registered with Google IMA, add an `ssai` config on the source description you pass to the THEOplayer. Set the `src` property of the `sources` object to an arbitrary, non-empty string and set the `type` to the MIME type for the manifest. Then fill in your Google DAI information in the `ssai` config, making sure to set the `integration` property of the `ssai` config to `"google-dai"`.

```brightscript
m.player.source = {
    "title": "Google DAI Stream",
    "sources": {
        "src": "ssai",
        "type": "application/x-mpegurl",
        "ssai": {
            integration: "google-dai",
            availabilityType: "live",
            assetKey: "<MY_ASSET_KEY>",
            networkCode: "<MY_NETWORK_CODE>",
            apiKey: "<MY_API_KEY>",
        },
    }
},
```

### THEOlive and THEOads

To play a THEOlive SSAI stream that is configured in THEOlive to use THEOads with Google IMA, add an `ssai` config on the source description you pass to the THEOplayer. Set the `src` property of the `sources` object to your THEOlive distribution ID and set the `type` to `"theolive"`. Then on the `ssai` config, set the `integration` property to `"theoads"`. You may additionally add ad tag parameters for Google IMA by setting the `adTagParameters` property of the `ssai` config to an associative array with the URL params as properties and values.

```brightscript
m.player.source = {
    "title": "THEOlive DAI Stream",
    "sources": {
        "src": "<MY_THEOLIVE_DISTRIBUTION_ID>",
        "type": "theolive",
        "ssai": {
            integration: "theoads",
            adTagParameters: {
                "iu": "<MY_IU_VALUE>"
            }
        }
    }
},
```

### Listening for Ad Events

With SSAI, the AdsAPI still will emit ad beacon events. You can add listeners for these ad events on the AdsAPI just like CSAI by following the instructions in the CSAI section. Unfortunately, monitoring RAF via the RAF proxy is not available for SSAI.

---

# How-to guides for OptiView Player Roku SDK

Want to start implementing features to your SDK? Our how-to-guides will help you with all kind of integrations!

## [🔐DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/drm/introduction.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/drm/introduction.md)

## [🎥Media tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/media-tracks/introduction.md)

[3 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/media-tracks/introduction.md)

## [▶️Player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/player/introduction.md)

[3 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/player/introduction.md)

## [💬Text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/text-tracks/introduction.md)

[4 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/text-tracks/introduction.md)

## [🔑License](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/license/introduction.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/license/introduction.md)

## [🚀OptiView Live](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/theolive/getting-started.md)

[Integrate OptiView Live streaming into your Roku app.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/theolive/getting-started.md)

---

# DRM on Roku

THEOplayer supports FairPlay, PlayReady and Widevine by default. To use these DRM systems, you will need to pass a DRM configuration along with the `source` object. We are partnered with many multi-DRM vendors to make it as easy as possible to get your DRM streams running.

## Custom configuration

Developers can use the generic DRM-functionalities in case in-house DRM-solutions are used, or services from DRM-vendors for which no integration is available.

If you are integrating Widevine DRM, first make sure your Roku application's `manifest` file contains the following entries:

```text
requires_widevine_drm=1
requires_widevine_version=1.0
```

In order to play DRM protected resources, you will need to pass extra DRM parameters. To see what kind of DRM protection is supported by Roku devices, please visit [this page](https://developer.roku.com/en-gb/docs/specs/media/content-protection.md).

In the following example, there is a function called "setSource", which sets the source of a THEOplayer instance ("m.player.source").

It is worth mentioning that "m" works like the "this" keyword from other languages. An "m" keyword points to the current component local namespace. Therefore, in case you want to access a variable across different functions inside the same component, use "m" to do so.

```brightscript
function setSource(streamFormat)
  if streamFormat = "hls" then
    drmParams = {
      "widevine": {
        "licenseAcquisitionURL": "<LICENSE_KEY_URL_WIDEVINE>"
      }
    }
    m.player.source = {
      "poster": "poster.png",
      "sources": [
        {
          "contentProtection": drmParams,
          "src": "<HLS_STREAM_URL>",
          "type": "application/x-mpegURL"
        }
      ]
    }
  end if
  if streamFormat = "dash" then
    drmParams = {
      "widevine": {
        "licenseAcquisitionURL": "<LICENSE_KEY_URL_WIDEVINE>"
      },
      "playready": {
        "licenseAcquisitionURL": "<LICENSE_KEY_URL_PLAYREADY>"
      }
    }
    m.player.source = {
        "poster": "poster.png",
        "sources": [
          {
            "contentProtection": drmParams,
            "src": "<DASH_STREAM_URL>",
            "type": "application/dash+xml"
          }
        ]
    }
  end if
end function
```

For more advanced configurations, consult the [content protection API documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/api-reference/roku.md#content-protection).

## Custom integration

Developers can make their own custom DRM integration for any DRM vendor. This can be done by making use of the [DRM integration API repository](https://github.com/THEOplayer/samples-drm-integration).

A complete guide on how to create a new integration, and some example integrations can be found in the provided repository.

---

# Media tracks on Roku

The articles in this section describe how to implement common use-cases related to audio and video tracks, such as switching between audio languages, or selecting a specific video quality.

The MediaTrack API, and its AudioTrack and VideoTrack sub-APIs, allow you to programmatically enable and disable audio tracks, inspect the available video qualities, override the ABR algorithm and more.

## Related articles

* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/media-tracks/enable-disable-audio-tracks.md)
* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/media-tracks/detect-audio-tracks.md)

---

# How to programmatically enable or disable audio tracks on Roku

This article describes how you can use the AudioTrack API, a sub-API of the MediaTrack API, to enable or disable audio tracks. Implementing this functionality is a common use-case for developers who want to build their own UI to toggle audio languages on and off.

Once you have programmatically selected a track, you can set its `enabled` property (or method) to `true` or `false`. Because only one audio track can play at a time, enabling an audio track automatically disables all other audio tracks. Note that this does not apply to text tracks: multiple text tracks can be active at the same time.

## Usage

To set a preferred audio track, you can write a subroutine like `setAudioLanguage`. This subroutine accepts `language` as a string parameter. It then searches for the specified language in the audio tracks, and enables the track if it has a matching language.

```brightscript
sub setAudioLanguage(language as String)
  audioTracks = m.player.audioTracks
  for i = audioTracks.count() - 1 to 0 step -1
    if audioTracks[i].language = language then
      audioTracks[i].enabled = true
    else
      audioTracks[i].enabled = false
    end if
  end for
  ' Assignment of new roAssociativeArray is required, because Roku field values are copies, not references.
  ' Read more: https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow
  m.player.audioTracks = audioTracks
end sub
```

## Related articles

* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/media-tracks/detect-audio-tracks.md)

---

# How to programmatically detect audio tracks on Roku

This article describes how you can use the AudioTrack API, a sub-API of the MediaTrack API, to detect audio tracks. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available audio languages.

## Usage

The snippet below allows you to detect added audio tracks. In this example, we have used the `addedaudiotrack` event to propagate information about audio tracks. Basically, all you have to do is add an event listener.

```brightscript
sub Init()
  ...
  m.THEOplayer.callFunc("addEventListener", "addedaudiotrack", m.top, "onAudioTracksChanged")
  ...
end sub

sub onAudioTracksChanged()
  audioTracks = m.player.audioTracks
  print "Audio tracks changed. "; audioTracks
end sub
```

## Related articles

* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/media-tracks/enable-disable-audio-tracks.md)

---

# Player on Roku

The Player API is the top-level API. This API exposes:

* basic functions to manipulate video playback, such as start and pause;
* properties to check states and values, such as the playhead position;
* events to track changes.

## Events

As a developer, you can programmatically attach event listeners to different APIs. Event listeners are often used to implement a custom UI, or to implement a custom analytics integration.

The THEOplayer API exposes many events across different interfaces, as can be seen in the graphic below. Furthermore, most events exist in all SDKs (Web, iOS-based, Android-based and Roku).

![THEOplayer API Interfaces and Events](/pr-932/assets/images/analytics-events-185d6ab52b556af08d8300b545ae5876.png "THEOplayer API Interfaces and Events")

Refer to [the Roku SDK API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/api-reference/roku.md) to go through the latest set of events.

## Related articles

* [How to measure the time-to-first-frame](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/player/measure-time-to-first-frame.md)
* [How to track the first play(ing) event](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/player/track-first-playing-event.md)

---

# How to measure the time-to-first-frame on Roku

The time-to-first-frame, also known as the start-up time, is the time between the moment where playback is requested and the moment where the first frame is rendered.

To measure it, measure the time between the `play` event and the `playing` event.

## Usage

On Roku, you measure the elapsed time with a [`roTimespan`](https://developer.roku.com/docs/references/brightscript/interfaces/iftimespan.md).

```brightscript
sub Init()
  ...
  m.timespan = CreateObject("roTimespan")
  m.THEOplayer.callFunc("addEventListener", "play", m.top, "onPlay")
  m.THEOplayer.callFunc("addEventListener", "playing", m.top, "onPlaying")
  ...
end sub

sub onPlay()
  m.timespan.Mark()
end sub

sub onPlaying()
  print "Time-to-first-frame: "; m.timespan.TotalMilliseconds()
end sub
```

If you use autoplay, start the measurement on the `sourcechange` event instead of the `play` event. Otherwise you miss the start-up time between setting the source and the player calling `play()`:

```brightscript
m.THEOplayer.callFunc("addEventListener", "sourcechange", m.top, "onSourceChange")

sub onSourceChange()
  m.timespan.Mark()
end sub
```

---

# How to track the first play(ing) event on Roku

Sometimes you want to know when a new stream starts playing for the first time, for example to forward a `firstplay` event to an analytics back-end. THEOplayer does not expose such an event, but you can implement it yourself, which gives you more control over its logic.

The implementation below listens for the first `playing` event after every source change. If the viewer pauses and resumes the stream, the event is not dispatched again. If the viewer switches to another stream, it is dispatched once more.

You can swap out the `playing` event for a `play` event, or for any other event for that matter.

## Usage

```brightscript
sub Init()
  ...
  m.THEOplayer.callFunc("addEventListener", "sourcechange", m.top, "onSourceChange")
  ...
end sub

sub onSourceChange()
  m.THEOplayer.callFunc("removeEventListener", "playing", m.top, "onFirstPlaying")
  m.THEOplayer.callFunc("addEventListener", "playing", m.top, "onFirstPlaying")
end sub

sub onFirstPlaying(params)
  m.THEOplayer.callFunc("removeEventListener", "playing", m.top, "onFirstPlaying")
  print "First playing event! "; params
end sub
```

---

# Text tracks on Roku

The articles in this section describe how to implement common use-cases related to text tracks, subtitles, closed captions and metadata. These use-cases can range from programmatically detecting new metadata, to side-loading subtitles.

THEOplayer supports

* subtitle and closed caption formats like WebVTT, CEA-608, DVB Subs and TTML;
* metadata formats like ID3, emsg, EventStream and `EXT-X-DATERANGE`.

The TextTrack API allows you to programmatically switch between text tracks, detect events related to text tracks (e.g. a new active cue) and more.

## Related articles

* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/text-tracks/change-visible-captions.md)
* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/text-tracks/detect-text-tracks.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/text-tracks/enable-disable-text-tracks.md)

---

# How to dynamically change the visible captions on Roku

This article describes how you can dynamically change the currently selected subtitle or closed captions language, or how you can set a default language.

This article assumes that you are using text tracks that are loaded with the manifest. If you add the text track separately, you can also mark it as the default track when you configure your source.

The examples below match tracks on their `language` property, which contains the ISO language code of the track. If that is not sufficient for your use case, for example when a stream contains multiple tracks with the same language, you can match on the track's `label` instead, which contains the human-readable name shown in your UI.

## Usage

In the following example we iterate through all available text tracks. Once we find a track with the desired language, we set its mode to `showing`. After that, we assign the `textTracks` object back to the THEOplayer attribute. This is all you have to do to make the desired text track visible. You can also change the visible text track during playback.

```brightscript
sub setCaptionsLanguage(language as String)
  textTracks = m.player.textTracks
  for i = textTracks.count() - 1 to 0 step -1
    if m.fullScreen and textTracks[i].kind = "captions" and textTracks[i].language = language then
      textTracks[i].mode = "showing"
    else
      textTracks[i].mode = "hidden"
    end if
  end for
  ' Assignment of new roAssociativeArray is required, because Roku field values are copies, not references.
  ' Read more: https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow
  m.player.textTracks = textTracks
end sub
```

## Related articles

* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/text-tracks/detect-text-tracks.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/text-tracks/enable-disable-text-tracks.md)

---

# How to programmatically detect text tracks on Roku

This article describes how you can use the TextTrack API to detect text tracks, which can be subtitles, closed captions or metadata. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available subtitle languages.

## Usage

You can use the `addedtexttrack` event to programmatically detect all text tracks which are loaded with the stream.

```brightscript
sub Init()
  ...
  m.THEOplayer.callFunc("addEventListener", "addedtexttrack", m.top, "onEventTextTracksChanged")
  ...
end sub

sub onEventTextTracksChanged()
  textTracks = m.player.textTracks
  print "Text tracks changed. "; textTracks
end sub
```

## Related articles

* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/text-tracks/enable-disable-text-tracks.md)
* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/text-tracks/change-visible-captions.md)

---

# How to programmatically enable or disable text tracks on Roku

This article describes how you can use the TextTrack API to enable or disable subtitles, closed captions or metadata. Implementing this functionality is a common use-case for developers who want to build their own UI to toggle subtitles.

It is advised to disable the text tracks which you do not want to display, in order to avoid issues with overlapping text.

## Usage

To disable all text tracks, iterate through all text tracks and set the `mode` field to `disabled` for each of them.

Note that in BrightScript and SceneGraph you have to assign a whole new associative array to the interface field in order to change the associative array exposed through the interface. Attempts to change fields of an associative array or elements of an array that are values of node fields have no effect.

```brightscript
'disable all tracks
textTracks = m.player.textTracks
for i = textTracks.count() - 1 to 0 step -1
  textTracks[i].mode = "disabled"
end for
' Assignment of new roAssociativeArray is required, because Roku field values are copies, not references.
' Read more: https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow
m.player.textTracks = textTracks

'disable specific track
textTracks = m.player.textTracks
textTracks[indexOfRequestedTextTrack].mode = "disabled"
m.player.textTracks = textTracks
```

## Related articles

* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/text-tracks/change-visible-captions.md)
* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/text-tracks/detect-text-tracks.md)

---

# License on Roku

A THEOplayer license is required to use THEOplayer. The licensing schema was previously based on the built-in license from the SDK build, but THEOplayer now allows you to update the license without rebuilding or re-integrating the player SDK.

This article explains how to configure the license at runtime.

## Passing the license through the player configuration

Pass the license to the `configure` function of the player, either as a license string or as a URL from which the license can be loaded:

```brightscript
' passing the license as a string
m.THEOplayer.callFunc("configure", { license: "your_license_here" })
```

```brightscript
' passing the license as a URL
m.THEOplayer.callFunc("configure", { licenseUrl: "your_licenseUrl_here" })
```

If no valid license can be found, the player will throw a license error.

## FAQ

### Why do I have to configure a license?

In order to provide THEOplayer insights if a stream can be played, it needs to have access to an active license. You can choose to either configure this license, or configure a URL where this license can be retrieved. We recommend everyone to configure an active license or a license URL.

### How do I avoid introducing any dependencies on THEOplayer servers?

There are two important aspects which can introduce a dependency on THEOplayer servers:

1. **Loading a THEOplayer SDK from the THEOplayer CDN.** This issue is only relevant for the Web SDK. In order to avoid this dependency, we recommend to self-host your THEOplayer SDK. The easiest approach is to load the player through npm, or download the player SDK as a zip file from the developer portal. More information on how to self-host your player can be found in "[Self-hosting THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/self-hosting-theoplayer.md)".
2. **Loading a THEOplayer license from the THEOplayer license system.** In order to avoid this dependency, it is important to always keep your license up to date, either by configuring an updated license or by configuring your own license URL. When your THEOplayer license expires, a new player instance will actively check against THEOplayer's license system if there is an updated license available. This system should however only serve as a fallback for applications which cannot be updated.

### Should I pass a license string or a license URL?

We recommend our customers to use the license string whenever possible.

In special cases it is possible to use the license URL instead. Use cases include contractual or legal (for example privacy) requirements. For more information, please contact <support@theoplayer.com>.

If the player is configured with both a license string and a license URL, it will first try to validate the license string. If the license string is either not configured or expired, the player will attempt to request the license URL instead. If no license URL is defined, then a default license URL will be used. If no valid license can be found, the player will throw a license error.

### Should I update my application upon license renewal?

Yes. After renewing your license, you should make sure to include the new THEOplayer license in your next app update.

### What happens if I don't timely update the license in my application?

The player will attempt to update the license up to 72 hours before expiration. For this, the player will request a new license either from the configured license URL, or as a fallback (when there is no license URL configured) from `validate.theoplayer.com`. Either way, if the request is successful, the player will store the license locally. We highly recommend you to self-host the license using the license URL in the player configuration.

For self-hosting, the license file with the latest license string for your application should be hosted. The full URL to this file should then be configured as the license URL in the player configuration.

### Will I still be able to play offline content with my THEOplayer SDK if my license expires?

When your license expires, THEOplayer will attempt to load an updated license. If an updated license is available, offline playback will still function. If no valid license is available, and no license server can be reached (due to the client being offline), the player will throw an error and stop playback. For this reason, it is important to always keep your license up to date.

### What should I do to protect my license?

The THEOplayer license you get from THEOportal is already an obfuscated string. If you want to protect your license, you need to make sure to configure your [page and source domains](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/page-and-source-domains.md) to guarantee that your license string cannot be used anywhere other than the specified pages and/or with those source domains.

---

# Getting started

## Usage

1. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/roku/getting-started.md) to set up THEOplayer in your Roku app.
2. Add an OptiView Live source to your player's source.

### Add an OptiView Live source

After setting up your THEOplayer on your App, set its source to a `SourceDescription` containing a `THEOliveSource`. You'll need an OptiView Live channel ID:

```brightscript
m.THEOsdk.source = {
    "live": true,
    "sources": {
      "src": "your-channel-id",
      "type": "theolive"
    }
}
```

Please note that the playlist feature cannot be used with OptiView Live. On Roku the OptiView Live source falls back to the HLS stream.

### Configure OptiView Live

On the player configuration object, you may add extra configuration using the `theoLive` property on the player configuration. For instance, if you would like to provide an external ID to track the session, you may add it to the `theoLive` configuration:

```brightscript
playerConfiguration = {
  license: "<YOUR_LICENSE_HERE>",
  theoLive: {
    externalSessionId: "my-unique-id"
  }
}
m.player.callFunc("configure", playerConfiguration)
```

## More information

* [API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/api-reference/roku.md)
* [Migrating to OptiView Live v2](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/theolive/migrating-to-v2.md)
* [Discovery URLs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/theolive/discovery-urls.md)

---

# Token based security

OptiView Live offers the option to enable JWT token security on channel distribution level. This can be interesting if you only want valid users to access your stream. Read more about the feature and configuring it on your channels on the [token based security guide](https://docs-preview.optiview.dolby.com/pr-932/theolive/distribution/security/token-based-security.md).

This page will demonstrate how to configure the Roku Player SDK for playback of channels with token based security enabled.

## Setting up the Roku THEOplayer SDK for OptiView Live

Refer to the [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/theolive/getting-started.md) for the prerequisite steps in getting the Roku SDK up and running for OptiView Live playback.

## Configuring THEOplayer to pass the token

The OptiView Live API provides a simple property to configure your token:

```brightscript
token = getToken() // Generate or request your token, for more information check the token based security guide linked above.
player.theolive.authToken = token
```

This will ensure the player includes your token in the authorization header on all subsequent requests it performs for playback of your OptiView Live channel.

## Dealing with token expiry and rotation

If your tokens are short-lived, you want to make sure to update the token being passed to the player and requests before it expires, to allow playback to continue beyond expiry. This can simply be done by updating the header on the player in the same way. For example, one could check on an interval that makes sense for your token lifespan whether the token is about to expire and update when necessary, for example:

Add a Timer to your SceneGraph component to check the token at an interval:

```brightscript
...
  <children>
    <Timer id="tokenTimer" repeat="true" duration="30" />
  </children>
...
```

And in your BrightScript code:

```brightscript
sub init()
    ...

    m.token = ""
    m.player = getPlayer()

    maybeUpdateToken()
    m.tokenTimer = m.top.findNode("tokenTimer")
    m.tokenTimer.observeField("fire", "maybeUpdateToken")
    m.tokenTimer.control = "start"
end sub

sub maybeUpdateToken()
    if m.token = "" or tokenWillExpireSoon(m.token) then
        m.token = getToken() ' Generate or request your token, for more information check the token based security guide linked above.
        m.player.theolive.authToken = m.token
    end if
end sub

function tokenWillExpireSoon(token as String) as Boolean
    parts = token.split(".")
    if parts.count() < 2 then return true

    payloadBase64 = parts[1]
    ba = CreateObject("roByteArray")
    ba.FromBase64String(payloadBase64)
    decodedJson = ParseJson(ba.ToAsciiString())
    if decodedJson = invalid then return true

    exp = decodedJson.exp
    if exp = invalid then return true
    now = Int(CreateObject("roDateTime").AsSeconds())

    return exp - now <= 60
end function
```

## Clearing the token

If the token isn't needed anymore, e.g. when switching to an unprotected channel or a non-OptiView Live source altogether, the header can be simply removed as follows:

```brightscript
player.theolive.authToken = ""
```

---

# Migrating to OptiView Live v2

If you are using OptiView Live v2 for your live streams, you will need to do some extra configuration to successfully play back your OptiView Live streams on Roku.

## Initial Setup

1. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/roku/getting-started.md) to set up THEOplayer in your Roku app.
2. Add an OptiView Live source to your player's source.

### Configure OptiView Live for v2

Since THEOplayer 11.5.0, the player tries the OptiView Live v2 discovery URL first, so v2 sources play without extra configuration. To avoid failed discovery requests, or with earlier versions of THEOplayer, specify one or more discovery URLs. On the player configuration object, you may add the discovery URLs using the `theoLive` property on the player configuration. See [Discovery URLs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/roku/theolive/discovery-urls.md) for more information.

```brightscript
playerConfiguration = {
  license: "<YOUR_LICENSE_HERE>",
  theoLive: {
    discoveryUrls: ["https://discovery.theo.live/v2/distributions/"]
  }
}
m.player.callFunc("configure", playerConfiguration)
```

---

# Discovery URLs

Before the player can play an OptiView Live channel, it sends a discovery request to find the stream details of that channel (such as its manifest URLs and token security settings). OptiView Live channels are served by one of three discovery API versions:

| API version | Channels                                          |
| ----------- | ------------------------------------------------- |
| V1 (legacy) | Channels created with the legacy THEOlive API.    |
| V2          | Distributions created with the OptiView Live API. |
| V3          | Distributions served by the newest discovery API. |

The player does not know in advance which API version serves your channel. If you do not configure a discovery URL, the player tries its built-in discovery URLs one by one, in this order:

1. V2
2. V1 (legacy)
3. V3

The player stops at the first discovery URL that returns the channel. If your channel is not served by V2, the earlier requests fail before the right one succeeds. These failed requests add a small delay before playback starts, and they show up as `404` responses in the network tab of your browser or in a network proxy. The `404` responses are expected and do not mean that playback failed.

## Why configure a discovery URL

When you configure the discovery URL that serves your channel, the player sends its first discovery request to that URL. This removes the failed requests and the extra startup delay.

Configured discovery URLs do not replace the built-in discovery URLs. The player tries them first, and continues with the built-in discovery URLs (V2, V1, V3) if the configured ones do not return the channel. A wrong discovery URL therefore costs one extra request, but it does not break playback.

On platforms that support both `discoveryUrl` and `discoveryUrls`, the player tries `discoveryUrl` first, then each URL of `discoveryUrls` in the order of the list, and then the built-in discovery URLs.

## Which discovery URL to use

The player derives the API version from the path of the discovery URL, so use the URL exactly as listed for your platform, including the trailing `/`. The URL for V1 channels is different on Web than on the other platforms.

| API version | Web                                             | Android, iOS, Roku                              |
| ----------- | ----------------------------------------------- | ----------------------------------------------- |
| V2          | `https://discovery.theo.live/v2/distributions/` | `https://discovery.theo.live/v2/distributions/` |
| V1 (legacy) | `https://discovery.theo.live/`                  | `https://discovery.theo.live/v2/publications/`  |
| V3          | `https://discovery.theo.live/v3/`               | `https://discovery.theo.live/v3/`               |

React Native and Flutter apps pass the discovery URL to the underlying Web, Android or iOS SDK, so the same rules apply per platform.

> **Find the API version of your channel**
>
> Play your channel without a discovery URL and open the network tab of your browser (or a network proxy for a native app). The discovery request that returns `200` shows the discovery URL that serves your channel. For example, a request to `https://discovery.theo.live/v2/distributions/<your-channel-id>` means that your channel is served by V2.

## Configure the discovery URL

Set the discovery URL in the `theoLive` property of the player configuration. For example, for a channel served by V2:

```brightscript
playerConfiguration = {
  license: "<YOUR_LICENSE_HERE>",
  theoLive: {
    discoveryUrl: "https://discovery.theo.live/v2/distributions/"
  }
}
m.player.callFunc("configure", playerConfiguration)
```

If your channels are served by different API versions, list the discovery URLs in the order you want the player to try them:

```brightscript
playerConfiguration = {
  license: "<YOUR_LICENSE_HERE>",
  theoLive: {
    discoveryUrls: [
      "https://discovery.theo.live/v2/distributions/",
      "https://discovery.theo.live/v2/publications/"
    ]
  }
}
m.player.callFunc("configure", playerConfiguration)
```

The player derives the API version from the URL path:

* A URL that contains `/v3/` is a V3 discovery URL.
* A URL that contains `/v2/distributions/` is a V2 discovery URL.
* Any other URL, including `https://discovery.theo.live/v2/publications/`, is a V1 discovery URL.

## Configuration reference

All properties of the [`theoLive` configuration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/api-reference/roku.md#theolive-configuration) are optional.

| Property            | Type               | Description                                                                                                           |
| ------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `discoveryUrl`      | string             | A discovery URL that the player tries before the built-in discovery URLs. Takes precedence over `discoveryUrls`.      |
| `discoveryUrls`     | roArray of strings | A list of discovery URLs that the player tries in order, after `discoveryUrl` and before the built-in discovery URLs. |
| `externalSessionId` | string             | A session ID for your THEOlens session. Use it to link an application session to a THEOlens session.                  |

The default discovery order V2, V1, V3 applies from THEOplayer 11.5.0.

---

# UI on Roku

Choose the approach that fits your requirements:

* Use Open Video UI when you want a custom experience without building common player components yourself.
* Use the chromeless player when you want to start with no UI and build every control and interaction from scratch.
* Use the basic default UI when its ready-made controls meet your needs and one is available.

| Approach      | Starting point                 | Flexibility | Development effort |
| ------------- | ------------------------------ | ----------- | ------------------ |
| Open Video UI | Ready-made, modular components | High        | Moderate           |
| Chromeless    | Player API without a UI        | Complete    | Highest            |
| Default UI    | Complete basic player UI       | Basic       | Lowest             |

Building a chromeless UI means using the OptiView Player API and your own application code without a ready-made UI. You are responsible for adding every control, such as a play button, and connecting it to the player API, such as `player.play()`. This approach gives you total control over the UI and UX, but requires an understanding of video playback and the OptiView Player API.

## Open Video UI

Open Video UI does not currently provide a Roku component library.

## Chromeless

Disable the native controls and build a complete interface with BrightScript and SceneGraph when you need full control over the experience.

## Default UI

The Roku SDK uses the native controls of the `THEOplayer` node. You can use these controls as they are or hide individual elements.

---

# Chromeless UI on Roku

A chromeless Roku player disables the native video controls and implements the complete interface with BrightScript and SceneGraph components.

Choose this approach when the native Roku controls do not meet your layout, branding, focus-management, or track-selection requirements. Your application becomes responsible for all controls, playback feedback, remote interactions, and errors.

Continue with [Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/roku/build-chromeless-ui.md) for the Roku implementation walkthrough.

---

# How to build a chromeless UI on Roku

Building a chromeless UI means building a brand-new video player UI from scratch. You achieve this by implementing your own custom UI components, and by associating those components with the appropriate THEOplayer API. The screenshot below visualizes such a chromeless UI -- albeit not the most pretty one.

![Chromeless UI Layout](/pr-932/assets/images/chromeless-ui-7-4025542f4b233096015b9e6ecce5bcd5.png "Chromeless UI Layout")

A chromeless UI gives you complete control over your full UI and UX, but it also means that you are responsible for implementing your full UI and UX. Achieving this feat requires you to have an adequate grasp on the video player architecture and its underlying API.

The goal of this guide is to advance your understanding on how to connect the dots between custom components and the THEOplayer API. For example, this guide will explain to which THEOplayer APIs you could map your custom play button.

This section will give you an overview on how custom controls can be integrated with the OptiView Player API and also a brief introduction to BrightScript and SceneGraph. We will create play, pause, stop buttons, add audio and text tracks management menu and create a simple timeline.

## Display chromeless player

To display the video in chromeless THEOplayer we have to take a few steps:

Include and add the instance of THEOplayer.

```xml
  <THEOsdk:THEOplayer id="TestPlayer" controls="false"/>
```

Set the "controls" attribute to "false" to hide all default controls.

```brightscript
sub Init()
    m.player = m.top.findNode("TestPlayer")
    m.player.configuration = {
      "license": "<YOUR_LICENSE_STRING>"
    }
    ' we can go chromeless both via XML or Brightscript'
    ' m.player.controls = false
end sub
```

To set the player source, you can create the following function and then just call it inside the "init" function.

```brightscript
sub setSource()
    sourceDescription = {
        "sources": [
            {
                "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
                "type": "application/x-mpegURL"
            }
        ]
    }
    m.player.source = sourceDescription
end sub
```

To make sure that the player will be displayed in a proper position you can set a destination rectangle. In our example we will display the video in a rectangle (1600x800) positioned in the middle of the screen using the "setDestinationRectangle" THEOplayer method.

```brightscript
sub setupPlayerPosition()
    uiRes = m.top.getScene().currentDesignResolution
    m.uiRes = uiRes
    playerRect = {
        width: 1600,
        height: 800,
        x: (m.uiRes.width - 1600) / 2,
        y: (m.uiRes.height - 800) / 2
    }
    m.player.callFunc("setDestinationRectangle", playerRect)
end sub
```

When all is set up, all we have to do is to play the video using the "play" method.

```brightscript
m.player.callFunc("play")
```

**Notice: The "play" method call is mandatory, otherwise the video playback won’t start and users won’t be able to use remote controls.**

Below you can see the whole working example. The BrightScript code in this snippet is added inside the component xml file, but you can easily extract the logic part to separate ".brs" file by using "script" tag with a specified "uri" field.

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="TestScene" extends="Scene">
    <interface>

    </interface>

    <script type = "text/brightscript" >

        <![CDATA[

        sub Init()
            m.player = m.top.findNode("TestPlayer")
            m.player.configuration = {
              "license": "<YOUR_LICENSE_STRING>"
            }
            ' we can go chromeless both via XML or Brightscript'
            ' m.player.controls = false

            m.player.callFunc("setMaxVideoResolution", 1920, 1080)
            setupPlayerPosition()
            setSource()
            m.top.setFocus(true)
            m.player.callFunc("play")
        end sub

        sub setSource()
            sourceDescription = {
                "sources": [
                    {
                        "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
                        "type": "application/x-mpegURL"
                    }
                ]
            }
            m.player.source = sourceDescription
        end sub

        sub setupPlayerPosition()
            uiRes = m.top.getScene().currentDesignResolution
            m.uiRes = uiRes
            playerRect = {
                width: 1600,
                height: 800,
                x: (m.uiRes.width - 1600) / 2,
                y: (m.uiRes.height - 800) / 2
            }
            m.player.callFunc("setDestinationRectangle", playerRect)
        end sub

        ]]>

    </script>

    <children>
	    <THEOsdk:THEOplayer id="TestPlayer" controls="false"/>
    </children>
</component>
```

## Control bar Play, Pause, Stop buttons

To create a control bar with play, pause and stop buttons, generally we would need to create custom UI elements (buttons) and call the api methods when they are played. To accomplish that we have to take the following steps:

Let's start with creating the UI elements which are simply xml elements. We will add three buttons (play, pause and stop), along with timeline bar.

```xml
<Group id="playerOverlay">
	<Group id="GroupOptions">
		<Rectangle id="OptionsBackground" color="0x000000FF" height="47" width="10" opacity="0.5"/>
		<Rectangle id="TimelineBackground" height="3" width="0" opacity="0.3"/>
		<Rectangle id="TimelineProgress" height="3" width="0" color="0xFFC713FF"/>

		<ButtonGroup id="ButtonGroupOptions" layoutDirection="horiz">
			<Button id="ButtonPlay" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
				<Poster width="75" height="65" id="playIcon" uri="pkg:/images/play.png" translation="[20,15]" opacity="0.9"/>
			</Button>
			<Button id="ButtonPause" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
				<Poster width="75" height="65" id="pauseIcon" uri="pkg:/images/pause.png" translation="[20,15]" opacity="0.9"/>
			</Button>
			<Button id="ButtonStop" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
				<Poster id="stopIcon" uri="pkg:/images/stop.png" width="75" height="65" translation="[20,15]" opacity="0.9"/>
			</Button>
		</ButtonGroup>
	</Group>
</Group>
```

Next step would be adding callback on buttons press. To do so, we will use [roku native observe mechanism](https://developer.roku.com/en-gb/docs/developer-program/core-concepts/handling-application-events.md#handling-node-field-value-changes).

```brightscript
sub Init()
	m.player = m.top.findNode("TestPlayer")
	m.player.configuration = {
      "license": "<YOUR_LICENSE_STRING>"
    }
	m.buttonPlay = m.top.findNode("ButtonPlay")
	m.buttonPause = m.top.findNode("ButtonPause")
	m.buttonStop = m.top.findNode("ButtonStop")

	setupPlayerPosition()
	setupControlsPosition()
	setSource()

	m.buttonPlay.setFocus(true)

	m.buttonPlay.observeField("buttonSelected", "OnEventPlay")
	m.buttonPause.observeField("buttonSelected", "OnEventPause")
	m.buttonStop.observeField("buttonSelected", "OnEventStop")

end sub

sub OnEventPlay()

end sub

sub OnEventPause()

end sub

sub OnEventStop()

end sub
```

The next step would be calling the THEOplayer api methods inside our callback. To do so, we will modify the callbacks:

```brightscript
sub OnEventPlay()
	if m.player.source = Invalid
		setSource()
	end if
	m.player.callFunc("play")
end sub

sub OnEventPause()
	m.player.callFunc("pause")
end sub

sub OnEventStop()
	m.player.source = Invalid
end sub
```

Last thing left to do is to make the timeline work. We will add an event listener to an event "timeUpdate". This listener will allow us to react to every time update, so we can draw the current progress in playing video.

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="TestScene" extends="Scene">
    <interface>

        <function name="callbackOnEventPlayerTimeupdate"/>

    </interface>

    <script type = "text/brightscript" >

        <![CDATA[

        sub Init()
            m.player = m.top.findNode("TestPlayer")
            m.player.configuration = {
              "license": "<YOUR_LICENSE_STRING>"
            }
            m.buttonPlay = m.top.findNode("ButtonPlay")
            m.buttonPause = m.top.findNode("ButtonPause")
            m.buttonStop = m.top.findNode("ButtonStop")

            m.player.callFunc("setMaxVideoResolution", 1920, 1080)
            setupPlayerPosition()
            setupControlsPosition()

            setSource()
            m.buttonPlay.setFocus(true)

            m.buttonPlay.observeField("buttonSelected", "OnEventPlay")
            m.buttonPause.observeField("buttonSelected", "OnEventPause")
            m.buttonStop.observeField("buttonSelected", "OnEventStop")

            m.player.listener = m.top
            m.player.callFunc("addEventListener", m.player.Event.c, "callbackOnEventPlayerTimeupdate")
        end sub

        sub setSource()
            sourceDescription = {
                "sources": [
                    {
                        "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
                        "type": "hls"
                    }
                ]
            }
            m.player.source = sourceDescription
        end sub

        sub setupPlayerPosition()
            uiRes = m.top.getScene().currentDesignResolution
            m.uiRes = uiRes
            playerRect = {
                width: 1600,
                height: 800,
                x: (m.uiRes.width - 1600) / 2,
                y: (m.uiRes.height - 800) / 2
            }
            m.player.callFunc("setDestinationRectangle", playerRect)
        end sub

        sub setupControlsPosition()
            buttons = [m.buttonPlay, m.buttonPause, m.buttonStop]
            buttonsWidth = 0

            for each button in buttons
                ' get rid of focus footprint on the buttons
                button.removeChildIndex(1)

                ' -20 because of buttons ovelaping and scale
                buttonsWidth += button.minWidth - 20
            end for

            uiRes = m.top.getScene().currentDesignResolution
            playerRect = m.player.boundingRect()
            playerBottomX = playerRect.width + playerRect.x
            playerBottomY = playerRect.height + playerRect.y
            m.groupOptions = m.top.findNode("GroupOptions")
            m.buttonGroupOptions = m.top.findNode("ButtonGroupOptions")
            m.groupOptionsVisible = true
            buttonGroupOptionsRect = m.buttonGroupOptions.boundingRect()
            centerY = playerRect.y + playerRect.height - buttonGroupOptionsRect.height
            centerX = playerRect.x
            m.groupOptions.translation = [centerX, centerY]
            centerX = (playerRect.width - buttonsWidth / 2) / 2
            m.buttonGroupOptions.translation = [centerX, 3]

            m.optionsBackground = m.top.findNode("OptionsBackground")
            m.optionsBackground.width = playerRect.width
            m.timelineBackground = m.top.findNode("TimelineBackground")
            m.timelineBackground.width = playerRect.width

            m.timelineProgress = m.top.findNode("TimelineProgress")
            m.timelineProgress.width = 1
        end sub

        sub callbackOnEventPlayerTimeupdate(eventData)
            'update movie timeline bar
            if m.player.duration > 0 and m.player.currentTime < m.player.duration
                rect = m.player.boundingRect()
                m.timelineProgress.width = rect.width * ( m.player.currentTime / m.player.duration )
            end if
        end sub

        sub OnEventPlay()
            if m.player.source = Invalid
                setSource()
            end if

            m.player.callFunc("play")
        end sub

        sub OnEventPause()
            m.player.callFunc("pause")
        end sub

        sub OnEventStop()
            m.player.source = Invalid
        end sub

        ]]>

    </script>

    <children>
	    <THEOsdk:THEOplayer id="TestPlayer" controls="false"/>

        <Group id="playerOverlay">
            <Group id="GroupOptions">
                <Rectangle id="OptionsBackground" color="0x000000FF" height="47" width="10" opacity="0.5"/>
                <Rectangle id="TimelineBackground" height="3" width="0" opacity="0.3"/>
                <Rectangle id="TimelineProgress" height="3" width="0" color="0xFFC713FF"/>

                <ButtonGroup id="ButtonGroupOptions" layoutDirection="horiz">
                    <Button id="ButtonPlay" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">

                        <Poster width="75" height="65" id="playIcon" uri="pkg:/images/play.png" translation="[20,15]" opacity="0.9"/>
                    </Button>
                    <Button id="ButtonPause" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">

                        <Poster width="75" height="65" id="pauseIcon" uri="pkg:/images/pause.png" translation="[20,15]" opacity="0.9"/>
                    </Button>
                    <Button id="ButtonStop" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">

                        <Poster id="stopIcon" uri="pkg:/images/stop.png" width="75" height="65" translation="[20,15]" opacity="0.9"/>
                    </Button>
                </ButtonGroup>

            </Group>
        </Group>
    </children>
</component>
```

## Control bar Switch audio or text tracks

Now, let’s add an audio or text track management menu. In this portion, we will use a fresh SceneGraph component (RadioButtonList). We will use other callbacks, API methods and attributes. The main steps which we have to take to accomplish the desired outcome are:

Create an empty RadioButtonList component:

```xml
<RadioButtonList
    id="ButtonGroupCategoryFirst"
    opacity="1"
    focusBitmapUri="pkg:/images/focusBG.png"
    focusedColor="0xFFFFFFFF"
    color="0xFFFFFFFF"
    itemSize="[300,65]"
    translation="[0,65]">
</RadioButtonList>
```

Add the content to our list. To do so, we will observe audio tracks and assign the audio tracks list to a previously created radio button list.

```brightscript
sub onEventAudioTracksChanged()
    list = createObject("roSGNode","ContentNode")
    option = list.createChild("ContentNode")
    option.title = "default"
    option.description = "default"
    option.id = ""
    checkedItem = 0
    index = 1
    for each track in m.player.audioTracks
        option = list.createChild("ContentNode")
        option.title = track.label
        option.description = track.language
        option.id = track.id
        if track.enabled then
            checkedItem = index
        end if
        index +=1
    end for

    optionsCount = 0
    if Type(m.buttonGroupCategorySecond.content) <> "roInvalid" then
        optionsCount = m.buttonGroupCategorySecond.content.count()
    end if
    if list.count() <> optionsCount then
        m.buttonGroupCategorySecond.content = list
        m.buttonGroupCategorySecond.checkedItem = checkedItem
        setAudioMenuPosition()
    end if
end sub
```

The next step would be managing a focus of the remote.

```brightscript
function OnKeyEvent(key, press) as Boolean
    handled = false
    showOptions()
    if press
        if key = "options"
        else if m.player.visible = true and key = "back"
            ' Settings Menu opened
            if m.settingsOptions.visible = true
                hideSettings()
                handled = true
            ' category 1 Menu opened
            else if m.categoryFirstOptions.visible = true then
                hideCategoryFirst()
                handled = true
            ' category 2 Menu opened
            else if m.categorySecondOptions.visible = true then
                hideCategorySecond()
                handled = true
            else
                m.player.source = Invalid
            end if
        else if key = "up"
            if m.settingsOptions.visible = true and m.buttonCategoryFirst.hasFocus() = true
                hideSettings()
                handled = true
            ' category 1 Menu opened
            ' else if m.categoryFirstOptions.visible = true and m.buttonGroupCategoryFirst.hasFocus() = true then
            '     hideCategoryFirst()
            '     handled = true
            ' category 2 Menu opened
            else if m.categorySecondOptions.visible = true and m.categorySecondButtonFirst.hasFocus() = true then
                hideCategorySecond()
                handled = true
            end if
        end if
    end if

    return handled
end function
```

In order to allow the user to change audio tracks, we have to prepare a function which will change audio track.

```brightscript
sub setAudioTrack(label as String)
    audioTracks =  m.player.audioTracks
    for i =  audioTracks.count() - 1 to 0 step -1
        if audioTracks[i].label = label then
            audioTracks[i].enabled = true
        else
            audioTracks[i].enabled = false
        end if
    end for
    'required because roku deep-copied roAssociativeArray through fields (pass-by-value)
    'read more : <https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow>
    m.player.audioTracks = audioTracks
end sub

sub OnEventCategorySecondSelectedItem()
    if m.player.instance <> Invalid
        itemIndex = m.buttonGroupCategorySecond.checkedItem
        item = m.buttonGroupCategorySecond.content.getChild(itemIndex)
        setAudioTrack(item.title)
    end if
end sub
```

To complete this functionality, we will add an observer to the radio button list and call the setAudioTrack function.

```brightscript
sub OnEventCategoryFirstSelectedItem()
    if m.player.instance <> Invalid
        itemIndex = m.buttonGroupCategoryFirst.checkedItem
        item = m.buttonGroupCategoryFirst.content.getChild(itemIndex)
        setCaptionsLanguage(item.description)
    end if
end sub
```

You can find the whole example below. This example contains two menus which allow users to manipulate audio and text tracks.

```xml
<?xml version="1.0" encoding="utf-8" ?>

<component name="TestScene" extends="Scene">

    <interface>

        <function name="callbackOnEventPlayerTimeupdate"/>

    </interface>

    <script type="text/brightscript">
        <![CDATA[

        sub Init()
            SetupUI()
            SetupObservers()
            SetupEventListeners()
        end sub

        sub SetupUI()
            m.buttonPlay = m.top.findNode("ButtonPlay")
            m.buttonPause = m.top.findNode("ButtonPause")
            m.buttonStop = m.top.findNode("ButtonStop")
            m.buttonSettings = m.top.findNode("ButtonSettings")
            m.categoryFirstHeaderBackground = m.top.findNode("CategoryFirstHeaderBackground")
            m.settingsOptions = m.top.findNode("SettingsOptions")
            m.buttonCategoryFirst = m.top.findNode("ButtonCategoryFirst")
            m.buttonCategorySecond = m.top.findNode("ButtonCategorySecond")
            m.categoryFirstButtonFirst = m.top.findNode("CategoryFirstButtonFirst")
            m.categorySecondButtonFirst = m.top.findNode("CategorySecondButtonFirst")

            m.player = m.top.findNode("TestPlayer")
            m.player.configuration = {
              "license": "<YOUR_LICENSE_STRING>"
            }
            SetupPlayerPosition()
            SetControlsPosition()

            setSource()
            m.buttonPlay.setFocus(true)
        end sub

        sub SetupObservers()
            m.player.observeField("audioTracks","onEventAudioTracksChanged")
            m.player.observeField("textTracks","onEventTextTracksChanged")

            m.buttonPlay.observeField("buttonSelected", "OnEventPlay")
            m.buttonPause.observeField("buttonSelected", "OnEventPause")
            m.buttonStop.observeField("buttonSelected", "OnEventStop")
            m.buttonSettings.observeField("buttonSelected", "OnEventSettings")

            m.buttonCategoryFirst.observeField("buttonSelected", "OnEventCategoryFirst")
            m.buttonGroupCategoryFirst.observeField("itemFocused", "OnEventCategoryFirstFocusedItem")
            m.buttonGroupCategoryFirst.observeField("checkedItem", "OnEventCategoryFirstSelectedItem")

            m.buttonCategorySecond.observeField("buttonSelected", "OnEventCategorySecond")
            m.buttonGroupCategorySecond.observeField("itemFocused", "OnEventCategorySecondFocusedItem")
            m.buttonGroupCategorySecond.observeField("checkedItem", "OnEventCategorySecondSelectedItem")
        end sub

        sub SetupEventListeners()
            m.player.listener = m.top
            m.player.callFunc("addEventListener", m.player.Event.timeupdate, "callbackOnEventPlayerTimeupdate")
        end sub

        sub SetupPlayerPosition()
            m.uiRes = m.top.getScene().currentDesignResolution
            m.timelineProgress = m.top.findNode("TimelineProgress")
            m.timelineProgress.width = 1
            'm.player.callFunc("setMaxVideoResolution", m.uiRes.width, m.uiRes.height)
            ' center video'
            'playerRect = {
            ''    width: m.uiRes.width,
            ''    height: m.uiRes.height,
            ''    x: 0,
            ''    y: 0
            ''}
            'm.player.callFunc("setDestinationRectangle", playerRect)
        end sub

        sub SetControlsPosition()
            buttons = [m.buttonPlay, m.buttonPause, m.buttonStop, m.buttonSettings]
            buttonsWidth = 0

            for each button in buttons
                ' get rid of focus footprint on the buttons
                button.removeChildIndex(1)

                ' -20 because of buttons ovelaping and scale
                buttonsWidth += button.minWidth - 20
            end for
            playerRect = m.player.boundingRect()
            playerBottomX = playerRect.width + playerRect.x
            playerBottomY = playerRect.height + playerRect.y
            m.groupOptions = m.top.findNode("GroupOptions")
            m.buttonGroupOptions = m.top.findNode("ButtonGroupOptions")
            m.groupOptionsVisible = true
            buttonGroupOptionsRect = m.buttonGroupOptions.boundingRect()
            centerY = playerRect.y + playerRect.height - buttonGroupOptionsRect.height
            centerX = playerRect.x
            m.groupOptions.translation = [centerX, centerY]
            centerX = (playerRect.width - buttonsWidth / 2) / 2
            m.buttonGroupOptions.translation = [centerX, 3]

            m.optionsBackground = m.top.findNode("OptionsBackground")
            m.optionsBackground.width = playerRect.width
            m.timelineBackground = m.top.findNode("TimelineBackground")
            m.timelineBackground.width = playerRect.width

            m.settingsOptions = m.top.findNode("SettingsOptions")
            m.buttonGroupSettings = m.top.findNode("ButtonGroupSettings")
            settingsRect = m.settingsOptions.boundingRect()
            buttonGroupSettingsRect = m.buttonGroupSettings.boundingRect()
            groupOptionsRect = m.groupOptions.boundingRect()
            centerX = playerBottomX - buttonGroupSettingsRect.x - settingsRect.width - 20
            centerY = playerBottomY - buttonGroupSettingsRect.y - settingsRect.height - 20
            m.settingsOptions.translation = [centerX, centerY ]

            m.categoryFirstOptions = m.top.findNode("CategoryFirstOptions")
            m.categoryFirstBackground = m.top.findNode("CategoryFirstBackground")
            m.buttonGroupCategoryFirst = m.top.findNode("ButtonGroupCategoryFirst")
            SetClosedCaptionsMenuPosition()

            m.categorySecondOptions = m.top.findNode("CategorySecondOptions")
            m.categorySecondBackground = m.top.findNode("CategorySecondBackground")
            m.buttonGroupCategorySecond = m.top.findNode("ButtonGroupCategorySecond")
            SetAudioMenuPosition()
        end sub

        sub SetClosedCaptionsMenuPosition()
            playerRect = m.player.boundingRect()
            playerBottomX = playerRect.width + playerRect.x
            playerBottomY = playerRect.height + playerRect.y
            categoryFirstRect = m.categoryFirstOptions.boundingRect()
            categoryFirstButtonGroupRect = m.buttonGroupCategoryFirst.boundingRect()
            centerX = playerBottomX - categoryFirstButtonGroupRect.x - categoryFirstRect.width - 20
            centerY = playerBottomY - categoryFirstButtonGroupRect.y - categoryFirstRect.height - m.categoryFirstHeaderBackground.height - 20
            m.categoryFirstOptions.translation = [centerX, centerY]
            m.categoryFirstBackground.height = categoryFirstRect.height + 30 ' added 30 because radio group shows separator
            if playerRect.x = 0 or playerRect.y = 0 or playerRect.width = m.uiRes.width or playerRect.height = m.uiRes.height then
                m.fullScreen = true
                if m.player.textTracks.count() > 0
                    m.buttonCategoryFirst.textColor = "0xFFFFFFFF"
                    m.buttonCategoryFirst.focusedTextColor = "0xFFFFFFFF"
                else
                    m.buttonCategoryFirst.textColor = "0x666666FF"
                    m.buttonCategoryFirst.focusedTextColor = "0x666666FF"
                end if
            else
                m.fullScreen = false
                m.buttonCategoryFirst.textColor = "0x666666FF"
                m.buttonCategoryFirst.focusedTextColor = "0x666666FF"
            end if
        end sub

        sub SetAudioMenuPosition()
            playerRect = m.player.boundingRect()
            playerBottomX = playerRect.width + playerRect.x
            playerBottomY = playerRect.height + playerRect.y
            categorySecondOptionsRect = m.categorySecondOptions.boundingRect()
            categorySecondButtonGroupRect = m.buttonGroupCategorySecond.boundingRect()
            centerX = playerBottomX - categorySecondButtonGroupRect.x - categorySecondOptionsRect.width - 20
            centerY = playerBottomY - categorySecondButtonGroupRect.y - categorySecondOptionsRect.height - 20
            m.categorySecondOptions.translation = [centerX, centerY]
            m.categorySecondBackground.height = categorySecondOptionsRect.height
            isNode = Type(m.buttonGroupCategorySecond.content) = "roSGNode"
            if isNode then
                m.buttonCategorySecond.textColor = "0xFFFFFFFF"
                m.buttonCategorySecond.focusedTextColor = "0xFFFFFFFF"
            else
                m.buttonCategorySecond.textColor = "0x666666FF"
                m.buttonCategorySecond.focusedTextColor = "0x666666FF"
            end if
        end sub

        sub callbackOnEventPlayerTimeupdate(eventData)
            ? "Event <timeupdate>: "; eventData

            'update movie timeline bar
            if m.player.duration > 0 and m.player.currentTime < m.player.duration
                rect = m.player.boundingRect()
                m.timelineProgress.width = rect.width * ( m.player.currentTime / m.player.duration )
            end if
        end sub

        sub setSource()
            sourceDescription = {
                "poster": ""
                "sources": [
                    {
                        "src": "http://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8",
                        "live": m.live,
                        "type": "application/x-mpegURL"
                    }
                ]
            }
            m.player.source = sourceDescription
        end sub

        sub OnEventPlay()
            if m.player.source = Invalid
                setSource()
            end if

            m.player.callFunc("play")
        end sub

        sub hideOptions()
            if m.groupOptionsVisible = true
                m.groupOptionsVisible = false
                hideCategoryFirst()
                hideCategorySecond()
                hideSettings()
            end if
        end sub

        sub showOptions()
            if m.groupOptionsVisible = false
                m.groupOptionsVisible = true
            end if
        end sub

        sub showCategoryFirst()
            hideSettings()
            m.categoryFirstOptions.visible = true
            m.buttonGroupCategoryFirst.setFocus(true)
        end sub

        sub hideCategoryFirst()
            if  m.categoryFirstOptions.visible = true
                m.categoryFirstOptions.visible = false
                showSettings()
            end if
        end sub

        sub showCategorySecond()
            hideSettings()
            m.categoryFirstOptions.visible = true
            m.categorySecondButtonFirst.setFocus(true)
        end sub

        sub hideCategorySecond()
            if m.categorySecondOptions.visible = true
                m.categorySecondOptions.visible = false
                showSettings()
            end if
        end sub

        sub showSettings()
            m.settingsOptions.visible = true
            m.buttonCategoryFirst.setFocus(true)
        end sub

        sub hideSettings()
            if m.settingsOptions.visible = true
                m.settingsOptions.visible = false
                m.buttonSettings.setFocus(true)
            end if
        end sub

        sub OnEventPause()
            m.player.callFunc("pause")
        end sub

        sub OnEventStop()
            m.player.source = Invalid
        end sub

        sub OnEventCategoryFirst()
            isNode = Type(m.buttonGroupCategoryFirst.content) = "roSGNode"
            if isNode and m.fullScreen
                m.settingsOptions.visible = false
                m.categoryFirstOptions.visible = true
                m.buttonGroupCategoryFirst.setFocus(true)
            end if
        end sub

        sub OnEventCategorySecond()
            isNode = Type(m.buttonGroupCategorySecond.content) = "roSGNode"
            if isNode
                m.settingsOptions.visible = false
                m.categorySecondOptions.visible = true
                m.buttonGroupCategorySecond.setFocus(true)
            end if
        end sub

        sub onEventAudioTracksChanged()
            list = createObject("roSGNode","ContentNode")
            option = list.createChild("ContentNode")
            option.title = "default"
            option.description = "default"
            option.id = ""
            checkedItem = 0
            index = 1
            for each track in m.player.audioTracks
                option = list.createChild("ContentNode")
                option.title = track.label
                option.description = track.language
                option.id = track.id
                if track.enabled then
                    checkedItem = index
                end if
                index +=1
            end for

            optionsCount = 0
            if Type(m.buttonGroupCategorySecond.content) <> "roInvalid" then
                optionsCount = m.buttonGroupCategorySecond.content.count()
            end if
            if list.count() <> optionsCount then
                m.buttonGroupCategorySecond.content = list
                m.buttonGroupCategorySecond.checkedItem = checkedItem
                setAudioMenuPosition()
            end if
        end sub

        sub onEventTextTracksChanged()
            list = createObject("roSGNode","ContentNode")
            option = list.createChild("ContentNode")
            option.title = "default"
            option.description = "default"
            option.id = ""
            checkedItem = 0
            index = 1
            for each track in m.player.textTracks
                if track.kind = "captions"
                    option = list.createChild("ContentNode")
                    option.title = track.label
                    option.description = track.language
                    option.id = track.id
                    if track.mode = "showing" then
                        checkedItem = index
                    end if
                    index +=1
                end if
            end for

            optionsCount = 0
            if Type(m.buttonGroupCategoryFirst.content) <> "roInvalid" then
                optionsCount = m.buttonGroupCategoryFirst.content.count()
            end if
            if list.count() <> optionsCount then
                m.buttonGroupCategoryFirst.content = list
                m.buttonGroupCategoryFirst.checkedItem = checkedItem
                setClosedCaptionsMenuPosition()
            end if
        end sub

        sub OnEventSettings()
            if m.settingsOptions.visible = false
                m.settingsOptions.visible = true
                m.buttonCategoryFirst.setFocus(true)
            else
                m.settingsOptions.visible = false
            end if
        end sub

        sub OnEventCategoryFirstFocusedItem()
            showOptions()
        end sub

        sub setCaptionsLanguage(language as String)
            textTracks =  m.player.textTracks
            for i =  textTracks.count() - 1 to 0 step -1
                if textTracks[i].kind = "captions" and textTracks[i].language = language then
                    if m.fullScreen then
                        textTracks[i].mode = "showing"
                    else
                        textTracks[i].mode = "hidden"
                    end if
                else
                    textTracks[i].mode = "disabled"
                end if
            end for
            'assigment of new roAssociativeArray is required because roku deep-copied roAssociativeArray through fields (pass-by-value)
            'read more : <https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow>
            m.player.textTracks = textTracks
        end sub

        sub OnEventCategoryFirstSelectedItem()
            if m.player.instance <> Invalid
                itemIndex = m.buttonGroupCategoryFirst.checkedItem
                item = m.buttonGroupCategoryFirst.content.getChild(itemIndex)
                setCaptionsLanguage(item.description)
            end if
        end sub

        sub OnEventCategorySecondFocusedItem()
            showOptions()
        end sub

        sub setAudioTrack(label as String)
            audioTracks =  m.player.audioTracks
            for i =  audioTracks.count() - 1 to 0 step -1
                if audioTracks[i].label = label then
                    audioTracks[i].enabled = true
                else
                    audioTracks[i].enabled = false
                end if
            end for
            'required because roku deep-copied roAssociativeArray through fields (pass-by-value)
            'read more : <https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow>
            m.player.audioTracks = audioTracks
        end sub

        sub OnEventCategorySecondSelectedItem()
            if m.player.instance <> Invalid
                itemIndex = m.buttonGroupCategorySecond.checkedItem
                item = m.buttonGroupCategorySecond.content.getChild(itemIndex)
                setAudioTrack(item.title)
            end if
        end sub

        function OnKeyEvent(key, press) as Boolean
            handled = false
            showOptions()
            if press
                if key = "options"
                else if m.player.visible = true and key = "back"
                    ' Settings Menu opened
                    if m.settingsOptions.visible = true
                        hideSettings()
                        handled = true
                    ' category 1 Menu opened
                    else if m.categoryFirstOptions.visible = true then
                        hideCategoryFirst()
                        handled = true
                    ' category 2 Menu opened
                    else if m.categorySecondOptions.visible = true then
                        hideCategorySecond()
                        handled = true
                    else
                        m.player.source = Invalid
                    end if
                else if key = "up"
                    if m.settingsOptions.visible = true and m.buttonCategoryFirst.hasFocus() = true
                        hideSettings()
                        handled = true
                    ' category 1 Menu opened
                    ' else if m.categoryFirstOptions.visible = true and m.buttonGroupCategoryFirst.hasFocus() = true then
                    '     hideCategoryFirst()
                    '     handled = true
                    ' category 2 Menu opened
                    else if m.categorySecondOptions.visible = true and m.categorySecondButtonFirst.hasFocus() = true then
                        hideCategorySecond()
                        handled = true
                    end if
                end if
            end if

            return handled
        end function

        ]]>
    </script>
    <children>
	    <THEOsdk:THEOplayer id="TestPlayer" controls="false"/>

        <Group id="playerOverlay">
            <Group id="GroupOptions">
                <Rectangle id="OptionsBackground" color="0x000000FF" height="47" width="10" opacity="0.5"/>
                <Rectangle id="TimelineBackground" height="3" width="0" opacity="0.3"/>
                <Rectangle id="TimelineProgress" height="3" width="0" color="0xFFC713FF"/>

                <ButtonGroup id="ButtonGroupOptions" layoutDirection="horiz">
                    <Button id="ButtonPlay" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
                        <Poster width="75" height="65" id="playIcon" uri="pkg:/images/play.png" translation="[20,15]" opacity="0.9"/>
                    </Button>
                    <Button id="ButtonPause" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
                        <Poster width="75" height="65" id="pauseIcon" uri="pkg:/images/pause.png" translation="[20,15]" opacity="0.9"/>
                    </Button>
                    <Button id="ButtonStop" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
                        <Poster id="stopIcon" uri="pkg:/images/stop.png" width="75" height="65" translation="[20,15]" opacity="0.9"/>
                    </Button>
                    <Button id="ButtonSettings" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
                        <Poster id="settingsIcon" uri="pkg:/images/settings.png" width="75" height="65" translation="[20,15]" opacity="0.9"/>
                    </Button>
                </ButtonGroup>

            </Group>

            <Group id="SettingsOptions" visible="false">
                <Rectangle id="SettingsBackground" color="0x000000FF" width="500" height="215" translation="[-15,0]" opacity="0.5"/>
                <Rectangle id="SettingsHeaderBackground" color="0xFFC713FF" width="500" height="65" translation="[-15,0]">
                    <Label text="Settings" height="65" width="470" horizAlign="center" vertAlign="center" font="font:SmallestBoldSystemFont"/>
                </Rectangle>

                <ButtonGroup id="ButtonGroupSettings" layoutDirection="vert" vertAlignment="top" translation="[0,65]" opacity="1">
                    <Button
                        id="ButtonCategoryFirst"
                        iconUri=""
                        focusedIconUri=""
                        focusBitmapUri="pkg:/images/focusBG.png"
                        maxWidth="470"
                        minWidth="470"
                        height="65"
                        opacity="0.9"
                        text="Captions"
                        focusedTextColor="0xFFFFFFFF"
                        textFont="font:SmallestBoldSystemFont"
                        focusedTextFont="font:SmallestBoldSystemFont"></Button>
                    <Button
                        id="ButtonCategorySecond"
                        iconUri=""
                        focusedIconUri=""
                        focusBitmapUri="pkg:/images/focusBG.png"
                        maxWidth="470"
                        minWidth="470"
                        height="65"
                        opacity="0.9"
                        text="Audio Tracks"
                        focusedTextColor="0xFFFFFFFF"
                        textFont="font:SmallestBoldSystemFont"
                        focusedTextFont="font:SmallestBoldSystemFont"></Button>
                </ButtonGroup>
            </Group>

            <Group id="CategoryFirstOptions" visible="false">
                <Rectangle id="CategoryFirstBackground" color="0x000000FF" width="300" height="0" opacity="0.5"/>
                <Rectangle id="CategoryFirstHeaderBackground" color="0xFFC713FF" width="300" height="65">
                    <Label text="Captions" height="65" width="300" horizAlign="center" vertAlign="center" font="font:SmallestBoldSystemFont"/>
                </Rectangle>

                <RadioButtonList
                    id="ButtonGroupCategoryFirst"
                    opacity="1"
                    focusBitmapUri="pkg:/images/focusBG.png"
                    focusedColor="0xFFFFFFFF"
                    color="0xFFFFFFFF"
                    itemSize="[300,65]"
                    translation="[0,65]">
                </RadioButtonList>
            </Group>
            <Group id="CategorySecondOptions" visible="false">
                <Rectangle id="CategorySecondBackground" color="0x000000FF" width="300" height="0" opacity="0.5"/>
                <Rectangle id="CategorySecondHeaderBackground" color="0xFFC713FF" width="300" height="65">
                    <Label text="Audio Tracks" height="65" width="300" vertAlign="center" horizAlign="center" font="font:SmallestBoldSystemFont"/>
                </Rectangle>

                <RadioButtonList
                    id="ButtonGroupCategorySecond"
                    opacity="1"
                    focusBitmapUri="pkg:/images/focusBG.png"
                    focusedColor="0xFFFFFFFF"
                    color="0xFFFFFFFF"
                    itemSize="[300,65]"
                    translation="[0,65]">
                </RadioButtonList>
            </Group>
        </Group>
    </children>
</component>
```

## Sample code

The GitHub project at <https://github.com/THEOplayer/samples-roku-sdk/tree/master/basic-playback-app/components/ChromelessView> provides a basic implementation of a chromeless UI on the Roku SDK.

## UX enhancements

You can make your user-experience more appealing through various enhancements. For example, when the player is out of video data and is waiting for additional content you could show a 'loading' indication.

Below are some common UX enhancements to consider:

1. Loading spinner: provide an indication when no video data is available.
2. Poster: show a poster (thumbnail) before initial play-request, and when the video is complete.
3. Auto next: when approaching the end, render a clickable overlay that allows the viewer to navigate to the next stream. Automatically play this stream when the current stream ends.
4. Skip intro: render a clickable button to skip the (ongoing) intro.
5. Ad countdown: overlay the remaining time of the ongoing ad break.
6. Ad markers: indicate the position of ad breaks in the scrub bar.

## Error handling

A UI should also be capable of handling errors and informing the viewer. Refer to our [introduction on errors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/error/introduction.md) to further explore this topic.

---

# Default UI on Roku

The OptiView Player Roku SDK uses the controls provided by Roku's native video node. Use this UI when the platform-native playback experience meets your requirements.

You can show the complete control set, remove individual native elements, or disable the controls and build a chromeless SceneGraph interface.

Continue with [Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/roku/default-ui/getting-started.md) to enable the native controls.

---

# Getting started with the default UI on Roku

The Roku SDK displays native controls when the `controls` field on the `THEOplayer` node is enabled. It is enabled by default, or you can set it explicitly:

```xml
<THEOsdk:THEOplayer id="TestPlayer" controls="true" />
```

Configure the Player and set a source as described in the [Roku SDK getting-started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/roku/getting-started.md). Roku renders its native playback controls when playback begins.

Use the [default UI how-to guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/roku/remove-ui-element.md) to remove individual controls. Set `controls` to `false` if you want to build a [chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/roku/chromeless.md).

---

# How to remove an element from the UI on Roku

You may want to limit the options and controls that are shown in the player's UI.

There are two general approaches:

1. Build a chromeless UI, and add only the controls you need. This is useful when you don't want to remove just one element, but want a radically different UI.
2. Hide or remove the individual element from the existing UI.

This guide focuses on the second approach.

## Implementation

By default, THEOplayer on Roku uses the Roku native player and its controls. To remove an element from these controls, you can remove that element manually. For example, the default controls show a clock UI element while paused. To remove it, follow the code below:

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="TestScene" extends="Scene">
    <interface>
    </interface>

    <script type = "text/brightscript" >

        <![CDATA[

        sub Init()
            m.player = m.top.findNode("TestPlayer")
            m.player.configuration = {
              "license": "<YOUR_LICENSE_STRING>"
            }
            ' remove the clock UI node
            m.player.getChildren(-1, 0)[0].getChildren(-1, 0)[1].removeChildIndex(11)

            setSource()
            m.player.setFocus(true)
            m.player.callFunc("play")
        end sub

        sub setSource()
            sourceDescription = {
                "sources": [
                    {
                        "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
                        "live": true,
                        "type": "application/x-mpegURL"
                    }
                ]
            }
            m.player.source = sourceDescription
        end sub

        ]]>

    </script>

    <children>
	    <THEOsdk:THEOplayer id="TestPlayer"/>
    </children>
</component>
```

## Removing all default controls

Instead of removing individual elements, you can turn off the default UI altogether by setting the player's `controls` field to `false`:

```xml
<THEOsdk:THEOplayer id="TestPlayer" controls="false"/>
```

You can also do this from BrightScript:

```brightscript
sub Init()
    m.player = m.top.findNode("TestPlayer")
    m.player.controls = false
end sub
```

From there on, you are responsible for the entire UI. See [How to build a chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/roku/build-chromeless-ui.md) for a walkthrough.

---

# Connectors for THEOplayer Roku SDK

## [![](/pr-932/img/conviva.svg)![](/pr-932/img/conviva_dark.svg)Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/roku/conviva)

[Integrate with Conviva analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/roku/conviva)

## [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/roku/comscore)

[Integrate with Comscore analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/roku/comscore)

## [Adobe Edge](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/roku/adobe-edge)

[Integrate with Adobe Edge analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/roku/adobe-edge)

## [![](/pr-932/assets/images/mux-1d56b7f17d515324f1547519db52c2ba.png)Mux](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/roku/mux)

[Integrate with Mux analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/roku/mux)

---

# Getting started with the Conviva Connector for the Roku SDK

Here's how to get started integrating the Conviva Connector with the THEOplayer Roku SDK.

## Prerequisites

In order to set up the Conviva Connector in your Roku application, you'll need the following:

* Your Conviva customer key (available in your Conviva Pulse dashboard)
* An app with the THEOplayer SDK for Roku already integrated, see our [Getting Started guide](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/roku/getting-started/).
* Optionally for debug and testing, your Conviva Touchstone gateway URL, which should be in the format of `"https://MY_TOUCHSTONE_DOMAIN.ts-testonly.conviva.com/"`

## Integration

1. First you must download the THEO Conviva Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOConvivaConnector` and providing the URI for the THEOConvivaConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 1.5.0:

```xml
<ComponentLibrary id="THEOConvivaConnector" uri="https://cdn.myth.theoplayer.com/roku/{SDK_VERSION}/THEOConvivaConnector.pkg" />
```

2. Then in the BrightScript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field.

```brightscript
sub Init()
    THEOConvivaNode = m.top.findNode("THEOConvivaConnector")
    THEOConvivaNode.observeField("loadStatus", "onLibraryLoadStatusChanged")
end sub

sub onLibraryLoadStatusChanged(event as object)
    THEOConvivaNode = event.getROSGNode()

    if THEOConvivaNode = invalid
        return
    end if

    if THEOConvivaNode.loadStatus = "ready"
		' Success
    else if THEOConvivaNode.loadStatus = "failed"
		? "Failed to load component library, please check URL. "; THEOConvivaNode.uri
	end if
end sub
```

3. Add the THEOConvivaConnector component to the SceneGraph file where your THEOplayer is defined

```xml
<THEOsdk:THEOplayer id="THEOplayer" controls="true" />
<THEOConvivaConnector:THEOConvivaConnector id="THEOConvivaConnector" />
```

4. Then in the BrightScript file, configure the connector by calling the configure method, passing the player instance and your Conviva customer key.

```brightscript
m.player = m.top.findNode("THEOPlayer")
m.convivaConnector = m.top.findNode("THEOConvivaConnector")
m.convivaConnector.callFunc("configure", m.player, "MY_CUSTOMER_KEY")
```

NOTE: that if you want to debug first and use Conviva's Touchstone service to validate your integration, you can include the gateway URL and a debug parameter in the configure call: `m.convivaConnector.callFunc("configure", m.player, "MY_CUSTOMER_KEY", "MY_TOUCHSTONE_GATEWAY_URL", true)`

5. Next, when you start playing the asset, call the `startSession` method and pass it the content metadata for the asset you're playing:

```brightscript
m.player.source = sourceDescription
contentMetadata = {
    defaultReportingResource: "MyCDN",
    playerName: "My Player",
    assetName: "My Asset Name",
    encodedFramerate: 24
}
m.convivaConnector.callFunc("startSession", contentMetadata)
```

See the [API documentation](https://www.theoplayer.com/docs/theoplayer/connectors/roku/conviva/API-reference/) for more on how to structure the content metadata for Conviva.

6. If you desire to monitor for CDN changes, you can optionally add a configuration for that after starting the session. `m.convivaConnector.callFunc("monitorCdnChanges", { mycdn: ["my-cdn.net"], theo: ["cdn.theoplayer.com"] })`
7. If the content metadata needs to change, you can update it by calling `setContentInfo`. This method accepts partial content metadata: `m.convivaConnector.callFunc( "setContentInfo", {assetName: "New Program"})`
8. When the video has stopped playing because it ended or the user exited, end the Conviva session `m.convivaConnector.callFunc("endSession")`
9. If you are exiting the player screen altogether, and destroying the player, make sure to destroy the connector at the same time, but before calling destroy on the SDK:

```brightscript
m.convivaConnector.callFunc("destroy")
m.convivaConnector = invalid

m.player.callFunc("destroy")
m.player = invalid
```

---

# Conviva Connector API reference

The attributes, methods and events for the THEOConvivaConnector.

## Attributes

| Name | Type   | Default | Access Permission | Description         |
| ---- | ------ | ------- | ----------------- | ------------------- |
| id   | string |         | read, write       | The ID of this node |

## Methods

| Method                 | Params                                                                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| configure              | player: THEOplayer, customerKey: string, gatewayUrl: string (Optional), debug: boolean (Optional) | Configure the Conviva SDK for use. The `gatewayUrl` param is the URL for the Touchstone service for use in validating your Conviva integration. Omit this for production builds.                                                                                                                                                                                                                                |
| destroy                | none                                                                                              | Destroy the connector. It also ends the current session, if any.                                                                                                                                                                                                                                                                                                                                                |
| endSession             | none                                                                                              | End the current Conviva session, but do not destroy the connector.                                                                                                                                                                                                                                                                                                                                              |
| getContentInfo         | none                                                                                              | Returns the content metadata for the current session.                                                                                                                                                                                                                                                                                                                                                           |
| monitorCdnChanges      | mappings: CDNMonitoringConfig, defaultCdn: string (optional)                                      | Updates the CDN monitoring settings. If passed a CDN monitoring config (see below), it will begin monitoring the downloaded segments for changes in CDN. This will update the defaultReportingResource for the current session if a CDN change is detected If passed invalid as the first parameter, it will stop the monitoring and use any string passed as the second param as the defaultReportingResource. |
| reportPlaybackEvent    | eventType: string, eventDetail: AssociativeArray                                                  | Reports a playback event with the associated data to Conviva.                                                                                                                                                                                                                                                                                                                                                   |
| reportPlaybackFailed   | errorMessage: string                                                                              | Reports a playback failure to Conviva.                                                                                                                                                                                                                                                                                                                                                                          |
| setAdInfo              | adInfo: AssociativeArray                                                                          | Sets the supplied ad info to Conviva. adInfo should be in the form of ConvivaContentInfo                                                                                                                                                                                                                                                                                                                        |
| setContentInfo         | contentMetadata: AssociativeArray                                                                 | Sets or updates the content metadata for the current session. Partials are supported and will be merged with the existing content metadata. See below for the schema of content metadata.                                                                                                                                                                                                                       |
| startSession           | contentMetadata: AssociativeArray                                                                 | Starts a Conviva session with the supplied content metadata. See below for the schema of content metadata.                                                                                                                                                                                                                                                                                                      |
| stopAndStartNewSession | contentMetadata: AssociativeArray                                                                 | Stops the existing Conviva session and starts a new one with the supplied content metadata. See below for the schema of content metadata.                                                                                                                                                                                                                                                                       |

### DPI Methods

The THEO Conviva Connector now exposes methods for Conviva DPI (Digital Product Insights) integration that the application can use to report application level analytics. If you are using Conviva for both DPI and Video, call `configureDPI` first for application analytics, then call `configure` when you have access to the player. In depth documentation for the parameters passed to these methods is provided in the (Conviva DPI Integration guide)\[<https://pulse.conviva.com/learning-center/content/sensor_developer_center/sensor_integration/roku/roku_stream_sensor.htm#ConvivaDPISensorIntegrationforRoku>]:

| Method              | Params                                                                                       | Description                                                                                                                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| configureDPI        | appId: string, customerKey: string, gatewayUrl: string (Optional), debug: boolean (Optional) | Configure the Conviva SDK for use for Conviva DPI. The `gatewayUrl` param is the URL for the Touchstone service for use in validating your Conviva integration. Omit this for production builds. |
| setUserId           | userId: string                                                                               | Set the user ID for this DPI session.                                                                                                                                                            |
| setChannelInfo      | channelInfo: assocarray                                                                      | Set the channel load times for this DPI session.                                                                                                                                                 |
| trackCustomEvent    | eventName: string, eventData: assocarray                                                     | Report a custom DPI event to Conviva.                                                                                                                                                            |
| trackClick          | clickDetails: assocarray                                                                     | Report a click event.                                                                                                                                                                            |
| trackAppError       | error: assocarray                                                                            | Report an application error.                                                                                                                                                                     |
| trackNetworkRequest | requestDetails: assocarray                                                                   | Report the stats for a network request.                                                                                                                                                          |
| setCustomTags       | customTags: assocarray                                                                       | Add custom tags to this DPI session.                                                                                                                                                             |
| unsetCustomTags     | customTags: array of strings                                                                 | Remove custom tags from this DPI session.                                                                                                                                                        |

### CDN Monitoring Config

The configuration for CDN monitoring should be an AssociativeArray with keys that are the name of the CDN and values that are arrays of strings to search for in segment URLs.

```brightscript
cdnMappings = {
	akamai: ["akamaized.net"],
	theo: ["dev.theoads.live", "cdn.theoplayer.com"]
	level3: ["llnw.com"]
}
```

Passing a config as the only param will start CDN change monitoring with the provided configuration, or update the config if it is already started. `m.theoConvivaConnector.callFunc("monitorCDNChanges", cdnMappings)` However, if you want to stop CDN change monitoring, pass `invalid` as the first parameter, and the string you want to use for the defaultReportingResource as the second parameter. `m.theoConvivaConnector.callFunc("monitorCDNChanges", invalid, "theo")`

### Content Metadata

Content metadata should be an AssociativeArray following [Conviva's schema](https://pulse.conviva.com/learning-center/content/sensor_developer_center/sensor_integration/roku/roku_stream_sensor.htm#PredefinedVideoandContentMetadata). However, the THEOConviaConnector does provide a shortcut for c3 data. You may specify the c3 data by its full name:

```brightscript
contentMetadata = {
	customMetadata: {
		myCustomTag: "Value",
		"c3.cm.contentType": "DVR",
		"c3.cm.name": "CMS"
	}
}
```

However, we also support using an object notation:

```brightscript
contentMetadata = {
	customMetadata: {
		myCustomTag: "Value",
		c3: {
			cm: {
				contentType: "DVR",
				name: "CMS"
			}
		}
	}
}
```

---

# Getting started with the Comscore Connector for the Roku SDK

Here's how to get started integrating the Comscore Connector with the THEOplayer Roku SDK.

## Prerequisites

In order to set up the Comscore Connector in your Roku application, you'll need the following:

* Your Comscore publisher ID and publisher secret (available in your Comscore Direct dashboard under Mobile Apps > Get Tag).
* An app with the THEOplayer SDK for Roku already integrated, see our [Getting Started guide](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/roku/getting-started/).

## Integration

1. First you must download the THEO Comscore Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOComscoreConnector` and providing the URI for the THEOComscoreConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 1.5.0:

```xml
<ComponentLibrary id="THEOComscoreConnector" uri="https://cdn.myth.theoplayer.com/roku/{SDK_VERSION}/THEOComscoreConnector.pkg" />
```

2. Then in the BrightScript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field.

```brightscript
sub Init()
    THEOComscoreNode = m.top.findNode("THEOComscoreConnector")
    THEOComscoreNode.observeField("loadStatus", "onLibraryLoadStatusChanged")
end sub

sub onLibraryLoadStatusChanged(event as object)
    THEOComscoreNode = event.getROSGNode()

    if THEOComscoreNode = invalid
        return
    end if

    if THEOComscoreNode.loadStatus = "ready"
		' Success
    else if THEOComscoreNode.loadStatus = "failed"
		? "Failed to load component library, please check URL. "; THEOComscoreNode.uri
	end if
end sub
```

3. Add the THEOComscoreConnector component to the SceneGraph file where your THEOplayer is defined

```xml
<THEOsdk:THEOplayer id="THEOplayer" controls="true" />
<THEOComscoreConnector:THEOComscoreConnector id="THEOComscoreConnector" />
```

4. Then configure the connector by calling the configure method, passing the player instance and your Comscore customer key.

```brightscript
m.player = m.top.findNode("THEOplayer")
m.comscoreConnector = m.top.findNode("THEOComscoreConnector")
m.comscoreConnector.callFunc("configure", m.player, { publisherId: "MY_PUBLISHER_ID", publisherSecret: "MY_PUBLISHER_SECRET", applicationName: "MY_APPLICATION_NAME"})
```

5. Next, when you start playing the asset, call the `startSession` method and pass it the content metadata for the asset you're playing:

```brightscript
m.player.source = sourceDescription
contentMetadata = {
	adLoadFlag: false,
	assetId: "myAssetId",
	c3: "Arbitrary C3 value",
	c4: "*null",
	c6: "*null",
	clipLength: 600,
	completeEpisodeFlag: true,
	contentGenre: "Sports",
	digitalAirDate: "2025-03-04",
	episodeNumber: "59",
	episodeSeasonNumber: "5",
	episodeTitle: "The Game Last Night",
	programTitle: "The Sports Show",
	publisherBrandName: "Sports Publisher Network",
	stationTitle: "KXYZ",
	tvAirDate: "2025-03-04"
}
m.comscoreConnector.callFunc("startSession", contentMetadata)
```

See the [API documentation](https://www.theoplayer.com/docs/theoplayer/connectors/roku/comscore/API-reference/) for more on how to structure the content metadata for Comscore.

6. Comscore requests a call to their `tick` method when the main event loop executes. If you update a global field called `tccTick`, the THEOComscoreConnector will automatically observe that field and call `tick` for you. Otherwise, you can manually call the `sendTick` method on the THEOComscoreConnector.

```brightscript
m.global.addField("tccTick", "integer", false)
m.global.tccTick = 0

while true
    m.global.tccTick = m.global.tccTick + 1
    msg = wait(1000, m.port)
    msgType = type(msg)
    if msgType = "roSGScreenEvent"
        if msg.isScreenClosed() then return
    end if
end while
```

NOTE: the `wait` method is running for 1000ms here, making the `tccTick` field get updated every second. Setting it to 0ms will cause the `tccTick` field to not get updated regularly.

7. If the content metadata needs to change, you can update it by calling `update`. This method accepts partial content metadata: `m.comscoreConnector.callFunc( "update", contentMetadata)`
8. When the video has stopped playing because it ended or the user exited, end the Comscore session `m.comscoreConnector.callFunc("endSession")`
9. If you are exiting the player screen altogether, and destroying the player, make sure to destroy the connector at the same time, but before calling destroy on the SDK:

```brightscript
m.comscoreConnector.callFunc("destroy")
m.comscoreConnector = invalid

m.player.callFunc("destroy")
m.player = invalid
```

---

# Comscore Connector API Reference

The attributes, methods and events for the THEOComscoreConnector.

## Attributes

| Name         | Type             | Default              | Access Permission | Description                                  |
| ------------ | ---------------- | -------------------- | ----------------- | -------------------------------------------- |
| id           | string           |                      | read,write        | The id of the node.                          |
| MEDIA\_TYPES | associativeArray | Comscore Media Types | read              | Constant with the Comscore media type enums. |
| AD\_TYPES    | associativeArray | Comscore Ad Types    | read              | Constant with the Comscore ad type enums.    |

## Methods

| Method               | Params                                                                                                                                      | Description                                                                                                                                                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| configure            | player: THEOplayer, configuration: THEOConnectorConfiguration, metadata: (optional) THEOComscoreReadableMetadata or THEOComscoreTagMetadata | Add a player to monitor, configure the Comscore SDK, and also pass in optional metadata for your content.                                                                                                                                  |
| destroy              | none                                                                                                                                        | Destroy the connector. It also ends the current session, if any.                                                                                                                                                                           |
| endSession           | none                                                                                                                                        | End the current Comscore session, but do not destroy the connector.                                                                                                                                                                        |
| update               | metadata: THEOComscoreReadableMetadata or THEOComscoreTagMetadata                                                                           | Updates the content metadata for the current session.                                                                                                                                                                                      |
| sendTick             | none                                                                                                                                        | Sends a tick to Comscore. This is only needed if you do not implement the `tccTick` field in your main event loop.                                                                                                                         |
| startSession         | mediaType: string, metadata: (optional) THEOComscoreReadableMetadata or THEOComscoreTagMetadata                                             | Starts a Comscore streaming session with the specified media type, and optionally applies the content metadata. If not passing content metadata, you will need to add it separately with the `update` method before calling `startSession` |
| reportPlaybackEvent  | eventType: string, eventDetail: AssociativeArray                                                                                            | Reports a playback event with the associated data to Comscore.                                                                                                                                                                             |
| reportPlaybackFailed | errorMessage: string                                                                                                                        | Reports a playback failure to Comscore.                                                                                                                                                                                                    |
| setAdInfo            | adInfo: AssociativeArray                                                                                                                    | Sets the supplied ad info to Comscore. adInfo should be in the form of ComscoreContentInfo                                                                                                                                                 |
| setContentInfo       | contentMetadata: AssociativeArray                                                                                                           | Sets or updates the content metadata for the current session. Partials are supported and will be merged with the existing content metadata. See below for the schema of content metadata.                                                  |
| startSession         | contentMetadata: AssociativeArray                                                                                                           | Starts a Comscore session with the supplied content metadata. See below for the schema of content metadata.                                                                                                                                |

### Comscore Config

The configuration the Comscore connector is the THEOConnectorConfiguration interface.

```brightscript
configuration = {
	publisherId: "MY_PUBLISHER_ID",
	publisherSecret: "MY_PUBLISHER_SECRET",
	applicationName: "MY_APPLICATION_NAME"
}
```

The `applicationName` property is optional. If omitted, Comscore will automatically collect it from the manifest file.

To get your publisher ID and secret, log into your Comscore account. Go to the Direct dashboard, and switch to the Mobile App tab. Then click the Get Tag button, and a dialog should show with the ID and secret in it.

### Content Metadata

Content metadata should be an AssociativeArray following Comscore's schema for streaming tags. However, the THEOComscoreConnector also will accept a more human readable format. These are in the THEOComscoreReadableMetadata and THEOComscoreTagMetadata interfaces. NOTE: if you omit a string value, replace it with `"*null"`, which is the value requested by Comscore for empty fields.

#### THEOComscoreReadableMetadata

```brightscript
comscoreMetadata = {
	adLoadFlag: false,
	assetId: "myAssetId",
	c3: "Arbitrary C3 value",
	c4: "*null",
	c6: "*null",
	clipLength: 600,
	completeEpisodeFlag: true,
	contentGenre: "Sports",
	digitalAirDate: "2025-03-04",
	episodeNumber: "59",
	episodeSeasonNumber: "5",
	episodeTitle: "The Game Last Night",
	programTitle: "The Sports Show",
	publisherBrandName: "Sports Publisher Network",
	stationTitle: "KXYZ",
	tvAirDate: "2025-03-04"
}
```

#### THEOComscoreTagMetadata

NOTE: all values must be strings for this object, with Booleans being represented as `"0"` and `"1"`.

```brightscript
comscoreMetadata = {
	ns_st_ia: "0",
	ns_st_ci: c3.cm.id,
	c3: "Arbitrary C3 value",
	c4: "*null",
	c6: "*null",
	ns_st_cl: "600",
	ns_st_ce: "1",
	ns_st_cg: "Sports",
	ns_st_ddt: "2025-03-04",
	ns_st_en: "59",
	ns_st_sn: "5",
	ns_st_ep: "The Game Last Night",
	ns_st_pr: "The Sports Show",
	ns_st_pu: "Sports Publisher Network",
	ns_st_st: "KXYZ",
	ns_st_tdt: "2025-03-04"
}
```

### Sending Ticks

Comscore wants a tick to be sent to it on every run of the main event loop. You can do this manually by calling the `sendTick` method on the THEOComscoreConnector: `m.comscoreConnector.callFunc("sendTick")`

However, if you want to have the connector automatically send the tick for you, in your `main.brs` file, add an integer field to the global node called `tccTick`. Set it equal to 0 and then increment it on each run of your event loop. Note that the `wait` line will make it run every 1000 milliseconds.

```brightscript
m.global.addField("tccTick", "integer", false)
m.global.tccTick = 0

while true
	m.global.tccTick = m.global.tccTick + 1
	msg = wait(1000, m.port)
	msgType = type(msg)
	if msgType = "roSGScreenEvent"
		if msg.isScreenClosed() then return
	end if
end while
```

---

# Getting started with the Adobe Edge Connector for the Roku SDK

Here's how to get started integrating the Adobe Edge Connector with the THEOplayer Roku SDK.

## Prerequisites

In order to set up the Adobe Edge Connector in your Roku application, you'll need the following:

* Your Adobe Edge domain and config ID (also known as data stream ID)
* An app with the THEOplayer SDK for Roku already integrated, see our [Getting Started guide](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/roku/getting-started/).

## Integration

1. First you must download the THEO Adobe Edge Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOAEPConnector` and providing the URI for the THEOAEPConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 9.2.0:

```xml
<ComponentLibrary id="THEOAEPConnector" uri="https://cdn.myth.theoplayer.com/roku/{SDK_VERSION}/THEOAEPConnector.pkg" />
```

2. Then in the BrightScript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field.

```brightscript
sub Init()
    THEOAEPNode = m.top.findNode("THEOAEPConnector")
    THEOAEPNode.observeField("loadStatus", "onLibraryLoadStatusChanged")
end sub

sub onLibraryLoadStatusChanged(event as object)
    THEOAEPNode = event.getROSGNode()

    if THEOAEPNode = invalid
        return
    end if

    if THEOAEPNode.loadStatus = "ready"
		' Success
    else if THEOAEPNode.loadStatus = "failed"
		? "Failed to load component library, please check URL. "; THEOAEPNode.uri
	end if
end sub
```

3. Add the THEOAEPConnector component to the SceneGraph file where your THEOplayer is defined

```xml
<THEOsdk:THEOplayer id="THEOplayer" controls="true" />
<THEOAEPConnector:THEOAEPConnector id="THEOAEPConnector" />
```

4. Then in the BrightScript file, configure the connector by calling the configure method, passing the player instance and your Adobe Edge configuration.

```brightscript
m.player = m.top.findNode("THEOPlayer")
m.aepConnector = m.top.findNode("THEOAEPConnector")
aepConfig = {
    configId: "<MY_AEP_CONFIG_ID>",
    domainName: "<MY_EDGE_DOMAIN>",
    mediaChannel: "My Channel",
    mediaPlayerName: "My Player",
    mediaAppVersion: "1.0",
    logLevel: 3
}
m.aepConnector.callFunc("configure", m.player, aepConfig)
```

5. Next, when you start playing the asset, call the `startSession` method and pass it the session details for the asset you're playing. You may also include an optional session configuration:

```brightscript
m.player.source = sourceDescription

aepSessionConfig = {}
aepSessionConfig["config.channel"] = "My Channel"
aepSessionConfig["config.adpinginterval"] = 5
aepSessionConfig["config.mainpinginterval"] = 30

aepSessionDetails = {
    name: "my-asset-id",
    friendlyName: sourceDescription.title,
    contentType: "video",
    streamType: "vod",
    length: 300,
    customMetadata: {
        key1: "value1",
        key2: "value2",
    }
}
m.aepConnector.callFunc("startSession", aepSessionDetails, aepSessionConfig)
```

See the [API documentation](https://github.com/adobe/aepsdk-roku/blob/main/Documentation/api-reference.md) for more on how to structure the data for Adobe Edge.

6. When the video has stopped playing because it ended or the user exited, end the Adobe Edge session. `m.aepConnector.callFunc("endSession")`
7. If you are exiting the player screen altogether, and destroying the player, make sure to destroy the connector at the same time, but before calling destroy on the SDK:

```brightscript
m.aepConnector.callFunc("destroy")
m.aepConnector = invalid

m.player.callFunc("destroy")
m.player = invalid
```

---

# Adobe Edge Platform Connector API

The attributes, methods and events for the THEOAEPConnector.

## Attributes

| Name          | Type             | Default          | Access Permission | Description                              |
| ------------- | ---------------- | ---------------- | ----------------- | ---------------------------------------- |
| id            | string           |                  | read,write        | The id of the node.                      |
| ecid          | string           | invalid          | read              | User's Experience Cloud ID.              |
| MEDIA\_EVENTS | associativeArray | AEP Media Events | read              | Constant with the AEP media event enums. |

## Methods

| Method                 | Params                                                                       | Description                                                                                                                                                                               |
| ---------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| configure              | player: THEOplayer, configuration: THEOAEPConfiguration                      | Adds the THEOplayer instance to monitor, and applies a configuration to the AEP SDK.                                                                                                      |
| destroy                | none                                                                         | Destroy the connector. It also ends the current session, if any.                                                                                                                          |
| endSession             | none                                                                         | End the current AEP session, but do not destroy the connector.                                                                                                                            |
| getExperienceCloudId   | none                                                                         | Retrieves the ECID for the user. The ECID will be added to the `ecid` field on the connector once it has been retrieved.                                                                  |
| resetIdentities        | none                                                                         | Resets the identities used in the SDK for the user.                                                                                                                                       |
| sendMediaEvent         | eventXDM: AssociativeArray                                                   | Send a media event to AEP.                                                                                                                                                                |
| setContentInfo         | contentMetadata: AssociativeArray                                            | Sets or updates the content metadata for the current session. Partials are supported and will be merged with the existing content metadata. See below for the schema of content metadata. |
| setExperienceCloudId   | ecid: string                                                                 | Sets a pre-existing ECID for the user on the SDK.                                                                                                                                         |
| startSession           | sessionDetails: THEOAEPMediaSessionDetails, sessionConfig: (optional) object | Starts a AEP session with the supplied session details and optional config. See below for the schema of details and config.                                                               |
| stopAndStartNewSession | sessionDetails: THEOAEPMediaSessionDetails, sessionConfig: (optional) object | Stops the existing session if any. Starts a AEP session with the supplied session details and optional config. See below for the schema of details and config.                            |

### AEP Connector Config

The configuration the AEP connector is the THEOConnectorConfiguration interface.

```brightscript
configuration = {
	configId: "<MY_CONFIGURATION_ID>",
    domainName: "<MY_EDGE_DOMAIN>",
    mediaChannel: "My Channel",
    mediaPlayerName: "My Player",
    mediaAppVersion: "1.0.0"
    logLevel: 3
}
```

The `logLevel` property is optional. The accepted values are (VERBOSE: `0`, DEBUG: `1`, INFO: `2`, WARNING: `3`, ERROR: `4`).

### Session Details and Config

The session details and session config control the metadata for the session you're starting. See the [AEP SDK documentation](https://github.com/adobe/aepsdk-roku/blob/main/Documentation/api-reference.md#createMediaSession) for expected values. The `customMetadata` property is optional. Values on that object must be strings.

#### THEOAEPMediaSessionDetails

```brightscript
aepSessionDetails = {
	streamType: "vod"
    friendlyName: "My Asset",
    name: "my-media-id",
    length: 596,
    contentType: "video",
    customMetadata: {
		key1: "value1",
		key2: "value2"
	}
}
```

#### Session Config

The optional session config should follow the schema described in the [AEP SDK documentation](https://github.com/adobe/aepsdk-roku/blob/main/Documentation/api-reference.md#createMediaSession).

```brightscript
aepSessionConfig = {}
aepSessionConfig["config.channel"] = "My Channel"
aepSessionConfig["config.adpinginterval"] = 5
aepSessionConfig["config.mainpinginterval"] = 30
```

### Getting the Experience Cloud ID

To get an ECID for a user, you'll need to observe the `ecid` field on the connector, and then call `getExperienceCloudId` on the connector. The field will update with the ECID when it is available and trigger your observer.

```brightscript
m.aepConnector.observeField("ecid", "onEcidChange")

sub onEcidChange( event as object )
	m.myEcid = event.getData()
end sub

m.aepConnector.callFunc("getExperienceCloudId")
```

### Reusing an existing AEP SDK library

The AEP SDK allows you to reuse instances of the SDK in case you're already using the AEP SDK in your application. This is done by adding a Task node to the scene. The THEO AEP Connector can reuse this Task node. In the MainScene.brs:

```brightscript
m.aepSDK = AdobeAEPSDKInit()
m.top.appendChild(m.aepSDK.getTaskNode())
```

As long as the task node is on the Scene before the connector is configured, the THEO AEP connector can pick up the AEP Task node and reuse it.

### Supported media events

The THEO AEP Connector will automatically detect most media events and send them to AEP for you, including player commands such as play or pause and events like bitrate change. It will not send media events related to chapters in this version:

* `media.chapterStart`
* `media.chapterComplete`
* `media.chapterSkip`

For these you may use the `sendMediaEvent` method and construct your own XDM payload:

```brightscript
chapterStartXDM = {
  "xdm": {
    "eventType": m.aepConnector.MEDIA_EVENTS.CHAPTER_START
    "mediaCollection": {
      "playhead": m.theoPlayer.currentTime,
      "chapterDetails": {
        "friendlyName": "My Chapter",
        "index": 1,
        "length": 300,
        "offset": 0
      }
    }
  }
}

m.aepConnector.callFunc("sendMediaEvent", chapterStartXDM)
```

---

# Getting started with the Mux Connector for the Roku SDK

Here's how to get started integrating the Mux Connector with the THEOplayer Roku SDK.

## Prerequisites

In order to set up the Mux Connector in your Roku application, you'll need the following:

* Your Mux environment key
* An app with the THEOplayer SDK for Roku already integrated, see our [Getting Started guide](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/roku/getting-started/).

## Integration

1. First you must download the THEO Mux Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOMuxConnector` and providing the URI for the THEOMuxConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 10.9.0:

```xml
<ComponentLibrary id="THEOMuxConnector" uri="https://cdn.myth.theoplayer.com/roku/{SDK_VERSION}/THEOMuxConnector.pkg" />
```

2. Then in the BrightScript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field.

```brightscript
sub Init()
    THEOMuxNode = m.top.findNode("THEOMuxConnector")
    THEOMuxNode.observeField("loadStatus", "onLibraryLoadStatusChanged")
end sub

sub onLibraryLoadStatusChanged(event as object)
    THEOMuxNode = event.getROSGNode()

    if THEOMuxNode = invalid
        return
    end if

    if THEOMuxNode.loadStatus = "ready"
		' Success
    else if THEOMuxNode.loadStatus = "failed"
		? "Failed to load component library, please check URL. "; THEOMuxNode.uri
	end if
end sub
```

3. Add the THEOMuxConnector component to the SceneGraph file where your THEOplayer is defined.

```xml
<THEOsdk:THEOplayer id="THEOplayer" controls="true" />
<THEOMuxConnector:THEOMuxConnector id="THEOMuxConnector" />
```

4. Then in the BrightScript file, configure the connector by calling the configure method, passing the player instance and your Mux configuration.

```brightscript
m.player = m.top.findNode("THEOPlayer")
m.muxConnector = m.top.findNode("THEOMuxConnector")
muxConfig = {
    env_key: "<MY_MUX_ENV_KEY>",
}
m.muxConnector.callFunc("configure", m.player, muxConfig)
```

5. Next, when you start playing the asset, call the `startSession` method and pass it the metadata for the asset you're playing:

```brightscript
m.player.source = sourceDescription

muxContentMetadata = {
    video_id: "<MY_VIDEO_ID>",
    video_title: "<MY_VIDEO_TITLE>"
}

m.muxConnector.callFunc("startSession", muxContentMetadata)
```

There are more properties available to add to the metadata, but `video_id` and `video_title` are required. See [Mux's schema for streaming metadata](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata#optional-configurable-metadata) for more properties that are available for Mux.

6. If you are using the THEOplayer in a size other than fullscreen, before you start the session, you can set the presentation mode to reflect the different size. This is also referred to as the playback mode.

```brightscript
m.muxConnector.callFunc("setPresentation", m.muxConnector.PRESENTATION_MODES.INLINE)
m.muxConnector.callFunc("startSession", muxContentMetadata)
```

The `setPresentation` method can also be called mid-session if the presentation mode changes during a session. The available presentation modes are `FULLSCREEN`, `INLINE`, `MINI`, and `PIP`.

7. If you desire to monitor for CDN changes, you can optionally add a configuration for that to start monitoring. `m.muxConnector.callFunc("monitorCdnChanges", { mycdn: ["my-cdn.net"], theo: ["cdn.theoplayer.com"] })`

8. When the video has stopped playing because it ended or the user exited, end the Mux session. `m.muxConnector.callFunc("endSession")`

9. If you are exiting the player screen altogether, and destroying the player, make sure to destroy the connector at the same time, but before calling destroy on the player:

```brightscript
m.muxConnector.callFunc("destroy")
m.muxConnector = invalid

m.player.callFunc("destroy")
m.player = invalid
```

---

# Mux Connector API

The attributes, methods and events for the THEOMuxConnector.

## Attributes

| Name                | Type             | Default                | Access Permission | Description                                    |
| ------------------- | ---------------- | ---------------------- | ----------------- | ---------------------------------------------- |
| id                  | string           |                        | read,write        | The id of the node.                            |
| CONTENT\_TYPES      | AssociativeArray | Mux Content Types      | read              | Constant with the Mux content types enums.     |
| PRESENTATION\_MODES | AssociativeArray | Mux Presentation Modes | read              | Constant with the Mux presentation mode enums. |

## Methods

| Method            | Params                                                                                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| configure         | player: THEOplayer, configuration: THEOMuxConfiguration, metadata: (optional) AssociativeArray                                   | Add a player to monitor, configure the Mux SDK, and also pass in optional metadata for your content.                                                                                                                                                                                                                                                                                                            |
| destroy           | none                                                                                                                             | Destroy the connector. It also ends the current session, if any.                                                                                                                                                                                                                                                                                                                                                |
| endSession        | none                                                                                                                             | End the current Mux session, but do not destroy the connector.                                                                                                                                                                                                                                                                                                                                                  |
| monitorCdnChanges | mappings: CDNMonitoringConfig, defaultCdn: string (optional)                                                                     | Updates the CDN monitoring settings. If passed a CDN monitoring config (see below), it will begin monitoring the downloaded segments for changes in CDN. This will update the defaultReportingResource for the current session if a CDN change is detected If passed invalid as the first parameter, it will stop the monitoring and use any string passed as the second param as the defaultReportingResource. |
| notifyError       | code: integer, message: string, context: string (optional), severity: string (optional), isBusinessException: boolean (optional) | Report an error to Mux. Note that most errors should be automatically reported. Severity defaults to "fatal".                                                                                                                                                                                                                                                                                                   |
| setPresentation   | presentationMode: MuxPresentationModes, data: (optional) AssociativeArray                                                        | Change the reported presentation mode (also called playback mode) for the player. Can also take optional arbitrary data about the mode.                                                                                                                                                                                                                                                                         |
| startSession      | metadata: (optional) THEOMuxMetadata                                                                                             | Starts a Mux streaming session with the specified media type, and optionally applies the content metadata. See below for the schema of content. If not passing content metadata, you will need to add it separately with the `update` method before calling `startSession`                                                                                                                                      |

### Mux Config

The configuration the Mux connector is the THEOMuxConfiguration interface. All properties except for `env_key` are optional.

```brightscript
configuration = {
  env_key: "<MY_MUX_ENV_KEY>",
  viewer_user_id: "<END_USER_ID>",
  mux_base_url: "<CUSTOM_MUX_BASE_URL>"
}
```

In order to get debug output from Mux in your console, you need to add the settings to your application's manifest file.

```text
mux_debug_events=partial
mux_debug_beacons=partial
```

The accepted values for the debug properties are `full`, `partial`, and `none`, defaulting to `none`.

### CDN Monitoring Config

The configuration for CDN monitoring should be an AssociativeArray with keys that are the name of the CDN and values that are arrays of strings to search for in segment URLs.

```brightscript
cdnMappings = {
	akamai: ["akamaized.net"],
	theo: ["dev.theoads.live", "cdn.theoplayer.com"]
	level3: ["llnw.com"]
}
```

Passing a config as the only param will start CDN change monitoring with the provided configuration, or update the config if it is already started. `m.muxConnector.callFunc("monitorCDNChanges", cdnMappings)` However, if you want to stop CDN change monitoring, pass `invalid` as the first parameter, and the string you want to use for the defaultReportingResource as the second parameter. `m.muxConnector.callFunc("monitorCDNChanges", invalid, "theo")`

### Content Metadata

Content metadata should be an AssociativeArray following [Mux's schema for streaming tags](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata#optional-configurable-metadata). All properties on it are optional, except for `video_id` and `video_title`.

For content type metadata values, there is an enum property on the THEOMuxConnector named `CONTENT_TYPES`. Its values are SHORT, MOVIE, CLIP, EPISODE, TRAILER, and EVENT. For example: `metadata.video_content_type = m.muxConnector.CONTENT_TYPES.MOVIE`.

### Presentation Modes

The THEOMuxConnector supports reporting changes in the presentation mode (also called playback mode) your application uses the player in, such as fullscreen or inline. The `PRESENTATION_MODES` enum property on the THEOMuxConnector holds the possible values (FULLSCREEN, INLINE, MINI, and PIP). For example, if your application changes the THEO player so it is in a list row component, you could call:

```brightscript
m.muxConnector.callFunc("setPresentation", m.muxConnector.PRESENTATION_MODES.INLINE)
```

There is also an optional `data` parameter for that method that can be an arbitrary associative array, as long as it can be converted to JSON.

```brightscript
presentationModeData = { reason: "Viewed Asset", timestamp: 1767735434 }
m.muxConnector.callFunc("setPresentation", m.muxConnector.PRESENTATION_MODES.FULLSCREEN, presentationModeData)
```

---

# Frequently asked questions (FAQ)

In this section we will list all the frequently asked questions we received over the years.

For our customers with a support plan package, if you have additional questions or can't find your answer here please contact our [Service Desk](https://opentelly.atlassian.net/servicedesk/customer/portal/1) for further support.

## Questions

* [How to combat autoplay policies](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-combat-autoplay-policies.md)
* [Why does fullscreen not behave as expected on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-does-fullscreen-not-behave-as-expected-on-ios.md)
* [Why does the Network API not work on iOS devices](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-does-network-api-not-work-on-ios-devices.md)
* [Why does Chromecast not work on iOS Chrome?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-does-chromecast-not-work-on-ios-chrome.md)
* [Why can't I select another video quality on iOS/tvOS?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-cant-we-select-other-video-quality-on-ios-tvos.md)
* [Is YouTube supported](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/is-youtube-supported.md)
* [Why does the player load only one audio track (even though there are several in the manifest)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-does-player-load-only-one-audio-track.md)
* [Is it possible to see 360 degrees photo with THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/is-it-possible-to-see-360-picture.md)
* [Why the Visibility API does not work through an iframe on Safari and IE11](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-visibilty-api-doesnt-work-in-iframe-on-safari-and-ie11.md)
* [What is an impression](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-is-an-impression.md)
* [How to know whether a live stream is playing](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-know-when-livestream-is-playing.md)
* [Why did my subtitles stop working](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-did-subtitles-stop-working.md)
* [How does Media Engagement Index (MEI) affect Autoplay on Chrome](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-does-mei-affect-autoplay-on-chrome.md)
* [Why are not all response headers exposed](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-are-not-all-response-headers-exposed.md)
* [Why does the currentTime seem off in my livestream & what can I do about it](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-does-currentime-seem-to-be-off.md)
* [How to remove CORS restrictions from a reproduction stream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-remove-cors-restrictions.md)
* [Which network calls (or requests) does THEOplayer do](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/which-network-calls-does-THEOplayer-do.md)
* [Why does the playback not work when using the Chrome iPhone/iPad simulator](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-does-playback-not-work-using-chrome-iphone-simulator.md)
* [How to remove unwanted CC track in iOS or Safari](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-remove-unwanted-cc-track-ios-safari.md)
* [MediaTek limitations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/mediatek-limitations.md)
* [How to use ProGuard with THEOplayer Android SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-use-proguard-with-android-sdk.md)
* [Self-hosting and versioning of THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/self-hosting-theoplayer.md)
* [Does THEOplayer support EXT-X-DATERANGE](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/does-theoplayer-support-ext-x-daterange.md)
* [Can clipping be used on a playlist](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/can-clipping-be-used-in-a-playlist.md)
* [Can timeline thumbnails be made available before playback start](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/can-timeline-thumbnails-be-made-available-before-playback-start.md)
* [What are the benefits of preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-are-the-benefits-of-preloading.md)
* [What are the player seeking and seeked events and when are they fired](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-are-the-player-seeking-and-seeked-events.md)
* [Can we use HLS or DASH ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/can-we-use-hls-or-dash-ads.md)
* [How to change text in THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-change-text-in-theoplayer.md)
* [Change text when AirPlaying](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-change-text-when-airplaying.md)
* [ITP2.1 problems using THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/itp21-problems-using-theoplayer.md)
* [Removing context menu 'Powered by THEOplayer...'](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/removing-context-menu-powered-by.md)
* [What aspects of THEOplayer do we need to take into account to deploy a proper Content Security Policy (CSP)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/whats-aspects-to-take-into-account-when-developing-csp.md)
* [How can we avoid that the player keeps looking for chunks/segments if they are not found](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-avoid-loading-chuncks-when-not-found.md)
* [Can we show a custom message on 403 on mp4](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/can-we-show-custom-message-on-403-on-mp4.md)
* [Can we prevent UpNext feature from redirecting](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/prevent-up-next-from-redirecting.md)
* [Is it possible to preload VOD content while the pre-roll is playing](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/preload-vod-content-when-pre-roll-is-playing.md)
* [Why is my video not playing automatically](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-is-video-not-playing-automatically.md)
* [Is it possible to have multiple player instances play at the same time](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/possible-to-have-multiple-player-instances-at-same-time.md)
* [Is it a problem if the viewer pauses a live stream for longer than the DVR window](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/is-it-a-problem-if-viewer-pauses-live-stream-longer-than-dvr-window.md)
* [THEOplayer Features & Modules](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/theoplayer-features-modules.md)
* [Chromecast on my webplayer does not work any longer despite no change in my implementation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/chromecast-on-weblayer-does-not-longer-work.md)
* [How to track network errors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-track-network-errors.md)
* [How to use the CDN fallback/backup stream feature](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/cdn-fallback-backup-stream-feature.md)
* [How to apply accurate buffering strategy](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-apply-accurate-buffering-strategy.md)
* [How can I distribute 4K content?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-can-i-distribute-4k-content.md)
* [What is the collaboration between Azure Media Services and THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-is-the-collaboration-between-azure-media-services-and-THEOplayer.md)
* [Is Portrait mode supported](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/is-portrait-mode-supported.md)
* [How to prevent screen recording](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-prevent-screen-recording.md)
* [The provided video source is incompatible with the license for this player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/the-provided-video-source-is-incompatible-with-the-license-for-this-player.md)
* [Page and Source domains](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/page-and-source-domains.md)
* [Why is my PlayReady stream not working in Chromium Edge?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/Why-is-my-Playready-stream-not-working-in-Chromium-Edge.md)
* [Which subtitle and CC formats are supported on native Safari](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/which-subtitle-and-cc-formats-are-supported-on-native-safari.md)
* [How to navigate through the documentation and resources](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-navigate-through-the-documentation-and-resources.md)
* [What are the limitations of AirPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-are-the-limitations-of-AirPlay.md)
* [What are the Uplynk challenges](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-are-the-uplynk-challenges.md)
* [How to use the Media Session API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-use-media-session-api.md)
* [How to use THEOplayer iOS SDK on an M1 mac](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-use-theoplayer-ios-sdk-on-m1.md)
* [Widevine CDM deprecation notice for old browser versions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/old-widevine-cdm-deprecation-notice.md)
* [Which source is the one being played](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/which-source-is-the-one-being-played.md)
* [What PiP options to use to make the video stay visible while browsing or on other applications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-make-pip-video-stay-visible-while-browsing.md)
* [Why are the FairPlay license and certificate being requested again on iOS after ads?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/why-is-DRM-license-retrieved-again-after-ads-on-iOS.md)
* [How to detect if the user changes the video quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-detect-if-user-changes-video-quality.md)
* [List of supported platforms](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/supported-platforms.md)

## Error handling

* [Which error related events does the player expose](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/which-error-related-events-does-player-expose.md)
* [What does the error message 'Unknown CDM error' mean](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-does-error-unknown-cdm-mean.md)
* [What does the error message 'Something went wrong with Native playback' mean](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-does-error-something-went-wrong-during-playback-mean.md)
* [What does the error message 'can only be initiated by a user gesture' imply? Can I still force the desired action](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-does-error-can-only-be-initiated-by-user-gesture-mean.md)
* [What does the error message “Something went wrong determining the initial period of the provided MPEG-DASH stream” mean](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/error-message-initial-period-provided-MPEG-DASH.md)
* [What is the "WebAssembly.compileStreaming failed" warning and what does it mean?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-is-the-webAssembly-compileStreaming-failed-warning.md)

## Support

* [What is the support for Wowza](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-is-the-support-for-wowza.md)
* [How to create a (great) ticket](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-create-a-ticket.md)
* [How to investigate a ticket](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-investigate-a-ticket.md)
* [How to use AI coding assistants with THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-use-ai-coding-assistants.md)

---

# How to combat autoplay policies

This short article explains what autoplay is, where autoplay is restricted, and what THEOplayer does to facilitate working with autoplay.

When you enable [autoplay](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#autoplay) for a HTML5 video, you instruct the viewer's browser to automatically play the content as soon as possible without action from the viewer.

## Restrictions

Browsers are restricting their autoplay capabilities. These policies are the result of the continuous misuse of autoplay which causes bad user experiences.

There are two types of autoplay:

* Unmuted Autoplay: autoplay with audio enabled.
* Muted Autoplay: autoplay with audio disabled.

The first type is considered more abrupt, while the second type is considered more user-friendly. Some browsers which normally disallow unmuted autoplay allow it when the viewer explicitly indicates so\*.

## API

##### Web SDK

An HTML5 video player can't circumvent these technical limitations, but it can offer an API which enables you in a smart way to switch between muted and unmuted autoplay.

THEOplayer has the `mutedAutoplay` property in the `PlayerConfiguration`. When you set this property to all, THEOplayer will run in unmuted autoplay on browsers where this is allowed, and in muted autoplay where autoplay with sound is not allowed. You can find a valid example below:

```js
// ...
var player = new THEOplayer.Player(element, {
  // ...
  mutedAutoplay: 'all',
  // ...
});
// ...
player.autoplay = true;
// ...
```

There's a possibility that new restrictions will be introduced in the future, so it's advised to keep autoplay restrictions in mind when developing your product.

---

# Why does fullscreen not behave as expected on iOS

One of the most frequently encountered issues on iOS devices is unexpected behavior concerning fullscreen playback.

This is in fact an iOS limitation, since iOS + Safari does not allow showing non-video elements in fullscreen, as mentioned on this [support matrix](https://caniuse.com/#feat=fullscreen).

THEOplayer's workaround involves playback in full-window, which sets THEOplayer's container to a `width` and `height` of 100%. Other elements can be placed on top of this view by giving it the CSS property `position: absolute;` (Combined with a top/bottom/right/left value) If this is not desired, reduce the `z-index` of these other elements.

Note that this solution keeps the THEOplayer UI intact, but doesn't get rid of the address bar as desired in some cases.

Alternatively, developers can use the [allowNativeFullscreen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerConfiguration#allowNativeFullscreen) property mentioned here, which pushes the video element to fullscreen as seen below.

```js
<script>
    var element = document.querySelector('.theoplayer-container');
    var player = new THEOplayer.Player(element, {
        libraryLocation : '/your_library_location/',
        license: "your_license",
        allowNativeFullscreen: true,
        ui : {
            width : '500px',
            height : '100px'
        }
    });

    player.source = {
        sources : [{
            src : '//cdn.example.com/index.m3u8',
            type : 'application/x-mpegurl'
        }]
    };
</script>
```

The downside of this approach is that the iOS native look & feel will replace the custom UI, although the address bar will be gone.

When you go full-window in an iframe, you won't see the container of the video grow because the iframe can't get any larger.

---

# Why does the Network API not work on iOS devices

Most Network API capabilities are not available on iOS devices. Generally speaking, video playback on iOS behaves like a black box. This black box handles the requests (and responses) related to video manifests and segments, which makes them impossible to intercept. This limits the possible uses of the Network API on such devices.

The Network API can still be used to intercept and alter requests and responses unrelated to video playback manifests and segments (e.g.: DRM-related requests and responses).

---

# Why does Chromecast not work on iOS Chrome?

iOS Chrome used to support Chromecast. However, Google silently removed support for it at some point. It is also documented [on their Web Sender guide here](https://developers.google.com/cast/docs/web_sender) that:

> **Info**
>
> Casting (Chromecast) is not supported on the iOS Chrome browser.

You can still implement Chromecast inside a native iOS app following our guide [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/cast/chromecast/enable-chromecast-on-the-sender.md).

---

# Why can't I select another video quality on iOS/tvOS?

**In short**: Apple technically restricts video players from doing this, and there is no workaround.

#### The case for iOS Safari, macOS Safari, iOS SDK and tvOS SDK

Any HTML5 video player, like THEOplayer, needs to use native technologies to do video playback, decoding and decryption. On web browsers, video players typically leverage the MSE and EME API by default. If this API is not available, then video players have to rely on native playback to handle video playback, decoding, decryption and ABR selection.

On iOS browsers, THEOplayer has to use the native playback pipeline, instead of the [MSE](https://developer.mozilla.org/en-US/docs/Web/API/Media_Source_Extensions_API) and [EME](https://developer.mozilla.org/en-US/docs/Web/API/Encrypted_Media_Extensions_API) API. The native playback pipeline on iOS also exposes an API, but this API doesn't expose any information on the available qualities in a HLS stream, nor does it indicate which quality is currently active.

When a FairPlay DRM protected stream is used, we are limited by the same scenario on macOS Safari since for DRM playback we rely on the native pipeline.

The underlying AVFoundation stack on iOS/tvOS SDKs, which THEOplayer has to use, brings along the technical limitation that you cannot select a specific video quality. Instead, you can set a maximum resolution or bitrate as explained [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/select-video-track-quality.md#usage-for-hls-streams).

In result, THEOplayer cannot offer functionality to developers and viewers to change qualities on these scenarios.

## Resources

The following resources provide more information:

* <https://developer.mozilla.org/en-US/docs/Web/API/Media_Source_Extensions_API>
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/ios/media-tracks/select-video-track-quality.md#usage-for-hls-streams)

---

# Is YouTube supported

This question above is typically asked by customers who have experience with the YouTube embedded player. It's also related to the following questions:

* Does THEOplayer support the playback of YouTube videos?
* How do you embed YouTube inside THEOplayer?

It is not legal to embed YouTube videos inside any video player, and overlay any custom UI elements. You can not use the YouTube embedded player inside THEOplayer.

Source: <https://developers.google.com/youtube/terms/required-minimum-functionality>:

> You must not display overlays, frames, or other visual elements in front of any part of a YouTube embedded player, including player controls. Similarly, you must not use overlays, frames or other visual elements to obscure any part of an embedded player, including player controls.

Links:

* <https://developers.google.com/youtube/terms/api-services-terms-of-service>
* <https://developers.google.com/youtube/terms/required-minimum-functionality>
* <https://developers.google.com/youtube/terms/developer-policies>

---

# Why does the player load only one audio track (even though there are several in the manifest)

You may be asking this question if you notice a discrepancy in the number of audio tracks present in the manifest and the audio tracks that you can select from the player UI.

Similar questions may be:

* How to make all audio tracks in of my stream appear in THEOplayer
* Why the player does not return the correct audio tracks?
* Why does the player detect only one of the audio tracks of my manifest?

First of all, a reassuring word: if your manifest is well-formed and contains multiple audio tracks, you do not need to do anything to import them all, as the player does this by default.

However, if your audio tracks are missing, it usually means that something in the manifest is wrong. **If the manifest is indeed correct according to specs, this kind of behavior may occur if the video track includes also audio** (even in the presence of separated audio tracks). In this case, the player considers that audio track as primary and ignores all the others.

In other words, when you want to be able to switch between different audio tracks, take care that all of them are included in the manifest separately from the video and that the video track does not include any audio track. This will also result in a slightly faster download time.

---

# Is it possible to see 360 degrees photo with THEOplayer

This question is asked by those users and developers that are wondering if the player 360 degree functionality can be used to view also images.

No, this cannot be done. The player is intended for video sources, so an image as input is not officially supported, which is also true for 3D images.

---

# Why the Visibility API does not work through an iframe on Safari and IE11

This question may be asked when you observe a different behavior of the Visibility API on different browsers.

The [Visibility API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Visibility) provides developers a way to observe how much of the player is visible.

When the player is embedded in an iframe, this API does not work on Safari and IE11. This depends on the fact that the player uses the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#Browser_compatibility) if it's available in the browser. Unfortunately, IE and Safari do not have support for this, so the player necessarily falls back to scroll events for these environments.

This is the reason why on those browsers the Visibility API works correctly when the player is on the page but it is not functional through an iframe.

February 2019: A piece of good news: the Intersection Observer API is now in beta in Safari: <https://webkit.org/blog/8582/intersectionobserver-in-webkit/>

---

# What is an impression

This article explains what an impression is and how THEOplayer calculates impressions.

THEOplayer will count an impression when the video or audio source is being played for the first time by our SDK. This can be triggered by a user clicking the Play button, or by playing the video automatically (autoplay). When you pause, play or seek within the same video or audio source, it still will be counted as only one impression. If a user refreshes the page or reloads the application, a second impression will be counted. If the content contains ads, these will not be counted towards the impression count. Except when the content only contains ads, then these will be counted towards the impression count.

As an example, if you start a video, pause the video and then resume again it is only considered one impression. If on the other hand you start a video and then refresh your browser, or reload your application, it would be considered 2 impressions.

---

# How to know whether a live stream is playing

You can check if a stream being played is live or VOD by checking its duration. If the duration returns `Infinity`, the stream would be live. Examples:

##### Web SDK

```js
var isLive = player.duration === Infinity; // true or false
```

##### Android SDK

```java
boolean isLive = Double.isNaN(tpv.getPlayer().getDuration()); // true or false
```

---

# Which error related events does the player expose

THEOplayer exposes different types of errors. Refer to "[How to do error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/error/error-handling.md)" for information on how to programmatically detect an `error` event through an event listener.

Note that only the `error` events in the "Player API" are fatal. Error events dispatched in different APIs (e.g. Ads API) are considered non-fatal, because some level of playback might still be possible, or the video player might recover from it.

| API                    | Event                                        | Use                                                                            | Example/how to trigger                                                           |
| ---------------------- | -------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Player                 | error                                        | Triggered for media issues, NOT network issues                                 | A poorly encoded segment                                                         |
|                        | segmentnotfound (not on iOS + only for DASH) | A segment was not found                                                        | A 404 returned on a segment                                                      |
| Ads API                | aderror                                      | Something went wrong during ad handling                                        | Empty ad tag / Adblocker                                                         |
| Network API (web only) | offline                                      | Thrown to indicate that the stream is offline                                  | DASH: take whole stream offline<br /><br />HLS: take 1 segment offline is enough |
| Chromecast API         | error                                        | Thrown to indicate that there was an error while casting / trying to cast      | Unplugged Chromecast power cable during casting                                  |
| Android Player API     | NoSupportedRepresentationFoundEvent          | Indicates that none of the provided representations is supported by the player | Trying to play a 4k stream encoded in AV1                                        |

---

# Why did my subtitles stop working

This question is occasionally asked by developers who've configured the latest release of THEOplayer.

### Before version 2.80

The most common reason on an older build why closed captions are no longer working is because the **`texttrackrendering` feature isn't enabled**. To verify whether this feature is enabled you can execute the query below.

```js
var subsEnabled = THEOplayer.features.indexOf('texttrackrendering') > -1;
```

### After version 2.80

Starting in THEOplayer version 2.80 the `texttrackrendering` feature is no longer an optional feature. It is instead part of the default build, and is always enabled.

### Other frequent reasons:

* A new stream is configured which does not list any subtitles in its manifest.
* The subtitle file can't be retrieved. (e.g. 404)
* There are CORS issues with the subtitle file.
* The subtitle file is encoded in a non-compatible format.

---

# How does Media Engagement Index (MEI) affect Autoplay on Chrome

The question above is related to the following questions:

* Why is autoplay not working on Chrome?
* Is THEOplayer limited by the Media Engagement Index?

In summary, **it's possible that on the desktop-version of Chrome (unmuted) autoplay is no longer working on your web page due to the Media Engagement Index**. The following two strategies can help you resolve this issue:

1. Increase your MEI.
2. Enable muted autoplay. ([How to combat autoplay policies](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-combat-autoplay-policies.md))

You can read more about Chrome's autoplay policy at <https://www.theoplayer.com/blog/chrome-autoplay-policy-what-you-need-to-know>. A demo illustrating this policy can be viewed at <http://demo.theoplayer.com/autoplay-policy>.

Remarks

* The following scenario is possible due to the Chrome autoplay policy: when you first land on a web page, unmuted autoplay is not permitted. When you click through to another page, or refresh the page, unmuted autoplay is permitted, due to the additional user interactions which affect the MEI.
* You can check your MEI at chrome://media-engagement/.

---

# What does the error message 'Unknown CDM error' mean

If you got to see this page, you probably know that CDM stands for Content Decryption Module, which is a component in the DRM pipeline, a part of the content protection process.

There are 2 scenarios where this error can be triggered:

* If a user is watching a DRM-protected stream, and then tries to Airplay **their whole screen** (In the device status bar as opposed to AirPlaying by clicking the icon in THEOplayer when watching in Safari). Because it cannot be guaranteed that the content is not being hijacked in this scenario, the player throws the "Unknown CDM error". This scenario is Mac/Safari specific.
* A second scenario where you would see this error is when, on iOS, you record your screen with built-in or third-party software while playing DRM-protected content. This scenario is iOS specific. Safari uses media error code 5, according to VideoJS documentation (<https://docs.videojs.com/mediaerror>)

Using this knowledge, developers could handle this error by capturing the 2 cases under one, more generic message towards the user e.g. 'This content is protected and can't be viewed this way.'

---

# What does the error message 'Something went wrong with Native playback' mean

This error, "Something went wrong with Native playback", occurs whenever the player struggles on the native rendering pipeline of the browser in use. The error code itself can be different, and it reflects the HTML5 MediaError interface.

"Something went wrong with Native playback" is a possible error message which can be exposed by THEOplayer. Although it sounds generic, it is related to native rendering, as explained above.

## Native Rendering

Native rendering is used when THEOplayer leverages the native media playback pipeline. Usually, THEOplayer leverages this when this pipeline is the only possible pipeline, for example when you can't use MSE.

Examples:

* When doing playback on iOS Safari, THEOplayer will do native playback, because native rendering is the only option on iOS Safari.
* When a plain MP4 asset is configured, instead of an HLS or MPEG-DASH stream, THEOplayer will do native rendering.

Native rendering can log an error due to multiple causes, but they relate to MediaError code. There are several MediaError codes, but for this case the ones relevant are:

* `MEDIA_ERR_DECODE: 3` – This is shown when a media resource was deemed as usable, but when trying to decode the media resource in question it appears to have some problems in it (can be segments missing,...).
* `MEDIA_ERR_SRC_NOT_SUPPORTED: 4` – The source added to the player is not suitable for this playback. A good example would be trying to play a DRM protected DASH stream on Safari (Safari only supports HLS-FairPlay)

The THEOplayer API can be used to access the MediaError code: `player.error.code`

This line will return the MediaError together with the specific code. This makes it easier to find out what the error exactly means, and allows developers to plan for further actions.

## Related articles

* <https://developer.mozilla.org/en-US/docs/Web/API/MediaError>

---

# Why are not all response headers exposed

You may ask this question if, for example, you are trying to intercept a certain XHR response to use data contained in custom headers but you don't find these among the exposed headers (see documentation below regarding network interceptors).

This happens because by default, only some headers are exposed by default. You can however decide to specify which additional headers you want exposed. This is done through the Access-Control-Expose-Headers response header. It "indicates which headers can be exposed as part of the response by listing their names" (see [documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers)).

---

# Why does the currentTime seem off in my livestream & what can I do about it

THEOplayer has a currentTime property, which returns you the current playback position in the video (in seconds). For VOD this works as you would expect. If you have a video, let it play for 30 seconds and query the currentTime, the player will report 30 seconds. However, if you start watching a livestream and query the currentTime after 30 seconds, you won't get 30 seconds reported. Nor will you get the time that would have elapsed if you watched the segments in the most recent manifest file until the point where you queried the currentTime. This might seem odd, but there's a very good reason for this, which we'll explain in a bit, along with some workarounds if you do want to use one of the aforementioned definitions of currentTime in a live streaming context.

To calculate the currentTime, THEOplayer follows the HTML5 specification. However, for livestreams, this is not specified. Hence, if you try to use currentTime for synchronization between players, you'd get different behavior among different players. It's even possible to see different behavior among different streaming protocols in conjunction with the same player.

The internal implementation THEOplayer uses, is constructed to never have a negative currentTime. A few things are being checked to ensure this:

* Check if it's a VOD. In this case the timeline starts at 0
* In case it's a live stream, there are two options

**It's a live-EVENT stream**

* Manifest contains `EXT-X-PLAYLIST-TYPE: EVENT`
* All renditions started at the same time, so the first segment would have timestamp 0

**It's a livestream with a DVR window**

* For these some players choose to start the 0-offset at the start of the first segment
* However, segments are not necessarily aligned across multiple renditions:
* Switching renditions can cause new content to become available before the start timestamps of the first rendition
* Such a segments would halve a negative start timestamp
* To avoid negative timestamps, THEOplayer keeps an offset of 3 target durations from the start as its zero-reference

How can you deal with this if you want to synchronize players or get a zero-based timestamp? You have **3 options**:

1. Use `EXT-X-PROGRAM-DATE-TIME`, which gives you an absolute time reference.
2. Make your stream an event stream by including `EXT-X-PLAYLIST-TYPE: EVENT` in the manifest
3. Use the player's seekable property (which is based on the manifest) and query seekable.start(0) to find the starting time of your stream 3.1 Attach an event listener for the 'durationchange' event (triggered the first time a media playlist is loaded) 3.2 Upon this event, store player.seekable.start(0) in a variable 'timeOffset' and remove the eventlistener 3.3 Subtract the value of 'timeOffset' from the player's currentTime to get a zero-based timestamp

Here's a code snippet for option 3 :

```js
function AbsoluteTimeline(player) {
  var timeOffset = 0;

  function durationchangeHandler() {
    timeOffset = player.seekable.start(0);
    player.removeEventListener('durationchange', durationchangeHandler);
  }
  player.addEventListener('durationchange', durationchangeHandler);

  return {
    getOffset: function () {
      return timeOffset;
    },
    getCurrentTime: function () {
      return player.currentTime - timeOffset;
    },
    seek: function (timestamp) {
      player.currentTime = timestamp + timeOffset;
    },
  };
}

var timeline = AbsoluteTimeline(player);
```

---

# How to remove CORS restrictions from a reproduction stream

A "CORS-issue" is a common cause of a stream not starting. In a nutshell, a CORS issue implies that the origin is not allowed to fetch the resource. This issue has to be resolved from the server-side.

Additionally, sometimes we ask customers to alter their CORS-policy in order to playback streams from a development environment. A CORS-issue blocks us from deploying the stream in our development environment.

---

# Which network calls (or requests) does THEOplayer do

The question above is related to the following questions:

* What is the call to license.theoplayer.com?
* Why is THEOplayer sending a request to licensing.theoplayer.com?
* What is the call to licenseapi.theoplayer.com, and why is it failing?

THEOplayer can do three different network requests to `*.theoplayer.com` which are not related to your stream.

1. `license.theoplayer.com`: this request logs an impression to THEOplayer's analytics server. THEOplayer uses impressions to know how many views you've received, because it's taken into account for billing purposes. The analytics server does not track personal information on your users.
2. `licensing.theoplayer.com/t?`: this request serves as a fallback request when the call to license.theoplayer.com fails.
3. `licenseapi.theoplayer.com/api/v1/check`: this request happens when your current license is invalid, for example on a domain (or IP-address) which hasn't been whitelisted. This request will not be successful because there's no service configured for this request. (This might change in the future.)

---

# Why does the playback not work when using the Chrome iPhone/iPad simulator

You might need an answer to this question if you are testing your page using the Chrome iPhone/iPad simulator and notice that, reloading the page, the video player stops working (even though the ads, if any, are displayed correctly) and some errors are displayed in the console.

Similar questions are:

* Why does the playback not work when using Mozilla in Responsive Design Mode?
* Why does the playback not work when using the Edge emulator to test my page on other platforms?
* Why does the playback not work when testing device-specific viewports with the browser dev tools?

The simple answer is that this occurs because the video player gets confused between the user agent (set as iOS during the simulation) and the browser actually in use. This does not imply that there is any problem with the video player. In fact, when the tested page will be accessed by an actual iOS device, the video player will work fine, in absence of other (unrelated) issues.

The same behavior is to be expected in similar tests, that is to say when a platform is emulated on another and they do not share the same playback logic of the native video element.

Some more details:

If you use Chrome + iOS simulator, your user-agent will change to iOS/Safari. THEOplayer detects this new user-agent, and because it's iOS it'll think that the MSE API is not available, and that they need to use the playback logic of the native video element. However, you're still on Chrome, so this alternate native iOS playback logic is not available. These circumstances lead to playback failure. It works for ads because they typically do not use the HLS protocol, so we do not have to leverage MSE.

It is not advisable to use (or rely on) the Chrome + iOS simulator mode to test anything else than the view mode. The native APIs which iOS offers are not available in this mode, so it's not really a useful testing mode.

---

# What does the error message 'can only be initiated by a user gesture' imply? Can I still force the desired action

You may get this error if you are trying to have the player execute an action without it being initiated by the user. A typical example is going fullscreen or automatically starting playback (often on mobile).

Related questions are:

* Why can’t I set the player to fullscreen mode on screenrotation? (Related error message: “Failed to execute 'requestFullScreen' on 'Element': API can only be initiated by a user gesture.”)
* Why is an error generated if I want to automatically start playback when certain conditions are met (Related error message: DOMException: play() can only be initiated by a user gesture)

The short answer is no, you cannot (and should not) force an action that gets this kind of error message: this is a block implemented by the browser to protect the user.

The details:

In some cases, the browser deems that a certain behavior cannot be initiated automatically and needs instead to be started by the user (or user action). This happens because these behaviors may be perceived as bad or harmful by a user, if automated. In other words, this limitation is implemented by the browser to protect the user from (for example) invasive pop ups, advertisement, etc., as well as from more serious threats to a good and safe web surfing.

To our knowledge, there is no way to force the browser to ignore this error, and you probably shouldn't want to do so, for the above-mentioned reasons. Therefore, if you incur in this situation you may want to find an alternative way to achieve the desired result (or take the hint from the browser and reconsider whether what you want to achieve is appropriate for your use case and good for the user).

Update 7/12/2018

This behavior is common on devices and on Safari.

Chrome 71, released a few days ago, also introduces the need for user interaction to go fullscreen.

---

# How to remove unwanted CC track in iOS or Safari

This article is intended to show how to remove any unwanted CC tracks that might be showing up in iOS or Safari. This can be done by editing the HLS master playlist.

**Unwanted CC in Safari native**

![Unwanted CC in Safari](/pr-932/assets/images/unwanted-cc-safari-afa200bfd56332b7a019c6a8b4d2ce62.png)

**Unwanted CC in THEOplayer iOS**

![Unwanted CC in iOS](/pr-932/assets/images/unwanted-cc-ios-9ca2c0569660319c77f96ecf29561a5a.png)

## How to remove unwanted cc tracks?

To remove any unwanted cc tracks, the “CLOSED-CAPTION” attribute has to be set to “NONE” inside the HLS master playlist. This is to be compatible with the HLS specification: <https://tools.ietf.org/html/rfc8216#section-4.3.4.2>

If it is a multi-variant stream, this has to be done for all variants.

```text
CLOSED-CAPTION=NONE
```

---

# MediaTek limitations

This page overviews a list of known issues caused by the MediaTek chipset.

## 1. Switching to fullscreen halts playback for approximately 10 seconds

The MediaTek decoder seems lackluster at handling a transition to fullscreen when **experimental rendering** is enabled because THEOplayer uses a separate Android Activity for fullscreen. Using the default rendering pipeline does not trigger this issue. A workaround is doing fullscreen without detaching the SurfaceView from the window.

### Why does THEOplayerView use a separate activity for fullscreen?

THEOplayerView uses a separate Activity for fullscreen so that the fullscreen view is completely isolated from the Activity the THEOplayerView is in. The Activity has its own orientation, window settings, and back button behavior. By using a separate Activity, we can leave those settings and the view hierarchy intact in the Activity in which the THEOplayerView is embedded.

A downside of this in case of experimental rendering is that we need to move the SurfaceView that holds the Surface on which video is rendered. This, however, means that the Surface is destroyed and a new one is created. On newer devices, this is normally no problem because the decoder is decoupled from the Surface. When the Surface is destroyed, a new one can be attached to the same decoder. On devices with an API lower than 23 (and some other devices which bug) however, the decoder can not change the Surface on which it draws without re-initialization. This means that on older and some buggy devices, switching to fullscreen will make the video hang until the next keyframe is reached in the stream.

### Solution: Fullscreen without detaching the SurfaceView from the window

If an implementer does not want the Surface to be destroyed when going fullscreen, the implementer needs to implement this themselves to fit within the Activity.

A few things are needed for this:

1. FullscreenCoupling needs to be disabled (with `getTPV().getSettings().setFullScreenOrientationCoupled(false)`).
2. If the UI is enabled, the fullscreen button needs to be hidden or overwritten. This needs to be done with [custom CSS and/or custom JavaScript](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).
3. Orientation needs to be handled in the Activity. 3.1 To change the orientation of the Activity, [`setRequestedOrientation`](https://developer.android.com/reference/android/app/Activity.html#setRequestedOrientation\(int\)) has to be called on the Activity or the Activity needs to be allowed to rotate. Allowing the activity to rotate means that the android:screenOrientation property in the [manifest](https://developer.android.com/guide/topics/manifest/manifest-intro) needs to be set to multiple values or not set. 3.2 To make sure that the Activity is not recreated on an orientationchange,android:configChanges field in the manifest need to include "orientation|screenSize". 3.3 To detect the change, the onConfigurationChanged method needs to be overridden in the Activity. In the implementation the orientation can be checked and fullscreen can be initiated or stopped depending on it.
4. To make the THEOplayerView fill the whole Activity without moving the view, the THEOplayerView and all of its parents view's width and height layout parameters need to be set to "match\_parent" and they all need to be the first child-view (with a non-zero surface area).
5. To hide the navigation buttons and status bar, the Activity should change the window and visibility flags. this can be done with: 5.1 getWindow().getDecorView().[setSystemUiVisibility](https://developer.android.com/reference/android/view/View#setSystemUiVisibility\(int\))(SYSTEM\_UI\_FLAG\_LOW\_PROFILE|SYSTEM\_UI\_FLAG\_FULLSCREEN|SYSTEM\_UI\_FLAG\_LAYOUT\_STABLE| SYSTEM\_UI\_FLAG\_IMMERSIVE\_STICKY|SYSTEM\_UI\_FLAG\_LAYOUT\_HIDE\_NAVIGATION|SYSTEM\_UI\_FLAG\_HIDE\_NAVIGATION); 5.2 getWindow().[setFlags](https://developer.android.com/reference/android/view/Window.html#setFlags\(int,%20int\))(FLAG\_FULLSCREEN, FLAG\_FULLSCREEN);
6. To let the player exit fullscreen on a back button press instead of stopping the Activity, the onBackPressed method of the Activity should be overridden with the desired behavior.
7. When going back from fullscreen, the original settings for the window and back button behavior need to be set back to desired values.

---

# How to use ProGuard with THEOplayer Android SDK

ProGuard is a popular tool to obfuscate and optimize Java code in Android projects. Depending on the settings, this tool can clash with the THEOplayer Android SDK.

Below, you can find a list of rules tested against THEOplayer Android SDK on 28 Nov 2018.

```text
-keep class com.theoplayer.android.** {*;}
-dontwarn com.theoplayer.android.**
-keep public class com.google.android.gms.* { public *; }
-dontwarn com.google.android.gms.**
-keep class android.support.v7.app.MediaRouteActionProvider {*;}
-dontwarn android.support.v7.app.MediaRouteActionProvider

# In case of using yospace integration
-keep class com.yospace.util.** {*;}
-dontwarn com.yospace.util.**

# For native Google IMA integration
-keep class com.google.obf.** { *; }
-keep interface com.google.obf.** { *; }
-keep class com.google.ads.interactivemedia.** { *; }
-keep interface com.google.ads.interactivemedia.** { *; }

# And in case of using a CastOptionsProvider and/or custom MediaRouteActionProvider for chromecast, you have to keep those classes too.
# eg:
# -keep class com.yourcomp.yourchromecastpackage.** {*;}
# -dontwarn com.yourcomp.yourchromecastpackage.**
```

---

# Self-hosting and versioning of THEOplayer

Your licensed THEOplayer can also be hosted on your own servers or CDN. This can be useful when you do not want to have a dependency on a third-party hosting infrastructure, for using THEOplayer on internal/local (and even offline) networks or for using THEOplayer inside mobile apps.

There are two approaches to download the THEOplayer SDK for self-hosting purposes:

1. Use [NPM](https://www.npmjs.com/package/theoplayer).
2. Download the SDK through <https://portal.theoplayer.com>.

> **Important**
>
> When self-hosting THEOplayer, it is important you regularly update your self-hosted THEOplayer files in order to benefit from the latest improvements.

In order to download the THEOplayer package and host it on your server, you will first have to determine which version of the player you want to use. Read up about version changes in the [changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md).

## Configuring self-hosting

Once you extracted the ZIP package to your server, you must configure THEOplayer and provide the information where the resources can be found. For this, you should configure 1 parameter correctly:

* `libraryLocation`: This parameter should point to the location of the library. It is the location where the ZIP package has been extracted and the resources are available on the server.

Of course, also keep in mind to correctly link to the correct JavaScript library and CSS file.

```html
<script type="text/javascript" src="/path/to/THEOplayer.js"></script>
<link rel="stylesheet" type="text/css" href="/path/to/ui.css" />
```

## Common mistakes

* Configuring the libraryLocation incorrectly. The referred location/folder should contain `theoplayer.d.js`, `theoplayer.e.js`, `theoplayer.p.js`, `THEOplayer.js`, and so on, and they need to all have the same version.
* Using the THEOplayer library on a web page which resides on a non-whitelisted domain (e.g. <http://localhost/index.html>). Although you can host your library assets anywhere, you can only use the actual video player on white-listed domains.
* Linking to an unreachable JavaScript or CSS library.

---

# Does THEOplayer support EXT-X-DATERANGE

Yes, the HLS tag `#EXT-X-DATERANGE` is supported in THEOplayer as of 2.61.0. To enable it, hlsDateRange needs to be added to either the player configuration or the source description and be set to true. The date range metadata will be made available through the TextTrack API.

`#EXT-X-DATERANGE` is a way of providing timed metadata in an HLS manifest. It is used to define date range metadata in a media playlist. A possible use case is defining timed metadata for interstitial regions such as advertisements, but can be used to define any timed metadata needed by your stream.

As indicated above, `#EXT-X-DATERANGE` is supported in THEOplayer as of 2.61.0. However, the feature is not enabled by default. To enable it, add hlsDateRange to the player configuration and set it to true. You can also choose (instead) to enable/disable the feature per source by adding the same option to a source in your source description.

The TextTrack API is used to retrieve the timed metadata. A MetadataTextTrack will provide cues which contain the timed metadata and will dispatch an event when started and ended.

## Remarks

* A manifest with EXT-X-DATERANGEs needs to have an EXT-X-PROGRAM-DATE-TIME to be able to calculate dates from playback times. This is also a specification requirement.
* If the tag name for a date range tag in the manifest is incorrect, the tag will be ignored
* If the name of any attribute is misspelled in a date range tag in the manifest, the attribute will not be parsed
* When using native browser playback features such as FairPlay content protection, the player might use more resources to parse date ranges from the manifest than in other scenarios.

## Resources

The following resources provide more information:

* [HLS Specification - #EXT-X-DATERANGE](https://tools.ietf.org/html/draft-pantos-hls-rfc8216bis-04#section-4.4.2.7)
* [API reference - TextTrackType](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/TextTrackType)

---

# Can clipping be used on a playlist

Yes. This is in principle not different from using it on a single video: a startTime and an endTime must be given for each video and applied when the video is loaded/played.

Let’s expand slightly the idea. You can have 2 use cases:

* The same start and end time can be used for all contents.
* Each content has a different start and end time.

## The same start and end time can be used for all contents

In this case, you can apply the Clip API without any further precaution or modification. You can find an example at the page Video clipping in THEOplayer (see below). Please remember to make sure that clipping happens after the source is set (e.g.: use a `durationchange` event).

## Each content has a different start and end time.

In this case, some adjustment is needed to be able to provide and read the right custom start and end time for each content. One possible way to do it is to simply pass such data together with the source data and read it directly from there when clipping the video, like in the example below.

```js
// an array is provided, containing multiple player.source. Each source contains startTime and endTime.
var playlist = [
  {
    source: {
      sources: {
        src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
        startTime: 100,
        endTime: 150,
      },
      title: 'Big Buck Bunny',
      description: 'Big Buck Bunny',
      poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
    },
  },
  {
    source: {
      sources: {
        src: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
        startTime: 120,
        endTime: 180,
      },
      title: 'Star Wars Reel',
      description: 'Star Wars Reel',
      poster: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/poster.jpg',
    },
  },
  {
    source: {
      sources: {
        src: 'https://cdn.theoplayer.com/video/tears_of_steel/index.m3u8',
        startTime: 50,
        endTime: 150,
      },
      title: 'Tears of Steel',
      description: 'Tears of Steel',
      poster: 'https://cdn.theoplayer.com/video/tears_of_steel/poster.jpg',
    },
  },
];

// the desired source is set in the player -
// this is not reported here as it depends on your implementation,
// but an example can be seen in the resources linked below.
// For the purpose of this example
// player.source = playlist[0];

// the following lines make sure that
// when the first playing event is fired for each (new) content
// clipping times are read from directly within the player.source

function firstplaying() {
  player.clip.startTime = player.source.sources.startTime;
  player.clip.endTime = player.source.sources.endTime;
  THEOplayer.players[0].removeEventListener('durationchange', firstplaying);
}

THEOplayer.players[0].addEventListener('sourcechange', function () {
  THEOplayer.players[0].removeEventListener('durationchange', firstplaying);
  THEOplayer.players[0].addEventListener('durationchange', firstplaying);
});
```

Notes:

* In this example, we are only describing how to apply the clipping, not how to play a playlist. For this, please consult the linked resources.
* The example is provided only in JavaScript because clipping is currently available only for the JavaScript SDK. It may be used also in other SDKs through JavaScript injection.

## Resources

The following resources provide more information:

API reference - [Clip API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Clip)

Clipping - [How-to guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/clipping.md)

---

# Can timeline thumbnails be made available before playback start

Yes, this is possible using the preload feature, provided your timeline is already visible. Both “metadata” and “auto” will be effective values to this end.

If the player on your implementation shows the timeline before playback start (differently than on our demo pages), you may indeed be interested to show the timeline thumbnails, and possibly other data (e.g.: video duration). As explained above, this may be achieved using the preload. Both values “metadata” and “auto” will work for this. The advantage of using “auto” is that also some media files will be buffered, reducing the start-up time. To know more about preload, please visit the linked resources.

In case your timeline is not visible before playback start, however, using preload will have no visible impact on the timeline thumbnails.

## Resources

The following resources provide more information:

* [Preloading - How to](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/preloading.md)
* [What are the benefits of preloading?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-are-the-benefits-of-preloading.md)
* [PreloadType API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/PreloadType)

---

# What are the benefits of preloading

Choosing whether to preload parts of the video before it starts playing will help you considerably improve the user experience.

Preloading involves loading parts of a video source before the video starts playing. When the video later starts playing, it can do this much faster because it has already downloaded some data. This can improve the user experience dramatically when you expect the user will want to play the video. On the other hand, when the video is less likely to be played, you can configure the player to not preload it and save bandwidth.

Interactive video experiences are one example use case for this functionality. In an interactive video, the user must choose between multiple options at the end of a video, with each option leading to a different video. Using preloading will help you ensure a smooth transition between videos (to this purpose you may also want to use other THEOplayer features, such as Cache API and Canvas API - see Resources).

Choosing to preload your video content will also make some data regarding the current source available before the user initiates playback. Such data include, for example, the video duration and the timeline thumbnails.

## Resources

The following resources provide more information:

* <https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-preload>: HTML5 specification
* [Preloading - How-to](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/preloading.md)
* [API reference: preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/PreloadType)
* [API reference: Cache API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Cache)
* [API reference: Canvas API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Canvas)

---

# What are the player seeking and seeked events and when are they fired

They are events related to the playback of media files. `seeking` is fired when the user starts seeking/moving to a new position. `seeked` is fired when the user is finished seeking/moving to a new position and the player has buffered a video portion, being therefore ready to play.

The player `seeking` and `seeked` events are not to be confused with the homonym `<video>` element events, although they mainly coincide in meaning and occurrence. In this regard, in THEOplayer you find both the player events and the video events.

*Seeking* and *scrubbing* are not considered equal in THEOplayer. *Seeking* is the action of starting to move to a new position and it has the corresponding `seeking` event. *Scrubbing* is the action to keep seeking to new positions while maintaining `mousedown` for a prolonged time. It has no corresponding event. Scrubbing can contain multiple seeking actions. While the viewer is scrubbing, the CSS class `vjs-scrubbing` is added on the `.theoplayer-container` element.

In other words, if the viewer does not seek directly to a new position with one click (`mousedown` and `mouseup`) but scrubs on the timeline instead, multiple `seeking` and `seeked` events may be fired. This is due to the not uniform movement while scrubbing. For example, if the pointer stays briefly in the same position while scrubbing and then resumes its motion, multiple `seeking` events may be thrown, as this is interpreted as different seeking actions. Even during scrubbing, if the pointer is temporarily staying in the same position, the player will try to buffer the corresponding video portion. If enough video is buffered and playback could start from that position, the `seeked` event will also be thrown at that moment, although the user may still be scrubbing.

## Remarks

The player events and `<video>` element events `seeking` and `seeked` should behave similarly, be fired on the same occasions and the same number of times. If they don’t, please report it in a ticket in our Service Desk.

## Resources

The following resources provide more information:

* <https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Media_events>: MDN reference
* [Player API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/classes/Player)

---

# Can we use HLS or DASH ads

Yes, we support HLS and DASH ads through a `THEOAdDescription` for the THEOplayer Web SDK 2.84.0 and up. HLS and DASH ads are currently not supported on any other SDKs. Our Google IMA integration does not support HLS or DASH ads.

To be able to play HLS or DASH advertisements, make sure to add `allowedMimeTypes` with the corresponding mime-types to your player configuration. When no `allowedMimeTypes` are specified, THEOplayer will only play progressive media types (non-streaming) as advertisements. When `allowedMimeTypes` are specified, THEOplayer will first prioritize DASH, then HLS, then progressive media types.

```js
new THEOplayer.Player(element, {
  ads: {
    allowedMimeTypes: [
      'application/dash+xml',
      'application/x-mpegURL',
      'application/vnd.apple.mpegurl',
      'video/mp4',
      'video/3gpp', // See the Remark about 3gpp at the bottom.
      'video/webm',
    ],
  },
});
```

This is currently only supported using the web pipeline. There is no support for native iOS or Android.

Using HLS ads is useful for preloading advertisements on low-end devices such as older smart TVs.

THEOplayer supports various media file formats for ads. This includes mp4-based progressive download, by far the most used format for ads, currently providing the widest coverage across devices.

If your reason for using HLS ads is the wish to use ABR to be more flexible regarding bandwidth, rest assured: VAST can (and usually does) contain multiple media files in several resolutions, qualities and formats. Among these, the most appropriate will be chosen to be played on your device or desktop browser.

## Remarks

* With the Google IMA integration, HLS and DASH ads are never played, even on platforms with native support.
* Although browsers consider `3gpp` a video codec, sometimes their support is just for the audio part. There could be cases where no video is shown. Avoid this legacy format when possible.

## Resources

The following resources provide more information:

* [IAB Standards, Guidelines & Best Practices](https://www.iab.com/guidelines/?post_type=iab_guideline)
* [API reference – Ads interface](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Ads)
* [THEOplayer Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/user-guide.md)

---

# How to change text in THEOplayer

Using language localization, you should be able to change any text in the player to the one you desire.

Language localization is not limited to only translating. It can also be used to change any text in the player.

You can change the language localization in the player configuration.

```js
ui: {
    // your other ui configuration
    language: 'fr',
    languages: { 'fr':
        {
            "Something went wrong during native playback." : "Une erreur s'est produite pendant la lectue native."
            // any other translation
        }
    }
}
```

An example on how to use language localization can be found [here](https://www.theoplayer.com/theoplayer-demo-language-localization).

---

# Change text when AirPlaying

You will need to add the 'metadata' parameter to the SourceDescription with the 'title' property filled with the title to be displayed.

In order for the Airplay title text to be changed, you will need to add a MetadataDescription. Within this MetadataDescription you have to provide metadataKeys (which can be set to nil to ignore) and a title. This title is the variable that changes the text shown when using Airplay.

## Code example

```swift
 public static var bigBuckBunny : SourceDescription {
    let typedSource = TypedSource(src: bigBuckBunnyURL, type: StreamType.hls)
    let metadataDescription = MetadataDescription(metadataKeys: nil, title: "A title")
    return SourceDescription(source : typedSource, metadata: metadataDescription)
}
```

---

# ITP2.1 problems using THEOplayer

Apple’s Intelligent Tracking Prevention 2.1 causes cookies to be only saved for 7 days unless the Safari user directly interacts with the website again.

**There will be no issues**

* If a third party CDN provider isn’t used.

**Could be issues**

* If a third party CDN provider is being used. Please check with the provider regarding ITP2.1 policy.
* Check with provider if they are using authentication that uses third party cookies

With ITP 2.1, all persistent client-side cookies, i.e. persistent cookies created through document.cookie, are capped to a 7-day expiry. This causes cookies older than seven days to be destroyed, which leads to the user being identified as a new user who hasn't seen the site before.

# Resources

The following resources provide more information:

* <https://www.seerinteractive.com/blog/what-is-intelligent-tracking-prevention/>
* <https://webkit.org/blog/8613/intelligent-tracking-prevention-2-1/>

---

# Removing context menu 'Powered by THEOplayer...'

The context menu can be removed while building your player by disabling the "contextmenu" feature or by adding a CSS rule on your page.

You can disable the context menu in the style sheet like this:

```html
<link rel="stylesheet" type="text/css" href="/path/to/ui.css" />

<style>
  .theo-context-menu {
    display: none;
  }
</style>
```

## Related articles

* [How can we disable the right click?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/context-menu/disable-right-click.md)
* [How to change the Context Menu?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/context-menu/change-context-menu.md)

---

# What aspects of THEOplayer do we need to take into account to deploy a proper Content Security Policy (CSP)

The script-src 'self' and 'inline' should be allowed. The player also requires doing calls to \*.theoplayer.com and to wherever the JavaScript files and workers are located. Additionally, depending on your active features, you may need to add some other source (e.g.: if you are using Chromecast, you will need to allow <https://www.gstatic.com/>, as its library is hosted there).

Designed to be fully compatible with browser versions that don’t support it, Content Security Policy (CSP) is an additional layer of security that helps to detect and mitigate certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks. Configuring Content Security Policy involves adding the Content-Security-Policy HTTP header to a web page and giving it values to control resources the user agent is allowed to load for that page. (source: <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>)

When configuring CSP on your pages including THEOplayer, you will need to allow:

* \*.theoplayer.com, as the license needs to contact this domain
* the domain(s) where your JavaScript and worker files are hosted
* script-src: 'self' and 'inline'
* any domains hosting the libraries related to the features of THEOplayer that you are using. For example, Google IMA, Chromecast, FreeWheel, Youbora, Conviva, etc.

## Resources

The following resources provide more information:

* <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP/>

---

# How can we avoid that the player keeps looking for chunks/segments if they are not found

You can use the Network API events to detect whether the stream is offline and implement the behavior you prefer. This is working for HLS and is being implemented (2020) for DASH as well.

When a playlist is loaded that returns 404, the player fails and returns error. However, when the playlist is present but the segments are not available (404), the player will keep looking for segments, if left on its own, in an attempt to play back the video as soon as it’s available.

In this case, however, you can decide to implement a behavior managing this situation by using the Network API, and more precisely the offline event. After some attempts, this event is thrown to indicate that the stream is offline.

The opposite event, online, is also present in the API, and it is Thrown to indicate that the stream has come back online and the player can continue playback. As this usually occurs after an 'offline' event is thrown, the two events may be used in combination to provide more elaborate behaviors.

## Remarks

* On some platforms (e.g.: iPads) when the segments are unavailable, an `error` event is thrown, differently than for the majority of platforms. This inconsistency is due to the lack of MSE (and EME) support on such platforms, which triggers the more generic error event.

## Resources

The following resources provide more information:

* [Network API events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/NetworkEventMap)
* [Network: How to use the Network API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/network/introduction.md)

---

# Can we show a custom message on 403 on mp4

Yes, this is possible, but not as easy as for DASH and HLS. To address this specific use case no internal THEOplayer tool exists yet (2019) and a separate XHR call needs to be done to determine the exact status of the request. Custom texts, overlays and buttons can be showed on the player following the instructions from the related linked resource.

It is easier to address this question in two steps: detection and message.

## Detection

The current (2019) error detection and differentiation in THEOplayer is not yet as specific as we would like and as detailed as some particular use cases, such as this one, may have a use for.

For HLS and DASH, the Network API (see Resources) can be used to intercept, filter and “read” the requests one is interested in, to determine whether something should happen (an error message, for example).

This is not possible with mp4, however, as it is played natively and the Network API cannot be applied. The solution in this case is to do a separate XHR request and read its status. Something along the lines of:

```js
var XMLHttpRequestObject;
var requestObject;

function reqListener() {
  XMLHttpRequestObject = this;
}
requestObject = new XMLHttpRequest();
requestObject.addEventListener('load', reqListener);
requestObject.open('GET', 'https://httpstat.us/403?sleep=100');
requestObject.send();

XMLHttpRequestObject.status; // result should be 403 - this may be used for a control that, if true, prints on the overlay the desired error message.
```

One disadvantage of this is that additional data is requested and it may slow down the page and increase the start-up time, especially if you implement an autoplay behavior.

## Message

Back to our specific use case, once you have determined that your mp4 returns a 403 status, you will need to add a custom overlay on the player, showing a message of your choosing. This is because the generic error message “Something went wrong during native playback” that will show up is no longer editable at this point (see remarks), so you will need to cover it up with your own message. This can be done player following the instructions from the related linked resource: “Adding buttons and text to the default UI”.

## Remarks

* This specific use case is different from the more generic personalization of texts and messages on the player, that can be done through language localization (please check the linked resources). Language localization is applied at the moment in which the player instance is created, so it cannot be used to alter texts once the player has been generated.

## Resources

The following resources provide more information:

* [API reference - Network API events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/NetworkEventMap)
* [How to use Network API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/network/introduction.md)
* [What does the error message "Something went wrong with Native playback" mean?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-does-error-something-went-wrong-during-playback-mean.md)
* [Demo page - Adding buttons and text to the default UI](http://demo.theoplayer.com/adding-buttons-text-overlay-to-theoplayer)
* [How to change text in THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-change-text-in-theoplayer.md)
* [Which error related events does the player expose?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/which-error-related-events-does-player-expose.md)
* [How to do error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/error/error-handling.md)

---

# Can we prevent UpNext feature from redirecting

Yes, this is possible. You need to modify the countdownDuration value in your UpNextPanel to Infinity.

The THEOplayer UpNext feature is generally used to play another content or redirect to another page, after a small delay. It is also possible to simply suggest the next content, but never actually redirect to it.

This is done by setting the value of the countdownDuration property of your UpNextPanel interface to Infinity: no countdown will happen, only the play button will appear to go to the video that is up next.

## Resources

The following resources provide more information:

* [API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/UpNextPanel#countdownDuration)
* [Demo page – Up Next](https://www.theoplayer.com/theoplayer-demo-up-next)

---

# Is it possible to preload VOD content while the pre-roll is playing

Yes, it is done with the preload feature. Before setting your source, you need to activate preload on your player. We advise to use the value ‘auto’: this allows the first segments of the stream to be downloaded during the ad, reducing the start-up time of the video content.

For more details regarding preload and how to implement it, please visit the resources linked below.

## Resources

The following resources provide more information:

* [Preloading - how to](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/preloading.md)
* [Demo page](https://demo.theoplayer.com/preloading-vod)
* [What are the benefits of preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-are-the-benefits-of-preloading.md)
* [API reference - PreloadType](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/PreloadType)

---

# Why is my video not playing automatically

There is a wide variety of possible causes that bring to a video not being automatically played. These may have to do with autoplay policies, iframes, Media Engagement Index and more. Please read the full answer in this article for more information. Also, please keep in mind that this is not an extensive list of causes for autoplay failure and that, as time goes by, browsers autoplay management and autoplay policies may change.

If you want your video to play automatically once the player is available, you should set the `autoplay` feature to `true`.

However, sometimes this does not lead directly to the desired result: different issues may be preventing the automatic reproduction of your video. In the following we will be listing some of the most common causes for this.

### Play

Some issues depend on the fact that autoplay is not really implemented, but the method `play()` is called on the player instead. Although in specific cases this may work, we do not advise to use this instead of the autoplay, as often this is more strictly blocked by autoplay policies and may produce, in certain cases, desync with the UI buttons (e.g.: the button suggests that the stream is playing although it’s not) or other issues.

**Solution**: for autoplay behavior, use the provided `autoplay` feature.

### Autoplay policies

Different browsers have different autoplay policies. For the specifics, please consult the policies themselves, as they may get updated. In general, though, when an autoplay policy is applied, it is possible to still autoplay a video if the player is muted.

**Solution**: to enable this, please use the `mutedAutoplay` property in your player configuration and set it to `all`.

### Chrome Media Engagement Index (MEI)

On the desktop-version of Chrome (unmuted) autoplay may also appear not to be working on your web page (while it does on your localhost). In this case the problem may be due to the Media Engagement Index. The MEI measures an individual's propensity to consume media on a site. The MEI score is highest on sites where media are played on a regular basis. When it is high enough, media playback is allowed to autoplay on desktop only.

**Solution**: the following article explains two ways to avoid this problem.

[How does Media Engagement Index (MEI) affect Autoplay on Chrome?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-does-mei-affect-autoplay-on-chrome.md)

### Iframes

When playing a video through an iframe, your autoplaying issues may be due to the iframe itself. In this case the issue comes from the fact that the iframe does not allow autoplay. Although this shouldn’t be a common problem when using a player, there have been cases in which this piece of advice was useful.

**Solution**: include the attribute `allow="autoplay"` in your iframe.

### iOS 11 and following

Apple made it that from iOS 11 and onwards autoplay is automatically muted from the start and added some settings that can remove autoplay from any site.

So it is possible that on your device autoplay is not working on Safari while it is working elsewhere.

**Solution**: check if the feature is disabled on the device. If it's explicitly disabled, the setting would be under Accessibility > Per App Settings > Add App > Safari > Safari > Auto-Playing Video Previews. Otherwise it would be enabled.

## Resources

The following resources provide more information:

* [Autoplay policy in Chrome](https://developer.chrome.com/blog/autoplay/)
* [Stop autoplay videos in Safari on Mac](https://support.apple.com/en-gb/guide/safari/ibrw29c6ecf8/mac)
* [Allow or block media autoplay in Firefox](https://support.mozilla.org/en-US/kb/block-autoplay)
* [How does Media Engagement Index (MEI) affect Autoplay on Chrome?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-does-mei-affect-autoplay-on-chrome.md)
* [API reference - mutedAutoplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/PlayerConfiguration#mutedAutoplay)
* [How to combat autoplay policies](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-combat-autoplay-policies.md)

---

# Is it possible to have multiple player instances play at the same time

Yes, this is possible, provided there are enough bandwidth and RAM for this to work (considering both server and client side). Although we don’t explicitly advise against this, we see how this could not be an ideal solution for the viewers. Please also keep in mind that this incurs into some limitations.

If your use case reckons on having multiple player instances play at the same time, this is indeed possible. In addition to the concerns expressed above, some precautions are to be considered. In fact, you may want to:

* find an alternative solution for mobile devices and in case of slow connection or low RAM, not to aggravate the user experience
* set to 0 the volume of all players (or all except one), to avoid cacophony
* consider strategies to activate and pause player instances when they are not used (e.g.: when they are out of the visible portion of the screen) to reduce RAM and bandwidth consumption
* check whether your use case can be achieved with gif replacing some of the player instances, especially in the case of short loop videos (e.g.: used as icons or to give a brief preview of your content).

One other thing to take into account are the possible platform/browser limitations.

From iOS-Specific Considerations:

> Currently, all devices running iOS are limited to playback of a single audio or video stream at any time. Playing more than one video—side by side, partly overlapping, or completely overlaid—is not currently supported on iOS devices. Playing multiple simultaneous audio streams is also not supported. You can change the audio or video source dynamically, however.

## Remarks

It is also worth mentioning that iOS loads a maximum of 16 (non-simultaneous) videos on a single web page and then gives a black display for any additional one. The page documenting this has disappeared (fall 2019), though, so this may have changed (or be changed) in newer iOS versions.

## Resources

The following resources provide more information:

* <https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/Using_HTML5_Audio_Video/Device-SpecificConsiderations/Device-SpecificConsiderations.html#//apple_ref/doc/uid/TP40009523-CH5-SW1>

---

# Is it a problem if the viewer pauses a live stream for longer than the DVR window

In general, this is no problem as the player will continue playback, once exhausted the current buffer, from the nearest point available, in this case the end of the sliding window.

The viewer may perceive this as a peculiar behavior. They will see at first a small video portion still player that connects to what they were watching before pausing the video: this is what was contained in the current buffer. Then the player will appear to seek on its own, without the user requesting it, to a new position.

In case you wish to avoid this behavior and skip the current buffer, this is also possible with a simple snippet that on resume checks whether the current position is still within the DVR window, and if it is not, then it seeks directly to a new position (without playing the current buffer).

This is a JavaScript example for this, where the DVR window is 60 sec long and the new custom position to seek to is in the middle of it.

```js
player.addEventListener('play', () => {
  player.currentTime = player.seekable.end() - player.currentTime > 60 ? player.seekable.end() - 30 : player.currentTime;
});
```

---

# THEOplayer Features & Modules

The THEOplayer SDK consists of modular features.

When building an SDK (i.e. license), you can specify which features are enabled. Only a subset of features are enabled by default, such as "HLS", "MPEG-DASH", "UI", "Chromecast", "Airplay", "Ads", and "Text Track Rendering".

This modular approach allows you to optimize the file size of your THEOplayer SDK.

## How do I enable or disable certain features?

You can do this through our [Portal](https://portal.theoplayer.com/).

![Portal: enabling features of a new SDK](/pr-932/assets/images/portal-features-new-sdk-c6a364411cedbb1fc26bdb8fd66f9631.png)

* If you're creating a new SDK, you can enable (and disable) features.
* If you want to toggle certain features for an existing SDK, you need to navigate to your SDK, update it, and re-publish it.

## My feature isn't working?

Many features sit behind this modular structure. For example, the VR API or Up Next API won't work unless you've enabled the feature when creating your SDK.

## How do I know which features are enabled?

You can log in to [portal.theoplayer.com](https://portal.theoplayer.com/) and navigate to your account. Once you're there, you further navigate to your desired SDK and check how you've customized your features.

![Portal: enabling features of a new SDK](/pr-932/assets/images/portal-features-existing-sdk-c4750657976aabfcf780be702fa46cbe.png)

If you're a developer (and you're only interested in this answer for the THEOplayer Web SDK), then you can also figure this out at runtime through JavaScript. You can call [`THEOplayer.features`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/variables/features) to identify which features are enabled.

```js
THEOplayer.features;
// (29) ["dash", "hls", "chromecast", "ads", "airplay", "yospace", "spotx", "vr", "conviva", "cache", "visibility", "webaudio", "youbora", "mediamelon", "moat", "google-dai", "streamone", "v-nova", "freewheel", "agama", "ui", "relatedcontent", "social", "upnext", "contextmenu", "texttrackstyle-ui", "activequalitylabel", "upcomingadnotification"]
```

## How do I quantify my optimizations?

After optimizing your SDK, by enabling and disabling certain features, you might want to quantify those actions.

* You could compare the file size of your THEOplayer.js files. For example, when building THEOplayer 2.78.1, with only the "HLS" and "UI" feature enabled, the library size is 315 kB. THEOplayer 2.78.1, with almost all features enabled, is almost 77% larger at 558 kB.
* You could [measure the loading time of your THEOplayer library](https://codesandbox.io/s/github/THEOplayer/samples-web?file=/reference-apps/utility/measure-loading-time/index.html).

Note that optimizing a video player goes way beyond reducing your file size. As a developer, you could consider [async library loading](https://demo.theoplayer.com/async-library-loading), you could change your [ABR strategy](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/ABRStrategyType) (as [demonstrated](https://demo.theoplayer.com/increase-viewer-experience-optimizing-video-abr)), you want to optimize your [time-to-first-frame](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/player/measure-time-to-first-frame.md), and much more!

---

# Chromecast on my webplayer does not work any longer despite no change in my implementation

This or a similar question may be asked in case your Chromecast stops working. There may indeed be different causes why your Chromecast is not working, especially if

* you changed or updated something in your implementation (Steps: review which change broke the feature)
* it's the first time you are trying it out (Steps: make sure your license includes the `chromecast` feature; have a look at our online documentation)
* you are trying to connect to a custom Chromecast Receiver application (Steps: check our online setup documentation and this article; check this article for a guide to debug your custom Chromecast Receiver application)

(Note: if the error is not found, please log a ticket into our service desk)

> However, in this article we are not covering all possible causes for a broken Chromecast: we are here referring specifically to a previously working implementation that has not been changed, and on which the Chromecast icon is no longer appearing.

So, if there have been no changes on your page but the Chromecast icon in your webplayer does not appear any longer, you might want to check that:

* The Chromecast device is connected and on the same network as the sender webplayer
* If on Chrome version 72.0.3626.81 or superior, you are casting over https (not on http)

Chrome does indeed no longer allow casting over http, but this will work properly over https.

---

# How to track network errors

THEOplayer currently doesn't throw an `error` event for all network request errors on all platforms. Sometimes you might want an event to listen for to track network related issues in your QoS/QoE dashboards. To enable this, you can use our Network API.

## Web

You can use the Network API as follows to track network requests with status codes 4xx and 5xx

```js
function httpErrorInterceptor(response) {
  if (response.status >= 400 && response.status <= 599) {
    var errorDetails = {
      status: response.status,
      fileType: response.request.type,
      url: response.request.url,
    };
    var networkErrorEvent = new CustomEvent('THEOnetworkerror', {
      detail: errorDetails,
    });
    document.dispatchEvent(networkErrorEvent);
  }
}

player.network.addResponseInterceptor(httpErrorInterceptor);
document.addEventListener('THEOnetworkerror', console.log);
```

## Android

For Android, you'll also use the Network API as you would with our Web SDK but you need to do it through JavaScript injection and pass a message to your Java environment. You need to follow these steps:

1. Make an `assets` folder, for instance under `android/app/src/main/assets` and add a JavaScript file, say `interceptor.js`

2. Add your network interceptor code but include a line to send a message with to be able to use the event's information in your Java code

   ```js
   function createHttpErrorInterceptor() {
     var player = THEOplayer.players[0];
     var interceptor = function (response) {
       if (response.status >= 400 && response.status <= 599) {
         var errorDetails = {
           status: response.status,
           fileType: response.request.type,
           url: response.request.url,
         };
         theoplayerAndroid.sendMessage('THEOplayer.network.error', JSON.stringify(errorDetails));
       }
     };
     player.network.addResponseInterceptor(interceptor);
     THEOplayer.HttpErrorInterceptor = interceptor;
   }

   function destroyHttpErrorInterceptor() {
     if (THEOplayer.HttpErrorInterceptor) {
       var player = THEOplayer.players[0];
       player.network.removeResponseInterceptor(THEOplayer.Interceptor_404);
       THEOplayer.HttpErrorInterceptor = undefined;
     }
   }
   ```

3. Link the JavaScript file to your THEOplayer instance as follows

   ```xml
   <com.theoplayer.android.api.THEOplayerView
       android:id="@+id/theoPlayerView"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       app:layout_behavior="@string/appbar_scrolling_view_behavior"
       app:jsPaths="interceptor.js"/>
   ```

4. In the Java file where you configure THEOplayer add the following:

   ```java
   protected void onCreate(Bundle savedInstanceState) {
       // Code to configure the player
       // ...
       // ...

       CreateInterceptor();
       SetSource();
   }

   protected void SetSource(){
       // bad url to test if the network response interceptor works
       String url =  "https://cdn.theoplayer.com/video/elephants-dream/playlist2.m3u8";

       TypedSource typedSource = TypedSource.Builder
               .typedSource()
               .src(url)
               .type(SourceType.HLS)
               .build();

       SourceDescription sourceDescription = SourceDescription.Builder
               .sourceDescription(typedSource)
               .build();

       theoPlayer.setSource(sourceDescription);
       theoPlayer.play();

   }

   protected void HandleNetworkError(String message){
       //Do something with the network error
       Log.i("THEO", "Network error: " + message);
   }

   protected void CreateInterceptor(){
       viewBinding.theoPlayerView.evaluateJavaScript("createHttpErrorInterceptor();", null);
   }

   protected void DestroyInterceptor(){
       viewBinding.theoPlayerView.evaluateJavaScript("destroyHttpErrorInterceptor();", null);
   }
   ```

## iOS

On iOS, there are platform-specific constraints that prevent us from giving you the control over network call like you can on Web. Therefore, we expose an event type for this on the network object. You can set up a listener as follows

```swift
self.player.network.addEventListener(type: NetworkEventTypes.ERROR) { (everror) in
    // handle the event
}
```

---

# What is the support for Wowza

Wowza and THEOplayer are partners in the streaming industry. When developers use both products,

* Wowza Streaming Cloud and Engine are used as the back-end to manage live streams.
* THEOplayer is used on the client-side to playout the live streams.

In this set-up, THEOplayer can play out the streams hosted by Wowza.

## Related Articles

* [Wowza Streaming Engine SecureToken version 2 on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/integrations/wowza-streaming-engine/secure-token.md)
* [Deliver Low-Latency HLS live streams with Wowza Streaming Engine on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/integrations/wowza-streaming-engine/low-latency-hls.md)

## Demo application

There is an open-source reference application at <https://github.com/THEOplayer/samples-html5-sdk/tree/master/reference-apps/wowza>. The purpose of this application is to enhance offline-to-online-to-offline transition.

## Resources

Cross-product documentation resources:

* <https://www.wowza.com/blog/wowza-streaming-cloud-getting-started>
* <https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine>
* <https://www.theoplayer.com/blog/theoplayer-joins-wowza-media-systems-technology-alliance-partner-program>

---

# How to use the CDN fallback/backup stream feature

THEOplayer offers a feature to detect more sources of content in manifest or playlist, so that the player can automatically switch to a fallback URL, in case any of the main content source is unavailable or not reachable. This feature works for both MPEG-DASH and HLS streams out of the box, and does not require any additional configuration to the player.

## For MPEG-DASH Streams

MPEG-DASH allows you to define multiple `<BaseURL>` elements, which points towards the root source of the content. By default, the player starts playing using the first BaseURL but if it is no longer available or not reachable, player automatically tries to use second url available. The `<BaseURL>` can be added at different layers, it is recommended to provide it on the `<MPD>` or `<Period>` level like an example below:

```xml
<?xml version="1.0"?>
<MPD type="static" ...>
	<BaseURL>https://example.com/path/to/your/content/cdn1</BaseURL>
	<BaseURL>https://example.com/path/to/your/content/cdn2</BaseURL>
	<BaseURL>https://example.com/path/to/your/content/cdn3</BaseURL>
	<Period>...</Period>
</MPD>
```

## For HLS Streams

As per HLS Specification for Apple Devices, playback on stream failover for a rendition is supported, if a redundant variant stream with a different URI is available in the manifest. A variant stream is considered to be redundant, if it has the exact same EXT-X-STREAM-INF tag as the original one. In case the first occurrence of the variant stream is unavailable or not reachable, player by default would use the redundant variant stream for continuing playback. An example of the manifest is like below:

```text
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-STREAM-INF:BANDWIDTH=2689440,CODECS="avc1.100.31,mp4a.40.2",RESOLUTION=1120x700
../../687317/6059a27e_1_2728/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=2689440,CODECS="avc1.100.31,mp4a.40.2",RESOLUTION=1120x700
../../687317-b/6059a27e_1_2728/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1808481,CODECS="avc1.77.40,mp4a.40.2",RESOLUTION=768x480
../../687317/6059a27e_1_1728/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1808481,CODECS="avc1.77.40,mp4a.40.2",RESOLUTION=768x480
../../687317-b/6059a27e_1_1728/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1225508,CODECS="avc1.77.32,mp4a.40.2",RESOLUTION=576x360
../../687317/6059a27e_1_1152/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1225508,CODECS="avc1.77.32,mp4a.40.2",RESOLUTION=576x360
../../687317-b/6059a27e_1_1152/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=712202,CODECS="avc1.66.30,mp4a.40.2",RESOLUTION=460x288
../../687317/6059a27e_1_640/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=712202,CODECS="avc1.66.30,mp4a.40.2",RESOLUTION=460x288
../../687317-b/6059a27e_1_640/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=560232,CODECS="avc1.66.30,mp4a.40.2",RESOLUTION=288x180
../../687317/6059a27e_1_448/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=560232,CODECS="avc1.66.30,mp4a.40.2",RESOLUTION=288x180
../../687317-b/6059a27e_1_448/chunklist.m3u8
```

## Resources

* [Apple Variant Stream Documentation](https://developer.apple.com/documentation/http_live_streaming/example_playlists_for_http_live_streaming/creating_a_master_playlist)
* [MPEG-DASH Base URL Documentation](https://dashif.org/docs/DASH-IF-IOP-v4.3.pdf)

---

# How to apply accurate buffering strategy

By default, THEOplayer buffers 20 seconds of video including audio/subtitles in order to guarantee smooth playout. THEOplayer (alike other Web players) is relying on [HTML SourceBuffer API](https://developer.mozilla.org/en-US/docs/Web/API/SourceBuffer) for buffering purposes. Unfortunately there is no method which informs you how big the buffer size of given browser/device is. Of course, it can be different for device, and even browser. In consequence in edge circumstances might happen that the following error is encountered: `Player error: Failed to execute 'appendBuffer' on 'SourceBuffer': The SourceBuffer is full, and cannot free space to append additional buffers.`

## Proactive strategy

One of the approach to deal with above issue is to apply proactive strategy which adjust `player.abr.targetBuffer` depending on what quality is currently used. The below table presents what approximately bandwidth is required for video streaming:

| Resolutions     | Required Bandwidth (H264) | Required Bandwidth (H265) |
| --------------- | ------------------------- | ------------------------- |
| 1280x720 (HD)   | 3Mbps                     | 1.5Mbps                   |
| 1920x1080 (FHD) | 6Mbps                     | 3Mbps                     |
| 3840x2160 (UHD) | 25Mbps                    | 12Mbps                    |
| 4096x2160 (4K)  | 32Mbps                    | 15Mbps                    |

Taking above table into account, the logic responsible for the proactive strategy can look like:

```javascript
player.addEventListener('representationchange', function (event) {
  // specifies how big bandwidth is required for the current quality
  var representationBandwidth = event.representation.bandwidth;
  // player.abr.targetBuffer is 20 by default
  var targetBuffer = player.abr.targetBuffer;

  // SD
  if (representationBandwidth < 3000000) {
    targetBuffer = 20;
  } else if (representationBandwidth > 3000000 && representationBandwidth < 6000000) {
    // HD
    targetBuffer = 10;
  } else if (representationBandwidth > 6000000) {
    //FHD, UHD, 4K
    targetBuffer = 5;
  }

  player.abr.targetBuffer = targetBuffer;
  console.log('representationchange - updated player.abr.targetBuffer: ' + player.abr.targetBuffer);
});
```

Please note that the above numbers should be adjusted depending on the video content used.

## Resources

* [Bandwidth Required For HD FHD 4K Video Streaming](https://www.synopi.com/bandwidth-required-for-hd-fhd-4k-video/)

---

# How can I distribute 4K content?

The ability to play 4k mostly depends on hardware. While the video player is responsible for passing on the data to the decoders, limitations to 4K playback often stem from the device, hardware, operating system or platform (e.g. Chrome, iOS app, Android TV app, ...). When either of these is unable to handle 4K content, you might be out of luck. It's important to ensure all of these boxes are checked.

*Why?* Streams above 1080p, like 4K (i.e. 2160p) and 8K, are usually packaged through codecs like HEVC (H.265), VP9 and AV1. Your device, hardware, operating system or platform might not be able to decode the selected codec. For example, Chrome lacks support for decoding HEVC. It's also possible that your platform doesn't support a specific codec profile or feature (e.g. HDR through Dolby Vision at 60fps) of a selected codec. While technically you can also do 4K streaming with AVC (H.264), it is often too inefficient from a bandwidth perspective. We will leave this out of scope for the remainder of the document.

## Common issues when playing 4K content

Let's zoom in on our previous statement:

> Limitations to playback of 4K often stem from the device, hardware, operating system or platform.

One of these individual components could be disrupting support for 4K streaming.

* Device ─ Your device might not have the capabilities to render the codec which represents your stream, or you might be using a model which doesn't support the selected codec. For example, Chromecast devices from Generation 1, 2, 3 and 4 only support H.264 and VP8 up until 1080p, and don't offer any support for 4K. However, the [Chromecast Ultra](https://developers.google.com/cast/docs/media#video_codecs) does offer 4K streaming through HEVC and VP9 including HDR at 60fps.
* Hardware ─ You might be connecting a device to a monitor incapable of rendering 4K, or you might be using a cable which cannot transfer your stream at the required rate. The leveraged hardware will usually downscale your video or even provide no feed at all.
* Operating System & Environment ─ Your operating system might not offer decoding support for a specific codec. For example, Apple didn't add support for 4K to iPhones until iOS 11 through HEVC. Chrome still doesn't support HEVC across any platform (except for on the iOS platform), and you have to use VP9 or AV1 to decode a 4K stream when using the browser.
* Platform ─ Your platform might not offer decoding support for a specific codec. For example, Android offers decoding support for 4K through HEVC through Android applications, but not through Android browsers like Chrome.

## 4K supported platforms

It's tough to provide a global view on platforms which support 4K streaming. In theory, you would have to maintain an overview of all supported codecs (and codec profiles and features) per version per model per platform. You could then consult this overview to check if your selected codec (and profiles/features) are supported on your targeted platforms. This overview would be challenging to maintain, because updates to platforms change the support for certain codecs, and new models of a specific platform could offer different support for a specific codec. For example, while the Chromecast Generation 4 offers no support for 4K through HEVC, Chromecast Ultra does.

Please consider the table below as a generic snapshot in time. The platforms below can handle 4K streaming, but only if the appropriate codecs, platform versions and device (models) are used. It's perfectly possible that you're not able to get your 4K stream to run on one of the platforms listed below, for example because you're using an unsupported codec.

| Platform                                                                                        | Notes                                                                                                   | THEOplayer SDK          |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------- |
| Browser                                                                                         | Depends on the device, browser and codec                                                                | Web SDK                 |
| [iOS](https://www.apple.com/iphone/)                                                            | Depends on the device and codec, but could support:<br />HDR10, Dolby Vision, HEVC                      | iOS/tvOS SDK            |
| [iPadOS](https://www.apple.com/ipad-pro/specs/)                                                 | Depends on the device and codec, but could support:<br />HDR10, Dolby Vision, HEVC                      | iOS/tvOS SDK            |
| [Apple TV](https://www.apple.com/lae/apple-tv-4k/specs/)                                        | Depends on the device and codec, but could support:<br />HDR10, Dolby Vision, HEVC SDR with 60fps, HEVC | iOS/tvOS SDK            |
| [Android](https://developer.android.com/guide/topics/media/media-formats)                       | Depends on the device and codec                                                                         | Android/Fire TV SDK     |
| [Android TV](https://developer.android.com/guide/topics/media/media-formats)                    | Depends on the device and codec                                                                         | Android/Fire TV SDK     |
| [AirPlay](https://www.apple.com/airplay/)                                                       | Depends on the device and codec                                                                         | Web SDK, iOS SDK        |
| [AirPlay 2](https://www.apple.com/lae/ios/home/accessories/#section-tv)                         | Depends on the device and codec                                                                         | Web SDK, iOS SDK        |
| [Chromecast Receiver](https://developers.google.com/cast/docs/media)                            | Depends on the device and codec, but could support:<br />HDR10, Dolby Vision, HEVC, VP9, 60fps          | Web SDK, Chromecast SDK |
| [Chromecast TV](https://www.google.com/chromecast/built-in/tv/)                                 | Depends on the device and codec.                                                                        | Web SDK, Chromecast SDK |
| [Fire TV](https://developer.amazon.com/docs/fire-tv/device-specifications.html)                 | Depends on the device and codec, but could support:<br />HDR10, Dolby Vision, HEVC, VP9, AV1, 60fps     | Android/Fire TV SDK     |
| [Roku](https://developer.roku.com/en-gb/docs/specs/streaming.md)                                | Depends on the device and codec, but could support:<br />HDR10, Dolby Vision, HEVC, VP9, 60fps          | Roku SDK                |
| [Tizen](https://developer.samsung.com/smarttv/develop/specifications/media-specifications.html) | Depends on the device and codec, but could support:<br />HEVC, VP9, AV1, 60fps, 8K                      | Web SDK                 |
| [webOS](https://webostv.developer.lge.com/develop/specifications/video-audio-230)               | Depends on the device and codec, but could support:<br />HEVC, AV1, 60fps, 8K                           | Web SDK                 |
| [Xbox](https://www.xbox.com/en-US/consoles/xbox-one-x)                                          | Depends on the device and codec                                                                         | Web SDK                 |
| [PlayStation](https://www.playstation.com/en-us/ps5/ps5-entertainment)                          | Depends on the device and codec                                                                         | Web SDK                 |

As this table is in flux, when you decide to implement 4K we encourage you to investigate if anything has changed for the platforms you are targeting (tip: searching for keywords like "Chromecast Media Capabilities 4K" often provides good results) or to reach out to the THEO support team with specific questions.

## Video players and decoding

Video players usually don't do software decoding and instead rely on the native decoding capabilities offered by the selected platform through a native API as player-based decoding would be highly inefficient for power consumption and often requires a lot of computational performance. For example, on Desktop Chrome, video players leverage the [Media Source Extensions API](https://developer.mozilla.org/en-US/docs/Web/API/Media_Source_Extensions_API) to decode the actual H.264 (or VP9 or AV1 or ...) codec representing your stream.

That being said, a video player might still be the one to blame when your viewers aren't seeing the beautiful 4K representation of your stream. Your video player should be able to correctly parse, extract and leverage the 4K stream from your HLS or MPEG-DASH manifest when your 4K representation can be applied. This functionality might not be implemented in your video player.

THEOplayer supports 4K streaming out of the box. For specific devices, specific configuration recommendations can apply in order to achieve 4K streaming efficiently.

---

# What is the collaboration between Azure Media Services and THEOplayer

> **Warning**
>
> Azure Media Services has been retired since June 30th, 2024.

Azure Media Services has a rich ecosystem of partners that provide their customers with the flexibility of choosing the best solution for their needs.

### What is the collaboration about?

Azure Media Services supports all the popular streaming formats including Microsoft Smooth Streaming, MPEG-DASH and HTTP Live Streaming (HLS). Azure Media Services also provides Microsoft Azure Media Player, a cross-platform HTML5 player framework that plays back content streamed from Azure Media Services.

With the collaboration with THEOplayer, customers now have an additional choice of using a proven and integrated fully HTML5-based player that can playback HLS or LL-HLS on all popular platforms without the need for any plug-ins.

### How can I use THEOplayer with AMS?

Azure Media Services has set up a GitHub repository to help get users started. Here, users can insert the streaming URLs they get from the Microsoft Azure Management portal and see them in action. They can also find all the information on getting started with THEOplayer.

* <https://github.com/Azure-Samples/media-services-3rdparty-player-samples/tree/master/docs/THEOplayer>

---

# Is Portrait mode supported

Yes. THEOplayer supports vertical video playback, which is also known as portrait mode.

More specifically, you can configure the aspect ratio of the container which holds the THEOplayer video player instance.

* If your video is shot in 9:16 (i.e. portrait), you can configure your container to respect this aspect ratio, and THEOplayer will fill the container.
* If your video is shot in 16:9 (i.e. landscape), you can configure your container to respect this aspect ratio, and THEOplayer will fill the container.

Of course, you can also configure your container to respect any other aspect ratio, like 5:4, which is employed by Instagram.

## Demo

A demo is available at <https://cdn.theoplayer.com/demos/vertical/index.html>. This demo provides a sample implementation which allow you to switch between popular viewing modes. This demo is best viewed on a mobile browser.

![Screenshot of Portrait Mode](/pr-932/assets/images/screenshot_portrait_mode-0633aae3f80f661cad0ea0595a439820.png)

---

# How to prevent screen recording

This article explains what screen recording is, and how to counter it.

## What is screen recording

We define "screen recording" (also known as "screen capturing") as the malpractice of illegally recording video streams on a website or application of a content provider.

* These screen recordings may be redistributed on platforms which are not owned by the content provider.
* This unconsented redistribution may impact the business of the content provider.

Screen recordings - and redistribution of screen recordings - is considered a major, (arguably) unsolved issue in the video industry. All content providers - including Netflix, Disney+ and Hulu - struggle to counter screen recordings. Most popular providers employ strategies to counter screen recordings, or to reduce the impact of screen recordings.

Creating a screen recording doesn't have to be difficult.

* The camera of a smartphone can be aimed at a screen. Your screen wouldn't know that a smartphone is recording it.
* The record function of Apple's QuickTime Player (or Window's Xbox Game Bar) can be used to record video content playing on Chrome on Windows, macOS and Linux. Chrome on Windows, macOS and Linux doesn't offer a native mechanism to prevent screen recording, even when DRM protects the content.

The quality (and bitrate) of a video stream degrades through a screen recording, which is a useful property when the recording leaks.

Details

Screen recording versus downloading

We do not define "screen recording" as the malpractice of illegally downloading and/or decrypting the original video streams on the website or application of a content provider.

* For example, if a pirate (i.e. a user with the intention to steal and/or illegally redistribute content) downloads the source files of an HLS stream (and perhaps removes the encryption), then they are not doing "screen recording".
* On the other hand, if a "pirate" uses QuickTime Player to record their screen (which is playing a video in Chrome), then they are doing "screen recording".

## How to counter screen recording

There are strategies to prevent screen recordings, and strategies to cope with screen recordings.

* A preventive strategy involves making it more challenging to create screen recordings. (e.g. DRM, plug-ins)
* A coping strategy involves responding to unprevented screen recordings. (e.g. watermarking, limited quality)

You want to consider both strategies as a content provider.

### Strategies to prevent screen recording

Strategies such as [using DRM](#drm) and [restricting the allowed platforms](#restrict-allowed-platforms) make it more challenging to create a screen recording.

However, never assume that you can make screen recording impossible, as "content pirates" will keep identifying and using workarounds. For example, a common workaround is "Digital-to-Analog", where a smartphone camera could record a screen. Alternatively, dedicated hardware may also be able to screen recording, such as an HDMI recorder which does follow HDCP, but uses leaked certificates to record the output regardless.

#### DRM

Using an appropriate multi-DRM set-up prevents screen recording. Many devices and platforms allow you to configure FairPlay, PlayReady and Widevine in such a way that the device and platform automatically prevents screen recording tools. These configurations rely on the availability on support for hardware DRM.

Reach out to your multi-DRM provider to understand which options they offer to prevent screen recordings, and how these options affect your targeted platforms.

The following statements are generally true for multi-DRM:

* You can prevent screen recordings on platforms which support hardware DRM. The list below represents a set of popular platforms which support hardware DRM:

  * Windows Edge
  * macOS Safari
  * iOS and iPadOS, both for apps and browsers
  * Android, but only for apps
  * Chromecast

* You cannot prevent screen recordings on platforms which do not support hardware DRM. The list below represents a set of popular platforms which do not support hardware DRM:
  * Chrome browsers (neither Windows nor Apple), because this platform only supports Widevine L3 (and not Widevine L1)

#### Restrict allowed platforms

The previous section establishes that you can prevent screen recordings on many platforms, but not all platforms. As a content provider, you could decide to only distribute your content on the set of platforms which allow for the prevention of screen recording through multi-DRM.

In this strategy, you could be forcing users to use another platform than their preferred choice. For example, disallowing your viewers to use Chrome, means that about 50% of your browser viewers need to switch to another browser.

#### Conclusion on the prevention of screen recording

There are other strategies beyond only allowing your users to watch content on platforms where DRM prevents screen recording.

* For Desktop users, you could try to force your viewers to install a desktop app which prevents screen recording. For example, you could offer a HTML5 Electron app which utilizes the [`setContentProtection`](https://www.electronjs.org/docs/api/browser-window#winsetcontentprotectionenable-macos-windows) method to prevent screen recording.

* You could try to use technology which prevents screen recording through third-party plugins.

  * This approach (usually) requires the viewer to install an additional piece of software.
  * For example, the viewer may have to install a Chrome extension which monitors computer services, and prevent video playback.

* You could try to use technology which renders the video in such a way that screen recording programs cannot properly capture the video.

The arguably primary industry problem w\.r.t. screen recording is the prevention of screen recording on Chrome for Windows and Apple machines, due to the sheer popularity of this platform. Should Windows and Apple add support for Widevine L1, then screen recording becomes more challenging on Chrome. This change would grant a large coverage of protection on the browser market through multi-DRM.

That being said, platform developers are engaging in efforts to make hardware DRM available on an increasing amount of platforms.

### Strategies to cope with screen recording

When you are not able to prevent screen recording, you can employ strategies to cope with it. For example, you can use [watermarking](#watermarking), or only [allow a limited stream quality](#restrict-qualities) on platforms which cannot prevent screen recording.

#### Watermarking

A forensic or digital watermark allows you to embed an identifier in a video stream. You can trace the identifier of a leaked screen recording. This tracking allows you to take punitive actions towards users who created the screen recording.

A forensic watermark should be imperceptible and robust.

* It should not be possible to visually recognize the watermark.
* It should not be possible to remove the watermark.

#### Restrict qualities

You can restrict the available video stream quality to users. For example, if your viewer is accessing the video stream on a platform which doesn't prevent screen recording through DRM, you don't allow them to access any quality above 720p. (*This is a popular strategy among top content providers, including Netflix and Disney+.*)

A low-quality, leaked recording (which is even further degraded through the recording process) may reduce its appeal.

#### Conclusion on coping with screen recordings

Watermarking and restricting the quality allow you to react to leaks, and to further reduce its impact.

You may also consider different strategies to reduce the impact of screen recordings. For example, an AVOD business model would arguably suffer less from this, because viewers can access your content for free, but you would monetize it through advertisements.

## Video players and screen recording

The influence of a video player on the prevention of screen recording is mainly through its support for DRM. Meaning, a video player can "indirectly" support the prevention of screen recording, if the video player is running on a website or app where screen recording is not allowed by the platform due to the employed DRM strategy.

For example,

* a video player prevents the screen recording of HLS streams protected with FairPlay on macOS, because the macOS platform prevents this for FairPlay on Safari.
* a video player does not prevent the screen recording of MPEG-DASH streams protected with Widevine on macOS, because the macOS platform doesn't prevent this for Chrome.

The technological limitations of a platform are also the technological limitations of a video player. The strategies discussed in this article are used in combination with a video player, but they are not the responsibility of a video player. For these strategies to work, the implementation and configuration of additional components (e.g. multi-DRM, watermarking, third-party plugin) is mandatory. These components are not offered by a single video player SDK out-of-the-box. This means that you have to combine a video player which external components.

### THEOplayer and screen recording

The previous section explains that video players indirectly prevent screen recordings when using the appropriate multi-DRM set-up. This statement is also true for THEOplayer.

Additionally, THEOplayer is partnered with vendors which offer multi-DRM and watermarking. These partners are listed at <https://www.theoplayer.com/partners>.

## Conclusion

You should tailor your strategy to your needs. Four valid strategies are listed below.

1. Do prevention through DRM, and coping through watermarking and restricting the qualities. On platforms which do not prevent screen recording through DRM, you limit your video quality (e.g. 720p). If a screen recording leaks, you have reduced the impact. Additionally, through the watermark, you can identify the source of the leak. This strategy might frustrate viewers, because they might not be able to view the best quality on their preferred platform. (*This approach is used by popular streaming services, including Netflix.*)

2. Do prevention through DRM and restricting the allowed platforms, and coping through watermarking. You don't allow viewers to watch your content on platforms which do not prevent the screen recording of DRM-protected streams. You identify the source of leaks through watermarks. This strategy might frustrate viewers, because they might not be able to view the stream on their preferred platform.

3. Do prevention through DRM and plugins, and coping through watermarking. You force viewers to install a plugin to view the stream on a platform which don't prevent the screen recording of DRM-protected streams. You identify the source of leaks through watermarks. This strategy might frustrate viewers, because they need to install a plugin to view the stream on their preferred platform.

4. Do coping through watermarking. This strategy doesn't prevent screen recording, but doesn't frustrate viewers. You identify the source of leaks through watermarks.

---

# The provided video source is incompatible with the license for this player

The player throws this error when the source of the player is incompatible with the license. This occurs when the domain of the source is not in the list of source domains of the license. For example, when you have **yourfirstcdn.com** and **yoursecondcdn.com** as source domains, but you use a video stream (i.e. source) from **<https://yourthirdcdn.com/video.m3u8>**, then the player will throw the above error because **yourthirdcdn.com** is not included in the source domains (**yourfirstcdn.com** and **yoursecondcdn.com**).

To resolve this issue you can do the following:

* Use another source which is compatible with your SDK.
* Verify the source domains of your SDK on the [Developer Portal](https://portal.theoplayer.com).
* Change the source domains of your SDK to whitelist all domains.

Additionally, you could see this error on an edge case where you are setting a `source` object with an empty `source` URL but with any other valid URL, such as a `poster`. In this case, since the source object passes a valid URL, the license check would be triggered and the empty array would cause to return this error. To work around this, you could consider setting both the `source` and any other URL contained at the same time or if possible, setting the other URLs outside the source object to avoid license check with an empty source.

---

# Page and Source domains

Page and Source domains prevent unauthorized users from embedding your SDK on their website. We highly recommend configuring both Page and Source domains carefully to protect your THEOplayer license.

## Page domains

Page domains (available only on Web SDK, React Native SDK and Flutter SDK) specify on which domains the player can be loaded.

Imagine your website has the following domain: `example.com`, you have configured your Page domains and the THEOplayer SDK is installed on your website. When a malicious user copies your SDK and installs it on their domain, `other.com`, the player will throw an error that the license is invalid.

Whitelisting `example.com` will also whitelist all its subdomains such as `a.example.com` or `a.b.example.com` so you don't have to enter each of them one by one. Please note that whitelisting `*.example.com` *will not* whitelist the subdomains.

Your page domains are included on your player [license](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/license/introduction.md). If you make any changes on your page domain configuration, you should update the license on your website.

## Source domains

Source domains specify from which domains the player is allowed to play streams. When the Source domains are configured to `example.com` the player will only play streams from this domain. If the player attempts to play a stream from `other.com`, it will result in an error stating that the license is invalid.

Similar to Page domains, whitelisting `example.com` will also whitelist all its subdomains such as `a.example.com` or `a.b.example.com` so you don't have to enter each of them one by one. Please note that whitelisting `*.example.com` *will not* whitelist the subdomains.

Your source domains are included on your player [license](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/license/introduction.md). If you make any changes on your source domain configuration, you should update the license on your application/website.

## How to configure Page and Source domains

Page and Source domains can be configured in the [Developer Portal](https://portal.theoplayer.com) when creating a license or a custom SDK. On an existing license/SDK, you can find the Page and Source domains under the “Configure” section of the SDK overview page. The “Allow all” option can be selected when you are not certain on which domains the player will be loaded or from which domains the player will play streams. This option is separately configurable for both Page and Source domains.

---

# What does the error message “Something went wrong determining the initial period of the provided MPEG-DASH stream” mean

This error, "Something went wrong determining the initial period of the provided MPEG-DASH stream", occurs whenever the player struggles to play a DASH stream due to problems determining the availability of the segments for that stream. The recommended solution for this is to make sure that the segments result available, based on the data provided in the manifest, at the time at which the manifest is requested.

## Long Answer

A number of fixes and improvements we made available in several releases throughout 2020 brought THEOplayer to apply the DASH specification regarding segments availability more strictly than in previous versions. In other words, the player now requires, for successful playback, that the manifest indicates correctly the availability of segments. This is especially relevant for dynamic Media Presentations (MPD\@type="dynamic").

**How to check whether your segments are available at the right time** For the segments to be correctly played, they must be available at the time when the manifest is requested/served. In other words,

*“start of segment availability” < “manifest is requested/served” < “end of segment availability”*

How is the segment availability time calculated? The DASH specification indicates that:

> For services with MPD\@type='dynamic', the Segment availability start time of a Media Segment is the sum of
>
> * the value of the MPD\@availabilityStartTime,
> * the PeriodStart time of the containing Period as defined in 5.3.2.1,
> * the MPD start time of the Media Segment, and
> * the MPD duration of the Media Segment.
>
> \[…] The Segment availability end time of a Media Segment is the sum of the Segment availability start time, the MPD duration of the Media Segment and the value of the attribute @timeShiftBufferDepth for this Representation.
>
> If the @availabilityTimeOffset attribute is present for a Representation, then the adjusted segment availability start time is determined by subtracting the value of @availabilityTimeOffset from the Segment availability start time. This adjusted segment availability start time provides a time instant in wall-clock time at which a Segment becomes an available Segment. Note that if the @availabilityTimeComplete flag is set to true for such a Representation, then the entire Segment may not yet be available at the adjusted segment availability start time.

---

# Why is my PlayReady stream not working in Chromium Edge?

If you are having problems playing PlayReady streams in Chromium Edge, this may be due to a conflict between player and browser, regarding the DRM system to use. If this is the case, you may solve the issue indicating PlayReady as your first option with the [*preferredKeySystems* property](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/DRMConfiguration#preferredkeysystems).

## Long Answer

Chromium Edge supports both PlayReady and Widevine DRM systems and by default both flags are active (<edge://flags/>) - see *Related issues* for exceptions.

In 2.78, we fixed an issue that was preventing specific streams to play in Edge Chromium with PlayReady (in certain cases) and with Widevine (in other cases) when both flags were enabled on the browser. In recent versions of the player, we also added the property *preferredKeySystems* (documentation linked above), which helps the player choose the preferred DRM system.

We noticed that, due to their default settings, a conflict arises (regarding which DRM system is to be given priority) between the player and the browser. This may lead to playback failure for certain PlayReady streams. This is solved directly on the implementer’s side by using the following values order for the *preferredKeySystems* property.

```js
preferredKeySystems: ['playready', 'widevine', 'fairplay'];
```

Please note that this will not hinder playback in case also/only Widevine is present, nor on other browsers.

### Related issues

In the same use cases, playback may also fail on the user’s side due to other causes, independent of the player, for example:

* the flag for the DRM system used in the current DRM configuration in the *player.source* is disabled
* the machine/platform/browser version does not provide full support for a certain DRM system. For example, you can check the following link for PlayReady: <https://testweb.playready.microsoft.com/Tool/Hwdrm>
* other issues related to the stream, DRM system or server

---

# Which subtitle and CC formats are supported on native Safari

The Safari browser on iOS uses the native Safari video player. Safari on the desktop also uses its native player when using FairPlay or when the `useNativePlayback` flag is enabled.

### WebVTT

For displaying webvtt subtitles, Safari on iOS requires the `SUBTITLES` attribute in the `EXT-X-STREAM-INF` tag of the m3u8 file. This `SUBTITLES` attribute is optional on browsers such as Chrome and Firefox and when Safari does not use its native video player.

### TTML

TTML subtitles aren't supported through native Safari. However, THEOplayer should be able to handle TTML subtitles on desktop Safari as long as FairPlay is not being used and the `useNativePlayback` flag is not enabled.

### CEA608 and CEA708

CEA608 and CEA708 subtitles are supported.

## Known Limitation

When multiple subtitles with mode `hidden` are configured, only one will fire its events such as `addcue` and `cuechange` when using Safari's native player.

## Resources

The following resources provide more information:

* [HLS Specification - #EXT-X-STREAM-INF](https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.4.2)
* [THEOplayer introduction to subtitles and closed captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/subtitles-and-closed-captions/introduction.md)
* [THEOplayer introduction texttracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/introduction.md)

---

# How to navigate through the documentation and resources

THEOplayer offers documentation and resources through a number of channels.

* The central THEO documentation at <https://docs.theoplayer.com> contains

  * Getting started guides that help you set up a THEOplayer SDK or framework (e.g. [Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md), [React Native](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/getting-started.md), ...)
  * How-to guides articles that cover specific topics (e.g. [how to do ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/introduction.md), [how to do DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/drm/introduction.md), [how to detect the active video quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/media-tracks/detect-video-track-qualities.md), ...)
  * FAQ articles that address specific questions (e.g. [what is an impression](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/what-is-an-impression.md), [is portrait mode supported](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/is-portrait-mode-supported.md), ...)
  * Knowledge base articles that explain media streaming concepts or related topics (e.g. [AES-128](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/content-protection/aes-128-encryption.md), [CORS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/cors/introduction.md), ...)
  * [Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md) that lists the release notes of our SDKs
  * API references that document APIs per SDK (e.g. [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web), [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android))

* Our GitHub at <https://github.com/THEOplayer> contains

  * Samples for all SDKs (e.g. [Basic playback in Android](https://github.com/THEOplayer/samples-android-sdk/tree/master/Basic-Playback), [Google IMA in iOS](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Google-IMA), ...)
  * Sample connectors to integration analytics (e.g. [Conviva](https://github.com/THEOplayer/sample-conviva-analytics-html5-sdk)) and [DRM connectors](https://github.com/THEOplayer/samples-drm-integration)
  * Sample integrations for development frameworks (e.g. [Next.js with TypeScript and NPM](https://github.com/THEOplayer/samples-nextjs/tree/master/typescript-npm))

* Web demos at <https://www.theoplayer.com/demo-zone>

* White papers, webinars, blog posts and more at <https://optiview.dolby.com/resources/blog/>

Customers manage their THEOplayer SDKs through the THEOplayer Developer Portal at <https://portal.theoplayer.com>. You can also use this portal to view your impressions or to acquire (or manage) a support plan.

A support plan gives you access to our Jira Service Desk at <https://servicedesk.theoplayer.com/>. Refer to "[How to create a (great) ticket](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-create-a-ticket.md)" for more information on creating tickets through our Service Desk.

---

# How to create a (great) ticket

Customers can create tickets through our Jira Service Desk at <https://servicedesk.theoplayer.com>. You can obtain a Service Desk account by purchasing a [support plan](https://www.theoplayer.com/supportplans) through <https://portal.theoplayer.com>, or by [contacting our Sales team](https://www.theoplayer.com/pricing).

## Creating a ticket

You use our Jira Service Desk to create tickets and collaborate with our team.

When you go to <https://servicedesk.theoplayer.com>, you'll be asked to enter your credentials. Afterwards, you must locate the *"Need to raise a request? Contact us."*-button, and click it. This action will take you to <https://opentelly.atlassian.net/servicedesk/customer/portal/1/group/1/create/150>, as illustrated by the screenshot below.

![THEOplayer Jira Service Desk](/pr-932/assets/images/jira-service-desk-92889fe2bf14999ebf74156adee051f1.png)

Enter a clear summary, select the appropriate request type, and enter a valuable description.

* Select "Information" as the request type when you're not sure how to implement a specific feature, or when you're not sure whether something is a bug or a feature request.
* Select "Bug" if you think your issue is due to a bug introduced by THEOplayer.
* Select "Feature" if you want to request a change or feature.
* Select "Renewals/Licensing" if you have license issues, or questions about your license.

### Creating a great ticket

A great ticket makes your life - and our life - easier. The collaboration will go smoother, and your tickets will be resolved faster.

A great ticket is **C.R.U.S.P.** (= Collaborative, Reproducible, Use Case, Specific, Proven).

**Collaborative** | Be a team player.

* Include resources that help us understand your ticket. (For example, when documenting a difficult to reproduce bug, attach a [Loom](https://www.loom.com/) video.) Things that are obvious to you, might not be obvious to us.
* Refer to other tickets when they're related.
* Refer to documentation and samples that you think are related.
* Not sure if "something" it's relevant? Mention it regardless.

**Reproducible** | Provide simple & reliable reproduction steps and resources.

* Don't send us the link to your website. Instead, set up a simple reproduction page on <https://codepen.io> or <https://replit.com>.
* Don't send us your .apk or App Store URL. Don't send us complex code bases. Instead, fork our GitHub reference apps (e.g. [Basic Playback for iOS](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Basic-Playback)), include your code that allows us to reproduce the issue, and forward it to us.
* Don't send us obfuscated, minimized or transformed (e.g. Webpack) code. Use simple code in simple environments.
* Ensure that your streams are reliable. Streams that can expire introduce significant overhead and will slow down the resolution time.
* Issues that you (or we) cannot consistently reproduce introduce significant overhead and may be rejected. Identify and describe consistent reproduction steps.
* Avoid credentials, VPNs or geo-restrictions as they introduce significant overhead. (If it's mandatory: specify this in every ticket. Although we might remember it recall it from your other tickets, don't assume that we remember them. Our team is spread over hundreds of customers and thousands of tickets.)

**Use case** | Provide sufficient context.

* What is the use case you're trying to achieve? *Why* are you interested in using this API or feature?
* Providing context helps our team to tailor their answers, recommendations and alternatives. We want to understand your big picture -- give us chance.

**Specific** | Be as specific and detailed as you can.

* Which SDK are you using? Which version?
* What browser or platform is relevant? Which version?
* What is the current behavior? What is the expected behavior?
* What is the reproduction stream? What are the reproduction steps?

**Proven** | Provide as much self-research as possible.

* What have you done to troubleshoot it yourself?
* What happens if you try the latest version of THEOplayer? (Or an older version of THEO?)
* What happens if you try another player (e.g. Safari, Dash.js, ...)?
* What happens if you try another (third-party) stream?
* What happens if you try to implement it in a different way?
* What happens if you try another version of your platform?
* How do you know that the issue is related to THEOplayer?

## Remarks

* Avoid using emails if you're an existing customer. Emails get lost and people are bottlenecks. (Only use emails to refer to tickets when needed.)
* Refer to our article on ["How to investigate a ticket"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-investigate-a-ticket.md) if you are interested in understanding how process your ticket. (You might also find this article interesting if you want to improve your troubleshooting capabilities!)

---

# How to investigate a ticket

This article describes how our team typically investigates an issue (i.e. bug) reported to us through a Service Desk ticket. We encourage you to go through these steps before creating a ticket, and to document your findings in your ticket.

## Prerequisites

* The ticket is well-described and/or [C.R.U.S.P.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-create-a-ticket.md#creating-a-great-ticket).

* The reported 'Current behavior' can be easily understood.
  * Illustrations, screenshots or screen recordings are provided to further elaborate on the issue.

* The reported 'Expected behavior' can be easily understood.

  * The affected SDK(s) are correctly labeled.
  * (The affected browsers are correctly labelled.)

* A reliable and simple reproduction page, stream or application has been shared.
  * Customer-specific application logic has been stripped when a reproduction page or application has been shared.

## Guide

Investigating an issue typically consists of 4 phases:

1. Reproducing the issue;
2. Checking whether it can be reproduced with the latest version (or other versions) of THEOplayer;
3. Pre-investigating the issue, and narrowing down the scope;
4. Investigating the root cause and determine the next action item.

![THEOplayer Jira Service Desk](/pr-932/assets/images/ticket-4-stages-c1b32aaf31118677b8e12ea0a6f913ec.png)

### Reproduce the issue

The first step is to reproduce the issue. Take the reproduction stream/page/application, and confirm the issue.

* If the issue can be reproduced: continue the investigation.
* If the issue cannot be reproduced: request more information from the reporter.

![THEOplayer Jira Service Desk](/pr-932/assets/images/ticket-reproduce-4f68ae49865e31e6696b3dddb622e3ad.png)

### Check other versions

The second step is to check if the issue can still be reproduced with the latest version (or other versions) of THEOplayer.

* If using a more recent version fixes the issue: deploy the latest version of THEOplayer.
* If an older version addresses the issue: investigate a potential regression.
* If this doesn't fix the issue: continue scoping the issue.

### Narrow the scope

The goal of this step is to narrow down the scope of the issue. After this phase, we want to determine the influence of the following components.

* Affected platforms;

  * Affected browsers;
  * Affected operating systems;
  * Affected SDKs;

* Affected THEOplayer versions;

* Affected video players.

![THEOplayer Jira Service Desk](/pr-932/assets/images/tickets-scope-1be0844416f48492be33a162c15ac16b.png)

#### Scope affected platforms

It's always useful to know which browsers, SDKs and operating systems are affected by the issue.

#### Scope affected THEOplayer versions

Whilst it's critical to share which THEOplayer versions are affected, it's even more useful to identify older (or newer) versions which are unaffected by the issue. If that's the case, THEOplayer can identify a regression, which speeds up the R\&D-process.

Check which older versions are unaffected.

#### Scope affected video players

In case of an AV playback issue (e.g. freezes, errors, ...), comparing with other video players can help in understanding whether there's a server-side issue (e.g. encoding, packaging, CDN) or a client-side video player issue. If all video players suffer from the issue, it's possible that the stream is not optimally encoded, packaged, etc.

Tips for comparing with other video players:

* If it's an HLS stream: Native Safari, AVPlayer, HLS.js, Shaka Player
* If it's an MPEG-DASH stream: DASH.js, ExoPlayer, Shaka Player

### Investigation

The goal of this step is to identify the cause. Let's discuss causes related to the API, Playback, Advertisements, Analytics and DRM.

#### API

Developers implement THEOplayer through a specific API related to a specific feature. Sometimes, an issue is caused by using a set of API-logic which triggers an edge-case. Sometimes, a nice-to-have API might break in a new update, which in turn breaks a must-have feature.

If you can identify which API-statement causes the issue,

* you can evaluate if you can temporarily disable the statement, and potentially identify a workaround,
* and the R\&D-team knows to what the root cause is related.

Below is a list of proposed action items:

1. Use a near-empty THEOplayer page (or application). Don't use autoplay or preload, or poster images, or ...; limit the API to the absolute minimum.
2. Gradually, add new statements, until the issue can be reproduced.
3. Try alternative approaches, values and states.

#### Playback

Playback issues are related to video and audio freezes, start-up failures, and crashes during playback.

1. Double-check the pre-investigation.

2. Extract information from the reporter why the issue is surfacing just now. Often, playback issues are caused by server-side changes.

3. Extract information from the reporter whether every asset is suffering from the issue.

4. Check whether the issue can be reproduced with other streams:

   * HLS: [https://cdn.theoplayer.com/video/star*wars\_episode\_vii-the\_force\_awakens\_official\_comic-con\_2015\_reel*(2015)/index.m3u8](https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_\(2015\)/index.m3u8)
   * MPEG-DASH: <https://amssamples.streaming.mediaservices.windows.net/634cd01c-6822-4630-8444-8dd6279f94c6/CaminandesLlamaDrama4K.ism/manifest(format=mpd-time-csf)>

5. Check if the issue is related to a specific video or audio quality. Manually switch to a specific quality or track, and verify whether the issue can still be reproduced. Often, the issues are caused by glitching quality-changes, or a badly encoded quality.

6. Check what is logged in chrome://media-internals.

7. Check whether there are [CORS-issues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq/how-to-remove-cors-restrictions.md).

8. In-case DRM is used, check whether the issue can also be reproduced if the asset is unprotected.

#### Advertisements

Advertisement set-ups can be quite complex, and the related issues can be quite subtle.

1. Check whether simpler versions of your set-up suffers from the issue:

   * In-case multiple ads are scheduled, check whether single ads suffer from the issue.
   * In-case pre-rolls/mid-rolls are scheduled, check whether the issue is still present if you schedule it as a post-roll/mid-roll instead.
   * In-case multiple ad pods are used inside an ad-break, check whether the issue can be reproduced with single ad pods.
   * In-case a VPAID is scheduled, check whether a VAST works instead.
   * In-case a VMAP is scheduled, check whether an altered VMAP works instead.

2. In-case Google IMA is used, check whether the issue can be reproduced at <https://developers.google.com/interactive-media-ads/docs/sdks/html5/vastinspector>.

3. In-case a SSAI solution is used, check whether other clients also suffer from the issue.

#### Analytics

Issues related to an analytics service usually comes in three shapes:

1. No data is being logged in the analytics service:
   * Check whether the analytics service requires a third-party SDK. If so, check whether this has been included.

2. Data is being logged incorrectly:

   1. Try alternative configurations. When is it working incorrectly?
   2. Identify the maintainer: is it THEOplayer or the analytics vendor?
   3. Find the reference implementation or documentation, and compare with the current implementation.

#### DRM

Sometimes issues are flagged as a DRM issue, whilst they are actually more generic playback issues:

* Check whether the issue can also be reproduced with unprotected streams.

In-case the issue is related to adding DRM:

* Double-check the pre-investigation. It's valuable information if -for example- the issue can be reproduced on Chrome, but not on Firefox, as this could imply that this is a platform-specific decoding issue.
* Check whether the issue is related to Widevine, PlayReady, FairPlay, or all.
* Extract information from the customer whether every DRM-protected asset is suffering from this issue.
* Check whether the issue can be reproduced with reference DRM streams. (e.g. <https://demo.theoplayer.com/drm-aes-protection-128-encryption>)

## Remarks

* The following resources might assist in your debugging efforts:

  * <https://optiview.dolby.com/resources/demos/test-stream/>: logs a number of events and states.
  * <https://www.chromium.org/audio-video/media-internals>: chrome://media-internals can help with identifying A/V decoding issues.
  * [ffprobe](https://ffmpeg.org/ffprobe.html) can help with analyzing streams and segments.
  * [MP4Box.js](https://gpac.github.io/mp4box.js/test/filereader.html) can help with analyzing MP4 files.
  * Apple's [HLS Tools](https://developer.apple.com/documentation/http_live_streaming/about_apple_s_http_live_streaming_tools) can help (e.g. Media Stream Validator).

---

# What are the limitations of AirPlay

When casting through [AirPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/casting/airplay.md) your viewer is relying on the native Apple video player. This setup gives rise to a number of limitations, as a third-party video player (i.e. THEOplayer) cannot circumvent the limitations of this native Apple video player.

Some of these limitations include, but are not limited to, the following:

* AirPlay does not support client-side ad-insertion. Instead, you could consider using server-side ad-insertion, or disabling client-side ad-insertion when allowing AirPlay.
* AirPlay does not support VR/360 videos. Instead, you should disable AirPlay for VR/360 videos.
* AirPlay does not support MPEG-DASH. Instead, you should use HLS if you want to allow AirPlay.
* AirPlay does not support UI customization. Instead, you could implement a [tvOS application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/tvos/getting-started) to offer a custom playback experience on an Apple TV.
* AirPlay does not support some closed captions and subtitle formats, including CEA-608 and [sideloaded (WebVTT) subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/insert-subtitles.md). Instead, you must use subtitles that are supported natively.
* AirPlay does not support manual quality switches. Instead, viewers can only rely on automatic quality selection.
* AirPlay may not have proper support for LL-HLS. The delay might be greater than you expect, and stuttering may occur.
* AirPlay does not support authentication cookies. AirPlay streams run on a device other than the device initiating the session. This means authentication cookies will not be available to retrieve playlists, encryption keys, ... There is also no way to intercept these requests from the initiating device (other than DRM license requests).

> **Does native Safari support it?**
>
> When you want to know whether the native AirPlay video player supports a certain feature, you can compare the experience with the native Safari video player.
>
> For example, if you want to know whether MPEG-DASH is supported, you can enter your MPEG-DASH URL in the address bar of Safari, hit enter, and observe the results. The same results are most likely true for the native AirPlay video player.

---

# How to use the Media Session API

Developers who implement the Media Session API give viewers the option to control and monitor media playback outside their web page. The first screenshot below demonstrates how a viewer can play/resume/seek a video through their iOS home screen, and the second screenshot below demonstrates the same level of control on a macOS.

![Media Session API iOS](/pr-932/assets/images/media-session-api-ios-e60ae898100d1ece8714233b635a35e3.png)

![Media Session API macOS](/pr-932/assets/images/media-session-api-macos-b7572ea6aaf490644bcc1e8dfa1c97ef.png)

The Media Session API is available on most modern desktop and mobile browsers as documented at <https://developer.mozilla.org/en-US/docs/Web/API/Media_Session_API>. The W3C working draft of the Media Session standard is available at <https://www.w3.org/TR/mediasession/>.

# How to implement the Media Session API in THEOplayer

We recommend developers to implement the Media Session API on top of the THEOplayer API in order to ensure the deepest level of control. A simple example is available below:

First, define the metadata for your MediaSession: [see documentation here](https://developer.mozilla.org/en-US/docs/Web/API/MediaSession/metadata).

```javascript
const mediaSessionMetadata = {
  title: 'Sintel',
  artist: 'Blender',
  album: 'Movie',
  artwork: [
    {
      src: 'https://storage.googleapis.com/media-session/sintel/artwork-96.png',
      sizes: '96x96',
      type: 'image/png',
    },
    {
      src: 'https://storage.googleapis.com/media-session/sintel/artwork-128.png',
      sizes: '128x128',
      type: 'image/png',
    },
    {
      src: 'https://storage.googleapis.com/media-session/sintel/artwork-192.png',
      sizes: '192x192',
      type: 'image/png',
    },
    {
      src: 'https://storage.googleapis.com/media-session/sintel/artwork-256.png',
      sizes: '256x256',
      type: 'image/png',
    },
    {
      src: 'https://storage.googleapis.com/media-session/sintel/artwork-384.png',
      sizes: '384x384',
      type: 'image/png',
    },
    {
      src: 'https://storage.googleapis.com/media-session/sintel/artwork-512.png',
      sizes: '512x512',
      type: 'image/png',
    },
  ],
};
```

Then define a helper function that sets the metadata and attaches all EventListeners to the player. The action handlers inside this function can be customized depending on your needs.

```javascript
function addMediaSessionEventListeners(player) {
  const mediaSession = navigator.mediaSession;
  if (mediaSession === undefined) {
    return;
  }
  mediaSession.setActionHandler('play', () => player.play());
  mediaSession.setActionHandler('pause', () => player.pause());
  mediaSession.setActionHandler('seekto', (details) => {
    if (isNaN(player.duration)) {
      return;
    }
    player.currentTime = details.seekTime;
  });
  mediaSession.setActionHandler('seekbackward', function (details) {
    if (isNaN(player.duration)) {
      return;
    }
    player.currentTime = Math.max(player.currentTime - (details.seekOffset ?? 10), 0);
  });
  mediaSession.setActionHandler('seekforward', function (details) {
    if (isNaN(player.duration)) {
      return;
    }
    player.currentTime = Math.min(player.currentTime + (details.seekOffset ?? 10), player.duration);
  });
  var updateMediaSession = function () {
    if (isNaN(player.duration)) {
      return;
    }
    mediaSession.playbackState = player.paused ? 'paused' : 'playing';
    const seekableLength = player.seekable.length;
    if (seekableLength === 0) {
      return;
    }
    mediaSession.setPositionState({
      duration: Math.max(player.seekable.end(seekableLength - 1), player.currentTime),
      playbackRate: player.playbackRate,
      position: player.currentTime,
    });
  };
  var onFirstPlaying = function () {
    player.removeEventListener(['play', 'playing'], onFirstPlaying);
    // Set MediaSession metadata
    if (mediaSessionMetadata !== undefined) {
      mediaSession.metadata = new MediaMetadata(mediaSessionMetadata);
    }
    // Start monitoring player to update MediaSession
    player.addEventListener(['play', 'pause', 'durationchange', 'timeupdate', 'ratechange'], updateMediaSession);
  };
  var onSourceChange = function () {
    // Remove event listeners
    player.removeEventListener(['play', 'playing'], onFirstPlaying);
    player.removeEventListener(['play', 'pause', 'durationchange', 'timeupdate', 'ratechange'], updateMediaSession);
    // Reset MediaSession
    mediaSession.metadata = undefined;
    mediaSession.playbackState = 'none';
    // Wait for next source playback
    player.addEventListener(['play', 'playing'], onFirstPlaying);
  };
  player.addEventListener('sourcechange', onSourceChange);
}
```

Finally, call the helper and set the source on your player that corresponds with the metadata:

```javascript
addMediaSessionEventListeners(player);

player.source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/sintel/nosubs.m3u8',
    },
  ],
};
```

# SharePlay

Implementing the Media Session API is part of implementing [Apple's SharePlay feature](https://developer.apple.com/shareplay/) on Safari. [Contact us](https://www.theoplayer.com/contact) if you're interested in building SharePlay experiences.

---

# How to use THEOplayer iOS SDK on an M1 mac

The iPhone simulators on M1 MacBooks use the arm64 architecture, therefore any binaries linked during compilation time that do not support the architecture will result in compilation error. Many third party frameworks lack the support for this particular architecture, and this causes unfortunate limitations for development.

Previous to writing this article (specifically with THEOplayer **versions 3.0.0 and below**), THEOplayer depended on few of these frameworks that lack the arm64 architecture, which in turn resulted in deciding to omit it. As of **version 3.1.0** and in part of our effort to optimize our modularization, the THEOplayer framework will be delivered with the arm64 architecture support as long as no feature is included that adds a dependency to an unsupported third party framework.

> **Important**
>
> To include the new architecture, import the **.xcframework** package into your project instead of the **.framework** package. The **.framework** is a fat framework and cannot include two arm64 architectures for device and simulator.

#### What are the features that lack arm64 simulator support?

**Google IMA / Google DAI** The Google IMA & DAI features rely on the [GoogleInteractiveMediaAds](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/download) framework which lacks the architecture in its fat framework binary. You can follow developer requests and updates from the IMA team in this [Google Groups conversation](https://groups.google.com/g/ima-sdk/c/y-5OHtAQ5rk?pli=1).

**Google Cast / Chromecast** The Chromecast feature relies on the [GoogleCast](https://developers.google.com/cast/docs/ios_sender#manual_setup) framework which lacks the architecture in its fat framework binary.

Other features that do not support the architecture are: **Agama, Moat & Yospace.**

#### What is the alternative solution?

In case you require one of the features in the section above to be included in your THEOplayer iOS SDK, then the suggested temporary solution is to use Apple's [Rosetta](https://support.apple.com/en-us/HT211861) to be able to run the framework on an iPhone simulator on an M1 mac. Rosetta will launch the simulator in **x86\_64** architecture instead of **arm64** and the framework will successfully be linked during compilation.

#### What about the future?

Whenever a third party dependency adds support to the architecture, we will address the situation and update our SDK framework. To stay up to date with changes related to our iOS SDK, check out our [changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md) where we post new updates and features with every new release.

---

# Widevine CDM deprecation notice for old browser versions

Google announced that the current version of the Widevine Content Decryption Module (CDM), which is a closed environment responsible for handling the DRM restrictions and decryption of media, will stop working on 6 December 2022.

## What is the effect of this?

Users will not be able to view Widevine-protected streams if they are on an older version of their browser since Google is deactivating the older versions of the Widevine CDM.

## What should you do if a certain user has an issue with your DRM-protected streams?

If you get a question on why your DRM streams wouldn't work for some of your users, especially around 6 December 2022, it is best to ask them to make sure they are on the latest version of their browser. Almost every browser nowadays have an auto-update mechanism, however many of us ignore the big `Update` button on Chrome or never fully restart the browser to let it finish an update.

## Which platforms are affected?

According to Google, only desktop browsers are affected. Mobile browsers and Chromium-based Smart TVs like LG webOS or Samsung Tizen SmartTVs are not affected.

## Should you update your THEOplayer SDK if you are on an older version?

The deprecation from Google does not require any changes from our side. If you are on an older THEOplayer version, your Widevine streams will still work as expected as long as the browser you are using the SDK on is on the latest version. However, as always, we recommend staying up to date and using the latest version of our SDKs to make use of the new features and improvements we constantly make.

To summarize, since this change from Google only affects the old CDM versions integrated with the older versions of Widevine supporting browsers, as long as you are on the latest version of your browser of choice, everything should still work after 6 December 2022.

## Related pages

* [How to update an SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/how-to-update-a-sdk.md)
* [THEOplayer Platform Support](https://www.theoplayer.com/platform-support)
* [THEOplayer Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/changelog.md)

---

# Which source is the one being played

In THEOplayer, `player.source.sources` can be used to provide alternative sources for playback, for cross-platform support. What is the actual source being played, if more than one is provided that is supported on the current platform/browser?

The player will select the first source (top to bottom) of a type that is supported on the current platform and try to play it. The player will *not* automatically select a new source from the list if the current one is failing to play for any reason unrelated to platform support.

You can also find out which the source is that the player selects with the `currentsourcechange` event ([documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/CurrentSourceChangeEvent)).

A few additional notes:

* It is of course possible to make the player attempt to play a different source if the one being played errors or never starts to play, but this is to be done in the implementation.
* `player.source.sources` is not intended as a playlist. Playlists can also be accomplished on the implementation side. Here is a simple [example](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/playback/playlist-and-caching.md) for the Web SDK.
* This mechanism is based on what the platform declares to support. It does not ensure that all codecs/features included in the stream are supported correctly on the current platform.

---

# What is the "`WebAssembly.compileStreaming` failed" warning and what does it mean?

When starting playback in THEOplayer, you might be seeing a warning in console that reads<br />`'WebAssembly.compileStreaming' failed because your server does not serve wasm with 'application/wasm' MIME type. Falling back to 'WebAssembly.compile' which is slower. Original error: TypeError: Failed to execute 'compile' on 'WebAssembly': Incorrect response MIME type. Expected 'application/wasm'.`

The current HLS pipeline, default since THEOplayer 4.0, works (where possible) with a wasm worker. Some implementations cannot or choose not to serve *wasm*, and we have a fallback mechanism for those cases, which avoids impact on user experience. If this fallback is triggered, this warning appears in console.

In other words, *wasm* allows for better overall performance and the player will try to use this solution first. If this is not possible, it will use different logic, but this doesn't impact the end users. You can safely ignore this warning.

> **Important**
>
> The *wasm* file must be served with the correct MIME type ('application/wasm'), otherwise the player will not recognize it properly and fall back onto the alternative (in this case, the warning will also be shown). If the file is served with the wrong MIME type (e.g.: text/html), this must be corrected on the server side.

---

# What PiP options to use to make the video stay visible while browsing or on other applications

When it comes to Picture-in-Picture (PiP), there are different options, each with its advantages and disadvantages. To have the floating video remain visible during browsing, you need an out-of-app PiP, but not all features are available (or the same) everywhere.<br />The following gives a short general description of the most commonly used options.

## THEOplayer PiP

[This guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/miscellaneous/picture-in-picture.md) will help you get started with THEOplayer PiP in your implementation.<br />Highlights:

* *Pros*: easily configured within the playerConfig; it will automatically trigger when the visible video portion is below the declared threshold; the pause/resume behavior with a click on any part of the video is maintained; CSAI ads and subtitles are correctly rendered in the floating window
* *Cons*: the floating player can't be resized at runtime and it sticks to its predefined position; it is in-app, meaning that it won't stay visible if you browse to other tabs or applications

## Native PiP

The [documentation available here](https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API) describes the API and you can easily get it working with the described methods.<br />Highlights:

* *Pros*: the user is in control of when the feature is active; this is out-of-app, meaning that the floating video element can be resized and moved, and it stays visible while browsing other tabs or apps.
* *Cons*: this requires a user action to be triggered; CSAI ads and subtitles may not be rendered in the floating video; resetting the source while in PiP may need additional logic for correct handling; it is not supported on all platforms (e.g.: Firefox and old versions of Safari, see [browser compatibility](https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API#browser_compatibility)); different browsers may have a somewhat different UI in the floating video;

## Firefox PiP

Firefox has its own version of PiP, which includes by default a button on the video element. [More information](https://support.mozilla.org/en-US/kb/about-picture-picture-firefox).<br />Highlights:

* pros and cons are mainly the same as for the native PiP, although the UI is different
* as this is a native Firefox feature, the button and context menu option to enable PiP cannot be hidden by the implementer. The users can, however, decide in their settings if the button will be visible for them.

---

# Why are the FairPlay license and certificate being requested again on iOS after ads?

The DRM license and certificate are retrieved when a DRM-protected stream starts to be played. This is usually enough for a full playback session since in most cases the DRM context can be maintained.<br />However, certain combinations of features may prevent this.

The most common case is when we indicate that on iOS browsers the native fullscreen should be used (`allowNativeFullscreen: true`). In this case, on these browsers ads and content will be played through the same `<video>` element, regardless of whether the user is actually playing in fullscreen.

This means that when a midroll is played, the previous DRM context is lost, so upon resuming content playback it must be re-established and the DRM license and certificate need to be requested again.

---

# How to detect if the user changes the video quality

It is possible to distinguish between when the quality is changed by ABR or by the user and, in the latter case, which quality has been selected.

This can be easily achieved listening to the `targetqualitychanged` event ([documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/TargetQualityChangedEvent)) such as in the snippet below:

```js
player.videoTracks[0].addEventListener('targetqualitychanged', (e) => {
  let selectedTrack = e.qualities[0];
});
```

**The possible cases**

* *ABR changes the quality being played*: this event is not fired
* *the user selects a specific quality*: an Object describing the quality is returned: the `height` and `bandwidth` properties may be checked to distinguish it from the other qualities
* *the user restores ABR*: `undefined` is returned

**Notes**

* The event returns an Array because the implementer may also use the targetQuality feature to select a subset of the available qualities to limit ABR to those qualities. If this is part of your use case, the snippet above might need to be tweaked to account for that case (e.g.: filter it out).
* when resetting the player.source, the videoTracks object is also reset, so the event will need to be appended again

---

# List of supported platforms

## THEOplayer HTML5 / Tizen / webOS SDK

|                                              | HLS                                                                                    |                                                                           | MPEG-DASH                                                                              |                                                            | HESP [1](#user-content-fn-hesp)                                                        |                                                   |
| -------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------- |
|                                              | Version                                                                                | Content Protection & DRM                                                  | Version                                                                                | Content Protection & DRM                                   | Version                                                                                | Content Protection & DRM                          |
| ### Desktop Browser Platforms                |                                                                                        |                                                                           |                                                                                        |                                                            |                                                                                        |                                                   |
| Chrome (and Chromium based)                  | Evergreen [2](#user-content-fn-evergreen)<br />(last 3 major versions)                 | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | ClearKey<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | Widevine DRM                                      |
| Edge (Chromium)                              | Evergreen<br />(last 3 major versions)                                                 | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM (on Windows) | Evergreen<br />(last 3 major versions)                                                 | ClearKey<br />Widevine DRM<br />PlayReady DRM (on Windows) | Evergreen<br />(last 3 major versions)                                                 | Widevine DRM<br />PlayReady DRM (on Windows)      |
| Firefox                                      | Evergreen<br />(last 3 major versions)                                                 | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | ClearKey<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | Widevine DRM                                      |
| Safari                                       | Evergreen<br />(last 3 major versions)                                                 | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | Evergreen<br />(last 3 major versions)                                                 | ClearKey                                                   | Evergreen<br />(last 3 major versions)                                                 | FairPlay DRM                                      |
| ### Mobile Browser Platforms                 |                                                                                        |                                                                           |                                                                                        |                                                            |                                                                                        |                                                   |
| Chrome for Android                           | Evergreen<br />(last 3 major versions)                                                 | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | ClearKey<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | Widevine DRM                                      |
| Firefox for Android                          | Evergreen<br />(last 3 major versions)                                                 | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | ClearKey<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | Widevine DRM                                      |
| Safari for iOS                               | Evergreen<br />(last 3 major versions)                                                 | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | N/A [3](#user-content-fn-na)                                                           | N/A                                                        | iOS 14+                                                                                | FairPlay DRM                                      |
| ### Connected devices and smart TV platforms |                                                                                        |                                                                           |                                                                                        |                                                            |                                                                                        |                                                   |
| Samsung Tizen                                | 2.3+                                                                                   | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 2.3+                                                                                   | ClearKey<br />Widevine DRM<br />PlayReady DRM              | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/) |
| LG webOS                                     | 3.0+                                                                                   | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 3.0+                                                                                   | ClearKey<br />Widevine DRM<br />PlayReady DRM              | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/) |
| HbbTV                                        | N/A                                                                                    | N/A                                                                       | 1.5, 2.0.1+<br />[Contact us](https://optiview.dolby.com/contact/)                     | ClearKey<br />PlayReady DRM                                | N/A                                                                                    | N/A                                               |
| Hisense Vidaa U                              | 3.0+                                                                                   | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | 3.0+                                                                                   | ClearKey<br />Widevine DRM                                 | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/) |
| Vizio                                        | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/)                         | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/)          | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/) |
| RDK<br />WPE & Lightning                     | 2.20+<br />[Contact us](https://optiview.dolby.com/contact/)                           | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 2.20+<br />[Contact us](https://optiview.dolby.com/contact/)                           | ClearKey<br />Widevine DRM<br />PlayReady DRM              | 2.20+<br />[Contact us](https://optiview.dolby.com/contact/)                           | Widevine DRM<br />PlayReady DRM                   |
| Xbox                                         | One, Series S, Series X                                                                | [Contact us](https://optiview.dolby.com/contact/)                         | One, Series S, Series X                                                                | [Contact us](https://optiview.dolby.com/contact/)          | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/) |
| PlayStation                                  | PS4<br />PS5<br />[Contact us](https://optiview.dolby.com/contact/)                    | PlayReady DRM                                                             | PS4<br />PS5<br />[Contact us](https://optiview.dolby.com/contact/)                    | PlayReady DRM                                              | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/) |
| Web based                                    | Chromium 38+<br />WebKit 537.3+<br />[Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)                         | Chromium 38+<br />WebKit 537.3+<br />[Contact us](https://optiview.dolby.com/contact/) | PlayReady DRM                                              | Chromium 38+<br />WebKit 537.3+<br />[Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |

## THEOplayer iOS / tvOS SDK

|        | HLS     |                                           | MPEG-DASH |                          | HESP (\*) |                          |
| ------ | ------- | ----------------------------------------- | --------- | ------------------------ | --------- | ------------------------ |
|        | Version | Content Protection & DRM                  | Version   | Content Protection & DRM | Version   | Content Protection & DRM |
| iOS    | 15+     | AES-128<br />SAMPLE-AES<br />FairPlay DRM | N/A       | N/A                      | 15+       | FairPlay DRM             |
| iPadOS | 15+     | AES-128<br />SAMPLE-AES<br />FairPlay DRM | 15+       | ClearKey                 | 15+       | FairPlay DRM             |
| tvOS   | 15+     | AES-128<br />SAMPLE-AES<br />FairPlay DRM | 15+       | ClearKey                 | 15+       | FairPlay DRM             |

## THEOplayer Android / Fire TV SDK

|                                         | HLS                                               |                                                              | MPEG-DASH                                         |                                                   | HESP (\*)                                         |                                                   |
| --------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- |
|                                         | Version                                           | Content Protection & DRM                                     | Version                                           | Content Protection & DRM                          | Version                                           | Content Protection & DRM                          |
| Android                                 | 5.0+                                              | AES-128<br />SAMPLE-AES<br />Widevine DRM                    | 5.0+                                              | ClearKey<br />Widevine DRM                        | 5.0+                                              | Widevine DRM                                      |
| Android TV                              | 7+                                                | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM | 7+                                                | ClearKey<br />Widevine DRM<br />PlayReady DRM     | 7+                                                | Widevine DRM<br />PlayReady DRM                   |
| Fire TV                                 | 5+                                                | AES-128<br />SAMPLE-AES<br />Widevine DRM                    | 5+                                                | ClearKey<br />Widevine DRM                        | 5+                                                | Widevine DRM                                      |
| AOSP<br />(Android Open Source Project) | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)            | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |

## THEOplayer Roku SDK

|                               | HLS                                    |                                                              | MPEG-DASH                              |                                               | HESP (\*)                                         |                                                   |
| ----------------------------- | -------------------------------------- | ------------------------------------------------------------ | -------------------------------------- | --------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- |
|                               | Version                                | Content Protection & DRM                                     | Version                                | Content Protection & DRM                      | Version                                           | Content Protection & DRM                          |
| Roku OS                       | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM | Evergreen<br />(last 3 major versions) | ClearKey<br />Widevine DRM<br />PlayReady DRM | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| ### Casting                   |                                        |                                                              |                                        |                                               |                                                   |                                                   |
| Apple Airplay                 | Safari<br />iOS & iPadOS               | FairPlay DRM                                                 | N/A                                    | N/A                                           | N/A                                               | N/A                                               |
| Google Cast<br />(Chromecast) | Chrome<br />Android<br />iOS & iPadOS  | AES-128<br />SAMPLE-AES<br />Widevine DRM                    | Chrome<br />Android<br />iOS & iPadOS  | ClearKey<br />Widevine DRM<br />PlayReady DRM | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |

## THEOplayer React Native SDK

|                                                                   | HLS                                               |                                                                           | MPEG-DASH                                         |                                                              | HESP (\*)                                         |                                                   |
| ----------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- |
|                                                                   | Version                                           | Content Protection & DRM                                                  | Version                                           | Content Protection & DRM                                     | Version                                           | Content Protection & DRM                          |
| ### Desktop Browser Platforms                                     |                                                   |                                                                           |                                                   |                                                              |                                                   |                                                   |
| Chrome (and Chromium based)                                       | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)            | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Edge (Chromium)                                                   | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM (on Windows) | Evergreen<br />(last 3 major versions)            | ClearKey<br />Widevine DRM<br />PlayReady DRM (on Windows)   | Evergreen<br />(last 3 major versions)            | Widevine DRM<br />PlayReady DRM (on Windows)      |
| Firefox                                                           | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)            | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Safari                                                            | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | Evergreen<br />(last 3 major versions)            | ClearKey                                                     | Evergreen<br />(last 3 major versions)            | FairPlay DRM                                      |
| ### Mobile Browser Platforms                                      |                                                   |                                                                           |                                                   |                                                              |                                                   |                                                   |
| Chrome for Android                                                | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)            | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Firefox for Android                                               | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)            | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Safari for iOS                                                    | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | N/A                                               | N/A                                                          | iOS 14+                                           | FairPlay DRM                                      |
| ### Connected devices and smart TV platforms                      |                                                   |                                                                           |                                                   |                                                              |                                                   |                                                   |
| Samsung Tizen                                                     | 2.3+                                              | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 2.3+                                              | ClearKey<br />Widevine DRM<br />PlayReady DRM                | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| LG webOS                                                          | 3.0+                                              | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 3.0+                                              | ClearKey<br />Widevine DRM<br />PlayReady DRM                | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| Hisense Vidaa U                                                   | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)                         | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)            | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| Vizio                                                             | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)                         | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)            | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| RDK<br />WPE & Lightning<br />(e.g. Liberty Global, Comcast, Sky) | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)                         | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)            | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| ### Native Apps                                                   |                                                   |                                                                           |                                                   |                                                              |                                                   |                                                   |
| iOS                                                               | 15+                                               | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | N/A                                               | N/A                                                          | 15+                                               | FairPlay DRM                                      |
| iPadOS                                                            | 15+                                               | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | 15+                                               | ClearKey                                                     | 15+                                               | FairPlay DRM                                      |
| tvOS                                                              | 15+                                               | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | 15+                                               | ClearKey                                                     | 15+                                               | FairPlay DRM                                      |
| Android                                                           | 5.0+                                              | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | 5.0+                                              | ClearKey<br />Widevine DRM                                   | 5.0+                                              | Widevine DRM                                      |
| Android TV                                                        | 7+                                                | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 7+                                                | ClearKey<br />Widevine DRM<br />PlayReady DRM                | 7+                                                | Widevine DRM<br />PlayReady DRM                   |
| Fire TV                                                           | 5+                                                | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | 5+                                                | ClearKey<br />Widevine DRM                                   | 5+                                                | Widevine DRM                                      |
| Xbox                                                              | One, Series S, Series X                           | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | One, Series S, Series X                           | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| ### Casting                                                       |                                                   |                                                                           |                                                   |                                                              |                                                   |                                                   |
| Apple Airplay                                                     | Safari<br />iOS & iPadOS                          | FairPlay DRM                                                              | N/A                                               | N/A                                                          | N/A                                               | N/A                                               |
| Google Cast<br />(Chromecast)                                     | Chrome<br />Android<br />iOS & iPadOS             | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Chrome<br />Android<br />iOS & iPadOS             | ClearKey<br />Widevine DRM<br />PlayReady DRM                | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |

## THEOplayer Flutter SDK

|                               | HLS                                    |                                                                           | MPEG-DASH                              |                                                              | HESP (\*)                                         |                                                   |
| ----------------------------- | -------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- |
|                               | Version                                | Content Protection & DRM                                                  | Version                                | Content Protection & DRM                                     | Version                                           | Content Protection & DRM                          |
| ### Desktop Browser Platforms |                                        |                                                                           |                                        |                                                              |                                                   |                                                   |
| Chrome (and Chromium based)   | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions) | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Edge (Chromium)               | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM (on Windows) | Evergreen<br />(last 3 major versions) | ClearKey<br />Widevine DRM<br />PlayReady DRM (on Windows)   | Evergreen<br />(last 3 major versions)            | Widevine DRM<br />PlayReady DRM (on Windows)      |
| Firefox                       | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions) | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Safari                        | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | Evergreen<br />(last 3 major versions) | ClearKey                                                     | Evergreen<br />(last 3 major versions)            | FairPlay DRM                                      |
| ### Mobile Browser Platforms  |                                        |                                                                           |                                        |                                                              |                                                   |                                                   |
| Chrome for Android            | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions) | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Firefox for Android           | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions) | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Safari for iOS                | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | N/A                                    | N/A                                                          | iOS 14+                                           | FairPlay DRM                                      |
| ### Native Apps               |                                        |                                                                           |                                        |                                                              |                                                   |                                                   |
| iOS                           | 15+                                    | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | N/A                                    | N/A                                                          | 15+                                               | FairPlay DRM                                      |
| iPadOS                        | 15+                                    | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | 15+                                    | ClearKey                                                     | 15+                                               | FairPlay DRM                                      |
| Android                       | 5.1+                                   | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | 5.1+                                   | ClearKey<br />Widevine DRM                                   | 5.1+                                              | Widevine DRM                                      |
| Android TV                    | 7+                                     | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 7+                                     | ClearKey<br />Widevine DRM<br />PlayReady DRM                | 7+                                                | Widevine DRM<br />PlayReady DRM                   |
| Fire TV                       | 5+                                     | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | 5+                                     | ClearKey<br />Widevine DRM                                   | 5+                                                | Widevine DRM                                      |
| Xbox                          | One, Series S, Series X                | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | One, Series S, Series X                | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |

## Footnotes

1. HESP support is not available by default in THEOplayer. Contact our team for more information. [↩](#user-content-fnref-hesp)

2. Evergreen means this platform receives automatic software updates. Customers will be using the last version of software, but for users lagging behind in updates, we ensure compatibility with the latest three versions. [↩](#user-content-fnref-evergreen)

3. N/A: Not available due to platform limitations. [↩](#user-content-fnref-na)

---

# How to use AI coding assistants with THEOplayer

AI coding assistants (Claude Code, Cursor, GitHub Copilot, Windsurf, ...) work better when they have up-to-date THEOplayer documentation in their context. This page lists the machine-readable files we publish and gives a starter rules file you can copy into your project.

## Machine-readable documentation

The documentation site publishes the following plain-text files, following the [llms.txt convention](https://llmstxt.org/):

| File                                                                                                        | Content                                                                                                                                                                                                           |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/docs/llms.txt`](https://docs-preview.optiview.dolby.com/pr-932/llms.txt)                                 | Root index: one section per product, linking to the files below                                                                                                                                                   |
| [`/docs/theoplayer/llms.txt`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/llms.txt)           | Index of all THEOplayer pages, grouped per SDK and category, with descriptions                                                                                                                                    |
| [`/docs/theoplayer/llms-full.txt`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/llms-full.txt) | Full text of the THEOplayer documentation in a single file                                                                                                                                                        |
| `/docs/<page>.md`                                                                                           | Markdown version of every page, for example [`/docs/theoplayer/getting-started/sdks/web/getting-started.md`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started/) |

The same `llms.txt` and `llms-full.txt` files exist for the other products: `open-video-ui`, `ads`, `ad-engine`, `millicast` and `theolive`.

The `llms-full.txt` files are large. Most assistants work best when you point them at `llms.txt` and let them fetch the individual `.md` pages when needed.

Other useful sources of context:

* **Web SDK API reference**: the `theoplayer` npm package ships TypeScript type definitions (`THEOplayer.d.ts`). Assistants read these directly from `node_modules`.
* **API reference for all platforms**: [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/android), [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/ios).
* **Open-source SDKs and connectors on GitHub**: [react-native-theoplayer](https://github.com/THEOplayer/react-native-theoplayer), [flutter-theoplayer-sdk](https://github.com/THEOplayer/flutter-theoplayer-sdk), [web-ui](https://github.com/THEOplayer/web-ui) and [web-connectors](https://github.com/THEOplayer/web-connectors).

## Starter rules file

Copy the text below into the rules file of your assistant (`CLAUDE.md` or `AGENTS.md` in the project root, `.cursor/rules/theoplayer.mdc` for Cursor, `.github/copilot-instructions.md` for Copilot) and remove the platforms you do not use.

```markdown
# THEOplayer integration rules

This project integrates the THEOplayer (Dolby OptiView Player) SDK.

## Documentation

- Documentation index: https://optiview.dolby.com/docs/theoplayer/llms.txt
  (every entry links to a Markdown version of the page; fetch pages from there)
- Full THEOplayer docs in one file: https://optiview.dolby.com/docs/theoplayer/llms-full.txt
- Index of all Dolby OptiView products: https://optiview.dolby.com/docs/llms.txt
- Prefer the documentation above over training data. THEOplayer APIs change between
  major versions; check the version used in this project before suggesting an API.

## Packages

- Web: `theoplayer` on npm. Import from `theoplayer` (or `theoplayer/chromeless` for a player
  without the default UI). Types are in `THEOplayer.d.ts` inside the package.
- Android: `com.theoplayer.theoplayer-sdk-android:core` (Maven). Optional integrations are
  separate artifacts, for example `com.theoplayer.theoplayer-sdk-android:integration-ads-ima`.
- iOS / tvOS: `THEOplayerSDK` via Swift Package Manager (https://github.com/THEOplayer/theoplayer-sdk-apple)
  or CocoaPods (`THEOplayerSDK-core`).
- React Native: `react-native-theoplayer` on npm.
- Flutter: `theoplayer` on pub.dev.

## Rules

- Keep the same THEOplayer major version across all SDKs and integrations in the project.
- The player needs a license string. Read it from configuration, never hard-code a production
  license in source.
- Do not implement playback logic (ABR, DRM, HLS/DASH parsing) yourself. Use the SDK APIs and
  the documented integrations (ads, DRM, analytics connectors).
- Wrapper SDKs (React Native, Flutter) delegate to the native SDKs. Configure features through
  the wrapper API; do not call the native SDK directly unless documented.
- When an API is not covered by the documentation, say so instead of guessing.
```

## Feedback

If the machine-readable files are missing content you need, open an issue on [THEOplayer/documentation](https://github.com/THEOplayer/documentation/issues).

---

# What are the Uplynk challenges

The purpose of this article is to group common challenges application developers might encounter when using [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/introduction.md) (formerly known as Verizon Media, Edgecast or Edgio) as the back-end.

1. [Why does Chromecast or AirPlay not work?](#why-does-chromecast-or-airplay-not-work)
2. [Why aren't all video qualities showing up?](#why-arent-all-video-qualities-showing-up)
3. [What should I know before tokenizing my stream?](#what-should-i-know-before-tokenizing-my-stream)

## Why does Chromecast or AirPlay not work?

If you've [correctly enabled Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/cast/chromecast/enable-chromecast-on-the-sender.md) or AirPlay, but you are not getting any playback on your Chromecast or AirPlay device, then a likely cause is your [tokenization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/preplay.md#using-tokens) approach.

1/ When you tokenize a URL, you are also specifying an expiration date. It is possible that your expiration date has passed when you initiate the casting session. Your stream will no longer be valid when this is the case, and result in unsuccessful casting.

The solution? Use an expiration date that is valid for a longer time.

2/ An Uplynk token will be attached to one IP address when it's invoked for the first time (i.e. request to the Preplay URL with the token as a query parameter). This could cause problems when either your sender device (i.e. iOS app, Android app, browser) or receiver device (i.e. Chromecast device) uses an iPv6 address, because those addresses are unique. (Meaning: the token could be invalid for your IPv6 receiver device because it was already attached to your different IPv4 sender device.)

The solution?

1. You can disable IP address checking by adding `pp2ip=0` to your token (and Preplay parameters).
2. You can implement a [custom Chromecast receiver app](https://github.com/THEOplayer/samples-google-cast-v3-receiver) that generates its own unique token. (This however doesn't address the issue on AirPlay, and also gives rise to challenges related to building a custom Chromecast app.)
3. You can disable tokenization (if it's not a requirement).

## Why aren't all video qualities showing up?

If you notice that THEOplayer doesn't expose all your Uplynk MPEG-DASH video qualities, then the likely culprit is not aggregating the different `AdaptationSet`s as part of Uplynk's multi-key approach.

The solution?

Add `singlevideolicense=1` to your Preplay parameters and/or token. Doing so will group all qualities to one `AdaptationSet` with one key.

## What should I know before tokenizing my stream?

Refer to [Preplay - tokenization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/preplay.md#using-tokens).

---

# Knowledge base

Want to know more about topics in the video industry? We have a small list of articles to provide you some basic knowledge.

## [💰Advertisements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/introduction.md)

[3 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/introduction.md)

## [🔐Content protection](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/content-protection/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/content-protection/introduction.md)

## [▶️Playback](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/introduction.md)

[7 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/introduction.md)

## [🎥Streaming](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/streaming/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/streaming/introduction.md)

## [🔗CORS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/cors/introduction.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/cors/introduction.md)

## [🏷️Metadata](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/metadata/introduction.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/metadata/introduction.md)

---

# Advertisements

This section allows you to learn everything about advertisements!

## [📄️Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/user-guide.md)

[THEOplayer allows you to configure different aspects of its advertising environment. By following this guide you will learn about:](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/user-guide.md)

## [📄️Server Side Ad Insertion](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/server-side-ad-insertion.md)

[If you are a content distributor, you know how difficult it is to properly monetize content. While content acquisition can be expensive, more and more users are looking for ways to access premium content for free.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/server-side-ad-insertion.md)

## [📄️Support matrix](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/support-matrix.md)

[THEOplayer currently supports two ad implementations:](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/support-matrix.md)

---

# Advertising User Guide

THEOplayer allows you to configure different aspects of its advertising environment. By following this guide you will learn about:

* The advertisement feature in THEOplayer, with a focus on a few key concepts

* The ad integrations in THEOplayer

* Ad configuration and ad block detection

* Related resources, including

  * How-to guides related to specific integrations
  * The reference API
  * Other ad-related how-to guides, information pages, blog articles, etc.

How to configure ads, code snippets and specific support and use for the various integrations are found on the guides dedicated to the specific integrations.

## Feature Overview

### An overview of THEOplayer's Advertisement tools

THEOplayer offers an array of features that allow you to take total control over your online video content advertisement environment.

To facilitate integration between content providers and ad servers, we implement the IAB Video Suite, a set of technical specifications that are widely used by many participants in the online video advertisement industry. More specifically, we implement the following IAB specifications: *Digital Video Ad Serving Template* (**VAST**), *Digital Video Multiple Ad Playlist* (**VMAP**) and *Digital Video Player-Ad Interface Definition* (**VPAID**). You will have to get acquainted with these specifications if you want to optimize your advertisement revenue.

On top of the IAB suite, THEOplayer comes with additional tools to improve advertisement efficiency, like **Adblock Detection**.

#### Digital Video Ad Serving Template (VAST)

The Digital Video Ad Serving Template (VAST) specification is a description for video ads that standardizes communication requirements between video players and ad server. It gives instructions to the video player on how ads should be handled and displayed. It can define how and how long the ad should be displayed, if and when it can be skipped and how to give tracking information to the ad servers. VAST also specifies ad pods. These are groups of advertisements which should be played back-to-back.

THEOplayer offers support for the delivery of video ads with VAST 4.0. Support is available for linear ads (pre-rolls, mid-rolls, post-rolls and ad breaks), non-linear ads (overlay banners) and companion banners, all of which are discussed in the next section.

#### Digital Video Multiple Ad Playlist (VMAP)

With Digital Video Multiple Ad Playlist (VMAP), video content owners can exercise control over the ad inventory displayed with their content when they cannot control the video player, to capitalize on advertising while maintaining the integrity of their program content. VMAP enables the content owner to define the ad breaks within their content, including the timing for each break, how many breaks are available, what type of ads and how many are allowed in each break. It is important to note however that VMAP was mainly designed with Video on demand (VOD) in mind.

#### Digital Video Player-Ad Interface Definition (VPAID)

VPAID establishes a common communication protocol between video players and ad units that allows a single “executable ad” (one that requires software logic to be executed as part of ad playback) to be displayed in-stream with the publisher’s video content. It allows the ad and the player to expect and rely upon a common set of functionalities. The significance is that advertisers using VPAID ads can provide rich ad experiences for viewers and collect ad playback and interaction details that are just as rich as the ad experience. With the adoption of VPAID, advertisers have more control over the display experience in their video campaigns. VPAID ads can easily be integrated on top of VAST manifests.

#### Adblock detection

Ad blockers or filters (such as the AdBlock plugin for browsers) remove or alter ads on webpages such that they become less obtrusive for the user. They can be a big threat to websites that get their revenue from video advertisements as they prevent an ad from being played. THEOplayer has built-in features that can detect ad blockers and act accordingly.

### An overview of THEOplayer's different ad types

THEOplayer has support for **Linear**, **Non-linear** and **Companion** VAST and VPAID ads, as well as for VMAP ads.

THEOplayer currently supports several ad playback implementations:

**Client-side ad insertion (CSAI)**

1. THEOplayer (default)
2. Google IMA
3. SpotX
4. FreeWheel

**Server-side ad insertion (SSAI)**

1. Google DAI
2. Yospace
3. Verizon Media
4. MediaTailor

Below you can find the support matrix for different types of ads:

|            | VAST | VMAP | VPAID |
| ---------- | ---- | ---- | ----- |
| THEOplayer | Yes  | Yes  | No    |
| Google IMA | Yes  | Yes  | Yes   |
| SpotX      | Yes  | Yes  | Yes   |
| FreeWheel  | Yes  | No   | Yes   |
| Google DAI | No   | No   | No    |
| Yospace    | Yes  | Yes  | No    |

#### Linear Ads

Linear ads are video ads that play before, during or after the content video. THEOplayer allows you to specify an optional offset to make a linear ad play at a given time during or after the video. Linear ads can be further configured by specifying how long the ad must be watched before the user can skip it. Linear ads can be interactive (VPAID) or can simply have a click-through that directs users to a webpage on a different screen.

#### Non-linear Ads (overlays)

Non-linear ads are shown on top of the video as an overlay during playback. The user can interact with these ads by clicking them, which will, for example, redirect them to a page with more information about the product being advertised. Non-linear ads can also be closed by users.

#### Companion Ads

Companion banners are ads surrounding the video player that, in comparison with linear and non-linear ads, do not directly interfere with a user’s viewing experience. THEOplayer allows you to choose where the companion ads should be displayed on your website so it better integrates with the layout of the page.

## Ad Integrations

Advertisements are described through the AdDescription object in the API. Beside defining a source, you can also define the integration property.

### Client-Side Ad Insertion (CSAI)

Client-Side Ad Insertion (CSAI) is the traditional method of inserting advertisements into an online video. Through this method, advertisements and video are served separately and integrated into the video player on the client side: this approach pauses your content, loads a video advertisement, and then resumes your video when the ad is finished. The benefit of CSAI is that it is easy to implement and integrate. As it has direct contact with the ad server, it also allows advertisers to better track metrics. On the client side, the video player is responsible for loading all necessary files (e.g. VAST, videos, banners), managing the timing of when the advertisements should be played, interrupting playback when needed and ensuring that switching content and error handling works smoothly.

THEOplayer provides several integrations to achieve CSAI, including its own integration:

#### THEOplayer

The THEOplayer ad system is selected with the value 'theo'. As this ad system is the default one, you do not have to indicate this preference, and you can omit the integration property altogether. More information can be found at:

* [Ads Reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Ad)

* [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/set-up-vast-and-vmap.md): this how-to guide contains information regarding this integration, including how to use this integration, requirements (if any) and code samples.

#### Google IMA

Set the `integration` property to `'google-ima'` to use the Google IMA integration. More information can be found at:

* [Reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/IMAAdDescription)
* [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/google-ima.md): this how-to guide contains information regarding this integration, including how to use this integration, requirements (if any) and code samples.

#### SpotX

Set the `integration property` to `'spotx'` to configure SpotX ads. More information can be found at:

* [Reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/SpotXAdDescription)
* [SpotX](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/spotx.md): this how-to guide contains more information regarding this integration, including how to use this integration, requirements (if any) and code samples.

#### FreeWheel

Set the `integration` property to `'freewheel'` to configure FreeWheel ads. Please note that, in this case, the adSource properties are different from those for other ad integrations (e.g.: theo integration). More information can be found at:

* [Reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/FreeWheelAdDescription)
* [FreeWheel](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/freewheel.md): this how-to guide contains more information regarding this integration, including how to use this integration, requirements (if any) and code samples.

### Server Side Ad Insertion (SSAI)

With Server-Side Ad Insertion (SSAI), advertising content is injected into a video stream: the broadcaster indicates when advertisements may be inserted by providing cues (hints) in the stream. The content is then forwarded to an ad insertion server, which replaces the dummy content with actual advertisements. That way, the advertisements are part of the stream. This creates an experience much like traditional broadcasting. SSAI opens the door to many possibilities. For example, inserted advertisement content can be personalized down to a single-user level, for improved advertisement efficiency. As a client can no longer make the distinction between content and advertisement video chunks, their download calls cannot be blocked by ad blockers. This increases advertisement revenue compared to traditional client-side ads.

THEOplayer pre-integrates with first-class Server-Side Ad Insertion(SSAI) providers, including Google DAI and Yospace.

#### Google Dynamic Ad Insertion (DAI)

To use the Google DAI integration you have to set the `integration` key to `'google-dai'`.

* [Reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/GoogleDAIConfiguration)

#### Yospace

To use the Yospace integration you have to set the `integration` key to `'yospace'`.

* [Reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Yospace)
* [Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/yospace.md): this how-to guide contains more information regarding this integration, including how to use this integration, requirements (if any) and code samples.

#### Verizon Media

To use the Verizon Media integration you have to set the `integration` key to `'verizon-media'`.

You can refer to [our section on Verizon Media](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/ads.md) to learn more about SSAI with Verizon Media.

#### MediaTailor

To use the MediaTailor integration you have to set the `integration` key to `'mediatailor'`.

You can refer to [our MediaTailor guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/mediatailor.md) to learn more about SSAI with MediaTailor.

## Ad Configuration

### Basic Ad Configuration

As we discussed in [An overview of THEOplayer's Advertisement tools](#overview-advertisement-tools), VAST gives instructions to the video player on how ads should be handled and displayed. This guide does not go into the details of how to create a VAST file. We only refer to the VAST specification, a good starting point if you want to learn the skill.

Here, we will discuss how you can add existing VAST ads to THEOplayer - examples for all the features explained in this section can be found in the how-to guides linked below.

#### Adding and configuring VAST ads

The player supports VAST by specifying a URL parameter to the VAST description in the player configuration. The player will automatically load this advertisement description and act accordingly.

| Attribute | Description                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------- |
| `sources` | This mandatory parameter allows you to specify the location of the VAST advertisement XML file. |

**Specifying an offset for your ad**

You can specify an optional offset parameter that indicates at what time the ad should be displayed before, during or after the video. This parameter works for linear as well as non-linear and companion ads and has the following specification:

* `timeOffset`: This optional parameter allows you to determine the placement of the specified ad. Five different formats are allowed:

  * **seconds**: a numeric value representing the number of seconds into the video the ad should play.
  * **time**: in the format `hh:mm:ss.mmm` (`.mmm` is optional), for example `'00:35:30.000'`.
  * **percentage**: in the format `n%`, where n is a value from 0-100, for example `50%`.
  * **start/end**: The value `'start'` signifies that the video is a pre-roll and should be played before the actual video can be watched. The value `'end'` signifies that the video is a post-roll and should be played after the original video.

If you are using a VMAP ad, this property should not be used, as the VMAP format specifies its own time offset for breaks. Using this property with VMAP may cause no ad breaks or incorrect placement of ad breaks.

**Configuring your ad to be skippable**

You can allow an ad to be skipped by adding a skip parameter in the configuration. The skip parameter describes how long - in seconds - the ad must be watched before the user can skip it. The parameter is optional: if you do not define one, THEOplayer will use the information specified by the VAST file itself.

*NOTE: ad-skipping is currently not supported on some iOS devices for google IMA.*

| Attribute    | Description                                                                                                                                                                                                                      |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `skipOffset` | This optional parameter allows you to override the amount of seconds a viewer must watch the advertisement before it can be skipped. A negative value of -1 disables ad-skipping (even if the VAST file specifies a skip delay). |

**Choosing where to place companion ads**

THEOplayer allows you to render companion ads where you want. This way, you can optimally integrate ads with the layout of your page. When a companion ad is in the VAST/VMAP/VPAID, you can detect them through an event listener. These elements can be added to the page where they fit best.

#### Control the ads shown alongside your content with VMAP

The VMAP protocol enriches the VAST data with the timing of the advertisements. Again, we will not explain how you should create VMAP files, you can read more on that in the [VMAP specification](https://www.iab.com/guidelines/digital-video-multiple-ad-playlist-vmap-1-0-1/). Configuration of the skipOffset delay can be done similarly as in the VAST configuration, discussed in [Adding and configuring VAST ads](#adding-configuring-vast-ads). The following table summarizes the possibilities and effects of each option.

| Attribute    | Description                                                                                                                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sources`    | This parameter specifies the location of the VMAP advertisement XML file.                                                                                                                                                            |
| `skipOffset` | This optional parameter allows overriding the number of seconds a viewer must watch a pre-roll ad before it can be skipped. A negative value of -1 disables ad-skipping. This will affect all linear ads specified in the VMAP file. |

#### Adding and configuring interactive VPAID ads

Our player provides VPAID 2.0 support via our Google IMA integration. This version of the specification is designed to further facilitate VPAID integration with VAST. This means that you can embed rich VPAID ads in your VAST manifests and add those manifests to our player, as we have shown in [Adding and configuring VAST ads](#adding-configuring-vast-ads).

### Advanced Ad Configuration

#### Dynamic Ad Scheduling

In [Basic Ad Configuration](#basic-ad-config), we learned how to statically add ads to THEOplayer on startup by specifying them in the configuration object. However, several interesting use cases exist that require on the fly ad injection, for example when VAST files should be added by a script provided by an external ad server.

To dynamically add advertisements, you should use the [`player.ads.schedule(AdDescription)`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Ads#schedule) function which will add the given ad file as if it were specified in the initial configuration. The AdDescription - which you will pass as a parameter to the function - is the same object as previously discussed in [Basic Ad Configuration](#basic-ad-config).

NOTE: Please note that when adding a pre-roll when the original video is already playing (for example because of autoplay), the pre-roll cannot start playing. An advertisement with an offset of '0%' will always be able to play.

## Ad Block Detection

THEOplayer offers the option to block the player when an adblocker is detected. This can be achieved by setting blockOnAdBlock in the configuration.ads object to true. The player will display a message saying it has detected an ad blocker and that the user will need to turn it off in order to watch the video. A more in-depth code-example can be found at [Ad block detection example](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/ad-block-detection.md).

The default message that is shown when ad-block is detected is depicted below.

![Adblock detection](/pr-932/assets/images/adblock-detected-8348d073be3013c7944848c140c8a7ef.png)

## Demos and sample applications

* [Google DAI Demo Page](https://www.theoplayer.com/theoplayer-demo-google-dai)
* [SSAI Demo Page](https://demo.theoplayer.com/ssai)
* [THEOplayer: Advertisements Tester (VAST, VPAID, VMAP)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/advertisement-tester.md)
* [Adblock detection](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ads/ad-block-detection.md)

---

# Server Side Ad Insertion

If you are a content distributor, you know how difficult it is to properly monetize content. While content acquisition can be expensive, more and more users are looking for ways to access premium content for free.

When content creators and providers offer easy access to content with advertisements, users will often go one step further and install an ad-blocker which cancels out any client-side advertising. As a result the monetization of the content is offset and providers will no longer be able to cover costs.

Luckily, the design of adaptive streaming protocols allows for a solution.

## Server-Side Ad Insertion

An HLS or MPEG-DASH stream consists of a long chain of separate segments. Server-Side Ad Insertion (SSAI) is a simple concept wherein advertising content is injected into this stream of segments. This creates an experience much like traditional broadcasting, with the additional benefit that the injected advertising content can be personalized down to a single-user level. As a client can no longer make the distinction between content and advertisement download call, these calls cannot be blocked by ad blockers.

A fully-fledged SSAI system will also contain obfuscation and transcoding services that together will make your content more secure and more stable in playback. As a result, SSAI creates a solution very much like a traditional broadcasting experience. Additionally, a number of modern information and advertisement technologies is leveraged to further increase its efficiency in monetizing content.

### Dynamic Ad Insertion

While often used as an interchangeable term for Server-Side Ad Injection, Dynamic Ad Insertion (DAI) actually refers to the ability to dynamically customize the advertising content that is stitched into the stream. While people around the world could be watching the same sports event, it makes very little sense to show each viewer the same advertisement. Targeted ads are much more powerful and Dynamic Ad Insertion allows you to do exactly that.

On top of that, Dynamic Ad Insertion allows you to update advertisements. If someone's looking at a live show from four years ago, advertising a four-year-old promotion on cat food at your favorite supermarket chain would not be very effective.

### Live vs Video on demand

When we look at live and video on demand, leveraging the full power of SSAI requires us to look at the differences between the use cases.

Starting from a video on demand stream without advertisements, SSAI can easily stitch in relevant advertisements for the user that requested the video stream. Since it is a video on demand, the length of the manifest can change to accommodate any ad that is injected.

Using SSAI in live streams poses a slightly more difficult use case, in the sense that simply injecting an ad in between segments in a live stream would lengthen the manifest. As a result, for a live stream to be used with SSAI, ad breaks will need to be defined, so that the server knows where it is supposed to stitch in the ads. On top of that the length of ads and ad breaks will need to be matched, whereas for a VOD this is not necessary.

The final use case to look at is a recorded live stream that is made available as a video on demand. At first glance it might look like the ad injection process would be the same as the previous use case. However, matching the ad and ad break length is not a hard requirement, as the length of the manifest is not as strict in the VOD use case.

### THEOplayer and SSAI

There are a number of solutions in the market that provide SSAI and DAI services. As a market leader in video playback, THEOplayer has chosen to integrate with a number of different partners in the market of SSAI and DAI. These integrations provide a world-class solution with modern advertisement mechanics that allow you to monetize your content successfully.

---

# Support matrix

THEOplayer currently supports two ad implementations:

* an in-house advertisement implementation
* an implementation of Google IMA which is [DFP certified](https://support.google.com/admanager/answer/186110?hl=en)

A more in-depth advertisement guide can be found [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/advertisement/user-guide.md)

| Ad Standard             | Type                 | Supported through |
| ----------------------- | -------------------- | ----------------- |
| **VAST 2.0**            | Linear               | 1.2               |
|                         | Non-linear (Overlay) | 1.2               |
|                         | Companion            | 1.2               |
|                         | Wrapper              | 1.2               |
| **VAST 3.0**            | Linear               | 1.2               |
|                         | Non-linear (Overlay) | 1.2               |
|                         | Companion            | 1.2               |
|                         | Wrapper              | 1.2               |
|                         | Ad Pod               | 1.2               |
|                         | Skippable linear     | 1.2               |
| **VAST 4.0**            | Linear               | 1.2               |
|                         | Non-linear (Overlay) | 1.2               |
|                         | Companion            | 1.2               |
|                         | Wrapper              | 1.2               |
|                         | Ad Pod               | 1.2               |
|                         | Skippable linear     | 1.2               |
| **VPAID 2.0 (HTML+JS)** | Linear               | 2                 |
|                         | Non-linear (Overlay) | 2                 |
|                         | Companion            | N/A               |
|                         | Wrapper              | N/A               |
|                         | Ad Pod               | N/A               |
|                         | Skippable linear     | 2                 |
| **VMAP 1.0.1**          |                      | 2                 |

*Notes:*

* Support for VPAID 1.0 (Flash) was dropped by Google IMA in May 2018.
* THEOplayer also supports [SpotX](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/spotx.md).

---

# Content protection

Get ready to learn everything about content protection.

## [📄️Digital Rights Management (DRM) Systems](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/content-protection/drm-systems.md)

[Intellectual property theft has a huge economic impact. The digital media sector is one of its biggest victims with annual losses running into billions of dollars.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/content-protection/drm-systems.md)

## [📄️AES-128 Encryption](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/content-protection/aes-128-encryption.md)

[The Apple HTTP Live Streaming (HLS) specification uses AES-128 encryption to provide content protection. The Advanced Encryption Standard (AES) is a specification for the encryption of electronic data established by the U.S. National Institute of Standards and Technology. In case of HLS with AES-128, individual media segments get encrypted with a 16-octet key. Most modern streaming servers have simple configuration options for enabling AES-128 on HLS streams.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/content-protection/aes-128-encryption.md)

---

# Digital Rights Management (DRM) Systems

Intellectual property theft has a huge economic impact. The digital media sector is one of its biggest victims with annual losses running into billions of dollars.

Due to its nature and distribution, digital media is one of the most difficult intellectual properties to secure. This is especially the case when it comes to securing digital media without impacting the user experience.

In the online streaming market, security is achieved through Digital Rights Management (DRM) Systems. These technologies use a combination of Access Control schemes and encryption to make content transparently available to authorized users, while restricting access for everyone else.

## How does it work?

DRM in HTML5 streaming is achieved by encrypting content with AES-128 Encryption. Subsequently, decryption keys are distributed through a DRM specific licensing server. Which DRM system needs to be used depends on the device and browser that is being used.

The major advantage of DRM systems over standard AES-128 Encryption as it is available in HLS streaming is the ability to pass encrypted content to the browser. For more information on AES-128 Encryption in HLS, you can read our article [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/content-protection/aes-128-encryption.md).

## MPEG-DASH vs. HLS

HLS was one of the first and is currently most widely used HTML5 adaptive streaming protocol. The specifications for HLS are proprietary to Apple, but are published on the IETF website as the [Pantos HTTP Live Streaming Specification](https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis). The protocol is regularly updated and enhanced by Apple at a steady pace of a new update every six months.

MPEG-DASH on the other hand is backed by an industry forum with a large number of members in the online streaming market.

As you can see from the infographic above, when using a DRM system, encrypted content is passed to the browser. To be able to play the content, the browser needs to have access to a Content Decryption Module (CDM) that can handle the DRM system's security policies.

Currently, each device and browser combination provides support for just one DRM technology. Apple's FairPlay is the DRM technology to use on Apple's Safari browser and in iOS apps, while Microsoft PlayReady is available on Edge and Internet Explorer and Google's Widevine DRM is available in Firefox and Chromium based browsers such as Google Chrome, Opera and Vivaldi.

| Operating System      | Browser              | DRM Content Protection           |
| --------------------- | -------------------- | -------------------------------- |
| **Windows**           | Edge                 | MPEG-DASH + PlayReady (in HTML5) |
|                       | Internet Explorer 11 | MPEG-DASH + PlayReady (in HTML5) |
|                       | Chrome               | MPEG-DASH + Widevine (in HTML5)  |
|                       | Firefox              | MPEG-DASH + Widevine (in HTML5)  |
|                       | Opera                | MPEG-DASH + Widevine (in HTML5)  |
|                       | Vivaldi              | MPEG-DASH + Widevine (in HTML5)  |
| **OS X**              | Safari               | HLS + FairPlay (in HTML5)        |
|                       | Chrome               | MPEG-DASH + Widevine (in HTML5)  |
|                       | Firefox              | MPEG-DASH + Widevine (in HTML5)  |
|                       | Opera                | MPEG-DASH + Widevine (in HTML5)  |
|                       | Vivaldi              | MPEG-DASH + Widevine (in HTML5)  |
| **Linux**             | Chrome               | MPEG-DASH + Widevine (in HTML5)  |
|                       | Firefox              | MPEG-DASH + Widevine (in HTML5)  |
|                       | Opera                | MPEG-DASH + Widevine (in HTML5)  |
| **Android**           | Chrome for Android   | MPEG-DASH + Widevine (in HTML5)  |
| **Windows Phone 8.1** | Internet Explorer    | MPEG-DASH + PlayReady (in HTML5) |

## Common Encryption

This divided landscape of DRM technologies, browsers and platforms could potentially mean that a content provider needs a lot of resources available to provide full streaming support for all these platforms.

This is however not the case in practice. The MPEG Common Encryption standards defines metadata specific for the container formats in which content can be transported. That way, the player and browser know exactly which encryption schemes were used and how specific parts of the stream were encrypted. As long as the different DRM schemes adhere to these specifications, they can be used in combination with the same stream. This allows to reduce the resources required for the streaming provider. In the end, this currently comes down to setting up an HLS stream with FairPlay and an MPEG-DASH stream with PlayReady and Widevine.

## Licensing Servers

A crucial element in the DRM workflow is the DRM licensing server. These servers control the access that users have to your content. Providing various features to fine-tune license types (subscriptions, rentals, purchases, ...) or create user profiles with fine-grained access control (e.g.: premium customers with access to content in higher quality).

This creates two drawbacks at the moment.

* To be able to support your entire viewer base, most content providers will have to use more than one licensing server.
* Available features between different DRMs and licensing servers differs, making management of the user base more complex.

## Multi-DRM Solutions

Leveraging Common Encryption and providing support for all common DRM systems on the market, multi-DRM solutions allow a content provider to reach their entire user base with a single point-of-access for their management backend. Multi-DRM solutions make it very easy to protect content with studio-approved DRM.

THEOplayer has proven integrations with a number of vendors in the multi-DRM market, as well as Widevine, PlayReady and FairPlay individually.

---

# AES-128 Encryption

The Apple [HTTP Live Streaming (HLS)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/streaming/http-live-streaming.md) specification uses AES-128 encryption to provide content protection. The Advanced Encryption Standard (AES) is a specification for the encryption of electronic data established by the U.S. National Institute of Standards and Technology. In case of HLS with AES-128, individual media segments get encrypted with a 16-octet key. Most modern streaming servers have simple configuration options for enabling AES-128 on HLS streams.

## Content Protection in THEOplayer

THEOplayer supports decryption and playback of HLS streams with AES-128 content protection out of the box, without extra configuration in the player. In order to play AES-128 content protected streams, the decryption key and an optional initialization vector have to be provided in the manifest. When configured correctly, THEOplayer allows playback of AES-128 content protected streams on all supported devices in real time. It allows for the usage of a single key, or a rotating key.

In order to make sure THEOplayer can decrypt the stream, make sure the following information is correct in the manifest:

* If a decryption key is specified, it is relevant for all following media segments. This allows you to specify a key for each segment or one for the whole manifest
* The decryption key can be hosted externally (by referencing the key URL) or embedded in the manifest file (by key value)

## Cross Origin Resource Sharing (CORS)

Make sure CORS is enabled both on the **media segments** that have to be downloaded, decrypted and played as well as the **decryption key** if referenced externally in the manifest file.

## Examples

### THEOplayer example

There’s a demo of THEOplayer playing an AES-128 Content Protected stream at <https://demo.theoplayer.com/drm-aes-protection-128-encryption>.

### Video on Demand stream with multiple encryption keys

An example manifest of a 44-second long VOD stream protected with AES-128 content protection - each media segment has its own key.

```text
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-ALLOWCACHE:1
#EXT-X-KEY:METHOD=AES-128,URI="segment-00000.key"
#EXTINF:4.458667,
segment-00000.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00001.key"
#EXTINF:4.010000,
segment-00001.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00002.key"
#EXTINF:4.468667,
segment-00002.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00003.key"
#EXTINF:3.893000,
segment-00003.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00004.key"
#EXTINF:4.007333,
segment-00004.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00005.key"
#EXTINF:3.292667,
segment-00005.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00006.key"
#EXTINF:4.011667,
segment-00006.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00007.key"
#EXTINF:4.001000,
segment-00007.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00008.key"
#EXTINF:4.011667,
segment-00008.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00009.key"
#EXTINF:4.001000,
segment-00009.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00010.key"
#EXTINF:4.011667,
segment-00010.ts.enc
#EXT-X-TARGETDURATION:5
#EXT-X-ENDLIST
```

---

# Playback

This section will update you about the world of playback.

## [📄️What are chapter markers?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/what-are-chapter-markers.md)

[Dividing a video into separate parts helps your audience navigate through your content. While hovering the seek bar, THEOplayer's chapter markers and titles will help your users identify different parts of your content more easily. It also allows them to revisit their favorite parts of your videos.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/what-are-chapter-markers.md)

## [📄️What are the benefits of preview thumbnails?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/what-are-the-benefits-of-preview-thumbnails.md)

[Preview thumbnails improve the user experience by allowing the user to scan the video for specific content. They also have a business impact determined by the bandwidth optimization connected to users that can decide and quickly jump to the content they are interested in.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/what-are-the-benefits-of-preview-thumbnails.md)

## [📄️Frame Accurate Seeking](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/frame-accurate-seeking.md)

[This guide will explain how you can achieve frame-accurate seeking with THEOplayer. It will explain how to calculate the current frame of your player, how to seek to a specific frame and known limitations with this approach.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/frame-accurate-seeking.md)

## [📄️Program Date Time](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/program-date-time.md)

[THEOplayer has support for associating media segments with an absolute date and time. This can be useful when you want to synchronize video playback with displaying other relevant information about the video stream.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/program-date-time.md)

## [📄️Basic guide to Web Audio API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/basic-guide-web-audio-api.md)

[THEOplayer provides a Web Audio API, which allows you to do some quite nifty stuff with the player's audio output. If you are unfamiliar with the ideas behind Web Audio API, Mozilla has an excellent intro to the basic ideas you need to know about here. This guide will help you set up a demo just like the one we have in our Demo Zone.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/basic-guide-web-audio-api.md)

## [📄️Video Clipping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/video-clipping.md)

[THEOplayer supports playing only a selected part of a video-on-demand stream, rather than playing it from start to finish. This can be used for example to watch a single game-changing event from a sports match, highlight an important part of a long video presentation, or skip straight to the best part of a song's video clip.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/video-clipping.md)

## [💬Subtitles and closed captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/subtitles-and-closed-captions/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/subtitles-and-closed-captions/introduction.md)

---

# What are chapter markers?

Dividing a video into separate parts helps your audience navigate through your content. While hovering the seek bar, THEOplayer's chapter markers and titles will help your users identify different parts of your content more easily. It also allows them to revisit their favorite parts of your videos.

Chapter markers are cue points that allow you to divide your video content into segments called chapters. Chapters are used to convey metadata (e.g.: a title for each video segment) and to help the viewer seek to the desired portion of the video. Segmenting a long video is, therefore, a way to provide additional navigation to your content, improving the user experience.

Chapter markers are rendered on the timeline to visualize different segments of a video. Browsing chapters is possible by scanning through the chapter titles that are rendered on the UI while the user hovers the seek bar.

THEOplayer supports loading of chapter markers in WebVTT, SRT and other text track formats.

For the following example, we will focus on chapter markers in WebVTT format. WebVTT is a plain text format, part of the HTML5 standard, that's also used for providing subtitles and closed captions. These WebVTT files are quite straightforward and contain the chapter titles for specific time ranges in the video.

A sample WebVTT file could look like the following:

```text
WEBVTT

1
00:00:00.000 --> 00:01:42.000
Opening credits

2
00:01:42.000 --> 00:04:44.000
A dangerous quest

3
00:04:44.000 --> 00:05:50.000
The attack
```

## Resources

The following resources provide more information:

* [How-to guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/subtitles-and-closed-captions/chapter-markers.md)
* [Demo page](https://demo.theoplayer.com/chapters)

---

# What are the benefits of preview thumbnails?

Preview thumbnails improve the user experience by allowing the user to scan the video for specific content. They also have a business impact determined by the bandwidth optimization connected to users that can decide and quickly jump to the content they are interested in.

Appearing when hovering over the seek bar, preview thumbnails show a quick snapshot of the video content in a tooltip.

The most straightforward advantage of thumbnails is that they allow your viewers to scan the video for content, in case they are interested in a specific portion instead of the whole video, and then seek back or forward to the desired point.

Thumbnails have also a second advantage: it might benefit your bandwidth usage. As your viewers will more easily find the content they are looking for by seeking through your video, less content needs to be buffered. Although the advantage is limited to a bandwidth optimization of only a few percentages, with growing consumption every percentage saved on bandwidth results in significant cost savings.

## Resources

* [How to guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/preview-thumbnails.md)
* [Demo page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/examples/ui/preview-thumbnails.md)
* [Blog post by THEO](https://www.theoplayer.com/blog/in-stream-thumbnail-support-dvr-dash-streams)

---

# Frame Accurate Seeking

This guide will explain how you can achieve frame-accurate seeking with THEOplayer. It will explain how to calculate the current frame of your player, how to seek to a specific frame and known limitations with this approach.

## Calculate current frame

The current frame of the player can be calculated given the current time of the player, the time at which the first frame is located and the framerate. A possible implementation could be:

```js
function getCurrentFrame(player) {
  var activeQuality = player.videoTracks[0].activeQuality;
  return Math.round((player.currentTime - activeQuality.firstFrame) * activeQuality.frameRate - 0.5);
}
```

NOTE: This implementation depends on the first frame and frameRate of the active video quality. This information is not available until start of playback. When an active quality is chosen, an `activequalitychanged` event will be dispatched. The active quality is then accessible but might not have initialized values for the framerate and firstframe properties. When these properties are updated, an `update` event will be dispatched on the active quality. Using these two events, you can determine from when frame accurate seeking is possible.

## Seek to specific frame

Given a certain frame number, it is possible to seek to this frame specifically. To obtain this behavior, the time that corresponds with the frame should be calculated. A possible implementation could be:

```js
function seekToFrame(player, targetFrame) {
  var activeQuality = player.videoTracks[0].activeQuality;
  var time = (targetFrame + 0.5) / activeQuality.frameRate + activeQuality.firstFrame;
  player.currentTime = time;
}
```

## Example

The previous sections can be combined to obtain a wide variety of use cases. Suppose you desire to seek to 100 frames after the current one, this can easily be obtained with the following snippet:

```js
seekToFrame(player, getCurrentFrame(player) + 100);
```

## Known limitations

The approach mentioned above is easy and straightforward, however it does have some limitations.

* The first frame will be 0 if you start playback in the middle of a stream. This can change later if you seek back to the start of the stream. Leading to small inaccuracies.
* If an HLS stream contains discontinuities, the frame rate might not be 100% accurate.
* Some MPEG-DASH streams manifests don't contain the frame rate. In this case frame accurate seeking is not possible.
* For MPEG-DASH streams, the first frame is always reported as 0. If the first frame does not start at 0, then this approach won't work.

---

# Program Date Time

THEOplayer has support for associating media segments with an absolute date and time. This can be useful when you want to synchronize video playback with displaying other relevant information about the video stream.

THEOplayer enables this feature by making use of the `EXT-X-PROGRAM-DATE-TIME` information that gets embedded in the HLS manifest file.

## API and usage

Once the `EXT-X-PROGRAM-DATE-TIME` information is set in the HLS manifest, reading and setting the current program date time information on a THEOplayer instance is fairly straight forward. Start by [obtaining a reference to the THEOplayer instance](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md):

```js
THEOplayer.players[identifier];
```

On this THEOplayer instance, the following API attributes are available for controlling the current program data time:

| Attribute                | Description                                                                                                                                                                                                             |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currentProgramDateTime` | Sets or returns the current program date time reference. This message is calculated from the PROGRAM-DATE-TIME tag. Setting the property will seek to the playback position to the new program date time. (Date object) |

The value of the currentProgramDateTime gets updated with each `timeupdate` event thrown by the THEOplayer instance.

---

# Basic guide to Web Audio API

THEOplayer provides a [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API), which allows you to do some quite nifty stuff with the player's audio output. If you are unfamiliar with the ideas behind Web Audio API, Mozilla has an excellent intro to the basic ideas you need to know about [here](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API). This guide will help you set up a demo just like the one we have in our [Demo Zone](https://demo.theoplayer.com/web-audio-api).

This guide expects that you have a THEOplayer license. Be sure to have THEOplayer version 2.19.4 or higher.

## Getting started with THEOplayer

The first thing you need is a valid THEOplayer set-up. If you have no experience with setting up our player, we have an excellent [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md). In the following sections, we will assume that you have just created a THEOplayer instance and bound it to the variable 'player'.

## A very basic Web Audio graph

The very first step in working with Web Audio is to create an AudioContext. This can be achieved as follows:

```js
var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
```

Once you have an AudioContext, you can create an AudioNode which contains the player's audio output:

```js
var sourceNode = player.audio.createAudioSourceNode(audioCtx);
```

If we stop now, the result is that the player's audio will be piped into the graph, but will not be connected to any outputs, resulting in no sound output from your speakers/headphones. The next step to get it working again would be:

```js
sourceNode.connect(audioCtx.destination);
```

Which will result in the audio being output again.

## Playing with the audio gain

Of course, this is not a very useful use of the Web Audio API, since essentially we are doing nothing with the audio. A first thing we could do is play with the gain, i.e. manipulate the player volume by using the Web Audio API.

```js
var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
var sourceNode = player.audio.createAudioSourceNode(audioCtx);
var gainNode = audioCtx.createGain();
sourceNode.connect(gainNode);
gainNode.connect(audioCtx.destination);
```

This sets up a gain filter on top of the player audio output, which we can manipulate using the gainNode.gain.value property. An example would be that we could set up a callback which monitors mouse movement:

```js
var updatePage = function (e) {
  gainNode.gain.value = (screen.height - e.screenY) / screen.height;
};

document.onmousemove = updatePage;
```

The callback will be executed every time the mouse position is updated. The result will be that the gain will be adjusted to be equal to the ratio of the distance of the mouse pointer position from the bottom of the screen (in pixels) and the screen height. So the farther you move the mouse pointer down, the quieter the output of the video will become, and the opposite effect when you move the mouse pointer up.

Playing with stereo panning

Similarly, we can play with the stereo panning of the player audio output. This can be achieved by playing with the pan.value property of the StereoPanner node.

```js
var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
var sourceNode = player.audio.createAudioSourceNode(audioCtx);
var pannerNode = audioCtx.createStereoPanner();
sourceNode.connect(pannerNode);
pannerNode.connect(audioCtx.destination);

var updatePage = function (e) {
  pannerNode.pan.value = (2 * e.screenX) / screen.width - 1;
};

document.onmousemove = updatePage;
```

The result is that moving the pointer left and right changes the stereo panning of the player audio, with balanced audio at the exact middle of the screen, pan all the way to the left when the pointer's on the left edge, and pan all the way right when the pointer's on the right edge.

## Double audio trouble

We can also do both things at the same time. The way Web Audio works allows us to pipe the output of one node as input for another node (in most cases). This way, we can combine the two tricks we were doing before into one trick: modifying the volume by moving the mouse pointer up and down, and modifying the panning by moving the mouse left and right. This is achieved by the following code:

```js
var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
var sourceNode = player.audio.createAudioSourceNode(audioCtx);
var gainNode = audioCtx.createGain();
var pannerNode = audioCtx.createStereoPanner();
sourceNode.connect(pannerNode);
pannerNode.connect(gainNode);
gainNode.connect(audioCtx.destination);

var updatePage = function (e) {
  gainNode.gain.value = (screen.height - e.screenY) / screen.height;
  pannerNode.pan.value = (2 * e.screenX) / screen.width - 1;
};

document.onmousemove = updatePage;
```

## Bringing it all together

The next step we can take is to create a simple demo where we manipulate the audio of two players simultaneously. Assume that we have two players set up, bound to variables player1 and player2. Then we can set up exactly the same audio pipeline for both players, and reroute their audio to a single output.

```js
var sourceNode1 = player1.audio.createAudioSourceNode(audioCtx);
var gainNode1 = audioCtx.createGain();
var pannerNode1 = audioCtx.createStereoPanner();
sourceNode1.connect(pannerNode1);
pannerNode1.connect(gainNode1);
gainNode1.connect(audioCtx.destination);

var sourceNode2 = player2.audio.createAudioSourceNode(audioCtx);
var gainNode2 = audioCtx.createGain();
var pannerNode2 = audioCtx.createStereoPanner();
sourceNode2.connect(pannerNode2);
pannerNode2.connect(gainNode2);
gainNode2.connect(audioCtx.destination);
```

And at this point, we can do some more complex tricks. We can actually do the same thing as we did in the previous section, except that we can do the inverse for the second player's audio. That is, we can make moving the mouse pointer up decrease the volume for the second player, and we can invert the panning as well. This can be achieved with the following callback:

```js
var updatePage = function (e) {
  gainNode1.gain.value = (screen.height - e.screenY) / screen.height;
  pannerNode1.pan.value = (2 * e.screenX) / screen.width - 1;
  gainNode2.gain.value = e.screenY / screen.height;
  pannerNode2.pan.value = 1 - (2 * e.screenX) / screen.width;
};

document.onmousemove = updatePage;
```

Try it out!

---

# Video Clipping

THEOplayer supports playing only a selected part of a video-on-demand stream, rather than playing it from start to finish. This can be used for example to watch a single game-changing event from a sports match, highlight an important part of a long video presentation, or skip straight to the best part of a song's video clip.

## API

The start and end of the clipping window can be controlled through the [Clip API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/interfaces/Clip):

* `startTime` and `endTime`, expressed in seconds

These properties are optional, and you don't need to specify both `startTime` and `endTime`. For example, you can set just `startTime = 30` to have the video start at 30 seconds and play the rest of the video normally.

## Basic setup

The following example shows a video clipped to start at 30 seconds and end at 60 seconds.

```js
var player = ...;
player.source = {
    sources : [{
     src : '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8', // sets HLS source
     type : 'application/x-mpegurl' // sets type to HLS
    }],
  poster: '//cdn.theoplayer.com/video/big_buck_bunny/poster.jpg'
    };

player.clip.startTime = 30;
player.clip.endTime = 60;
```

---

# Introduction

THEOplayer supports rendering of subtitles and closed captions in both live and VOD content via the WebVTT format. You can supply subtitles and closed captions to THEOplayer in WebVTT format either externally via the `<track>` element or embedded inside the HLS stream.

## Embedded WebVTTs in the HLS playlist

Apart from specifying the WebVTT file in the track element, THEOplayer has support for WebVTT captions and subtitles embedded in the HLS m3u8 manifest file.

## Examples

### Sideloading WebVTT

[This page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/insert-subtitles.md) explains how you can insert WebVTT files.

### HTTP Live Streaming Manifest with embedded WebVTT subtitles

The following is a root HLS manifest with English, French, Spanish and Japanese subtitles. THEOplayer will handle and parse the required subtitles and synchronize them with the stream.

```text
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="English",DEFAULT=YES,AUTOSELECT=YES,FORCED=NO,LANGUAGE="en",CHARACTERISTICS="public.accessibility.transcribes-spoken-dialog, public.accessibility.describes-music-and-sound",URI="subtitles/eng/prog_index.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="Français",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="fr",CHARACTERISTICS="public.accessibility.transcribes-spoken-dialog, public.accessibility.describes-music-and-sound",URI="subtitles/fra/prog_index.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="Español",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="es",CHARACTERISTICS="public.accessibility.transcribes-spoken-dialog, public.accessibility.describes-music-and-sound",URI="subtitles/spa/prog_index.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="日本語",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="ja",CHARACTERISTICS="public.accessibility.transcribes-spoken-dialog, public.accessibility.describes-music-and-sound",URI="subtitles/jpn/prog_index.m3u8"
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=1860000,RESOLUTION=960x540,CODECS="avc1.42c01f,mp4a.40.2",SUBTITLES="subs"
gear1/prog_index.m3u8
```

## Demo

A demo on closed captions and subtitles can be found at <https://demo.theoplayer.com/closed-captions-subtitles>.

---

# Chapter markers

This guide explains to you how to set up THEOplayer to display chapter markers as a way of navigating videos. For more information regarding chapter markers, see Resources at the bottom of this page.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | N/A      | N/A            | N/A            |

## How to use the Up Next API

The Up Next API is a UI feature and shows video chapters when hovering the timeline.

### Prerequisites

This guide expects that you have a THEOplayer license. If you aren't using THEOplayer yet, you can start your free trial [here](https://portal.theoplayer.com). Be sure to have THEOplayer version 2.11 or higher.

### Adding a chapter markers track

In order to add chapter markers, you need to add a TextTrackDescription to your source that specifies a sideloaded text track of kind 'chapters'. THEOplayer supports loading of chapter markers in WebVTT, SRT and other text track formats.

To see an example of chapter markers in WebVTT formats, check out the article [What are chapter markers?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/what-are-chapter-markers.md).

### Code samples

The following code samples show how you can load THEOplayer with a video and sideloaded chapters track:

##### Web SDK

This example shows how to use chapters on your video. In this example, the source contains one `TextTrack` object, including a WebVTT file with video chapters.

```js
player.source = {
    ...
    textTracks : [{
        kind : 'chapters',
        src : 'https://cdn.theoplayer.com/video/sintel/chapters.vtt',
        srclang : 'en'
    }]
};
```

##### Android SDK

The following example shows how to use chapters on your video. In this example, the source contains one `TextTrack` object, including a WebVTT file with video chapters.

```java
sourceDescription(
    typedSource("https://cdn.theoplayer.com/video/sintel/nosubs.m3u8")
        .build()
)
.textTracks(
    new TextTrackDescription(
        src: "https://cdn.theoplayer.com/video/sintel/chapters.vtt",
        isDefault: true,
        TextTrackKind.CHAPTERS,
        srclang: "en",
        label: "Chapters")
)
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

A `TextTrackDescription` object has the following constructor:

```swift
TextTrackDescription(src: String,
                     srclang: String,
                     isDefault: Bool?,
                     kind: TextTrackKind?,
                     label: String?,
                     format: TextTrackFormat?)
```

The following example shows how to use chapters on your video. In this example, the source contains one `TextTrack` object, including a WebVTT file with video chapters.

Example code:

```swift
var textTrackDescription = TextTrackDescription(src: "https://cdn.theoplayer.com/video/sintel/chapters.vtt",
                                                srclang: "en",
                                                kind: .chapters)
}

var sourceDescription = SourceDescription(source: TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8",
                                                              type: "application/x-mpegurl"),
                                          textTracks: [textTrackDescription])
)
```

## Sample application

This demo illustrates the use of chapter markers in production: <https://demo.theoplayer.com/chapters>.

---

# Streaming

Always wanted to know more about streaming? This is your chance!

## [📄️HTTP Live Streaming](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/streaming/http-live-streaming.md)

[HTTP Live Streaming (also known as HLS) is a protocol implemented by Apple for streaming of audio and/or video content over HTTP. HLS has become over the last years a de facto standard for streaming content online. The main reasons for this are:](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/streaming/http-live-streaming.md)

## [📄️What are the recommended stream settings?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/streaming/what-are-the-recommended-stream-settings.md)

[There are many options to encode your streams. These encoding are often related to the content you are streaming. For example, fast motion movies like sporting events might require higher frame rates and more bandwidth compared to video of static landscape webcams.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/streaming/what-are-the-recommended-stream-settings.md)

---

# HTTP Live Streaming

HTTP Live Streaming (also known as HLS) is a protocol implemented by Apple for streaming of audio and/or video content over HTTP. HLS has become over the last years a de facto standard for streaming content online. The main reasons for this are:

* Adaptive streaming: HLS is able to dynamically adjust playback quality to match the device and network conditions such as the available speed of wired or wireless networks. This method of adaptive streaming allows the protocol to deliver better viewer experiences.
* Support for live, video-on-demand (VOD) and time-shifted (DVR) streaming.
* HTTP transactions: Because HLS only makes use of standard HTTP requests it is capable of traversing any firewall or proxy server that let through standard HTTP traffic. This also allows content to be delivered via widely available CDNs.

The HLS protocol also specifies a standard encryption mechanism with AES-128 for content protection, offers support for subtitles and closed captions, advertisements, ...

## THEOplayer and HLS: HTML5 vs. Flash

HTTP Live Streaming is currently the only protocol capable of streaming to Apples iPhone and iPad devices. However, besides Safari on Mac, most other browsers do not directly support playback of the HLS protocol. Other solutions for playback of HLS require primarily the installation of external browser plug-ins such as Flash, Silverlight or QuickTime.

With THEOplayer it is possible to stream live, VOD or DVR content with HLS directly to HTML5 platforms without the need to have any plug-ins or apps installed. THEOplayer offers support for HLS on almost all modern devices and browsers. This includes desktop devices running Windows, Linux and OS X, but also mobile devices running Android or Windows Phone.

## Supported platforms and browsers

THEOplayer offers support for HTTP Live Streaming on the following HTML5 platforms and browsers without the need to have any apps or plug-ins such as Flash, Silverlight or QuickTime installed:

| Platform              | Browser                |
| --------------------- | ---------------------- |
| **Windows**           | Internet Explorer (\*) |
|                       | Edge                   |
|                       | Chrome                 |
|                       | Firefox                |
|                       | Opera                  |
|                       | Vivaldi                |
| **OS X**              | Safari                 |
|                       | Chrome                 |
|                       | Firefox (\*\*)         |
|                       | Opera                  |
|                       | Vivaldi                |
| **Linux**             | Chrome                 |
|                       | Firefox (\*\*\*)       |
|                       | Opera                  |
| **Android**           | Chrome for Android     |
|                       | Firefox for Android    |
|                       | Opera                  |
| **iOS**               | Safari                 |
|                       | Chrome for iOS         |
|                       | Opera Mini             |
|                       | Opera Coast            |
| **Windows Phone 8.1** | Internet Explorer      |

(\*) = Version 10+

(\*\*) = As of Firefox 35+

(\*\*\*) = Requires gstreamer H.264 plug-in to be installed

---

# What are the recommended stream settings?

There are many options to encode your streams. These encoding are often related to the content you are streaming. For example, fast motion movies like sporting events might require higher frame rates and more bandwidth compared to video of static landscape webcams.

The video and audio codecs which are recommended are:

* Video: H.264 in Baseline Profile, Main Profile or High Profile. We advise against the usage of B-frames as this requires the entire chunk to be available before playback can start. It is important to take into account not all platforms will be able to play back the High profile. When setting up encoding profiles, keep in mind the platforms you intend to support.

* Audio: AAC-LC or HE-AAC. It is however important to use the same codec for all audio tracks. Using the same sampling frequency and bitrate is not required, but deviating from this might result in audible changes between streams. Also, when using HE-AAC it is highly recommended stating this in the stream's CODEC-attribute.

In regard to packaging, both raw-audio files (.aac, .mp3, ...) and MPEG Transport Streams can be used. For video, it is recommended to add a full IDR frame (keyframe) at the start of each video chunk.

The following configurations for adaptive streams have proven to work well on most content. Keep in mind some content can be displayed better when tweaking these parameters:

| # | Resolution | Video settings | Video bitrate | Frame rate | Audio settings | Audio bitrate | Audio sample rate |
| - | ---------- | -------------- | ------------- | ---------- | -------------- | ------------- | ----------------- |
| 1 | 480x270    | Baseline 3.0   | 500k          | 25 fps     | HE-AAC         | 128k          | 44.1kHz           |
| 2 | 640x360    | Baseline 3.0   | 900k          | 25 fps     | HE-AAC         | 128k          | 44.1kHz           |
| 3 | 960x540    | Baseline 3.1   | 1800k         | 25 fps     | HE-AAC         | 128k          | 44.1kHz           |
| 4 | 1280x720   | Main 3.1       | 4500k         | 25 fps     | HE-AAC         | 128k          | 44.1kHz           |
| 5 | 1920x1080  | High 4.0       | 8500k         | 25 fps     | HE-AAC         | 128k          | 44.1kHz           |

For manifest generation, we always advice to add at least the CODECS and RESOLUTION as they will speed up the adaptive bitrate capabilities of the player.

As a reference, Apple also provides a list of recommendations in regard to HLS: [TN2224](https://developer.apple.com/library/ios/technotes/tn2224/_index.html#//apple_ref/doc/uid/DTS40009745-CH1-SETTINGSFILES)

---

# Cross Origin Resource Sharing (CORS)

Cross-origin resource sharing (CORS) is a content protection mechanism that allows resources (manifests, video files or encryption keys) on server to be requested from a webpage on a different domain, subdomain or port than the one on from which the resources originated.

Such "cross-origin" requests would otherwise be forbidden by web browsers, per the same-origin security policy. CORS defines a way in which the browser and the server can interact and determine whether the browser is allowed to make these cross-origin request.

THEOplayer makes use of CORS for downloading manifests, video files and encryption keys from the streaming infrastructure. If CORS headers are not present on these server(s), THEOplayer assumes that it is not allowed to play the provided link. Make sure CORS headers are being served along with your resources in order to ensure smooth playback by THEOplayer.

## Content Delivery Network Support

From our experience and collaborations, the following CDNs have support for honoring or even adding CORS headers to requests they handle. If you are aware of a CDN that has support for CORS and is not on the list, make sure to contact us.

| Name       | Support |
| ---------- | ------- |
| Akamai     | Yes     |
| Anevia     | Yes     |
| Bitgravity | Yes     |
| Edgio      | Yes     |
| Highwinds  | Yes     |
| Internap   | Yes     |
| Level 3    | Yes     |
| Limelight  | Yes     |

## Enabling CORS on Wowza Media Server

Open the relevant (VOD, Live, ...) Wowza Application.xml configuration files.<br />Go to the `HTTPStreamer / Properties` container.<br />Add or make sure it contains:

```xml
<HTTPStreamer>
    <Properties>
        <Property>
            <Name>cupertinoUserHTTPHeaders</Name>
            <Value>Access-Control-Allow-Origin: *</Value>
        </Property>
    </Properties>
</HTTPStreamer>
```

This ensures that requested HLS files have the required CORS headers for domain \*. When in doubt, restart your Wowza Media Server instance to make sure the new configuration has been loaded.

## Enabling CORS on Adobe Flash Media Server

For Adobe Flash Media Server, CORS can be enabled by editing the .htaccess file that ships along with the installation. Add or make sure the file contains:

```xml
<IfModule mod_headers.c>
    Header set Access-Control-Allow-Origin *
</IfModule>
```

This ensures that requested HLS files have the required CORS header for domain \*. When in doubt, restart your Adobe Flash Media Server instance to make sure the new configuration has been loaded.

## Other Resources

Enabling CORS depends on the backend technology and on the used CDN. More information about CORS and how to enable it on a range of backend server technology can be found at <http://enable-cors.org/>

---

# Timed Metadata

*Timed metadata* describes a subset of a stream through data (bytes, text, image, ...), a start time and/or a stop time. For example, if you're watching a 60 seconds video, and if I would declare that an advertisement is playing in this video between 00:30 and 00:45, then I am declaring timed metadata because I'm referring to a subset of this video.

Timed metadata shouldn't be confused with *general metadata*. General metadata describes data related to your entire video content, like the title of the video, its total duration and its PG-rating. In this article we use timed metadata and metadata interchangeably, and consider general metadata out-of-scope.

![Metadata Flow](/pr-932/assets/images/metadata-flow-e0209c23fa4699e2528b581ecd591be1.png "Metadata Flow")

This article provides information on the different types of timed metadata and how you can leverage it in an application. The story is told in the reverse order: first we'll consider some use-cases (e.g. highlights), next we'll talk about the role of a video player versus the application, and finally we'll list the types of metadata (e.g. ID3) you can insert.

## Using Metadata

When using timed metadata, you are trying to achieve a [use-case](#use-cases) through a [technical implementation](#technical-implementation). In an ideal world, your video player provides an [out-of-the-box solution](#out-of-the-box-solutions) for your use-case, and you don't need to write and maintain a lot of code.

### Use-Cases

Timed metadata enables all kinds of use-cases in the field across various domains.

**Markers**

A popular use-case is to associate some data (text, image, ...) with a specific moment in time to mark a highlight.

![Metadata Markers](/pr-932/assets/images/metadata-goals-de17fe35188d311939191999ab0e74ca.png "Metadata Markers")

For example, in the screenshot above, we're leveraging metadata to highlight where a goal has been scored. If you click on the goal icon, you'll be taken to this moment in time in the video. You could of course expand this feature, and hovering the goal icon would toggle a tooltip which tells you who scored and what the new score is.

**Advertising**

Timed metadata can help you define the start and end of an advertisement. This information can be used to enhance the UI and UX. For example, at <https://cdn.theoplayer.com/demos/verizon-media/index.html>, the application leverages metadata to render markers in the scrub bar and to count down to the end of the ad break, and on top of that, if you try to seek over an ad break, the cursor snaps back to the ad break.

![Metadata Advertising](/pr-932/assets/images/metadata-advertising-15104844ee4b00b1cb4b5c40d44602b7.png "Metadata Advertising")

You can also leverage timed metadata "behind the scenes". For example, the timed metadata might contain info on the creative ID of the advertisement, and the URLs of its event trackers. An application could then use this information to communicate with an ad server or analytics server.

**Actions**

Timed metadata could also be used to initiate events and actions. For example, perhaps you want to overlay some text or image when you are at position 00:40. Or perhaps you want to disable seeking through the scrub bar for a defined period of time.

![Metadata Actions](/pr-932/assets/images/metadata-actions-01db1cadbab3af30116042c4a68cd07e.png "Metadata Actions")

The screenshot showcases a demo where a relevant hyperlink is being overlaid on top of the video within a specific time period. This hyperlink (and its start and stop time) was indicated through timed metadata.

**Other**

You can get very creative with timed metadata.

* You can use it to schedule client-side advertisements.
* You can use it to make certain areas of your video frame clickable at certain times, and clicking it will bring you to a web shop.
* ...

If you have a use-case where a certain behavior can be associated with a certain moment in time, you can probably tackle it through timed metadata.

### Technical Implementation

To programmatically extract your metadata and implement your use-case, you will always need to write custom application logic to some degree.

* You still need to write the custom code which calls the video player API.
* You might use a combination of external metadata and specification-compliant metadata, which requires you to write custom logic to tie things together.
* You probably want to tweak the UI and UX, so you'd also write some custom application code for that.

On top of this, you might need to leverage a video player API to extract your metadata, if you pass along your metadata in such a way it adheres to a certain streaming specification. More about this in the following sections.

### Out-of-the-box Solutions

To implement the use-cases listed above, applications developers have to write and maintain application code.

Sometimes, pre-integrations offered by the video player can take away some responsibilities of the application developer. For example, THEOplayer has a pre-integration with Verizon Media which allows developers to easily configure whether viewers can see ad break markers, whether viewers can skip over ad breaks, and much more.

At other times, there might be a recommended workflow and pre-integrated feature to achieve your use-case. For example, you can use [Chapter Markers](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/subtitles-and-closed-captions/chapter-markers.md) to highlight different chapters in a video.

THEOplayer also acts as the main contributor to [Enriched Media Streaming Solutions](https://www.theoplayer.com/emss) (EMSS). EMSS describes a standardized way to insert metadata and how a video player should handle and visualize this metadata. It might be interesting for you to [reach out to THEOplayer](https://servicedesk.theoplayer.com/) and ask if your use-case is supported by EMSS out-of-the-box.

## Extracting Metadata

Depending on how you insert the metadata, you have to use your video player API to extract the metadata, and/or write custom application logic.

* You use a **video player API** if you've inserted metadata which adheres to a streaming-related specification supported by the selected video player. For example, if you're using ID3 tags to pass along your metadata, you will use the designated video player API, if your video player supports the extraction of ID3 metadata.
* You write **custom application logic** if you're storing your metadata externally (e.g. on a CMS) or if you're using a metadata format which is not supported by your video player. It might be possible that you're using a video player which is pre-integrated with an external database, so you could perhaps still leverage your video player. (e.g. THEOplayer and Verizon Media.)

When you use THEOplayer as your video player API, you can use the `TextTracks API` to extract certain types of timed metadata like ID3, emsg, EXT-X-DATERANGE and EventStream, and APIs like `player.currentProgramDateTime` to determine the absolute date and time should you want to compare that with an external CMS.

## Inserting Metadata

Before we can unlock our use-cases, we need to create and insert our timed metadata. How you'll do this depends on your back-end set-up. (e.g. [Azure Media Services](https://docs.microsoft.com/en-us/azure/media-services/media-services-specifications-live-timed-metadata#2-timed-metadata-ingest) versus [Verizon Media Platform](https://docs.vdms.com/video/index.html#Develop/Live-Slicer-API.htm#timedmeta).)

Let's talk about the different types of timed metadata.

* [Segment Metadata](#segment-metadata)
* [Manifest Metadata](#manifest-metadata)
* [External Metadata](#external-metadata)
* [Timeline Metadata](#timeline-metadata)

It depends on your use-case and back-end which type you should pick, and which [considerations](#considerations) you should make. Perhaps your back-end doesn't allow you to insert any stream metadata (i.e. segment and manifest metadata), or perhaps you cannot use an external CMS.

### Segment Metadata

Segment metadata is contained within a segment. The industry also refers to segment metadata as in-band media timed events. There are two popular types of segment metadata:

1. ID3 is mostly contained .ts segments. This type of segment (`.ts`) is commonly used in HLS. ID3 can also occur in MPEG-DASH through a carriage over emsg.
2. emsg is mostly contained in CMAF media segments (e.g. `.mp4`). This type of segment is commonly used in MPEG-DASH, and in HLS when your HLS stream is using fragmented MP4 segments instead of .ts segments.

### Manifest Metadata

Manifest metadata is contained in the manifest of your streaming protocol. The industry also refers to manifest metadata as out-band media timed events. There are two popular types of manifest metadata:

1. EXT-X-DATERANGE is contained in the HLS (e.g. `.m3u8`) manifest.
2. EventStream is contained in the MPEG-DASH (e.g. `.mpd`) manifest.

### External Metadata

You can also store metadata externally, for example in a remote database or in a file.

**Database**

You can store metadata in an external database, for example by using a content management system (CMS). In this CMS, you will probably associate an IDs with asset, and associate certain types of data with these IDs.

Furthermore, your database should offer an API to your application, in order for your application developer to successfully query your database through an asset ID.

**File**

You can store metadata in files. For example, you could leverage [Chapter Markers](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/subtitles-and-closed-captions/chapter-markers.md) and thus use `.vtt` files. That being said, you would still need to know which asset should load which `.vtt` file, thus creating the need for an underlying CMS.

### Timeline Metadata

Your video player might be able to determine *timeline metadata* through your segments or manifests. Knowing your playhead position, video duration and/or absolute date may be necessary for you to implement your use-case.

For example, your HLS manifest might contain the `#PROGRAM-DATE-TIME` tag which defines the absolute date and time. This property allows your video player to calculate and expose the absolute date and time, which you can then leverage in your use-case.

Check with your back-end (vendor) whether if they expose the manifest metadata required for video players to calculate the absolute date and time. For HLS, this goes through the `#PROGRAM-DATE-TIME` tag. For MPEG-DASH, this goes through the `availabilityTimeOffset` attribute, and additionally through the `suggestedPresentationDelay` attribute.

### Considerations

We've listed some remarks below which could influence your decision in selecting a specific type of metadata.

* Manifest metadata can be useful because your video player will know about the metadata without requiring your video player to download individual segments. This is useful in use-cases where you want to mark highlights.
* Generating manifest metadata might increase the time it takes to load your manifest, either because the file size increases, or because of additional computations.
* Segment metadata must be downloaded by the video player before it can be extracted. What if the segment is skipped?
* Manifests and segments are not ideal suitors to carry large chunks of data. Perhaps you should put images elsewhere if you can load them on-demand?
* Not all back-end systems support all types of manifests metadata or segment metadata. You might not be able to implement your use-case on specific platforms. For example, what if your back-end does support EXT-X-DATERANGE through HLS, but not EventStream through MPEG-DASH? What if you initially didn't need to use MPEG-DASH, but suddenly (e.g. through new DRM requirements) have to us MPEG-DASH?
* Not all back-end systems (e.g. CMS) provide APIs which can be queried by an application.

## THEOplayer and Timed Metadata

THEOplayer is able to extract all applicable types of timed metadata across all supported platforms:

* EventStream through the `TextTracks` API.
* EXT-X-DATERANGE through the `TextTracks` API.
* ID3 through the `TextTracks` API.
* emsg through the `TextTracks` API.
* Timeline metadata through the `player.currentTime` and `player.currentProgramDateTime` API.

THEOplayer offers a number of pre-integrations to facilitate the implementation of relevant SSAI use-cases. Reach out to THEOplayer if your vendor is missing from the list below, because the list is incomplete.

* [Google DAI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/google-dai.md)
* [Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/ads/yospace.md)
* [Verizon Media](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/uplynk/introduction.md)

THEOplayer offers features which might implement your desired use-case out-of-the-box:

* [Chapter Markers](https://demo.theoplayer.com/chapters)
* [Preview Thumbnails](https://demo.theoplayer.com/preview-thumbnails)

## Resources

* THEOplayer

  * [How to track ID3 cues/tags?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/how-to-guides/web/text-tracks/track-id3-cues.md)
  * [TextTrack Types](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v11/api-reference/web/types/TextTrackType)
  * [ID3 Audio Player Demo](https://demo.theoplayer.com/audio-id3-metadata)

* External

  * [Requirements for Media Timed Events by the Media and Entertainment Interest Group](https://www.w3.org/TR/media-timed-events/)
  * [EXT-X-DATERANGE in the HLS specification](https://tools.ietf.org/html/draft-pantos-hls-rfc8216bis-07#section-4.4.5.1)
  * [Apple on ID3 in HLS](https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/Introduction/Introduction.html)
  * [MPEG-DASH Guidelines](https://dashif.org/guidelines/)

---

# Changelog for version 10.x

## 🚀 10.14.0 (2026/04/08)

### Web

#### ✨ Features

* Added support for ClearKey license URLs in MPEG-DASH streams using `<dashif:Laurl>`.
* Added the `TextTrack.captionChannel` property to retrieve the CEA-608 channel and/or CEA-708 service numbers of closed caption text tracks.

#### ⚡ Improvements

* Added various playback enhancements for the Sky Q STB.

#### 🐛 Issues

* Fixed an issue where `currentTime` did not advance linearly after playing an OptiView Ads ad.
* Fixed an issue where the `ended` event would not dispatch in the native Safari player.
* Fixed an issue where seeking on a webOS device could cause endless buffering.
* Fixed an issue where seeking to the end of stream in native Chrome would cause endless buffering.
* Fixed an issue where streams would sometimes not start on a Sky Q STB if autoplay was enabled and preload was set to `auto`.

### Android

#### ✨ Features

* Added the ability to use system-wide caption styles when showing subtitles. Use `THEOplayerConfig.Builder.useSystemCaptionStyle(Boolean)` to enable.

#### ⚡ Improvements

* When the player is in picture-in-picture mode, it can now be expanded to span the screen's width by double-tapping or pinching the PIP view.
* Added a default director URL for `MillicastSource`, so callers no longer need to explicitly provide the `apiUrl` parameter for standard Millicast connections.

#### 🐛 Issues

* Fixed an issue where seeking in a progressive source (e.g. an MP4 or MP3 file) could cause a fatal error when using certain servers or CDNs. The player will now always send an open-ended HTTP `Range` request header for such seeks.
* Fixed an issue where `AdBreak.timeOffset` would incorrectly return 0 for VMAP ads.

### Roku

#### ✨ Features

* Added the ability to use sideloaded text tracks for DASH and HLS.

#### 🐛 Issues

* Fixed an issue where the `aderror` event was not dispatched for malformed ads.

## 🚀 10.13.0 (2026/03/25)

### Web

#### ✨ Features

* Added support for `clearBufferWhenSettingTargetQuality` for DASH streams. This allows manual quality switches on DASH to occur immediately.

#### ⚡ Improvements

* Improved handling of unreachable `csai` ad break URLs by adding a timeout of 3s. If the download times out, the player will now throw an ad error and not play the ad break.

#### 🐛 Issues

* Fixed issue where very small periods in DASH manifests would cause the player to crash.
* Fixed an issue where no content steering was done for text track `AdaptationSet`s in a DASH stream.
* Fixed an issue in low performant Android WebViews where playback stalls were made worse by trying to recover too fast.
* Fixed an issue where the player would not use the cached segments of the streaming `csai` ad.
* Fixed an issue where the player would not preload the next `csai` ad breaks when it already preloaded another `csai` ad break.
* Fixed an issue where the player would not play the scheduled `csai` ad breaks when one of the ad breaks starting at the same time could not be fetched.
* Fixed an issue where OptiView Lens CMCD headers were being duplicated when playing a DVR-enabled OptiView Live source.
* Fixed an issue where the player would have an incorrect `currentProgramDateTime` during the second ad break when playing multiple consecutive ad breaks on an OptiView Ads stream.
* Fixed an issue where playback would end when transitioning between ad breaks in an OptiView Ads stream on iOS Safari.

### Android

#### ✨ Features

* Added `TextTrack.captionChannel` property to retrieve the CEA-608 channel and/or CEA-708 service numbers of closed caption text tracks.

#### 🐛 Issues

* Fixed an issue where all but the first CEA-608/CEA-708 channel was ignored.
* Fixed an issue where `AdBreak.getTimeOffset` would always return 0 for IMA ads.
* Fixed Nielsen ID3 tags not being reported during HESP playback.
* Fixed an issue where the `CHANGE` event was missing when an audio or video track was automatically enabled by the player (e.g. for a default track).
* Fixed an issue when selecting specific video qualities may lead player to choose a completely different, sometimes invalid, quality.

### iOS

#### ✨ Features

* Added `move` method to `CachingTask` to help move the cached stream assets to a specified directory URL.

#### 🐛 Issues

* Fixed an issue where the downloaded assets were not properly cleared from storage after calling `remove()` on an active `CachingTask`.
* Fixed an issue where `Ads.Omid` APIs would not apply correctly.

### Roku

#### ⚡ Improvements

* Updated Mux SDK to version 2.6.2 in the Roku Mux connector.

#### 🐛 Issues

* Fixed an issue where the `emptied` event was no longer being dispatched.

## 🚀 10.12.3 (2026/05/13)

### iOS

#### 🐛 Issues

* Fixed an issue where the player would crash during deinitialization.

## 🚀 10.12.2 (2026/04/15)

### iOS

#### 🐛 Issues

* Fixed an issue where OptiView Ads triggered through ID3 would fail to load correctly.

## 🚀 10.12.1 (2026/03/17)

### iOS

#### ⚡ Improvements

* Improved startup time for HESP-enabled OptiView Live streams on slower networks.

#### 🐛 Issues

* Fixed an issue where the first video frame would appear stuck for a while when starting playback of an HESP OptiView Live stream.

## 🚀 10.12.0 (2026/03/12)

### Web

#### ✨ Features

* Added default values for the `mpt` and `mpv` ad tag parameters for Google DAI.
* Added the `AdBreak.id` API.
* Added the experimental `View.player` property to the MultiView API to access the player underlying that view.

#### 🐛 Issues

* Fixed an issue where the player would not parse Nielsen cues when playing an OptiView Live stream.
* Fixed an issue where the player would not dispatch ad events when playing a Google DAI DASH live stream.
* Fixed an issue in HLS streams with TS segments where setting a `targetQuality` could sometimes cause an infinite loop.
* Fixed an issue where the player would still receive id3 events from the previous Google DAI source after resetting the source to a non Google DAI source.
* Fixed an issue where, when playing an OptiView Ads enabled stream, subsequent switches from ad to content would take longer and longer each time.
* Fixed an issue where the backdrop doesn't respect the aspect ratio when an ad is played with another aspect ratio in an OptiView Ads stream.
* Fixed an issue where the player would not pause the content in double box layout when clicking on an ad clickthrough for an OptiView Ads stream.
* Fixed an issue where OptiView Live streaming fallback functionality was not behaving as expected when playing HESP streams.
* Fixed an issue where the player would sometimes play a Google IMA preroll ad again when switching from ad to content while playing an OptiView Ads stream in native fullscreen or native PiP.
* Fixed an issue where the content would be paused when playing an OptiView Ads double-box advertisement.
* Fixed an issue where the double box layout would not dismiss when the VAST ad creative was unavailable for OptiView Ads.
* Fixed an issue where the player would sometimes not play the VAST ad unmuted on iOS Safari for an OptiView Ads stream.

#### ⚠ Known Limitations

* Using OptiView Ads with Picture-in-Picture (PiP) on Firefox is not supported. The default PiP button will be hidden in this scenario to discourage usage.

### Android

#### 💥 Breaking Changes

* `LatencyManager.currentLatency` now returns `null` when the player is not actively playing.

#### ✨ Features

* Added default values for the `mpt` and `mpv` ad tag parameters for Google DAI.
* Added the `AdBreak.idAsString` API.
* Added `Logger.HESP` logging tag for debugging HESP playback issues.

#### 👎 Deprecations

* Deprecated `MediaTailorAdAvail.id` in favor of `AdBreak.idAsString`.

### iOS

#### ✨ Features

* Added the `bytes` property to the `CachingTask` API which estimates the total amount of bytes that the task will download.
* Added the `AdBreak.id` API.
* Added default values for the `mpt` and `mpv` ad tag parameters for Google DAI.
* Added better error handling for HESP loading during startup with bad network conditions.

#### ⚡ Improvements

* Improved performance when accessing the `bytesCached` property of `CachingTask`.
* Improved error handling during ABR switches when playing OptiView Live sources.
* Improve error details (error code and message) when storage is low during a caching task. In a future major version, we will send better error metadata where possible: ie. send `THEOErrorCode.CACHE_SOURCE_ERROR` instead of `THEOErrorCode.NETWORK_ERROR`.

#### 🐛 Issues

* Fixed an issue where text tracks were not synced properly with Chromecast.
* Fixed an issue where HESP playout would occasionally fail to start or stall shortly after startup.
* Fixed an issue where a `CastError` was thrown during Chromecast connection establishment.
* Fixed an issue where retrying segment downloads for OptiView Live sources in bad network conditions would cause a fallback instead of continuing with the retried segment download.
* Fixed an issue where autoplay would not work when setting Millicast sources.
* Fixed an issue where setting `muted` on the player before setting a `MillicastSource` would be ignored.
* Fixed an issue where a quality switch on an OptiView Live HESP source caused unintended fallbacks.
* Fixed an issue where the ABR controller would switch up too fast after startup or after a previous quality switch.
* Fixed an issue during HESP playback where sometimes a `playing` event would be missing after resuming playback.

### Roku

#### ✨ Features

* Added the `AdBreak.id` API.
* Added default values for the `mpt` and `mpv` ad tag parameters for Google DAI.

#### ⚡ Improvements

* Updated the Mux SDK in the THEOMuxConnector to 2.6.0.

#### 🐛 Issues

* Fixed an issue in the THEOMuxConnector where the poster URL was not being recorded.

## 🚀 10.11.1 (2026/03/05)

### Web

#### 🐛 Issues

* Fixed an issue where versions 10.10.0 to 10.11.0 of the [`@theoplayer/basic-hls`](https://www.npmjs.com/package/@theoplayer/basic-hls) variant were published with an incorrect feature set.
* Fixed an issue where setting a second OptiView Live source in a row would sometimes cause the stream to fail to start.

## 🚀 10.11.0 (2026/02/25)

### Web

#### ⚡ Improvements

* Updated the OptiView Real-time streaming retry logic. Minimum backoff time for a OptiView Real-time source is now 1 second.
* OptiView Live streams played on mobile Safari will fallback faster when segments would be unavailable.
* Improved the resiliency for MPEG-DASH Content Steering when the steering server is unstable.

#### 🐛 Issues

* Fixed an issue where a PS4 WebMAF app could freeze when autoplay is enabled.
* Fixed an issue where autoplay on an ended stream could fire a play event before the sourcechange event, causing duplicate analytics sessions.
* Fixed an issues in MPEG-DASH Content Steering where successful manifest location downloads were reported in the `_DASH_pathway` search param.
* Fixed an issue where layer configuration passed in `MillicastSource.connectOptions` was not kept into account when switching layers after the source had been set.

#### ⚠ Known Limitations

* [`@theoplayer/basic-hls` version 10.11.0](https://www.npmjs.com/package/@theoplayer/basic-hls/v/10.11.0) was incorrectly published with the `basic-dash` feature set. If you're using this variant, please update to version 10.11.1 or higher for the correct feature set.

### Android

#### ⚡ Improvements

* Updated Media3 to [version 1.9.2](https://github.com/androidx/media/releases/tag/1.9.2).

#### 🐛 Issues

* Fixed an issue where ABR was not switching to a lower quality on very low bandwidth.
* Fixed an issue where `TextTrackStyle.fontSize` was not correctly applied to TTML subtitles with a `tts:fontSize` attribute.
* Fixed an issue where changing the `player.textTrackStyle` of one player could accidentally also change the text track style of other players.
* Fixed an issue where using Picture-in-Picture with `PiPType.ACTIVITY` on apps without `Theme.AppCompat` theme could crash the application.
* Fixed an issue where autoplay on an ended stream could fire a play event before the sourcechange event, causing duplicate analytics sessions.
* Updated the Millicast SDK to version 2.5.3, which adds a necessary consumer ProGuard rule to prevent a missing symbol crash from occurring when enabling minification.
* Fixed an issue where the backdrop would not be visible for OptiView Ads.
* Fixed an issue where the player would restart a VOD source when a scheduled interstitial would not have a resume time for OptiView Ads.
* Fixed an issue where the target latency was not applied for OptiView Live v1 channels.

### iOS

#### ✨ Features

* Added mobile layout support for OptiView Ads to override the ad layout when playing on iOS.

#### ⚡ Improvements

* Bumped the Millicast SDK version to 2.5.3

#### 🐛 Issues

* Fixed an issue where playing OptiView Live streams would cause an initial audio stutter.
* Fixed an issue in OptiView Ads where subsequent adbreak requests on monetized streams would fail after receiving an ad error.
* Fixed an issue where playing a VAST ad pod would only play the first ad for OptiView Ads.
* Fixed an issue in OptiView ads where the player would pause instead of playing the main content when an ad fails to load.
* Fixed an issue where the target latency was not applied for OptiView Live v1 channels.

### Roku

#### 👎 Deprecations

* Deprecated the `bitratechange` event in favor of the `activequalitychanged` event.

## 🚀 10.10.1 (2026/02/25)

### Web

#### 🐛 Issues

* Fixed an issue in HLS streams with TS segments where setting a `targetQuality` could sometimes cause an infinite loop.

#### ⚠ Known Limitations

* [`@theoplayer/basic-hls` version 10.10.1](https://www.npmjs.com/package/@theoplayer/basic-hls/v/10.10.1) was incorrectly published with the `basic-dash` feature set. If you're using this variant, please update to version 10.11.1 or higher for the correct feature set.

## 🚀 10.10.0 (2026/02/11)

### General

#### ✨ Features

* Added the `distributionloaded` event to the `player.theolive` API.

### Web

#### 🐛 Issues

* Fixed an issue where DRM-enabled HLS streams could error on rendition switches due to missing keys.
* Fixed an issue where quality changes during HLS playback could cause an error on low-end devices.
* Fixed an issue where an HESP source with a relative manifest URL could not be played.
* Fixed an issue on Safari where sometimes the `ended` event would not be fired when the player reaches the end of a stream.
* Fixed an issue where multiple subtitle cues within a segment would not display correctly.
* Fixed an issue where an HLS live stream would not start playback after a pre-roll ad on iOS Safari.
* Fixed an issue where the player would dispatch the `pause` and `ended` event in an incorrect order when seeking to the end of a stream.
* Fixed an issue where a track's `activeQuality` could be `undefined` on a playing event with OptiView Live streams.
* Fixed an issue where an OptiView Ads stream with disabled VPAID ads could cause the player to stop serving ads.
* Fixed an issue where playing ads using Google IMA and OptiView Ads together could cause the Google IMA ad to not play.
* Fixed an issue where an incorrect waiting event could be dispatched during an ad break to ad break transition on an OptiView Ads stream.

#### ⚠ Known Limitations

* [`@theoplayer/basic-hls` version 10.10.0](https://www.npmjs.com/package/@theoplayer/basic-hls/v/10.10.0) was incorrectly published with the `basic-dash` feature set. If you're using this variant, please update to version 10.11.1 or higher for the correct feature set.

### Android

#### ✨ Features

* Added `NetworkConfiguration` support for retries for OptiView Real-time streams.

#### 🐛 Issues

* Fixed an issue where the bandwidth caching parameter was ignored when caching DRM-protected streams.
* Fixed an issue during offline playback where playing a not fully downloaded content-protected (DRM) stream could cause a crash.
* Fixed an issue where a stall during playback on Chromecast for OptiView Live streams was not handled correctly.

### iOS

#### ✨ Features

* Made the `contentProtection` property public on the `EndpointAPI` protocol.

#### ⚡ Improvements

* Fixed an issue where recovery from network errors while playing and OptiView Live stream could take longer than expected due to platform limitations.

#### 🐛 Issues

* Fixed an issue where using `player.ads.schedule(adDescription:)` API did not trigger an ad playback.
* Fixed an issue where the recovery logic during playback of OptiView Live streams could check incorrect endpoints.
* Fixed an issue where playback was stuck when receiving an empty VAST for OptiView Ads.
* Fixed a bug that reset the `autoplay` flag whenever an integration was added to the player.
* Fixed an issue where OptiView Ads with VAST would not play in picture-in-picture mode.
* Fixed an issue where track selection was not respected during Chromecast.

## 🚀 10.9.1 (2026/04/15)

### Roku

#### 🐛 Issues

* Fixed an issue where the license expired text would show momentarily while renewing a license.

## 🚀 10.9.0 (2026/01/29)

### Web

#### ✨ Features

* Added `DashPlaybackConfiguration.contentSteering` to control whether content steering is enabled in MPEG-DASH streams.

#### ⚡ Improvements

* Added the ability to set a `RetryConfiguration` on a per-source basis.

#### 🐛 Issues

* Fixed an issue for OptiView Ads where the layout could be incorrect when playing a VAST ad in double box or L-shape layout.
* Fixed an issue where the player could not switch sources after a DAI stream errored.
* Fixed an issue where a WideVine L1 protected DASH stream would occasionally fail to play on certain Android FireTV models (AFTSS & AFTSSS).
* Fixed an issue where an `#EXT-X-KEY` with a base64 `data:` URI was sometimes parsed incorrectly from the HLS playlist.
* Fixed an issue where playback of subsequent OptiView Live sources would cause incorrect endpoints to be selected.
* Fixed an issue where MPEG-DASH content steering was sometimes not switching to a different `serviceLocation` when segment downloads failed.
* Fixed an issue where a PS4 WebMAF app could freeze upon requesting a media segment.
* Fixed an issue where the timecode text track would not be present on HESP streams that contain SEI timecodes.
* Fixed an issue in MPEG-DASH Content Steering where the `Retry-After` header was not respected when the server returned status code `429`.
* Fixed an issue where a crash would occur when playing an unsupported VPAID ad during native fullscreen on iOS Safari for an OptiView Ads stream.
* Fixed an issue in MPEG-DASH Content Steering where the `_DASH_throughput` and `_DASH_pathway` query parameters only supported a single pathway.
* Fixed an issue in MPEG-DASH Content Steering where sometimes a `serviceLocation` was chosen that was outside the provided `PATHWAY-PRIORITY` list.
* Fixed an issue in MPEG-DASH Content Steering where `_DASH_throughput` would report a pathway that was not actually downloaded.
* Fixed an issue in MPEG-DASH Content Steering where the default serviceLocation was not respected with `queryBeforeStart="false"`.
* Fixed an issue where the player would dispatch play/pause events incorrectly when playing ad break to ad break on an OptiView Ads stream.
* Fixed an issue for OptiView Ads where an IMA ad break could error when playing in iOS Safari native fullscreen.
* Fixed an issue for OptiView Ads where the audio could play multiple times for a VAST ad in Picture-in-Picture.
* Fixed an issue for OptiView Ads where the same ad could sometimes be scheduled multiple times.
* Fixed an issue where the `playing` event was sometimes not dispatched when resuming playback after fallback of an OptiView Live stream.

### Android

#### ⚡ Improvements

* The player will now automatically switch to a different quality when the current quality needs a DRM key that is missing in the DRM license. (Previously, the player would crash with a `MediaCodec.CryptoException` instead.)

#### 🐛 Issues

* Fixed an issue where `Ads.getCurrentAds()` could contain `null` ads.
* Fixed an issue where `player.duration` was incorrectly reported as `Infinity` for MP3 files when using the `HttpEngine` network stack.
* Fixed an issue where `TrackListChangeEvent` was not triggered when the subtitles were turned off.
* Fixed an issue where the subtitle state was not maintained between the sender and receiver apps.

#### ⚠ Known Limitations

* When the player's ABR strategy is set to `QUALITY`, but the highest quality is missing a required DRM key, the player will fall back to *any* other quality (not necessarily the highest quality with an available DRM key).

### iOS

#### ✨ Features

* Added a `LatencyManager` to control offset from live in HLS livestreams.

### Roku

#### ✨ Features

* Created the THEOMuxConnector to enable Mux analytics in the THEO Roku SDK.

#### 🐛 Issues

* Fixed an issue where Comscore and Adobe connectors could spawn multiple lingering task threads after multiple instantiations.
* Fixed an issue where VOD Google SSAI assets would not play.
* Fixed an issue where the stall detection would wrongly say a stream with no audio was stalled.

## 🚀 10.8.0 (2026/01/15)

### Web

#### ✨ Features

* Added support for MPEG-DASH content steering.
* Added support for `player.metrics.bufferedSegments` when playing an HLS stream.

#### ⚡ Improvements

* OptiView Streaming sources now support more `TypedSource` properties, such as `TypedSource.abr` and `TypedSource.crossOrigin`.

#### 🐛 Issues

* Fixed an issue where some HLS live streams could stall indefinitely when playing over an `#EXT-X-DISCONTINUITY` on Samsung Tizen devices.
* Fixed an issue where the `player.currentTime` could be incorrect after playing a CSAI ad with OptiView Ads.
* Fixed an issue where `player.metrics.currentBandwidthEstimate` was not set when playing an HESP stream.
* Fixed an issue where the player would sometimes jump back to the first ad of an OptiView Ads break instead of continuing with the second ad of that break.
* Fixed an issue for OptiView Ads where a VAST ad break in Safari native fullscreen could stutter.

### iOS

#### ✨ Features

* Added the `Network` API to `CachingTask` to help enable media playlist interception.

#### 🐛 Issues

* Fixed an issue where seeking to the live point could cause unnecessary buffering on OptiView Streaming (THEOlive) sources.

#### 👎 Deprecations

* Deprecated `DeveloperSettings` & `ManifestInterceptor` in favor of `NetworkAPI`. You can access the network API from `player.network` or `cachingTask.network`. For a comprehensive guide, please refer to [our documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/network/ios-hls-media-playlist-interceptor.md).

### Roku

#### 🐛 Issues

* Fixed an issue where OptiView Live streams would not properly fall back to a backup feed in case of a streaming error.
* Fixed an issue where OptiView Live streams could experience endless buffering without recovering.

## 🚀 10.7.2 (2026/01/27)

### Web

#### 🐛 Issues

* Fixed an issue where HLS playback on lower spec devices could error on a quality change between qualities with identical initializers.

## 🚀 10.7.1 (2026/01/26)

### Web

#### 🐛 Issues

* Fixed an issue where HLS playback on lower spec devices could error on a quality change briefly after starting playback.

## 🚀 10.7.0 (2025/12/16)

### Web

#### ✨ Features

* Added the ability to override connect options for OptiView Real-time streams.
* Added support for casting token-protected OptiView Live DVR streams to Chromecast.
* Added Millicast connect options to the OptiView Live discovery response.

#### ⚡ Improvements

* Added `RetryConfiguration` support for OptiView Real-time streams.
* Improved OptiView Real-time stream stability by automatically attempting to reconnect when errors occur mid-stream.

#### 🐛 Issues

* Fixed an issue where the player would not play from the live point when exiting an errored casting session.
* Fixed an issue for OptiView Ads where using a CSAI adbreak would not be handled properly when going into PiP or native fullscreen.
* Fixed a regression where `currentProgramDateTime` was no longer returning `null` for non-DVR streams without program date time information.
* Fixed an issue with consecutive ad breaks on an OptiView Ads Stream where the second ad break would not play if its duration was smaller than the preceding ad break.
* Fixed an issue where the player would play a CSAI ad break muted in a double box layout for an Optiview Ads stream.
* Fixed an issue where pausing OptiView Real-time streams would show a frozen frame on browsers on Android devices.
* Fixed an issue where CEA-608 captions from the content continued showing during an SSAI ad break.

### Android

#### ✨ Features

* Added `DRMConfiguration.multiSession` to enable multi-session support for streams that require different key requests for different qualities, or for streams that use key rotation.
* Added support for casting token-protected OptiView Live DVR streams to Chromecast.
* Added the ability to override connect options for OptiView Real-time streams.

#### 🐛 Issues

* Fixed an issue where subtitles could not be turned off while using Chromecast.
* Fixed an issue where failover of OptiView Live sources during HLS playback would return the player to non-HLS playback.

#### 👎 Deprecations

* Deprecated `THEOplayerConfig.isMultiSession`, use `DRMConfiguration.multiSession` instead.

### iOS

#### ✨ Features

* Added Chromecast support for DVR-enabled OptiView Live streams.
* Added the ability to override connect options for OptiView Real-time streams.

#### 🐛 Issues

* Fixed a regression where PiP was not retained when the `retainPresentationModeOnSourceChange` setting was enabled in the `PipConfiguration`.
* Fixed an issue where the auth token was not being passed correctly with DVR enabled OptiView Live streams.

### Roku

#### 🐛 Issues

* Fixed an issue where closed captions would be disabled when destroying the player while buffering.

## 🚀 10.6.1 (2025/12/02)

### Android

#### 🐛 Issues

* Fixed an issue where ID3 metadata from an HLS alternative audio rendition was not being parsed.

## 🚀 10.6.0 (2025/12/02)

### Web

#### ✨ Features

* Added a fallback to the Google DAI server-side beaconing stream when an OptiView Ads stream or OptiView Live stream with ads enabled is played via Airplay and a `daiAssetKey` is defined.
* Added support for personalized discovery call responses by configuring the `profile` property on an OptiView Live source.

#### ⚡ Improvements

* Added `ActiveQualityChanged` event for OptiView RealTime streams.
* Improved HLS segment selection on ABR changes to not download segments that had already been buffered in a different quality.
* The query parameters on the endpoint license acquisition URL of a DRM protected OptiView Live stream now take precedence over the query parameters that are defined in `contentProtection.queryParameters` or in the corresponding key system configuration.
* The `player.ads.dai` API is now undefined when there the DAI library is not loaded.

#### 🐛 Issues

* Fixed an issue where the player would always preload the Google DAI manifest when setting a Google DAI source.
* Fixed an issue where audio labels would not default to the language for HESP streams.
* Fixed an issue where the player could stall shortly on a discontinuity switch if the stream contained a small gap.
* Fixed issue where failover of OptiView Live sources during HLS playback would return the player to non-HLS playback.

#### 👎 Deprecations

* Deprecated `preloadPublications` on the THEOliveAPI. This will be removed in a future version.

### Android

#### ✨ Features

* Added Chromecast support for DVR-enabled OptiView Live streams.
* Added support for personalized discovery call responses by configuring the `profile` property on an OptiView Live source.

#### ⚡ Improvements

* The query parameters on the endpoint license acquisition URL of a DRM protected OptiView Live stream now take precedence over the query parameters that are defined in `contentProtection.queryParameters` or in the corresponding key system configuration.

#### 👎 Deprecations

* Deprecated `preloadPublications` on the THEOliveAPI. This will be removed in a future version.

### iOS

#### 💥 Breaking Changes

* THEOplayer SDK and all its integrations frameworks will now be built with Xcode 16 instead of 15. We expect no impact on applications since Apple enforced the policy of building with Xcode 16 to publish to the app store since April 24, 2025. Categorizing this as "Breaking change" since the compiler is bumped from Swift 5.10 to 6.0 with the Xcode version bump.

#### ✨ Features

* Added `targetQualities` property to `MediaTrack` API. Only supported for THEOlive.
* Added support for personalized discovery call responses by configuring the `profile` property on an OptiView Live source.
* Added a new experimental pipeline for chromecast, which enables new features, i.e. OptiView Live DVR. To use the new pipeline enable the `enableExperimentalPipeline` on the `CastConfiguration` object when creating the CastIntegration.

#### 🐛 Issues

* Fixed an issue where sometimes playback would pause after ending an OptiView Ads ad break on iPadOS.
* Fixed an issue where `player.buffered` would return the same as `player.seekable`.
* Fixed an issue where adding multiple drm query parameters would not work as expected.

#### 👎 Deprecations

* Deprecated `preloadPublications` on the THEOliveAPI. This will be removed in a future version.

### Roku

#### ✨ Features

* Added support for personalized discovery call responses by configuring the `profile` property on an OptiView Live source.

## 🚀 10.5.1 (2025/11/26)

### Web

#### 🐛 Issues

* Fixed an issue where seeking back in an OptiView Live stream with a DVR window on iOS Safari would make the player jump to the live edge instead of the desired time.
* Fixed an issue where the current time was incorrect when returning from casting a DVR asset.

### Android

#### 🐛 Issues

* Removed dependency on `kotlinx-datetime` library from OptiView Ads integration.

## 🚀 10.5.0 (2025/11/19)

### Web

#### ✨ Features

* Added support for targeted bitrate limiting on OptiView Live streams with OptiView Ads enabled.
* Added the `fallback` event to the `theoads` API to indicate when the player falls back to Google DAI when OptiView Ads is not supported or blocked.
* Added support for configuring query parameters that are common to multiple key system configurations. The parameters defined in `contentProtection.queryParameters` will be merged with any query parameters that are explicitly defined on a key system configuration, whereby the latter takes precedence.

#### ⚡ Improvements

* Updated OptiView Ads overlays to be available during the whole DVR range instead of being removed after it was shown.
* Improved the transition from content to ad on Safari for OptiView Ads.

#### 🐛 Issues

* Fixed an issue for OptiView Ads where the player could get stuck when scheduling multiple ad breaks close together.
* Fixed an issue where the player would not dispatch an `AdErrorEvent` when failing to play an ad during an OptiView Ads stream.
* Fixed a regression since 10.2.0 for OptiView Ads where a scheduled overlay could be rendered multiple times.
* Fixed an issue where incorrect events were dispatched when transitioning between content and ads for OptiView Ads.
* Fixed an issue where the cues of text tracks would never be pruned on HLS live streams.
* Fixed an issue where the player would sometimes throw a media decode error on PS5 when playing multi period DASH streams.
* Fixed an issue where the Uplynk UI was creating unnecessary DOM nodes on every `timeupdate` event, even when the Uplynk integration was not in use.
* Fixed an issue for OptiView Ads where L-Shape ad breaks on iOS would show the content instead of the backdrop.
* Fixed an issue where multiple quartile events could be dispatched when playing a Google DAI source.

### Android

#### ✨ Features

* Added `TheoAdsFallbackEvent` to indicate when the player falls back to Google DAI when OptiView Ads is not supported or blocked.
* Added support for targeted bitrate limiting on OptiView Live streams with OptiView Ads enabled.
* Added support for configuring query parameters that are common to multiple key system configurations. The parameters defined in `contentProtection.queryParameters` will be merged with any query parameters that are explicitly defined on a key system configuration, whereby the latter takes precedence.

#### 🐛 Issues

* Fixed an issue where an `InterstitialError` event was incorrectly emitted for single ads in OptiView Ads.
* Fixed an issue where the `AddAdBreakEvent` would fire multiple times while playing a Google DAI ad.
* Fixed an issue on OptiView Ads where an additional `AdBegin` event was fired in case of an ad error or very short slate.
* Fixed an issue where the player did not always fall back to a configured Google DAI stream when it encounters a problem with the main OptiView Ads stream.
* Fixed an issue where `AdBreakBeginEvent` was fired at the start of each ad in a Google IMA/DAI ad break, instead of just once at the start of the ad break.
* Fixed an issue where a crash could occur due to locally stored bandwidth properties being null unexpectedly.
* Fixed an issue where `AdBreak.timeOffset` was always 0 for midrolls in a Google DAI livestream.
* Fixed an issue where different midroll ad breaks in a Google DAI livestream were incorrectly represented by the same `AdBreak` object.
* Fixed an issue where ad breaks in a Google DAI livestream were never removed from the Ads API after being played.
* Fixed an issue where OptiView Live was incorrectly skipping endpoints with higher priority.

### iOS

#### ✨ Features

* Added `THEOadsFallbackEvent` to indicate when the player falls back to Google DAI when OptiView Ads is not supported or blocked.
* Added support for targeted bitrate limiting on OptiView Live streams with OptiView Ads enabled.
* Added support for configuring query parameters that are common to multiple key system configurations. The parameters defined in `DRMConfiguration.queryParameters` will be merged with any query parameters that are explicitly defined on a key system configuration, whereby the latter takes precedence.

#### 🐛 Issues

* Fixed an issue where both SGAI and SSAI were enabled for a SSAI only OptiView Live stream.
* Fixed an issue where accessing the ad break of a Google DAI ad would crash the application.
* Fixed an issue where playback would not automatically start when setting a new source and calling play after connecting to AirPlay.
* Fixed an issue where the picture-in-picture presentation mode was not preserved when an adbreak ended for OptiView Ads.
* Fixed an issue where player controls and API's were broken when returning from a Chromecast session.

#### 👎 Deprecations

* Deprecated the `adBreak` property of the `Ad` protocol, this property can still be used but will become optional with the next major version.

### Chromecast

#### 🐛 Issues

* Fixed an issue where a mismatch could occur between enabled tracks on the sender versus the receiver, causing unexpected behaviour in audio track selection.

### Chromecast CAF

#### ✨ Features

* Added support for configuring query parameters that are common to multiple key system configurations.

### Roku

#### ✨ Features

* Added support for targeted bitrate limiting on OptiView Live streams with OptiView Ads enabled.

#### 🐛 Issues

* Fixed an issue where a crash could occur due to event listener cleanup during player destruction.

## 🚀 10.4.1 (2025/11/14)

### Web

#### ⚡ Improvements

* Improved the performance of CEA-608 parsing and rendering.

#### 🐛 Issues

* Fixed an issue where the cues of text tracks would never be pruned on HLS live streams.

### iOS

#### 🐛 Issues

* Fixed an issue where accessing the ad break of a Google DAI ad would crash the application.
* Fixed an issue where unmuting the player on iOS failed after muting a stream that contains an IMA ad.
* Fixed an issue where after loading a VMAP ad, additional VMAP ads would fail to load and playout would be broken.

#### 👎 Deprecations

* Deprecated the `adBreak` property of the `Ad` protocol, this property can continue to be used but will become optional with the next major version.

## 🚀 10.4.0 (2025/11/05)

### General

#### ⚡ Improvements

* Aligned the position of the video during an OptiView Ads L-Shape interstitial to be consistent across SDKs.

### Web

#### ✨ Features

* Added DVR switching for OptiView Live streams so users can seek between live sources (HESP/Millicast) and DVR sources (HLS) on DVR-enabled channels.
* Added support for DAI SSAI as the primary stream for OptiView Live streaming.

#### 🐛 Issues

* Fixed an issue for OptiView Ads where Overlay interstitials did not update during an ad break interstitial where the content continues playing.
* Fixed an issue for OptiView Ads where the backdrop set in the source description wasn't used correctly.

### Android

#### 🐛 Issues

* Fixed a regression where `TheoLiveSource.headers` were no longer being passed to the discovery call for OptiView Live streams.
* Fixed an issue where sideloaded WebVTT chapters and thumbnails tracks could not both be enabled at the same time.
* Fixed an issue where ad configuration parameters were not being applied to DAI OptiView Live streams.
* Fixed an issue where the player could crash while loading an OptiView Live channel that is unavailable.

#### 👎 Deprecations

* Deprecated `TheoAdsErrorEvent`. Use the `AdErrorEvent` on the Ads API instead.

### iOS

#### ✨ Features

* Added a convenience initializer to `GoogleDAITypedSource` to enable DRM with Google DAI.
* Added support for DAI SSAI as the primary stream for OptiView Live streaming.

#### 🐛 Issues

* Fixed an issue for OptiView Ads where the backdrop set in the source description wasn't used correctly.

### Roku

#### 🐛 Issues

* Added protection against unexpected values being set for `encoding_type` on Conviva metadata.

## 🚀 10.3.0 (2025/10/23)

### Web

#### 🐛 Issues

* Fixed an issue where embedded subtitles could sometimes disappear after repeatedly seeking back and forth in an MPEG-DASH stream.
* Fixed an issue where disconnecting a headset while playing an MPEG-DASH live stream causes the player to stall.

### Android

#### ✨ Features

* Added SSAI fallback through DAI for OptiView Ads if an ad blocker prevents ads from playing when using OptiView Streaming.
* Added support for `adTagParameters` on `gamProperties` for overlays and `backdropURIGamProperties` for backdrops on OptiView Ads.
* Added support for DAI SSAI as a primary stream source via OptiView Streaming.

#### 🐛 Issues

* Fixed an issue where EZDRM ClearKey license responses were not correctly handled and could result in playback failures.
* Fixed an issue where HLS streams with gzip compressed playlists failed to play on older Android devices when the HTTP response contains a `Content-Encoding` header with a lowercased header name (i.e. `content-encoding`).
* Fixed an issue where OptiView Ads playback was broken after the application comes back from background.

#### 👎 Deprecations

* Deprecated `THEOplayerConfig.getPipConfiguration()`, use `THEOplayerConfig.getPip()` instead.
* Deprecated `THEOplayerConfig.getNetworkConfiguration()`, use `THEOplayerConfig.getNetwork()` instead.
* Deprecated `THEOplayerConfig.getTHEOLiveConfiguration()`, use `THEOplayerConfig.getTheoLive()` instead.
* Deprecated `THEOplayerConfig.castConfiguration`, use `THEOplayerConfig.cast` instead.
* Deprecated `THEOplayerConfig.googleImaConfiguration`, use `THEOplayerConfig.googleIma` instead.

### iOS

#### ✨ Features

* Added support for `adTagParameters` on `gamProperties` for overlays and `backdropURIGamProperties` for backdrops on OptiView Ads.
* Added `averageBandwidth` property to the `Quality` API.
* Added `activeQuality` property to the `MediaTrack` API.
* Deprecated `activeQualityBandwidth` property from the `MediaTrack` API, use `activeQuality` instead. To access the bandwidth value, use the `bandwidth` property of `activeQuality`.
* Added `Ad.isSlate` API to indicate whether the ad is slate or not.
* Added `playerMetrics` API with `droppedVideoFrames` property.
* Added `renderedFramerate` property to `Metrics` API.

#### ⚡ Improvements

* Improved ad break reporting for Google DAI by already creating an ad break when not all information is known from Google DAI. We will dispatch `UpdateAdBreakEvent` when more information is known from Google DAI.

#### 🐛 Issues

* Fixed an issue where the `player.muted` and `player.volume` properties were not preserved when setting a source when OptiView Ads is included.
* Fixed an issue where `player.ads.playing` would return `false` when joining a Google DAI stream in the middle of an advertisement.
* Fixed an issue where the `TextTrackListEventTypes.REMOVE_TRACK` event listener would not trigger.
* Fixed an issue where the `aspectRatio` and `videoRect` APIs were not working correctly.

#### 👎 Deprecations

* Deprecated return type of `metrics` API. The type will change from `Any?` to `Metrics` with the next major version.

### Roku

#### ✨ Features

* Added Google DAI support for OptiView Live streams.

## 🚀 10.2.2 (2025/10/14)

### Web

#### 🐛 Issues

* Fixed an issue where the `TheoAdDescription.adTagParameters` were not used for interstitial with the `LSHAPE_CONTENT` layout on OptiView Ads.

### Android

#### 🐛 Issues

* Fixed an issue where the second and following Ad breaks were not playing for Optiview Ads.

### iOS

#### 🐛 Issues

* Fixed an issue where playing OptiView Streaming (THEOlive) streams could crash due to a race condition.

## 🚀 10.2.1 (2025/10/13)

### Web

#### 🐛 Issues

* Fixed an issue where the `TheoAdDescription.adTagParameters` were not used for backdrops on OptiView Ads.
* Fixed a regression in Chromium-based browsers on macOS where HESP streams would sometimes fail to start.
* Fixed an issue where the player would not play any ads after the player has errored on playing a l-shape content interstitial during native fullscreen for an OptiView Ads stream.
* Fixed an issue where the player would show a black screen during native fullscreen when the player already errored on playing a l-shape content interstitial during native fullscreen and then switched back to inline playback for an OptiView Ads stream.

### iOS

#### 🐛 Issues

* Fixed an issue where the `THEOAdDescription.adTagParameters` were not used for backdrops on OptiView Ads.

## 🚀 10.2.0 (2025/10/09)

### Web

#### ✨ Features

* Added VAST ad support for Smart TVs with OptiView Ads.
* Added support for adding an authToken to OptiView live streams when casting (given that a cast receiver is used with the [useShakaForHls](https://developers.google.com/cast/docs/web_receiver/shaka_migration/) flag set).
* The [`@theoplayer/extended` package on npm](https://www.npmjs.com/package/@theoplayer/extended) now also supports OptiView Live streams.
* Added support for adTagParameters on gamProperties for Overlays and backdropURIGamProperties for backdrops on OptiView Ads.

#### ⚡ Improvements

* Improved the startup times on certain smart TVs.
* Improved the ABR to select higher resolutions on smart TVs whose `devicePixelRatio` is greater than `1.0`.
* `InterceptableRequest.redirect()` and `.respondWith()` now accept iterables and native `Headers` objects when replacing the request/response headers.

#### 🐛 Issues

* Fixed an issue where a VAST ad could be invisible in combination with OptiView Ads.
* Fixed an issue where the player shows a black screen when it tries to load an l-shape content interstitial during native fullscreen or native picture-in-picture for an OptiView Ads stream.
* Fixed an issue where the player would sometimes show a black screen instead of video while falling back on OptiView live streams.
* Fixed an issue where the seekable was not correct on certain HLS streams.
* Fixed an issue where the player would sometimes stall for a very short time on Safari right after starting playback on some HLS streams.
* Fixed an issue where old devices without WebAssembly support could not transmux MPEG-TS segments.
* Fixed an issue where an HLS live stream with a very short DVR window would stall immediately on iOS Safari when initiating playback.
* Fixed an issue where the player would not switch back to the content after playing back to back l-shape content interstitials on an OptiView Ads stream.
* Fixed an issue where OptiView live streams didn't start playing after a channel transitioned from offline to playing.

### Android

#### ✨ Features

* Added `Player.poster` API for displaying the poster image in the player.
* Added `CurrentSourceChangeEvent`, which is dispatched when the player receives a new source from `SourceDescripion.sources`.
* Allow overriding `adTagParameters` for an individual overlay interstitial.

#### ⚡ Improvements

* Increased the maximum number of HTTP 3xx redirects to follow to 20, to align with standard browser behavior.

#### 🐛 Issues

* Setting `SourceDescription.poster` will now display the poster both in the player UI and when casting to Chromecast.
* Fixed an issue where live streams on Chromecast would start at the beginning of their DVR window if the current time was unknown.
* Fixed an issue for OptiView Ads where the current time was incorrect during an ad break with `DOUBLE` layout.
* Fixed an issue where the `Content-Length` header was not available in `HTTPResponse.headers` when using the new default network stack. Note that when the response body is compressed, this header will still be unavailable.
* Fixed an occasional `InterruptedException` being logged to Logcat while playing an LL-HLS stream when the `Logger.Media3` logs are enabled.
* Fixed an issue where SVG overlay images might not be visible in an OptiView Ads stream.
* Fixed a regression where `Player.readyState` was not updated while playing a Google IMA ad.
* Fixed an issue where the selected text track would get disabled on multi-period DASH streams if the codec of the text tracks between the periods were different.

### iOS

#### ✨ Features

* Added `Quality` and `VideoQuality` protocols. `ActiveQualityChangedEvent` now has a `quality` property.
* Added the option to override `adTagParameters` for an individual overlay interstitial.
* Added the CurrentSourceChangeEvent, which is dispatched when the player starts playing a new source.
* Added `qualities` property to `MediaTrack`.
* The player now dispatches `EncryptedEvent` and `ContentProtectionSuccessEvent` during a DRM flow. `EncryptedEvent` indicates the start of a DRM flow, while `ContentProtectionSuccessEvent` indicates the success. Use `PlayerEventTypes.ENCRYPTED` and `PlayerEventTypes.CONTENT_PROTECTION_SUCCESS` to listen to these events.

#### ⚡ Improvements

* Reporting errors for THEOlive (OptiView Streaming) streams via CMCD headers

#### 🐛 Issues

* Fixed an issue where THEOlive (OptiView Streaming) would not start playing after coming back from the background.
* Fixed an issue where deinitializing the player during the loading of a THEOlive (OptiView Streaming) stream would cause a crash.

### Chromecast CAF

#### ✨ Features

* Added support for adTagParameters on gamProperties for Overlays on OptiView Ads.

### Roku

#### ⚡ Improvements

* Improved URL rewriting in `THEOM3u8TagRemover` so relative URLs that begin with a slash are handled correctly.

## 🚀 10.1.1 (2025/09/30)

### Web

#### 🐛 Issues

* Fixed an issue where the player would run into a fatal decode error on HESP streams on Chromium based browsers without hardware acceleration.

## 🚀 10.1.0 (2025/09/24)

### General

#### ✨ Features

* Added the `adTagParameters` property to OptiView `Interstitial`.

### Web

#### ⚡ Improvements

* Added `segmenterror` and `manifesterror` events to be used for detecting offline status.

#### 🐛 Issues

* Fixed an issue where live streams on Chromecast would start at the beginning of their DVR window if the current time was unknown.
* Fixed an issue where the player would sometimes stall about 10 seconds after stream start on devices with slow appends on certain HLS streams.

#### 👎 Deprecations

* Deprecated the `segmentnotfound`, `manifestnotfound`, `offline`, and `online` events. Use the new `manifesterror` and `segmenterror` events to detect offline status. Use the `manifestupdate` event to detect online status.

### Android

#### ✨ Features

* Added Google IMA VAST support to OptiView Ads.

#### 🐛 Issues

* Fixed an issue where the player would crash with an `IllegalArgumentException` when playing certain low-latency HLS streams.
* Fixed an issue where the player could stall indefinitely when enabling an embedded subtitle track containing no actual subtitles.
* Fixed an issue where some HLS streams with gzip compressed playlists failed to play when using the new default network stack on Android 14 or higher (or when using Cronet).

### iOS

#### 🐛 Issues

* Fixed an issue where the quartile events would not be dispatched for OptiView Ads.
* Fixed an issue where the player would not switch to the next adbreak when playing adbreak to adbreak with OptiView Ads.
* Fixed an issue that causes a crash after listening to `TextTrackListEventTypes.ADD_TRACK` and loading webVTT subtitles in an app that is compiled using Swift 6 and is using `@preconcurrency import THEOplayerSDK`.
* Fixed an issue where Dolby OptiView Streams would crash in a rare race condition during playback.

### Roku

#### ✨ Features

* Made the Conviva connector able take a new player instance after the previous instance was destroyed.
* Added `encoding_type` to custom metadata sent to Conviva.

## 🚀 10.0.1 (2025/09/16)

### Android

#### 🐛 Issues

* Fixed an issue where HTTP POST requests made by the player (such as DRM license requests) failed to be sent using the new default network stack on Android 14 or higher (or when using Cronet).
* Fixed `MillicastSource` referencing types from the native Millicast SDK that were not correctly included in the published API of the Millicast integration.

## 🚀 10.0.0 (2025/09/12)

### Announcing THEOplayer 10.0

We are happy to announce the tenth major version of THEOplayer, releasing all the improvements and developments our team has achieved since version 9.0.

THEOplayer 10.0 includes **some breaking changes per SDK**. Please review them carefully in the respective changelog for your SDK.

* On Android, THEOplayer now always uses the Media3 pipeline for all playback, bringing bug fixes, performance improvements and increased stability across a wider range of devices! Check out our [Media3 guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/android/media3/getting-started.md) for more information.

* The Android SDK will now automatically use modern network stacks with HTTP/2 and HTTP/3 support when available, optimizing media delivery to your viewers.

* [OptiView Ads](https://optiview.dolby.com/docs/theoads/) is now fully supported on iOS. This brings our personalized advertising solution to all major platforms.

For more info on navigating our breaking changes, take a look at our migration guides for [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/migrating-to-theoplayer-10.md), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/migrating-to-theoplayer-10.md), [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/ios/migrating-to-theoplayer-10.md) and [React Native](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/migrating-to-react-native-theoplayer-10.md).

### Web

#### 💥 Breaking Changes

* Removed `AdBreakEvent.ad`, use `AdBreakEvent.adBreak` instead.
* Removed `THEOplayerAdDescription` type, use `CsaiAdDescription` instead.
* Removed `WebVTTRegion.identifier`, use `WebVTTRegion.id` instead.
* Removed `PlayerConfiguration.vr`. This configuration was already ignored since version 9.0.0, because the player always uses WebXR.
  * Note that `SourceDescription.vr` is not affected, and is still required to play a virtual reality source.
* Removed `MediaTailorSource.adParams`, use `MediaTailorSource.adsParams` instead.
* Removed `PlayerConfiguration.verizonMedia`, use `PlayerConfiguration.uplynk` instead.
* Removed `'verizon-media'` as a valid source integration ID for Uplynk sources (previously Verizon Media). Uplynk sources must now have their `integration` set to `'uplynk'` instead.
* Removed THEOlive publication events (`publicationloadstart`, `publicationloaded` and `publicationoffline`), use the equivalent distribution events instead (`distributionloadstart`, `endpointloaded` and `distributionoffline` respectively).
* Enabled `GoogleImaConfiguration.useAdUiElementForSsai` by default, allowing Google DAI to show additional ad UI elements on top of the player if needed (such as a skip button for skippable ads).
* Removed support for THEOlive sources using `source.integration = 'theolive'`. THEOlive sources must now have their `type` set to `'theolive'` instead.

### Android

#### 💥 Breaking Changes

* Updated `minSdk` to API 23 ("Marshmallow"). This aligns with [other Android Jetpack libraries requiring API 23 as of June 2025](https://developer.android.com/jetpack/androidx/versions#version-table).
* Updated to target Kotlin 2.0 language level, to [align with AndroidX Core 1.17.0](https://developer.android.com/jetpack/androidx/releases/core#core_and_core-ktx_version_117_2). This requires Kotlin Gradle Plugin 2.0.0 or newer.
* Removed support for the legacy playback pipeline (using `TypedSource.playbackPipeline = PlaybackPipeline.LEGACY`). The player will now always use the Media3 playback pipeline.
  * This brings down the `.aar` size of the Core SDK from \~33 MB to \~2 MB (excluding dependencies).
* Removed support for the legacy cache backend (using `CachingParameters.storageType = CacheStorageType.LEGACY`). All caching tasks will now use the Media3 cache backend, and any previously cached streams that used the legacy backend will need to be re-downloaded.
* Changed `NetworkConfiguration.useHttpEngine` to be enabled by default, allowing the player to switch to a modern network stack with HTTP/2 and HTTP/3 support if available.
* Removed unused `GoogleDaiConfiguration.format`.
* Removed `MediaTailorSource.adParams`, use `MediaTailorSource.adsParams` instead.
* Removed the `DashPlaybackConfiguration.ignoreAvailabilityWindow()` method, use the `.ignoreAvailabilityWindow` property instead.
* Removed `KeySystemConfiguration.isUseCredentials`, use `KeySystemConfiguration.useCredentials` instead.
* Removed `ConaxDRMConfiguration.Builder.fairPlay()`, use `ConaxDRMConfiguration.Builder.fairplay()` instead.
* Removed THEOlive publication events (`PublicationLoadStartEvent`, `PublicationLoadedEvent` and `PublicationOfflineEvent`), use the equivalent distribution events instead (`DistributionLoadStartEvent`, `EndpointLoadedEvent` and `DistributionOfflineEvent` respectively).
* Removed `THEOplayerGlobal.playbackSettings`. This API is not supported in the Media3 playback pipeline.
* Removed `SourceChangeEvent.playbackPipeline`.

#### 🐛 Issues

* Fixed an issue where a THEOlive stream would not start playing on `play()` after first playing a different stream.

### iOS

#### 💥 Breaking Changes

* In an effort to align with the changes made by Apple regarding the [App Store publishing policy](https://developer.apple.com/news/upcoming-requirements/?id=02212025a), starting from THEOplayer 10.0 we will distribute our SDK builds using Xcode 16. Effectively, this means that developing a client application using THEOplayer iOS/tvOS SDK will require a minimum version of Xcode 16.
* Removed the flag `useLegacyPlaybackEngine` in the initializer of `THEOliveConfiguration`.
* Removed THEOlive publication events (`PublicationLoadStartEvent`, `PublicationLoadedEvent` and `PublicationOfflineEvent`), use the equivalent distribution events instead (`DistributionLoadStartEvent`, `EndpointLoadedEvent` and `DistributionOfflineEvent` respectively).
* Removed the `destroy` method. Instead, destroy the player by removing its reference `self.player = nil`.
* Removed the `set` from the subscript of the `TextTrackList` API. The `TextTrackList` is a read-only list.

#### ✨ Features

* Added Google IMA VAST support to OptiView Ads.

### Roku

#### 💥 Breaking Changes

* Removed the `getHeader` method from the Network API in favor of the new `getHeaders` method.

#### ⚡ Improvements

* Added the `getHeaders` method to Network API.
* Added protection against race conditions during destruction of the player.

---

# THEOplayer

Dolby OptiView Player (formerly THEOplayer) is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [OptiView Player Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/web.md)

[For desktop and mobile web browsers, and smart TVs like Tizen and WebOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/web.md)

## [OptiView Player Android SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/android.md)

[For smartphones, tablets and Android TVs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/android.md)

## [OptiView Player iOS & tvOS SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/ios.md)

[For iPhone, iPad and Apple TV](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/ios.md)

## [OptiView Player React Native SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/react-native.md)

[For cross-platform apps targeting web, Android and iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/react-native.md)

## [OptiView Player Flutter SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/flutter.md)

[For cross-platform apps targeting web, Android and iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/flutter.md)

## [OptiView Player Chromecast SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/chromecast.md)

[For custom Chromecast receiver apps](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/chromecast.md)

## [OptiView Player Roku SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/roku.md)

[For Roku smart TVs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/roku.md)

---

# Connectors for THEOplayer

## [Connectors for Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web.md)

## [Connectors for Android SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android.md)

## [Connectors for iOS & tvOS SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios.md)

## [react-nativeConnectors for React Native SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/react-native.md)

## [Connectors for Roku](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/roku.md)

---

# THEOPlayer 🤝 Sideloaded TextTracks Samples

We provide source code of two sample applications that illustrate how to use the connector with different package managers:

* [Sample using **Cocoapods**](https://github.com/THEOplayer/iOS-Connector/blob/-/Code/Sideloaded-TextTracks-Examples/Cocoapod) (requires Cocoapods installation through terminal)

---

# @theoplayer/react-native-analytics-npaw

## 1.1.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.0.0

* Initial release.

---

# THEOplayer React Native NPAW Connector

An [NPAW](https://npaw.com/) (formerly YOUBORA) analytics connector for `@theoplayer/react-native`.

This connector is JavaScript-only and works across iOS, Android and web through the unified `react-native-theoplayer` player, using only the `npaw-plugin-react-native` plugin — no native iOS/Android modules are required.

> **Note:** This connector targets **NPAW v7+** (it depends on `npaw-plugin-react-native` `^7.3.x`).

## Installation

```sh
npm install @theoplayer/react-native-analytics-npaw
```

## Usage

### Configuring the connector

Create the connector with the `useNpaw` hook, passing a config object and initializing it once the `THEOplayer` instance is ready:

```tsx
import { LogLevel, useNpaw } from '@theoplayer/react-native-analytics-npaw';

const App = () => {
  const [npaw, initNpaw] = useNpaw({
    accountCode: 'your-account-code',
    analytics: {
      'content.title': 'Big Buck Bunny',
      'content.isLive': false,
      // Free-form custom metadata shown in the NPAW "Metadata" panel:
      'content.metadata': { genre: 'animation' },
    },
    // Optional NpawPlugin options (host, sessionRecovery, ...):
    plugin: { sessionRecovery: 'auto' },
    logLevel: LogLevel.DEBUG,
  });

  const onPlayerReady = (player: THEOplayer) => {
    initNpaw(player);
  };

  return <THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady} />;
};
```

Alternatively, construct the `NpawConnector` class directly:

```ts
import { NpawConnector } from '@theoplayer/react-native-analytics-npaw';

const connector = new NpawConnector(player, { accountCode: 'your-account-code' });
```

### Configuration

| Field         | Description                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `accountCode` | Your NPAW account code. **Required.**                                                                     |
| `analytics`   | Per-video analytics options, e.g. `content.title`, `content.isLive`, `content.metadata`, `user.name`, ... |
| `plugin`      | `NpawPlugin` options such as `host`, `sessionRecovery` and `balancerAnalyticsEnabled`.                    |
| `logLevel`    | Initial `LogLevel`.                                                                                       |

### What is tracked automatically

Once initialized, the connector registers a video adapter (and an ads adapter) against the player and reports playback automatically:

* Playback events (start, join, pause/resume, buffering, seeking, end and errors) mapped from the unified `PlayerEventType` events.
* Playhead, duration and live/VOD state, resource, rendition and bitrate.
* The active subtitle/caption track language (`getSubtitles`) and audio language (`getVideoLanguage`).
* Ads: ad breaks, ad start/join/stop, quartiles, skip, click and errors, with ad position (`pre`/`mid`/`post`), duration and skippability.

### Updating options at runtime

```ts
// Update options for the current video (e.g. late-arriving metadata):
npaw.current?.setVideoOptions({ 'content.title': 'New Title' });

// Update global analytics options:
npaw.current?.setAnalyticsOptions({ 'user.name': 'viewer-1' });

// Change the log level:
npaw.current?.setLogLevel(LogLevel.SILENT);

// Stop analytics and close all sessions:
npaw.current?.destroy();
```

See the [NPAW integration documentation](https://documentation.npaw.com/integration-docs/docs/) for the full set of plugin and analytics options.

---

# @theoplayer/adscript-connector-web

## 0.5.0

### ✨ Features

* Added support for THEOplayer v11.

## 0.4.0

### ✨ Features

* Added support for THEOplayer version 10.

## 0.3.0

### ✨ Features

* Added support for THEOplayer `9.0`.

## 0.2.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 0.1.0

### ✨ Features

* Initial release.

---

# adscript-connector-web

The AdScript connector provides an AdScript integration for THEOplayer.

## Installation

Install using your favorite package manager for Node (such as `npm` or `yarn`):

### npm

```bash
npm install @theoplayer/adscript-connector-web
```

### yarn

```bash
yarn add @theoplayer/adscript-connector-web
```

## Usage

First you need to add the AdScript connector to your app :

* Add as a regular script

```html

<script type="text/javascript" src="path/to/adscript-connector.umd.js"></script>
<script type="text/javascript">
    const player = new THEOplayer.Player(element, configuration);

    // Define your configuration for the connector:
    const adScriptConfig = {
        implementationId: 'your-implementation-id', // Replace this!
        metadata: {
            "assetid": "v0000001",
            "type": "content",
            "program": "Big Buck Bunny",
            "title": "Sample Video - Extended",
            "length": "635",
            "crossId": "000 111 22222",
            "livestream": "0",
            "channelId": "",
            "attribute": "1"
        },
        debug: false
    }

    // Create the AdScriptConnector:
    const adScriptConnector = new THEOplayerAdScriptConnector.AdScriptConnector(player, adScriptConfig);
</script>
```

* Add as an ES2015 module

```html

<script type="module">
    import {AdScriptConnector} from "@theoplayer/adscript-connector-web";

    const player = new THEOplayer.Player(element, configuration);

    // Define your configuration for the connector:
    const adScriptConfig = {
        implementationId: 'your-implementation-id', // Replace this!
        metadata: {
            "assetid": "v0000001",
            "type": "content",
            "program": "Big Buck Bunny",
            "title": "Sample Video - Extended",
            "length": "635",
            "crossId": "000 111 22222",
            "livestream": "0",
            "channelId": "",
            "attribute": "1"
        },
        debug: false
    }

    // Create the AdScriptConnector:
    const adScriptConnector = new AdScriptConnector(player, adScriptConfig);
</script>
```

## Updating metadata

If the metadata has changed during playback, you can update it with:

```javascript
adScriptConnector.updateMetadata(newMetadata);
```

## Updating userInfo

If the user info has changed during playback, you can update it with:

```javascript
adScriptConnector.updateUser(i12n);
```

---

# @theoplayer/gemius-connector-web

## 0.5.0

### ✨ Features

* Added support for THEOplayer v11.

## 0.4.0

### ✨ Features

* Added support for THEOplayer version 10.

## 0.3.0

### ✨ Features

* Added support for THEOplayer `9.0`.

## 0.2.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 0.1.0

### ✨ Features

* Initial release.

---

# gemius-connector-web

The Gemius connector provides a Gemius integration for THEOplayer.

## Installation

```sh
npm install @theoplayer/gemius-connector-web
```

Load the gplayer.js library from Gemius. There are two options to to this: either you do it synchronously:

```html

<script type="text/javascript" src="https://PREFIX.hit.gemius.pl/gplayer.js"></script>
```

... or asynchronously

```html
<script type="text/javascript">
<!--//--><![CDATA[//><!--
function gemius_pending(i) { window[i] = window[i] || function() {var x = window[i+'_pdata']
= window[i+'_pdata'] || []; x[x.length]=arguments;};};
gemius_pending('gemius_init');
function gemius_player_pending(obj,fun) {obj[fun] = obj[fun] || function() {var x =
window['gemius_player_data'] = window['gemius_player_data'] || [];
x[x.length]=[this,fun,arguments];};};
gemius_player_pending(window,"GemiusPlayer");
gemius_player_pending(GemiusPlayer.prototype,"newProgram");
gemius_player_pending(GemiusPlayer.prototype,"newAd");
gemius_player_pending(GemiusPlayer.prototype,"adEvent");
gemius_player_pending(GemiusPlayer.prototype,"programEvent");
gemius_player_pending(GemiusPlayer.prototype,"setVideoObject");
(function(d,t) {try {var gt=d.createElement(t),s=d.getElementsByTagName(t)[0],
l='http'+((location.protocol=='https:')?'s':''); gt.setAttribute('async','async');
gt.setAttribute('defer','defer'); gt.src=l+'://PREFIX.hit.gemius.pl/gplayer.js';
s.parentNode.insertBefore(gt,s);} catch (e) {}})(document,'script');
//--><!]]>
```

Make sure you replace `PREFIX` with the short string of letters specifying the Gemius collecting server. It can be acquired as a part of the tracking code from gemiusPrism interface ( in Settings / Scripts / Streaming Players) or from your local Gemius Tech Support Department.

## Usage

First you need to add the Gemius connector to your app :

* Add as a regular script

```html

<script type="text/javascript" src="path/to/gemius-connector.umd.js"></script>
<script type="text/javascript">
    const player = new THEOplayer.Player(element, configuration);

    // Define your configuration for the connector:
    const gemiusConfig = {
        gemiusID: '<your-publisher-id>',
        debug: true
    };

    // Define the initial program parameters:
    const programParameters = {
        "programID": "000001",
        "programName": "Big Buck Bunny (DASH)",
        "programDuration": 635,
        "programType": "video",
        "transmissionType": 1,
        "programGenre": 4,
        "series": "Test Content",
        "programSeason": "season 1",
        "programProducer": "Blender",
        "customAttributes": {
            "intCategory": "Comedy",
            "intType": "vod",
            "intStatus": "public"
        }
    };

    // Create the GemiusConnector:
    const gemiusConnector = new THEOplayerGemiusConnector.GemiusConnector(player, gemiusConfig, programParameters);
</script>
```

* Add as an ES2015 module

```html
<script type="module">
    import {GemiusConnector} from "path/to/gemius-connector.esm.js";

    const player = new THEOplayer.Player(element, configuration);

    // Define your configuration for the connector:
    const gemiusConfig = {
        gemiusID: '<your-publisher-id>',
        debug: true
    };

    // Define the initial program parameters:
    const programParameters = {
        "programID": "000001",
        "programName": "Big Buck Bunny (DASH)",
        "programDuration": 635,
        "programType": "video",
        "transmissionType": 1,
        "programGenre": 4,
        "series": "Test Content",
        "programSeason": "season 1",
        "programProducer": "Blender",
        "customAttributes": {
            "intCategory": "Comedy",
            "intType": "vod",
            "intStatus": "public"
        }
    };

    // Create the GemiusConnector:
    const gemiusConnector = new GemiusConnector(player, gemiusConfig, programParameters);
</script>
```

## Updating program parameters

If the program parameters changed during playback, you can update it with:

```javascript
const newProgramParameters = { ... };

gemiusConnector.update(newProgramParameters);
```

---

# Getting started

THEOplayer offers a rich portfolio of video SDKs for many platforms and frameworks across desktop, mobile and TV devices.

Our dedicated guides help you get started right away.

## [OptiView Player Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)

## [OptiView Player Android SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/getting-started.md)

## [OptiView Player iOS & tvOS SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/ios/getting-started.md)

## [OptiView Player React Native SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/getting-started.md)

## [OptiView Player Flutter SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/flutter/getting-started.md)

## [OptiView Player Chromecast SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/chromecast/getting-started.md)

## [OptiView Player Roku SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/roku/getting-started.md)

---

# How to update an SDK?

This how-to guide describes how to update to a new version of the THEOplayer SDK.

> **Info**
>
> Starting from version 2.79.0, you can make use of License as a Configuration with Web SDK. This allows you to reuse the same library when changing your license. It also allows you to make use of our NPM modules instead of using the THEOplayer zip-file. In order to use this functionality, there is a change needed in your THEOplayer integration. You can read more about this [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/license/introduction.md).
>
> We highly recommend using this new license system due to all the advantages it brings.

## Update Web SDK

Typically, next to using [NPM](https://www.npmjs.com/package/theoplayer), you grab a CDN URL or a downloadable ZIP file through <https://portal.theoplayer.com>, which gives you access to URLs like those below:

* LIBRARY LOCATION: `https://cdn.myth.theoplayer.com/<license-key>/`
* CDN ZIP LINK: `https://portal.theoplayer.com/download/<license-key>?h=1643658986`

Configuring THEOplayer through the "Library Location" implies a **cloud-hosted (CDN)** approach. Downloading (and configuring) the ZIP (or using NPM) implies a **self-hosted (ZIP file)** approach.

![Update SDK](/pr-932/assets/images/update-sdk-5f00e7ff6ef3854952cf07f2562b3d08.png)

### 1. Cloud-hosted

Every SDK that you create through <https://portal.theoplayer.com/> is associated with a specific THEOplayer version. When you're doing cloud hosting, you're referring to THEOplayer's CDN to load the relevant JavaScript, for example `https://cdn.myth.theoplayer.com/<license-key>/THEOplayer.js`.

To change the version of this specific SDK, you use the GUI at <https://portal.theoplayer.com/> to change it to a different version, and hit the "Save & Publish" button after making your changes. Your video player will now automatically start using this new version, but do note that the CDN and browser cache might still be referring to your older version for a little while. If your browser is still not fetching the new JS libraries, try hard refreshing your browser tab first.

![Save \&amp; Publish](/pr-932/assets/images/republish-7d7f211f07d91032ae93414a82528d26.png)

### 2. Self-hosted

Alternatively, you could extract the included zip file and host the library yourself.

In this case, the steps are similar to the above steps, but you'll also need to re-download your SDK to grab the new THEOplayer files.

When you extract the ZIP file, you will see the following 'helper files':

* `theoplayer.d.js`
* `theoplayer.e.js`
* `theoplayer.p.js`

It is **important** these files are placed in the **same directory as the core library (THEOplayer.js)**.

**It is crucial to also update the libraryLocation as seen in the snippet above. Not doing will result in playback failure.**

If you're using [THEOplayer through NPM](https://www.npmjs.com/package/theoplayer), then you should replace the version of THEOplayer in your `package.json` file.

## Other SDKs

Updating the iOS SDK, Android SDK and Roku SDK is similar with regards to self-hosting the SDK.

The iOS SDK and Android SDK can also be managed through CocoaPods and Maven respectively. You cannot "cloud host" these SDKs.

---

# SDKs

Dolby OptiView Player provides a set of feature-rich video player software development kits (SDKs). Each SDK targets a set of platforms. For example, a developer integrates the iOS SDK in their iOS app.

Dolby OptiView Player offers the following SDKs. (Clicking the link takes you to the respective getting started guide.)

* HTML5/Tizen/webOS SDK

  * [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md) targets (desktop and mobile) browsers, HTML5-based smart TVs, progressive web apps, and other HTML5-based platforms.
  * [webOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/webos/getting-started.md) targets LG webOS apps.
  * [Tizen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/tizen/getting-started.md) targets Samsung Tizen apps.
  * [Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/chromecast/getting-started.md) targets (custom) Chromecast apps.

* Android/Android TV/Fire TV SDK

  * [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/getting-started.md) targets Android, Android TV and Fire TV apps. It may also be used for other Android-based platforms.

* iOS/tvOS SDK

  * [iOS & tvOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/ios/getting-started.md) targets iOS, iPadOS and tvOS apps.

* Roku SDK

  * [Roku](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/roku/getting-started.md) targets Roku apps.

* [React Native](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/getting-started.md) SDK

Want to update an existing SDK instead? Follow [this guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/how-to-update-a-sdk.md).

> **Looking for the Legacy Android and iOS/tvOS (4.12.x) SDKs?**
>
> The legacy Android and iOS/tvOS SDKs (version 4.12.x) are no longer supported. However, you can still access their documentation through the following links:
>
> * Android/Android TV/Fire TV Legacy (4.12.x) SDK
>
>   * [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/android/getting-started) targets Android apps, and may be used for other Android-based platforms.
>   * [Android TV](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/android-tv/getting-started) targets Android TV apps.
>   * [Fire TV](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/fire-tv/getting-started) targets Fire TV apps.
>
> * iOS/tvOS Legacy (4.12.x) SDK
>
>   * [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/ios/getting-started) targets iOS and iPadOS apps.
>   * [tvOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/tvos/getting-started) targets tvOS (i.e. Apple TV) apps.

---

# OptiView Hosted Player

Dolby hosts a special version of the OptiView video player for use with customers intended to be used for `<iframe>` embedding. This version of the player is configurable with query parameters to make it easy to setup and configure.

> **Hosted Player Under Construction**
>
> This version of the player is under development.

> **Player Updates**
>
> This version of the player will automatically be updated when new releases are published.

The player is hosted at:

```text
https://sbp.optiview.dolby.com
```

## Configuration

The following parameters can be provided used to configure the hosted player. *Note: query parameters are case sensitive!*

### Required Parameters

* `license`: a OptiView player license obtained through the dashboard. If using the hosted version of the player you should limit sources for playback, you can utilize "Source Domain" restrictions in the player portal. This will prevent viewers from stealing your license and using it for their own streams. If using streams from Dolby, you must white list the following

  * *Whitelist Page Domains*

    * `sbp.optiview.dolby.com`
    * *Note: at this time it is not possible to whitelist the end-application domain for whitelisted page domains in the license. If you wish to secure your streams by page domain, please contact Dolby to get your own license and player implementation.*

  * *Whitelist Source Domains*

    * `cdn.theo.live`
    * `cdn.anywhere.theo.live`
    * `cdn.tla-prd.theostream.live`
    * `discovery.theo.live`
    * `stream.anywhere.theo.live`
    * `stream.theo.live`

* `sourceType`: the type of source to configure the player to play back. Choose one of:

  * `realtime`: Real-time WebRTC playback with OptiView's real-time streaming solution (formerly Millicast)
  * `lowdelay`: Low-delay HESP playback with OptiVIew's live streaming solution (formerly THEOlive).
  * `live`: HLS playback with an .m3u8 manifest
  * `vod`: used for MP4 progressive download playback or for HLS/DASH non-live assets. The type is determined by the file extension.

* `source`: the source itself based on the `sourceType`. Here are some examples:

  * for `realtime`, the source looks like `accountId/streamname`. Example: `k9Mwad/multiview`.
  * for `lowdelay`, the source looks like `channelId`. Example: `ar5c53uzm3si4h4zgkzrju44h`.

### Optional Parameters

* `token`: an optional playback token for enabling stream protection. The type of token must be matched to the `sourceType`.
* `autoPlay`: *(default `false`).* A boolean whether to enable playback to automatically start when the page loads.
* `muted`: *(default `true`).* A boolean whether to start the stream playback muted or not. *Note that if `autoPlay` is set to `true`, playback will begin muted due to browser restrictions.*
* `poster`: a publicly accessible poster frame image to show when the stream is offline
* `playerColor`: *(default `4D5963`)* a hex color code value to set the play button and scrub bar. *Note that the value is an integer and should NOT contain the `#` at the beginning.*

### Optional Parameters (real-time only configurations)

The following parameters are only valid with Dolby OptiView real-time streaming and will be ignored with other `sourceTypes`.

* `minDelay`: *(default: `50`).* a small minimum playout delay set to improve performance in degraded network conditions. Specified in milliseconds. See [Documentation](https://docs-preview.optiview.dolby.com/pr-932/millicast/playback/players-sdks/web/player.md#playout-delay).
* `maxDelay`: *(default: `120`).* a small maximum playout delay set to improve performance in degraded network conditions. Specified in milliseconds.
* `maxHeight`: The maximum height resolution height (pixels) in the ABR range control to load in the given playback session. See [Documentation](https://docs-preview.optiview.dolby.com/pr-932/millicast/playback/players-sdks/web/player.md#abr-range-control). Intended to be used mutually exclusively with `maxWidth`.
* `maxWidth`: The maximum width resolution (pixels) in the ABR range control to load in the given playback session. See [Documentation](https://docs-preview.optiview.dolby.com/pr-932/millicast/playback/players-sdks/web/player.md#abr-range-control). Intended to be used mutually exclusively with `maxHeight`.

## Player Events

Basic [player events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdBreakEvent) are sent with [window post messages](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) to the parent page in case the embedding application wishes to utilize them. Events include:

* ended
* pause
* play
* playing
* resize
* volumechange

Here is an example of how to consume these messages, logging them to the console:

```javascript
<script>
  window.addEventListener("message", (event) => {
    // confirm origin for security
    if (event.origin !== "https://sbp.optiview.dolby.com") {
      return;
    }

    console.log("iframe event", event.data);
  });
</script>
```

### Configuration Examples

This is a basic example of a player that is configured in a basic way to play a real-time source:

```text
https://sbp.optiview.dolby.com/?sourceType=realtime&source=k9Mwad/multiview&license=LICENSE_STRING
```

This is an example of a player that is configured to play a real-time stream with token protection and other customizations:

```text
https://sbp.optiview.dolby.com/?sourceType=realtime&source=k9Mwad/multiview&autoPlay=false&muted=true&playerColor=58007a&license=LICENSE_STRING&token=TOKEN_STRING
```

This is an example to load an OptiView low-delay stream and start with automatic playback:

```text
https://sbp.optiview.dolby.com/?sourceType=lowdelay&source=ar5c53uzm3si4h4zgkzrju44h&autoPlay=true&muted=true&license=LICENSE_STRING
```

This is an example to load an HLS stream and start with automatic playback:

```text
https://sbp.optiview.dolby.com/?sourceType=live&source=https://stream.theo.live/europe-west/e2c4220c-3cf4-4499-ab3a-ea5e904d0406/ar5c53uzm3si4h4zgkzrju44h/stream/main.m3u8&autoPlay=true&muted=false&license=LICENSE_STRING
```

## A Complete Example

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Dolby Stream Embed</title>
    <style>
      html,
      body {
        height: 100%;
        width: 100%;
        margin: 0;
      }
      iframe {
        width: 100%;
        height: 100%;
        border: none;
      }
    </style>
  </head>
  <body>
    <iframe
      src="https://sbp.optiview.dolby.com/?sourceType=realtime&source=k9Mwad/multiview&autoPlay=false&muted=true&playerColor=58007a&license=LICENSE_STRING"
      allowfullscreen
      allow="autoplay; encrypted-media"
    ></iframe>
    <script>
      window.addEventListener('message', (event) => {
        // confirm origin for security
        if (event.origin !== 'https://sbp.optiview.dolby.com') {
          return;
        }

        console.log('iframe event', event.data);
      });
    </script>
  </body>
</html>
```

---

# THEOplayer Web SDK

Dolby OptiView Player (formerly THEOplayer) is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)

[Set up your first THEOplayer in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md)

## [🛝Examples](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/examples.md)

[See the player in action!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/examples.md)

## [🔌Connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/web.md)

[Integrate third-party solutions with THEOplayer using our pre-built connectors.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/web.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog.md)

[Find out what's new in the OptiView Player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog.md)

## [\*️⃣API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web)

[Discover all properties and functions of THEOplayer.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

# Getting started on Web

Dolby OptiView Player (formerly THEOplayer) is the universal video player solution from Dolby. The HTML5/Tizen/webOS Player SDK offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

This article is your starting point if you are using Dolby OptiView Player for the first time. It takes you through the required steps to achieve a basic manual implementation of the Player SDK on Web. The outcome of this article is the template below.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="SDK-LIBRARY-LOCATION/ui.css" />
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
    <script src="SDK-LIBRARY-LOCATION/THEOplayer.js"></script>
    <script>
      var element = document.querySelector('.theoplayer-container');
      var player = new THEOplayer.Player(element, {
        libraryLocation: 'SDK-LIBRARY-LOCATION',
        license: 'YOUR-LICENSE-STRING',
      });
      player.source = {
        sources: [
          {
            src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
            type: 'application/x-mpegurl',
          },
        ],
      };
    </script>
  </body>
</html>
```

> **Note**
>
> When copy-pasting the above code, make sure to replace the placeholders `YOUR-LICENSE-STRING` and `SDK-LIBRARY-LOCATION` with your license and library location respectively. [See below for more information.](#build-configure-and-publish-sdk)

## Prerequisites

Before we can start using THEOplayer, you'll need a few things:

1. A web server and domain name to host your code and provide access to viewers.
2. A THEOplayer SDK and license to implement the THEOplayer library and access the THEOplayer API.
3. A video stream (e.g. an `.m3u8` or `.mpd` file) to show to your viewers through the THEOplayer API.

### Installing THEOplayer Web SDK

The THEOplayer Web SDK is available on npm: <https://www.npmjs.com/package/theoplayer>. Installation can be done using your favorite package manager for Node (such as `npm` or `yarn`):

```bash
npm install theoplayer
```

You can also install a specific version instead:

```bash
npm install theoplayer@7.0.0
```

Different THEOplayer packages are available on npm with their own included features. Choose the package which best fits your requirements. In the rest of the guide we reference `SDK-LIBRARY-LOCATION` which should become the path to the installed theoplayer package in your node modules, similar to: `path/to/node_modules/theoplayer/`.

> **Custom Web SDK**
>
> We do recommend downloading the THEOplayer Web SDK through npm, but if you need a custom SDK with a different combination of features it is possible to create one on [the Portal](https://portal.theoplayer.com/login). Skip to [Create an SDK through Portal](#create-an-sdk-through-portal) for a detailed explanation.

### Getting a THEOplayer License

Creating a Web SDK on the Portal can be achieved by the following steps:

1. [Register and sign in](#register-and-sign-in)
2. [Initiate license creation](#initiate-license-creation)
3. [Build, configure and publish license](#build-configure-and-publish-license)

#### Register and sign in

You register with your GitHub or Google account through the [sign-in page](https://portal.theoplayer.com/login), or complete the [signup form](https://portal.theoplayer.com/register). You sign in with your GitHub or Google account, or with your credentials, through the sign-in page.

#### Initiate license creation

On the THEOplayer Developer Portal dashboard, click the Create button in the licenses panel, as annotated with a red arrow in the following screenshot.

![THEOplayer Developer Portal\&#39;s dashboard](/pr-932/assets/images/portal-dashboard-b6d20084c1941c5e96902bd8c3a4a92e.png)

Alternatively, you create a license through the SDKs page.

* You click the SDKs item in the side navigation panel to navigate to the overview of your existing SDKs.
* The content panel of the SDKs page presents action buttons. Click the Create button to initiate the license creation process, as highlighted in the screenshot below.

![THEOplayer Developer Portal SDK Page](/pr-932/assets/images/portal-sdk-b439507beb50e04557eefb9e763db28b.png)

#### Build, configure and publish license

Building your license involves three steps.

1. Choose platform – Select the HTML5 icon highlighted with the red circle in the following screenshot. HTML5 applications (i.e. websites, progressive web apps) use the THEOplayer Web SDK.
2. Configure license – Name the license and configure your domain whitelisting settings. The latter allows your license to only function for some websites and/or streams.
3. Review and publish – Validate your configuration and click "Publish", or go back.

![Choose platform](/pr-932/assets/images/portal-choose-platform-23ce30a0d4c2ea5364a6429c679bfb39.png)

After you complete the third step, "Review and Publish", you will get your unique LICENSE which should replace `YOUR-LICENSE-STRING` in the examples.

![License generated](/pr-932/assets/images/portal-license-86831573290e72f6ab522fba40572050.png)

### Create an SDK through Portal

> **Info**
>
> We recommend [downloading the THEOplayer SDK through npm](#installing-theoplayer-web-sdk) for most use cases. If you need an SDK with custom features, you can follow the next steps. Otherwise, skip to [Basic setup](#basic-setup).

Creating a Web SDK on the Portal can be achieved by the following steps:

1. [Register and sign in to Portal](#register-and-sign-in-to-portal)
2. [Initiate SDK creation](#initiate-sdk-creation)
3. [Build, configure and publish SDK](#build-configure-and-publish-sdk)

#### Register and sign in to Portal

You register with your GitHub or Google account through the sign-in page, or complete the signup form. You sign in with your GitHub or Google account, or with your credentials, through the sign-in page.

#### Initiate SDK creation

To create an SDK through Portal similar steps should be followed as generating a license only. On the dashboard or in the SDKs menu, also click the Create button. Important here is to make sure you are on the CUSTOM tab as this will allow creating a custom SDK with a license instead of only a license.

![THEOplayer Developer Portal\&#39;s dashboard custom](/pr-932/assets/images/portal-custom-sdk-5d9ea6fb504a6ebe49b949014e1dc9a6.png)

Alternatively, when following the steps to generate only a license there will be redirect link to the steps for creating a custom THEOplayer SDK.

![Custom SDK redirect](/pr-932/assets/images/portal-sdk-redirect-fd80f250b0a7d315392169ff414ea16e.png)

#### Build, configure and publish SDK

Building your Web SDK involves four steps.

1. Choose platform – Select the HTML5 icon highlighted with the red circle in the following screenshot. HTML5 applications (i.e. websites, progressive web apps) use the THEOplayer Web SDK.
2. Configure SDK – Name the SDK and configure your domain whitelisting settings. The latter allows you to restrict your SDK to only function on your own websites and/or streams.
3. Select features – Enable certain features (e.g. HLS advertising) and disable others (e.g. Chromecast).
4. Review and publish – Validate your configuration and click "Publish", or go back.

![Build SDK](/pr-932/assets/images/portal-build-sdk-246e4b4384d6eb310935338612b5a560.png)

After you complete the fourth step, "Review and Publish", it'll take the portal a couple of minutes to generate your unique SDK. Once you see the Ready! button, as the screenshot below highlights with the red rectangle, you know that your SDK is available.

![SDK ready](/pr-932/assets/images/portal-sdk-ready-5d3aa3e1aed98d820b77eb79e0f4523f.png)

The following sections of this guide reference `SDK-LIBRARY-LOCATION` which should be replaced with the SDK library location URL. Similarly, `YOUR-LICENSE-STRING` should be replaced with the LICENSE

## Basic setup

Now, we're ready to set up THEOplayer on your website. This guide explains how you implement THEOplayer in four steps:

1. We'll [start from a basic HTML file](#step-1-set-up-an-html-file), with no mention of THEOplayer.
2. In the [second step](#step-2-including-the-theoplayer-library), we'll explain what the THEOplayer library is and how you can include it. We'll do the same for the default THEOplayer UI.
3. In the [third step](#step-3-the-video), we'll describe how you play a video stream through THEOplayer.
4. In the [fourth step](#step-4-the-result), we'll give a final overview.

### Step 1: Set up an HTML file

When THEOplayer is used as a web video player, we will need a web page (i.e. HTML file) to embed THEOplayer and the code.

Note that a THEOplayer SDK license can only be used on whitelisted domains. You configure these domains when you create a THEOplayer license at <https://portal.theoplayer.com>.

Let's start with the following HTML file:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
  <body></body>
</html>
```

Next, we’ll include the THEOplayer SDK.

### Step 2: Including the THEOplayer library

To access the THEOplayer API and default UI, you must first include the THEOplayer library files. The JavaScript library exposes the THEOplayer API and the CSS library contains the default UI.

> **Open Video UI**
>
> The Open Video UI is our new Web UI. It provides component libraries for building a world-class video player experience powered by the THEOplayer SDK. [See our Getting Started guide to start using the Open Video UI.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui/getting-started.md)

#### THEOplayer JavaScript library

In a previous step, we downloaded the [THEOplayer npm package](#installing-theoplayer-web-sdk) or created a [custom THEOplayer SDK](#create-an-sdk-through-portal). Now we'll include it in our HTML file. There are two options for this:

* Option 1: in your HTML

  ```html
  <script src="SDK-LIBRARY-LOCATION/THEOplayer.js"></script>

  <!-- or if you only need the chromeless version (without UI) -->
  <script src="SDK-LIBRARY-LOCATION/THEOplayer.chromeless.js"></script>
  ```

  The `<script>` tag can include an external JavaScript library on a web page. In this case we use it to include the THEOplayer library.

  The `src` attribute is the URI of the THEOplayer library that you wish to use. This could be something like: `'SDK-LIBRARY-LOCATION/THEOplayer.js'`, where the URL is a link to your THEOplayer.js file.

* Option 2: in your JavaScript

  ```javascript
  import * as THEOplayer from 'theoplayer';

  // or if you only need the chromeless version (without UI):
  import * as THEOplayer from 'theoplayer/chromeless';
  ```

  > **Legacy browser support**
  >
  > Starting with THEOplayer 6.0, this will import a JavaScript module targeting modern browsers, using modern JavaScript syntax such as [`async/await`](https://caniuse.com/async-functions). If you need to support older browsers (such as older smart TVs), then you'll need to use option 1 instead as this creates a global `THEOplayer` variable that exposes the full API.

#### THEOplayer CSS library

To use the default THEOplayer UI, you need to reference the THEOplayer CSS library:

```html
<link rel="stylesheet" type="text/css" href="SDK-LIBRARY-LOCATION/ui.css" />
```

The `<link>` tag includes a CSS file on a web page. Similar to the JavaScript library, you must swap `SDK-LIBRARY-LOCATION` with your actual library location.

Next, we’ll create a THEOplayer instance and configure a video stream.

### Step 3: The video

To play a video through the THEOplayer Web SDK, you must:

1. Create a video player container element.
2. Retrieve a reference to this container through JavaScript.
3. Create a THEOplayer instance associated with that container.
4. Configure a video stream for this instance.

The snippet below implements these 4 steps:

```html
<div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
<script src="SDK-LIBRARY-LOCATION/THEOplayer.js"></script>
<script>
  // Retrieve the THEOplayer container div
  var element = document.querySelector('.theoplayer-container');

  // Create the video player
  var player = new THEOplayer.Player(element, {
    libraryLocation: 'SDK-LIBRARY-LOCATION', // references folder containing your THEOplayer library files (theoplayer.p.js, THEOplayer.js, ...)
    license: 'YOUR-LICENSE-STRING', // references your THEOplayer SDK license
  });

  // HLS
  player.source = {
    sources: [
      {
        src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8', // sets HLS source
        type: 'application/x-mpegurl', // sets type to HLS
      },
    ],
  };

  // DASH
  // player.source = {
  //   sources: [
  //     {
  //       src: '//cdn.theoplayer.com/video/cosmos/cmaf.mpd', // sets DASH source
  //       type: 'application/dash+xml', // sets type to MPEG-DASH
  //     },
  //   ],
  // };
</script>
```

Let's break down the above snippet.

#### Create video player container

This `<div>` element creates a video player container.

```html
<div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
```

* The `theoplayer-container` class is used to fetch the container through JavaScript, as demonstrated by the snippet below.
* The `video-js theoplayer-skin vjs-16-9` classes load the default THEOplayer UI. You may omit `vjs-16-9` if you don't want a 16:9 container.

Setting the size of the container

There are other approaches to setting the size of your container instead of using `vjs-16-9`. For example, you could omit the `vjs-16-9` class, and instead configure the width and height of container class through CSS.

```css
.theoplayer-container {
    width: 200px;
    height: 200px;
}
```

![screenshot from a sample minimal page with THEOplayer, showing how to use the width and height to change the size of the player](/pr-932/assets/images/container-height-percent-f3c137751a4bcaf899cbe1717cfe5363.png)

Alternatively, you set your container to be responsive to its parent node by setting `fluid: true` in your configuration, as demonstrated by the following screenshot.

```js
var player = new THEOplayer.Player(element, {
    fluid: true
    // ...other options go here
});
```

![screenshot from a sample minimal page with THEOplayer, showing how to use the playerConfig property fluid to regulate the player size](/pr-932/assets/images/container-height-fluid-8b4b6a4d519bed788ed2231a26a8b1ab.png)

There is no wrong or right. It's up to you to decide which approach is best for your use-case.

```javascript
var element = document.querySelector('.theoplayer-container');
```

#### Create THEOplayer instance

The snippet below creates a THEOplayer instance for a container with a specific [Player Configuration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerConfiguration).

```js
var player = new THEOplayer.Player(element, {
  // instantiates the video player
  libraryLocation: 'SDK-LIBRARY-LOCATION', // references folder containing your THEOplayer library files (theoplayer.p.js, THEOplayer.js, ...)
  license: 'YOUR-LICENSE-STRING', // references your THEOplayer SDK license
});
```

Similar to the JavaScript and CSS library, you must swap out `SDK-LIBRARY-LOCATION` and `YOUR-LICENSE-STRING`.

You can read more about configuring the `license` at the [License section](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/license/introduction.md).

#### Configure video stream

The snippet below configures a HLS video stream for the THEOplayer instance.

```js
player.source = {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8', // sets HLS source
      type: 'application/x-mpegurl', // sets type to HLS
    },
  ],
};
```

To configure a DASH stream instead, you must set `type` to `'application/dash+xml'` instead of `'application/x-mpegurl'`, as demonstrated by commented out code in one of the earlier snippets.

In the next step we'll put everything together.

### Step 4: The result

Use the snippet below on your web server.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="SDK-LIBRARY-LOCATION/ui.css" />
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
    <script src="SDK-LIBRARY-LOCATION/THEOplayer.js"></script>
    <script>
      var element = document.querySelector('.theoplayer-container');
      var player = new THEOplayer.Player(element, {
        libraryLocation: 'SDK-LIBRARY-LOCATION',
        license: 'YOUR-LICENSE-STRING',
      });
      player.source = {
        sources: [
          {
            src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
            type: 'application/x-mpegurl',
          },
        ],
      };
    </script>
  </body>
</html>
```

## Bundler setup

When using a [bundler](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Overview) such as [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/), [Vite](https://vitejs.dev/) or [Parcel](https://parceljs.org/) you may need some additional configuration to make your bundler copy all files needed by the THEOplayer Web SDK and set your `libraryLocation` correctly.

> **Just give me the code!**
>
> If you prefer starting from a fully working example rather than copy-pasting these snippets into your code, check out [our examples on GitHub](https://github.com/THEOplayer/samples-npm-html5-sdk)!

What is a `libraryLocation`?

The THEOplayer Web SDK uses [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) to off-load several CPU-intensive tasks to a separate worker thread. By moving these tasks off the main thread, THEOplayer ensures that your app remains fast and responsive.

The code for these workers is located in separate JavaScript files, outside the main THEOplayer library. The THEOplayer Web SDK ships with several of these files, such as:

* `THEOplayer.transmux.js`: responsible for transmuxing MPEG-TS and AAC files to fragmented MP4.
* `theoplayer.d.js`: responsible for decrypting HLS segments encrypted with full-segment AES-128 encryption.

Additionally, some of these workers leverage [WebAssembly](https://developer.mozilla.org/en-US/docs/WebAssembly) for improved performance:

* `THEOplayer.transmux.wasm`: the WebAssembly binary for transmuxing MPEG-TS and AAC files.

These files need to be hosted on your app's server, so the main THEOplayer library can locate and load them when needed. You tell THEOplayer where you put those files by setting the `libraryLocation` in your [player configuration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerConfiguration).

JavaScript bundlers work by traversing your app's dependencies through `import` or `require()` statements in your source code. As such, they can't auto-magically detect that THEOplayer needs these extra files, since they are never directly imported. You'll need to configure your bundler to *also* copy these extra files to your app's output directory.

### Webpack

Use [`copy-webpack-plugin`](https://webpack.js.org/plugins/copy-webpack-plugin/) to copy the THEOplayer files to the output directory.

webpack.config.js

```js
const CopyPlugin = require('copy-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: __dirname + '/dist',
  },
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          context: 'node_modules/theoplayer/',
          from: './*.(css|js|html|wasm)',
          info: { minimized: true },
          to: 'vendor/theoplayer/',
        },
      ],
    }),
  ],
};
```

Then, configure your library location:

src/index.js

```js
import * as THEOplayer from 'theoplayer';

var player = new THEOplayer.Player(element, {
  libraryLocation: '/vendor/theoplayer/',
  license: 'YOUR-LICENSE-STRING',
});
```

### Rollup

Use [`rollup-plugin-copy`](https://webpack.js.org/plugins/copy-webpack-plugin/) to copy the THEOplayer files to the output directory.

rollup.config.js

```js
import copy from 'rollup-plugin-copy';

export default {
  input: {
    bundle: './src/index.js',
  },
  output: {
    dir: './dist',
  },
  plugins: [
    copy({
      targets: [
        {
          src: './node_modules/theoplayer/*.(js|css|html|wasm)',
          dest: './dist/vendor/theoplayer',
        },
      ],
    }),
  ],
};
```

Then, configure your library location:

src/index.js

```js
import * as THEOplayer from 'theoplayer';

var player = new THEOplayer.Player(element, {
  libraryLocation: '/vendor/theoplayer/',
  license: 'YOUR-LICENSE-STRING',
});
```

### Vite

Use [`vite-plugin-static-copy`](https://www.npmjs.com/package/vite-plugin-static-copy) to copy the THEOplayer files to the output directory.

vite.config.js

```js
import { defineConfig } from 'vite';
import { viteStaticCopy } from 'vite-plugin-static-copy';

export default defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        {
          src: 'node_modules/theoplayer/*.(css|js|html|wasm)',
          dest: 'vendor/theoplayer/',
        },
      ],
    }),
  ],
});
```

Then, configure your library location:

src/index.js

```js
import * as THEOplayer from 'theoplayer';

var player = new THEOplayer.Player(element, {
  libraryLocation: `${import.meta.env.BASE_URL}vendor/theoplayer/`,
  license: 'YOUR-LICENSE-STRING',
});
```

### Parcel

Use [`parcel-reporter-static-files-copy`](https://www.npmjs.com/package/parcel-reporter-static-files-copy) to copy the THEOplayer files to the output directory.

.parcelrc

```json
{
  "extends": ["@parcel/config-default"],
  "reporters": ["...", "parcel-reporter-static-files-copy"]
}
```

package.json

```json
{
  "name": "my-app",
  "staticFiles": {
    "staticPath": "node_modules/theoplayer/",
    "distDir": "dist/vendor/theoplayer/"
  }
}
```

Then, configure your library location:

src/index.js

```js
import * as THEOplayer from 'theoplayer';

var player = new THEOplayer.Player(element, {
  libraryLocation: '/vendor/theoplayer/',
  license: 'YOUR-LICENSE-STRING',
});
```

## Next steps

Ready to learn more?

* Go through our [how-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md) to learn about [UI customization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/introduction.md), [advertising](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/introduction.md), [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md), [casting](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/introduction.md), [analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/introduction.md) and other topics.
* Check out our [API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer).
* Try out samples from our [GitHub](https://github.com/THEOplayer).

---

# API examples

This page contains an overview of examples, demonstrating the capabilities of the THEOplayer API and custom JavaScript. With these examples, we try to explain the fundamentals of how to use our API:

* Accessing **player properties** and using **methods** (e.g. *currentTime*, *duration*, ...) ,

* Hooking to **events**,

* Inserting DOM-elements (buttons, text, ...) in the **UI**

* ...

The examples are sorted per subject, and a link can re-appear if it also relates to another subject. New examples will be added from time to time, when new use cases arise, or when new developments happen.

If you are new to THEOplayer, please read our [Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md) or our [API pages](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web).

## Properties and methods

* <http://demo.theoplayer.com/creating-bookmarks-with-js-css-theoplayer> — Demonstrates how to use basic player properties and the *play()* method to create your own bookmarks, and load those settings into your active player.

* <http://demo.theoplayer.com/keeping-track-of-currenttime-timeupdate> — Demonstrates a use case of the *currentTime*, *played* and *buffered* properties.

* <http://demo.theoplayer.com/adblock-detection> — Demonstrates how to use ad block detection.

* <http://demo.theoplayer.com/schedule-ad-example> — Demonstrates how to schedule an advertisement.

## Events

* <http://demo.theoplayer.com/using-events-examples> — Demonstrates how to listen to player events as *playing* and *pause*, and ad events as *adbegin*.

* <http://demo.theoplayer.com/keeping-track-of-currenttime-timeupdate> — Demonstrates a use case of the *timeupdate* and *loadeddata* event.

* <http://demo.theoplayer.com/implementing-continuous-play-with-js-cookies-theoplayer> — Demonstrates how to save the playhead position and restore it, using cookies.

* <http://demo.theoplayer.com/adblock-detection> — Demonstrates how to use ad block detection.

## UI

* <http://demo.theoplayer.com/adding-buttons-text-overlay-to-theoplayer> — Demonstrates how to insert a button in the control bar, overlay a container and overlay text.

* <http://demo.theoplayer.com/changing-default-player-ui-css> — Demonstrates how to change some elements (e.g. re-color progress bar, change control bar icon) of the default UI.

* <http://demo.theoplayer.com/chromeless-ui-js-html-css> — Demonstrates how to create a minimal chromeless UI.

* <http://demo.theoplayer.com/timejump-buttons> - Demonstrates how to insert buttons which can jump back/forth in time.

* <http://demo.theoplayer.com/language-localization> - Demonstrates how to configure language localization.

* <http://demo.theoplayer.com/custom-center-controlbar> - Demonstrates how to create custom centered control bar

* <http://demo.theoplayer.com/fullscreen-social-controlbar> - Demonstrates how to create a custom social control bar which is only visible when the player is in fullscreen mode

* <http://demo.theoplayer.com/playlist-and-caching> - Demonstrates how to build a playlist which can preload upcoming content

* <http://demo.theoplayer.com/player-background-image> - Demonstrates how to set a background image for the player

* <http://demo.theoplayer.com/using-custom-error-messages> - Demonstrates how to display custom error messages

---

# Getting started with Accessibility

Integrating accessibility features on the web is crucial to accommodating viewers with limitations, optimize the general viewer experience and maximize overall reach. The basis of video accessibility means that viewers with disabilities can perceive, understand, navigate, and engage with video content equally, and without obstacles or barriers. Additionally, accessibility can apply to all viewers, regardless of disability or not (i.e. situational limitations, slow internet connection, temporary disabilities, etc.). In this guide we discuss what guidelines to follow to make your content accessible, the legal bodies in place, why accessibility is important, as well as what features are available for OptiView player to make video content accessible.

## Web Content Accessibility Guidelines

*The Web Content Accessibility Guidelines (WCAG)* are created by both individuals and organizations, and are seen as the standard for accessible web content internationally. Those organizations are formally known as the Accessibility Guidelines Working Group (AG WG) which is part of the World Wide Web Consortium (W3C) Web Accessibility Initiative (WAI). The guidelines are created to help individuals and organizations across the world make their online content accessible to all viewers, including those with disabilities. Online content is seen by the WCAG as information such as text, image, video, audio, and also as any code that determines structure, UI presentation, and more. You can find the full overview of WCAG guidelines [on their website](https://www.w3.org/WAI/standards-guidelines/wcag/).

There are three levels to the WCAG: A, AA, and AAA:

* A: the basic/bare minimum accessibility functionalities
* AA: decently accessible, where most organizations tend to stand
* AAA: very accessible, top tier accessibility

What is new in WCAG? WCAG 2.1 was updated in 2018. The success criteria from WCAG 2.0 are included verbatim in WCAG 2.1, but 17 additions were included in 2.1 to address mobile accessibility, viewers with low vision and viewers with cognitive and learning disabilities. WCAG 2.0 and 2.1 are backwards compatible, or in other words, if an organization adheres to 2.1 they also adhere to 2.0.

The additions in 2.1 require online content to be adaptable, distinguishable, compatible, keyboard accessible, have functional modalities, be safe for those with seizures or physical reactions, and have ‘enough time’ capabilities. To view the technical documentation of the WCAG 2.1 and use case examples, [visit their website here](https://www.w3.org/WAI/standards-guidelines/).

WCAG 2.2 was updated in 2024. The 2.0 and 2.1 success criteria are essentially the same in 2.2, with one exception: Parsing is obsolete and removed from WCAG 2.2.

OptiView Player is a single player across all major mobile devices, platforms and browsers, and our video player solution is upgraded with accessibility capabilities to adhere to WCAG across all of them, out of the box.

## User Agent Accessibility Guidelines (UAAG)

Under the WCAG is the User Agent Accessibility Guidelines (UAAG), which encompasses web browsers, browser extensions and media players, and the UAAG targets developers. The UAAG was created to primarily provide alternative information for those who want to remain compliant with WCAG, but are using a variety of different technologies and platforms. For example, some accessibility needs are met through the browser the viewer is using, while others are better met through the media content.

UAAG is seen as relevant for the future of accessibility, especially for mobile device accessibility. Mobile devices show the need for accessibility within a combination of UI, the content and applications used. UAAG also highlights the need for more accessibility features that work seamlessly across devices, platforms, and browsers. If you would like to explore more about UAAG specifically, check out the documentation with [standards and guidelines from WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/).

## Why is WCAG important for Video?

Complying with the WCAG is crucial for all publishers of online content, particularly video content. By ignoring accessibility, you are losing a large chunk of your audience. By a large chunk, we mean 15% of the world’s population who have at least one disability. By implementing accessibility features you are including everyone, reaching more viewers and increasing your traffic and SEO rankings.

Not only is accessibility important for rankings and to those with disabilities, but it is also adds to the viewer experience and usability for non-disabled viewers as well. For example, if a viewer is in a noisy or quiet environment, or the viewer is a non-native speaker of the language used in the video, subtitles will allow them to still enjoy the video content. Keyboard accessibility can be of great use to those viewers whom may not have a mouse or have a temporary injury.

# Accessibility Features

OptiView Player integrates the following features for accessibility:

### Text Tracks

Text Tracks (i.e. video captions or subtitles) are the audio from a video, but in text form. This includes words that are spoken, who is speaking (if it isn’t clear) and important noises such as music. This can help viewers who are hearing impaired in any capacity, or those with cognitive or learning disabilities. These captions can also benefit those general viewers whom, for example, may be in a loud, or silent, viewing environment. You can seamlessly integrate this feature into your OptiView Player. For more information on integrating Text Tracks into OptiView player and the supported formats, see our [guide on text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/introduction.md).

### Text Track Style

Text track style allows for the text in video captions to be displayed in a way the text is readable. This involves adapting the text color, font, size, spacing and other text properties. This makes the audio and video captions accessible to those with low vision, dyslexia, and/or cognitive or learning disabilities. This feature also makes your content more adaptable to different devices and browsers, content translation and personal preferences for caption viewing. This feature goes hand-in-hand with Text Tracks, and can be easily integrated in your OptiView player. For more on this feature, see this section of our [guide on text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-insert-subtitles.md#subtitle-styling).

### Accessibility Roles for Tracks

The OptiView player can expose the type of text or audio track programmatically through the API via `AccessibilityRole`. These roles allow assistive technologies to recognize the purpose of each track automatically. See more in our [API Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/AccessibilityRole).

Common roles are:

* *Captions*: speech + non-speech audio cues
* *Subtitles*: translation, no non-speech audio cues
* *Audio Descriptions*: narration of visual content)
* *Sign Language*: describes a sign-language track

### Focus Style

Focus Style allows the buttons on the video player (the control bar, menu items, close buttons, etc.) to be outlined in order to make them more visible when they are clicked or hovered over. This feature makes it easier for all viewers to see and understand which buttons are in use and which one they have selected. Also while hovered over, the Tooltips feature can make it easier for users by giving them a text description of the button on the UI. For example, when hovered over the mute button, it is outlined and a readers also see the word "Mute" appear on their UI. You can change the look of the default UI with our [UI Skinning Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/ui-skinning.md) or fully customize every element of your video player with our [Open Video UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md).

### User Interface Customization

User Interface, or UI, is the aspect of the video content that the viewer engages with. For viewers with disabilities, it is important that colors have sufficient contrast with the text and its background. The contrast is not limited to captions, but also includes the text on images, buttons and icons. This feature is especially helpful for viewers with color blindness or low contrast visibility, which is common in aging viewers, as well as viewers in difficult light conditions. It is also important for the video player to have a clear layout and design, to make it as easy and accessible to all viewers as possible. You can change the look of the default UI with our [UI Skinning Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/ui-skinning.md) or fully customize every element of your video player with our [Open Video UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md).

### Keyboard Compatibility

This allows for viewers to navigate the UI (i.e. buttons, links, player functions) via the keyboard. This feature is helpful for viewers who are physically unable to use a mouse, or those viewers who are visually impaired and unable to see the player UI. To customize keyboard presses, refer to our [guide on keyboard hotkeys](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/how-to-implement-hotkeys.md).

Our universal player is focused on the mandatory guidelines, and is compliant with those guidelines set out by the WCAG 2.2, the EU Web Accessibility Directive, as well as other guidelines for regions across the world. It is also important to note that different countries and regions of the world can have different guidelines and regulations. For an extensive list of guidelines and regulations per country or region, and all of the standards and specifications related to accessibility, please visit the [WCAG website](https://www.w3.org/WAI/standards-guidelines/wcag/).

### Screen Reader Support

The OptiView player supports screen readers across different platforms including VoiceOver for Mac/iOS and Narrator for Windows. For more detail on the WCAG success criterion, refer to [SC 1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html).

### Bookmarks, Chapter Markers, and Thumbnails

The player supports thumbnails, bookmarks and chapter markers as alternative navigation aids for time-based media.

* [Reference for Bookmarks](https://optiview.dolby.com/docs/theoplayer/getting-started/sdks/web/api-examples/#properties-and-methods)
* [Reference for Chapter Markers](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/knowledge-base/playback/what-are-chapter-markers.md)
* [Reference for Thumbnails](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-implement-preview-thumbnails.md)

### Other Features

There are a few other features of the OptiView player which adhere to the WCAG guidelines. Specifically:

* *orientation*: the player adapts itself out of the box to different device orientations (and advanced controls for this are also available).
* *audio controls*: Audio controls are available, including a mute button, and a pause button (also during ads); player adheres to browsers autoplay policies
* *speed*: the player speed can be customized, so fast-paced subtitles can be showed for longer times

---

# How to implement Keyboard Hotkeys

This how-to guide describes how you can implement keyboard shortcuts in THEOplayer. Hotkeys allow viewers to also control THEOplayer functionality by using their keyboard.

## TLDR:

1. Add an id attribute to the player element in your HTML.

2. **Copy, Paste** and **Link** [this script](#full-javascript-code-example) in your HTML to enable the following set of hotkeys.

## List of Hotkeys

Keyboard hotkeys are not an 'out-of-the-box' feature provided by THEOplayer. This means you'll have to insert a bit of custom code to enable this functionality.

The script below will implement the following shortcuts:

* Spacebar : Toggles between Pause and Play.
* Left Arrow: Rewinds the video. (default: 5s)
* Right Arrow: Forwards the video. (default: 5s)
* Up Arrow: Increases the volume.
* Down Arrow: Lowers the volume.
* ' F ' Key: Toggles fullscreen mode.
* ' M ' Key: Toggles audio mute.

## Step-by-step Guide

### 1. THEOplayer-wrapper

Because the hotkeys we're about to include also have default browser functionality (e.g. space bar skipping down the page), we have two options:

1. Disable default browser hotkeys and overwrite them with our custom player hotkeys.

2. Enable THEOplayer hotkeys only when the viewer's mouse is inside the player area or when the player is focused.

Start by adding an id attribute to the player element in your HTML:

```html
<div id="yourPlayerId" class="video-js theoplayer-skin"></div>
```

### 2. JavaScript

Make a new JavaScript file and include it to your project with the rest of your scripts.

First off we're going to make a variable that holds the element in which we want to check for user interaction.

```javascript
const wrapper = document.getElementById('yourPlayerId');
```

Next up are the individual functions:

### 2.1 Disabling Default browser hotkeys

#### preventStandardHotKeyActions()

With event[.preventDefault()](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) we prevent the pressed key from performing their default browser functionality.

In our case this will disable the 'keydown' event if conditions are met.

```javascript
function preventStandardHotKeyActions(event) {
  event.stopPropagation();
  event.preventDefault();
}
```

### 2.2 Pause and Play

#### togglePlay()

Switches between pausing and playing the video. This function is triggered by pressing the spacebar.

```javascript
function togglePlay() {
  if (player.paused) {
    player.play();
  } else {
    player.pause();
  }
}
```

### 2.3 Rewinding and Skipping

#### rewind()

Rewinds the video 5 seconds (default) back in time when triggered.

```javascript
function rewind() {
  player.currentTime -= 5; //Subtracts 5 seconds
}
```

#### forward()

Skips the video 5 seconds (default) forward in time when triggered.

```javascript
function forward() {
  player.currentTime += 5; //Adds 5 seconds
}
```

### 2.4 Volume Settings

#### increaseVolume()

Increases the THEOplayer's volume in 5% increments (default).

```javascript
function increaseVolume() {
  player.volume = Math.min(player.volume + 0.05, 1); //Increases volume by 5%
}
```

#### decreaseVolume():

Lowers the THEOplayer's volume in 5% increments (default).

```javascript
function decreaseVolume() {
  player.volume = Math.max(player.volume - 0.05, 1); //Lowers volume by 5%
}
```

### 2.5 Toggle Fullscreen

#### toggleFullScreen()

Checks what presentation mode THEOplayer is in and switches the presentation mode to 'fullscreen' or 'inline' accordingly.

```javascript
function toggleFullScreen() {
  if (player.presentation.currentMode === 'fullscreen') {
    player.presentation.requestMode('inline');
  } else {
    player.presentation.requestMode('fullscreen');
  }
}
```

### 2.6 Toggle Mute

#### toggleMute()

Turns THEOplayer's audio on or off.

```javascript
function toggleMute() {
  player.muted = !player.muted;
}
```

### 2.7 KeyPressed Event

#### getPressedKey()

This function gets the 'key' property of the event object that triggered it (In our case a 'keydown' event). [List of Key values](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)

Start by initiating a variable for any key's that are pressed ('pressedKey') and a variable called 'action' that's going to call one of the functions we made earlier.

Next we make a switch case where we check the event's 'key' property for the ones we want to catch (e.g. ArrowLeft, " " for space, ... etc). If there's a match, we assign the corresponding function to 'action' to call after our conditions have been met.

```javascript
function getPressedKey(event) {
  const pressedKey = event.key;
  let action;
  switch (pressedKey) {
    case ' ':
      action = togglePlay(); //Pauses or Unpauses with Space
      break;
    case 'ArrowLeft':
      action = rewind(); //Rewinds the video with the Left Arrow Key
      break;
    case 'ArrowRight':
      action = forward(); //Forwards the video with the Right Arrow Key
      break;
    case 'ArrowUp':
      action = increaseVolume(); //Increases volume with the Up Arrow Key
      break;
    case 'ArrowDown':
      action = decreaseVolume(); //Lowers volume with the Down Arrow Key
      break;
    case 'f':
      action = toggleFullScreen(); //Toggle Fullscreen mode with the 'F' Key
      break;
    case 'm':
      action = toggleMute(); //Toggle Mute with the 'M' Key
      break;
  }
  if (action && pressedKey !== 'Control' && pressedKey !== 'Alt' && pressedKey !== 'Shift') {
    action();
    preventStandardHotKeyActions(event); //Stops the default key behavior like jumping the page with space.
  }
}
```

### 2.8 Enable hotkeys with focus

#### playerFocused():

Next we will allow the use of the THEOplayer hotkeys whenever the active element on the site is an element inside the player.

Any element that the user interacts with is set to be the active element. (e.g.: pressing a button with the mouse or by selecting something with tab for example.)

The snippet below will catch when the active element changes. If this element is part of the THEOplayer, we will enable the use of player hotkeys.

```javascript
function playerFocused() {
  if (wrapper.contains(document.activeElement)) {
    document.addEventListener('keydown', getPressedKey);
  } else {
    document.removeEventListener('keydown', getPressedKey);
  }
}
```

### 2.9 Enable Hotkeys on mouseEnter

Since browsers have default hotkey functionality (like skipping down the page by pressing space), you may only want to allow the use of the hotkeys whenever the viewer is actively watching the player.

The following functions will handle that use-case.

#### mouseInPlayer()

Gets called when a viewer enters the specified wrapper area with their cursor.

Creates an eventListener for both 'keydown' events and when the viewer's mouse leaves the wrapper area we specified at the beginning.

```javascript
function mouseInPlayer() {
  //Adds listeners for the keydown event and mouse leave event
  document.addEventListener('keydown', getPressedKey);
  wrapper.addEventListener('mouseleave', mouseOutPlayer);
}
```

#### mouseOutPlayer()

Gets called when a viewer exits the wrapper area.

When the viewer has left the wrapper area, the unused eventListeners are removed.

```javascript
function mouseOutPlayer() {
  //Checks if the mouse leaves the player wrapper area
  wrapper.removeEventListener('mouseleave', mouseOutPlayer);
  document.removeEventListener('keydown', getPressedKey);
}
```

### 3.0 Enabling the Hotkeys

#### enableShortcuts()

This function lets you choose between enabling the hotkeys site-wide, or only enabling them when the viewer's mouse is inside the player or the player is focused.

When calling this function you can use:

1. `enableShortcuts();` -To enable THEOplayer hotkeys site-wide.
2. `enableShortcuts('mouseOver');` -To enable THEOplayer hotkeys when the viewer's mouse is inside the specified area.

```javascript
function enableShortcuts(method) {
  switch (method) {
    case 'mouseOver': //If the param reads 'mouseOver' shortcuts are only enabled when the mouse is inside of the player.
      wrapper.addEventListener('mouseenter', mouseInPlayer);
      break;
    case 'playerFocused': //If the param reads 'playerFocused' shortcuts are only enabled when the player is focused.
      document.addEventListener('focus', playerFocused, true);
      break;
    default:
      document.addEventListener('keydown', getPressedKey); //Else player shortcuts are always enabled.
  }
}
enableShortcuts('mouseOver');
```

***

## Full JavaScript Code Example

```javascript
const wrapper = document.getElementById('yourPlayerId');
const element = document.querySelector('.video-js');

const player = new THEOplayer.Player(element, {
  ui: {
    fluid: true,
  },
  libraryLocation: '/YourTHEOplayerLibraryLocation/',
  license: 'your-license-here',
});

player.source = {
  sources: ['https://example.mpd'],
  metadata: {
    images: [
      {
        src: 'https://thumbnail.jpg',
      },
    ],
    releaseDate: '2014-10-31',
    releaseYear: 2014,
    subtitle: 'My movie subtitle',
    title: 'My movie',
    type: 'movie',
  },
};

function togglePlay() {
  if (player.paused) {
    player.play();
  } else {
    player.pause();
  }
}

function rewind() {
  player.currentTime -= 5; //Subtracts 5 seconds
}

function forward() {
  player.currentTime += 5; //Adds 5 seconds
}

function increaseVolume() {
  player.volume = Math.min(player.volume + 0.05, 1); //Increases volume by 5%
}

function decreaseVolume() {
  player.volume = Math.max(player.volume - 0.05, 1); //Lowers volume by 5%
}

function toggleFullScreen() {
  if (player.presentation.currentMode === 'fullscreen') {
    player.presentation.requestMode('inline');
  } else {
    player.presentation.requestMode('fullscreen');
  }
}

function toggleMute() {
  player.muted = !player.muted;
}

function preventStandardHotKeyActions(event) {
  event.stopPropagation();
  event.preventDefault();
}

function getPressedKey(event) {
  const pressedKey = event.key;
  let action;
  switch (pressedKey) {
    case ' ':
      action = togglePlay(); //Pauses or Unpauses with Space
      break;
    case 'ArrowLeft':
      action = rewind(); //Rewinds the video with the Left Arrow Key
      break;
    case 'ArrowRight':
      action = forward(); //Forwards the video with the Right Arrow Key
      break;
    case 'ArrowUp':
      action = increaseVolume(); //Increases volume with the Up Arrow Key
      break;
    case 'ArrowDown':
      action = decreaseVolume(); //Lowers volume with the Down Arrow Key
      break;
    case 'f':
      action = toggleFullScreen(); //Toggle Fullscreen mode with the 'F' Key
      break;
    case 'm':
      action = toggleMute(); //Toggle Mute with the 'M' Key
      break;
  }
  if (action && pressedKey !== 'Control' && pressedKey !== 'Alt' && pressedKey !== 'Shift') {
    action();
    preventStandardHotKeyActions(event); //Stops the default key behavior like jumping the page with space.
  }
}

function playerFocused() {
  if (wrapper.contains(document.activeElement)) {
    document.addEventListener('keydown', getPressedKey);
  } else {
    document.removeEventListener('keydown', getPressedKey);
  }
}

function mouseInPlayer() {
  //Checks if the mouse is inside the player wrapper area
  document.addEventListener('keydown', getPressedKey);
  wrapper.addEventListener('mouseleave', mouseOutPlayer);
}

function mouseOutPlayer() {
  //Checks if the mouse leaves the player wrapper area
  wrapper.removeEventListener('mouseleave', mouseOutPlayer);
  document.removeEventListener('keydown', getPressedKey);
}

function enableShortcuts(method) {
  switch (method) {
    case 'mouseOver': //If the param reads 'mouseOver' shortcuts are only enabled when the mouse is inside of the player.
      wrapper.addEventListener('mouseenter', mouseInPlayer);
      break;
    case 'playerFocused': //If the param reads 'playerFocused' shortcuts are only enabled when the player is focused.
      document.addEventListener('focus', playerFocused, true);
      break;
    default:
      document.addEventListener('keydown', getPressedKey); //Else player shortcuts are always enabled.
  }
}

//enableShortcuts('mouseOver');    //Enable player shortcuts only when mouse inside the player area.
enableShortcuts(); //Always enable shortcuts.
```

## Additional Resources

* [preventDefault()](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault)

* [stopPropagation()](https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation)

* [List of Key values](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)

---

# How to embed an iframe

Embedding a video player through an `<iframe>` can be interesting for a number of reasons:

* You might want to easily embed your videos across different domains and brands.
* You want to facilitate social sharing on third-party websites through your viewers.
* You are using a service or framework which doesn't allow you to include custom JavaScript, but it does allow you to embed an `<iframe>`.

Regardless of your use-case: you can embed THEOplayer through an iframe on first-party and third-party domains.

The goal of this guide is to help you embed THEOplayer through an `<iframe>` by going through the following topics:

1. [\<iframe>](#iframe): what is an iframe?

2. [Implementation](#implementation): which THEOplayer APIs are relevant and how can I achieve my use-case?

   1. [Allowing embedding](#allowing-embedding)
   2. [Enabling fullscreen and other features](#enabling-fullscreen-and-other-features)
   3. [Deciding approaches](#deciding-approaches)
   4. [Considering limitations](#considering-limitations)
   5. [Adjusting UI and UX](#adjusting-ui-and-ux)

3. [Demo](#demo): resulting implementation and live demo

4. [Resources](#resources)

Just want to copy-paste code and view a live example? [Skip to the demo](#demo).

## \<iframe>

An iframe is an HTML tag, the [`<iframe>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) tag, which allows you to embed an HTML page (i.e. "a website") on your HTML page (i.e. "your website"). You come across iframes all the time when using the web. (*That YouTube video on that news website you just visited? That's an iframe. That Facebook or Twitter post which was embedded on that blog? That could also be an iframe. They are all HTML website pages which are embedded on another HTML website page.*)

```html
<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/GrOJkhIXifc"
  frameborder="0"
  allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen
></iframe>
```

The code snippet above represent an actual `<iframe>` tag. Adding this code snippet to the HTML of your website would embed <https://www.youtube.com/embed/GrOJkhIXifc>, which is a YouTube video. If you opened this link, you would see that it is a YouTube video which fits the entire size of your browser window.

![iframe YouTube example](/pr-932/assets/images/iframe-youtube-example-6ca52c8e328a867b3160d2e231adcd7a.png "iframe YouTube example")

As you can see, [the embedded page](https://www.youtube.com/embed/GrOJkhIXifc) is quite different from the "[real](https://www.youtube.com/watch?v=GrOJkhIXifc)" YouTube page. When you design and develop a page which should be embedded through an `<iframe>`, you optimize for this embedding use-case. Typically, your component (e.g. a video player) fills the entire browser window, and thus has a width and height of 100%. (You set the width and height of the `<iframe>` on your page, as can be seen from the above code snippet.)

We won't go into the pros and cons of using an `<iframe>` in this article. We do argue that you should try to avoid using iframes, because iframes can be [evil](https://www.blackburnlabs.com/iframe-evil/) and can cause [usability issues](https://www.ostraining.com/blog/webdesign/against-using-iframes). From our experience, most services and companies are trying to phase out iframes, and are instead embedding JavaScript code to render the same result.

## Implementation

When embedding THEOplayer through an `<iframe>` tag, you need to do a couple of things:

1. [Allow embedding](#allowing-embedding): you need to use the THEOplayer API to allow for embedding.
2. [Enable fullscreen (and other features)](#enabling-fullscreen-and-other-features): you might want to use the HTML API to allow certain features like fullscreen and autoplay.
3. [Decide approach](#deciding-approaches): you need to decide on a strategy on how to dynamically load content.
4. [Consider limitations](#considering-limitations): you need to be aware of the constraints and how to address them.
5. [Adjust UI and UX](#adjusting-ui-and-ux): you need to style your iframe tag.

### Allowing embedding

You can easily allow embedding by setting the `isEmbeddable`-flag in the THEOplayer's [`PlayerConfiguration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerConfiguration) to `true`, as demonstrated by the code snippet below.

```js
let playerConfiguration = {
  // ...
  libraryLocation: '</path-to-library>/',
  license: 'your-license-here',
  isEmbeddable: true,
  // ...
};
let player = new THEOplayer.Player(element, playerConfiguration);
```

Embedding THEOplayer through an `<iframe>` tag is disabled by default. Why?

* Your THEOplayer license (i.e. your THEOplayer Web SDK) has a set of whitelisted domains. Typically, you only whitelist domains where you deploy THEOplayer. Deploying your THEOplayer SDK on a non-whitelisted domain would result in a license error. Thus, you need to specify that a page which contains your THEOplayer Web SDK, may be embedded. You do not need to whitelist every domain which embeds your `<iframe>` tag.
* When embedding is allowed, and if third-party websites are embedding your THEOplayer video player, then those parties generate additional video views and impressions for your license. (Remember: THEOplayer charges you by the number of impressions.) Additionally, if your [iframe approach](#deciding-approaches) allows people to specify the video URL through the `<iframe>` tag, then third-parties could potentially piggyback for free on your (commercial) license if they reverse-engineer your approach.

### Enabling fullscreen and other features

If you want to allow your viewers to open your iframe in fullscreen, then you must explicitly enable the [`allowfullscreen`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allowfullscreen)-attribute.

```html
<iframe src="player.html" frameborder="0" scrolling="no" width="100%" height="100%" allowfullscreen=""> </iframe>
```

On top of this, you want to configure the [`allow`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#attr-allow)-attribute and track its evolution.

```html
<iframe
  src="player.html"
  frameborder="0"
  scrolling="no"
  width="100%"
  height="100%"
  allow="accelerometer; autoplay; encrypted-media; fullscreen; gyroscope; picture-in-picture"
  allowfullscreen=""
>
</iframe>
```

Through this attribute, you can allow your iframe to access a set of [features](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy#Directives), like autoplay, Picture-in-Picture, DRM, and more.

### Deciding approaches

The previous section explains how you can make THEOplayer compatible with an `<iframe>`, but it doesn't explain the possible approaches for loading content and configurations. What do we mean with this? When you are embedding THEOplayer, you still need a mechanism to configure a stream URL and toggle settings like autoplay and mute. You don't want to create one HTML page per stream and combination of settings. Instead, you want to be able to embed one HTML page which is capable of dynamically configuring your stream and settings.

There are at least three approaches to pass along your stream URL and settings:

1. **Direct**: you pass along your stream URL and settings directly through the iframe URL and/or query parameters of the iframe URL. For example, your iframe URL could be similar to `https://cdn.theoplayer.com/demos/iframe/theoplayer.html?autoplay=false&muted=false&preload=none&src=//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8`. On your iframe page, you (*i.e. either your front-end or back-end*) would read out these four query parameters (or GET parameters), and then use those values to set up your THEOplayer instance and configure your stream URL and settings.
2. **Indirect**: you pass along an identifier through the iframe URL and/or query parameters of the iframe URL. For example, your iframe URL could be similar to `https://cdn.theoplayer.com/demos/iframe/video-123`. On your iframe page, you would read out this identifier (e.g. `video-123`), and do a call to a content management system (CMS) requesting data matching your identifier. This CMS would then return the actual stream URL and settings. You use this response to set up your THEOplayer instance and configure your stream URL and settings.
3. **Hybrid**: you pass along your stream URL indirectly or directly, and your settings directly or indirectly. For example, your iframe URL could be similar to `https://cdn.theoplayer.com/demos/iframe/video-123?autoplay=false&muted=false&preload=none`. On your iframe page, you would read out this identifier and the query parameters, and use the identifier to fetch the stream URL through a CMS, but configure your settings through the values of your query parameters.

Every approach has its trade-offs. Using a CMS is useful to avoid third-parties from loading their own streams through your iframe setup, but it does require you to spend resources on a CMS.

### Considering limitations

As hinted in the [\<iframe>](#iframe)-section, using iframes can incur some limitations. Some of those limitations can be addressed, and some of those cannot due to technological platform constraints.

* [Fullscreen might not work on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-does-fullscreen-not-behave-as-expected-on-ios.md): you can fix this.
* [Autoplay might not work](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-is-video-not-playing-automatically.md): you can fix this.
* [Chromecast does not work on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-does-chromecast-not-work-on-ios-chrome.md): you cannot address this.
* [The Visibility API does not work on IE11 and Safari](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-visibilty-api-doesnt-work-in-iframe-on-safari-and-ie11.md): you cannot address this on IE11.
* [Picture-in-Picture does not work as expected](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/picture-in-picture.md#code-examples): you can address this by using native Picture-in-Picture instead, or by building a similar feature which creates a floating iframe component.

### Adjusting UI and UX

Styling the `<iframe>` element on your page, and the actual page behind the `<iframe>`, can be a challenge. Additionally, you may want to alter your user experience by implementing messaging between your page and the embed page.

1. [Styling \<iframe>](#styling-iframe)
2. [Styling embedded page](#styling-embedded-page)
3. [Communication between parent page and embedded page](#communication-between-parent-page-and-embedded-page)

#### Styling \<iframe>

Styling your `<iframe>` element is a breeze if you're using a fixed width and height: you can directly configure those through the `width` and `height` attributes as demonstrated below.

```html
<iframe src="player.html" frameborder="0" scrolling="no" width="800px" height="450px" allowfullscreen=""> </iframe>
```

However, more common is to rely on responsive styling, and not knowing your specific width and height. On top of wanting a responsive iframe, you usually want to respect the aspect ratio of your video. Basically, you want your `<iframe>` container to automatically -and appropriately- scale when the size of your browser window changes.

```html
<iframe src="player.html" frameborder="0" scrolling="no" width="100%" style="width:100%;aspect-ratio:16/9"> </iframe>
```

The above snippet demonstrates how you can achieve this.

* You want to set an `aspect-ratio` in the `style` of your `<iframe>` element. We've used `16/9` for a 16:9 aspect ratio, but you can change this to e.g. `4/3` for a 4:3 video.
* You want to disable the border around your iframe by specifying `frameborder="0"` and disable scrolling by specifying `scrolling="no"`.
* You want to maximize the width of your iframe by specifying `width="100%"`. The height will be computed automatically based on the `aspect-ratio`.

Of course, rather than using inline styling through the `style` attribute, you could also achieve the same through CSS. And, of course: this is not the only way to style your iframe element, but just one of the many ways.

#### Styling embedded page

You usually want your video player to fit the full width and height of your browser window, because it should fill the entire iframe container element.

```html
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <meta http-equiv="x-ua-compatible" content="ie=edge" />
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        width: 100%;
        height: 100%;
      }

      .theoplayer-container {
        width: 100%;
        height: 100%;
      }
    </style>
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin"></div>
  </body>
</html>
```

The above snippet demonstrates a way to achieve this.

* You want to remove all padding and margin, and give your document a `width` and `height` of 100%.
* You want your video player container, the `<div>` in the above snippet, to fill the entire document by setting its `width` and `height` to 100%.

#### Communication between parent page and embedded page

You may have a need for messaging between your parent page and your embedded page.

* If your video or ad break ends, you want to hide (or destroy) the iframe container on your parent page.
* If someone clicks a control button in your video player, you may want to know about this action in your parent page.

You can achieve this with cross-document messaging and the `postMessage` API. Please refer to the resources below to learn more on this:

* [Stackoverflow.com: how to communicate between iframe and the parent side](https://stackoverflow.com/questions/9153445/how-to-communicate-between-iframe-and-the-parent-site)
* [MDN: postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)
* [JavaScript.info: cross-window communication](https://javascript.info/cross-window-communication)

## Demo

The video player below this paragraph is embedded through an `<iframe>` tag.

[Embedded THEOplayer](https://cdn.theoplayer.com/demos/iframe/theoplayer.html?autoplay=false\&muted=false\&preload=none\&src=//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8)

We selected the "direct approach" by leveraging query parameters, as demonstrated by the code snippet below.

```html
<iframe
  src="https://cdn.theoplayer.com/demos/iframe/theoplayer.html?autoplay=false&muted=false&preload=none&src=//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8"
  title="Embedded THEOplayer"
  frameborder="0"
  scrolling="no"
  width="100%"
  style="width:100%;aspect-ratio:16/9"
  allow="accelerometer; autoplay; encrypted-media; fullscreen; gyroscope; picture-in-picture"
  allowfullscreen=""
>
</iframe>
```

If we had configured a different `src`-value, like `https://cdn.theoplayer.com/demos/iframe/theoplayer.html?autoplay=false&muted=false&preload=none&src=//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8`, then it would have loaded a different video. Note that unmuted autoplay may not be possible, and that you may have to [combat autoplay policies](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-combat-autoplay-policies.md).

You can see the code of the iframe HTML page at <https://cdn.theoplayer.com/demos/iframe/theoplayer.html>, or in the code snippet below.

```html
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <meta http-equiv="x-ua-compatible" content="ie=edge" />
    <link rel="stylesheet" type="text/css" href="/path/to/libraryLocation/ui.css" />
    <script src="/path/to/libraryLocation/THEOplayer.js"></script>
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        width: 100%;
        height: 100%;
      }

      .theoplayer-container {
        width: 100%;
        height: 100%;
      }
    </style>
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin"></div>
    <script>
      // https://stackoverflow.com/a/901144/588833
      // function to get URL query parameters by name
      function getParameterByName(name, url) {
        if (!url) url = window.location.href;
        name = name.replace(/[\[\]]/g, '\\$&');
        var regex = new RegExp('[?&]' + name + '(=([^&#]*)|&|#|$)'),
          results = regex.exec(url);
        if (!results) return null;
        if (!results[2]) return '';
        return decodeURIComponent(results[2].replace(/\+/g, ' '));
      }

      // initialize THEOplayer instance
      var element = document.querySelector('.theoplayer-container');
      var player = new THEOplayer.Player(element, {
        libraryLocation: '/path/to/libraryLocation/',
        license: 'your-license-here',
        ui: {
          width: '100%',
          height: '100%',
        },
        isEmbeddable: true,
      });

      // get query parameter values
      var autoplay = getParameterByName('autoplay') && getParameterByName('autoplay') == 'true';
      var muted = getParameterByName('muted') && getParameterByName('muted') == 'true';
      var preload = getParameterByName('preload');
      var src = getParameterByName('src');

      // set settings and stream URL
      player.autoplay = autoplay;
      player.muted = muted;
      player.preload = preload;
      player.src = src;
    </script>
  </body>
</html>
```

## Resources

* [Player API - PlayerConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerConfiguration)
* [iframe demo code](https://cdn.theoplayer.com/demos/iframe/theoplayer.html?autoplay=false\&muted=false\&preload=none\&src=//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8)
* [AMP](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/amp/getting-started.md) (consider translating your learning to the AMP framework)
* [MDN: iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)
* [ottball.com: lazy loading](https://ottball.com/lazy-loading-video/#embedded-players) (consider lazy loading for your iframes)

---

# How to implement a seamless transition between videos?

You may need an answer to this question if you want to play one video after the other without letting the user know the source has changed (to the user they will seem as if playing just one video). Similar questions may be:

* Is it possible to make 2 video files play one after the other without pause?
* How can I play a second video file after the first without the user notice what happened?
* How to make a forking video, one where the user can choose his/her own path?

**This result is achieved taking advantage of a HTML5 canvas element to cover the source change.** An example can be seen on [this page](http://cdn.theoplayer.com/demos/confluence/seamless-video-transition.html).

You can find the code of the page here below, opportunely commented to clarify how it works (hint: all interesting comments start with "COMMENT:" to aid the search).

Seamless video transitionExpand source

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <meta http-equiv="x-ua-compatible" content="ie=edge" />

    <title>Seamless video transition</title>
    <link
      rel="stylesheet"
      href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.5/css/bootstrap.min.css"
      integrity="sha384-AysaV+vQoT3kOAXZkl02PThvDr8HYKPZhNT5h/CXfBThSRXQ6jW5DO2ekP5ViFdi"
      crossorigin="anonymous"
    />
    <link rel="stylesheet" type="text/css" href="//cdn.theoplayer.com/dash/theoplayer/ui.css" />

    <script type="text/javascript" src="//cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>

    <style>
      canvas {
        width: 100%;
        height: 100%;
        position: absolute;
        display: none;
      }
      button {
        margin: 1em 0;
      }
    </style>
  </head>
  <body>
    <h1>Seamless video transition</h1>
    <div class="container">
      <div id="theoplayer-wrapper">
        <div class="video-js theoplayer-skin">
          <!-- COMMENT: a canvas element is set inside the THEOplayer wrapper. Initial sizes are set but will be reset when the canvas is called -->
          <canvas width="503px" height="283px"> </canvas>
        </div>
        <button id="sourcechange-btn">Change video</button>
      </div>
    </div>

    <script type="text/javascript">
      var element = document.querySelector('.video-js');

      // COMMENT: some player configuration here - interesting but nothing related to this example
      var player = new THEOplayer.Player(element, {
        ui: {
          //fluid: true
          width: '800',
          height: '450',
        },
        libraryLocation: '//cdn.theoplayer.com/dash/theoplayer/',
      });
      player.autoplay = true;
      player.source = {
        sources: '//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
      };

      //COMMENT: objective: hide the transition between 2 videos.
      // To do this, we:
      // - detect when the source must be changed
      // - save the last frame in the canvas poster that is placed on top of the player
      // - we load the new source
      // - when playback starts, the canvas is hidden

      // COMMENT: this detects the first play event and calls the function firstplay()
      player.addEventListener('sourcechange', function () {
        //console.log("A new SourceDescription has been set.");
        player.removeEventListener('playing', firstplay);
        player.addEventListener('playing', firstplay);
      });

      // COMMENT: on click we call writeToCanvas() and change the player source after a small delay (time is needed for the canvas content to be loaded)
      var button = document.querySelector('#sourcechange-btn');
      button.addEventListener('click', () => {
        writeToCanvas();
        setTimeout(function () {
          player.src =
            'https://amssamples.streaming.mediaservices.windows.net/bb34a723-f69a-4231-afba-dc850f9e3da8/ChildOfThe90s.ism/manifest(format=m3u8-aapl)';
        }, 50);
      });

      // COMMENT: canvas is hidden when the first play event is fired
      function firstplay(event) {
        var canvas = document.querySelector('canvas');
        player.removeEventListener('playing', firstplay);
        //console.log("first play event!", event);
        canvas.style.display = 'none';
      }

      // COMMENT:
      // (1) Canvas is detected, its sizes adapted to those of the player and it gets the last frame as content.
      // (2) It is displayed as block (as opposed to the initial "none")
      function writeToCanvas() {
        var canvas = document.querySelector('canvas');
        canvas.setAttribute('width', player.videoWidth + 'px');
        canvas.setAttribute('height', player.videoHeight + 'px');
        var ctx = canvas.getContext('2d');
        canvas.style.display = 'block';
        player.canvas.drawImage(ctx, 0, 0);
      }
    </script>
  </body>
</html>
```

The result on your page can also be improved implementing [cache](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Cache) for your videos.

---

# How to work around browser cache with new THEOplayer SDK libraries?

In some cases you may experience problems related to cached versions of the THEOplayer library (e.g. if you are dealing with users who are getting expired license errors even though you already deployed new SDK libraries).

Related questions may be:

* Can I implement a cachebuster on the THEOplayer library load?
* Can I force a file to be called always from the server to prevent it from being fetched from the cache?
* How can I make sure that users always get the newest version of THEOplayer libraries I deployed?

## Cache

To reduce the internet usage and increase the responsiveness of a webpage, browsers use caching.

In simple terms, it may take a while to download a file (e.g. `THEOplayer.js`). The browser will therefore keep files stored locally in its cache for a certain amount of time for later usage. After some time, the browser will remove the file and update it the next time you visit that page. By keeping it locally, the browser can use the local file instead of having to fetch a new one. This makes your page faster, but the downside is that the browser may not get the most up-to-date file.

If you really need users to use the latest library you serve or renew at the expiration date of your contract, you may still run into caching issues.

Luckily there are some ways to ensure that the browser updates the file.

## Ways to force the browser to update

### Change the file path

A good way to ensure that the file gets updated, is by changing the file path. If your file path is different, the browser will see all the files within that new directory as new files and download them again.

You could, for example, keep track of the version of THEOplayer or the deploy date by using different directories:

For example:

```html
<yoursite.com
  >/resource/file/path/5.5.0/THEOplayer.js
  <yoursite.com
    >/resource/file/path/5.5.1/THEOplayer.js <yoursite.com>/resource/file/path/31-01-2023/THEOplayer.js</yoursite.com></yoursite.com
  ></yoursite.com
>
```

### Add a variable at the end of the file

Another way to trick the browser into updating the file immediately, is by adding a variable at the end of the filename. This variable on its own, in the case of `THEOplayer.js`, won't change anything to the file.

By adding something like the version or the date, you can be sure that the browser updates the file.

For example:

```html
<yoursite.com>/resource/file/path/THEOplayer.js?d=10012023 <yoursite.com>/resource/file/path/THEOplayer.js?v=5.5.1</yoursite.com></yoursite.com>
```

**Note**: For HLS playback, the player uses worker files. These workers must be present in the `libraryLocation` set on the player configuration. You do not need to link to them in the webpage as they are dynamically called from the `libraryLocation`.

The downside of adding a variable at the end of the filename is that these worker files will not get this variable and therefore may still be cached, resulting in a `THEOplayer.js` file from a newer version, while the workers are still on the old version from the cache. In this case you may see an error from the player like the following:

`THEOplayer workers could not be loaded. please check that the worker's version matches THEOplayer's version (5.5.1)`

You can make sure that the variable is a different one for each call, thus requesting the server version of the file each time (and ignoring the cached version).

Here's an example on how to dynamically generate such a cachebuster variable in JavaScript (taken from [this original article](https://www.virendrachandak.com/techtalk/cachebuster-code-in-javascript/)):

```html
<script type="text/javascript">
  var cachebuster = Math.round(new Date().getTime() / 1000);
  document.write('<scr' + 'ipt type="text/javascript" src="external.js?cb=' + cachebuster + '"></scr' + 'ipt>');
</script>
```

## Related articles

* [How to update an SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/how-to-update-a-sdk.md)
* [License](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/license/introduction.md)
* [How to reduce data usage on mobile devices on mobile web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-reduce-data-usage-on-mobile-devices.md)

---

# How to customize quality selection and labels on the default UI (MP4)

Some of our customers prefer MP4 assets over HLS/MPEG-DASH ones. One major downside to this approach is that Adaptive Bitrate Streaming (ABR) is not possible with such streams, as they don't have a playlist with multiple qualities.

To counter this, we've made it possible to pass on a list of MP4 qualities & switch between them manually, to improve the overall UX. What is nice about this piece of integration code, is that it can be tweaked and applied to customize other parts of the default UI as well!

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | N/A         | N/A     | N/A      | N/A            | N/A            |

## Customizing the quality selector and labels

This example explains how to customize quality selection & labels for MP4 assets.

##### Web SDK

First of all, we need to [set up the player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md). Then, the different MP4 qualities of the same asset need to be stated, along with the corresponding resolutions:

```js
// set your resolutions and sources
var resolutions = [
  { name: '360p', src: 'https://example.com/demos/sample-videos/low.mp4' },
  { name: '540p', src: 'https://example.com/demos/sample-videos/medium.mp4' },
  { name: '720p', src: 'https://example.com/demos/sample-videos/high.mp4' },
];
```

Now for the slightly trickier part: Removing current & adding custom menu

```js
var currentTime, wasPaused;
var settingsMenu = player.ui.getChild('ControlBar').getChild('SettingsButton').menu;

// Remove built-in quality sub menu
settingsMenu.removeMenuItem(settingsMenu.menuItems[0]);

// Create custom quality sub menu
var qualityMenuItem = settingsMenu.addSubMenuItem({
  index: 0,
});
var qualityMenuTitle = document.createElement('span');
qualityMenuTitle.className = 'theo-settings-control-menu-item-title';
qualityMenuTitle.innerHTML = 'Quality';
var qualityMenuValue = document.createElement('span');
qualityMenuValue.className = 'theo-settings-control-menu-item-value';
qualityMenuItem.el().appendChild(qualityMenuTitle);
qualityMenuItem.el().appendChild(qualityMenuValue);
qualityMenuItem.subMenu.menuHeader.el().innerHTML = 'Quality';
var qualityItems = resolutions.map(function (resolution) {
  var qualityItem = qualityMenuItem.subMenu.addMenuItem();
  qualityItem.el().innerHTML = resolution.name;
  qualityItem.on('click', function () {
    selectQuality(resolution);
  });
  return qualityItem;
});

// Getting the player/UI in the correct state
function selectQuality(resolution) {
  qualityMenuValue.innerHTML = resolution.name;
  currentTime = player.currentTime;
  wasPaused = player.paused;
  player.src = resolution.src;
  player.currentTime = currentTime;
  if (!wasPaused) {
    player.play();
  }
  var qualityItem = qualityItems[resolutions.indexOf(resolution.name)];
  qualityItems.forEach(function (item) {
    item.selected(item === qualityItem);
  });
}
selectQuality(resolutions[0]);
```

##### Android SDK

Android SDK does not have a built-in UI. It also does not support JavaScript injection. However, you can implement a similar custom quality selection menu using [Open Video UI for Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui.md) and following the same logic for Web SDK.

##### iOS SDK

iOS SDK does not have a built-in UI. It also does not support JavaScript injection. However, you can implement a similar custom quality selection menu on your custom UI following the same logic for Web SDK.

You can now select multiple qualities of the same MP4 asset!

![Customize quality selection](/pr-932/assets/images/customize-quality-selection-e65dfce41a9308baad45748bb40589d8.png "Customize quality selection")

---

# How to get frame-accurate currentTime display in the UI Control bar

This article will show you how to display a frame-accurate currentTime on your THEOplayer instance UI control bar. For more information regarding the currentTime itself, please refer to the [reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer).

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | No       | Yes            | N/A            |

## Changing the currentTime UI display

At this moment there is no official THEOplayer feature to display a frame-accurate currentTime in the UI Controlbar. The following snippets rewrite the innerHTMLText of the currentTime element.

##### Web SDK

```js
function secondsToHms(d) {
  d = Number(d);
  console.log(player.currentTime);
  var ms = d % 1;
  var h = Math.floor(d / 3600);
  var m = Math.floor((d % 3600) / 60);
  var s = Math.floor((d % 3600) % 60);

  var hDisplay = h < 10 ? '0' + h : h;
  var mDisplay = m < 10 ? '0' + m : m;
  var sDisplay = s < 10 ? '0' + s : s;
  var msDisplay = ms.toFixed(3);
  //var msDisplay = d.toPrecision() -player.currentTime.toFixed();
  return hDisplay + ':' + mDisplay + ':' + sDisplay + '.' + String(msDisplay).split('.')[1];
}

setInterval(function () {
  document.querySelector('.vjs-current-time-display').innerText = secondsToHms(player.currentTime);
}, 1);

player.addEventListener('durationchange', function (e) {
  document.querySelector('.vjs-duration').innerText = secondsToHms(Math.floor(e.duration));
});
```

##### Android & iOS SDK

This can be done through JavaScript injection: [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)

## Remarks

With the same logic, slightly modified, you could also decide to show the frame number for that second instead of the milliseconds.

## Resources

* [API reference - player properties](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer)

---

# How to play an LCEVC source with THEOplayer

This article will show you how to play an LCEVC encoded source in THEOplayer. If you are not familiar with THEOplayer, we strongly recommend reading the [getting started documentation for web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md) first.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | No          | No      | No       | No             | No             |

## Prerequisites

#### 1. Your THEOplayer SDK needs to have the 'lcevc' feature enabled.

You can quickly check using `THEOplayer.features`. The feature is only available from THEOplayer 4.0 onwards.

#### 2. You need to include V-Nova's [LCEVC Decoder for Web](https://docs.v-nova.com/v-nova/lcevc/sdk/lcevc-decoder-for-web-lcevcdecjs) on the page.

This example below uses the latest version of the LCEVCdecJS library that is maintained by V-Nova:

```js
<script type="text/javascript" src="https://unpkg.com/lcevc_dec.js@latest/dist/lcevc_dec.min.js"></script>
```

## Setting the source

After your player is correctly configured you can set your LCEVC source, but you need to also include `lcevc: true` on the SourceDescription so that the player knows how to configure the correct playback pipeline:

##### DASH example

```js
player.source = {
  sources: {
    type: 'application/dash+xml',
    src: 'path/to/your/source/master.mpd',
    lcevc: true,
  },
};
```

##### HLS example

```js
player.source = {
  sources: {
    type: 'application/x-mpegurl',
    src: 'path/to/your/source/master.m3u8',
    lcevc: true,
  },
};
```

## Remarks

LCEVC enhanced playback only works on modern browsers that support Media Source Extensions (MSE). If the platform does not support MSE (for example: Safari on iOS), the player will fall back to native playback without LCEVC enhancements.

---

# How to use THEOplayer as a JavaScript module

As of THEOplayer 6.0, THEOplayer can also be used as a [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). Instead of loading the library through a `<script>` tag in your HTML, you `import` it directly from your JavaScript code.

Using JavaScript modules has several advantages:

* It's easier to manage dependencies per file, rather than maintaining a long list of `<script>` tags and keeping them in the right order.
* If multiple JavaScript files `import` the same module, the module is only loaded once. (On the other hand, multiple `<script>` tags with the same `src` attribute will load and execute the script multiple times.)
* When you use a bundler for your web app, your bundler can more easily understand the dependencies between your files and generate a single output bundle of your entire app.

Additionally, since JavaScript modules are only supported in modern web browsers, THEOplayer can use more modern JavaScript syntax in its JavaScript module (such as [async/await](https://caniuse.com/async-functions)). This results in smaller files, which load and execute faster on your viewer's devices.

> **Note** If you need to support older browsers (such as older smart TVs), you should stick with a classic `<script>` tag. [See the getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md).

In this article, we will set up a simple web page using JavaScript modules with the THEOplayer SDK on Web. The outcome of this article is the template below.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="/path/to/ui.css" />
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
    <script type="module">
      import * as THEOplayer from '/path/to/THEOplayer.esm.js';

      let element = document.querySelector('.theoplayer-container');
      let player = new THEOplayer.Player(element, {
        libraryLocation: '/path/to/your-theoplayer-folder/',
        license: 'your_license_string',
      });

      player.source = {
        sources: [
          {
            src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
            type: 'application/x-mpegurl',
          },
        ],
      };
    </script>
  </body>
</html>
```

## Prerequisites

See [the prerequisites in our getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md#prerequisites).

## Basic setup

Now, we're ready to set up THEOplayer on your website. This guide explains how you implement THEOplayer in four steps:

1. We'll [start from a basic HTML file](#step-1-set-up-an-html-file), with no mention of THEOplayer.
2. In the [second step](#step-2-including-the-theoplayer-library), we'll explain what the THEOplayer library is and how you can include it. We'll do the same for the default THEOplayer UI.
3. In the [third step](#step-3-the-video), we'll describe how you play a video stream through THEOplayer.
4. In the [fourth step](#step-4-the-result), we'll give a final overview.

### Step 1: Set up an HTML file

When THEOplayer is used as a web video player, we will need a web page (i.e. HTML file) to embed THEOplayer and the code.

Note that a THEOplayer SDK license can only be used on whitelisted domains. You configure these domains when you create a THEOplayer Web SDK at <https://portal.theoplayer.com>.

Let's start with the following HTML file:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
  <body>
    <script type="module"></script>
  </body>
</html>
```

Pay attention to the `type="module"` attribute on the `<script>` tag. This informs the browser to execute it as a module, rather than as a classic script. This allows the code inside it to use `import` and `export` statements.

Next, we’ll include the THEOplayer SDK.

### Step 2: Including the THEOplayer library

To access the THEOplayer API and default UI, you must first include the THEOplayer library files. The JavaScript library exposes the THEOplayer API and the CSS library contains the default UI.

#### THEOplayer JavaScript library

The following line imports the THEOplayer JavaScript library, and gives you access to the THEOplayer API.

```html
<script type="module">
  import * as THEOplayer from '/path/to/THEOplayer.esm.js';
</script>
```

The path of the `import` statement is the URI of the THEOplayer library that you wish to use. This could be something like: `/path/to/THEOplayer.esm.js`, where the URL is a link to your `THEOplayer.esm.js` file.

You must swap `/path/to/` with your CDN URL. For example, if your SDK is hosted on `https://example.com/vendor/theoplayer/`, then you'd write the following import:

```js
import * as THEOplayer from 'https://example.com/vendor/theoplayer/THEOplayer.esm.js';
```

#### THEOplayer CSS library

To use the default THEOplayer UI, you need to reference the THEOplayer CSS library:

```html
<link rel="stylesheet" type="text/css" href="/path/to/ui.css" />
```

The `<link>` tag includes a CSS file on a web page. Similar to the JavaScript library, you must swap `/path/to/` with your CDN URL.

Next, we’ll create a THEOplayer instance and configure a video stream.

### Step 3: The video

To play a video through the THEOplayer Web SDK, you must:

1. Create a video player container,
2. fetch this container through JavaScript,
3. create a THEOplayer instance associated with that container,
4. and configure a video stream for this instance.

The snippet below implements these 4 steps.

```html
<div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
<script type="module">
  import * as THEOplayer from '/path/to/THEOplayer.esm.js';

  let element = document.querySelector('.theoplayer-container'); // fetch THEOplayer container div

  let player = new THEOplayer.Player(element, {
    // instantiates video player
    libraryLocation: '/path/to/your-theoplayer-folder/', // references folder containing your THEOplayer library files (theoplayer.p.js, THEOplayer.js, ...)
    license: 'your_license_string', // references your THEOplayer SDK license
  });

  // HLS
  player.source = {
    sources: [
      {
        src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8', // sets HLS source
        type: 'application/x-mpegurl', // sets type to HLS
      },
    ],
  };

  // DASH
  // player.source = {
  //     sources : [{
  //         src : '//amssamples.streaming.mediaservices.windows.net/634cd01c-6822-4630-8444-8dd6279f94c6/CaminandesLlamaDrama4K.ism/manifest(format=mpd-time-csf)', // sets DASH source
  //         type : 'application/dash+xml' // sets type to MPEG-DASH
  //     }]
  // };
</script>
```

Let's break down the above snippet.

#### Create video player container

This `<div>` element creates a video player container.

```html
<div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
```

* The `theoplayer-container` class is used to fetch the container through JavaScript, as demonstrated by the snippet below.
* The `video-js theoplayer-skin vjs-16-9` classes load the default THEOplayer UI. You may omit `vjs-16-9` if you don't want a 16:9 container.

```javascript
let element = document.querySelector('.theoplayer-container');
```

#### Create THEOplayer instance

The snippet below creates a THEOplayer instance for a container with a specific [Player Configuration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerConfiguration).

```js
let player = new THEOplayer.Player(element, {
  // instantiates video player
  libraryLocation: '/path/to/your-theoplayer-folder/', // references folder containing your THEOplayer library files (theoplayer.p.js, THEOplayer.js, ...)
  license: 'your_license_string', // references your THEOplayer SDK license
});
```

Similar to the JavaScript and CSS library, you must swap out `'/path/to/your-theoplayer-folder/'` and `'your_license_string'`.

For example, if your SDK is hosted on `https://example.com/vendor/theoplayer/` and your license string is `ABCD1234`, then you would instead configure the snippet below:

```js
var player = new THEOplayer.Player(element, {
  libraryLocation: 'https://example.com/vendor/theoplayer/',
  license: 'ABCD1234',
});
```

You can read more about configuring the `license` at the [License section](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/license/introduction.md).

#### Configure video stream

The snippet below configures a HLS video stream for the THEOplayer instance.

```js
player.source = {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8', // sets HLS source
      type: 'application/x-mpegurl', // sets type to HLS
    },
  ],
};
```

To configure a DASH stream instead, you must set `type` to `'application/dash+xml'` instead of `'application/x-mpegurl'`, as demonstrated by commented out code in one of the earlier snippets.

In the next step we'll put everything together.

### Step 4: The result

We're done! Here's the complete code again, which you can put on your web server:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="/path/to/ui.css" />
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
    <script type="module">
      import * as THEOplayer from '/path/to/THEOplayer.esm.js';

      let element = document.querySelector('.theoplayer-container');
      let player = new THEOplayer.Player(element, {
        libraryLocation: '/path/to/your-theoplayer-folder/',
        license: 'your_license_string',
      });

      player.source = {
        sources: [
          {
            src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
            type: 'application/x-mpegurl',
          },
        ],
      };
    </script>
  </body>
</html>
```

## Next steps

Ready to learn more?

* Go through our [how-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md) to learn about [UI customization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/introduction.md), [advertising](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/introduction.md), [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md), [casting](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/introduction.md), [analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/introduction.md) and other topics.
* Check out our [API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer).
* Try out samples from our [GitHub](https://github.com/THEOplayer).

---

# How to use MultiView

This article will go over how to work with THEOplayer's MultiViewPlayer. As the setup is very similar to using normal THEOplayer, we strongly recommend reading the [getting started documentation for web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md) first.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | No          | No      | No       | No             | No             |

## Prerequisites

#### 1. Your THEOplayer SDK needs to have the 'multiview' feature enabled.

You can quickly check using `THEOplayer.features`. The feature is only available from THEOplayer 4.3 and onwards. This feature is included by default in the [@theoplayer/extended](https://www.npmjs.com/package/@theoplayer/extended) npm package.

#### 2. You need to have a THEOplayer license which is compatible with MultiView

This can be done through <https://portal.theoplayer.com>.

## Basic setup

To make a `MultiViewPlayer`, add the following code to your page:

```html
<div class="theoplayer-container video-js theoplayer-skin vjs-16-9"></div>
<script src="/path/to/THEOplayer.js"></script>
<script>
  const element = document.querySelector('.theoplayer-container'); // fetch THEOplayer container div

  const player = new THEOplayer.MultiViewPlayer(element, {
    // instantiates the MultiView player
    libraryLocation: '/path/to/your-theoplayer-folder/', // references folder containing your THEOplayer library files (THEOplayer.js, ...)
    license: 'your_license_string', // references your THEOplayer SDK license
  });
</script>
```

Now that the `MultiViewPlayer` is instantiated, you'll need to load each view separately:

```js
// set the name of the source
player.load('Star Wars', {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8', // sets HLS source
      type: 'application/x-mpegurl', // sets type to HLS
    },
  ],
});

// set the name of the source
player.load('Big Buck Bunny', {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8', // sets HLS source
      type: 'application/x-mpegurl', // sets type to HLS
    },
  ],
});
```

The `MultiViewPlayer` has a slightly different API from the general THEOplayer, so for more information we refer to the [documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/MultiViewPlayer).

---

# Migrating to THEOplayer Web SDK 10.x

This article will guide you through updating to THEOplayer Web SDK version 10 (from version 9), and the changes needed in your code.

## Update THEOplayer

Run the following command to install THEOplayer Web SDK version 10:

```bash
npm install theoplayer@10
```

If you're using the [Open Video UI for Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/web/open-video-ui.md) or one of [our connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web.md), make sure to update them to the latest version too to ensure proper support for THEOplayer version 10.

```bash
npm update @theoplayer/web-ui
npm update @theoplayer/conviva-connector-web
```

# Google DAI ad UI enabled by default

`GoogleImaConfiguration.useAdUiElementForSsai` is now enabled by default. This allows Google DAI ads to show additional UI elements on top of the player if needed (such as a skip button for skippable ads). See the [Google DAI documentation on `adUiElement`](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/html5/reference/js/StreamManager#StreamManager) for more information.

If you want to disallow ads with custom UI elements, you can manually set this option to `false` in your `GoogleImaConfiguration`. This will instruct THEOplayer to use the (deprecated) [`StreamManager.setClickElement`](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/html5/reference/js/StreamManager#setClickElement) method instead. Note that the use of this deprecated API is discouraged, and may stop being supported in the future.

## Replace usages of deprecated APIs

Some properties and methods that were previously deprecated have been removed from the API. Update your code to use the new APIs instead.

* Removed support for THEOlive sources using `source.integration = 'theolive'`. THEOlive sources must now have their `type` set to `'theolive'` instead.
* Removed `'verizon-media'` as a valid source integration ID for Uplynk sources (previously Verizon Media). Uplynk sources must now have their `integration` set to `'uplynk'` instead.
* Removed THEOlive publication events (`publicationloadstart`, `publicationloaded` and `publicationoffline`), use the equivalent distribution events instead (`distributionloadstart`, `endpointloaded` and `distributionoffline` respectively).
* Removed `PlayerConfiguration.verizonMedia`, use `PlayerConfiguration.uplynk` instead.
* Removed `PlayerConfiguration.vr`, since it was no longer used by the player.
* Removed `AdBreakEvent.ad`, use `AdBreakEvent.adBreak` instead.
* Removed `THEOplayerAdDescription` type, use `CsaiAdDescription` instead.
* Removed `MediaTailorSource.adParams`, use `MediaTailorSource.adsParams` instead.
* Removed `WebVTTRegion.identifier`, use `WebVTTRegion.id` instead.

---

# Getting Started on webOS

This guide will help you integrate your Dolby OptiView Player SDK on webOS.

Since webOS IDE is [no longer available](https://webostv.developer.lge.com/develop/tools/ide-introduction) as of February 2022, you will need to set up [webOS CLI](https://webostv.developer.lge.com/develop/tools/cli-installation), optionally in combination with the [webOS TV VS Code Extension](https://webostv.developer.lge.com/develop/tools/vsce-installation).

The focus of this article is using our [sample apps for webOS](https://github.com/THEOplayer/samples-webos).

You may also find the [Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md) guide useful.

## Prerequisites

1. Make sure that the [webOS CLI](https://webostv.developer.lge.com/develop/tools/cli-installation) is correctly installed on your system.
2. Validate that the CLI is correctly set up on your environment by invoking `ares` at the command line of a new terminal. If the command is recognized, you are correctly set up. If not, please go over the steps on the CLI installation guide again.
3. Optionally you can also install the official VS Code extension listed [here](https://marketplace.visualstudio.com/items?itemName=webostvsdk.webostv) to quickly connect/deploy to your devices.

# Download the starter files

* Download the starter code from [our sample repository](https://github.com/THEOplayer/samples-webos).

* The folder contains all the necessary files to quickly deploy a THEOplayer solution to a webOS device.

* The packager will use the `app` folder to build an IPK package
  * the `app` folder contains a crude solution with entry point `index.html`; the only thing left is to put your THEOplayer library files in the `libs` folder.

* The folder `example-with-UI` contains a more elaborate example,

  * To use it, optionally modify the code and run the following commands:
    ```shell
    cd example-with-ui
    npm i
    npm run build
    ```
  * Next, copy the `js` folder, the `css` folder and the `index.html` file to the app folder (overwriting the existing files).

## Setting up the physical device

### Prerequisites

1. Make sure you have created an [LG Developer Account](https://webostv.developer.lge.com/login). You will need this to login to the Developer Tools app on the physical device.
2. Download the Developer Tools app to the TV from the LG Content Store, login with your LG account and follow the instructions to set the device in developer mode (a restart is required).

### Make a connection

* In case you downloaded the webOS TV VS Code extension, you can use it to link your development environment to the physical device (from the webOS TV Devices menu on the left-hand toolbar).

* Manually set up (use the guideline provided by LG):

  1. Open terminal and enter `ares-setup-device`

     1. Choose `add`.
     2. Enter device name: tv (feel free to use another name).
     3. Enter the IP address of the LG TV (open the Developer Tools app on the device to find out).
     4. Use port `9922` for physical devices (for a simulator the port is 6622).
     5. SSH user: this should be set to `prisoner` (**important note**: do not use the proposed `root`, this will not work).
     6. Enter an optional description.
     7. Authentication: choose option `password`.
     8. Leave the actual password blank.
     9. Save.

  2. Next, you need to acquire a key from the physical device to be able to securely interact:

     1. Enter `ares-novacom -d tv --getkey` (make sure to use the device name you chose in case you changed it).
     2. You will be prompted for a key; the key will be visible in the Developer Tools app on the physical device.

## Simulator

**Important Note**: the use of a simulator is not recommended as simulators do not implement all features (e.g. DRM).

If you decide to use a simulator, follow the guide [here](https://webostv.developer.lge.com/develop/tools/simulator-installation) to install one.

# Running the app

**Note**: please visit the [LG webOS developer site](https://webostv.developer.lge.com/) to get more info on commands, tools and guidelines.

First make sure to `cd` into the root folder (this is the parent of app folder). Next, run the following commands.

### Packaging

```shell
ares-package  ./app --outdir ./
```

### Installation

Default name for the created package is *webos.theo\_1.0.0\_all.ipk*, *tv* is the device name that was given when setting up the device in the previous step.

This step will fail if there is no connection to the device, e.g. the device is offline, not on the same network.

```shell
ares-install webos.theo_1.0.0_all.ipk  -d tv
```

### Launch

App ID is by default *web.theo* (you can change this in `appinfo.json`)

```shell
ares-launch webos.theo  -d tv
```

### Debug

```shell
ares-inspect webos.theo -d tv --open
```

---

# Getting started on Tizen

This how-to guide describes how to set up a Tizen application using the Dolby OptiView Player SDK on Tizen.

You may also find the [Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md) to be useful.

## Set-up

For brevity, the set-up is split up over multiple pages:

* [Setting up Tizen Studio](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/tizen/installing-tizen-studio.md)
* [Generating a certificate](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/tizen/generating-a-certificate.md)
* [Setting up and deploying on a physical device (recommended)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/tizen/setting-up-physical.md)
* [Setting up and deploying on an emulator (less recommended)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/tizen/setting-up-emulator.md)

## Getting started with the THEOplayer Tizen reference app

### Prerequisites

* Generate a Tizen SDK build via the [THEOplayer portal](https://portal.theoplayer.com/).
* Download the [reference app project](https://github.com/THEOplayer/samples-tizen)
* Read the README to get started. There is one at the root level and one in the two examples.
* Import the project in Tizen Studio.

Go to File -> Open Projects from File System.

![](/pr-932/assets/images/import-1-8aaecab1b94a589fec742e47cd9bd394.jpg)

Select the directory, then press Finish.

![](/pr-932/assets/images/import-2-abd40c64a1537775af117e7460865ac6.jpg)

### Reference app structure structure

* **example-with-ui/**

  * Contains a Tizen project with a UI. Follow the readme for more instructions.
  * **css/**
    * CSS styles as used in the app.
  * **js/**
    * JavaScript files as used in the app. The compiled result of `src/` is put in here.
  * **src/**
    * The source code of the UI application. Change or replace as desired.
  * **libs/**
    * (Insert your THEOplayer Tizen SDK here.)
  * **index.html**
    * Entry point of application.
  * **config.xml**
    * Permissions of the app.
  * **package.json**
    * Contains the commands required to build the UI.

* **minimum-example/**

  * Contains a very minimal Tizen project example. No UI included.
  * **libs/**
    * (Insert your THEOplayer Tizen SDK here.)
  * **index.html**
    * Entry point of application.
  * **config.xml**
    * Permissions of the app.

---

# Installing the Tizen developer tools

* Check if your device meets the [Tizen developer tools prerequisites](https://docs.tizen.org/application/tizen-studio/setup/prerequisites/).
* Download the Tizen developer tools at [Tizen development tools](https://developer.tizen.org/development/tizen-studio/download). You can decide to either install the IDE or CLI, but in this guide we assume you use the IDE.
* In Tizen Studio, make sure to install the Tizen package extensions:

Go to Tools, then Package Manager

![](/pr-932/assets/images/tizen-extensions-1-832ce052ecfc2dd8d85a0d3a9b9a5b5c.jpg)

Install everything under Tizen SDK tools under Main SDK.

**Note:** Make sure to close Tizen Studio before installing, otherwise an empty warning message might show up that stops you from completing the installation.

![](/pr-932/assets/images/tizen-extensions-2-e020322a3a7e70ab03067a6c823f80fd.jpg)

Install the latest tv extensions under Extension SDK.

![](/pr-932/assets/images/tizen-extensions-3-d03d447b80a0502d74d51d1de6b5bcdf.jpg)

---

# Setting up a Tizen device for debugging

Tizen requires a certificate to launch an application on a (physical) device. Below are the steps on how to create one:

Go to Tools → Certificate Manager

![](/pr-932/assets/images/tizen-certificate-1-5dc8da6607b5532e09b09217eef7d97d.jpg)

In the Certificate Manager, click the Add (plus) button to generate a new certificate.

![](/pr-932/assets/images/tizen-certificate-2-4e3672ee2e2fa8cbdcc9d518f3b8ce6a.jpg)

Generate a Tizen Certificate.

![](/pr-932/assets/images/tizen-certificate-3-f5c7f5477ef3c33c0438c1f3be6aa5df.jpg)

Give your certificate a profile name (name is free to pick).

![](/pr-932/assets/images/tizen-certificate-4-e8aad0838f338202f6ff8872dd43bbe1.jpg)

Pick “Create a new author certificate” if you have never used one. If you already have one, then you can choose to select an existing author certificate instead.

![](/pr-932/assets/images/tizen-certificate-5-c08251931d95a82bbd050cd021acc7d5.jpg)

If you decided to create a new author certificate, you will get this screen. Fill in the fields as requested with your own. Fill in a password. You can add additional fields when opening the “More details” component.

![](/pr-932/assets/images/tizen-certificate-6-c6150763460504d017b394943dbaf60d.jpg)

Pick “Use the default Tizen distributor certificate”.

![](/pr-932/assets/images/tizen-certificate-7-81c3b7cc09f35744d96bcedf37a7e2ee.jpg)

If everything went well, a pop-up will appear indicating that the certificate profile has been created.

![](/pr-932/assets/images/tizen-certificate-8-dc745be45feb631cdeb6a54185c9194c.jpg)

Your certificate should now be available for selection.

![](/pr-932/assets/images/tizen-certificate-9-1cc2cd3b3d2d3d75e8ccd0160942aff2.jpg)

---

# Deploying a test app on a physical Tizen device

Both the physical Tizen device as the development computer must be on the same network.

## Set-up

### Tizen device

* Go to the home menu (home button) and navigate to apps. Launch it.

* Use the 123-key (or numbers) to type 12345. A menu will prompt.

* Enable Developer mode.

  * Type in the local IP-address of the laptop you want to deploy a build from. They must be on the same network.
  * Reboot Tizen device by long-pressing (about 2 seconds) the power button on the remote.

### Set-up on development device

* Go to Tizen Studio. Open Tools -> Device Manager.

* Open Remote Device Manager (the icon with a pc and a smart tv)

  * Add Tizen device via its IP-address, connect and confirm.
  * The Tizen IP-address can be found under Settings -> General -> Network -> Network Status -> IP Settings.
  * Enable connection with remote device.

## Launching on a physical Tizen device

* Ensure the connection is established. You can check this under Tools → Devices.
* In Tizen Studio, click right on the project (under Project Explorer). Pick either "Run as" or "Debug as".

---

# Deploying a test app on a Tizen emulator

We strongly recommend using a physical Tizen device. If this is not possible, using an emulator can be a back-up.

## Set up

* If you haven't done so, make sure to install the Tizen TV Emulator:
  * In Tizen Studio: Tools -> Package Manager -> Extension SDK -> TV Extensions 5.5
* Create the emulator by pressing the "Create" button and following the steps.

## Launching

* In Tizen Studio, click right on the project (under Project Explorer). Pick either:

  * Run As -> Tizen Web Simulation Application
  * Debug As -> Tizen Application

## Known limitations of emulators:

* AVPlay is unavailable.
* DRM is unavailable due to a missing Content Decryption Module (CDM).
* `manifest.json` permissions are ignored for emulators. Make sure to test on a physical device, as they are more strict.

---

# Getting started with Angular

*A brief guide on how to build a THEOplayer in an Angular environment.*

Note that this information is for a basic player in a local testing environment. Additional information may be needed for specific cases.

## Step-by-step guide:

1. Make sure you have the Angular CLI installed

```shell
npm install -g @angular/cli
```

2. If needed, create a new workspace and initial application ng new appname

3. In the root project, create a new component for the player (in this case appname)

```shell
cd appname
ng generate component theoplayer
```

4. add the THEOplayer.js files to the root project
5. In index.html add the /THEOplayer.js as a script tag and /ui.css as a stylesheet
6. In theoplayer.component.html add

```html
<div class="theoplayer-container video-js theoplayer-skin"></div>
```

7. In theoplayer.component.ts add

```typescript
import { Component, OnInit } from '@angular/core';
import * as THEOplayer from '../../../THEOplayer.js';

@Component({
  selector: 'app-theoplayer',
  templateUrl: './theoplayer.component.html',
  styleUrls: ['./theoplayer.component.css'],
})
export class TheoplayerComponent implements OnInit {
  constructor() {}

  ngOnInit() {
    this.createPlayer();
  }

  createPlayer() {
    const element = document.querySelector('.theoplayer-container');

    const player = new THEOplayer.Player(element, {
      libraryLocation: '',
    });

    player.source = {
      sources: [
        {
          src: '//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
          type: 'application/x-mpegurl', // sets type to MPEG-DASH
        },
      ],
    };
  }
}
```

Then

```typescript
import * as THEOplayer from '../../../THEOplayer.js';
```

will make sure to get everything needed from our sdk.

9. In app.component.html add the following code to display the player in the app component.

```html
<app-theoplayer></app-theoplayer>
```

10. Profit.

## Related articles

* <https://angular.io/guide/quickstart>

---

# Getting started with React

There is a sample app using THEOplayer as a React component available [on our GitHub](https://github.com/THEOplayer/samples-react-js).

## Project setup

```shell
git clone https://github.com/THEOplayer/samples-react-js.git
```

Creates a local clone of the project

```shell
npm install
```

Installs the necessary dependencies. This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app). You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).

```shell
npm start
```

Compiles and runs the app in the development mode. Open <http://localhost:3000> to view it in the browser. The page will reload if you make edits. You will also see any lint errors in the console.

## Creating and using a component

### `src/THEOplayerWrapper.js`

is an example implementation of a React Component that wraps the THEOplayer.js module. You can extend this wrapper to support whatever THEOplayer API that you want to use.

### `src/App.js`

uses the `Player` component exported by `THEOplayerWrapper.js` and specifies a source for the player to play.

## Going to Production

The THEOplayer library provided in this sample is currently targeted to the latest version and is set to run on **localhost only**

### Getting a license

To run THEOplayer in production you will need a valid THEOplayer HTML5 SDK set up to run on your domain. You can use your existing license or get one for free on [THEOportal](http://portal.theoplayer.com).

### Updating the project

You will need to update some files that reference the THEOplayer.js and THEOplayer.css files:

* `src/THEOplayerWrapper.js`, -- Please replace the URL of the `libraryLocation` to the URL or folder where your THEOplayer files (THEOplayer.js, THEOplayer.d.js, etc.) are residing.
* `src/App.js`
* `public/index.html` -- Please replace the links to the THEOplayer assets with your own URLs.

---

# Getting started with NuxtJS

This how-to guide describes how to integrate THEOplayer with NuxtJS framework.

## Instructions

1. Open your favorite IDE and then a terminal and install Vue CLI component:

```shell
npx create-nuxt-app theoplayer-nuxtjs-sample
```

2. Follow the installation process (please note these instructions assume you’ve chosen npm as a module packager)

3. Once the app is created, execute the following commands:

```shell
cd theoplayer-nuxtjs-sample
npm install
npm run dev
```

4. The default application should be served under: <http://localhost:3000/>

5. Reference the THEOplayer Web SDK by editing file `nuxt.config.js` like the following:

```js
export default {
  mode: 'spa',
  /*
   ** Headers of the page
   */
  head: {
    title: process.env.npm_package_name || '',
    meta: [
      { charset: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      {
        hid: 'description',
        name: 'description',
        content: process.env.npm_package_description || '',
      },
    ],
    link: [
      { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' },
      {
        rel: 'stylesheet',
        type: 'text/css',
        href: '//cdn.theoplayer.com/dash/theoplayer/ui.css',
      },
    ],
    script: [
      {
        type: 'text/javascript',
        src: '//cdn.theoplayer.com/dash/theoplayer/THEOplayer.js',
      },
    ],
  },
  /*
   ** Customize the progress-bar color
   */
  loading: { color: '#fff' },
  /*
   ** Global CSS
   */
  css: [],
  /*
   ** Plugins to load before mounting the App
   */
  plugins: [],
  /*
   ** Nuxt.js dev-modules
   */
  buildModules: [
    // Doc: https://github.com/nuxt-community/eslint-module
    '@nuxtjs/eslint-module',
  ],
  /*
   ** Nuxt.js modules
   */
  modules: [],
  /*
   ** Build configuration
   */
  build: {
    /*
     ** You can extend webpack config here
     */
    extend(config, ctx) {},
  },
};
```

6. Add the new component named Player.vue under this path: components/Player.vue

```html
<template>
  <div ref="theoplayer" class="theoplayer-container video-js theoplayer-skin vjs-16-9 THEOplayer"></div>
</template>

<script>
  import { mapState } from 'vuex';
  export default {
    computed: mapState({
      source: (state) => state.source,
    }),
    mounted() {
      this.playerInit();
    },
    methods: {
      playerInit() {
        const player = new window.THEOplayer.Player(this.$refs.theoplayer, {
          fluid: true,
          libraryLocation: '//cdn.theoplayer.com/dash/theoplayer/',
        });
        player.source = {
          sources: this.source,
        };
      },
    },
  };
</script>
<style>
  .THEOplayer {
    width: 50%;
    margin: 0 auto;
  }

  .video-js.vjs-16-9 {
    padding-top: 28.12%;
    width: 50%;
  }
</style>
```

7. Please note that vuex is used to pass the player source, for this purpose add index.js file under this path: store/index.js with following content:

```js
export const state = () => ({
  source: null,
});

export const mutations = {
  setSource(state, source) {
    state.source = source;
  },
};
```

8. Now, we are ready to reference the player component in the index.vue like following:

```html
<template>
  <div class="container">
    <div>
      <logo />
      <player />
      <h1 class="title">theoplayer-nuxtjs-sample</h1>
      <h2 class="subtitle">THEOplayer nuxtjs sample app</h2>
      <div class="links">
        <a href="https://nuxtjs.org/" target="_blank" class="button--green"> Documentation </a>
        <a href="https://github.com/nuxt/nuxt.js" target="_blank" class="button--grey"> GitHub </a>
      </div>
    </div>
  </div>
</template>
<script>
  import Logo from '~/components/Logo.vue';
  import Player from '~/components/Player.vue';

  export default {
    components: {
      Logo,
      Player,
    },
    created() {
      this.$store.commit('setSource', [
        {
          type: 'application/x-mpegurl',
          src: '//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
        },
      ]);
    },
  };
</script>

<style>
  .container {
    margin: 0 auto;
    min-height: 100vh;
    display: flex;
    justify-content: center;
    align-items: center;
    text-align: center;
  }

  .title {
    font-family:
      'Quicksand',
      'Source Sans Pro',
      -apple-system,
      BlinkMacSystemFont,
      'Segoe UI',
      Roboto,
      'Helvetica Neue',
      Arial,
      sans-serif;
    display: block;
    font-weight: 300;
    font-size: 100px;
    color: #35495e;
    letter-spacing: 1px;
  }

  .subtitle {
    font-weight: 300;
    font-size: 42px;
    color: #526488;
    word-spacing: 5px;
    padding-bottom: 15px;
  }

  .links {
    padding-top: 15px;
  }
</style>
```

9. This should result in a page which includes the THEOplayer component.

## Build Setup

```bash
# install dependencies
$ npm run install

# serve with hot reload at localhost:3000
$ npm run dev

# build for production and launch server
$ npm run build
$ npm run start

# generate static project
$ npm run generate
```

For detailed explanation on how things work, check out [Nuxt.js docs](https://nuxtjs.org).

---

# Getting started with VueJS

This how-to guide describes how to integrate THEOplayer with VueJS framework.

### Customize configuration

See [Configuration Reference](https://cli.vuejs.org/config/).

## A step-by-step guide:

1. Open your favorite IDE and then a terminal and install Vue CLI component:

```shell
npm install vue
```

2. If needed, create a new workspace and initial application:

```shell
vue create theoplayer-vuejs-sample
```

3. Choose your preferred configuration by choosing one of the presets from the list.

4. Once the project is created, you should see a successful message.

5. Go to root project and start application using instructions:

```shell
cd theoplayer-vuejs-sample
npm run serve
```

6. As a result you should be able to browse the default page under the following URL: <http://localhost:8080/>

7. Reference the THEOplayer files in index.html like following:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width,initial-scale=1.0" />
    <link rel="icon" href="<%= BASE_URL %>favicon.ico" />
    <title>theoplayer-vuejs-sample</title>
    <link rel="stylesheet" type="text/css" href="//cdn.theoplayer.com/dash/theoplayer/ui.css" />
  </head>

  <body>
    <noscript>
      <strong>We're sorry but theoplayer-vuejs-sample doesn't work properly without JavaScript enabled. Please enable it to continue.</strong>
    </noscript>
    <div id="app"></div>
    <script type="text/javascript" src="//cdn.theoplayer.com/dash/theoplayer/THEOplayer.js"></script>
    <!-- built files will be auto injected -->
  </body>
</html>
```

8. In the src/components/ add a new file and name it Player.vue, then add the following snippet:

```html
<template>
  <div class="theoplayer-container video-js theoplayer-skin vjs-16-9 THEOplayer" ref="theoplayer"></div>
</template>

<script>
  export default {
    props: ['source'],
    mounted: function () {
      this.playerInit();
    },
    methods: {
      playerInit() {
        const player = new window.THEOplayer.Player(this.$refs.theoplayer, {
          fluid: true,
          libraryLocation: '//cdn.theoplayer.com/dash/theoplayer/',
        });
        player.source = {
          sources: this.source,
        };
      },
    },
  };
</script>
<style>
  .THEOplayer {
    width: 50%;
    margin: 0 auto;
  }

  .video-js.vjs-16-9 {
    padding-top: 28.12%;
    width: 50%;
  }
</style>
```

9. Then you can reference the Player component in different parts of the app and pass the source, for instance you can change App.vue like following:

```html
<template>
  <div id="app">
    <img alt="Vue logo" src="./assets/logo.png" />
    <Player :source="source" v-if="source" />
  </div>
</template>

<script>
  import Player from './components/Player.vue';

  export default {
    name: 'app',
    components: {
      Player,
    },
    data: function () {
      return {
        source: [
          {
            type: 'application/x-mpegurl',
            src: '//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
          },
        ],
      };
    },
  };
</script>
<style>
  #app {
    font-family: 'Avenir', Helvetica, Arial, sans-serif;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
    text-align: center;
    color: #2c3e50;
    margin-top: 60px;
  }
</style>
```

## Including THEOplayer library assets

1. Create a new folder named i.e. libs under public folder and copy the THEOplayer WebSDK files there.

2. Change the index.html to reference local files:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width,initial-scale=1.0" />
    <link rel="icon" href="<%= BASE_URL %>favicon.ico" />
    <title>theoplayer-vuejs-sample</title>
    <link rel="stylesheet" type="text/css" href="libs/THEOplayer/ui.css" />
  </head>

  <body>
    <noscript>
      <strong>We're sorry but theoplayer-vuejs-sample doesn't work properly without JavaScript enabled. Please enable it to continue.</strong>
    </noscript>
    <div id="app"></div>
    <script type="text/javascript" src="libs/THEOplayer/THEOplayer.js"></script>
    <!-- built files will be auto injected -->
  </body>
</html>
```

3. In the Player.vue modify libraryLocation like following:

```js
const player = new window.THEOplayer.Player(this.$refs.theoplayer, {
  fluid: true,
  libraryLocation: './libs/THEOplayer',
});
```

---

# Getting started with AMP

*A brief guide on how to build a THEOplayer in an AMP environment.*

Note that this information is for a basic player in a testing environment. Additional information may be needed for specific cases.

## AMP

Accelerated Mobile Pages (AMP) is an open-source HTML framework. More information about AMP is available at <https://amp.dev/>.

## Step-by-step guide:

1. Have a [valid AMP page](https://validator.ampproject.org/). *(Let's call this page A.)*
2. Prepare an embeddable page which can be served through an [`<amp-iframe>`](https://amp.dev/documentation/components/amp-iframe/?format=websites). *(Let's call this page B.)* Read more about THEOplayer and iframes [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/how-can-we-embed-iframe.md). It's your responsibility to decide the most optimal approach for your use-case. You can use <https://cdn.theoplayer.com/demos/iframe/iframe.html> as a starting point to prepare your page.
3. Upload page B to a different (sub) domain than page A in order to adhere to the [iframe origin policy](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-iframe-origin-policy.md).
4. Embed page B into page A by using an `<amp-iframe>`. It's your responsibility to decide the most optimal approach for your use-case. You can use the snippet below as an example.

```html
<!doctype html>
<html ⚡>
  <head>
    <meta charset="utf-8" />
    <title>amp-iframe</title>
    <script async src="https://cdn.ampproject.org/v0.js"></script>
    <!--  Import the amp-iframe component in the header. -->
    <script async custom-element="amp-iframe" src="https://cdn.ampproject.org/v0/amp-iframe-0.1.js"></script>
    <!-- You can use the `amp-bind` extension to dynamically change an iframe src. -->
    <script async custom-element="amp-bind" src="https://cdn.ampproject.org/v0/amp-bind-0.1.js"></script>
    <link rel="canonical" href="<% canonical %>" />
    <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1" />
    <style amp-boilerplate>
      body {
        -webkit-animation: -amp-start 8s steps(1, end) 0s 1 normal both;
        -moz-animation: -amp-start 8s steps(1, end) 0s 1 normal both;
        -ms-animation: -amp-start 8s steps(1, end) 0s 1 normal both;
        animation: -amp-start 8s steps(1, end) 0s 1 normal both;
      }
      @-webkit-keyframes -amp-start {
        from {
          visibility: hidden;
        }
        to {
          visibility: visible;
        }
      }
      @-moz-keyframes -amp-start {
        from {
          visibility: hidden;
        }
        to {
          visibility: visible;
        }
      }
      @-ms-keyframes -amp-start {
        from {
          visibility: hidden;
        }
        to {
          visibility: visible;
        }
      }
      @-o-keyframes -amp-start {
        from {
          visibility: hidden;
        }
        to {
          visibility: visible;
        }
      }
      @keyframes -amp-start {
        from {
          visibility: hidden;
        }
        to {
          visibility: visible;
        }
      }
    </style>
    <noscript
      ><style amp-boilerplate>
        body {
          -webkit-animation: none;
          -moz-animation: none;
          -ms-animation: none;
          animation: none;
        }
      </style></noscript
    >
    <style amp-custom>
      #sample-resizable-iframe div[overflow] {
        text-align: center;
        background: #f9f7f7;
        line-height: 36px;
      }
    </style>
  </head>
  <body>
    <amp-iframe
      width="500"
      height="281"
      title="THEOplayer demo"
      layout="responsive"
      sandbox="allow-scripts allow-same-origin allow-popups"
      allowfullscreen
      frameborder="0"
      src="https://cdn.theoplayer.com/demos/iframe/iframe.html"
    >
      <amp-img layout="fill" src="https://cdn.theoplayer.com/demos/iframe/pixel.png" placeholder></amp-img>
    </amp-iframe>
  </body>
</html>
```

5. Once again: upload page A to a different (sub) domain than page B in order to adhere to the [iframe origin policy](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-iframe-origin-policy.md). For example, you can put page B on <https://iframe.website.com/player.html> and page A on <https://www.website.com/a-random-video.html>

An example application of this step-by-step guide is available [here](https://f.hubspotusercontent20.net/hubfs/2163521/Demo_zone/amp-iframe-example.html).

## Alternatives

Some video players offer a **custom AMP tag**. For example, YouTube offers this through [`<amp-youtube>`](https://amp.dev/documentation/components/amp-youtube/?format=websites). Under the hood, these video players also leverage an `<iframe>`. Although custom AMP tags are primarily syntax sugar, it is arguably a more developer-friendly implementation than `<amp-iframe>`. The advantage of using `<amp-iframe>` is flexibility: you are in full control of the page you're embedding.

Feel free to [contact us](https://www.theoplayer.com/contact) if you would like to contribute to `<amp-theoplayer>`.

## Related content

* <https://amp.dev/>
* <https://amp.dev/documentation/components/amp-iframe/?format=websites>
* <https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-iframe-origin-policy.md>

---

# Getting started with WordPress

[WordPress](https://wordpress.org/) is a popular CMS. [Wikipedia](https://en.wikipedia.org/wiki/WordPress) writes that it was originally aimed at blogs, but nowadays it's leveraged for all sorts of use-cases. It's not uncommon to want to embed a video player on a WordPress website.

This guide describes one approach to integrate the THEOplayer Web SDK in an open-source WordPress.org deployment by using *Custom Code Blocks* and the *Code Editor*. As a developer, you can also opt for different approaches, as explained by <https://webdesign.tutsplus.com/tutorials/how-to-add-custom-javascript-to-your-wordpress-site--cms-34368> and <https://www.wpbeginner.com/wp-tutorials/how-to-easily-add-javascript-in-wordpress-pages-or-posts/>.

Interested in our WordPress 5+ plugin? [Reach out to us](https://www.theoplayer.com/contact) if you want to evaluate this.

## Selected approach

We use "[Custom HTML blocks](https://wordpress.com/support/wordpress-editor/blocks/custom-html-block/)" and the "[Code Editor](https://wordpress.com/support/editors/)" as our approach. Both features are accessible by default in a fresh WordPress.org 5.5 installation. This approach allows us to embed JavaScript and CSS libraries, as well as write unique JavaScript and HTML code for a specific page. Why is that relevant? When using the THEOplayer Web SDK, you use JavaScript to specify which video stream you want to configure, and typically you want to configure one (or more) unique streams per page.

### Alternatives

#### Code Embed plugin

You could use the [Code Embed plugin](https://wordpress.org/plugins/simple-embed-code/#description) because it allows you to embed unique JavaScript code per page (or post).

Other popular plugins, like [Insert Headers and Footers](https://wordpress.org/plugins/insert-headers-and-footers/), allow you to insert code which is shared across all posts and pages. This is useful for tracker scripts or pixels (like Google Analytics), but less so for video players which should only be integrated on some pages and with a unique video stream configured per page. You could consider using a plugin like "Insert Headers and Footers" to load the THEOplayer JavaScript and CSS files (i.e. the SDK files) on every page, but you typically still want to embed some unique JavaScript code per page to configure the unique video stream.

*We have no affiliation with these plugins or their creators. They were just the first applicable plugins which popped up when looking.*

#### \<iframe>

You can embed THEOplayer through an `<iframe>` instead of through JavaScript. Please refer to "[How to embed an iframe](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/how-can-we-embed-iframe.md)" for more information on setting up an iframe.

## Step-by-step guide

### 1. WordPress.org deployment

You must have a valid WordPress.org deployment. We used WordPress version 5.5 in a [local MAMP set-up](https://skillcrush.com/blog/install-wordpress-mac/) when writing this article.

### 2. THEOplayer SDK

You must have the THEOplayer Web SDK library files (`THEOplayer.js`, `ui.css`, ...), or you must know how to refer to them and the `libraryLocation`. You've read through our [Web SDK Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md), and you understand all of its content.

### 3. Locate post or page

Navigate to the page where you want to integrate the THEOplayer Web SDK.

### 4. Include THEOplayer SDK

First off, you want to include the THEOplayer CSS file and THEOplayer JavaScript file by adding the code below through a Custom HTML block.

```html
<link rel="stylesheet" type="text/css" href="/path/to/libraryLocation/ui.css" />
<script type="text/javascript" src="/path/to/libraryLocation/THEOplayer.js"></script>
```

The screenshot below shows you how to access such a "Custom HTML block". ![WordPress Custom HTML](/pr-932/assets/images/wordpress-custom-html-e361f80bf642a46a6cd838a1861b40c7.png "WordPres Custom HTML")

### 5. Create container

Create the HTML `<div>` container which should load your video player instance.

Your Custom HTML block should now be similar to the code below.

```html
<link rel="stylesheet" type="text/css" href="/path/to/libraryLocation/ui.css" />
<script type="text/javascript" src="/path/to/libraryLocation/THEOplayer.js"></script>
<div class="video-js vjs-16-9 theoplayer-container theoplayer-skin"></div>
```

You can set the CSS of this container directly in the `<div>` tags by using `<div style="height: ...">`, or you could add additional CSS to your page.

We added `vjs-16-9` to the `<div class="...` because we want THEOplayer to render in a 16:9 aspect ratio. Sometimes, the CSS and styles of your WordPress theme might clash with THEOplayer's styling. It is your responsibility to identify styling issues caused by your theme. For example, the CSS of our WordPress skin tried to meddle with the width of our container, so we manually unset it as demonstrated below.

```html
<div class="video-js vjs-16-9 theoplayer-container theoplayer-skin" style="max-width: unset;"></div>
```

### 6. Configure video

Finally, you want to create your video player instance and configure a video stream for this player instance.

You can achieve this by expanding your Custom HTML block to resemble the snippet below:

```html
<link rel="stylesheet" type="text/css" href="/path/to/libraryLocation/ui.css" />
<script type="text/javascript" src="/path/to/libraryLocation/THEOplayer.js"></script>
<div class="video-js vjs-16-9 theoplayer-container theoplayer-skin" style="max-width: unset;"></div>
<script>
  var element = document.querySelector('.theoplayer-container');
  var player = new THEOplayer.Player(element, {
    libraryLocation: '/path/to/libraryLocation/',
    license: 'your-license-here',
  });

  player.source = {
    sources: [
      {
        src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
        type: 'application/x-mpegurl',
      },
    ],
  };
</script>
```

All of this should result in a demo similar to the screenshot below. ![WordPress Demo Screenshot](/pr-932/assets/images/wordpress-demo-screenshot-66c62d8dd0af8248b95aa77aecfca088.png "WordPres Demo Screenshot")

## Note

* Steps 4-6 are similar to our [Getting Started guide for Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md) so you might want to consider checking out that article as well.

---

# Introduction

THEOplayer and Uplynk are partners in the streaming industry. [Uplynk](https://www.uplynk.com/) offers services like encoding, transcoding, server-side ad-insertion, a CDN and more.

> **Verizon Media / Edgio**
>
> Uplynk is formerly known as **Verizon Media** and **Edgio**. We are moving away from any Verizon Media references in our API. These are now marked as deprecated and should be replaced by the Uplynk API.

Uplynk offers services which can enhance the API, UI and UX of video players and applications. The most popular services are called *Preplay*, *Ping* and *Asset Info*. THEOplayer integrates these services so that developers and viewers can benefit from them.

For example,

* Viewers can skip over ads;
* Viewers can see when an ad is playing (and stopping);
* Developers can define the behavior when viewers try to seek over an ad;
* Developers can query metadata to render a playlist in their application.

A live demo of THEOplayer's integration of Uplynk is available [here](https://cdn.theoplayer.com/demos/verizon-media/index.html).

![UplynkDemo](/pr-932/assets/images/VerizonMediaDemo-57db7aa1e91a449a9a1d708b999251d5.png "Uplynk Demo")

For more information on the integration and available APIs, continue your read on the pages below.

## [📄️Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/preplay.md)

[This article explains how to leverage the Uplynk Preplay API through THEOplayer. This API allows developers to pre-integrate with Uplynk's Preplay service.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/preplay.md)

## [📄️Uplynk Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ads.md)

[Uplynk offers support for server-side ad-insertion (SSAI).](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ads.md)

## [📄️Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ping.md)

[This article explains how to use Uplynk's Ping API.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ping.md)

## [📄️Uplynk configuration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/configuration.md)

[This article explains what is possible with an Uplynk configuration when setting up a THEOplayer instance.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/configuration.md)

## [📄️Uplynk interface](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/interface.md)

[This article explains how developers can hook into the Uplynk interface. This interface allows developers to query the available assets and ads in an Uplynk stream, its properties, and subscribe to its events.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/interface.md)

## [📄️What are the Uplynk challenges](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-are-the-uplynk-challenges.md)

[The purpose of this article is to group common challenges application developers might encounter when using Uplynk (formerly known as Verizon Media, Edgecast or Edgio) as the back-end.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-are-the-uplynk-challenges.md)

Sample Git projects are available on the following links:

* Web: <https://github.com/THEOplayer/samples-html5-sdk/tree/master/reference-apps/verizon-media-app>
* Android: <https://github.com/THEOplayer/samples-android-sdk/tree/master/Verizon-Media>
* iOS: <https://github.com/THEOplayer/samples-ios-sdk/tree/master/Verizon-Media>
* Roku: <https://github.com/THEOplayer/samples-roku-sdk/tree/master/verizon-app>

---

# Preplay

This article explains how to leverage the Uplynk Preplay API through THEOplayer. This API allows developers to pre-integrate with Uplynk's Preplay service.

Uplynk users can use an API (i.e. `Preplay`) to generate a streaming playlist given one or more assets or advertisements. The Uplynk back-end stitches the content together and allows for server-side ad-insertion (SSAI) when applicable. This document describes how THEOplayer users should configure their source to leverage this Preplay service.

Assumptions:

* THEOplayer assumes the availability of the Preplay API and Uplynk content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
* THEOplayer assumes that developers who are interested in this feature have a basic understanding of the Preplay API. Uplynk documents this service in the [API docs](https://api-docs.uplynk.com/#Develop/Preplayv2.htm).
* THEOplayer assumes that developers provide correct asset identifiers, as well as the proper content protection level.

## Stream Configuration (without ads)

The examples below demonstrate how to configure a stream through the Uplynk pre-integration.

```js
player.source = {
  sources: [
    {
      integration: 'uplynk',
      id: '<your_uplynk_asset_id>',
      preplayParameters: {}, // Optional, defaults to an empty object. These will be added as query parameters to the Preplay API call.
      assetType: 'asset', // Optional, defaults to 'asset'. Can also be 'channel' or 'event', following the Uplynk semantics, where 'asset' is On-demand content.
      contentProtected: false, // Optional, defaults to false.
    },
  ],
};

// Source example for an external id (with optional properties omitted)
player.source = {
  sources: [
    {
      integration: 'uplynk',
      id: {
        userId: '<your_uplynk_user_id>',
        externalId: '<your_uplynk_external_id>',
      },
    },
  ],
};

// Source example for a regular asset id with e.g. 'delay' parameter and 'sig' token parameter (with optional properties omitted)
player.source = {
  sources: [
    {
      integration: 'uplynk',
      id: '<your_uplynk_asset_id>',
      preplayParameters: {
        delay: '7200',
        rays: 'dcba',
        sig: '2ff94739b021912712adafeccd6fa291f11eef0648c3b18b30224b84e0590b4f',
      },
    },
  ],
};
```

The snippet above gives a quick overview of the structure of an Uplynk-specific source, also known as an [UplynkSource](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkSource). More information on certain properties:

* `id`: The ID field identifies the asset. Instead of a single string, developers can also specify an array of asset IDs as strings, which will be stitched into a continuous stream. The same goes for the `externalId` property in case an external ID is used in the source.

* `preplayParameters`: The `preplayParameters` object should have string-key-string-value combinations, which will be used as query parameters for the Preplay API call. Nested objects are not supported.

* `contentProtected`: Boolean value which will internally set any necessary content-protection information. No content-protection details have to be specified by the customer.

* **A Preplay request must include all parameters defined within the playback request, hence these parameters must be included in the THEOplayer source**. This request must also include a digital signature if the 'Require a token for playback' option is enabled in the back-end on the corresponding live channel. (See also : [Signing a Playback URL Tutorial](https://api-docs.uplynk.com/#Tutorials/Signed-Playback-URL-Tutorial.htm))

* Uplynk specific documentation on the available playback URL query parameters can be found on the Uplynk documentation site under [Customizing Playback via Parameters](https://api-docs.uplynk.com/#Setup/Customizing-Playback.htm).

* Some parameters can be excluded from the digital signature calculation. These parameters may enable certain use cases (e.g. DVR) and would for this reason be excluded from the digital signature.

## Stream Configuration (with ads)

The examples below demonstrate how to configure a stream with server-side ads through an [UplynkSource](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkSource).

```js
player.source = {
    sources: [{
        integration: 'uplynk',
        id: [
            '<your_uplynk_content_first_part>',
            '<your_uplynk_ad_break_1>',
            '<your_uplynk_content_middle_part>',
            '<your_uplynk_ad_break_2>',
            '<your_uplynk_content_last_part>'
        ],
        preplayParameters: {
            // Parameters here should specify the necessary ad parameters for the Preplay API
            ad.param1: 'param_val1',
            ad.param2: 'param_val2'
        },
    }]
}
```

More information on certain properties:

* `preplayParameters`: The `preplayParameters` object should have string-key-string-value combinations, which will be used as query parameters for the Preplay API call. Nested objects are not supported.

* **A Preplay request must include all parameters defined within the [playback request](https://api-docs.uplynk.com/#Setup/Playback-URLs.htm#LiveChannelPURLs), hence these parameters must be included in the THEOplayer source**. This request must also include a digital signature if the 'Require a token for playback' option is enabled in the back-end on the corresponding live channel. (See also : [Signing a Playback URL Tutorial](https://api-docs.uplynk.com/#Tutorials/Signed-Playback-URL-Tutorial.htm))

  > Note the confusion that the provided link only mentions signing the **playback URL**, even though we are describing using tokens for the call to the Preplay API. However, this process is also valid for signing the `preplayParameters`.

* Uplynk specific documentation on the available playback URL query parameters can be found on the Uplynk documentation site under [Customizing Playback via Parameters](https://api-docs.uplynk.com/#Setup/Customizing-Playback.htm).

* Some parameters can be excluded from the digital signature calculation. These parameters may enable certain use cases (e.g. DVR) and would for this reason be excluded from the digital signature.

## Preplay Response

THEOplayer automatically interprets the response returned by the Preplay service. However, if a developer wants to perform their own logic with the Preplay API response, then they can intercept the `preplayresponse` event.

```js
const listener = (event) => {
  console.log('Do something with the raw response of the Preplay API call', event.response);
};

player.uplynk.addEventListener('preplayresponse', listener);
```

## Using Tokens

Uplynk users often leverage URL signatures (i.e. tokens) to further secure their content -- on top of AES-128 encryption or studio DRM. A token is (typically) generated on back-end using an API key and a set of parameters, as described on [Signing a Playback URL Tutorial](https://api-docs.uplynk.com/#Tutorials/Signed-Playback-URL-Tutorial.htm).

> Note the confusion that the provided link only mentions signing the **playback URL**, even though we are describing using tokens for the call to the Preplay API. However, this process is also valid for signing the `preplayParameters`.

This set of parameters should also be passed along to the `preplayParameters` in an [UplynkSource](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkSource). If you do not configure the `preplayParameters` correctly in relation to your signature parameters, then the Preplay request made by THEOplayer will most likely return an invalid Preplay response, preventing THEOplayer from setting up your stream.

Let's consider a set-up where an Uplynk customer uses both URL signatures and multi-DRM. [When you do DRM, you must specify the `rmt` and `manifest` parameter](https://api-docs.uplynk.com/#Develop/Preplayv2.htm?Highlight=rmt), **or** you can set `allowrmt` to `1` instead. We recommend using the latter, as demonstrated in our Node.js reference project at [GitHub](https://github.com/THEOplayer/theoplayer-verizon-media-node-js).

So, let's say you want to generate a signature on your back-end that is compatible with HLS + FairPlay, MPEG-DASH + Widevine and MPEG-DASH + PlayReady, then it could look like the snippet below using `allowrmt`.

```js
let params = {
  v: '2',
  tc: '1',
  exp: 36000,
  rn: 12345,
  ct: 'a',
  cid: '<your_uplynk_asset_id>',
  allowrmt: 1,
};
let query = Object.keys(params)
  .map((key) => key + '=' + params[key])
  .join('&');
let sig = CryptoJS.HmacSHA256(query, '<your_api_secret>').toString();
params['sig'] = sig;
```

Now you want to communicate this entire `params` object to your client-side, and set it as the value for `preplayParameters`:

```js
player.source = {
  sources: {
    integration: 'uplynk',
    id: '<your_uplynk_asset_id>',
    preplayParameters: params,
    assetType: 'asset',
    contentProtected: true,
  },
};
```

When there's a mismatch between signature parameters and Preplay parameters, the Preplay response usually returns `Invalid token signature` and playback is not possible.

Having difficulties figuring out tokens, DRM and THEOplayer? Check out the Node.js reference project at [GitHub](https://github.com/THEOplayer/theoplayer-verizon-media-node-js).

# Related articles

* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ads.md)
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ping.md)

---

# Uplynk Ads

Uplynk offers support for [server-side ad-insertion](https://docs.uplynk.com/docs/ads) (SSAI).

This article explains how to use the Uplynk Ads API exposed by THEOplayer to hook into these SSAI advertisements. Additionally, this API allows developers to manipulate the ad-related UX and UI.

## Global Configuration

The examples below demonstrate how to pass along global configuration for the Uplynk ads. These settings can be overwritten.

##### Web SDK

```js
var player = new THEOplayer.Player(element, {
  uplynk: {
    defaultSkipOffset: 2, // Ad breaks added by SSAI are by default skippable after two seconds. Optional and defaults to unskippable.
    onSeekOverAd: 'play-last', // When seeking over ad breaks, this configuration decides how to snapback and play any missed ad breaks.
    // Possible values are currently 'play-none', 'play-last' and 'play-all' where 'play-none' is the default.
  },
  // ... Other configuration goes here
});
```

## Uplynk Ads API

> **Deprecation**
>
> Starting THEOplayer v8.12.0, it is possible to use the regular `player.ads` API for subscribing to Uplynk ad breaks, as described on [How to subscribe to ad events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-subscribe-to-ad-events.md). The implementation below can be expected to be removed in the future.

Specifying a source which contains server-side ads configured through the Uplynk pre-integration will have the player expose an Ads API specific to Uplynk, i.e. on the `player.uplynk.ads` API:

* `player.uplynk.ads.adBreaks`: Specifies all ad breaks that are currently in the stream by using SSAI through Preplay.
* `player.uplynk.ads.currentAdBreak`: If applicable, returns the ad break that is currently being played.
* `player.uplynk.ads.currentAds`: If applicable, returns a list of the current ads being played.
* `player.uplynk.ads.skip()`: If there is an ad break playing, and it is skippable, skip the ad break to the next content (or next seek point in case of snapback).

Calling the `player.uplynk.ads.skip()` function on a live stream will not have any effect.

In addition, event listeners are available to listen to new ad breaks:

* For adbreaks, the following events are defined:

  * *adbreakbegin*
  * *adbreakend*
  * *adbreakskip*
  * *addadbreak*
  * *removeadbreak*

* For ads, the following events are defined:

  * *adbegin*
  * *adchange*
  * *adend*
  * *adfirstquartile*
  * *admidpoint*
  * *adthirdquartile*
  * *adcomplete*

```js
// Sample source snippet

player.uplynk.ads.adBreaks.addEventListener('addadbreak', (event) => {
  // do something with event.adBreak as it is an ad break added through SSAI, an example:
  const adBreak = event.adBreak;
  if (adBreak.duration <= 15) {
    adBreak.skipOffset = -1; // Do not allow skipping of short ad breaks
  } else if (adBreak.duration > 60) {
    adBreak.skipOffset = 10; // Allow skipping of long ad breaks after ten seconds
  } else {
    adBreak.skipOffset = 0; // For all other ad breaks, allow immediate skipping
  }
  // subscribe to additional events
  event.adBreak.addEventListener('adbreakbegin', console.log);
  event.adBreak.addEventListener('adbreakend', console.log);
  for (var i = 0; i < event.adBreak.ads.length; i++) {
    event.adBreak.ads[i].addEventListener('adbegin', console.log);
    event.adBreak.ads[i].addEventListener('adend', console.log);
  }
});
```

## Related articles

* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/preplay.md)
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ping.md)

---

# Ping

This article explains how to use Uplynk's Ping API.

The Ping API by Uplynk allows users of their CMS to receive updates about SSAI on running live-streams or provide better playback position beaconing for Video on demand. The Ping API is used together with the Preplay API because the latter provides a session to be used with the Ping API.

This pre-integration allows the integrator to specify a source for Preplay as integrated in other tickets (RDMP-287), and enable or disable certain features of the Ping API. The player will then perform these Ping calls internally, without the integrator having to write their own Ping client. The response of Ping calls will be exposed for external handling if necessary. The updates about SSAI received through the Ping API will be reflected in the player API, where information about SSAI through the Verizon Media Platform is already present.

**Version 3 of the Ping API will be implemented.**

**Playhead Position** When Ping mentions time (and time mentioned below) relative compared to 0, the 0-point will be the start of playback. This might be a mismatch with the normal `player.currentTime`. Instead, this will be comparable with the time passed since `player.played.start(0)`.

**Feature Assumptions** We assume the SSAI information returned through the Ping API to be of a certain format, which we compile from examples and our own testing. The documentation does not define the structure of this payload very well and only states that it is "like the object returned in Preplay requests", though the formats are not a one-on-one match.

This feature currently excludes client-side ad tracking and VPAID support.

**Assumptions**

* THEOplayer assumes the availability of the Ping API and Uplynk content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
* THEOplayer assumes application developers have a notion of the Ping API, namely any extra parameters to be appended to the requests to Uplynk (e.g. for correct ad insertion). Uplynk documents this service in the [API docs](https://api-docs.uplynk.com/#Develop/Pingv3.htm).
* THEOplayer assumes application developers provide proper ID's of the Assets they want to play back, as well as the proper content protection level.

## Configuring Ping

The player allows specification of the desired features of the Ping API as listed [in the official Ping API documentation](https://api-docs.uplynk.com/#Develop/Pingv3.htm#Features).

By default, the ping API is disabled for all sessions. To enable it, the `ad.cping=1` parameter must be added to your preplay request. If you attempt to call the API without passing in the `ad.cping` parameter, you can throw off the server's ability to make ad event calls correctly.

In addition to enabling the API, you must also notify the server of the features you want to support for this viewing session. To specify which features you'd like to enable, you add the `ad.pingf={some value}` parameter to the playback token. The value of the parameter is detailed in the official Ping Documentation.

Sample playback URL with `cping`:

`https://content.uplynk.com/preplay/cc829785506f46dda4c605abdf65392b.json?ad=adserver&ad.cping=1&ad.pingf=3`

In the THEOplayer API, these features can simply be activated through the `ping` property in the source configuration:

```js
player.source = {
    sources: [{
        integration: 'uplynk',
        ...,
        ping: {
            linearAdData: true,
            adImpressions: false,
            freeWheelVideoViews: false
        },
        ...
    }]
}
```

## Ping requests

When the Ping API is enabled, THEOplayer will call the Ping URL located at:

```text
{prefix}/session/ping/{sessionID}.json?v=3&pt={currentTime}&ev={event}&ft={freeWheelTime}
```

Where:

* `{prefix}`: the prefix URL from the Preplay response.

* `{sessionID}`: the session ID from the Preplay response.

* `{currentTime}`: mandatory parameter. This is the current player time in seconds.

* `{event}`: the current Ping event. An event should only be passed when playback starts or when a viewer seeks to a new position. Valid values are:

  * **start**: Pass this event, along `withpt=0`, when the player starts playback. This lets the server know where playback starts and allows the server to fire start events as needed.
  * **seek**: Pass this event when a viewer seeks. This resets the timeline to prevent inadvertently firing events for skipped ads.

* `{freeWheelTime}`: indicates the playback position, in seconds, right before a viewer seeks to a different position in the timeline. This property is mandatory when the freeWheelVideoViews is used.

## Ping Response

When performed correctly, a Ping request will return a JSON response. THEOplayer will interpret this response according to the following principles:

* `next_time`: a new beacon will be scheduled when the player's currentTime passes this value. In case the value is -1, no further beacons will be scheduled.

* `currentBreakEnd`: will be used to update the end time of an ongoing ad-break in case the breakEnd was previously unknown. (Note Verizon Media by default requests 240s of ads in case the break length is unknown and will return all ads in the Ping response.)

* `ads`: will be interpreted in order to display markers in the timeline as well as expose ad information through the player.verizonMedia.ads property.

  * `ads.breaks.timeOffset` will be used in order to determine the start time of the ad break (in seconds).

  * `ads.breaks.ads` will be looped in order to extract the ad information to be exposed in the Uplynk Ad on the THEO API:

    * `ad.duration` will serve as duration in the ad (in seconds)
    * `ad.mimeType` will serve as mimeType in the ad
    * `ad.apiFramework` will serve as apiFramework in the ad
    * `ad.companions` will serve as companions in the ad
    * `ad.creative` will serve as creative in the ad
    * `ad.width` will serve as width in the ad
    * `ad.height` will serve as height in the ad
    * `ad.events` will serve as events in the ad
    * `ad.fw_parameters` will serve as freeWheelParameters in the ad

  * `ads.breaks.breakEnd` will be used in order to determine the end of the ad break. Note that this property is optional, and the duration of an ad break can be unknown and updated at a later point.

  * `ads.breaks.duration` will be ignored by the player.

  For all ads and breaks added, `adbreakbegin`, `adbreakend`, `adbegin` and `adend` events will be dispatched. Additionally, when `breakEnd` gets updated, an `updateadbreak` event will be dispatched.

* extensions: Will be ignored by THEOplayer.

* error: Errors will be reported back through the THEOplayer API.

The raw ping response can be retrieved by adding an event listener for the `pingresponse` event on the `player.uplynk` property.

| Event        | Description                             | Event object                                                            |
| ------------ | --------------------------------------- | ----------------------------------------------------------------------- |
| pingresponse | Fired when a Ping response is received. | event.response will contain the raw JSON response from the Ping server. |

```js
player.uplynk.addEventListener('pingresponse', function (event) {
  console.log(event.response); // Will print the raw Ping response.
});
```

## Related articles

* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/preplay.md)
* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ads.md)

---

# Uplynk configuration

This article explains what is possible with an Uplynk configuration when setting up a THEOplayer instance.

## Features

Developers can set an Uplynk configuration when creating their video player instance. Through this configuration, developers can set some UX and UI preferences related to the Uplynk integration.

* `defaultSkipOffset`: specifies when an ad break can be skipped. The default value is `-1`, which means that the ad break cannot be skipped.

* `onSeekOverAd`: specifies what should happen when viewers try to seek over an ad. By default, no ad are played when seeking over ads. As an alternative, you can

  1. only play the last ad break (before the requested playhead position), or
  2. play all ad breaks (before the requested playhead position).

* `ui`

  * `adBreakMarkers`: specifies that a (red) ad break marker should be rendered in the scrub bar. (Enabled by default.)
  * `assetMarkers`: specifies that a (black) asset marker should be rendered in the scrub bar. (Enabled by default.)
  * `adNotification`: specifies that a count-down timer must be rendered when an ad is playing. (Enabled by default.)
  * `contentNotification`: specifies that a count-down timer to the next asset must be rendered when the viewer is close to the transition of another asset of a multi-asset stream. (Enabled by default.)

You can toggle this features on [our demo page](https://cdn.theoplayer.com/demos/verizon-media/index.html). *(Note: technically, this demo doesn't use `defaultSkipOffset` to configure the skip offset. Instead, this demo uses `player.uplynk.ads.adBreaks[<element>].skipOffset` to adjust this dynamically at run-time.)*

![UplynkDemo](/pr-932/assets/images/VerizonMediaConfiguration-e6131ae47761b09919322b8c26ee3d15.png "Uplynk Configuration")

The examples below demonstrate how to use an Uplynk configuration per platform.

```js
const player = new THEOplayer.Player(element, {
    libraryLocation: '...',
    uplynk: { // optional
        onSeekOverAd: 'play-all', // default to 'play-none'. Other values: 'play-all' and 'play-last'
        ui: {
            contentNotification: true, // optional; defaults to true
            adNotification: true, // optional; defaults to true
            assetMarkers: true, // optional; defaults to true
            adBreakMarkers: true, // optional; defaults to true
        },
        defaultSkipOffset: 5 // ad break can be skipped after 5 seconds. (defaults to -1)
    },
    ...
});
```

Refer to the [UplynkConfiguration API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkConfiguration) for more information.

# Related articles

* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ads.md): this article zooms in on `defaultSkipOffset` and \`\`onSeekOverAd\`.
* [Uplynk - Introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/introduction.md): this article links to sample Git projects which implement an `UplynkConfiguration`.

---

# Uplynk interface

This article explains how developers can hook into the Uplynk interface. This interface allows developers to query the available assets and ads in an Uplynk stream, its properties, and subscribe to its events.

## Using the Uplynk interface

The `Uplynk` interface is exposed through your THEOplayer instance (e.g.: `player.uplynk` for the Web SDK). Through this interface,

* You can retrieve information (e.g. start and stop time) on the available assets (because THEOplayer extracts this information from its integration with the Asset Info and Preplay service offered by Uplynk).
  * You can also subscribe `addasset` and `removeasset` events, which can be useful when you need to be informed when the assets become available.

* You can intercept Preplay, Asset Info and Ping responses (because THEOplayer integrates with these services offered by Uplynk).

* You can retrieve information on the available advertisements (because THEOplayer extracts this information from its integration with the Preplay and Ping service offered by Uplynk).

  * You can also subscribe to `addadbreak`, `addad`, `removeadbreak`, ... events, which can be useful if you want to know when which state is applicable (e.g. to overlay a custom advertisement countdown-timer).
  * You can also adjust the ad skip offset of an ad break.

If you're looking for more information on how to query the available advertisements and how to subscribe to ad events, then refer to [Uplynk Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ads.md).

The examples below provide a basic demonstration of how to use the `Uplynk` interface. The GitHub projects linked at [Uplynk - Introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/introduction.md) provide more code samples.

```js
const player = new THEOplayer.Player(element, {...});
// uplynk events
[
    'preplayresponse',
    'pingresponse',
    'assetinforesponse'
].forEach(function(e) {
    player.uplynk.addEventListener(e, console.log);
});
// uplynk.assets events
[
    'addasset',
    'removeasset'
].forEach(function(e) {
    player.uplynk.assets.addEventListener(e, console.log);
});
// uplynk.ads events
[
    'addadbreak',
    'removeadbreak'
].forEach(function(e) {
    player.uplynk.ads.adBreaks.addEventListener(e, function (e1) {
        if (e1.type === "addadbreak") {
            // uplynk.ads.adBreak[i] events
            [
                'adbreakbegin',
                'adbreakend',
                'adbreakskip',
                'updateadbreak'
            ].forEach(function(e) {
                e1.adBreak.addEventListener(e, console.log);
                // uplynk.as.adBreak.ads[i] events
                for (let i = 0; i < e1.adBreak.ads.length; i++) {
                    [
                        'adbegin',
                        'adend',
                        'adfirstquartile',
                        'admidpoint',
                        'adthirdquartile',
                        'adcomplete'
                    ].forEach(function(e) {
                        e1.adBreak.ads[i].addEventListener(e, console.log);
                    });
                }
            });
        }
    });
});
```

Refer to the [Uplynk API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Uplynk) for more information. Additionally, reviewing [the player configuration in the demo app](https://github.com/THEOplayer/samples-html5-sdk/blob/master/reference-apps/verizon-media-app/src/player.js) helps to understand the `Uplynk` interface.

## Related articles

* [Uplynk - Introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/introduction.md): this article links to sample Git projects which query (and subscribe to) the various properties and events offered by the `Uplynk` interface.
* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/preplay.md): this article explains how you can use the Uplynk interface to intercept Preplay responses.
* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ads.md): this article offers more information on the `ads` parts of the Uplynk interface.
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ping.md): this article explains how you can use the Uplynk interface to intercept Ping responses.

---

# MPEG-DASH Content Steering

This guide shows you how to use MPEG-DASH Content Steering in the THEOplayer Web SDK.

MPEG-DASH Content Steering is a server-driven mechanism that allows content providers to dynamically control CDN selection across large groups of clients. While players can independently respond to local network conditions and switch between CDNs, Content Steering enables centralized decision-making at scale. By communicating with a steering server, the player receives a prioritized list of CDN endpoints that reflects real-time information about CDN performance, capacity, and cost across your entire user base. This allows you to proactively route traffic away from overloaded or underperforming CDNs, balance load across multiple providers, or implement cost optimization strategies—all without requiring player-side logic or client updates.

## Enabling/Disabling Content Steering

By default, Content Steering in MPEG-DASH is enabled, however, it can be explicitly enabled or disabled using a flag in your `SourceDescription`.

You can also override the `clientRequirement="false"` property in the MPEG-DASH manifest to enable Content Steering for a specific playback session by explicitly setting it to `true`.

```javascript
player.source = {
  sources: {
    src: 'https://your-dash-source-with-content-steering.mpd',
    dash: {
      contentSteering: true, // Default is true; set to false to disable.
    },
  },
};
```

## Events for Content Steering

THEOplayer provides events to monitor the Content Steering process. For more details, check the [API documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web#ContentSteeringStartEvent).

```javascript
player.addEventListener('contentsteeringstart', console.log);
player.addEventListener('contentsteeringstop', console.log);
player.addEventListener('contentsteeringlocationchange', console.log);
player.addEventListener('contentsteeringupdate', console.log);
player.addEventListener('contentsteeringerror', console.log);
```

## Known Limitations

* `PATHWAY-CLONE` from the Content Steering server response is not supported yet.
* Extended HTTP GET request parametrization instructions are not supported yet. You can add custom parameters to Content Steering requests by using a `RequestInterceptor` to intercept and modify network requests with the type `content-steering`.
* Targeting a specific set of clients as part of a ServiceDescription element is not supported.

## More information

* [DASH-IF: Content Steering for DASH](https://www.etsi.org/deliver/etsi_ts/103900_103999/103998/01.01.01_60/ts_103998v010101p.pdf)

---

# Getting started

## Usage

1. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/web/getting-started.md) to set up THEOplayer in your web app or website.
2. Register the service worker if necessary.
3. Add an OptiView Live source to your player's source.

### Register the service worker

On Apple devices running an iOS version lower than 17.1, a service worker needs to be registered to support low latency play-out of OptiView Live streams.

```javascript
function needsServiceWorkerForTHEOlive() {
  const canPlayMSE = !!(window.MediaSource || window.ManagedMediaSource);
  const videoElement = document.createElement('video');
  const canPlayHLS = videoElement.canPlayType && videoElement.canPlayType('application/vnd.apple.mpegURL') !== '';
  return canPlayHLS && !canPlayMSE;
}
if (needsServiceWorkerForTHEOlive()) {
  await navigator.serviceWorker.register('theoplayer.sw.js');
}
```

The service worker `theoplayer.sw.js` is part of the THEOplayer SDK and needs to be on the same domain and path as the page initiating the player.

### Add an OptiView Live source

After setting up your THEOplayer on your web page, set its source to a `SourceDescription` containing a `THEOliveSource`. Take into account that the source must be set after awaiting the registration of the service worker for streams to work on iOS versions lower than 17.1. You'll need an OptiView Live channel ID:

```javascript
const player = new THEOplayer.Player(element, configuration);
player.source = {
  sources: {
    type: 'theolive',
    src: 'your-channel-id',
  },
};
```

### Add configuration

Optionally, you can provide additional configuration to the player, specific for OptiView Live streams. To configure these settings, add a `theolive` property to the player configuration. For an exhaustive list of these options, please visit the [documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/interfaces/TheoLiveConfiguration).

```javascript
var player = new THEOplayer.Player(element, {
  license: 'your-license',
  // This is needed for fallback to work properly
  retryConfiguration: {
    maxRetries: 6,
  },
  theoLive: {
    externalSessionId: 'my-external-session-id',
    fallbackEnabled: true,
  },
});
```

## More information

* [API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/interfaces/TheoLiveSource)

---

# Basic Playback Guide

After following our [Getting Started on Web guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/theolive/getting-started.md) or the [Player Setup](#player-setup) section below, you will be ready to programmatically perform common playback actions. These include increasing/decreasing the volume, playing/pausing the stream, enabling full screen, and selecting quality layers.

## Player Setup

To get started with OptiView Live playback using THEOplayer, you must first initialize your player with reference to your OptiView Live channel as the source.

Here is an example of initializing a THEOplayer instance for OptiView Live:

```javascript
const player = new THEOplayer.Player(element, configuration);
player.source = {
  sources: {
    type: 'theolive',
    src: 'your-channel-id',
  },
};
```

Once done, your player variable will reference the returned THEOplayer instance and have access to all of its [properties and methods](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/classes/Player).

## Adjust Volume

To adjust the volume of your stream during playback, you can set the [`volume`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/classes/Player#volume) property to a floating point number in the range of `0.0` (0%) minimum and `1.0` (100%) maximum.

The following code sets the player's volume to 60%:

```javascript
// the stream's volume will now be 60%
player.volume = 0.6;
```

## Play/Pause Stream

To play or pause your stream, you can use the [play](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/classes/Player#play) and [pause](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/classes/Player#pause) methods available on your player variable.

To pause your stream:

```javascript
player.pause();
```

To play your stream:

```javascript
player.play();
```

## Enable Full Screen

To make your stream take up the full screen of the device it is being viewed upon, you must use the [`requestMode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/interfaces/Presentation#requestMode) method available on the [`presentation`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/classes/Player#presentation) property of your player variable.

Before doing so, check that the player supports other presentation modes (besides the default `'inline'`) for the device which the stream is viewed on by using the [`supportsMode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/interfaces/Presentation#supportsMode) method on the presentation property.

Both the `requestMode` and `supportsMode` methods require a [`PresentationMode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/types/PresentationMode) parameter that can accept the following arguments:

* `inline`: The player is shown in its original location on the page. (default presentation mode)
* `fullscreen`: The player fills the entire screen.
* `picture-in-picture`: The player is shown on top of the page (see PiPConfiguration for more options).
* `native-picture-in-picture`: (Experimental) The player requests out-of-app picture-in-picture mode. Not supported on Firefox.

Check if fullscreen is supported with the following code:

```javascript
// returns a boolean value of true or false
player.presentation.supportsMode('fullscreen');
```

If the `supportsMode` method returns true for the presentation mode you passed into it, then you can move on to the steps below.

To make the current stream take up the full screen, pass a presentation mode of `'fullscreen'` to the `requestMode` method with the following code:

```javascript
// stream will take up the full screen which it is being viewed on
player.presentation.requestMode('fullscreen');
```

To confirm that the change has occurred, check the [`currentMode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/interfaces/Presentation#currentMode) property to ensure it now returns `'fullscreen'` as its value:

```javascript
// should return a value of 'fullscreen' to the console
console.log('this is the current presentation mode being used -->', player.presentation.currentMode);
```

## Select Quality Layer

To select a specific quality layer during the playing of your stream, you must set the [`targetQuality`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/interfaces/MediaTrack#targetQuality) property which is accessible on the [`videoTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/classes/Player#videoTracks) property of your player variable.

The `videoTracks` property leverages the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/interfaces/MediaTrack).

To see what qualities you have available, use the following code:

```javascript
// put all available quality layers in an array and log them to the console
const qualities = player.videoTracks[0].qualities;
console.log('this is an array containing all available qualities --> ', qualities);
```

Once you know what options you have available, you can set the stream to be a specific quality by doing the following:

```javascript
// set a specific quality layer by using its index in the qualities array
player.videoTracks[0].targetQuality = qualities[indexOfDesiredQualityLayer];
```

## More information

* [API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/classes/Player)

---

# Airplay

OptiView Live streams have support for Airplay. However, a limitation for now is that the latency is higher while casting (about 12 seconds). Configuring it is exactly the same as for other streams you would play with THEOplayer. The instructions are described in the [Airplay guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/airplay/introduction.md).

---

# Chromecast

OptiView Live streams have support for Chromecast. However, a limitation for now is that the latency is higher while casting (about 12 seconds). Configuring it is exactly the same as for other streams you would play with THEOplayer. The instructions are described in the [Chromecast guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/enable-chromecast-on-the-sender.md).

---

# Metadata

The messages added to your stream using the [Backend Metadata guide](https://docs-preview.optiview.dolby.com/pr-932/theolive/channel/metadata-insertion.md), you can access as a metadata text track.

First listen to the event to see if a new metadata track has been added, and add an `onTimeCode` listener:

```javascript
player.textTracks.addEventListener('addTrack', (event) => {
  const track = event.track;
  if (track.id === 'timecode') {
    track.mode = 'showing'; // Setting the mode to showing will enable the entercue events
    track.addEventListener('entercue', this.onTimeCode);
  }
});
```

The actual onTimeCode listener could look like this:

```javascript
const onTimeCode = (event) => {
  const timeCode = event.cue.content;
  // Insert other code here
};
```

Where the timecode has the following type:

```typescript
export interface TimeCode {
  readonly hours: number;
  readonly minutes: number;
  readonly seconds: number;
  readonly frames: number;
}
```

So a full example could be as follows:

You distribute sports matches and want to display an overlay on the player when the score changes. Every time a score change happens, you add a picture timing SEI message to the stream and store in your backend that this time corresponds with this score. (You could also just add the timing message to all frames if this is easier, but this requires more processing both server and player side). This information can then be retrieved by the application running on the device of a viewer. You then add the event listener and listen for the `entercue` events. In the listener you check whether the `TimeCode` corresponds with a score change event you recorded earlier and if so, display an overlay over the player.

---

# Token based security

OptiView Live offers the option to enable JWT token security on a distribution (formerly referred to as an alias) level. This can be interesting if you only want valid users to access your stream. Read more about the feature and configuring it on your channels on the [token based security guide](https://docs-preview.optiview.dolby.com/pr-932/theolive/distribution/security/token-based-security.md).

This page will demonstrate how to configure the Web SDK for playback of channels with token based security enabled.

## Setting up the Web THEOplayer SDK for OptiView Live

Refer to the [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/theolive/getting-started.md) for the prerequisite steps in getting the Web SDK up and running for OptiView Live playback.

## Configuring THEOplayer to pass the token

The token needs to be passed along with player requests as a Bearer token in the `Authorization` header of the requests. To do so we can make use of the Network API of the player, which works as follows:

```javascript
const token = getToken(); // Generate or request your token, for more information check the token based security guide linked above.
player.theoLive.authToken = token;
```

This will ensure the player includes your authorization header on all subsequent requests it performs for playback of your OptiView Live distribution.

## Dealing with token expiry and rotation

If your tokens are short-lived, you want to make sure to update the token being passed to the player and requests before it expires, to allow playback to continue beyond expiry. This can simply be done by updating the header on the player in the same way. For example, one could check on an interval that makes sense for your token lifespan whether the token is about to expire and update when necessary, for example:

```javascript
let token;

// Helper function to check whether your token will expire within one minute from now
function tokenWillExpireSoon() {
  const payload = JSON.parse(atob(token.split('.')[1]));
  const exp = payload.exp; // in seconds
  const now = Math.floor(Date.now() / 1000); // current time in seconds
  return exp - now <= 60;
}

function maybeUpdateToken() {
  if (!token || tokenWillExpireSoon(token)) {
    token = getToken(); // Generate or request your token, for more information check the token based security guide linked above.
    player.theoLive.authToken = token;
  }
}

maybeUpdateToken();
setInterval(maybeUpdateToken, 30000); // Check every 30 seconds
```

## Clearing the token

If the token isn't needed anymore, e.g. when switching to an unprotected distribution or a non-OptiView Live source altogether, the header can be simply removed as follows:

```javascript
player.theoLive.authToken = undefined;
```

## Enabling Token Based Security for Safari browsers on iOS <17

Apple devices running an iOS version lower than 17.1 do not support MSE, therefore there are limitations with what is possible when playing an OptiView Live stream. One such limitation is that the above network API approach does not work on those devices. Instead, a service worker needs to be registered to support playback of JWT enabled streams.

The service worker needs to intercept the `fetch` requests originating from the app, to be able to include the `Authorization` header to the requests. This requires the player to make all HTTP requests with [CORS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/cors/introduction.md) enabled, even when using Safari's native playback. Make sure to set [the `crossOrigin` property](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TypedSource#crossOrigin) on your OptiView Live source:

```javascript
player.source = {
  sources: {
    type: 'theolive',
    src: 'your-channel-id',
    crossOrigin: 'anonymous',
  },
};
```

A code snippet for the service worker code is shared below.

> **Note**
>
> Service worker registration is only possible in a secure environment (`https://`) or on `localhost`. There can also only be one service worker active, so if your environment or application already has a service worker active, you will need to include the additional functionality in that service worker.

iOS Safari service worker

```javascript
self.addEventListener('install', () => {
  console.log('Service worker installed!');
  self.skipWaiting();
});

self.addEventListener('activate', (event) => {
  console.log('Service Worker activated');
  // Claim clients so the service worker is in effect immediately
  event.waitUntil(self.clients.claim());
});

// Intercept the fetch event and add in your JWT
self.addEventListener('fetch', (event) => {
  try {
    const url = new URL(event.request.url);
    if (!url.origin.endsWith('theo.live')) {
      // Requests not made by the player for playback of the OptiView Live distribution should not be modified.
      return;
    }
    const token = getToken(); // Generate or request your token. For more information, check the token based security guide linked above.
    // Clone the request and add the JWT header
    const modifiedHeaders = new Headers(event.request.headers);
    modifiedHeaders.set('Authorization', `Bearer ${token}`);
    const modifiedRequest = new Request(event.request, {
      headers: modifiedHeaders,
    });
    return event.respondWith(fetch(modifiedRequest));
  } catch (error) {
    console.error('Error in fetch handler:', error);
    return event.respondWith(new Response('Service Worker Error', { status: 500 }));
  }
});
```

> **Note**
>
> In order for the service worker to be able to intercept requests made from the player library, its scope must include the player SDK files. That means the player and service worker must be hosted on the same path or the player must be hosted in a subfolder of the path where the service worker is hosted.

To register this service worker in to your code, you can attach it this way.

Register service worker

```javascript
async function registerServiceWorker() {
  if (!('serviceWorker' in navigator)) {
    console.error('Service worker not supported!');
    return;
  }
  const serviceWorkerScope = '/service/worker/path'; // Replace with your own path to the service worker location.
  const serviceWorkerPath = '${root}/service-worker.js'; // Replace with the filename of your service worker.

  // We recommend unregistering actively before (re-)registering as we've seen issues where hard reloads could cause issues if the service worker wasn't unregistered.
  const oldRegistration = await navigator.serviceWorker.getRegistration(serviceWorkerPath);
  await oldRegistration?.unregister();

  try {
    const registration = await navigator.serviceWorker.register(serviceWorkerPath, {
      scope: serviceWorkerScope,
    });
    if (registration.active) console.log('Service worker registered!');
  } catch (err) {
    console.error('Could not register service worker!', err);
  }
}

// Initialise the service worker some time early in the process.
if (!(window.MediaSource || window.ManagedMediaSource)) {
  registerServiceWorker();
}
```

The snippet above assumes the existence of a function `getToken()` that generates a JSON Web Token (JWT) and signs it using the default HMAC SHA-256 algorithm. [(Refer to docs on jwt.io)](https://jwt.io/introduction). In pseudocode:

```javascript
const getToken = async () => {
  const YOUR_JWT_SIGNING_KEY = 'YOUR-SIGNING-KEY-GOES-HERE';
  const payload = {
    exp: Math.floor(Date.now() / 1000) + 300, // 5 minutes
  };

  return await sign(payload, YOUR_JWT_SIGNING_KEY);
};
```

You can use an existing library like [Jose](https://github.com/panva/jose), or you can use our example implementation:

JWT `sign` function

```js
const base64UrlEncode = (str) => {
  return btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
};

const utf8ToUint8Array = (str) => {
  return new TextEncoder().encode(str);
};

const sign = async (payload, secret) => {
  const header = { alg: 'HS256', typ: 'JWT' };

  const encodedHeader = base64UrlEncode(JSON.stringify(header));
  const encodedPayload = base64UrlEncode(JSON.stringify(payload));

  const data = `${encodedHeader}.${encodedPayload}`;
  const secretBytes = utf8ToUint8Array(secret);

  const key = await crypto.subtle.importKey('raw', secretBytes, { name: 'HMAC', hash: { name: 'SHA-256' } }, false, ['sign']);

  const signature = await crypto.subtle.sign({ name: 'HMAC' }, key, utf8ToUint8Array(data));

  const signatureStr = String.fromCharCode(...new Uint8Array(signature));

  return `${data}.${base64UrlEncode(signatureStr)}`;
};
```

> **Info**
>
> You can validate the token generated by inspecting it using the JWT decoder on [JWT.io](https://jwt.io/). The header and payload will be decoded immediately. If you provide your HMAC key, you can validate that the signature is also valid.

> **Note**
>
> If you are using a bundler such as Vite or Rollup etc, you will need to ensure that your service worker also gets copied to your output directory and is `registered` from the correct path.

---

# Migrating from deprecated THEOlive player to THEOplayer on Web

The goal of this guide is to help you migrate from the deprecated [theolive player](https://www.npmjs.com/package/@theolive/player) to the recommended [THEOplayer](https://www.npmjs.com/package/theoplayer). If you haven't integrated with any player, please follow the [recommended](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/theolive/getting-started.md) guide instead of this one.

## Dependencies

First remove the old player dependency:

```text
npm uninstall @theolive/player
```

And replace with theoplayer using:

```text
npm install theoplayer
```

## Setting up a player

Player creation is quite similar, instead of

```javascript
const player = new THEOLive.Player(element);
```

Create the player like this:

```javascript
var player = new THEOplayer.Player(element, {
  license: 'your-license',
  // This is needed for fallback to work properly
  retryConfiguration: {
    maxRetries: 6,
  },
  theoLive: {
    // these are optional
    externalSessionId: 'my-external-session-id',
    fallbackEnabled: true,
  },
});
```

Note that you now need a license, either use the THEOplayer license you had before, or use the one provided in the [OptiView Live dashboard](https://dashboard.optiview.dolby.com) when creating a channel.

## Loading a channel

After setting up your THEOplayer on your web page, we will set the source to a channel. The old way was calling loadChannel on the player.

```javascript
player.loadChannel('<your-channel-id>').catch(console.error);
```

With THEOplayer you just set a [SourceDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/interfaces/TheoLiveSource).

```javascript
player.source = {
  sources: {
    type: 'theolive',
    src: 'your-channel-id',
  },
};
```

## Calling methods and listening to events

Most of the old functionality is right there on THEOplayer and can be found in the [THEOplayer docs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/classes/ChromelessPlayer). For OptiView Live specific API, check out [player.theolive](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/interfaces/TheoLiveApi).

## More information

* [API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/web/interfaces/TheoLiveSource)

---

# Examples

See the player in action!

## [▶️Basic player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/examples/basic.md)

[Code](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/examples/basic.md)

---

# Basic player

Code

```html
<div id="player" class="video-js theoplayer-skin vjs-16-9"></div>
<script>
  var player = new THEOplayer.Player(document.querySelector('#player'), {
    libraryLocation: '/path/to/theoplayer',
    license: 'your_theoplayer_license',
  });
  player.source = {
    sources: [
      {
        src: '//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
        type: 'application/x-mpegurl',
      },
    ],
  };
</script>
```

---

# Connectors for THEOplayer Web SDK

## [☁️CMCD](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/web/cmcd)

[Integrate with Common Media Client Data (CMCD) for server-side analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/web/cmcd)

## [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/web/comscore)

[Integrate with Comscore for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/web/comscore)

## [![](/pr-932/img/conviva.svg)![](/pr-932/img/conviva_dark.svg)Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/web/conviva)

[Integrate with Conviva for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/web/conviva)

## [Nielsen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/web/nielsen)

[Integrate with Nielsen for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/web/nielsen)

## [![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAy0SURBVHgB7d1PbhRJFsfxiLIxs+iW2DbuaZVvwNzASGB6iU+AOQGuHd2YwSVhYId9AsMJYNmYkewb2DdwafjjWXoBEvUvYzKqSMqmjV1ZlZnxIuL7kVpqoZaM6M5f53svMp5SAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAORwt3q8fpn8pAKXQSij78Ju5S7tKmXr6m1z/0vm0tbC3eawAFEZkABwurl6Zm/tpN/3NXRv9qm4lpt/89e2TFwpAIcQFwNkP/ykH7U5veWHvWUsBmIqoABjj4f/GaP2i0+42CQJgcmICIM/DP6JbSidbV99sbCoAuYkIgMke/pPoDwCTcB4A0z/8I5QFQD5OA6DIh/+k4diw95IgAM7nLADKevhHKAuAizgJgPIf/pN0q93pXudtAPi7ygOg2od/hP4A8HeVBoCrh/+E4/Rnb/6y87ipAFQXAAIe/hPoDwBWJQEg6+EfoSxA7EoPAKkP/ylab7bb3S2CALEpNQC8ePi/oSxAfEoNgPc31zZrWt1TXhkEwXIaBAcKCFxNlUhrc0V5x9Rrurb/4dbDbW4jQuhKDQCfaWNWLs/NHh4trT1SQKAIgAsYpdY/Lj08fH/zzxUFBIYAGMugLNj+uLT2irIAISEA8rltywL6AwgFATCBYX/g0i5lAXxHAEwsKwseHr67sbaoAA8RAFMz9Zma2qUsgI8IgIIwNoSPCICCMTaETwiAUnwbG+5TFkAyAqBc1xgbQjICoALZ2PDjrQerChCEAKiMqSujn9v+wIelP24rQAACoHJ23fnMK8oCSEAAOHJybGgvTlGAAwSAY3ZseHnu533GhnCBABBhdKyYsgBVIgBEMXXGhqgSASBQNjbkWDHKRgCIZeocK0bZCADxhv0BygKUgQDwRDY2/Hjr4XOCAEUhAHxjzCq3EaEoBICXRmPDNAg82LoEqQgAr7HEBNMhAALwtT+wz9gQeREA4bjC2BB5EQDBYYkJxkcAhIslJrgQARA4lpjgPARAFFhigrMRAFFhiQlOIwAixBITZAiAiDE2BAEQPZaYxIwAQIYlJhEiAHAKY8O4EAA4w2hsyBKTsBEAOAdLTEJHAOBCLDEJFwGAsbHEJDwEAHJiiUlICABMiCUmISAAMBWWmPiNAEABWGLiKwIABWKJiW8IABTu9NiQIJCMAEBphmNDjhVLRgCgZIwNJSMAUBHGhhIRAKgUS0xkIQDgAktMhCAA4BBLTFwjACABS0wcIQAgBrcRVY8AgDCjsWEaBNcUSkUAQKhBEOxTFpSLAIBoLDEpFwEALzA2LAcBAI8M+wNHN9d2KQuKQQDAO0arRcaGxSAA4C3GhtMjAOA5lphMgwBAIFhiMgkCAEFhiUk+pQaASdSBAhxgicl4tCrZ0e/36yaZ2U1/VF0Bbhy0O73lhb1nLYVTSg+AjE3imtaPCAK4YrR+0Wl3mwTBSGUBYB0url+Zm+utpj+UY51wRLeUTrauvtnYVKg2ADK2LEiSmXWt9B0FOKFbiek3f3375IWKmJMAyLy7sbY4UzPblAVwJfaywGkAZOgPwLX0QVj/0um9jC0IRASAZcuCfn92tabVPQU4EV9ZICYAMvQH4J5utTvd6zG8DYgLgAxlAVyLoT8gNgAyBAEcO04fks1fdh43VYDEB4BFWQD3wuwPeBEAmeGx4tnn6d/y2Sdced3u9BqhlAVeBUCGsgDOab3Zbne3fA8CLwMg82FpLS0LzB2CAG74XxZ4HQAW/QG4NwiC5TQIvPv83fsAyHztD7xK/5ZtMnDCx7FhMAGQoT8A1+yxYl/GhsEFQGbYHxgcK+ZaKDjgR38g2ACw6A/ANW3U3pdu767UsiDoAMhwLRlck9ofiCIAMvQH4Ja8siCqALC4lgzu6ZZRvcb8ztPXyrHoAiBDfwCuSSgLog2ATFoWXEvLgleUBXDF5dgw+gDI0B+AW276AwTACcOyYHaF/gAcqnSJCQFwBvoDcK2q/gDLQc/wy1/PWvM7Gyumr5bTfxUtBVRssOT08kzp917wBjAG+gOolFF77Zne3YW/yi8DCIAxURagfKbVT/Tdf/7n8Z6qCAGQE0GAEhwbpbY6nU+bC3ubx6pCBMCEKAtQBKNN2uz73Kj6wc8QAFN6f+PBaq1mPzvWdQWMK63z+0Y1q3zdPwsBUADKAuRwnLb4m1LWkxMABRp8dtyf3U7/VBcV8J20zm+6qPPPQwCUgP4ATqlwrJcXAVAiriWLXfVjvbwIgJLRH4jSYKw3v/N4XQkXVAC8u7G2OKvVo6SmW9KuX+La8ji4HuvlFUQAHC3er6vLlx4ZY1ZO/rrE65npDwRKyFgvL68D4HBx9co/5n66l75uraof1tkyr2f+2h/gs2P/HScmafi6HszbAPjv0h+3Z5XdFGzq4/zzEq9npj/gN4ljvby8C4CszjcTztolXs/MtWSeETzWy8ubALCv+5fnfk5fmc2qmppuKZ1sSTmNlaE/IJ38sV5eXgTA0dLao/Pr/EnJ6w9wbblI3oz18hIdAPZ1f6amt8et8yclsSygPyBDYtRWt/tp3ec6/zwiA2Aw1rs0u22qPlOv9Wa73d2SFATDEDTblAUV83Ssl5eoACi2zp+UzLEh/YHKeD3Wy0tMAPzv5r/vJTpZV2LOzeu04WNENXxsWdDvz67W9OD7AhTL2a08LjkPAPuKW6up51roEVn6AxEIaKyXl7MAcFbnT8geK/7S+bQl6f8OlAXTCm+sl1flATDe8V2p6A8EItixXl6VBsDwP9Tac+X99/G61e50r1MW+Cf0sV5elQTAtMd3pZLaHzCJ/UZClb5VxiuRjPXyKjUAfvSZbmCO0z/ETT47lsqkZZsRV7ZJUWoAfFh68CKeV1Kh/YF4ry2PcqyXFwFQvNftTq9Bf8ChiMd6eREAJRHbHwj62nLGenmxHrwkg/XOc5d2bS2uhLBrz6++fXw9McndwNae22Ubjas7Gws8/PnwBlAJ3TKq15jfefpaCRLCteWM9aZDAFSIY8UFYqxXCALAgeGx4t5LeecHZnblTwtMq6eSxm/C3qZ8RQ/AgXQ8tS6yP5DW0IL7A3as12x3Pv+Lh784vAE4Nzg/sPzr2ycHShBR15Yz1isNbwDOmXpN1/Y/3Hq4fWhPTgphP5TRtd6CUealciT92Qf9RF23kwse/nLwBiCM0G1GVV9bbsd6TWm3NoeINwBhbH/g49LDQ0n9AVueVNUfsGO9dufTAg9/NXgDkO2g3ektyxsbzq4U3h9grOcEAeCBsM8PMNZziRLAA9mx4o+3Hji8Lfk0Ozac39lYMX21PGFZwFhPAN4AvBPEtWSv27Veg86+ewSAp6SWBeddW27HekmiG9T5chAAvhO4zeiM/gBjPaEIgCDILQu0rtW5lUcuAiAo8rYZQTamAEEx9Zma2pV2rBhyEQABGo4NZw+PltYe2UUsCvgBAiBgw8+Of96XdKwYshAAwRt8bbhtvy+gLMD3CIBomLotC+gP4CQCIDJf+wP7tj+gED0CIE5XJH52jOoRAFEb9geObq7tUhbEiQCAslub6Q/EiQDAN9lnx4e/EwKxIAAwYtSevaGYz3TjMasAlmpGiwCIm72VZ6vT+czXepEiAOLFrTwgAKLD7bs4gQCIx/BWnh1u5cEIARABu2yj2/20Tp2P7xEAIWOpJi5AAASJsR7GQwCEhbEeciEAAmG0edFpf27w4CMPAsB338Z6G3sKyIkA8NdxYpKGtF0A8AsB4CG7VJNlGygCAeATxnooGAHgBcZ6KAcBINtgrDe/s7GugBIQAEJxfBdVIACk4Ws9VIgAkIOxHipHALj39fguYz1UjwBwibEeHCMAnGCsBxkIgGoNb+V5w608kIEAqAhjPUhEAJSNsR4EIwBKY1o9lTR+e/v0tQKEIgCKx6088AYBUCyWbcArBEABjDIHSaIb1PnwDQEwncFYb56xHjxFAEyIsR5CQADklY71EjX4aOdAAZ4jAMbG8V2EhwC4GGM9BIsAOMdg2YbuNxnrIVQEwFlYtoFIlBoAxpg9rfUd5Y/h13o7jPUQB61K9v7mnys1XdtWwrFsAzEqPQAs0SHArTyIWCUBYMkLAcZ6QGUBYAkJAS7hBL6qNAAslyEwGOu1Pzd48IGhygPAqjwEuJUHOJOTALAqCgGWbQDncBYAVpkhwFgPuJjTALAKDwHGesDYnAeAVUwIMNYD8hIRANYUITAY683vPF5XAHIREwBW3hDgVh5gOqICwBorBBjrAYUQFwDWj0PAtBJjmoz1gGKIDADruxDg+C5QArEBYA1CQNXuMNYDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABALP4PxPhKst9YjwYAAAAASUVORK5CYII=)Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/web/yospace)

[Integrate with Yospace for server-side ad insertion (SSAI).](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/web/yospace)

---

# cmcd-connector-web

A connector between a THEOplayer instance and a Common Media Client Data (CMCD) server for the THEOplayer HTML5/Tizen/webOS SDK. This implementation supports CMCD data as defined in CTA-5004, published in September 2020.

## Prerequisites

In order to use this connector, a [THEOplayer](https://www.npmjs.com/package/theoplayer) build with a valid license is required. You can use your existing THEOplayer HTML5 SDK license or request yours via [THEOportal](https://portal.theoplayer.com/).

## Installation

Install using your favorite package manager for Node (such as `npm` or `yarn`):

### Install via npm

```bash
npm install @theoplayer/cmcd-connector-web
```

### Install via yarn

```bash
yarn add @theoplayer/cmcd-connector-web
```

## Usage

First you need to add the CMCD connector to your app :

* Add as a regular script

```html
<script type="text/javascript" src="path/to/cmcd-connector.umd.js"></script>
<script type="text/javascript">
  const player = new THEOplayer.Player(element, playerConfiguration);
  const connector = THEOplayerCMCDConnector.createCMCDConnector(player);
</script>
```

* Add as an ES2015 module

```html
<script type="module">
    import { createCMCDConnector } from "path/to/cmcd-connector.esm.js";
    const player = new THEOplayer.Player(element, playerConfiguration);  
    const connector = createCMCDConnector(player);
</script>
```

By default, the data is sent via query arguments, but you can configure the transmission mode before creating the CMCD connector. For example, to transmit via HTTP headers:

* regular script

```html
<script type="text/javascript" src="path/to/cmcd-connector.umd.js"></script>
<script>
  const player = new THEOplayer.Player(element, playerConfiguration);
  const configuration = {
    transmissionMode: THEOplayerCMCDConnector.TransmissionMode.HTTP_HEADER
  }
  const connector = THEOplayerCMCDConnector.createCMCDConnector(player, configuration);
</script>
```

* ES2015 module

```html
<script type="module">
    import { createCMCDConnector, TransmissionMode } from "path/to/cmcd-connector.esm.js";
    const player = new THEOplayer.Player(element, playerConfiguration);
    const configuration = {
      transmissionMode: TransmissionMode.HTTP_HEADER
    }
    const connector = createCMCDConnector(player, configuration);
</script>
```

The connector will be automatically destroyed upon destruction of the provided player. When changing the player source and a content ID is being passed in, this is to be reset through `reconfigure()` as it will not be cleared automatically.

## Remarks

Note that when native playback is being used, either through THEOplayer's configuration, or due to absence of MSE/EME APIs, the JSON Object transmission mode should be used.

Currently, all standardized reserved keys are reported, except:

* Object duration (`d`)
* Next object request (`nor`)
* Next range request (`nrr`)

---

# @theoplayer/cmcd-connector-web

## 1.5.0

### ✨ Features

* Added support for THEOplayer v11.

## 1.4.0

### ✨ Features

* Added support for THEOplayer version 10.

## 1.3.0

### ✨ Features

* Added support for THEOplayer `9.0`.

## 1.2.0

### ✨ Features

* Disable CMCD for HESP requests

## 1.1.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 1.0.2

### 🐛 Issues

* Fix missing API types in TypeScript type definitions.
* Fixed an issue where multiple CMCD query arguments were being added to the request URL.

## 1.0.1

### 🐛 Issues

* Added support for THEOplayer 7.0.

## 1.0.0

### ✨ Features

* Initial release

---

# comscore-connector-web

The Comscore connector provides a Comscore integration for THEOplayer.

## Installation

```sh
npm install @theoplayer/comscore-connector-web
```

This connector depends on the JavaScript ComScore SDK, which should be loaded and available in the global scope before the connector. Get it from your ComScore dashboard or talk to a ComScore representative. This connector was developed and tested with versions 7.2.0.200214 and 7.6.1.210506

```html
<script src="/path/to/comscore.js">
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, a ComscoreConfiguration (which contains your publisher id, also referred to as the c2 value) and the ComscoreMetadata of the first source being set to the player. You can change the metadata dynamically throughout the lifecycle of the connector.

```js
import { ComscoreConnector } from '../../dist/comscore-connector.esm.js';

const comscoreConfig = {
    publisherId: '<your publisher id>',
    applicationName: 'Test App',
    userConsent: '1',
    platformApi: ns_.analytics.PlatformAPIs.WebBrowser,
    debug: true
};

const comscoreMetadata = {
    mediaType: 'longFormOnDemand',
    uniqueId: 'testuniqueId',
    length: 634566, // in milliseconds
    stationTitle: 'THEOTV',
    programTitle: 'Big Buck Bunny',
    episodeTitle: 'Intro',
    genreName: 'Animation',
    classifyAsAudioStream: false,
    customLabels: {
        testcustomlabel: 'testcustomvalue'
    }
};

const comscoreConnector = new ComscoreConnector(player, comscoreConfig, comscoreMetadata);
```

### Optional ComscoreConfiguration properties

#### `usagePropertiesAutoUpdateMode`

When omitted this wil default to foregroundOnly.

#### `skeleton`

Pass an interface object with target platform specific implementations for the necessary Platform APIs. E.g.

```js
analytics.PlatformApi.setPlatformApi(analytics.PlatformApi.PlatformApis.Skeleton, {
    onDataFetch: function (onSuccessCallback, onErrorCallback) {
        // Execute a function with platform-specific code to retrieve up-to-date information.
        runPlatformSpecificCodeToRetrieveValues(onSuccessCallback, onErrorCallback);
    }

    // Other overridden PlatformAPI methods, as needed.
});
```

For more information, please consult the [Skeleton PlatformAPI Implementation Guide](https://mymetrix-support.comscore.com/hc/en-us/article_attachments/31257678886299)

Note that if the skeleton property is defined, the connector will always use `setPlatformAPI(ns_.analytics.PlatformAPIs.Skeleton)`.

#### `platformApi`

Pass a valid value from `ns_.analytics.PlatformAPIs`. When omitted, the connector will report `setPlatformAPI(ns_.analytics.PlatformAPIs.html5)`.

#### `adIdProcessor`

Pass a function with the following signature if you require custom ad id handling: `(ad: Ad) => string`. When omitted, the connector will use `(ad) => ad.id`. Consult THEOplayer's types for more info about the `Ad` interface.

#### `debug`

A flag to enable verbose logging.

### Passing metadata dynamically

The connector allows updating the current asset's metadata at any time. Do it when setting a new source to the player.

```js
comscoreConnector.update(newMetadata);
```

### ComscoreMetadata fields

Based on the `ComscoreMetadata` type, you can tell which fields are mandatory and which aren't. Note that this is purely for the integration to work correctly. Depending on the Comscore solution you are using, different fields are required/optional. The mandatory fields in the `ComscoreMetadata` type are the ones that are mandatory for all three Comscore solutions:

* Video Metrix (V)
* Cross Platform Product Suite (X)
* Cross Media Audience Measurement (C)

| Property                           | Required | Optional |
| ---------------------------------- | -------- | -------- |
| `mediaType`                        | All      |          |
| `uniqueId`                         | All      |          |
| `length`                           | All      |          |
| `c3?`                              | V        |          |
| `c4?`                              | V        |          |
| `c6?`                              | V        |          |
| `stationTitle`                     | All      |          |
| `stationCode?`                     |          | All      |
| `networkAffiliate?`                |          | All      |
| `publisherName?`                   | X C      | V        |
| `programTitle`                     | All      |          |
| `programId?`                       |          | V C      |
| `episodeTitle`                     | All      |          |
| `episodeId?`                       |          | X C      |
| `episodeSeasonNumber?`             | X C      |          |
| `episodeNumber?`                   | X C      |          |
| `genreName`                        | All      |          |
| `genreId?`                         |          | All      |
| `carryTvAdvertisementLoad?`        | X        |          |
| `classifyAsCompleteEpisode?`       | X        |          |
| `dateOfProduction?`                |          | C        |
| `timeOfProduction?`                |          | C        |
| `dateOfTvAiring?`                  | X C      |          |
| `timeOfTvAiring?`                  |          | X C      |
| `dateOfDigitalAiring?`             | X C      |          |
| `timeOfDigitalAiring?`             |          | X C      |
| `feedType?`                        | X        |          |
| `classifyAsAudioStream`            | Al       |          |
| `deliveryMode?`                    |          | All      |
| `deliverySubscriptionType?`        |          | All      |
| `deliveryComposition?`             |          | All      |
| `deliveryAdvertisementCapability?` |          | All      |
| `mediaFormat?`                     |          | All      |
| `distributionModel?`               |          | All      |
| `playlistTitle?`                   |          | C        |
| `totalSegments?`                   |          | V C      |
| `clipUrl?`                         |          | V C      |
| `videoDimension?`                  |          | C        |
| `customLabels?`                    |          | All      |

## Documentation

The integration guidelines from ComScore can be found on their [Unified Digital Measurements page](https://www.comscore.com/Products/Digital/Unified-Digital-Measurement-Enhanced) in the Tagging section.

---

# @theoplayer/comscore-connector-web

## 1.5.0

### ✨ Features

* Added support for THEOplayer v11.

## 1.4.0

### ✨ Features

* Added support for THEOplayer version 10.

## 1.3.0

### ✨ Features

* Added support for THEOplayer `9.0`.

## 1.2.0

### ✨ Features

* Add the option to inform the ComScore library of the environment it is running in through the `setPlatformAPI`.

### 🐛 Issues

* Fixed an issue where DVR window length and offsets were incorrectly reported.
* Fixed an issue where playhead positions or content/ad durations were not reported in (rounded) milliseconds.
* Fixed an issue where only one ad in an adbreak would be reported.
* Fixed an issue where playback of the main content wouldn't get reported if Google IMA returned an empty pre-roll ad break.
* Fixed an issue where no content metadata was reported during a pre-roll ad.

## 1.1.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 1.0.21

### ✨ Features

* Initial release as a connector on npm.

### 🐛 Issues

* Fixed multiple issues where the timing of reporting the DVR window length and the playhead's offset wrt the DVR window end was wrong if a LIVE stream with a CSAI pre-roll was set as the player source.

---

# conviva-connector-web

The Conviva connector provides a Conviva integration for THEOplayer.

## Prerequisites

In order to use this connector, a [THEOplayer](https://www.npmjs.com/package/theoplayer) build with a valid license is required. You can use your existing THEOplayer HTML5 SDK license or request yours via [THEOportal](https://portal.theoplayer.com/).

For setting up a valid Conviva session, you must have access to a [Conviva developer account](https://pulse.conviva.com/) with access to a debug or production key.

## Installation

Install using your favorite package manager for Node (such as `npm` or `yarn`):

### Install via npm

```bash
npm install @theoplayer/conviva-connector-web
```

### Install via yarn

```bash
yarn add @theoplayer/conviva-connector-web
```

## Usage

First you need to define the Conviva metadata and configuration:

```javascript
    const convivaMetadata = {
        ['Conviva.assetName']: 'ASSET_NAME_GOES_HERE',
        ['Conviva.streamUrl']: 'CUSTOMER_STREAM_URL_GOES_HERE',
        ['Conviva.streamType']: 'STREAM_TYPE_GOES_HERE', // VOD or LIVE
        ['Conviva.applicationName']: 'APPLICATION_NAME_GOES_HERE',
        ['Conviva.viewerId']: 'VIEWER_ID_GOES_HERE'
    };

    const convivaConfig = {
        debug: false,
        gatewayUrl: 'CUSTOMER_GATEWAY_GOES_HERE',
        customerKey: 'CUSTOMER_KEY_GOES_HERE' // Can be a test or production key.
    };
```

Optionally, you can include device metadata in the ConvivaConfiguration object. Note that `SCREEN_RESOLUTION_WIDTH`, `SCREEN_RESOLUTION_HEIGHT` and `SCREEN_RESOLUTION_SCALE_FACTOR` are the only fields that Conviva will auto-collect on most web-based platforms.

```typescript
const exampleDeviceMetadata: ConvivaDeviceMetadata = {
    [Constants.DeviceMetadata.BRAND]: "Samsung",
    [Constants.DeviceMetadata.MANUFACTURER]: "Samsung",
    [Constants.DeviceMetadata.MODEL]: "QE43Q64BAUXXN",
    [Constants.DeviceMetadata.TYPE]:  Constants.DeviceType.SMARTTV,
    [Constants.DeviceMetadata.VERSION]: "6.5.0",
    [Constants.DeviceMetadata.OS_NAME]: "Tizen",
    [Constants.DeviceMetadata.OS_VERSION]: "6.5.0",
    [Constants.DeviceMetadata.CATEGORY]: Constants.DeviceCategory.SAMSUNG_TV,
    [Constants.DeviceMetadata.SCREEN_RESOLUTION_WIDTH]: 3840,
    [Constants.DeviceMetadata.SCREEN_RESOLUTION_HEIGHT]: 2160,
    [Constants.DeviceMetadata.SCREEN_RESOLUTION_SCALE_FACTOR]: 1
}

convivaMetadata.deviceMetadata = exampleDeviceMetadata
```

Using these configs you can create the Conviva connector with THEOplayer.

* Add as a regular script:

```html
<script type="text/javascript" src="path/to/conviva-connector.umd.js"></script>
<script type="text/javascript">
    const player = new THEOplayer.Player(element, configuration);
    const convivaIntegration = new THEOplayerConvivaConnector.ConvivaConnector(
            player,
            convivaMetadata,
            convivaConfig
    );
</script>
```

* Add as an ES2015 module:

```html
<script type="module">
    import { ConvivaConnector } from "path/to/conviva-connector.esm.js";
    const player = new THEOplayer.Player(element, configuration);
    const convivaIntegration = new ConvivaConnector(player, convivaMetadata, convivaConfig);
</script>
```

The Conviva connector is now ready to start a session once THEOplayer starts playing a source.

Note that the `convivaMetadata` provided to the `ConvivaConnector` constructor is primarily used to pass application specific information to Conviva. Source specific metadata can be provided through the connector's `setContentInfo` method. This data does not carry over to the following sources and needs to be set after the `sourcechange` event has been received.

```js
player.source = exampleSource;

const onSourceChange = () => {
    convivaIntegration.setContentInfo(exampleSourceMetadata);
}
player.addEventListener('sourcechange', onSourceChange);
```

## Usage with Yospace connector

If you have a Yospace SSAI stream and want to also report ad related events to Conviva, you can use this connector in combination with the Yospace connector: [@theoplayer/yospace-connector-web](https://www.npmjs.com/package/@theoplayer/yospace-connector-web)

After configuring the Yospace connector, can link it to the Conviva connector:

```javascript
async function setupYospaceConnector(player) {
        const source = {
            sources: [
                {
                    src: "https://csm-e-sdk-validation.bln1.yospace.com/csm/extlive/yospace02,hlssample42.m3u8?yo.br=true&yo.av=4",
                    ssai: {
                        integration: "yospace"
                    }
                }
            ]
        };
        
        // Create the connectors.
        const yospace = new THEOplayerYospaceConnector.YospaceConnector(player);
        const conviva = new THEOplayerConvivaConnector.ConvivaConnector(player, convivaMetadata, convivaConfig);
    
        // Link ConvivaConnector with the YospaceConnector.
        conviva.connect(yospace);
        
        // Set the source.
        await yospace.setupYospaceSession(source);
    }
```

---

# @theoplayer/conviva-connector-web

## 3.3.2

### 🐛 Issues

* Report THEOads interstitial errors as failed ads.

## 3.3.1

### 🐛 Issues

* Added support for `@theoplayer/yospace-connector-web` version 3.

## 3.3.0

### ✨ Features

* Added support for THEOplayer v11.

## 3.2.0

### ✨ Features

* Changed the behaviour of `stopAndStartNewSession`, not starting a new session if the player is paused until play-out is resumed.
* Added reporting of THEOads `streamActivityMonitorId`, which is passed to the GAM Pod stream request.

## 3.1.2

### 🐛 Issues

* Fixed an issue where ads were no longer reported correctly, caused by a deprecation in the adBreakBegin event.

## 3.1.1

### 🐛 Issues

* Fixed an issue that prevented the ESM build from being loaded using an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap).
  * The ESM build now imports the Conviva SDK using a default import (`import Conviva from '@convivainc/conviva-js-coresdk'`) rather than a named import (`import { Analytics, Constants } from '@convivainc/conviva-js-coresdk'`).

## 3.1.0

### ✨ Features

* Moved the ad start tracking to when the first frame has loaded.
* Added reporting of `encoding_type` (either "DASH", "HLS" or "HESP"), as well as `Constant.defaultResource` and `intentToFallback` reason for THEOlive sources.

## 3.0.0

### 💥 Breaking Changes

* Dropped support for THEOplayer version 8.11.0 and lower.

### ✨ Features

* Added support for THEOplayer version 10.

## 2.9.0

### ✨ Features

* Added play-out configuration values such as `liveOffset`, `targetBuffer`, `bufferLookbackWindow`, `abrStrategy` and `abrMetadata` as custom metadata fields.
* Fixed an issue where the `streamType` value set through the connector API could be overriden with a different value by the connector.

## 2.8.0

### ✨ Features

* Added full call stack info to an error report by splitting it in multiple entries.

## 2.7.0

### ✨ Features

* Added the ability to include the player name in the metadata object passed when creating the ConvivaConnector.
* Added support for THEOplayer `9.0`.

## 2.6.0

### ✨ Features

* Added a check to differentiate between Samsung, LG, Xbox and Vizio when defining the default device category in the metadata.
* Added a detailed report, containing the current player buffer and last fetched segments, in case of a playback failure.

### 🐛 Issues

* Added 'Server Guided' as ad type passed when reporting a THEOads ad break has started.

## 2.5.1

### 🐛 Issues

* Fixed an issue where the stream type, either `VOD` or `Live`, would sometimes be set with a wrong value for live streams.

## 2.5.0

### ✨ Features

* Added `deviceMetadata` property to `ConvivaConfiguration`.

### 🐛 Issues

* Fixed an issue where an asset name, provided via a `ConvivaMetadata` object in the `ConvivaConnector` initialization, stops getting reported after a `sourcechange` event.
* Fixed an issue where the content type of an ad would sometimes be reported as "Live".

## 2.4.0

### ✨ Features

* Added 'Server Guided' ad technology.

## 2.3.0

### ✨ Features

* Added reporting of slate for THEOads.
* Added additional error details on playback failure.

## 2.2.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 2.1.4

### 🐛 Issues

* Fixed an issue where we could throw an error for non Google-IMA ads.

## 2.1.3

### 🐛 Issues

* Fixed an issue where the metadata is not passed correctly after a replay.

## 2.1.2

### 🐛 Issues

* Fixed an issue where the `segmentnotfound` event was reported as a fatal error.

## 2.1.1

### 🐛 Issues

* Report average bitrate to Conviva.

## 2.1.0

### ✨ Features

* Changed Conviva SDK to a peer dependency, enabling users to update it independently from the Conviva connector.

### 🐛 Issues

* Fixed an issue where TypeScript could throw a TS2307 type error on the generated type definitions when the optional `@theoplayer/yospace-connector-web` peer dependency is not installed.

### 📦 Dependency Updates

* @theoplayer/yospace-connector-web\@2.1.2

## 2.0.2

### 🐛 Issues

* Fixed an issue where the THEOplayer library and the Yospace connector were accidentally bundled together with the Conviva connector.

### 📦 Dependency Updates

* @theoplayer/yospace-connector-web\@2.1.1

## 2.0.1

### 🐛 Issues

* Added functionality to listen for external ad events using the `convivaAdEventsExtension` property.

## 2.0.0

### 📦 Dependency Updates

* @theoplayer/yospace-connector-web\@2.1.0

## 1.3.0

### ✨ Features

* Updated to be compatible with THEOplayer `6.X`.

## 1.2.0

### ✨ Features

* Added error event with addition error information on playback failed.

## 1.1.7

### 🐛 Issues

* Removed reporting a buffering state on getting an `emptied` event.

## 1.1.6

### ✨ Features

* Added ad metadata for CSAI.

### 🐛 Issues

* Fixed an issue where the ad break position would be incorrectly reported.

## 1.1.5

### 🐛 Issues

* Updated yospace connector peer dependency.

## 1.1.4

### 🐛 Issues

* Fixed an issue where a session could be created without a source.

## 1.1.3

### Changed

* Made THEOplayer an external dependency.

## 1.1.2

### 🐛 Issues

* Fixed passing content length for a live stream or on early error.

## 1.1.1

### Changed

* Updated THEOplayer version to 5.X.

## 1.1.0

### ✨ Features

* Added `setContentInfo` to pass video metadata during playback.
* Added `setAdInfo` to pass ad metadata during playback.
* Added `reportPlaybackFailed` to notify Conviva of non-video errors.
* Added `stopAndStartNewSession` to enable explicitly stopping the current session and starting a new one.
* Added visibility change reporting.
* Updated THEOplayer version to 4.X.
* Improved error handling.
* Improved default metadata.

### 🐛 Issues

* Fixed handling a replay of the same source.

## 1.0.0

### ✨ Features

* Initial release

---

# Nielsen Web Connector

A connector implementing Nielsen with THEOplayer.

## Installation

```sh
npm install @theoplayer/nielsen-connector-web
```

## Usage

### Configuring the connector

Create the connector by providing the following mandatory parameters:

* The `THEOplayer` instance
* the Nielsen App ID
* the channelName for the asset

and optionally the following parameters:

* a `NielsenOptions` object
* a `NielsenConfiguration` object (if none is provided, the default configuration disables DCR, enables DTVR and sets the country to US)

```js
import { NielsenConnector } from '../../dist/THEOplayerNielsenConnector';

const appId = '<your app ID>';
const channelName = '<your channel name>';

// Non-mandatory options
const options: NielsenOptions = {
    containerId: 'THEOplayer',
    optout: false
};

// Non-mandatory configuration (e.g. for DCR tracking with the Czech Republic SDK)
const configuration: NielsenConfiguration = {
    country: NielsenCountry.CZ,
    enableDTVR: false,
    enableDCR: true
};
const nielsenConnector = new NielsenConnector(player, appId, channelName, options);
```

The `NielsenOptions` can have the following fields:

| Key            | Value                                                           |
| -------------- | --------------------------------------------------------------- |
| `containerId`  | HTML DOM element id of the player container.                    |
| `nol_sdkDebug` | Enables Debug Mode which allows output to be viewed in console. |
| `optout`       | Whether to opt-out of Nielsen Measurement.                      |

### Passing metadata dynamically (DTVR)

The connector allows updating the current asset's metadata at any time. Note that Nielsen's [documentation](https://engineeringportal.nielsen.com/wiki/updateMetadata_\(Browser\)) prohibits updating of the values for `type`, `vidtype` or `assetid` parameters

```js
const metadata = {
    ['channelName']: 'newChannelName',
    ['customTag1']: 'customValue1',
    ['customTag2']: 'customValue2'
};
nielsenConnector.updateMetadata(metadata);
```

### Passing metadata when setting a source to the player (DCR)

This can be achieved through the `updateDCRContentMetadata` method, e.g.:

```js
const metadata: NielsenDCRContentMetadataCZ = {
    assetid: 'cz-500358-98731568435405',
    program: 'Animated Test Content',
    title: 'Big Buck Bunny',
    length: '596',
    airdate: '20230620 20:00:00',
    isfullepisode: true,
    crossId1: '915 954 39504',
    c2: '651678089925925',
    segB: '011',
    adloadtype: AdLoadType.linear,
    hasAds: HasAds.supports_ads
};

nielsenConnector.updateDCRContentMetadata(metadata);
```

Note that types are included in the package: `NielsenDCRContentMetadataUS`, `NielsenDCRContentMetadataCZ`. Please contact your THEO Technologies representative if you need support for another International DCR SDK.

---

# @theoplayer/nielsen-connector-web

## 1.7.0

### ✨ Features

* Added support for THEOplayer v11.

## 1.6.0

### ✨ Features

* Added support for THEOplayer version 10.

## 1.5.0

### ✨ Features

* Added support for THEOplayer `9.0`.

## 1.4.0

### ✨ Features

* Added an optional c4 parameter to `NielsenDCRContentMetadataCZ`.

## 1.3.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 1.2.0

### ✨ Features

* Add DCR support (CZ and US).

## 1.1.2

### 🐛 Issues

* Fixed an issue where the package did not properly export the Nielsen types.

## 1.1.1

### 🐛 Issues

* Added support for DASH emsg cue payloads.

## 1.1.0

### ✨ Features

* Updated to be compatible with THEOplayer `6.X`.

## 1.0.0

### ✨ Features

* Initial release

---

# yospace-connector-web

The Yospace connector provides a Server-Side Ad Insertion (SSAI) integration with Yospace for THEOplayer.

## Prerequisites

In order to use this connector, a [THEOplayer](https://www.npmjs.com/package/theoplayer) build with a valid license is required. You can use your existing THEOplayer HTML5 SDK license or request yours via [THEOportal](https://portal.theoplayer.com/).

For setting up a valid Yospace session, the Yospace Ad Management SDK is required. For more information on how to install the Ad Management SDK, please refer to the documentation of [Yospace](https://docs.yospace.com/library/technical/sdks/en/ad-management-sdks-v3/javascript.html).

**Remark:** This version of the Yospace Connector is compatible with Yospace Ad Management SDK version 3.10.0 or higher. If you still want to use an older Ad Management SDK, please use the connector version 2.8.0 or earlier.

## Installation

Install using your favorite package manager for Node (such as `npm` or `yarn`):

### Install via npm

```bash
npm install @theoplayer/yospace-connector-web
```

### Install via yarn

```bash
yarn add @theoplayer/yospace-connector-web
```

## Usage

First you need to add the Yospace connector to your app :

* Add as a regular script

```html
<script type="text/javascript" src="path/to/yospace-connector.umd.js"></script>
<script type="text/javascript">
    const player = new THEOplayer.Player(element, configuration);
    const yospaceConnector = new THEOplayerYospaceConnector.YospaceConnector(player);
</script>
```

* Add as an ES2015 module

```html
<script type="module">
    import { YospaceConnector } from "path/to/yospace-connector.esm.js";
    const player = new THEOplayer.Player(element, configuration);
    const yospaceConnector = new YospaceConnector(player);
</script>
```

To make use of the Yospace integration, you need to set up a session for your Yospace source :

```javascript
const source = {
    sources: [
        {
            src: "YOUR_YOSPACE_SRC",
            ssai: {
                integration: "yospace"
                // If necessary, you can define your streamType.
                // streamType: 'vod' | 'live' | 'livepause'
            }
        }
    ]
}

await yospaceConnector.setupYospaceSession(source);
```

If you want to customize your session, you can also pass your customized `SessionProperties` from the Yospace Ad Management SDK :

```javascript
// create a new SessionProperties object using the Ad Management SDK.
const sessionProperties = new YospaceAdManagement.SessionProperties();
const source = {
    sources: [
        {
            src: "YOUR_YOSPACE_SRC",
            ssai: {
                integration: "yospace"
                // If necessary, you can define your streamType.
                // streamType: 'vod' | 'live' | 'livepause'
            }
        }
    ]
}

await yospaceConnector.setupYospaceSession(source, sessionProperties);
```

Once the setup of the Yospace session is done, you can continue to use the player and the connector will handle everything related to Yospace.

---

# @theoplayer/yospace-connector-web

## 3.0.0

### 💥 Breaking Changes

* Removed `isPlaceholder()` and `isEncoded()` type definitions since they were removed in Yospace Ad Management SDK 3.11.0.
* Replaced `PlaybackMode` with `SessionMode` for compatibility with Yospace Ad Management SDK 3.10.0+. This change brings the minimum supported Yospace Ad Management SDK version to 3.10.0.

### 🐛 Issues

* Fixed an exception when an ad break starts without data during live playback.

## 2.8.0

### ✨ Features

* Added support for THEOplayer v11.

## 2.7.0

### ✨ Features

* Added support for THEOplayer version 10.

## 2.6.0

### ✨ Features

* Added support for THEOplayer `9.0`.

## 2.5.0

### ✨ Features

* Create ad break from advert start, if missing

### 🐛 Issues

* Require THEOplayer 8.1.0 or higher for correct TypeScript type definitions.

## 2.4.0

### ✨ Features

* Added support for THEOplayer `8.0`.

## 2.3.0

### ✨ Features

* Added `YospaceServerSideAdInsertionConfiguration` type definition to the connector, superseding the type defined by the THEOplayer Web SDK.

## 2.2.0

### ✨ Features

* The connector now integrates with the [custom server-side ad integration API](https://www.theoplayer.com/docs/theoplayer/v7/api-reference/web/interfaces/Ads.html#registerServerSideIntegration.registerServerSideIntegration-1) introduced in THEOplayer 7.4.0. This allows Yospace adverts to show up through the `player.ads` API of THEOplayer.

## 2.1.3

### 🐛 Issues

* Fixed playback position reporting for live DVR streams (with `streamType` set to `"livepause"`).

## 2.1.2

### 🐛 Issues

* Fix missing API types in TypeScript type definitions.

## 2.1.1

### 🐛 Issues

* Added support for THEOplayer 7.0.

## 2.1.0

### ✨ Features

* Exposed SessionErrorCode.

## 2.0.0

### ✨ Features

* Upgrade to latest Yospace Ad Management SDK

## 1.4.0

### ✨ Features

* Allow THEOplayer 6.0.0 as peer dependency

## 1.3.0

### ✨ Features

* Update THEOplayer peer dependency

## 1.2.0

### ✨ Features

* Expose typings

### 🐛 Issues

* Handle empty `activeCues` list

## 1.1.0

### ✨ Features

* Add support for custom Analytics Event Observers

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer Android SDK

Dolby OptiView Player (formerly THEOplayer) is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/getting-started.md)

[Set up your first THEOplayer in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md)

## [🔌Connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android.md)

[Integrate third-party solutions with THEOplayer using our pre-built connectors.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog.md)

[Find out what's new in the OptiView Player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog.md)

## [\*️⃣API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android)

[Discover all properties and functions of THEOplayer.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

# Getting started on Android

## Add THEOplayer and Kotlin libraries to your application

We have to modify the `build.gradle` files to be able to fetch the Android SDK and the Kotlin plugin.

1. In your **top-level** (project) `settings.gradle.kts` file

2. Add the THEOplayer Maven repository.

**Groovy**

```groovy
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url "https://maven.theoplayer.com/releases" }
    }
}
```

**Kotlin**

```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://maven.theoplayer.com/releases") }
    }
}
```

1. Next, we need to edit the `build.gradle` on the **module-level** (**app/build.gradle**)

**Groovy**

```groovy
implementation "com.theoplayer.theoplayer-sdk-android:core:+"
implementation "org.jetbrains.kotlin:kotlin-stdlib:1.6.21"
implementation "androidx.appcompat:appcompat:1.7.0"
```

**Kotlin**

```kotlin
implementation("com.theoplayer.theoplayer-sdk-android:core:+")
implementation("org.jetbrains.kotlin:kotlin-stdlib:1.6.21")
implementation("androidx.appcompat:appcompat:1.7.0")
```

*Note*: It's possible to replace the `+` with a particular version of THEOplayer that should be used, for example:

`implementation 'com.theoplayer.theoplayer-sdk-android:core:8.0.0'`

## Setting up the license

You need to configure your THEOplayer license, if you don't enter this license string, you might encounter licensing issues (e.g.: when trying to play non-whitelisted video streams).

First, obtain a THEOplayer Android SDK license through the [THEOplayer Developer Portal](https://portal.theoplayer.com/login). ![](https://cdn.theoplayer.com/images/git/theoplayer-android-sdk-license-string.png)

Then, identify your license string from the screenshot above and add the `<meta-data ...` tag below at the appropriate location in your `AndroidManifest.xml`, and swap `your_license_here` with your actual license string.

```xml
<application>
    <meta-data
        android:name="THEOPLAYER_LICENSE"
        android:value="your_license_here" />
</application>
```

Additionally, to play online videos with THEOplayer, you first need to add [INTERNET](https://developer.android.com/reference/android/Manifest.permission.html#INTERNET) permission into the `AndroidManifest.xml` file too.

```xml
<uses-permission android:name="android.permission.INTERNET" />
```

More information regarding the license can be found [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/license/introduction.md).

## Add THEOplayer view to your application

THEOplayer can be added to an Android application either:

1. **Through a layout (XML)**: By adding the `THEOplayerView` to your layout XML file (e.g., `activity_main.xml`), or
2. **Programmatically using the Constructor API**: This approach also allows you to configure the license string through a programmatic configuration instead of the `AndroidManifest.xml`.

### Adding THEOplayerView via XML layout

You can add the `THEOplayerView` to the layout of the `MainActivity` with the snippet below.

![](/pr-932/assets/images/android-getting-started-13_2-2581c1dcb239371b38441eff6e36e67d.png)

At least the `id`, `width` and `height` attributes need to be specified on the new view. The `id` is important as it is used to identify the view object in your `MainActivity` class.

```xml
<com.theoplayer.android.api.THEOplayerView
    android:id="@+id/theoplayer"
    android:layout_width="match_parent"
    android:layout_height="300dp"
    app:layout_constraintTop_toTopOf="parent">
</com.theoplayer.android.api.THEOplayerView>
```

![](/pr-932/assets/images/android-getting-started-14_2-d3679a00ce0fd4aa120793ddf8a96df3.png)

### Adding THEOplayerView programmatically (Constructor API)

In the Activity/Fragment, you can use the [constructor API](https://docs.theoplayer.com/api-reference/android/index.html?com/theoplayer/android/api/THEOplayerView.html) to create a THEOplayer instance by passing along a context and a [`THEOplayerConfig`](https://docs.theoplayer.com/api-reference/android/index.html?com/theoplayer/android/api/THEOplayerConfig.html).

In this `THEOplayerConfig`, you can configure your license string, as demonstrated in the snippet below.

**Kotlin**

```kotlin
val playerConfig = THEOplayerConfig.Builder()
    .license("your_license_here")
    .build()

val theoPlayerView = THEOplayerView(this, playerConfig)
```

**Java**

```java
THEOplayerConfig playerConfig = new THEOplayerConfig.Builder()
    .license("your_license_here")
    .build();

THEOplayerView theoPlayerView = new THEOplayerView(this, playerConfig);
```

This approach is ideal when you need to adjust the configuration dynamically, such as during runtime or based on specific app conditions. It removes the need for XML-based configuration and is useful for advanced customization scenarios.

## Use THEOplayer API in your application

Now in the `MainActivity` we can retrieve the `THEOplayerView` by the `id` we set earlier using the `findViewById` method.

### 1. Get the THEOplayer instance

**Kotlin**

```kotlin
...
import com.theoplayer.android.api.THEOplayerView

class MainActivity : ComponentActivity() {
    lateinit var theoPlayerView: THEOplayerView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        theoPlayerView = findViewById(R.id.theoplayer)
    }
}
```

**Java**

```java

import com.theoplayer.android.api.THEOplayerView;

public class MainActivity extends ComponentActivity {
    private THEOplayerView theoPlayerView;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        theoPlayerView = findViewById(R.id.theoplayer);
    }
}
```

### 2. Configure source

To play a video in THEOplayer, we need to configure a source for the player in our `MainActivity`:

**Kotlin**

```kotlin
val typedSource = TypedSource
    .Builder("https://cdn.theoplayer.com/video/dash/big_buck_bunny/BigBuckBunny_10s_simple_2014_05_09.mpd")
    .type(SourceType.DASH)
    .build()

val sourceDescription = SourceDescription
    .Builder(typedSource)
    .build()

theoPlayerView.player.source = sourceDescription
```

**Java**

```java
TypedSource typedSource = new TypedSource
        .Builder("https://cdn.theoplayer.com/video/dash/big_buck_bunny/BigBuckBunny_10s_simple_2014_05_09.mpd")
        .type(SourceType.DASH)
        .build();

SourceDescription sourceDescription = new SourceDescription
        .Builder(typedSource)
        .build();

theoPlayerView.getPlayer().setSource(sourceDescription);
```

### 3. Control THEOplayer through the API

We will now introduce a button to start/stop the video in the player.

First add the button to our `activity_main.xml` layout file.

```xml
<Button
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:id="@+id/btn_playpause"
        android:text="PLAY/PAUSE" />
```

![](/pr-932/assets/images/android-getting-started-16_2-c9da3210e9ea5233dd37a28b23cf3436.png)

Then set an `OnClickListener()` on the button in our `MainActivity` code to trigger `play()` and `pause()` on the player.

**Kotlin**

```kotlin
val btnPlayPause = findViewById<Button>(R.id.btn_playpause)
btnPlayPause.setOnClickListener {
    if (theoPlayerView.player.isPaused) {
        theoPlayerView.player.play()
    } else {
        theoPlayerView.player.pause()
    }
}
```

**Java**

```java
Button btnPlayPause = findViewById(R.id.btn_playpause);
btnPlayPause.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        if (theoPlayerView.getPlayer().isPaused()) {
            theoPlayerView.getPlayer().play();
        } else {
            theoPlayerView.getPlayer().pause();
        }
    }
});
```

![](/pr-932/assets/images/android-getting-started-17_2-7c2ab5a4cca6f765e67b9c91989dab65.png)

### 4. Listen for THEOplayer events

The next step is listening for player events.

First, we need to create two more TextViews in the `activity_main.xml` file.

```xml
<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/txt_playstatus"
    android:layout_marginStart="20dp"/>

<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/txt_timeupdate"
    android:layout_marginStart="20dp"/>
```

We will now listen for `PLAY`, `PAUSE` and `TIMEUPDATE` in this example.

**Kotlin**

```kotlin
val txtPlayStatus = findViewById<TextView>(R.id.txt_playstatus)
val txtTimeUpdate = findViewById<TextView>(R.id.txt_timeupdate)

theoPlayerView.player.addEventListener(PlayerEventTypes.PLAY) {
    txtPlayStatus.text = "Playing"
}

theoPlayerView.player.addEventListener(PlayerEventTypes.PAUSE) {
    txtPlayStatus.text = "Paused"
}

theoPlayerView.player.addEventListener(PlayerEventTypes.TIMEUPDATE) { timeUpdateEvent ->
    txtTimeUpdate.text = timeUpdateEvent.currentTime.toString()
}
```

**Java**

```java
TextView txtPlayStatus = findViewById(R.id.txt_playstatus);
TextView txtTimeUpdate = findViewById(R.id.txt_timeupdate);

theoPlayerView.getPlayer().addEventListener(PlayerEventTypes.PLAY, new EventListener<PlayEvent>() {
    @Override
    public void handleEvent(PlayEvent playEvent) {
        txtPlayStatus.setText("Playing");
    }
});

theoPlayerView.getPlayer().addEventListener(PlayerEventTypes.PAUSE, new EventListener<PauseEvent>() {
    @Override
    public void handleEvent(PauseEvent pauseEvent) {
        txtPlayStatus.setText("Paused");
    }
});

theoPlayerView.getPlayer().addEventListener(PlayerEventTypes.TIMEUPDATE, new EventListener<TimeUpdateEvent>() {
    @Override
    public void handleEvent(TimeUpdateEvent timeUpdateEvent) {
        txtTimeUpdate.setText(String.valueOf(timeUpdateEvent.getCurrentTime()));
    }
});
```

When the events are triggered, we will update the **MainActivity** UI with the corresponding state.

### 5. Play fullscreen video in landscape mode

THEOplayer SDK contains a default fullscreen activity which can be started automatically when you rotate your device.

We have to configure our player instance in the `MainActivity` to react to orientation changes and start the Fullscreen activity.

**Kotlin**

```kotlin
override fun onCreate(savedInstanceState: Bundle?) {
    //...
    theoPlayerView = findViewById(R.id.theoplayer)
    theoPlayerView.fullScreenManager.isFullScreenOrientationCoupled = true
    //...
}
```

**Java**

```java
@Override
protected void onCreate(Bundle savedInstanceState) {
    // ...
    theoPlayerView = findViewById(R.id.theoplayer);
    theoPlayerView.getFullScreenManager().setFullScreenOrientationCoupled(true);
    // ...
}
```

![](/pr-932/assets/images/android-getting-started-21_2-2d0fe0d572fda2b75cd485696997f3b8.png)

In the `AndroidManifest.xml` we can disable the default orientation behavior on our `MainActivity` and lock it in portrait. Then, because we enabled fullscreen orientation coupling with the `setFullScreenOrientationCoupled(true)` method earlier, THEOplayer will take care of the support of seamless landscape activity transition at rotation.

```xml
<activity android:name=".MainActivity"
    android:screenOrientation="userPortrait"
    android:configChanges="orientation|screenSize" >
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />

        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>
```

If you would like to customize the Fullscreen Activity, you can take a look at our sample [here](https://github.com/THEOplayer/samples-android-sdk/tree/master/full-screen-handling).

## Couple THEOplayer with the lifecycle callbacks

In order for THEOplayer to work properly and in sync with the [Activity lifecycle changes](https://developer.android.com/guide/components/activities/activity-lifecycle) (e.g. when we rotate the device or start a new Activity or the app goes to background). We need to call the `onResume`, `onPause` and `onDestroy` methods of the `THEOplayerView` when the matching methods are called in the Activity.

**Kotlin**

```kotlin
class MainActivity : ComponentActivity() {

    // ...

    override fun onPause() {
        super.onPause()
        theoPlayerView.onPause()
    }

    override fun onResume() {
        super.onResume()
        theoPlayerView.onResume()
    }

    override fun onDestroy() {
        super.onDestroy()
        theoPlayerView.onDestroy()
    }

    // ...

}
```

**Java**

```java
public class MainActivity extends AppCompatActivity{

    // ...

    @Override
    protected void onPause() {
        super.onPause();
        theoPlayerView.onPause();
    }

    @Override
    protected void onResume() {
        super.onResume();
        theoPlayerView.onResume();
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        theoPlayerView.onDestroy();
    }

    // ...
}
```

## Run your application

Here you have some screenshots from the running application:

### Start screen

![](/pr-932/assets/images/android-getting-started-screenshot-1-38ce0ff7ab21b1cffa889c91d2543b9f.png)

### Playing screen

![](/pr-932/assets/images/android-getting-started-screenshot-2-d107e77d808409e46aceb0af2254c254.png)

### Paused screen

![](/pr-932/assets/images/android-getting-started-screenshot-3-a2952d823ef5f5c639d5fca97458b8f6.png)

### Rotated fullscreen

![](/pr-932/assets/images/android-getting-started-screenshot-4-cadbdc87fd1b76e026ce32081367c1d6.png)

## Summary

This guide focuses on creating an Android application from scratch and integrating the THEOplayer Android SDK.

* You have learned how to interact with the player via the available APIs in Kotlin and Java,
* you have registered player events,
* and you have learned how to enable automatic orientation detection.

You can find various samples for different use cases on [GitHub](https://github.com/THEOplayer/samples-android-sdk/tree/master).

Did you encounter any issues? Raise a ticket through [the ticketing system](https://opentelly.atlassian.net/servicedesk/customer/portal/1) and we will be happy to assist.

---

# Getting started with the Android UI

For the most up-to-date information about our new open source, fully native Android UI, visit [the GitHub page](https://github.com/THEOplayer/android-ui).

---

# Android Feature Integrations

## Modularization

The Android THEOplayer SDK uses modularized features, which means there is a base SDK that can handle basic playback and additional feature integrations are provided as separate modules that can be added as desired. This approach gives more flexibility and results in a reduced application size, since non-required parts are not included in the build of the application.

For example, the base SDK is provided by:

```groovy
implementation 'com.theoplayer.theoplayer-sdk-android:core:8.0.0'
```

Meanwhile, additional features such as Google IMA and Google Cast are provided by:

```groovy
implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-ima:8.0.0'
implementation 'com.theoplayer.theoplayer-sdk-android:integration-cast:8.0.0'
```

## Importing additional integration modules

As shown in the previous section, importing additional integration modules can be done by simply adding the dependency in the `build.gradle` file of the module using THEOplayer.

> **Important**
>
> It is required to keep the Android base SDK and all the required integration modules on the **same** version number. For example one should **not** import `core:8.1.0` and `integration-cast:8.2.0` in the same project.
>
> Consider using [version catalogs](https://developer.android.com/build/migrate-to-catalogs) in your app to manage the version of the base SDK and the integration modules.

## Adding integrations

After importing the dependencies, it's time to create the integrations and connect them to THEOplayer.

### Adding integrations automatically

Starting with version 8.13.0, the Android SDK supports automatically connecting all available integrations to your player. When constructing your `THEOplayerView`, set [`THEOplayerConfig.autoIntegrations`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/THEOplayerConfig.Builder#autoIntegrations\(boolean\)) to `true`:

```kotlin
val theoplayerConfig = THEOplayerConfig.Builder()
    .autoIntegrations(true)
    .build()
val theoplayerView = THEOplayerView(context, theoplayerConfig)
```

The player will automatically create and attach any integrations that were added to your app's dependencies.

> **Info**
>
> Starting with version 9.0.0, this automatic behavior will become the default. You can always opt out by manually setting [`THEOplayerConfig.autoIntegrations`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/THEOplayerConfig.Builder#autoIntegrations\(boolean\)) to `false`.

### Adding integrations manually

You can also create and attach each integration manually.

Each module provides a **Factory** class that allows the creation of that specific integration. For example, the Google IMA module provides [`GoogleImaIntegrationFactory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/ads/ima/GoogleImaIntegrationFactory) and the Google Cast module provides [`CastIntegrationFactory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/cast/CastIntegrationFactory). You can then attach the created integration to your player using the [`addIntegration(Integration integration)`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#addIntegration\(com.theoplayer.android.api.Integration\)) method of the `Player` API.

For example, to set up the Google IMA integration, you create an integration using the [`GoogleImaIntegrationFactory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/ads/ima/GoogleImaIntegrationFactory) and then attach it to the player using [`addIntegration(Integration integration)`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#addIntegration\(com.theoplayer.android.api.Integration\)):

```kotlin
import com.theoplayer.android.api.ads.ima.GoogleImaIntegrationFactory

val theoplayerView = THEOplayerView(context)
val googleImaIntegration = GoogleImaIntegrationFactory.createGoogleImaIntegration(theoplayerView)
theoplayerView.player.addIntegration(googleImaIntegration)
```

[The documentation of each individual integration](#available-feature-integrations) provides more detail on how to set up and configure that integration.

> **Warning**
>
> You must call `addIntegration()` before using the integration. Attempting to call a method on the integration without attaching it to a player will throw an error.

## Available feature integrations

With Android THEOplayer SDK we currently support the following feature integrations:

| Feature         | Dependency                      | Release | Documentation                                                                                                                                       |
| --------------- | ------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Google IMA      | `integration-ads-ima:+`         | 3.1.0+  | [Google IMA Documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/google-ima.md#android-sdk)               |
| Chromecast      | `integration-cast:+`            | 3.4.0+  | [Chromecast Documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/introduction.md#android-sdk) |
| AWS MediaTailor | `integration-ads-mediatailor:+` | 4.0.0+  | [AWS MediaTailor Documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/mediatailor.md#android-sdk)         |
| Google DAI      | `integration-ads-dai:+`         | 4.3.0+  | [Google DAI Documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/google-dai.md#android-sdk)               |
| Optiview Ads    | `integration-ads-theoads:+`     | 8.2.0+  | [Optiview Ads Documentation](https://docs-preview.optiview.dolby.com/pr-932/ads/player-integration/optiview-player/android.md)                      |
| Millicast       | `integration-millicast:+`       | 8.2.0+  | [Millicast Documentation](https://docs-preview.optiview.dolby.com/pr-932/millicast/android-player)                                                  |
| Jetpack Media3  | `integration-media3:+`          | 8.10.0+ | [Media3 Documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/android/media3/getting-started.md)               |

---

# Migrating to THEOplayer Android SDK 10.x

This article will guide you through updating to THEOplayer Android SDK version 10 (from version 9), and the changes needed in your code.

## Update THEOplayer

Update THEOplayer Android SDK to version 10 in your **module-level** `build.gradle` file:

```groovy
dependencies {
    implementation 'com.theoplayer.theoplayer-sdk-android:core:10.+'
}
```

If you're using the [Open Video UI for Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui.md) or one of [our connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android.md), make sure to update them to the latest version too to ensure proper support for THEOplayer version 10.

## Update `minSdkVersion` to API 23 or higher

The [minimum supported Android version](https://developer.android.com/build#android_sdk_settings) of the THEOplayer Android SDK has been raised from API 21 (Android 5.0 "Lollipop") to API 23 (Android 6.0 "Marshmallow"). This aligns with [other Android Jetpack libraries requiring API 23 as of June 2025](https://developer.android.com/jetpack/androidx/versions#version-table).

Update the `minSdkVersion` to be 23 (or higher) in your **module-level** `build.gradle` file:

```groovy
android {
    defaultConfig {
        minSdkVersion 23
    }
}
```

## Update `compileSdk` to 36 or higher

THEOplayer depends on the AndroidX Core library, which [requires `compileSdk` 36 as of version 1.17.0](https://developer.android.com/jetpack/androidx/releases/core#core_and_core-ktx_version_117_2).

Update the `compileSdk` to be 36 (or higher) in your **module-level** `build.gradle` file:

```groovy
android {
    compileSdk 36
}
```

We also recommend [updating the Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin#updating-plugin) to the latest version. In Android Studio, go to Tools → AGP Upgrade Assistant and follow the steps to update AGP in your project.

## Update to Kotlin Gradle plugin 2.0.0 or higher

THEOplayer now targets the Kotlin 2.0 language level, so you must build your app with Kotlin Gradle Plugin 2.0 or higher. This aligns with [the AndroidX Core library also targeting Kotlin 2.0 as of version 1.17.0](https://developer.android.com/jetpack/androidx/releases/core#core_and_core-ktx_version_117_2).

Update the version of the `org.jetbrains.kotlin.android` plugin to be 2.0.0 (or higher) in your **project-level** `build.gradle` file:

```groovy
plugins {
    id 'org.jetbrains.kotlin.android' version '2.2.20' apply false
}
```

## Media3 as single playback pipeline

THEOplayer now always uses [Jetpack Media3](https://developer.android.com/media/media3) as its playback pipeline, providing more stable playback on a wider range of devices. The legacy playback pipeline (from version 8.x) has been fully retired, and the `TypedSource.playbackPipeline` property has been removed.

Caching is now also handled by Media3. Any previously created caching tasks that used the legacy backend (using `CachingParameters.storageType = CacheStorageType.LEGACY`) will automatically be switched over to the Media3 backend, although their cached content will not be preserved. They can be re-downloaded by calling `CachingTask.start()` again.

See [our Media3 guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/android/media3/getting-started.md) for more information.

## Use modern network stack by default

THEOplayer will now use a modern network stack when available, to take advantage of their HTTP/2 and HTTP/3 support for more optimal media streaming.

The player supports both [`HttpEngine`](https://developer.android.com/reference/android/net/http/HttpEngine) (available in Android 14 or higher) and [Cronet](https://developer.android.com/develop/connectivity/cronet) (when added as a library to your app). When neither of these APIs are available, the player falls back to HTTP/1.1 using [`HttpURLConnection`](https://developer.android.com/reference/java/net/HttpURLConnection).

If you're not yet ready for this switch, you can opt out of this behavior and revert back to `HttpURLConnection` by setting [`NetworkConfiguration.useHttpEngine`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/NetworkConfiguration#useHttpEngine) to `false`.

## Replace usages of deprecated APIs

Some properties and methods that were previously deprecated have been removed from the API. Update your code to use the new APIs instead.

* Removed `TypedSource.playbackPipeline` and `SourceChangeEvent.playbackPipeline`. The player will now always use the Media3 playback pipeline.
* Removed unused `GoogleDaiConfiguration.format`.
* Removed `MediaTailorSource.adParams`. Use `MediaTailorSource.adsParams` instead.
* Removed the `DashPlaybackConfiguration.ignoreAvailabilityWindow()` method. Use the `.ignoreAvailabilityWindow` property instead.
* Removed `KeySystemConfiguration.isUseCredentials`. Use `KeySystemConfiguration.useCredentials` instead.
* Removed `ConaxDRMConfiguration.Builder.fairPlay()`. Use `ConaxDRMConfiguration.Builder.fairplay()` instead.
* Removed THEOlive publication events (`PublicationLoadStartEvent`, `PublicationLoadedEvent` and `PublicationOfflineEvent`). Use the equivalent distribution events instead (`DistributionLoadStartEvent`, `EndpointLoadedEvent` and `DistributionOfflineEvent` respectively).
* Removed `THEOplayerGlobal.playbackSettings`.

---

# Getting started with CMCD on Android

Media player clients can transmit useful information to Content Delivery Networks (CDNs) with each object request. This implementation supports Common Media Client Data (CMCD) as defined in [CTA-5004](https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf), published in September 2020.

## Usage

To enable CMCD, developers can add a CMCDTransmissionMode inside a SourceDescription.

```kotlin
val typedSource = TypedSource.Builder("<HLS_STREAM_URL>")
    .cmcdTransmissionMode(CMCDTransmissionMode.HTTP_HEADER)
    .build()

val sourceDescription = SourceDescription.Builder(typedSource)
    .build()

theoPlayerView.player.source = sourceDescription
```

The preferred mode of transmission for HTTP requests is to use custom headers, but you can configure the transmission mode when creating the CMCD source. For example, to transmit via query arguments:

```kotlin
val typedSource = TypedSource.Builder("<HLS_STREAM_URL>")
    .cmcdTransmissionMode(CMCDTransmissionMode.QUERY_ARGUMENT)
    .build()

val sourceDescription = SourceDescription.Builder(typedSource)
    .build()

theoPlayerView.player.source = sourceDescription
```

## Remarks

Note that CMCD is only supported with the [Media3 integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/android/media3/getting-started.md).

---

# Media3 pipeline for Android

The THEOplayer Android Media3 pipeline is a new and rebuilt base layer for playback of video and audio files for the THEOplayer Android SDK. It is based on [Jetpack Media3](https://developer.android.com/media/media3) components, and it provides more stable playback covering a broader range of use cases, all while being lighter in size and more performant.

## Usage

The Media3 pipeline is part of the THEOplayer Android SDK. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/getting-started.md) to set up THEOplayer in your Android app.

> **Info**
>
> In THEOplayer version 9.x, the Media3 and legacy pipelines were available side-by-side. Starting with version 10.0, the THEOplayer Android SDK has fully switched over to the Media3 pipeline, and the legacy pipeline has been retired.
>
> See [our migration guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/migrating-to-theoplayer-10.md) for more information.

## FAQ

### How does Media3 affect the THEOplayer Android SDK?

Media3 replaces the media playback layer of the THEOplayer Android SDK, offering improvements in performance and stability for playback over our current implementation. As only core media playback is affected, all player APIs remain identical and other features and integrations (such as ads, analytics or Chromecast) are not affected and will function the same.

### Does this use ExoPlayer?

While we make use of ExoPlayer components, this is not a plain ExoPlayer implementation. In addition to the integrations, features and support already offered by the THEOplayer Android SDK, we've reused what makes sense to implement our own playback pipeline that offers improvements, bugfixes and additional functionality over ExoPlayer.

---

# Getting started

To begin with the Dolby OptiView platform please review our guide for getting started with [OptiView Streaming](https://docs-preview.optiview.dolby.com/pr-932/theolive/getting-started.md).

### Installing the THEOplayer for Android

1. Support for OptiView Live comes out of the box with the THEOplayer for Android. Please follow [this guide for installing the Player SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/android/getting-started.md) for Android development.

2. Once the Player is installed, continue following the guide for setting up the player. Please note that THEOplayer licenses can be found for streaming customers [here](https://docs-preview.optiview.dolby.com/pr-932/theolive/getting-started.md) in the OptiView Live dashboard.

3. With the player installed and set up with a valid license, you can now import the `THEOliveSource` object from the SDK:

```kotlin
import com.theoplayer.android.api.theolive.TheoLiveSource
```

Rather than set your Player `source` as a manifest as you would for a HLS stream, you can now instead set it as a `TheoLiveSource` including your channel alias:

```kotlin
theoPlayer.source = SourceDescription
    .Builder(
        TheoLiveSource(
            src = "YOUR_THEOLIVE_CHANNEL_ALIAS"
        )
    )
    .build()
```

For testing, you can use this HESP demo source: `ar5c53uzm3si4h4zgkzrju44h` which the OptiView team [keeps live 24/7](https://demo.theo.live/?channel=ar5c53uzm3si4h4zgkzrju44h).

From here, your OptiView Live source should be ready to playback in THEOplayer.

### Adding Player Controls

At this stage in implementation, you should have an OptiView Live stream playing within your Android app. The Player SDK provides functionality for controlling stream playback which can be extended to users in the form of controls or buttons. The platform also supports an [Open Video UI for the Android SDK](https://docs-preview.optiview.dolby.com/pr-932/open-video-ui/android/getting-started), which provides a component library for advanced styling and control of UI components.

#### 1. Adding Play/Pause Controls

To add a play/pause button to your app, you’ll first need to create a button. This could be done via an XML layout file, for example:

```xml
<Button
    android:id="@+id/playPauseButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Play/Pause" />
```

Your app could then listen to interaction with the button and call either the `.play()` or `.pause()` functions from the Player SDK:

```kotlin
findViewById<Button>(R.id.playPauseButton).setOnClickListener {
    if (theoPlayer.isPaused) {
        theoPlayer.play()
        Log.i(TAG, "Playback started")
    } else {
        theoPlayer.pause()
        Log.i(TAG, "Playback paused")
    }
}
```

#### 2. Adding a Volume Slider

Like play/pause, a slider could also be added to control volume:

```xml
<SeekBar
    android:id="@+id/volumeSlider"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:max="100" />
```

The Player SDK tracks volume and allows you to adjust it as a percentage of the max volume:

```kotlin
findViewById<SeekBar>(R.id.volumeSlider).apply {
    max = 100
    progress = (theoPlayer.volume * 100).toInt()

    setOnSeekBarChangeListener(object : SeekBar.OnSeekBarChangeListener {
        override fun onProgressChanged(seekBar: SeekBar?, progress: Int, fromUser: Boolean) {
            val volumeLevel = progress / 100.0
            theoPlayer.volume = volumeLevel
            Log.i(TAG, "Volume set to ${Math.round(volumeLevel * 100)}%")
        }

        override fun onStartTrackingTouch(seekBar: SeekBar?) {}
        override fun onStopTrackingTouch(seekBar: SeekBar?) {}
    })
}
```

This will allow users to adjust the volume between 0% and 100%.

#### 3. Adding Fullscreen Support

To add a fullscreen button, add the following to your layout file:

```xml
<Button
    android:id="@+id/fullscreenButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Fullscreen" />
```

Then, set up the button in your `MainActivity`:

```kotlin
// Fullscreen Button
findViewById<Button>(R.id.fullscreenButton).setOnClickListener {
    theoPlayerView.fullScreenManager.requestFullScreen()
    Log.i(TAG, "Fullscreen enabled")
}
```

> **Tip**
>
> Looking for a UI component library to style the player experience? We recommend using our [Open Video UI for Android](https://docs-preview.optiview.dolby.com/pr-932/open-video-ui/android/getting-started) for faster development and control over UI components in the player.

### Adding Logging

To assist with debugging and understanding how your player is behaving, you can add event listeners for key player events. For example:

```kotlin
// Add basic playback event listeners
private fun configureTHEOplayer(theoPlayer: Player) {
    theoPlayer.addEventListener(PlayerEventTypes.PLAY) { Log.i(TAG, "Event: PLAY") }
    theoPlayer.addEventListener(PlayerEventTypes.PLAYING) { Log.i(TAG, "Event: PLAYING") }
    theoPlayer.addEventListener(PlayerEventTypes.PAUSE) { Log.i(TAG, "Event: PAUSE") }
    theoPlayer.addEventListener(PlayerEventTypes.ERROR) { event ->
        Log.e(TAG, "Event: ERROR, error=${event.errorObject}")
        Toast.makeText(this, "Stream Error: ${event.errorObject}", Toast.LENGTH_LONG).show()
    }
}
```

This will log important events like play, pause, and errors to the Android logcat, making it easier to identify issues during development. An exhaustive list of events can be found at our [API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/android/api/event/player/PlayerEventTypes).

## Troubleshooting

1. When building with the Android SDK please use `Android SDK Build-Tools 35 (build-tools;35.0.0)` or greater.
2. `Event: ERROR, error=com.theoplayer.android.api.error.THEOplayerException: The publication could not be found`. This error indicates the channel alias is invalid. An alias could be invalid because it doesn't exist, the channel is not started, or the channel is started but content isn't available for delivery.

## More information

* [Android Player SDK Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/android).

---

# Token based security

OptiView Live offers the option to enable JWT token security on a distribution (formerly referred to as an alias) level. This can be interesting if you only want valid users to access your stream. Read more about the feature and configuring it on your channels on the [token based security guide](https://docs-preview.optiview.dolby.com/pr-932/theolive/distribution/security/token-based-security.md).

This page will demonstrate how to configure the Android SDK for playback of channels with token based security enabled.

## Setting up the Android THEOplayer SDK for OptiView Live

Refer to the [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/android/theolive/getting-started.md) for the prerequisite steps in getting the web SDK up and running for OptiView Live playback.

## Configuring THEOplayer to pass the token

The token needs to be passed along with player requests as a Bearer token in the `Authorization` header of the requests. To do so we can make use of the Network API of the player, which works as follows:

```kotlin
val token = getToken() // Generate or request your token, for more information check the token based security guide linked above.
player.theoLive.authToken = token
```

This will ensure the player includes your authorization header on all subsequent requests it performs for playback of your OptiView Live distribution.

## Dealing with token expiry and rotation

If your tokens are short-lived, you want to make sure to update the token being passed to the player and requests before it expires, to allow playback to continue beyond expiry. This can simply be done by updating the header on the player in the same way. For example, one could check on an interval that makes sense for your token lifespan whether the token is about to expire and update when necessary, for example:

```kotlin
private var token: String? = null
private var tokenUpdateJob: Job? = null

// Helper function to check whether your token will expire within one minute from now
private fun tokenWillExpireSoon(): Boolean {
    val currentToken = token ?: return true

    return try {
        val parts = currentToken.split(".")
        if (parts.size < 2) return true

        val payload = String(Base64.decode(parts[1], Base64.DEFAULT))
        val jsonPayload = JSONObject(payload)
        val exp = jsonPayload.getLong("exp").seconds
        val now = System.currentTimeMillis().milliseconds

        exp - now <= 60.seconds
    } catch (e: Exception) {
        true // If parsing fails, assume token needs refresh
    }
}

private fun maybeUpdateToken() {
    if (token == null || tokenWillExpireSoon()) {
        token = getToken() // Generate or request your token
        token?.let { newToken ->
            player.theoLive.authToken = newToken
        }
    }
}

// Start the token management
private fun startTokenManagement(scope: CoroutineScope) {
    scope.launch {
        maybeUpdateToken() // Initial token update

        // Check every 30 seconds
        tokenUpdateJob = scope.launch {
            while (isActive) {
                delay(30.seconds)
                maybeUpdateToken()
            }
        }
    }
}

fun stopTokenManagement() {
    tokenUpdateJob?.cancel()
}
```

> **Info**
>
> For coroutine support with kotlin, ensure you have the `kotlinx-coroutines-android` dependency installed.
>
> ```groovy
> dependencies {
>     // ... Other dependencies
>     implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:$coroutineVersion'
> }
> ```
>
> `coroutineVersion` represents the library version as defined elsewhere in your project setup.

## Clearing the token

If the token isn't needed anymore, e.g. when switching to an unprotected distribution or a non-OptiView Live source altogether, the header can be simply removed as follows:

```kotlin
player.theoLive.authToken = null;
```

---

# Connectors for THEOplayer Android SDK

## [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/comscore)

[Integrate with Comscore for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/comscore)

## [![](/pr-932/img/conviva.svg)![](/pr-932/img/conviva_dark.svg)Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/conviva)

[Integrate with Conviva for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/conviva)

## [Nielsen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/nielsen)

[Integrate with Nielsen for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/nielsen)

## [📱Media Session](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/mediasession)

[Integrate with Android Media Session to delegate system-level playback controls to your app.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/mediasession)

## [![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAy0SURBVHgB7d1PbhRJFsfxiLIxs+iW2DbuaZVvwNzASGB6iU+AOQGuHd2YwSVhYId9AsMJYNmYkewb2DdwafjjWXoBEvUvYzKqSMqmjV1ZlZnxIuL7kVpqoZaM6M5f53svMp5SAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAORwt3q8fpn8pAKXQSij78Ju5S7tKmXr6m1z/0vm0tbC3eawAFEZkABwurl6Zm/tpN/3NXRv9qm4lpt/89e2TFwpAIcQFwNkP/ykH7U5veWHvWUsBmIqoABjj4f/GaP2i0+42CQJgcmICIM/DP6JbSidbV99sbCoAuYkIgMke/pPoDwCTcB4A0z/8I5QFQD5OA6DIh/+k4diw95IgAM7nLADKevhHKAuAizgJgPIf/pN0q93pXudtAPi7ygOg2od/hP4A8HeVBoCrh/+E4/Rnb/6y87ipAFQXAAIe/hPoDwBWJQEg6+EfoSxA7EoPAKkP/ylab7bb3S2CALEpNQC8ePi/oSxAfEoNgPc31zZrWt1TXhkEwXIaBAcKCFxNlUhrc0V5x9Rrurb/4dbDbW4jQuhKDQCfaWNWLs/NHh4trT1SQKAIgAsYpdY/Lj08fH/zzxUFBIYAGMugLNj+uLT2irIAISEA8rltywL6AwgFATCBYX/g0i5lAXxHAEwsKwseHr67sbaoAA8RAFMz9Zma2qUsgI8IgIIwNoSPCICCMTaETwiAUnwbG+5TFkAyAqBc1xgbQjICoALZ2PDjrQerChCEAKiMqSujn9v+wIelP24rQAACoHJ23fnMK8oCSEAAOHJybGgvTlGAAwSAY3ZseHnu533GhnCBABBhdKyYsgBVIgBEMXXGhqgSASBQNjbkWDHKRgCIZeocK0bZCADxhv0BygKUgQDwRDY2/Hjr4XOCAEUhAHxjzCq3EaEoBICXRmPDNAg82LoEqQgAr7HEBNMhAALwtT+wz9gQeREA4bjC2BB5EQDBYYkJxkcAhIslJrgQARA4lpjgPARAFFhigrMRAFFhiQlOIwAixBITZAiAiDE2BAEQPZaYxIwAQIYlJhEiAHAKY8O4EAA4w2hsyBKTsBEAOAdLTEJHAOBCLDEJFwGAsbHEJDwEAHJiiUlICABMiCUmISAAMBWWmPiNAEABWGLiKwIABWKJiW8IABTu9NiQIJCMAEBphmNDjhVLRgCgZIwNJSMAUBHGhhIRAKgUS0xkIQDgAktMhCAA4BBLTFwjACABS0wcIQAgBrcRVY8AgDCjsWEaBNcUSkUAQKhBEOxTFpSLAIBoLDEpFwEALzA2LAcBAI8M+wNHN9d2KQuKQQDAO0arRcaGxSAA4C3GhtMjAOA5lphMgwBAIFhiMgkCAEFhiUk+pQaASdSBAhxgicl4tCrZ0e/36yaZ2U1/VF0Bbhy0O73lhb1nLYVTSg+AjE3imtaPCAK4YrR+0Wl3mwTBSGUBYB0url+Zm+utpj+UY51wRLeUTrauvtnYVKg2ADK2LEiSmXWt9B0FOKFbiek3f3375IWKmJMAyLy7sbY4UzPblAVwJfaywGkAZOgPwLX0QVj/0um9jC0IRASAZcuCfn92tabVPQU4EV9ZICYAMvQH4J5utTvd6zG8DYgLgAxlAVyLoT8gNgAyBAEcO04fks1fdh43VYDEB4BFWQD3wuwPeBEAmeGx4tnn6d/y2Sdced3u9BqhlAVeBUCGsgDOab3Zbne3fA8CLwMg82FpLS0LzB2CAG74XxZ4HQAW/QG4NwiC5TQIvPv83fsAyHztD7xK/5ZtMnDCx7FhMAGQoT8A1+yxYl/GhsEFQGbYHxgcK+ZaKDjgR38g2ACw6A/ANW3U3pdu767UsiDoAMhwLRlck9ofiCIAMvQH4Ja8siCqALC4lgzu6ZZRvcb8ztPXyrHoAiBDfwCuSSgLog2ATFoWXEvLgleUBXDF5dgw+gDI0B+AW276AwTACcOyYHaF/gAcqnSJCQFwBvoDcK2q/gDLQc/wy1/PWvM7Gyumr5bTfxUtBVRssOT08kzp917wBjAG+gOolFF77Zne3YW/yi8DCIAxURagfKbVT/Tdf/7n8Z6qCAGQE0GAEhwbpbY6nU+bC3ubx6pCBMCEKAtQBKNN2uz73Kj6wc8QAFN6f+PBaq1mPzvWdQWMK63z+0Y1q3zdPwsBUADKAuRwnLb4m1LWkxMABRp8dtyf3U7/VBcV8J20zm+6qPPPQwCUgP4ATqlwrJcXAVAiriWLXfVjvbwIgJLRH4jSYKw3v/N4XQkXVAC8u7G2OKvVo6SmW9KuX+La8ji4HuvlFUQAHC3er6vLlx4ZY1ZO/rrE65npDwRKyFgvL68D4HBx9co/5n66l75uraof1tkyr2f+2h/gs2P/HScmafi6HszbAPjv0h+3Z5XdFGzq4/zzEq9npj/gN4ljvby8C4CszjcTztolXs/MtWSeETzWy8ubALCv+5fnfk5fmc2qmppuKZ1sSTmNlaE/IJ38sV5eXgTA0dLao/Pr/EnJ6w9wbblI3oz18hIdAPZ1f6amt8et8yclsSygPyBDYtRWt/tp3ec6/zwiA2Aw1rs0u22qPlOv9Wa73d2SFATDEDTblAUV83Ssl5eoACi2zp+UzLEh/YHKeD3Wy0tMAPzv5r/vJTpZV2LOzeu04WNENXxsWdDvz67W9OD7AhTL2a08LjkPAPuKW6up51roEVn6AxEIaKyXl7MAcFbnT8geK/7S+bQl6f8OlAXTCm+sl1flATDe8V2p6A8EItixXl6VBsDwP9Tac+X99/G61e50r1MW+Cf0sV5elQTAtMd3pZLaHzCJ/UZClb5VxiuRjPXyKjUAfvSZbmCO0z/ETT47lsqkZZsRV7ZJUWoAfFh68CKeV1Kh/YF4ry2PcqyXFwFQvNftTq9Bf8ChiMd6eREAJRHbHwj62nLGenmxHrwkg/XOc5d2bS2uhLBrz6++fXw9McndwNae22Ubjas7Gws8/PnwBlAJ3TKq15jfefpaCRLCteWM9aZDAFSIY8UFYqxXCALAgeGx4t5LeecHZnblTwtMq6eSxm/C3qZ8RQ/AgXQ8tS6yP5DW0IL7A3as12x3Pv+Lh784vAE4Nzg/sPzr2ycHShBR15Yz1isNbwDOmXpN1/Y/3Hq4fWhPTgphP5TRtd6CUealciT92Qf9RF23kwse/nLwBiCM0G1GVV9bbsd6TWm3NoeINwBhbH/g49LDQ0n9AVueVNUfsGO9dufTAg9/NXgDkO2g3ektyxsbzq4U3h9grOcEAeCBsM8PMNZziRLAA9mx4o+3Hji8Lfk0Ozac39lYMX21PGFZwFhPAN4AvBPEtWSv27Veg86+ewSAp6SWBeddW27HekmiG9T5chAAvhO4zeiM/gBjPaEIgCDILQu0rtW5lUcuAiAo8rYZQTamAEEx9Zma2pV2rBhyEQABGo4NZw+PltYe2UUsCvgBAiBgw8+Of96XdKwYshAAwRt8bbhtvy+gLMD3CIBomLotC+gP4CQCIDJf+wP7tj+gED0CIE5XJH52jOoRAFEb9geObq7tUhbEiQCAslub6Q/EiQDAN9lnx4e/EwKxIAAwYtSevaGYz3TjMasAlmpGiwCIm72VZ6vT+czXepEiAOLFrTwgAKLD7bs4gQCIx/BWnh1u5cEIARABu2yj2/20Tp2P7xEAIWOpJi5AAASJsR7GQwCEhbEeciEAAmG0edFpf27w4CMPAsB338Z6G3sKyIkA8NdxYpKGtF0A8AsB4CG7VJNlGygCAeATxnooGAHgBcZ6KAcBINtgrDe/s7GugBIQAEJxfBdVIACk4Ws9VIgAkIOxHipHALj39fguYz1UjwBwibEeHCMAnGCsBxkIgGoNb+V5w608kIEAqAhjPUhEAJSNsR4EIwBKY1o9lTR+e/v0tQKEIgCKx6088AYBUCyWbcArBEABjDIHSaIb1PnwDQEwncFYb56xHjxFAEyIsR5CQADklY71EjX4aOdAAZ4jAMbG8V2EhwC4GGM9BIsAOMdg2YbuNxnrIVQEwFlYtoFIlBoAxpg9rfUd5Y/h13o7jPUQB61K9v7mnys1XdtWwrFsAzEqPQAs0SHArTyIWCUBYMkLAcZ6QGUBYAkJAS7hBL6qNAAslyEwGOu1Pzd48IGhygPAqjwEuJUHOJOTALAqCgGWbQDncBYAVpkhwFgPuJjTALAKDwHGesDYnAeAVUwIMNYD8hIRANYUITAY683vPF5XAHIREwBW3hDgVh5gOqICwBorBBjrAYUQFwDWj0PAtBJjmoz1gGKIDADruxDg+C5QArEBYA1CQNXuMNYDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABALP4PxPhKst9YjwYAAAAASUVORK5CYII=)Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/yospace)

[Integrate with Yospace for server-side ad insertion (SSAI).](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/yospace)

## [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/uplynk)

[Add support for Uplynk CMS to your player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/uplynk)

---

# THEOplayer Android Comscore Connector

A Comscore analytics connector for use with THEOplayer in Android applications.

## Usage

### Configuring the Connector

Create the connector by providing the `THEOplayer` instance, a `ComscoreConfiguration` (which contains your publisher id), and the `ComscoreMetadata` of the first source you will set to the player (you can change it dynamically throughout the entire lifecycle of the connector):

```kotlin
val comscoreConfiguration = ComscoreConfiguration(
    publisherId = "<your publisher ID here>", // Can be a test or production key.
    applicationName = "THEOplayer Demo",
    userConsent = "1",
    childDirected = false,
    secureTransmission = true,
    usagePropertiesAutoUpdateMode = 1,
    debug = true
)
val metadata = ComscoreMetaData(
    mediaType = ComscoreMediaType.LONG_FORM_ON_DEMAND,
    uniqueId = "testuniqueId",
    length = 634,
    stationTitle = "THEOTV",
    programTitle = "Big Buck Bunny",
    episodeTitle = "Intro",
    genreName = "Animation",
    classifyAsAudioStream = false,
    c3 = "c3value",
    c4 = "c4value",
    c6 = "c6value",
    stationCode = null,
    networkAffiliate = null,
    publisherName = null,
    programId = null,
    episodeId = null,
    episodeSeasonNumber = null,
    episodeNumber = null,
    genreId = null,
    carryTvAdvertisementLoad = null,
    classifyAsCompleteEpisode = null,
    dateOfProduction = null,
    timeOfProduction = null,
    dateOfTvAiring = null,
    timeOfTvAiring = null,
    dateOfDigitalAiring = null,
    timeOfDigitalAiring = null,
    feedType = null,
    deliveryMode = null,
    deliverySubscriptionType = null,
    deliveryComposition = null,
    deliveryAdvertisementCapability = null,
    mediaFormat = null,
    distributionModel = null,
    playlistTitle = null,
    totalSegments = null,
    clipUrl = null,
    videoDimension = null,
    customLabels = emptyMap(),
)

val comscore = ComscoreConnector(this, theoplayerView.player, comscoreConfiguration, metadata)

val playerConfig = THEOplayerConfig.Builder()
    .analytics(comscore)
    .build()

val theoplayerView = THEOplayerView(this)
theoplayerView.config = playerConfig

val theoplayer = theoplayerView.theoplayer
theoplayer.source = SourceDescription.Builder()
    .sources("YOUR_SOURCE_URL_HERE")
    .build()

theoplayerView.onCreatePlayer { player ->
    // Initialize Comscore connector
    comscore.init(player)
}
```

### Passing Metadata Dynamically

The connector allows passing or updating the current asset's metadata at any time:

```kotlin
comscoreConnector.update(ComscoreMetaData())
```

### ComscoreMetadata Fields

Based on the `ComscoreMetaData` type, you can tell which fields are mandatory and which aren't. Note that this is purely for the integration to work correctly. Depending on the Comscore solution you are using, different fields are required/optional. The mandatory fields in the `ComscoreMetadata` type are the ones that are mandatory for all three Comscore solutions:

* Video Metrix (V)
* Cross Platform Product Suite (X)
* Cross Media Audience Measurement (C)

| Property                          | Required | Optional |
| --------------------------------- | -------- | -------- |
| `mediaType`                       | All      |          |
| `uniqueId`                        | All      |          |
| `length`                          | All      |          |
| `c3`                              | V        |          |
| `c4`                              | V        |          |
| `c6`                              | V        |          |
| `stationTitle`                    | All      |          |
| `stationCode`                     |          | All      |
| `networkAffiliate`                |          | All      |
| `publisherName`                   | X C      | V        |
| `programTitle`                    | All      |          |
| `programId`                       |          | V C      |
| `episodeTitle`                    | All      |          |
| `episodeId`                       |          | X C      |
| `episodeSeasonNumber`             | X C      |          |
| `episodeNumber`                   | X C      |          |
| `genreName`                       | All      |          |
| `genreId`                         |          | All      |
| `carryTvAdvertisementLoad`        | X        |          |
| `classifyAsCompleteEpisode`       | X        |          |
| `dateOfProduction`                |          | C        |
| `timeOfProduction`                |          | C        |
| `dateOfTvAiring`                  | X C      |          |
| `timeOfTvAiring`                  |          | X C      |
| `dateOfDigitalAiring`             | X C      |          |
| `timeOfDigitalAiring`             |          | X C      |
| `feedType`                        | X        |          |
| `classifyAsAudioStream`           | All      |          |
| `deliveryMode`                    |          | All      |
| `deliverySubscriptionType`        |          | All      |
| `deliveryComposition`             |          | All      |
| `deliveryAdvertisementCapability` |          | All      |
| `mediaFormat`                     |          | All      |
| `distributionModel`               |          | All      |
| `playlistTitle`                   |          | C        |
| `totalSegments`                   |          | V C      |
| `clipUrl`                         |          | V C      |
| `videoDimension`                  |          | C        |
| `customLabels`                    |          | All      |

---

# THEOplayer Android SDK Conviva Connector

The Conviva connector provides a Conviva integration for THEOplayer Android SDK.

## Prerequisites

The THEOplayer Android SDK Conviva Connector requires the application to import the THEOplayer Android SDK since the connector relies on its public APIs. For more details, check out our [Getting started on Android](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/android/getting-started/) guide.

For setting up a valid Conviva session, you must have access to a [Conviva developer account](https://pulse.conviva.com/) with access to a debug or production key.

## Installation

After setting up the THEOplayer Android SDK, in your **module** level `build.gradle` file add the THEOplayer Android SDK Conviva Connector and the Conviva SDK:

```text
implementation 'com.theoplayer.android-connector:conviva:+'
implementation 'com.conviva.sdk:conviva-core-sdk:4.0.33'
```

## Usage

### Setting up the Conviva Connector

```kotlin
val theoplayerView: THEOplayerView

private fun setupConviva() {
    val customerKey = "your_conviva_customer_key"
    val gatewayUrl = "your_conviva_debug_gateway_url"
    
    val metadata = hashMapOf(
        "Conviva.applicationName" to "THEOplayer",
        "Conviva.viewerId" to "viewerId"
    )
    val config = ConvivaConfiguration(
        customerKey,
        true, // debug
        gatewayUrl,
    )
    convivaConnector = ConvivaConnector(applicationContext, theoplayerView.player, metadata, config)
}
```

### Setting asset metadata

Most media related properties, such as its streamURL, duration or whether it is a live or vod stream, are determined and passed by the connector itself when setting a new source.

Whenever a new source is set on the player, the metadata `title` property is used to pass an asset name.

```kotlin
theoplayerView.player.source = 
    SourceDescription.Builder(
        TypedSource.Builder("https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8").build()
    )
    .metadata(MetadataDescription(mapOf("title" to "Big Buck Bunny")))
    .build()
```

Alternatively, the asset name can be passed to the connector at any time during playback along with additional metadata through an open key-value map. An important note is that the `setContentInfo` call needs to happen after the `sourcechange` event is dispatched, for example:

```kotlin
theoplayerView.player.source = sourceDescription

theoplayerView.player.addEventListener(PlayerEventTypes.SOURCECHANGE) {
    convivaConnector.setContentInfo(hashMapOf(
        "Conviva.assetName" to "Big Buck Bunny",
        "customTag1" to "customValue1",
        "customTag2" to "customValue2"
    ))
}
```

### Starting a new session on program boundaries

By default, new sessions are only started on play-out of a new source, or when an ad break starts. During a live stream it is possible to manually mark the start of a new session, for example when a new program starts.

```kotlin
convivaConnector?.stopAndStartNewSession(hashMapOf(
    "Conviva.assetName" to "New program",
    "customTag1" to "customValue1",
    "customTag2" to "customValue2"
))
```

### Destroying / Cleaning up

To release listeners and resources, call destroy whenever the Conviva Connector is no longer needed.

```kotlin
convivaConnector?.destroy()
```

Note:

* After destroying a Conviva Connector instance, it can no longer be used. If needed, a new instance should be created.

---

# THEOplayer Android SDK Nielsen Connector

The Nielsen connector provides a Nielsen integration for THEOplayer Android SDK.

## Prerequisites

The THEOplayer Android SDK Nielsen Connector requires the application to import the THEOplayer Android SDK since the connector relies on its public APIs. For more details, check out our [Getting started on Android](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/android/getting-started/) guide.

## Installation

After setting up the THEOplayer Android SDK, in your **module** level `build.gradle` file add the THEOplayer Android SDK Nielsen Connector and the Nielsen SDK dependencies:

```groovy
implementation 'com.theoplayer.android-connector:nielsen:+'
implementation 'com.nielsenappsdk.global:ad:9.1.0.0'
```

Also in the `build.gradle` file, specify the Nielsen maven repository inside the repositories section:

```groovy
repositories {
    maven { url 'https://maven.theoplayer.com/releases/' }
    maven { url 'https://raw.githubusercontent.com/NielsenDigitalSDK/nielsenappsdk-android/master/'}
}
```

## Usage

### Setting up the Nielsen Connector

```kotlin
val theoplayerView: THEOplayerView

private fun setupNielsen() {
    val appId = "your_nielsen_app_id"
    val debug = true
    nielsenConnector = NielsenConnector(applicationContext, theoplayerView.player, appId, debug)
}
```

### Updating metadata

Whenever a new source is set on the player, update the current metadata as follows:

```kotlin
theoplayerView.player.source = sourceDescription
nielsenConnector?.updateMetadata(hashMapOf(
    "assetid" to "C112233",
    "program" to "programName"
))
```

### Destroying / Cleaning up

To release listeners and resources, call destroy whenever the Nielsen Connector is no longer needed.

```kotlin
nielsenConnector?.destroy()
```

Note:

* After destroying a Nielsen Connector instance, it can no longer be used. If needed, a new instance should be created.

---

# THEOplayer Media Session Connector

The media session connector provides a universal way for Android to interact with THEOplayer. Integrating with the connector allows an app to advertise media playback and to receive playback commands from external sources, such as from a TV remote or through Google Assistant commands using voice commands such as *'What is currently playing?'*.

## Android Media Session

As described on the Android documentation pages [Using a Media Session](https://developer.android.com/guide/topics/media-apps/working-with-a-media-session):

> Media sessions provide a universal way of interacting with an audio or video player. By informing Android that media is playing in an app, playback controls can be delegated to the app. Integrating with the media session allows an app to advertise media playback externally and to receive playback commands from external sources. These sources can be physical buttons (such as the play button on a headset or TV remote control) or indirect commands (such as instructing "pause" to Google Assistant). The media session then delegates these commands to the app that applies them to the media player for which it is transparent where the commands originated.

## Getting Started

This section details how to integrate the connector in a video app, as demonstrated on Android's [Building a video app](https://developer.android.com/guide/topics/media-apps/video-app/building-a-video-app). The app will advertise its player state and media metadata to the media session through the connector, and responds to requests from the media session.

In this example the media session is active as long as the app's activity is active and running in the foreground. The full example code is available in our [Sample repository](https://github.com/THEOplayer/samples-android-sdk).

For a demonstration on how to build a more extensive app that does background audio playback, we refer to the Android documentation on [Building an audio app](https://developer.android.com/guide/topics/media-apps/audio-app/building-an-audio-app), as well as our [Sample repository](https://github.com/THEOplayer/samples-android-sdk).

### Creating the media session connector

After [Creating and initializing a media session](https://developer.android.com/guide/topics/media-apps/working-with-a-media-session#init-session), pass the `mediaSession` and THEOplayer instances to the connector.

Optionally set the `debug` flag to receive log statements from the connector.

```text
private lateinit var mediaSession: MediaSessionCompat
private lateinit var mediaSessionConnector: MediaSessionConnector

public override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Create and initialize the media session
    mediaSession = MediaSessionCompat(this, TAG).apply {
        // Do not let MediaButtons restart the player when the app is not visible
        setMediaButtonReceiver(null)
    }

    // Create a MediaSessionConnector and attach the THEOplayer instance.
    mediaSessionConnector = MediaSessionConnector(mediaSession)
    mediaSessionConnector.debug = true
    
    // Pass the player instance
    mediaSessionConnector.player = viewBinding.theoPlayerView.player
    
    // Set mediaSession to active
    mediaSessionConnector.setActive(true)
}
```

### Passing media metadata

The connector advertises the currently playing asset to the media session. The `MetadataDescription` object that is passed to THEOplayer's source description provides additional information on the asset, such as title, author and an icon.

If your app uses a [MediaController](https://developer.android.com/reference/kotlin/android/support/v4/media/session/MediaControllerCompat) to interact with the media session, the [onMetadataChanged](https://developer.android.com/reference/kotlin/android/support/v4/media/session/MediaControllerCompat.Callback#onMetadataChanged\(android.support.v4.media.MediaMetadataCompat\)) callback can be used to display the metadata on screen.

A full list of supported metadata properties is available in [MediaMetadataProvider](https://github.com/THEOplayer/android-connector/blob/-/connectors/mediasession/src/main/java/com/theoplayer/android/connector/mediasession/MediaMetadataProvider.kt)

```text
val metadataFields = hashMapOf<String, Any>(
    "title" to "Elephants Dream",
    "displaySubtitle" to "by the Orange Open Movie Project",
    "mediaId" to "stream01",
    "mediaUri" to "https://theoplayer.com",
    "album" to "THEOplayer test streams",
    "author" to "THEOplayer"
)
player.source = SourceDescription.Builder(
    TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlistCorrectionENG.m3u8")
        .type(SourceType.HLSX)
        .build()
    )
    .metadata(MetadataDescription(metadataFields))
    .build()
```

![](/pr-932/assets/images/sample-c23a4a59c15abdd122d9b4cd6ecdd966.png)

### Lifecyle callbacks

The THEOplayer instance needs to know about the Activity's lifecycle methods. In accordance, the connector will need to update its state as well.

```text
override fun onPause() {
    viewBinding.theoPlayerView.onPause()
    mediaSessionConnector.setActive(false)
    super.onPause()
}

override fun onResume() {
    viewBinding.theoPlayerView.onResume()
    mediaSessionConnector.setActive(true)
    super.onResume()
}

override fun onDestroy() {
    mediaSessionConnector.destroy()
    viewBinding.theoPlayerView.onDestroy()
    super.onDestroy()
}
```

### Connector interfaces

Besides basic playback requests, the media session can also send requests related to queued media items, setting ratings and custom actions. These are forwarded to optionally implemented interfaces of the connector:

* `QueueNavigator` allows handling queue navigation actions.
* `QueueEditor` allows handling queue editing actions.
* `PlaybackPreparer` allows handling media prepare actions.
* `RatingCallback` allows handling rating actions.
* `CustomActionProvider` allows handling custom actions.

We refer to our [Sample repository](https://github.com/THEOplayer/samples-android-sdk) for an example on how these could be implemented.

### Dispatching media commands

Using `adb` (Android Debug Bridge), media commands can be triggered command-line as well:

```text
$ adb shell media dispatch KEY
```

with `KEY` being any command `play, pause, play-pause, mute, headsethook, stop, next, previous, rewind, record, fast-forward.`

### Media player state

The player's current state can be queried using `adb`:

```text
$ adb shell dumpsys media_session

MEDIA SESSION SERVICE (dumpsys media_session)

5 sessions listeners.
Global priority session is null
User Records:
Record for full_user=0
  Volume key long-press listener: null
  Volume key long-press listener package: 
  Media key listener: null
  Media key listener package: 
  Callback: android.media.session.ICallback$Stub$Proxy@ff4b775
  Last MediaButtonReceiver: null
  Restored MediaButtonReceiver: null
  Restored MediaButtonReceiverComponentType: 0
  Media button session is com.theoplayer.android.mediasession.demo/PlayerActivity (userId=0)
  Sessions Stack - have 2 sessions:
    PlayerActivity com.theoplayer.android.mediasession.demo/PlayerActivity (userId=0)
      ownerPid=7705, ownerUid=10060, userId=0
      package=com.theoplayer.android.mediasession.demo
      launchIntent=null
      mediaButtonReceiver=null
      active=true
      flags=3
      rating type=0
      controllers: 15
      state=PlaybackState {state=3, position=45840, buffered position=66664, speed=1.0, updated=333568, actions=4199295, custom actions=[], active item id=1, error=null}
      audioAttrs=AudioAttributes: usage=USAGE_MEDIA content=CONTENT_TYPE_UNKNOWN flags=0x800 tags= bundle=null
      volumeType=1, controlType=2, max=0, current=0
      metadata: size=5, description=Elephants Dream, null, Elephants Dream
      queueTitle=null, size=0
```

## Resources

* [Using a media session](https://developer.android.com/guide/topics/media-apps/working-with-a-media-session)
* [Building an audio app](https://developer.android.com/guide/topics/media-apps/audio-app/building-an-audio-app)
* [Building a video app](https://developer.android.com/guide/topics/media-apps/video-app/building-a-video-app)

---

# THEOplayer Yospace Connector for Android

The Yospace connector provides a Yospace integration for THEOplayer.

## Installation

1. Add the THEOplayer Maven repository to your project-level `settings.gradle` file:
   ```groovy
   dependencyResolutionManagement {
       repositories {
           google()
           mavenCentral()
           maven { url = uri("https://maven.theoplayer.com/releases/") }
       }
   }
   ```
2. Add the Yospace Maven repository to that same `settings.gradle` file. Please refer to the [Yospace Ad Management SDK documentation](https://developer.yospace.com/sdk-documentation/android/userguide/latest/en/index-en.html) (section 7.2. Downloads > Ad Management SDK) for instructions.
3. Add THEOplayer, the Yospace Ad Management SDK and the Yospace Connector as dependencies in your module-level `build.gradle` file:
   ```groovy
   dependencies {
       implementation "com.theoplayer.theoplayer-sdk-android:core:7.+"
       implementation "com.yospace:admanagement-sdk:3.+"
       implementation "com.theoplayer.android-connector:yospace:7.+"
   }
   ```

## Usage

First, follow [the getting started guide for the THEOplayer Android SDK](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/android/getting-started/) to set up a `THEOplayerView` in your app.

Then, create the `YospaceConnector`:

```kotlin
import com.theoplayer.android.api.THEOplayerView
import com.theoplayer.android.connector.yospace.YospaceConnector

val theoPlayerView = findViewById(R.id.theoplayer)
val yospaceConnector = YospaceConnector(theoPlayerView)
```

Finally, set the THEOplayer source to a `SourceDescription` with a `YospaceSsaiDescription` as its `ssai` description:

```kotlin
theoplayerView.player.source = SourceDescription.Builder(
   TypedSource.Builder("https://example.com/stream.m3u8")
      .ssai(
         YospaceSsaiDescription(streamType = YospaceStreamType.LIVE)
      )
      .build()
).build()
```

---

# THEOplayer Uplynk Connector for Android

The Uplynk connector provides a Uplynk integration for THEOplayer.

## Installation

1. Add the THEOplayer Maven repository to your project-level `settings.gradle` file:
   ```groovy
   dependencyResolutionManagement {
       repositories {
           google()
           mavenCentral()
           maven { url = uri("https://maven.theoplayer.com/releases/") }
       }
   }
   ```
2. Add THEOplayer and the Uplynk Connector as dependencies in your module-level `build.gradle` file:
   ```groovy
   dependencies {
       implementation "com.theoplayer.theoplayer-sdk-android:core:8.+"
       implementation "com.theoplayer.android-connector:uplynk:8.+"
   }
   ```

## Usage

First, follow [the getting started guide for the THEOplayer Android SDK](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/android/getting-started/) to set up a `THEOplayerView` in your app.

Then, create the `UplynkConnector`:

```kotlin
import com.theoplayer.android.api.THEOplayerView
import com.theoplayer.android.connector.uplynk.UplynkConnector
...
val theoPlayerView = findViewById(R.id.theoplayer)
val uplynkConnector = UplynkConnector(theoPlayerView)
```

Finally, set the THEOplayer source to a `SourceDescription` with a `UplynkSsaiDescription` as its `ssai` description:

```kotlin
theoplayerView.player.source = SourceDescription
    .Builder(
        TypedSource.Builder("no source")
            .ssai(
                UplynkSsaiDescription
                    .Builder()
                    .prefix("https://content.uplynk.com")
                    .assetIds(listOf(
                        "41afc04d34ad4cbd855db52402ef210e",
                        "c6b61470c27d44c4842346980ec2c7bd",
                        "588f9d967643409580aa5dbe136697a1",
                        "b1927a5d5bd9404c85fde75c307c63ad",
                        "7e9932d922e2459bac1599938f12b272",
                        "a4c40e2a8d5b46338b09d7f863049675",
                        "bcf7d78c4ff94c969b2668a6edc64278",
                    ))
                    .preplayParameters(linkedMapOf(
                        "ad" to "adtest",
                        "ad.lib" to "15_sec_spots"
                    ))
                    .build())
            .build()
    )
    .build()
```

### Getting Ad Information

To retrieve information about the currently playing ad or ad break, you can use the following properties of THEOplayer:

* `player.ads.currentAds`: Provides a list of currently playing ads.
* `player.ads.currentAdBreak`: Provides information about the currently active ad break.

These fields contain generic data for any ad or ad break in THEOplayer. However, for Uplynk-specific ad data, you can access the `customData` property. Below are examples demonstrating how to do that:

```kotlin
fun logCurrentAd() {
    val uplynkAd =
        theoplayerView.player.ads.currentAds.firstOrNull()?.customData as? UplynkAd ?: return
    Log.d(
        TAG, "UplynkAd: " +
                "apiFramework = ${uplynkAd.apiFramework}, " +
                "events = ${uplynkAd.events}, " +
                "duration = ${uplynkAd.duration}, " +
                "height = ${uplynkAd.height}, " +
                "width = ${uplynkAd.width}, " +
                "fwParameters = ${uplynkAd.fwParameters}, " +
                "mimeType = ${uplynkAd.mimeType}"
    )
}

fun logCurrentAdBreak() {
    val uplynkAdBreak =
        theoplayerView.player.ads.currentAdBreak?.customData as? UplynkAdBreak ?: return
    Log.d(
        TAG, "UplynkAdBreak: " +
                "type = ${uplynkAdBreak.type}, " +
                "ads = ${uplynkAdBreak.ads.size}, " +
                "duration = ${uplynkAdBreak.duration}, " +
                "timeOffset = ${uplynkAdBreak.timeOffset}, " +
                "position = ${uplynkAdBreak.position}"
    )
}
```

---

# Introduction

THEOplayer and Uplynk are partners in the streaming industry. The [Uplynk Platform](https://www.uplynk.com/) offers services like encoding, transcoding, server-side ad-insertion, a CDN and more.

> Uplynk was previously known as EdgeIO or Verizon Media. The iOS and Android connector will refer to the new name which is Uplynk.

Uplynk offers services which can enhance the API, UI and UX of video players and applications. The most popular services are called Preplay, Ping and Asset Info. THEOplayer integrates these services so that developers and viewers can benefit from them.

For example,

* Viewers can skip over ads;
* Viewers can see when an ad is playing (and stopping);
* Developers can define the behavior when viewers try to seek over an ad;
* Developers can query metadata to render a playlist in their application.

A live demo of THEOplayer's integration of Uplynk on the Web is available [here](https://cdn.theoplayer.com/demos/verizon-media/index.html).

Once the connector is added to your project, you can import it like so:

```kotlin
import com.theoplayer.android.connector.uplynk.UplynkConnector
```

To instantiate the connector, we first need to create a configuration for it, to describe how the connector should be behave when it comes to Ads:

```kotlin
val uplynkConfiguration = UplynkConfiguration(defaultSkipOffset: ..., onSeekOverAd: ...)
```

> `defaultSkipOffset` describes how many seconds the user has to wait before an ad is skippable. `onSeekOverAd` controls how the connector behaves when seeking over ads. There are three values: `PLAY_ALL`, `PLAY_LAST` and `PLAY_NONE`. The first option forces playback of all the unwatched ads before the seek point. `PLAY_LAST` forces playback of the last ad before the seek point.

We can now instantiate the `UplynkConnector` provided that you have an available `THEOplayer` instance:

```kotlin
val uplynkConnector = UplynkConnector(theoplayerView = yourTHEOplayer, uplynkConfiguration = uplynkConfiguration)
```

For more information on the connector and available APIs, continue to read on the pages below.

* [Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/uplynk/preplay.md): this article provides information on how to configure a Uplynk source.
* [Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/uplynk/ads.md): this article provides information on which APIs can be leveraged to track and enhance the ad-viewing experience.
* [Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/uplynk/ping.md): this article provides information on how to leverage the Ping service and which THEOplayer APIs you should use.

---

# Preplay

This article explains how to leverage the Uplynk Preplay API through THEOplayer. This API allows developers to pre-integrate with Uplynk Preplay service.

Uplynk users can use an API (i.e. Preplay) to generate a streaming playlist given 1 or more assets or advertisements. The back-end of Uplynk stitches the content together and allows for server-side ad-insertion (SSAI) when applicable. This document describes how THEOplayer users should configure their source to leverage this Preplay service.

Assumptions:

* THEOplayer assumes the availability of the Preplay API and Uplynk content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
* THEOplayer assumes that developers who are interested in this feature have a basic understanding of the Preplay API. Uplynk documents this service at <https://api-docs.uplynk.com/#Develop/Preplayv2.htm>
* THEOplayer assumes that developers provide correct asset identifiers, as well as the proper content protection level.

## Stream Configuration (without ads)

The examples below demonstrate how to configure a stream through the Uplynk connector.

We start by creating an `UplynkSsaiDescription` object that describes how to configure an Uplynk source.

```kotlin
    val ssaiDescription = UplynkSsaiDescription
        .Builder()
        .prefix("https://content.uplynk.com")
        .assetType(UplynkAssetType.ASSET)
        .assetIds( your list of asset IDs )
        .preplayParameters( your linkedMapOf preplay parameters)
        .contentProtected(false)
        .build()
```

* `assetIds`: This field identifies the asset. Developers can also specify an array of one or more asset IDs as strings, which will be stitched into a continuous stream. Assets can also be identified by `externalIds` and a `userId` in the builder. `userId` **must** always be provided with `externalIds` else `IllegalArgumentException` will be thrown.

* `preplayParameters`: The `preplayParameters` object should have string-key-string-value combinations, which will be used as query parameters for the Preplay API call. Nested objects are not supported.

* `contentProtected`: Boolean value which will internally set any necessary content-protection information. No content-protection details have to be specified by the customer.

* **A Preplay request must include all parameters defined within the playback request, hence these parameters must be included in the THEOplayer source**. This request must also include a digital signature if the 'Require a token for playback' option is enabled in the back-end on the corresponding live channel. (See also : [Signing a Playback URL Tutorial](https://docs.uplynk.com/docs/sign-playback-url))

* Uplynk specific documentation on the available playback URL query parameters can be found on the Uplynk documentation site under [Customizing Playback via Parameters](https://docs.uplynk.com/docs/customize-playback-via-parameters)

* Some parameters can be excluded from the digital signature calculation. These parameters may enable certain use cases (e.g. DVR) and would for this reason be excluded from the digital signature.

Now, you can create a typed source, and attach the `UplynkSsaiDescription` object to the `ssai` property of the source

```kotlin
    val typedSource = TypedSource.Builder("no source")
        .ssai(ssai)
        .build()
    
    val sourceDescription = SourceDescription.Builder(typedSource)
    yourTHEOplayer.source = sourceDescription
```

## Stream Configuration (with ads)

Ad specific parameters can be passed in the `preplayParameters` argument of the `UplynkSsaiDescription`. An example of that is:

```kotlin
    val ssaiDescription = UplynkSsaiDescription
        .Builder()
        .prefix("https://content.uplynk.com")
        .assetType(UplynkAssetType.ASSET)
        .assetIds(...)
        .preplayParameters(
            linkedMapOf(
                "ad" to "adtest",
                "ad.lib" to "15_sec_spots"
            )
        )
        .contentProtected(false)
        .build()
```

## Preplay Response

THEOplayer automatically interprets the response returned by the Preplay service. However, if a developer wants to perform their own logic with the Preplay API response, then they can register their implementation of the `UplynkListener` interface through the `UplynkConnector` `addListener`. There, you can get access to the `PreplayLiveResponse` or `PreplayVodResponse` objects through:

```kotlin
    uplynkConnector.addListener(object : UplynkListener {
        .....
    
        override fun onPreplayLiveResponse(response: PreplayLiveResponse) {
            Log.d("UplynkConnectorEvents", "PREPLAY_LIVE_RESPONSE $response")
        }
    
        override fun onPreplayVodResponse(response: PreplayVodResponse) {
            Log.d("UplynkConnectorEvents", "PREPLAY_VOD_RESPONSE $response")
        }
    }
```

## Using Tokens

Uplynk users often leverage URL signatures (i.e. tokens) to further secure their content -- on top of AES-128 encryption or studio DRM.

A token is (typically) generated on back-end using an API key and a set of parameters. (The documentation at [Signing a Playback URL Tutorial](https://docs.uplynk.com/docs/sign-playback-url) describes this process.) This set of parameters should also be passed along to the `playbackUrlParameters` in a `UplynkSsaiDescription`.

If you do not configure the `playbackUrlParameters` correctly in relation to your signature parameters, then the Preplay request made by THEOplayer will most likely return an invalid Preplay response, preventing THEOplayer from setting up your stream.

# Related articles

* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/uplynk/ads.md)
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/uplynk/ping.md)

---

# Uplynk Ads

Uplynk offers support for server-side ad-insertion or in-short SSAI.

This article explains how to use the THEOplayer's Ads APIs to interact with the Uplynk Ads service

## Global Configuration

The examples below demonstrate how to pass along global configuration for Uplynk Ads in the Connector.

```kotlin
val uplynkConfiguration = UplynkConfiguration(defaultSkipOffset: ..., onSeekOverAd: ...)
```

> `defaultSkipOffset` describes how many seconds the user has to wait before an ad is skippable. `onSeekOverAd` controls how the connector behaves when seeking over ads. There are three values: `PLAY_ALL`, `PLAY_LAST` and `PLAY_NONE`. The first option forces playback of all the unwatched ads before the seek point. `PLAY_LAST` forces playback of the last ad before the seek point.

## Uplynk Ads API

Specifying a source which contains server-side ads configured through Uplynk will have the THEOplayer instance report such ads through its Ads API.

Users can use the THEOplayer Ads events to interact with Uplynk Ads:

```kotlin
player.ads.addEventListener(AdsEventTypes.ADD_AD_BREAK) {
    Log.d("UplynkConnectorEvents", "ADD_AD_BREAK ")
}

player.ads.addEventListener(AdsEventTypes.AD_BREAK_BEGIN) {
    Log.d("UplynkConnectorEvents", "AD_BREAK_BEGIN ")
}

player.ads.addEventListener(AdsEventTypes.AD_BEGIN) {
    Log.d("UplynkConnectorEvents", "AD_BEGIN ")
}

player.ads.addEventListener(AdsEventTypes.AD_FIRST_QUARTILE) {
    Log.d("UplynkConnectorEvents", "AD_FIRST_QUARTILE ")
}

player.ads.addEventListener(AdsEventTypes.AD_MIDPOINT) {
    Log.d("UplynkConnectorEvents", "AD_MIDPOINT ")
}

player.ads.addEventListener(AdsEventTypes.AD_THIRD_QUARTILE) {
    Log.d("UplynkConnectorEvents", "AD_THIRD_QUARTILE ")
}

player.ads.addEventListener(AdsEventTypes.AD_END) {
    Log.d("UplynkConnectorEvents", "AD_END ")
}

player.ads.addEventListener(AdsEventTypes.AD_BREAK_END) {
    Log.d("UplynkConnectorEvents", "AD_BREAK_END ")
}

player.ads.addEventListener(AdsEventTypes.AD_ERROR) {
    Log.d("UplynkConnectorEvents", "AD_ERROR " + it.error)
}

player.ads.addEventListener(AdsEventTypes.AD_SKIP) {
    Log.d("UplynkConnectorEvents", "AD_SKIP ")
}

player.addEventListener(PlayerEventTypes.ERROR) {
    Log.d("UplynkConnectorEvents", "ERROR " + it.errorObject)
}
```

Users can also skip Ads through the `skip` API in THEOplayer:

```kotlin
player.ads.skip()
```

> Calling the `player.ads.skip()` function on a live stream will not have any effect.

## Related articles

* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/uplynk/preplay.md)
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/uplynk/ping.md)

---

# Ping

This article explains how to use the Uplynk Ping API.

The Ping API for Uplynk allows users of their CMS to receive updates about SSAI on running live-streams or provide better playback position beaconing for Video on demand. The Ping API is used together with the Preplay API because the latter provides a session to be used with the Ping API.

This connector allows the user to specify a source for Preplay, and enable or disable certain features of the Ping API. The player will then perform these Ping calls internally, without the user having to write their own Ping client. The response of Ping calls will be exposed for external handling if necessary.

**Feature Assumptions** We assume the SSAI information returned through the Ping API to be of a certain format, which we compile from examples and our own testing. The documentation does not define the structure of this payload very well and only states that it is "like the object returned in Preplay requests", though the formats are not a one-on-one match.

**Assumptions**

* THEOplayer assumes the availability of the Ping API and Uplynk content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
* THEOplayer assumes application developers have a notion of the Ping API, namely any extra parameters to be appended to the requests to Uplynk (e.g. for correct ad insertion). As documented in <https://api-docs.uplynk.com/#Develop/Preplayv2.htm>
* THEOplayer assumes application developers provide proper ID's of the Assets they want to play back, as well as the proper content protection level.

## Configuring Ping

The connector allows specification of the desired features of the Ping API as listed [in the official Ping API documentation](https://api-docs.uplynk.com/#Develop/Preplayv2.htm#Features).

In the THEOplayer-Connector-Uplynk, these features can be activated through the `pingConfiguration` property in the SSAI description:

```kotlin
  val ssaiDescription = UplynkSsaiDescription
    .Builder()
    .prefix("https://content.uplynk.com")
    .assetType(UplynkAssetType.ASSET)
    .assetIds( your list of asset IDs )
    .preplayParameters( your linkedMapOf preplay parameters)
    .contentProtected(false)
    .pingConfiguration(
      UplynkPingConfiguration.Builder()
        .adImpressions(true)
        .freeWheelVideoViews(false)
        .linearAdData(false)
        .build()
    )
    .build()
```

By default, the ping API is disabled for all sessions. To enable it, the `ad.cping=1` parameter must be added to your preplay request. In addition to enabling the API, you must also notify the server of the features you want to support for this viewing session. To specify which features you'd like to enable, you add the`ad.pingf={some value}` parameter to the playback token. The value of the parameter is detailed in the official Ping Documentation.

Ping is enabled and `ad.pingf` is set to a proper value when the `UplynkPingConfiguration` has one or more of the `adImpressions`, `freeWheelVideoViews` or `linearAdData` configuration set to `true`.

If you attempt to call the API without passing in the `ad.cping` parameter, you can throw off the server's ability to make ad event calls correctly.

Sample Preplay URL with `ad.cping`:

`https://content.uplynk.com/preplay/cc829785506f46dda4c605abdf65392b.json?ad=adserver&ad.cping=1&ad.pingf=3`

The default value for `UplynkPingConfiguration` has `adImpressions`, `freeWheelVideoViews` and `linearAdData` all set to false, ie, Ping API will not be used.

## Ping requests

When the Ping API is enabled, THEOplayer will call the Ping URL located at:

```text
{prefix}/session/ping/{sessionID}.json?v=3&pt={currentTime}&ev={event}&ft={freeWheelTime}
```

Where:

* `{prefix}`: Is the prefix URL from the Preplay response.

* `{sessionID}`: Is the session ID from the Preplay response.

* `{currentTime}`: Mandatory parameter. This is the current player time in seconds.

* `{event}`: Is the current Ping event. An event should only be passed when playback starts or when a viewer seeks to a new position. Valid values are:

  * **start**: Pass this event, along with `pt=0`, when the player starts playback. This lets the server know where playback starts and allows the server to fire start events as needed.
  * **seek**: Pass this event when a viewer seeks. This resets the timeline to prevent inadvertently firing events for skipped ads.

* `{freeWheelTime}`: Indicates the playback position, in seconds, right before a viewer seeks to a different position in the timeline. This property is mandatory when the freeWheelVideoViews is used.

## Ping Response

When performed correctly, a Ping request will return a JSON response which is decoded into a `PingResponse`.

The ping response includes:

* nextTime: A new beacon will be scheduled when the player's currentTime passes this value. In case the value is -1, no further beacons will be scheduled.

* ads: Will be interpreted in order to create AdBreak's and Ad's as well as expose Ad information through the THEOplayer instance's `ads.scheduledAds` property.

  * ads.breaks.timeOffset will be used in order to determine the start time of the ad break (in seconds).

  * ads.breaks.ads will be looped in order to extract the list of ad's in an UplynkAdBreak:

    * apiFramework - Indicates the API Framework for the ad (e.g., VPAID).
    * companions - List of companion ads that go with the ad.
    * mimeType - Indicates the ad's Internet media type (aka mime-type)
    * creative - If applicable, indicates the creative to display.
    * events - Object containing all of the events for this ad. Each event type contains an array of URLs.
    * width - If applicable, indicates the width of the creative.
    * height - If applicable, indicates the height of the creative.
    * duration - Indicates the duration, in seconds, of an ad's encoded video.
    * extensions - Contains the custom set of VAST extensions returned by the ad server.
    * fwParameters - If the ad response provided by FreeWheel contains creative parameters, they will be reported as name-value pairs within this object.

  * ads.breaks.duration - Indicates the duration of the ad break.

  * ads.breaks.position - Indicates the position of the ad break. Valid values are: preroll | midroll | postroll | pause | overlay.

  * ads.breaks.type - Indicates the ad break type. Valid values are: "linear", "nonlinear".

The ping response can be retrieved from the `onPingResponse(:)` callback method by setting an `addListener` to the `UplynkConnector` instance.

| Callback method | Description                             | Arguments                                           |
| --------------- | --------------------------------------- | --------------------------------------------------- |
| onPingResponse  | Fired when a Ping response is received. | `pingResponse` argument contains the `PingResponse` |

## Related articles

* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/uplynk/preplay.md)
* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/android/uplynk/ads.md)

---

# THEOplayer iOS & tvOS SDK

Dolby OptiView Player (formerly THEOplayer) is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/ios/getting-started.md)

[Set up your first THEOplayer in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/ios/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md)

## [🔌Connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios.md)

[Integrate third-party solutions with THEOplayer using our pre-built connectors.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog.md)

[Find out what's new in the OptiView Player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog.md)

## [\*️⃣API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios)

[Discover all properties and functions of THEOplayer.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

# Getting started on iOS/tvOS

## Introduction

This guide covers the steps to obtain and set up the core Dolby OptiView Player SDK targeting a native iOS/tvOS application. It also provides information and usage of the commonly used APIs.

## Setup

### THEOplayer license

THEOplayer requires a valid THEOplayer license to be configured in order to access the SDK APIs (with the exception of some whitelisted sources hosted by our CDN). Request your license via <https://portal.theoplayer.com>.

After creating your license, you can copy its license string to your clipboard as demonstrated in the screenshot below.

![](https://cdn.theoplayer.com/images/git/theoplayer-ios-sdk-license-string.png)

> **Note**
>
> It's possible to add multiple platforms in a single license i.e. iOS & tvOS.

Later in the guide we explain how to configure the license ([in this section](#adding-the-theoplayer-license)).

### Installation

The THEOplayer SDK is published on the following package managers:

#### CocoaPods

> **Tip**
>
> It's considered good practice to run `pod repo update` before adding new pods to your Podfile. This will help find newly added pods by updating the list of references to the public spec repos. If you just installed CocoaPods or are already up-to-date, then this step can be skipped.

<br />

Add the following entry to your Podfile:

```ruby
target 'MyApp' do
  pod 'THEOplayerSDK-core', '~> 8' # at the time of writing, v8 is the latest major version.
end
```

> **Note**
>
> You can skip specifying the version to get the latest published version of THEOplayerSDK.

Then, using the terminal navigate to the directory where your Podfile is located and run:

```bash
pod install
```

If it's the first time that your project integrates with CocoaPods, then after this step you should stop using the `xcodeproj` file and instead start using the `xcworkspace` file generated by CocoaPods.

#### Swift Package Manager

Navigate to your Xcode project, and select the `Package Dependencies` tab, then click on the `+` button to add a new dependency. Then in the search bar, add the following URL <https://github.com/THEOplayer/theoplayer-sdk-apple>. Choose the version and click on `Add Package`.

The following image illustrates what it should look like:

![](/pr-932/assets/images/ios-getting-started-1-892e63410e915e1e73824a33fa3038de.png)

> **Info**
>
> If Xcode fails to fetch the THEOplayer package, navigate in Terminal to the root directory of your project and run `xcodebuild -resolvePackageDependencies`. This will re-attempt to fetch the packages specified in the project. Restart your Xcode and the package dependencies should be in place.

And make sure the THEOplayerSDK framework is added to the target application:

![](/pr-932/assets/images/ios-getting-started-3-af7cd19fa611660e32ef5dc2b71957b1.png)

## Usage

The following code snippets will demonstrate a basic playback scenario. The demo adopts the `UIKit` framework, and assumes the usage of `UIViewController`.

### Adding the THEOplayer license

[After obtaining your THEOplayer license string](#theoplayer-license), navigate to your Xcode project's plist file and add a new key/value entry. The key should be `THEOplayerLicense` and the value should be your license string.

The following image illustrates what it should look like:

![](/pr-932/assets/images/ios-getting-started-2-773df42c859c8472dbeda2b02ef975c1.png)

### Importing the framework

Add the import statement in your source files where you would like to use THEOplayer:

```swift
import THEOplayerSDK
```

### Setting up the player

THEOplayer provides a configuration object to configure the player settings. In the following snippet we configure the player license to be passed to the player.

> **Note**
>
> If the license is provided through the `plist` file (as mentioned above), then passing again in the player configuration is not required.

```swift
var theoplayer: THEOplayer?
...
...
override func viewDidLoad() {
...
	let configBuilder = THEOplayerConfigurationBuilder()
    configBuilder.license = "your_license_here"
    let theoplayer = THEOplayer(configuration: configBuilder.build())
    self.theoplayer = theoplayer
...
}
```

> **Info**
>
> It is important to keep a strong reference to the player as demonstrated in the above code snippet, otherwise the player will not be retained by ARC.

### Displaying the player

THEOplayer provides conventional APIs similar to UIKit framework's view related APIs. The following snippet demonstrates how to present an inline player view:

```swift
let playerFrame = CGRect(x: 0, y: 0, width: 320, height: 180)
theoplayer.frame = playerFrame
theoplayer.center = view.center
theoplayer.addAsSubview(of: self.view)
```

For more information on how to present the player in various modes, please check out the player documentation for the `PresentationMode` API. The link to the API reference can be found at the end of this guide.

### Adding a source for playback

Sources are passed to the player via an object called SourceDescription. The following snippet uses a source URL that serves an HLS manifest file:

```swift
let source = "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"
let mimeType = "application/x-mpegurl"
theoplayer.source = SourceDescription(source: TypedSource(src: source, type: mimeType))
```

> **Warning**
>
> Sources that are not whitelisted in the THEOplayer license will fail to play. If no player license is configured, then by default only sources from the `theoplayer` domain will play. This can be the reason of failure when updating the source in the snippet above.

### Basic playback controls

#### Starting playback

```swift
theoplayer.play()
```

#### Pausing or stopping playback

```swift
theoplayer.pause()
// or
theoplayer.stop()
```

The difference between the `pause` and `stop` methods is that `pause` will allow the player to continue if `play` is called, whereas `stop` will end playback. When stopped, a new source is expected to be set.

#### Seeking forward or backward in time

```swift
let time: Double = 30.0
theoplayer.currentTime = time
```

#### Seeking forward relatively to current time

```swift
let currentTime = theoplayer.currentTime
// Jump 10 seconds forward
theoplayer.currentTime = currentTime + 10
```

### Attaching player event listeners

It's very useful during the player's lifecycle, especially for state management and UI updates, to listen to certain events that are dispatched from the THEOplayer SDK.

For example, to listen to the time update event and update the UI of the application to reflect the change:

```swift
var eventListener: EventListener?
...
...
eventListener = theoplayer.addEventListener(type: PlayerEventTypes.TIME_UPDATE) { [weak self] event in self?.onTimeUpdate(event: event) }
...
...
func onTimeUpdate(event: TimeUpdateEvent) {
    playerInterfaceView.currentTime = Float(event.currentTime)
}
```

To remove an event listener:

```swift
theoplayer.removeEventListener(type: PlayerEventTypes.TIME_UPDATE, listener: eventListener!)
```

For more player event types, please check out the player documentation for the `PlayerEventTypes` API. The link to the API reference can be found at the end of this guide.

## Useful links

* [THEOplayer iOS SDK API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/index)
* [THEOplayer iOS sample app with basic playback](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Basic-Playback)
* [THEOplayer iOS sample app with Google IMA integration](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Google-IMA)
* [THEOplayer iOS sample app with Google Cast playback](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Google-Cast)

---

# THEOplayer iOS/tvOS 5.0 Feature Integrations

## Modularization

The THEOplayer iOS 5.0 SDK uses modularized features, which means there is a base SDK that can handle basic playback and additional feature integrations are provided as separate modules that can be added as desired. This approach gives more flexibility and results in a reduced application size, since non-required parts are not included in the build of the application.

For example, the core SDK is provided by:

```swift
import THEOplayerSDK
```

Meanwhile, additional features such as Google IMA and Google Cast are provided by:

```swift
import THEOplayerGoogleIMAIntegration
import THEOplayerGoogleCastIntegration
```

## Importing additional integration modules

As shown in the previous section, importing additional integration modules can be done by simply adding the dependency to your swift source file.

For more information on how to fetch the dependencies to your Xcode project, [please check the getting started guide.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/ios/getting-started.md)

**Important Note:** It is required to keep the THEOplayer core SDK and all the required feature modules on the **same** version number. For example one should **not** import `THEOplayerSDK-core~>5.6.0` and `THEOplayer-Integration-GoogleIMA~>5.5.0` in the same project.

## Adding integrations

After importing the dependencies, it's time to create the integrations and connect them to THEOplayer.

Each module provides a **Factory** class that allows the creation of that specific integration. For example, the Google IMA module provides `GoogleImaIntegrationFactory` and the Google Cast module provides `GoogleCastIntegrationFactory`.

Additionally, the `THEOplayer` class provides the `addIntegration(_ integration: Integration)` API which allows adding the integration to the player.

Connecting the feature integration with the `THEOplayer` will make them available to be used. Otherwise, calling an API from an integration without adding it to the `THEOplayer` will cause an error to be thrown.

## Available feature integrations

With THEOplayer iOS 5.0 SDK we currently support the following feature integrations:

| Feature    | Dependency                        | Release | Documentation                                                                                                   |
| ---------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| Google IMA | `THEOplayerGoogleIMAIntegration`  | 5.0.0   | [documentation](https://github.com/THEOplayer/theoplayer-sdk-ios/tree/master/THEOplayer-Integration-GoogleIMA)  |
| Chromecast | `THEOplayerGoogleCastIntegration` | 5.0.0   | [documentation](https://github.com/THEOplayer/theoplayer-sdk-ios/tree/master/THEOplayer-Integration-GoogleCast) |

---

# Migrating to THEOplayer iOS/tvOS SDK 10.x

This article will guide you through updating to THEOplayer iOS/tvOS SDK version 10 (from version 9), and the changes needed in your code.

## Update THEOplayer

Update THEOplayer iOS/tvOS SDK to version 10 in your Podfile:

```ruby
target 'MyApp' do
  pod 'THEOplayerSDK-core', '~> 10'
end
```

If you're using one of [our connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios.md), make sure to update them to the latest version too to ensure proper support for THEOplayer version 10.

## Builds generated with Xcode 16

In an effort to align with the changes made by Apple regarding the [App Store publishing policy](https://developer.apple.com/news/upcoming-requirements/?id=02212025a), starting from THEOplayer 10.0 we will distribute our SDK builds using Xcode 16. Effectively, this means that developing a client application using THEOplayer iOS/tvOS SDK will require a minimum version of Xcode 16.

## Single THEOlive playback pipeline

In THEOplayer 9.7.0 we introduced an improved THEOlive playback engine as a default option. The `useLegacyPlaybackEngine` flag on `THEOliveConfiguration` allowed customers to switch back to the legacy pipeline in case of unforeseen issues.

The discrepancies between the two pipelines were fully ironed out during the transition period.

The legacy playback pipeline is now has been fully retired, and the `useLegacyPlaybackEngine` property on `THEOliveConfiguration` has been removed.

## Replace usages of deprecated APIs

* Removed the `destroy()` method. Instead, destroy the player by removing its reference `self.player = nil`.
* Removed the `set` from the subscript of the `MediaTrackList` API. The `MediaTrackList` is a read-only list.
* Removed the `goLive()` method from THEOliveAPI. Instead, use `player.play()` which will seek to live and play.
* Removed the flag `useLegacyPlaybackEngine` in the initializer of `THEOliveConfiguration`
* Removed THEOlive publication events (`PublicationLoadStartEvent`, `PublicationLoadedEvent` and `PublicationOfflineEvent`), use the equivalent distribution events instead (`DistributionLoadStartEvent`, `EndpointLoadedEvent` and `DistributionOfflineEvent` respectively).

---

# Getting started with CMCD on iOS

Media player clients can transmit useful information to Content Delivery Networks (CDNs) with each object request. This implementation supports Common Media Client Data (CMCD) as defined in [CTA-5004](https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf), published in September 2020.

## Usage

To enable CMCD, developers can set the `cmcd` parameter inside a SourceDescription.

```swift
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", cmcd: true)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Remarks

Note that CMCD is only supported on iOS 18.0+.

---

# Getting started

## Usage

1. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/ios/getting-started.md) to set up THEOplayer in your iOS app.
2. Add an OptiView Live source to your player's source.

### Add an OptiView Live source

After setting up your THEOplayer in your app, set its source to a `SourceDescription` containing a `TheoLiveSource`. You'll need an OptiView Live channel ID:

```swift
theoplayer.source = SourceDescription(source: TheoLiveSource(channelId: "3aa5qylwwk7gijsobayq09yee"))
```

## More information

* [API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/api-reference/ios)

---

# Connectors for THEOplayer iOS & tvOS SDK

## [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/comscore)

[Integrate with Comscore for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/comscore)

## [![](/pr-932/img/conviva.svg)![](/pr-932/img/conviva_dark.svg)Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/conviva)

[Integrate with Conviva for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/conviva)

## [Nielsen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/nielsen)

[Integrate with Nielsen for player analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/nielsen)

## [![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAy0SURBVHgB7d1PbhRJFsfxiLIxs+iW2DbuaZVvwNzASGB6iU+AOQGuHd2YwSVhYId9AsMJYNmYkewb2DdwafjjWXoBEvUvYzKqSMqmjV1ZlZnxIuL7kVpqoZaM6M5f53svMp5SAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAORwt3q8fpn8pAKXQSij78Ju5S7tKmXr6m1z/0vm0tbC3eawAFEZkABwurl6Zm/tpN/3NXRv9qm4lpt/89e2TFwpAIcQFwNkP/ykH7U5veWHvWUsBmIqoABjj4f/GaP2i0+42CQJgcmICIM/DP6JbSidbV99sbCoAuYkIgMke/pPoDwCTcB4A0z/8I5QFQD5OA6DIh/+k4diw95IgAM7nLADKevhHKAuAizgJgPIf/pN0q93pXudtAPi7ygOg2od/hP4A8HeVBoCrh/+E4/Rnb/6y87ipAFQXAAIe/hPoDwBWJQEg6+EfoSxA7EoPAKkP/ylab7bb3S2CALEpNQC8ePi/oSxAfEoNgPc31zZrWt1TXhkEwXIaBAcKCFxNlUhrc0V5x9Rrurb/4dbDbW4jQuhKDQCfaWNWLs/NHh4trT1SQKAIgAsYpdY/Lj08fH/zzxUFBIYAGMugLNj+uLT2irIAISEA8rltywL6AwgFATCBYX/g0i5lAXxHAEwsKwseHr67sbaoAA8RAFMz9Zma2qUsgI8IgIIwNoSPCICCMTaETwiAUnwbG+5TFkAyAqBc1xgbQjICoALZ2PDjrQerChCEAKiMqSujn9v+wIelP24rQAACoHJ23fnMK8oCSEAAOHJybGgvTlGAAwSAY3ZseHnu533GhnCBABBhdKyYsgBVIgBEMXXGhqgSASBQNjbkWDHKRgCIZeocK0bZCADxhv0BygKUgQDwRDY2/Hjr4XOCAEUhAHxjzCq3EaEoBICXRmPDNAg82LoEqQgAr7HEBNMhAALwtT+wz9gQeREA4bjC2BB5EQDBYYkJxkcAhIslJrgQARA4lpjgPARAFFhigrMRAFFhiQlOIwAixBITZAiAiDE2BAEQPZaYxIwAQIYlJhEiAHAKY8O4EAA4w2hsyBKTsBEAOAdLTEJHAOBCLDEJFwGAsbHEJDwEAHJiiUlICABMiCUmISAAMBWWmPiNAEABWGLiKwIABWKJiW8IABTu9NiQIJCMAEBphmNDjhVLRgCgZIwNJSMAUBHGhhIRAKgUS0xkIQDgAktMhCAA4BBLTFwjACABS0wcIQAgBrcRVY8AgDCjsWEaBNcUSkUAQKhBEOxTFpSLAIBoLDEpFwEALzA2LAcBAI8M+wNHN9d2KQuKQQDAO0arRcaGxSAA4C3GhtMjAOA5lphMgwBAIFhiMgkCAEFhiUk+pQaASdSBAhxgicl4tCrZ0e/36yaZ2U1/VF0Bbhy0O73lhb1nLYVTSg+AjE3imtaPCAK4YrR+0Wl3mwTBSGUBYB0url+Zm+utpj+UY51wRLeUTrauvtnYVKg2ADK2LEiSmXWt9B0FOKFbiek3f3375IWKmJMAyLy7sbY4UzPblAVwJfaywGkAZOgPwLX0QVj/0um9jC0IRASAZcuCfn92tabVPQU4EV9ZICYAMvQH4J5utTvd6zG8DYgLgAxlAVyLoT8gNgAyBAEcO04fks1fdh43VYDEB4BFWQD3wuwPeBEAmeGx4tnn6d/y2Sdced3u9BqhlAVeBUCGsgDOab3Zbne3fA8CLwMg82FpLS0LzB2CAG74XxZ4HQAW/QG4NwiC5TQIvPv83fsAyHztD7xK/5ZtMnDCx7FhMAGQoT8A1+yxYl/GhsEFQGbYHxgcK+ZaKDjgR38g2ACw6A/ANW3U3pdu767UsiDoAMhwLRlck9ofiCIAMvQH4Ja8siCqALC4lgzu6ZZRvcb8ztPXyrHoAiBDfwCuSSgLog2ATFoWXEvLgleUBXDF5dgw+gDI0B+AW276AwTACcOyYHaF/gAcqnSJCQFwBvoDcK2q/gDLQc/wy1/PWvM7Gyumr5bTfxUtBVRssOT08kzp917wBjAG+gOolFF77Zne3YW/yi8DCIAxURagfKbVT/Tdf/7n8Z6qCAGQE0GAEhwbpbY6nU+bC3ubx6pCBMCEKAtQBKNN2uz73Kj6wc8QAFN6f+PBaq1mPzvWdQWMK63z+0Y1q3zdPwsBUADKAuRwnLb4m1LWkxMABRp8dtyf3U7/VBcV8J20zm+6qPPPQwCUgP4ATqlwrJcXAVAiriWLXfVjvbwIgJLRH4jSYKw3v/N4XQkXVAC8u7G2OKvVo6SmW9KuX+La8ji4HuvlFUQAHC3er6vLlx4ZY1ZO/rrE65npDwRKyFgvL68D4HBx9co/5n66l75uraof1tkyr2f+2h/gs2P/HScmafi6HszbAPjv0h+3Z5XdFGzq4/zzEq9npj/gN4ljvby8C4CszjcTztolXs/MtWSeETzWy8ubALCv+5fnfk5fmc2qmppuKZ1sSTmNlaE/IJ38sV5eXgTA0dLao/Pr/EnJ6w9wbblI3oz18hIdAPZ1f6amt8et8yclsSygPyBDYtRWt/tp3ec6/zwiA2Aw1rs0u22qPlOv9Wa73d2SFATDEDTblAUV83Ssl5eoACi2zp+UzLEh/YHKeD3Wy0tMAPzv5r/vJTpZV2LOzeu04WNENXxsWdDvz67W9OD7AhTL2a08LjkPAPuKW6up51roEVn6AxEIaKyXl7MAcFbnT8geK/7S+bQl6f8OlAXTCm+sl1flATDe8V2p6A8EItixXl6VBsDwP9Tac+X99/G61e50r1MW+Cf0sV5elQTAtMd3pZLaHzCJ/UZClb5VxiuRjPXyKjUAfvSZbmCO0z/ETT47lsqkZZsRV7ZJUWoAfFh68CKeV1Kh/YF4ry2PcqyXFwFQvNftTq9Bf8ChiMd6eREAJRHbHwj62nLGenmxHrwkg/XOc5d2bS2uhLBrz6++fXw9McndwNae22Ubjas7Gws8/PnwBlAJ3TKq15jfefpaCRLCteWM9aZDAFSIY8UFYqxXCALAgeGx4t5LeecHZnblTwtMq6eSxm/C3qZ8RQ/AgXQ8tS6yP5DW0IL7A3as12x3Pv+Lh784vAE4Nzg/sPzr2ycHShBR15Yz1isNbwDOmXpN1/Y/3Hq4fWhPTgphP5TRtd6CUealciT92Qf9RF23kwse/nLwBiCM0G1GVV9bbsd6TWm3NoeINwBhbH/g49LDQ0n9AVueVNUfsGO9dufTAg9/NXgDkO2g3ektyxsbzq4U3h9grOcEAeCBsM8PMNZziRLAA9mx4o+3Hji8Lfk0Ozac39lYMX21PGFZwFhPAN4AvBPEtWSv27Veg86+ewSAp6SWBeddW27HekmiG9T5chAAvhO4zeiM/gBjPaEIgCDILQu0rtW5lUcuAiAo8rYZQTamAEEx9Zma2pV2rBhyEQABGo4NZw+PltYe2UUsCvgBAiBgw8+Of96XdKwYshAAwRt8bbhtvy+gLMD3CIBomLotC+gP4CQCIDJf+wP7tj+gED0CIE5XJH52jOoRAFEb9geObq7tUhbEiQCAslub6Q/EiQDAN9lnx4e/EwKxIAAwYtSevaGYz3TjMasAlmpGiwCIm72VZ6vT+czXepEiAOLFrTwgAKLD7bs4gQCIx/BWnh1u5cEIARABu2yj2/20Tp2P7xEAIWOpJi5AAASJsR7GQwCEhbEeciEAAmG0edFpf27w4CMPAsB338Z6G3sKyIkA8NdxYpKGtF0A8AsB4CG7VJNlGygCAeATxnooGAHgBcZ6KAcBINtgrDe/s7GugBIQAEJxfBdVIACk4Ws9VIgAkIOxHipHALj39fguYz1UjwBwibEeHCMAnGCsBxkIgGoNb+V5w608kIEAqAhjPUhEAJSNsR4EIwBKY1o9lTR+e/v0tQKEIgCKx6088AYBUCyWbcArBEABjDIHSaIb1PnwDQEwncFYb56xHjxFAEyIsR5CQADklY71EjX4aOdAAZ4jAMbG8V2EhwC4GGM9BIsAOMdg2YbuNxnrIVQEwFlYtoFIlBoAxpg9rfUd5Y/h13o7jPUQB61K9v7mnys1XdtWwrFsAzEqPQAs0SHArTyIWCUBYMkLAcZ6QGUBYAkJAS7hBL6qNAAslyEwGOu1Pzd48IGhygPAqjwEuJUHOJOTALAqCgGWbQDncBYAVpkhwFgPuJjTALAKDwHGesDYnAeAVUwIMNYD8hIRANYUITAY683vPF5XAHIREwBW3hDgVh5gOqICwBorBBjrAYUQFwDWj0PAtBJjmoz1gGKIDADruxDg+C5QArEBYA1CQNXuMNYDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABALP4PxPhKst9YjwYAAAAASUVORK5CYII=)Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/yospace)

[Integrate with Yospace for server-side ad insertion (SSAI).](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/yospace)

## [💬Sideloaded Subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/sideloaded-texttracks)

[Add support for sideloaded subtitles to your player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/sideloaded-texttracks)

## [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk)

[Add support for Uplynk CMS to your player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/changelog.md)

[Find out what's new.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/changelog.md)

---

# THEOPlayer 🤝 Comscore

THEOplayer-Connector-Comscore provides an integration between the THEOplayerSDK and ComScore.

## Installation

### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add links to the registry of Cocoapods: `source 'https://cdn.cocoapods.org/'`. If this fails, bypass their CDN by using `source 'https://github.com/CocoaPods/Specs.git'`
3. To your Podfile, add the connector pods that you want to use in your app: `pod 'THEOplayer-Connector-Comscore'`
4. Install the pods using `pod install` , then open your `.xcworkspace` file to see the project in Xcode.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.
2. Use a [local override](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine) of the `THEOplayerSDK-basic` pod by adding the following line to your projects Podfile: `pod 'THEOplayerSDK-basic', :path => 'iOS-Connector/Helpers/TheoPod'` and make sure the path points to the [TheoPod folder](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoPod).

## Usage

Import the `THEOplayerConnectorComscore` module

```swift
import THEOplayerConnectorComscore
```

Create a ComScoreConfiguration that contains your publisherId (also referred to as customer or c2 id), app name, an indication of whether the user has granted his/her consent for tracking, an adIdProcessor (if you want to extract and manipulate ad id's that will be reported to ComScore, by default we use THEOplayerSDK.Ad.id) and a debugging flag (for extra logging) :

```swift
let configuration = ComScoreConfiguration(
    publisherId: "<your id>",
    applicationName: "<your application name>",
    usagePropertiesAutoUpdateMode: .foregroundOnly,
    userConsent: .granted,
    adIdProcessor: nil,
    debug: true
)
```

Create a `ComscoreConnector` that uses this `configuration`, your `THEOplayer` instance and a valid `ComScoreMetadata` instance for the first content you will load to the player. You can change the metadata dynamically later on if necessary:

```swift
let connector = ComscoreConnector(
    configuration: configuration,
    player: yourTHEOplayer,
    metadata: ComScoreMetadata(
        mediaType: .shortFormOnDemand,
        uniqueId: "0123ABC",
        length: 596,
        stationTitle: "THEO TV",
        programTitle: "Big Buck Bunny",
        episodeTitle: "Example Title",
        genreName: "animation",
        classifyAsAudioStream: false)
)
```

Note that if you are using Google IMA connector, you must make sure it's registered before you initialize the `ComscoreConnector`. Otherwise it will fail to hook into the ad related events.

## Which metadata do I need to provide?

### ComscoreMetadata fields

Based on the `ComScoreMetadata` constructor, you can tell which fields are mandatory and which aren't. Note that this is purely for the integration to work correctly. Depending on the Comscore solution you are using, different fields are required/optional. The mandatory fields in the `ComScoreMetadata` type are the ones that are mandatory for all three Comscore solutions:

* Video Metrix (V)
* Cross Platform Product Suite (X)
* Cross Media Audience Measurement (C)

| Property                           | Required | Optional |
| ---------------------------------- | -------- | -------- |
| `mediaType`                        | All      |          |
| `uniqueId`                         | All      |          |
| `length`                           | All      |          |
| `c3?`                              | V        |          |
| `c4?`                              | V        |          |
| `c6?`                              | V        |          |
| `stationTitle`                     | All      |          |
| `stationCode?`                     |          | All      |
| `networkAffiliate?`                |          | All      |
| `publisherName?`                   | X C      | V        |
| `programTitle`                     | All      |          |
| `programId?`                       |          | V C      |
| `episodeTitle`                     | All      |          |
| `episodeId?`                       |          | X C      |
| `episodeSeasonNumber?`             | X C      |          |
| `episodeNumber?`                   | X C      |          |
| `genreName`                        | All      |          |
| `genreId?`                         |          | All      |
| `carryTvAdvertisementLoad?`        | X        |          |
| `classifyAsCompleteEpisode?`       | X        |          |
| `dateOfProduction?`                |          | C        |
| `timeOfProduction?`                |          | C        |
| `dateOfTvAiring?`                  | X C      |          |
| `timeOfTvAiring?`                  |          | X C      |
| `dateOfDigitalAiring?`             | X C      |          |
| `timeOfDigitalAiring?`             |          | X C      |
| `feedType?`                        | X        |          |
| `classifyAsAudioStream`            | Al       |          |
| `deliveryMode?`                    |          | All      |
| `deliverySubscriptionType?`        |          | All      |
| `deliveryComposition?`             |          | All      |
| `deliveryAdvertisementCapability?` |          | All      |
| `mediaFormat?`                     |          | All      |
| `distributionModel?`               |          | All      |
| `playlistTitle?`                   |          | C        |
| `totalSegments?`                   |          | V C      |
| `clipUrl?`                         |          | V C      |
| `videoDimension?`                  |          | C        |
| `customLabels?`                    |          | All      |

---

# THEOPlayer 🤝 Comscore Samples

We provide source code of two sample applications that illustrate how to use the connector with different package managers:

* [Sample using **Cocoapods**](https://github.com/THEOplayer/iOS-Connector/blob/-/Code/Comscore-Examples/Cocoapod) (requires Cocoapods installation through terminal)

---

# THEOPlayer 🤝 Conviva

THEOplayer-Connector-Conviva for iOS provides an integration between the THEOplayerSDK and ConvivaSDK. It connects to the Conviva backend and reports events fired from THEOplayer instances.

For example xcode projects with this connector see [Conviva-Examples](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/conviva/examples.md).

## Installation

### [Swift Package Manager](https://swift.org/package-manager/)

1. In Xcode, install the Conviva libraries by navigating to **File > Add Packages**
2. In the prompt that appears, select the iOS-Connector GitHub repository: `https://github.com/THEOplayer/iOS-Connector`
3. Select the version you want to use.
4. Choose the Connector libraries you want to include in your app.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.

2. Use a [local override](https://developer.apple.com/documentation/xcode/editing-a-package-dependency-as-a-local-package) of the `theoplayer-sdk-ios` package by selecting the folder `../../Helpers/TheoSPM/theoplayer-sdk-ios` in Finder and dragging it into the Project navigator of your Xcode project.

3. Place your custom THEOplayerSDK.xcframework at `../../Helpers/TheoSPM/theoplayer-sdk-ios/THEOplayerSDK.xcframework`. (It is also possible to place your xcframework somewhere else. In that case make sure to update the [Package.swift](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoSPM/theoplayer-sdk-ios/Package.swift) manifest inside the your local override so that it points to your custom THEOplayer build)

4. If Xcode complains about a missing xcframework

   1. Choose `File` > `Packages` > `Reset Package Caches` from the menu bar.
   2. If it is still not working, make sure to remove any `THEOplayerSDK.xcframework` inclusions that you manually installed before installing this THEOplayer-Connector-Conviva package.

### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add the Conviva connector pods that you want to use in your app: `pod 'THEOplayer-Connector-Conviva'`
3. Install the pods using `pod install` , then open your `.xcworkspace` file to see the project in Xcode.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.
2. Use a [local override](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine) of the `THEOplayerSDK-basic` pod by adding the following line to your projects Podfile: `pod 'THEOplayerSDK-basic', :path => 'iOS-Connector/Helpers/TheoPod'` and make sure the path points to the [TheoPod folder](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoPod).

## Usage

Import the `THEOplayerConnectorConviva` module

```swift
import THEOplayerConnectorConviva
```

Create a `ConvivaConfiguration` that contains the info on how to connect to your conviva endpoint:

```swift
let configuration = ConvivaConfiguration(
    customerKey: "put your customer key here",
    gatewayURL: " put your  gateway URL here ",
    logLevel: .LOGLEVEL_FUNC
)
```

Create a `ConvivaConnector` that uses this `configuration` and your `THEOplayer` instance:

```swift
let connector = ConvivaConnector(
    configuration: configuration,
    player: yourTHEOplayer
)
```

For each asset you play, the **asset name** needs to be reported to Conviva which you can do by providing the asset name as a `title` field inside your `SourceDescription's metadata`:

```swift
let mySource = SourceDescription(source: source, metadata: MetadataDescription(metadataKeys: ["title": "your_asset_name"]))
```

Alternatively, the **asset name** can be provided as contentInfo (`CIS_SSDK_METADATA_ASSET_NAME`) using the setContentInfo method, along with other metadata. For example to report the **viewer's ID**:

```swift
let contentInfo = [ 
   CIS_SSDK_METADATA_VIEWER_ID: "your_viewer_id"
]
connector.setContentInfo(contentInfo)
```

**Important note**: setting a new source on the player will reset previously set contentInfo. Make sure to use the `setContentInfo` method after receiving the SOURCE\_CHANGE event.

## Lifecycle

Hold a reference to your connector. Once the connector is released from memory it will clean up itself and stop reporting to Conviva.

---

# THEOPlayer 🤝 Conviva Samples

We provide source code of two sample applications that illustrate how to use the connector with different package managers:

* [Sample using **Swift Package Manager**](https://github.com/THEOplayer/iOS-Connector/blob/-/Code/Conviva-Examples/SPM) (works out of the box with Xcode 12 and above)

* [Sample using **Cocoapods**](https://github.com/THEOplayer/iOS-Connector/blob/-/Code/Conviva-Examples/Cocoapod) (requires Cocoapods installation through terminal)

---

# THEOPlayer 🤝 Nielsen

THEOplayer-Connector-Nielsen provides an integration between the THEOplayerSDK and NielsenAppSDK & NielsenTVOSAppSDK. It connects to the Nielsen backend and reports events fired from THEOplayer instances.

## Installation

### [Swift Package Manager](https://swift.org/package-manager/)

1. In Xcode, install the Nielsen connector by navigating to **File > Add Packages**
2. In the prompt that appears, select the iOS-Connector GitHub repository: `https://github.com/THEOplayer/iOS-Connector`
3. Select the version you want to use.
4. Choose the Connector libraries you want to include in your app.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.

2. Use a [local override](https://developer.apple.com/documentation/xcode/editing-a-package-dependency-as-a-local-package) of the `theoplayer-sdk-ios` package by selecting the folder `../../Helpers/TheoSPM/theoplayer-sdk-ios` in Finder and dragging it into the Project navigator of your Xcode project.

3. Place your custom THEOplayerSDK.xcframework at `../../Helpers/TheoSPM/theoplayer-sdk-ios/THEOplayerSDK.xcframework`. (It is also possible to place your xcframework somewhere else. In that case make sure to update the [Package.swift](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoSPM/theoplayer-sdk-ios/Package.swift) manifest inside the your local override so that it points to your custom THEOplayer build)

4. If Xcode complains about a missing xcframework

   1. Choose `File` > `Packages` > `Reset Package Caches` from the menu bar.
   2. If it is still not working, make sure to remove any `THEOplayerSDK.xcframework` inclusions that you manually installed before installing this connector package.

### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add links to the registries of Cocoapods and Nielsen: `source 'https://cdn.cocoapods.org/'` and `source 'https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-specs-dynamic.git'`
3. To your Podfile, add the connector pods that you want to use in your app: `pod 'THEOplayer-Connector-Nielsen'`
4. Install the pods using `pod install` , then open your `.xcworkspace` file to see the project in Xcode.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.
2. Use a [local override](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine) of the `THEOplayerSDK-basic` pod by adding the following line to your projects Podfile: `pod 'THEOplayerSDK-basic', :path => 'iOS-Connector/Helpers/TheoPod'` and make sure the path points to the [TheoPod folder](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoPod).

## Usage

Import the `THEOplayerConnectorNielsen` module

```swift
import THEOplayerConnectorNielsen
```

Create a Dictionary that contains the info on how to connect to your Nielsen endpoint:

```swift
let configuration = [
  "appid": "XXYnnnnnn-XnnX-nXXn-nXnn-XnnnnXnnnXnX",
  "appversion": "n.n",
  "appname": "Theo Nielsen Sample App",
  "nol_devDebug": "DEBUG"
]
```

Create a `NielsenConnector` that uses this `configuration` and your `THEOplayer` instance:

```swift
let connector = NielsenConnector(
    configuration: configuration,
    player: yourTHEOplayer
)
```

Hold a reference to your connector. Once the connector is released from memory it will clean up itself and stop reporting to Nielsen.

## What events does this connector report to Nielsen?

### Basic playback events

| THEOplayer event                    | NielsenAppApi report func       |
| ----------------------------------- | ------------------------------- |
| PlayerEventTypes.LOADED\_META\_DATA | loadMetadata(\_ metadata: Any?) |
| PlayerEventTypes.PAUSE              | stop()                          |
| PlayerEventTypes.SOURCE\_CHANGE     | end()                           |
| PlayerEventTypes.ENDED              | end()                           |
| PlayerEventTypes.DESTROY            | end()                           |
| TextTrackEventTypes.ENTER\_CUE      | sendID3(\_ data: String)        |

---

# THEOPlayer 🤝 Yospace

THEOplayer-Connector-Yospace provides an integration between the THEOplayerSDK and Yospace to allow playback of server-side ad inserted streams.

## Installation

### [Swift Package Manager](https://swift.org/package-manager/)

1. In Xcode, install the Yospace connector by navigating to **File > Add Packages**
2. In the prompt that appears, select the iOS-Connector GitHub repository: `https://github.com/THEOplayer/iOS-Connector`
3. Select the version you want to use.
4. Choose the Connector libraries you want to include in your app.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.

2. Use a [local override](https://developer.apple.com/documentation/xcode/editing-a-package-dependency-as-a-local-package) of the `theoplayer-sdk-ios` package by selecting the folder `../../Helpers/TheoSPM/theoplayer-sdk-ios` in Finder and dragging it into the Project navigator of your Xcode project.

3. Place your custom THEOplayerSDK.xcframework at `../../Helpers/TheoSPM/theoplayer-sdk-ios/THEOplayerSDK.xcframework`. (It is also possible to place your xcframework somewhere else. In that case make sure to update the [Package.swift](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoSPM/theoplayer-sdk-ios/Package.swift) manifest inside the your local override so that it points to your custom THEOplayer build)

4. If Xcode complains about a missing xcframework

   1. Choose `File` > `Packages` > `Reset Package Caches` from the menu bar.
   2. If it is still not working, make sure to remove any `THEOplayerSDK.xcframework` inclusions that you manually installed before installing this connector package.

### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add the Yospace connector pod that you want to use in your app: `pod 'THEOplayer-Connector-Yospace'`
3. Add the following post-install hook in your Podfile:

```ruby
post_install do |installer|
    custom_framework_path = "#{installer.sandbox.root}/YOAdManagement-Release/YOAdManagement.xcframework"

    installer.pods_project.targets.each do |target|
      if target.name == 'THEOplayer-Connector-Yospace'
        framework_build_phase = target.frameworks_build_phase
        file_ref = installer.pods_project.new_file(custom_framework_path)

        framework_build_phase.add_file_reference(file_ref)
      end
    end
end
```

Check the Dependencies section below to get information on how to obtain the `YOAdManagement.xcframework` as a pod. 4. Install the pods using `pod install` , then open your `.xcworkspace` file to see the project in Xcode.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.
2. Use a [local override](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine) of the `THEOplayerSDK-basic` pod by adding the following line to your projects Podfile: `pod 'THEOplayerSDK-basic', :path => 'iOS-Connector/Helpers/TheoPod'` and make sure the path points to the [TheoPod folder](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoPod).

## Dependencies

The THEOPlayer Yospace connector has two dependency frameworks: THEOplayerSDK and YOAdManagement.

THEOplayerSDK is added as a dependency on both Cocoapods and SPM and will be fetched by each dependency manager. YOAdManagement is published as a private pod hosted on Artifactory by jfrog. In order to get the framework you will need to:

1. Setup a Yospace developer account at <https://www.yospace.com/developer>
2. Login to the Yospace Apple docs <https://developer.yospace.com/sdk-documentation/apple/userguide/latest/en/index-en.html>
3. Follow the instructions to setup the artifactory, authenticate, and fetch the framework at <https://developer.yospace.com/sdk-documentation/apple/userguide/latest/en/prerequisites.html>

## Usage

Import the `THEOplayerConnectorYospace` module

```swift
import THEOplayerConnectorYospace
```

Create a `SourceDescription` that defines the Yospace stream:

```swift
let streamType: YospaceStreamType = .live
let typedSource: TypedSource = .init(
    src: "yospace_live_stream_url",
    type: "application/x-mpegurl",
    ssai: YospaceServerSideAdInsertionConfiguration(streamType: streamType)
)
let source: SourceDescription = SourceDescription(source: typedSource)
```

Create a `YospaceConnector` that uses a `THEOplayer` instance:

```swift
let theoplayer: THEOplayer = .init()
let connector: YospaceConnector = .init(player: theoplayer)
```

**Note:** Hold a reference to your connector instance by storing it as a property. Keeping it inline will get it auto-released from memory. Once the connector is released from memory it will reset and unload autonomously.

Set the source and play. There are 2 ways to set a Yospace source:

1. Through the API provided by the YospaceConnector:

```swift
connector.setupYospaceSession(sourceDescription: source)
```

The connector will then fire a `SESSION_AVAILABLE` event once the setup is successful. The client can track this event to start playback:

```swift
_ = connector.addEventListener(type: YospaceEventTypes.SESSION_AVAILABLE, listener: { event in
    theoplayer.play()
})
```

When using the `setupYospaceSession` API, the connector will throw an error in case the `TypedSource` is not of type `YospaceServerSideAdInsertionConfiguration`.

2. Through the player:

```swift
theoplayer.source = source
theoplayer.play()
```

---

# THEOplayer ❤️ Sideloaded Subtitles

THEOplayer-Connector-SideloadedSubtitle brings sideloaded subtitle support to THEOplayer's iOS SDK.

By using an experimental API from THEOplayer, this library aims to achieve sideloaded TextTrack support across all Apple devices and all media playback scenarios.

The presented technique is superior to any other similar options as it brings sideloading support to Airplay, Picture-in-Picture and DRM playback (and their combinations) and is out-of-the-box compatible with the TextTrackStyling API from THEOplayer.

This connector is intended to be used for subtitle text tracks. For metadata text tracks, such as WebVTT thumbnails, starting from v7.10 the core THEOplayerSDK will handle the sideloading without the help of this connector.

## Installation

### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add links to the registry of Cocoapods: `source 'https://cdn.cocoapods.org/'`. If this fails, bypass their CDN by using `source 'https://github.com/CocoaPods/Specs.git'`
3. To your Podfile, add the connector pods that you want to use in your app: `pod 'THEOplayer-Connector-SideloadedSubtitle'`
4. Install the pods using `pod install`, then open your `.xcworkspace` file to see the project in Xcode.

## Usage

Import the `THEOplayerConnectorSideloadedSubtitle` module.

```swift
import THEOplayerConnectorSideloadedSubtitle
```

After importing the module, a new API will be available on the THEOplayer instance called `setSourceWithSubtitles(source: SourceDescription?)`

If you use this method to set a source, THEOplayer will be able to present sideloaded subtitles (via the `TextTrackDescription` already known from THEOplayer 4.x) configured with your `SourceDescription`, e.g.:

```swift
public static var sourceWithSideloadedTextTrack : SourceDescription {
    let typedSource = TypedSource(src: "https://sourceURL.com/manifest.m3u8, type: "application/x-mpegurl")
    let textTrack = TextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
    return SourceDescription(source : typedSource, textTracks :[textTrack])
}
```

```swift
theoplayer.setSourceWithSubtitles(source: sourceWithSideloadedTextTrack)
```

**NOTE:** Replace every `theopalyer.source = newSource` call with `theoplayer.setSourceWithSubtitles(source: newSource)` in your application if you intend to use (at least once) subtitle sideloading. Even if you don't have sideloaded subtitles on some of your sources. **Combining both approaches could lead to unexpected behavior.**

## Limitations

1. THEOplayer-Connector-SideloadedSubtitle relies on an experimental API from THEOplayer which is subject to change. **Always use matching THEOplayer and Connector versions.**
2. **Supported formats are: iOS-compatible `WebVTT` subtitles and SRT** via this connector today.
3. The presented **label within THEOplayer is auto-generated by the operating system** based on the language code and **the configured label will be disregarded**. (e.g. "eng" --> "English" (if the device language is English; "eng" --> "Engels", if the device language is Dutch). If an invalid language code is specified, the system will use that one as label. (e.g. "MyCustomLanguageCode" --> "MyCustomLanguageCode")
4. The `isDefault: true` setting will be not taken into account on sideloaded TextTracks as it could lead to invalid source (if the stream already contains default subtitles). Enabling the desired sideloaded subtitle can be achieved via `ADD_TRACK` listener.

```swift
theoplayer.textTracks.addEventListener(type: TextTrackListEventTypes.ADD_TRACK) { ev in
    var texttrack = ev.track as! TextTrack
    if texttrack.language == "sideloaded_language_code" {
        tt.mode = .showing
    }
}
```

5. Loading thumbnail metadata through sideloaded WebVTT subtitles is not supported.

## Setting a time offset

It is possible to shift the presentation of the cues by using the extended `SSTextTrackDescription` class instead of `TextTrackDescription`. It will provide an additional property `vttTimestamp` which allows to specify a [X-TIMESTAMP-MAP](https://datatracker.ietf.org/doc/html/draft-pantos-http-live-streaming-22#section-3.5).

The X-TIMESTAMP-MAP is optional and can be omitted from the WebVTT file and in general, it is not required. It is **only necessary if you use a WEBVTT file inside an HLS subtitle rendition** and you try to achieve subtitle synchronization. And this is exactly the way how this connector operates.

The APIs below provide a way of adding or modifying the timestamp in case it is required by **mapping the PTS** (e.g. from a video rendition) **to a local time within the WEBVTT** file.

When converting different formats to WebVTT, this module does not add the timestamp by default.

The API usage remains mostly the same, with the exception of adding the timestamp:

```swift
public static var sourceWithSideloadedTextTrack : SourceDescription {
    let typedSource = TypedSource(src: "https://sourceURL.com/manifest.m3u8, type: "application/x-mpegurl")
    let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
    textTrack.vttTimestamp = .init(pts: "900000", localTime: "00:00:00.000")
    return SourceDescription(source : typedSource, textTracks :[textTrack])
}
```

```swift
theoplayer.setSourceWithSubtitles(source: sourceWithSideloadedTextTrack)
```

If the source WebVTT file specified in the `SSTextTrackDescription` already contains the X-TIMESTAMP-MAP timestamp, then it can be accessed by using the `extractSourceTimestamp` method:

```swift
let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
textTrack.extractSourceTimestamp { timestamp, error in
    print(timestamp.pts, timestamp.localTime)   // outputs the values from "https://sideloadedurl.com/subtitle.vtt"
}
```

**Note:** The `extractSourceTimestamp` method does not set the `vttTimestamp` property, but only reads the timestamp value from the source. You will need this if you want to modify the timestamp according to the initial values.

### More examples:

A sample WEBVTT file:

```text
WEBVTT

1
00:00:11.000 --> 00:00:12.000
- Never drink liquid nitrogen.

2
00:00:13.000 --> 00:15:00.000
- It will perforate your stomach.
- You could die.
```

Using the sample file mentioned above, if your PTS is `900000` in the video rendition, then mapping `900000` to `00:00:00.000` will show the first subtitle cue exactly when you would expect it, at 11 seconds in the movie.

```swift
let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
textTrack.vttTimestamp = .init(pts: "900000", localTime: "00:00:00.000")
```

#### (Experimental) Shifting the presentation of the cues forward (later) by 5 seconds.

You can achieve this by adding values to the first digit of the PTS timestamp with localTime set to 0:

```swift
let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
// we assume here that the PTS in the video rendition is 900000, so 900000 + 500000 = 1400000
textTrack.vttTimestamp = .init(pts: "1400000", localTime: "00:00:00.000")
```

The timestamp is relative to the localTime, so the following settings will cancel each other out:

```swift
let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
textTrack.vttTimestamp = .init(pts: "1400000", localTime: "00:00:05.000")
```

#### (Experimental) Shifting the presentation of the cues backwards (earlier) by 5 seconds.

You can achieve this by subtracting values to the first digit of the PTS timestamp with localTime set to 0:

```swift
let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
// we assume here that the PTS in the video rendition is 900000, so 900000 - 500000 = 400000
textTrack.vttTimestamp = .init(pts: "400000", localTime: "00:00:00.000")
```

or set the localTime to 5 seconds while keeping the timestamp value the same:

```swift
let textTrack = SSTextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: false, kind: .subtitles, label:"Label", format: .WebVTT)
// we assume here that the PTS in the video rendition is 900000
textTrack.vttTimestamp = .init(pts: "900000", localTime: "00:00:05.000")
```

**Note:** Every 100000 of PTS timestamp results in roughly 1 second in time mapping. Use this carefully as it is not officially documented.

#### Warnings

1. You should always use HLS subtitle rendition-compliant WEBVTT files which are in sync with your streams and you should not be using the time-shifting functionality.
2. Shifting cues backwards is only possible until the timestamp of the first cue (e.g. if your first cue has to be rendered at 10 sec, you should not shift the subtitle by 15 sec).
3. Shifting forward is possible, but considered as hack, and it is not a specification-compliant manifest entry. Use it at your own risk!

## Automatic synchronization

In case the presentation timestamp is not known, or it cannot be obtained, the `automaticTimestampSyncEnabled` property can be enabled to estimate the value of the PTS and automatically set the X-TIMESTAMP-MAP in the WEBVTT file. This property is defined on the class `SSTextTrackDescription`. Since the value is calculated retrospectively, it will cause a re-toggle of the enabled text track. This might cause a brief flash when a cue is present while the syncing takes effect.

## Caching

The caching feature of this connector allows you to download a source alongside a sideloaded subtitle to store it locally on the device and play it offline. To make this happen, the connector provides an API extension.

All that is needed is a source with a text track description:

```swift
public static var sourceWithSideloadedTextTrack: SourceDescription {
    let typedSource = TypedSource(src: "https://sourceURL.com/manifest.m3u8, type: "application/x-mpegurl")
    let textTrack = TextTrackDescription(src: "https://sideloadedurl.com/subtitle.vtt", srclang: "language_code", isDefault: true, kind: .subtitles, label: "Label", format: .WebVTT)
    return SourceDescription(source: typedSource, textTracks: [textTrack])
}
```

and to call the aforementioned API which creates a new caching task, and finally calling the start method:

```swift
let parameters = CachingParameters(expirationDate: .distantFuture)
let task = THEOplayer.cache.createTaskWithSubtitles(source: sourceWithSideloadedTextTrack, parameters: parameters)
task?.start()
```

For more information on how to implement offline playback with caching, please refer [to our guide](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Offline-Playback/Guides/howto-offline-stream-caching).

### Limitations

1. Caching is only available on iOS.

---

# THEOplayer 🤝 Uplynk

THEOplayer-Connector-Uplynk for iOS provides an integration between the THEOplayerSDK and the Uplynk CMS. It allows the `THEOplayerSDK` to playback uplynk sources.

For example xcode projects with this connector see [Uplynk-Examples](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/examples.md).

## Installation

### [Swift Package Manager](https://swift.org/package-manager/)

1. In Xcode, install the THEOplayer iOS-Connector package by navigating to **File > Add Packages**
2. In the prompt that appears, select the iOS-Connector GitHub repository: `https://github.com/THEOplayer/iOS-Connector`
3. Select the version you want to use.

> the Uplynk connector is available for versions >= 8.11 only.

4. Choose the Connector libraries you want to include in your app.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.

2. Use a [local override](https://developer.apple.com/documentation/xcode/editing-a-package-dependency-as-a-local-package) of the `theoplayer-sdk-ios` package by selecting the folder `../../Helpers/TheoSPM/theoplayer-sdk-ios` in Finder and dragging it into the Project navigator of your Xcode project.

3. Place your custom THEOplayerSDK.xcframework at `../../Helpers/TheoSPM/theoplayer-sdk-ios/THEOplayerSDK.xcframework`. (It is also possible to place your xcframework somewhere else. In that case make sure to update the [Package.swift](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoSPM/theoplayer-sdk-ios/Package.swift) manifest inside the your local override so that it points to your custom THEOplayer build)

4. If Xcode complains about a missing xcframework

   1. Choose `File` > `Packages` > `Reset Package Caches` from the menu bar.
   2. If it is still not working, make sure to remove any `THEOplayerSDK.xcframework` inclusions that you manually installed before installing this THEOplayer-Connector-Uplynk package.

### [Cocoapods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add the Uplynk connector pods that you want to use in your app: `pod 'THEOplayer-Connector-Uplynk'`
3. Install the pods using `pod install` , then open your `.xcworkspace` file to see the project in Xcode.

To support custom feature builds of THEOplayerSDK perform the following steps:

1. Clone this repository to your computer.
2. Use a [local override](https://guides.cocoapods.org/using/the-podfile.html#using-the-files-from-a-folder-local-to-the-machine) of the `THEOplayerSDK-basic` pod by adding the following line to your projects Podfile: `pod 'THEOplayerSDK-basic', :path => 'iOS-Connector/Helpers/TheoPod'` and make sure the path points to the [TheoPod folder](https://github.com/THEOplayer/iOS-Connector/blob/-/Helpers/TheoPod).

## Related articles

Learn more about Uplynk and how to use the connector in the following list of articles:

* [Introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/introduction.md): this article provides information on what Uplynk provides as a service.
* [Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/preplay.md): this article provides information on how to configure a Uplynk source.
* [Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/ads.md): this article provides information on which APIs can be leveraged to track and enhance the ad-viewing experience.
* [Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/ping.md): this article provides information on how to leverage the Ping service and which THEOplayer APIs you should use.

---

# Introduction

THEOplayer and Uplynk are partners in the streaming industry. The [Uplynk Platform](https://www.uplynk.com/) offers services like encoding, transcoding, server-side ad-insertion, a CDN and more.

> Uplynk was previously known as EdgeIO or Verizon Media. The iOS and Android connector will refer to the new name which is Uplynk.

Uplynk offers services which can enhance the API, UI and UX of video players and applications. The most popular services are called Preplay, Ping and Asset Info. THEOplayer integrates these services so that developers and viewers can benefit from them.

For example,

* Viewers can skip over ads;
* Viewers can see when an ad is playing (and stopping);
* Developers can define the behavior when viewers try to seek over an ad;
* Developers can query metadata to render a playlist in their application.

A live demo of THEOplayer's integration of Uplynk on the Web is available [here](https://cdn.theoplayer.com/demos/verizon-media/index.html).

Once the connector is added to your project, you can import it like so:

```swift
import THEOplayerConnectorUplynk
```

To instantiate the connector, we first need to create a configuration for it, to describe how the connector should be behave when it comes to Ads:

```swift
let uplynkConfiguration = UplynkConfiguration(defaultSkipOffset: ..., skippedAdStrategy: ...)
```

> `defaultSkipOffset` describes how many seconds the user has to wait before an ad is skippable. `skippedAdStrategy` controls how the connector behaves when seeking over ads. There are three values: `playAll`, `playLast` and `playNone`. The first option forces playback of all the unwatched ads before the seek point. `playLast` forces playback of the last ad before the seek point.

We can now instantiate the `UplynkConnector` provided that you have an available `THEOplayer` instance:

```swift
let connector = UplynkConnector(player: yourTHEOplayer,
                                configuration: uplynkConfiguration
                                eventListener: nil)
```

Here, the event listener refers to an implementation of the `UplynkEventListener` protocol which gives the client access to the Uplynk API responses. We will touch on what these responses are in the following articles. If you are not interested in receiving those callbacks, you can pass `nil` like above.

For more information on the connector and available APIs, continue to read on the pages below.

* [Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/preplay.md): this article provides information on how to configure a Uplynk source.
* [Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/ads.md): this article provides information on which APIs can be leveraged to track and enhance the ad-viewing experience.
* [Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/ping.md): this article provides information on how to leverage the Ping service and which THEOplayer APIs you should use.

---

# Preplay

This article explains how to leverage the Uplynk Preplay API through THEOplayer. This API allows developers to pre-integrate with Uplynk Preplay service.

Uplynk users can use an API (i.e. Preplay) to generate a streaming playlist given 1 or more assets or advertisements. The back-end of Uplynk stitches the content together and allows for server-side ad-insertion (SSAI) when applicable. This document describes how THEOplayer users should configure their source to leverage this Preplay service.

Assumptions:

* THEOplayer assumes the availability of the Preplay API and Uplynk content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
* THEOplayer assumes that developers who are interested in this feature have a basic understanding of the Preplay API. Uplynk documents this service at <https://api-docs.uplynk.com/#Develop/Preplayv2.htm>
* THEOplayer assumes that developers provide correct asset identifiers, as well as the proper content protection level.

## Stream Configuration (without ads)

The examples below demonstrate how to configure a stream through the Uplynk connector.

We start by creating an `UplynkSSAIConfiguration` object that describes how to configure an Uplynk source.

```swift
    let ssaiConfiguration = UplynkSSAIConfiguration(
                                id: .asset(ids: [ your list of asset IDs]),
                                assetType: .asset or .channel,
                                prefix: "https://content.uplynk.com", 
                                preplayParameters: [ Dictionary of parameters ]
                                contentProtected: true or false)
```

* `id`: The ID field identifies the asset. Instead of a single string, developers can also specify an array of asset IDs as strings, which will be stitched into a continuous stream. Assets can also be identified by `externalIds` and a `userId`. In that case, you can instantiate a `.external(ids: [list of channel IDs], userID: your user ID)` instead.

* `preplayParameters`: The `preplayParameters` object should have string-key-string-value combinations, which will be used as query parameters for the Preplay API call. Nested objects are not supported.

* `contentProtected`: Boolean value which will internally set any necessary content-protection information. No content-protection details have to be specified by the customer.

* **A Preplay request must include all parameters defined within the playback request, hence these parameters must be included in the THEOplayer source**. This request must also include a digital signature if the 'Require a token for playback' option is enabled in the back-end on the corresponding live channel. (See also : [Signing a Playback URL Tutorial](https://docs.uplynk.com/docs/sign-playback-url))

* Uplynk specific documentation on the available playback URL query parameters can be found on the Uplynk documentation site under [Customizing Playback via Parameters](https://docs.uplynk.com/docs/customize-playback-via-parameters)

* Some parameters can be excluded from the digital signature calculation. These parameters may enable certain use cases (e.g. DVR) and would for this reason be excluded from the digital signature.

Now, you can create a typed source, and attach the `UplynkSSAIConfiguration` object to the `ssai` property of the source

```swift
// Swift examples
let myTypedSource = TypedSource(src: "",
                                type: "application/x-mpegurl",
                                ssai: ssaiConfiguration)

let sourceDescription = SourceDescription(source: typedSource)
yourTHEOplayer.source = sourceDescription
```

## Stream Configuration (with ads)

Ad specific parameters can be passed in the `preplayParameters` argument of the `UplynkSSAIConfiguration`. An example of that is:

```swift
    let ssaiConfiguration = UplynkSSAIConfiguration(
                                id: ...
                                assetType: ...,
                                prefix: ..., 
                                preplayParameters: [
                                    // Parameters here should specify the necessary ad parameters for the Preplay API
                                    "ad.param1": "param_val1",
                                    "ad.param2": "param_val2" 
                                ],
                                contentProtected: ...)
```

## Preplay Response

THEOplayer automatically interprets the response returned by the Preplay service. However, if a developer wants to perform their own logic with the Preplay API response, then they can register their implementation of the `UplynkEventListener` protocol through the `UplynkConnector` constructor. There, you can get access to the `PrePlayLiveResponse` or `PrePlayVODResponse` objects through:

```swift
    func onPreplayLiveResponse(_ response: PrePlayLiveResponse) { ... }
    func onPreplayVODResponse(_ response: PrePlayVODResponse) { ... }
```

## Using Tokens

Uplynk users often leverage URL signatures (i.e. tokens) to further secure their content -- on top of AES-128 encryption or studio DRM.

A token is (typically) generated on back-end using an API key and a set of parameters. (The documentation at [Signing a Playback URL Tutorial](https://docs.uplynk.com/docs/sign-playback-url) describes this process.) This set of parameters should also be passed along to the `playbackURLParameters` in a `UplynkSSAIConfiguration`.

If you do not configure the `playbackURLParameters` correctly in relation to your signature parameters, then the Preplay request made by THEOplayer will most likely return an invalid Preplay response, preventing THEOplayer from setting up your stream.

# Related articles

* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/ads.md)
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/ping.md)

---

# Uplynk Ads

Uplynk offers support for server-side ad-insertion or in-short SSAI.

This article explains how to use the THEOplayer's Ads APIs to interact with the Uplynk Ads service

## Global Configuration

The examples below demonstrate how to pass along global configuration for Uplynk Ads in the Connector.

```swift
let uplynkConfiguration = UplynkConfiguration(defaultSkipOffset: ..., skippedAdStrategy: ...)
```

> `defaultSkipOffset` describes how many seconds the user has to wait before an ad is skippable. `skippedAdStrategy` controls how the connector behaves when seeking over ads. There are three values: `playAll`, `playLast` and `playNone`. The first option forces playback of all the unwatched ads before the seek point. `playLast` forces playback of the last ad before the seek point.

## Uplynk Ads API

Specifying a source which contains server-side ads configured through Uplynk will have the THEOplayer instance report such ads through its Ads API.

Users can use the THEOplayer Ads events to interact with Uplynk Ads:

```swift
 func addAdsEventListeners() {
        listeners["ADD_AD_BREAK"] = player.ads.addEventListener(type: AdsEventTypes.ADD_AD_BREAK) { [weak self] in
            os_log("--------------------------------------->")
            os_log("--> Add Ad Break Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_BREAK_BEGIN"] = player.ads.addEventListener(type: AdsEventTypes.AD_BREAK_BEGIN) { [weak self] in
            os_log("--------------------------------------->")
            os_log("--> Ad break begin Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_BREAK_END"] = player.ads.addEventListener(type: AdsEventTypes.AD_BREAK_END) { [weak self] in
            os_log("--------------------------------------->")
            os_log("--> Ad break end Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["ADD_AD"] = player.ads.addEventListener(type: AdsEventTypes.ADD_AD) {
            os_log("--------------------------------------->")
            os_log("--> Add Ad Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_BEGIN"] = player.ads.addEventListener(type: AdsEventTypes.AD_BEGIN) {
            os_log("--------------------------------------->")
            os_log("--> Ad Begin Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_FIRST_QUARTILE"] = player.ads.addEventListener(type: AdsEventTypes.AD_FIRST_QUARTILE) {
            os_log("--------------------------------------->")
            os_log("--> Ad First Quartile Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_MIDPOINT"] = player.ads.addEventListener(type: AdsEventTypes.AD_MIDPOINT) {
            os_log("--------------------------------------->")
            os_log("--> Ad Mid Point Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_THIRD_QUARTILE"] = player.ads.addEventListener(type: AdsEventTypes.AD_THIRD_QUARTILE) {
            os_log("--------------------------------------->")
            os_log("--> Ad Third Quartile Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_END"] = player.ads.addEventListener(type: AdsEventTypes.AD_END) {
            os_log("--------------------------------------->")
            os_log("--> Ad End Event occured: \($0)")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_ERROR"] = player.ads.addEventListener(type: AdsEventTypes.AD_ERROR) {
            os_log("--------------------------------------->")
            os_log("--> Ad Error Event occured: \($0.error ?? "")")
            os_log("--------------------------------------->")
        }
        
        listeners["AD_SKIP"] = player.ads.addEventListener(type: AdsEventTypes.AD_SKIP) {
            os_log("--------------------------------------->")
            os_log("--> Ad Skip Event occured: \($0)")
            os_log("--------------------------------------->")
        }
```

Users can also skip Ads through the `skip` API in THEOplayer:

```swift
player.ads.skip()
```

> Calling the `player.ads.skip()` function on a live stream will not have any effect.

## Related articles

* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/preplay.md)
* [Uplynk - Ping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/ping.md)

---

# Ping

This article explains how to use the Uplynk Ping API.

The Ping API for Uplynk allows users of their CMS to receive updates about SSAI on running live-streams or provide better playback position beaconing for Video on demand. The Ping API is used together with the Preplay API because the latter provides a session to be used with the Ping API.

This connector allows the user to specify a source for Preplay, and enable or disable certain features of the Ping API. The player will then perform these Ping calls internally, without the user having to write their own Ping client. The response of Ping calls will be exposed for external handling if necessary.

**Feature Assumptions** We assume the SSAI information returned through the Ping API to be of a certain format, which we compile from examples and our own testing. The documentation does not define the structure of this payload very well and only states that it is "like the object returned in Preplay requests", though the formats are not a one-on-one match.

**Assumptions**

* THEOplayer assumes the availability of the Ping API and Uplynk content servers to be 100%, since these identify and provide the necessary streams for playback with this feature.
* THEOplayer assumes application developers have a notion of the Ping API, namely any extra parameters to be appended to the requests to Uplynk (e.g. for correct ad insertion). As documented in <https://api-docs.uplynk.com/#Develop/Preplayv2.htm>
* THEOplayer assumes application developers provide proper ID's of the Assets they want to play back, as well as the proper content protection level.

## Configuring Ping

The connector allows specification of the desired features of the Ping API as listed [in the official Ping API documentation](https://api-docs.uplynk.com/#Develop/Preplayv2.htm#Features).

In the THEOplayer-Connector-Uplynk, these features can be activated through the `uplynkPingConfiguration` property in the SSAI configuration:

```swift
let ssaiConfiguration = UplynkSSAIConfiguration(
                                id: .asset(ids: [ your list of asset IDs]),
                                assetType: .asset or .channel,
                                prefix: "https://content.uplynk.com",
                                preplayParameters: [ Dictionary of parameters ]
                                contentProtected: true or false,
                                uplynkPingConfiguration: UplynkPingConfiguration(adImpressions: true or false, // Defaults to false
                                                                                 freeWheelVideoViews: true or false, // Defaults to false
                                                                                 linearAdData: true or false)) // Defaults to false
```

By default, the ping API is disabled for all sessions. To enable it, the `ad.cping=1` parameter must be added to your preplay request. In addition to enabling the API, you must also notify the server of the features you want to support for this viewing session. To specify which features you'd like to enable, you add the`ad.pingf={some value}` parameter to the playback token. The value of the parameter is detailed in the official Ping Documentation.

Ping is enabled and `ad.pingf` is set to a proper value when the `uplynkPingConfiguration` has one or more of the `adImpressions`, `freeWheelVideoViews` or `linearAdData` configuration set to `true`.

If you attempt to call the API without passing in the `ad.cping` parameter, you can throw off the server's ability to make ad event calls correctly.

Sample Preplay URL with `ad.cping`:

`https://content.uplynk.com/preplay/cc829785506f46dda4c605abdf65392b.json?ad=adserver&ad.cping=1&ad.pingf=3`

The default value for `uplynkPingConfiguration` has `adImpressions`, `freeWheelVideoViews` and `linearAdData` all set to false, ie, Ping API will not be used.

## Ping requests

When the Ping API is enabled, THEOplayer will call the Ping URL located at:

```text
{prefix}/session/ping/{sessionID}.json?v=3&pt={currentTime}&ev={event}&ft={freeWheelTime}
```

Where:

* `{prefix}`: Is the prefix URL from the Preplay response.

* `{sessionID}`: Is the session ID from the Preplay response.

* `{currentTime}`: Mandatory parameter. This is the current player time in seconds.

* `{event}`: Is the current Ping event. An event should only be passed when playback starts or when a viewer seeks to a new position. Valid values are:

  * **start**: Pass this event, along `withpt=0`, when the player starts playback. This lets the server know where playback starts and allows the server to fire start events as needed.
  * **seek**: Pass this event when a viewer seeks. This resets the timeline to prevent inadvertently firing events for skipped ads.

* `{freeWheelTime}`: Indicates the playback position, in seconds, right before a viewer seeks to a different position in the timeline. This property is mandatory when the freeWheelVideoViews is used.

## Ping Response

When performed correctly, a Ping request will return a JSON response which is decoded into a `PingResponse`.

The ping response includes:

* next\_time: A new beacon will be scheduled when the player's currentTime passes this value. In case the value is -1, no further beacons will be scheduled.

* ads: Will be interpreted in order to create AdBreak's and Ad's as well as expose Ad information through the THEOplayer instance's `ads.scheduledAds` property.

  * ads.breaks.timeOffset will be used in order to determine the start time of the ad break (in seconds).

  * ads.breaks.ads will be looped in order to extract the list of ad's in an UplynkAdBreak:

    * apiFramework - Indicates the API Framework for the ad (e.g., VPAID).
    * companions - List of companion ads that go with the ad.
    * mimeType - Indicates the ad's Internet media type (aka mime-type)
    * creative - If applicable, indicates the creative to display.
    * events - Object containing all of the events for this ad. Each event type contains an array of URLs.
    * width - If applicable, indicates the width of the creative.
    * height - If applicable, indicates the height of the creative.
    * duration - Indicates the duration, in seconds, of an ad's encoded video.
    * extensions - Contains the custom set of VAST extensions returned by the ad server.
    * fwParameters - If the ad response provided by FreeWheel contains creative parameters, they will be reported as name-value pairs within this object.

  * ads.breaks.duration - Indicates the duration of the ad break.

  * ads.breaks.position - Indicates the position of the ad break. Valid values are: preroll | midroll | postroll | pause | overlay.

  * ads.breaks.events - Object containing all of the events for this ad break.

The ping response can be retrieved from the `onPingResponse(:)` delegate method by setting an `eventListener` to the `UplynkConnector` instance.

| Delegate method | Description                             | Arguments                                       |
| --------------- | --------------------------------------- | ----------------------------------------------- |
| onPingResponse  | Fired when a Ping response is received. | `response` argument contains the `PingResponse` |

## Related articles

* [Uplynk - Preplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/preplay.md)
* [Uplynk - Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/ios/uplynk/ads.md)

---

# THEOPlayer 🤝 Uplynk Samples

A sample application that illustrate how to use the connector:

* [Sample using **Cocoapods**](https://github.com/THEOplayer/iOS-Connector/blob/-/Code/Uplynk-Examples/Cocoapod) (requires Cocoapods installation through terminal)

---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## Unreleased

## \[10.8.0.1] - 2026-01-20

### Fixed

* SideloadedSubtitle
  * Fixed an issue where a bad http response code for subtitle sources would cause playback issues.

## \[10.8.0] - 2026-01-15

### Added

* SideloadedSubtitle

  * Added support for simultaneous multi-source caching with sideloaded subtitles. Previously there was a limitation of caching only a single task at a time.
  * Added support to make a sideloaded subtitle selected for caching by default. Use the `isDefault` property in `SSTextTrackDescription` or `TextTrackDescription`. Only one default track can be added.

### Fixed

* Conviva

  * Fixed an issue where the initial metadata passed to the convivaConnector was not persistent across Conviva sessions.
  * Fixed an issue where the session's assetName was not configurable by setContentInfo, which has higher precedence than source.metadata.title.
  * Fixed an issue with the encodingType, where sometimes the encodingType of the previous session was reported

## \[10.7.0] - 2025-12-18

### Changed

* Conviva
  * Bumped the Conviva SDK dependency to 4.2.4.

### Fixed

* SideloadedSubtitle
  * Fixed an issue where the stream would not play if an invalid subtitle source is passed and activated.

## \[10.4.0] - 2025-11-05

### Fixed

* Conviva
  * Fixed an issue where the session was automatically started with a stopAndStartNewSession request, even when the player was in a paused state.

### Changed

* Conviva
  * Report droppedFrames and renderedFramerates from player metrics, making the AVPlayer accesslog usage obsolete.
* Nielsen
  * Bumped minimum Nielsen SDK Dependency to 10.0.0

### Added

* Conviva

  * Report average bitrate from activeQualityChange event.
  * Report streamActivityMonitorId from theoads AdDescription and GoogleDAIConfiguration.

## \[10.2.0] - 2025-10-09

### Added

* Conviva

  * Pass podTechnology as custom field in reportAdBreakStarted.
  * Report DRM events.
  * Report intentToFallback event to Conviva as custom event.
  * Report encoding\_type (HLS or HESP) to conviva
  * Report cdn for THEOlive sources to conviva

### Fixed

* SideloadedSubtitle
  * Fixed an issue where enabling a `TextTrack` on the `ADD_TRACK` event would cause an error.

## \[10.0.0] - 2025-09-12

### Removed

* Conviva
  * Removed the `setErrorCallback`. The same behaviour can be achieved in THEOplayer 10 by calling `addEventListener` on THEOplayer with a type of `PlayerEventTypes.ERROR`

## \[9.6.1] - 2025-06-23

### Fixed

* Conviva
  * Fixed an issue where the ad duration of a THEOad was not reported.

## \[9.3.2] - 2025-05-13

### Fixed

* Conviva
  * Fixed a crash on tvOS, caused by a change to the player reference count.

## \[9.1.1] - 2025-04-15

### Fixed

* Conviva
  * Fixed a memory leak on iOS, caused by a dangling bitrate change observer on the AppEventForwarder.

## \[9.0.0] - 2025-04-03

### Added

* Conviva
  * Added average bitrate reporting

### Fixed

* Conviva
  * Improved the VPF detection for iOS and tvOS.

### Removed

* Conviva

  * Removed Objective-C API support.

* Yospace

  * Removed Objective-C API support.

## \[8.13.0] - 2025-03-13

### Fixed

* Conviva
  * Fixed an issue where the bitrate change events were reported to the incorrect Conviva endpoint.

## \[8.12.0] - 2025-02-26

### Changed

* Nielsen
  * Allow bumping minor and patch versions of the Nielsen SDK dependency.

## \[8.11.1] - 2025-02-21

### Added

* Uplynk
  * Added Uplynk integration with THEOplayer to allow integrating Uplynk CMS into THEOplayer.

## \[8.8.0] - 2025-01-02

### Added

* Comscore

  * Added `usagePropertiesAutoUpdateMode` and `usagePropertiesAutoUpdateInterval` to `ComScoreConfiguration`.
  * Exposed `notifyUxActive`, `notifyUxInactive`, `notifyEnterForeground` and `notifyExitForeground` methods.

## \[8.7.0] - 2024-12-18

### Added

* Conviva
  * Added compatibility for reporting playback bitrate metrics with THEOlive sources.

### Fixed

* Conviva
  * Fixed an issue where the playback bitrate metrics were not reported.

## \[8.0.1.1] - 2024-09-18

### Fixed

* Conviva
  * Fixed an issue where the vpfDetector was not firing a VPF due to a missing player reference.

## \[7.10.0] - 2024-08-13

### Fixed

* Conviva

  * Fixed an issue where multiple fatal errors were reported to the Conviva backend, resulting in multiple sessions being created.
  * Fixed an issue where VPF was not detected for VOD when the player has enough buffered data to get passed the detection interval.

## \[7.9.0] - 2024-08-01

### Fixed

* Comscore
  * Fixed an issue where converting `Double.infinity` values would crash on some analytics events.

## \[7.8.0] - 2024-07-18

### Added

* Yospace
  * Added Yospace integration with THEOplayer to allow playback of server-side ad inserted streams.

## \[7.5.0] - 2024-06-06

### Fixed

* SideloadedSubtitle
  * Fixed an issue that prevented `automaticTimestampSyncEnabled` to sync cues properly.

## \[7.4.0] - 2024-05-23

### Fixed

* SideloadedSubtitle
  * Prevent using HTTP redirects on media requests.

## \[7.3.0] - 2024-05-08

### Added

* SideloadedSubtitle
  * Added `automaticTimestampSyncEnabled` API on `SSTextTrackDescription`.

### Fixed

* Conviva

  * Fixed an issue where reported contentInfo was not cleaned up correctly when starting a new viewing session.
  * Fixed an issue where c3.ad.technology was reported as an integer value instead of a string.

## \[7.2.0] - 2024-04-24

### Fixed

* SideloadedSubtitle

  * Fixed an issue where playlists that contain urls with percentEncoding got an extra percentEncoding pass resulting in erronneous urls.
  * Fixed an issue where variant playlists with additional tags between EXTINF and the segment url, where not properly processed.

## \[7.0.0] - 2024-04-03

### Changed

* Conviva

  * Aligned the API to THEOplayer's Android and Web Conviva connectors.
  * Shield Conviva analytics endpoints. All data reporting now happens via the API.
  * Removed the 'report' methods for AssetName and ViewerID. These are replaced by using the setcontentInfo method (for viewerId) and by passing metadata to the sources (for AssetName).

### Added

* Conviva
  * VPF (Video Playback Failure) detection

## \[6.8.1] - 2024-01-18

### Fixed

* Conviva
  * Updated deprecated name for access log notification to fix broken bitrate reporting.
* Comscore
  * Prevent Comscore connector crash when reporting ad info for a DAI stream

### Changed

* Conviva
  * Dropped the protocol dependency for the external event dispatcher.

## \[6.1.1] - 2023-10-06

### Fixed

* SideloadedSubtitle
  * Add iOS 17 compatibility

## \[6.0.1] - 2023-09-27

### Fixed

* SideloadedSubtitle
  * adjust content string encoder in transformer

## \[6.0.0] - 2023-09-26

### Fixed

* SideloadedSubtitle

  * urlDecode the contentUrl string before downloading the track
  * resolve relative uri params in quality playlists

## \[5.11.0] - 2023-09-14

### Fixed

* SideloadedSubtitle
  * Take into account playlist redirects

## \[5.9.1] - 2023-08-24

### Added

* SideloadedSubtitle
  * Sideloaded subtitle connector now supports: SRT text tracks, specifying a time offset and caching for offline playback.

## \[5.7.0] - 2023-07-28

### Added

* Conviva
  * Added additional Ad metadata properties

## \[5.5.1] - 2023-06-29

### Fixed

* Conviva
  * Reset stored bitrate value on source changes

### Added

* Conviva
  * Send c3.csid and contentAssetName as adMetadata on AdBegin event

## [5.4.2](https://github.com/THEOplayer/iOS-Connector/compare/5.2.0...5.4.2) - 2023-06-21

### Fixed

* Conviva
  * Reporting bitrates after start and stop new session.

## [5.2.0](https://github.com/THEOplayer/iOS-Connector/compare/5.1.0...5.2.0) - 2023-05-31

### Added

* SideloadedSubtitle
  * Added new connector to sideload subtitles on tvOS and iOS

## [5.1.0](https://github.com/THEOplayer/iOS-Connector/compare/5.0.5...5.1.0) - 2023-05-15

### Fixed

* Conviva

  * Do not use ads API when there is no ad integration on the THEOplayer
  * Fix example with custom built framework

## [5.0.5](https://github.com/THEOplayer/iOS-Connector/compare/5.0.4...5.0.5) - 2023-04-27

### Added

* Conviva
  * Reporting bitrates for ads (0af67a3c)

### Fixed

* Comscore
  * Prevent crash that sometimes happened during playback (75e9eacb)
* Conviva
  * Fixed a bug that would cause the connector to not report bitrates when using manifest interception on the THEOplayer via the developer settings. (6ee5e519)

### Changed

* Conviva

  * Report bitrates from iOS in kbps to conviva (a231831a)
  * Do not report empty sessions (4257d803)

## [5.0.4](https://github.com/THEOplayer/iOS-Connector/compare/5.0.3...5.0.4) - 2023-04-21

### Changed

* Conviva
  * Report false as default for `CIS_SSDK_METADATA_IS_LIVE` (6bb45c17)

## [5.0.3](https://github.com/THEOplayer/iOS-Connector/compare/5.0.2...5.0.3) - 2023-04-17

### Added

* Conviva
  * Report ad resourceURI’s (a6b158d9)

## [5.0.2](https://github.com/THEOplayer/iOS-Connector/compare/5.0.1...5.0.2) - 2023-04-14

### Added

* Conviva

  * Report rendered framerate (c5e272d1)
  * Report ended when deinitialised (f49d2bb0)
  * Report network errors (02930576)

## [5.0.1](https://github.com/THEOplayer/iOS-Connector/compare/5.0.0...5.0.1) - 2023-04-13

### Changed

* Conviva
  * Do not report duration if no source is set (64db6846)

## [5.0.0](https://github.com/THEOplayer/iOS-Connector/compare/4.6.0...5.0.0) - 2023-04-07

### Fixed

* Comscore

  * Call notifyPlay when playback resumes after seek (9420ec5f)
  * Don't pause the player on background move (df92e0ff)

### Changed

* Comscore

  * Changed THEOplayer cocoapod dependency from `THEOplayerSDK-basic` to `THEOplayerSDK-core`
  * Changed minimum version requirement of ComScore from `6.7.1` to `6.10.0`

* Nielsen
  * Changed THEOplayer cocoapod dependency from `THEOplayerSDK-basic` to `THEOplayerSDK-core`

* Conviva
  * Changed THEOplayer cocoapod dependency from `THEOplayerSDK-basic` to `THEOplayerSDK-core`

## [4.6.0](https://github.com/THEOplayer/iOS-Connector/compare/4.5.1...4.6.0) - 2023-04-05

### Added

* Conviva

  * Report player framework info for ads (ececcab0)
  * Read duration of ads from THEOplayer instance (54a51109)

### Changed

* Conviva
  * Report a default value of `"NA"` for `CIS_SSDK_METADATA_ASSET_NAME` (6c4ba003)

* Nielsen

  * Only report ended if played to Nielsen (639c08c1)
  * Remove length metadata reporting (c53642b9)

### Removed

* Conviva
  * Removed backgrounding logs from stdout (ccb64d05)

## [4.5.1](https://github.com/THEOplayer/iOS-Connector/compare/4.5.0...4.5.1) - 2023-03-30

### Fixed

* Comscore
  * Fixed a crash that happened when removing the connector (36c30950)

### Removed

* Nielsen

  * removed the following DCR reports (cc14c08c):

    * playheadPosition
    * play
    * loadMetadata

## [4.5.0](https://github.com/THEOplayer/iOS-Connector/compare/4.4.0...4.5.0) - 2023-03-24

### Added

* Comscore
  * Added Comscore connector

## [4.4.0](https://github.com/THEOplayer/iOS-Connector/compare/4.3.1...4.4.0) - 2023-03-21

### Added

* Nielsen
  * Readme (62afa92c)

### Changed

* Nielsen
  * Use `NielsenAppSDK` and `NielsenTVOSAppSDK` dependencies for cocoapod instead of `NielsenAppSDK-XC` (ded687d0)

## [4.3.1](https://github.com/THEOplayer/iOS-Connector/compare/4.3.0...4.3.1) - 2023-03-17

### Added

* Nielsen

  * Report play, stop and end events (b737b336)
  * Report ID3 tags, metadata and duration changes (f4118e19)
  * Report Ad events (47ab93e6)

* Utilities
  * Shared package with utilities that can be reused for multiple connectors

## [4.3.0](https://github.com/THEOplayer/iOS-Connector/compare/4.2.0...4.3.0) - 2023-03-02

### Added

* Nielsen
  * Setup target for SPM (33b5ff6c)
* Conviva
  * Added tvOS platform to cocoapod (d4ea17dc)

### Changed

* Conviva

  * Round `CIS_SSDK_METADATA_DURATION` to closest integer (105ddf96)

  * Report metrics in milliseconds instead of seconds (105ddf96):

    * `CIS_SSDK_PLAYBACK_METRIC_PLAY_HEAD_TIME`
    * `CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED`
    * `CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED`

  * Only report non-linear ad types. (39edc330)

  * Report “NA” for `CIS_SSDK_METADATA_ASSET_NAME` when no title is provided. (90c86a4c)

  * Close session after fatal error (ce6bcd27)

  * Report `THEOplayer.version` instead of `.playerSuiteVersion` for Conviva's `CIS_SSDK_PLAYER_FRAMEWORK_VERSION` metric (9e1eb3c8)

### Removed

* Conviva
  * Removed unneeded playing report during ads (51670e42)

## [4.2.0](https://github.com/THEOplayer/iOS-Connector/compare/4.1.1...4.2.0) - 2023-02-21

### Added

* Conviva
  * Automatic reporting of `CIS_SSDK_METADATA_ASSET_NAME` from THEOplayer's `metadata.title` inside the current source's `SourceDescription` (f4c59570)

## [4.1.1](https://github.com/THEOplayer/iOS-Connector/releases/tag/4.1.1) - 2022-10-19

### Added

* Conviva connector
* Conviva-VerizonMedia connector

---

# THEOplayer React Native SDK

Dolby OptiView Player (formerly THEOplayer) is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/getting-started.md)

[Set up your first THEOplayer in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md)

## [🔌Connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native.md)

[Integrate third-party solutions with THEOplayer using our pre-built connectors.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog/react-native.md)

[Find out what's new in the OptiView Player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog/react-native.md)

## [\*️⃣API references](https://theoplayer.github.io/react-native-theoplayer/api/)

[Discover all properties and functions of THEOplayer.](https://theoplayer.github.io/react-native-theoplayer/api/)

## [![](/pr-932/img/github.svg)![](/pr-932/img/github_dark.svg)GitHub](https://github.com/THEOplayer/react-native-theoplayer)

[Browse the source code or report issues on GitHub.](https://github.com/THEOplayer/react-native-theoplayer)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

## \[10.13.0] - 26-03-27

### Fixed

* Fixed an issue on Android where the Ads API would sometimes return an empty map instead of an array when querying the list of current ads or scheduled ad breaks.
* Fixed an issue on iOS where the transition from PiP to fullscreen was not smooth.

## \[10.12.1] - 26-03-19

### Fixed

* Fixed an issue on Android where play-out of a Google DAI stream would crash the app.

## \[10.12.0] - 26-03-12

### Added

* Added `currentsourcechange` event to the player API, which is dispatched when the current source, chosen from the source description's sources, changes.
* Added `debugLogsEnabled` flag to `PlayerConfiguration` to allow enabling all debug logs from the underlying Android SDK.
* Added the `id` property to `AdBreak`, representing the identifier of the ad break.

### Fixed

* Fixed an issue on Android where the build process would pick up version from the snapshot repository instead of the release repository, causing build failures.
* Fixed an issue on iOS & Android where, when using `<StrictMode>`, the player's list of text tracks would be empty.

## \[10.11.0] - 26-03-10

### Fixed

* Fixed an issue on Android where transitioning from picture-in-picture presentation mode would fail when using Expo Router.
* Fixed an issue where the player would remove all listeners when using `<StrictMode>` on mobile platforms.

### Changed

* Updated `NativeAdBreak` to prevent iOS build failure caused by changed `AdBreak` protocol.

## \[10.10.0] - 26-02-17

### Fixed

* Fixed an issue on iOS where the `onPlayerStateSync` callback was not called from the main thread.

### Added

* Added the `DistributionLoaded` event for THEOlive.
* Added contentProtection extraction for THEOlive endpoints on iOS.

## \[10.9.0] - 26-01-29

### Fixed

* Fixed an issue on Android where the player could disrupt the layout by sending an unexpected dimension change event.
* Fixed an issue on Android where the default properties of the player's `backgroundAudioConfiguration` would not be properly applied.

### Added

* Added functionality to synchronize the player state from the native mobile players to React Native.
* Added a bypass property on iOS to control the THEOplayerView's ability to detach from its superView.
* Trigger an update for the iOS control centers (nowPlayingInfo and remoteCommands) to reflect a player state sync.

### Changed

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-theoplayer/blob/-/LICENSE) file for more information.

## \[10.8.0] - 26-01-22

### Added

* Added support on iOS to push the initial state of the player from the iOS bridge to the React native adapter.
* Added RNRepo support for Android to the example app. More info on the official [documentation](https://rnrepo.org/) page.

### Fixed

* Fixed an issue on iOS where the integrationParameters from the contentProtection section of the source were not processed correctly, resulting in failures for DRM connectors that depend on them.
* Fixed an issue on iOS where the player could crash when terminating the app while the player is backgrounded in fullscreen.
* Fixed an issue on Android where `player.ads.currentAds` would not return an array of ads due to a native error.
* Fixed an issue on Android where the player would sometimes have wrong dimensions after transitioning to fullscreen presentation mode.
* Fixed an issue on Android where the `useEMSG` property was not included when setting a TheoAds source description.

## \[10.7.1] - 26-01-06

### Added

* Added a `multiSession` property to `DRMConfiguration` to enable multi-key content on Android platforms.

## \[10.7.0] - 25-12-19

### Added

* Added a webrtc configuration property `webrtc` in `TheoLiveSource`, to enable configuring the playout delay for Millicast streams consumed through OptiView Live.

## \[10.6.1] - 25-12-18

### Fixed

* Fixed an issue on AndroidTV and FireTV devices, where pressing the center D-pad button during play-out of an ad configured with a click-through URL would cause the player to pause, without the ability to resume playback.

### Added

* Added `useExperimentalPipeline` to `CastConfiguration` for iOS, that controls the usage of an experimental, alternative implementation of the chromecast pipeline with a different feature set.

## \[10.6.0] - 25-12-02

### Added

* Added support for personalized discovery call responses by configuring the `profile` property on an OptiView Live source.

## \[10.5.1] - 25-11-28

### Added

* Support for contentProtection query parameters on THEOlive sources.
* Added `LatencyConfiguration` to `SourceDescription` for Android and Web.

### Fixed

* Fixed an issue on tvOS where unsupported pip logic was used on older tvOS target versions (< 14.0).

## \[10.5.0] - 25-11-24

### Fixed

* Fixed an issue on iOS where the scrim of an IMA ad was in a wrong position due to incorrect `safeAreaInsets`.

### Added

* Added `stopOnBackground` property to `BackgroundAudioConfiguration` to control whether playback should stop when the app goes to the background.
* Added `millicastSrc` to `TheoLiveEndpoint` for Web and Android.
* Added support for configuring query parameters that are common to multiple key system configurations. The parameters defined in `contentProtection.queryParameters` will be merged with any query parameters that are explicitly defined on a key system configuration, whereby the latter takes precedence.

### Changed

* Updated the active quality info extraction on iOS to use the activeQualityChange event data instead of player API.
* On iOS, we now also pass all available qualities and the current active quality when bridging video- and audio track data.

## \[10.4.0] - 25-11-13

### Fixed

* Fixed an issue on Android, where the app could crash when a `THEOads` error event was dispatched.
* Fixed an issue on Web, where the contents of the `reason` property of the THEOads `intenttofallback` event did not conform to its declared `PlayerError` type.

### Added

* Pass `streamActivityMonitorId` property for `THEOAdDescription` on iOS and Android.
* Added `allowLivePlayPause` and `seekToLiveOnResume` properties to `PlayerConfiguration.mediaControl` to control pausing and resuming behavior on live streams from the lockscreen controls.

### Changed

* Upgraded example app to React-Native v0.82.

## \[10.3.0] - 25-10-27

### Fixed

* Fixed an issue on Web, where adbreak related AdEvents did no longer contain the adBreak info.

### Changed

* When the player's `currentTime` is set to `Infinity` on mobile platforms, the player will seek to the live edge rather than the end of the `seekable` range.
* Added `useHttpEngine` to `PlayerConfiguration` to allow toggling the use of HttpEngine for network requests on Android.

## \[10.2.2] - 25-10-23

### Fixed

* Fixed a build issue on iOS/tvOS due to a breaking change on the THEOplayerSDK.Ad protocol in iOS SDK 10.3.0 .

## \[10.2.1] - 25-10-21

### Fixed

* Fixed an issue on web where the `<THEOplayerView>` would be re-rendered non-stop.

## \[10.2.0] - 25-10-20

### Added

* React Native THEOplayer now supports [React Compiler](https://react.dev/learn/react-compiler).
  * For Expo users: refer to the [Expo docs](https://docs.expo.dev/guides/react-compiler/) to set up React Compiler in your app.

### Fixed

* Fixed an issue on iOS where the player crashed when it was destroyed while in fullscreen.
* Fixed an issue on Android where creating a caching task with `MediaCache.createTask` would not return the created `task`.
* Fixed an issue where setting `player.theoLive.authToken = undefined` would cause a crash on Android.

### Changed

* Added `THEOplayer.theoLive` and deprecated `THEOplayer.theolive`, to be consistent with the THEOplayer SDKs for other platforms.
* Moved the `hlsDateRange` property from `SourceConfiguration` to its correct location in `TypedSource`.

## \[10.1.0] - 25-10-06

### Added

* Added an explicit clearing of the NowPlayingInfo on iOS, when the app receives a `willTerminateNotification`, to make sure all NowPlayingInfo is removed from the lock screen when an app is closed.
* Added `videoWidth` and `videoHeight` properties to `THEOplayer` containing the active video's resolution in pixels.
* Added `videoresize` player event enabling monitoring of video rendition resizes.
* Added `dimensionchange` player event enabling monitoring of player resizes. This event is set to replace the now deprecated `resize` player event.
* Added `fontPath` to `TextTrackStyle` to allow loading custom fonts from the Android assets folder.

### Fixed

* Fixed an issue on Android where play-out of Millicast sources in the example app would fail. The Android NDK version needs to be at least v28.
* Fixed an issue on Web where on older devices the `display: contents` style property is sometimes not supported.
* Fixed an issue on Android where the `MediaPlaybackService` could be restarted after the app was closed, in some cases causing a `ForegroundServiceDidNotStartInTimeException`. A conditional receiver makes sure the service is never restarted.
* Fixed an issue on iOS where a setup with multiple players could cause a view index NSInternalInconsistencyException after moving players in and out of fullscreen.
* Fixed an issue on Android where some event listeners were not properly disposed of after destroying the player.
* Fixed an issue on Web where the `width` and `height` properties on `THEOplayer` would show the active video rendition's resolution width and height instead of the width and height of the video element.

## \[10.0.0] - 25-09-15

### Added

* Added support for player SDK v10. More info on the [migration documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/migrating-to-react-native-theoplayer-10.md) page.
* Added iOS and Android support for THEOads API and THEOads events.

### Fixed

* Fixed an issue on Android where the app could still enter picture-in-picture presentation mode after closing the player.

### Changed

* Upgraded the example app to React-Native v0.81.
* All child views of `<THEOplayerView>` are being hidden when transitioning to picture-in-picture presentation mode on Android.

## \[9.10.0] - 25-08-19

### Fixed

* Fixed an issue on Android where transitioning into picture-in-picture presentation mode with the `THEOplayer_reparent_on_PiP` flag enabled would sometimes break the lay-out.
* Fixed an issue where the player's `currentTime` would not be immediately updated when dispatching `seeking` and `seeked` events.
* Fixed an issue on iOS where a listener for `seeked` events was not properly created.

## \[9.9.1] - 25-07-31

### Fixed

* Fixed an issue on Web in case the `aspect-ratio` CSS property is not supported on older browsers.
* Prevented passing infinite or NaN for intializationDelay in TheoAdDescription, on the Android bridge.
* Fixed and issue on Android where transitioning automatically into PiP presentation mode would fail on Android 16+.
* Fixed sources without an explicit `type` not being correctly recognized on Android when the URL contains query parameters.

### Added

* Added support for Clearkey DRM on Android.
* Added `endpoint` property to THEOlive `EndpointLoaded` event.
* Added support for `ABRStrategyConfiguration` on iOS.

## \[9.9.0] - 25-07-14

### Added

* Added initializationDelay to TheoAdsDecription, to delay THEOads session creation for more optimal ads monetisation.

### Fixed

* Fixed an issue on iOS where on iPads the fullscreen dimensions were not correctly updated after the first device orientation change.

## \[9.8.0] - 25-07-08

### Changed

* Deprecated the `BaseSource.integration` property in favor of `TypedSource.type`.

### Added

* Added support for `THEOlive` events.

### Fixed

* Fixed an issue on Android where, depending on the project structure, the Maven repository list would be incorrect.

## \[9.7.1] - 25-07-03

### Fixed

* Fixed a build issue on Android when using player SDK v9.7.0.

## \[9.7.0] - 25-07-01

### Added

* Added the theolive discoveryUrl to the PlayerConfiguration's theolive properties.
* Added focusguides (@THEOplayer/react-native-ui feature) to the example app for tvOS.

## \[9.6.0] - 25-06-27

### Added

* Added, for HLS on iOS, the `unlocalizedLabel` to the text-, audio- and videoTracks API, which contains the unmodified label as extracted from the manifest.
* Added a flag `focusSkipButtonWhenAvailable` to `GoogleImaConfiguration`.

## \[9.5.0] - 25-06-20

### Added

* Added Expo plugin support for iOS. More info on the [documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/expo.md) page.
* Added `currentProgramDateTime` to player API.

### Fixed

* Fixed an issue where a delayed `PresentationModeChange` event on Android could cause lay-out issues when going in to fullscreen mode.

## \[9.4.0] - 25-06-12

### Fixed

* Fixed an issue with the Expo plugin where Android extensions would not be properly enabled.

### Added

* Added `theoads` and `millicast` support for Android Expo plugin.
* Added support for the new `TextTrackStyle.marginBottom` and `TextTrackStyle.marginRight` API's on THEOplayer Android SDK v9.5.0.

## \[9.3.0] - 25-06-02

### Fixed

* Fixed an issue on iOS where the fullscreen dimensions could become wrong when the device is Flat Up or Flat Down on the table, or in an angle close to these.
* Fixed an issue on Android where switching to the PiP window during an IMA ad caused a crash on Android 8-11.

### Added

* Added `currentTime` property to `SeekingEvent` and `SeekedEvent`, indicating the player time to which is being seeked.

## \[9.2.0] - 25-05-20

### Added

* Added support for Millicast on iOS, Android and Web.
* Added support for `TextTrackStyle.edgeColor` on Android.
* Added support for THEOads on tvOS.

### Fixed

* Fixed an issue where the last cue of a VTT was not parsed if there is no newline after it.
* Fixed an issue on Android where a conversion build error would occur when targeting SDK version 9.4.

### Changed

* Changed the fullscreen dimensions calculation on iOS to make use of the native screen width and height, while taking into account the device orientation.

## \[9.1.2] - 25-05-14

### Fixed

* Prevented a possible crash on iOS/tvOS by deallocating the player instance without calling an explicit 'destroy' that brings the native player API at risk. The erroneous destroy method will be deprecated on the native SDK.

## \[9.1.1] - 25-04-24

### Fixed

* Fixed an issue on Android where a muted player would still be paused by the `AudioFocusManager`.

## \[9.1.0] - 25-04-23

### Added

* Added iOS support for `sseEndpoint` property to `TheoAdDescription`.
* Added iOS support for side-loaded chapter TextTracks.

### Changed

* Changed the `playbackPipeline` parameter in `SourceConfiguration` to be an optional parameter.

## \[9.0.1] - 25-04-08

### Fixed

* Fixed an issue on Android where an app would sometimes crash while receiving the license response when using a custom DRM integration.

### Added

* Added supported for multimedia tunneling on Android using the Media3 playback pipeline. More info on the [documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/media3.md#multimedia-tunneling) page.

## \[9.0.0] - 25-04-04

### Removed

* Removed `chromeless` property from `PlayerConfiguration`. Only React Native based UIs are supported.
* Removed ad integration kind `theo`.
* Removed `enableTHEOlive` property from `PlayerConfiguration` as THEOlive is always enabled.

### Added

* Added `liveOffset` property to `SourceDescription` for Web and Android platforms.
* Added `description` property for Google IMA ads on Web and Android platforms.
* Added `networkCode` property for Google DAI configuration on Web platforms.
* Added `segmentRelativeVttTiming` property on `DashPlaybackConfiguration` for Web to indicate whether segmented WebVTT files' timestamps should be considered relative to the segment start time.
* Added `storageType` to `CachingTaskParameters` to allow writing to either the legacy cache or Media3 cache on Android.

### Changed

* Reverted DataRangeCue timings calculation on iOS (based on programDateTime offset). Correct values are provided by the native SDK.

## \[8.18.0] - 25-04-02

### Changed

* No longer showing poster after setting the source when the player has been configured to use autoplay. With autoplay enabled, displaying the poster will only result in a brief flash of the image.
* Changed the fullscreen screen dimension calculation on Android, taking into account edgeToEdge layouts.

### Added

* Exposed THEOads API through the Player API.
* Added support for Common Media Client Data (CMCD) on all platforms. More info on the [documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/cmcd.md) page.

### Fixed

* Fixed an issue on Android where the transition to a PiP window would not focus on the player window.

## \[8.17.0] - 25-03-20

### Fixed

* Fixed an issue on Web where the metadata on the lockscreen was not showing correctly or missing occasionally.
* Fixed a crash on Android when setting a source with THEOads without the Media3 extension being enabled.
* Fixed an issue on iOS where the AdTapped and AdClicked events were not correctly cleaned up.
* Fixed an issue on Android where the player would sometimes crash when passing a DRM protected source without an `integration` property.

### Added

* Added SeekTo functionality to the web lockscreen controls, allowing to drag the lockscreen slider and seek to a specific time value.
* Added the IMA DAI `streamActivityMonitorId` property as a configuration on the SGAI `TheoAdDescription` for web.
* Added the THEOads API for Web.
* Added `retrievePodIdURI` property to `TheoAdsDescription` for Android and iOS.

## \[8.16.0] - 25-02-28

### Changed

* Delegating the autoplay functionality to the underlying native Android and iOS SDKs, making that logic independent from player events.
* On Android, sources with THEOads will always use the media3 player pipeline.

### Fixed

* Fixed an issue on iOS where `hlsDateRange` was not passed from RN towards iOS native
* Fixed an issue on Android, where the player would sometimes not initialise correctly in case New Architecture was not being used, resulting in a black screen.
* Fixed an issue on iOS Safari browsers, where the `presentationmodechange` event would not be dispatched when entering or exiting fullscreen.

## \[8.15.0] - 25-02-12

### Changed

* Transitioning to `fullscreen` presentation mode on Web platforms now puts only the `THEOplayerView` element and its child elements, such as the UI, in fullscreen. Previously, the whole page would transition to fullscreen.
* Changed `presentationmodechange` event dispatching on iOS to take into account if the change actually happened on the native player.

### Fixed

* Fixed an issue on iOS Safari where transitioning to `fullscreen` presentation mode would not work.
* Fixed an issue on Web where `presentationmodechange` events would sometimes be dispatched more than once.
* Fixed an issue on iOS where the view origin in fullscreen presentationMode was wrong when running under the RN new architecture / interop layer

## \[8.14.0] - 25-02-10

### Added

* Added a `theoLive` property to `PlayerConfiguration` to enable THEOlive configuration.

### Fixed

* Fixed an issue on iOS where the `currentTime` on `NowPlayingInfoCenter` would go out of sync or reset when changing playback rate.
* Fixed an issue on Android where the player would crash in case resolving the `THEOplayerView` instance fails.

## \[8.13.1] - 25-01-27

### Fixed

* Fixed an issue on iOS where fullscreen-inline transitions would cause a UIViewControllerHierarchyInconsistency when the current view's viewcController has sibling viewControllers that manage views that don't descend of the moving view.

## \[8.13.0] - 25-01-15

### Added

* Added support for New Architecture's through the Interop Layer. More info on the [React Native developer pages](https://reactnative.dev/architecture/landing-page).

### Fixed

* Fixed an issue on Web where picture-in-picture presentation mode would sometimes fail.

### Changed

* Upgraded the example app to use react-native-tvos\@0.76.5-0.

## \[8.12.0] - 25-01-09

### Fixed

* Fixed a memory leak on iOS, where the presentationModeManager was holding a strong reference to the fullscreen's target and return views
* Fixed an issue on iOS where the destruction of the THEOplayerView was not always propagated correctly over the iOS Bridge, resulting in an occasional memory leak.
* Fixed an issue where, when requesting a text track's cues, the time properties would sometimes be in seconds instead of milliseconds.
* Fixed a rare crash on Android due to a `java.lang.NullPointerException` when creating the THEOplayerView.
* Fixed an issue on Android where R8 minification would obfuscate some API class names, which could lead to a crash.

### Added

* Added a `adLoadTimeout` property to `GoogleImaConfiguration` to control the amount of time that the SDK will wait before moving onto the next ad or main content.

## \[8.11.1] - 24-12-18

### Fixed

* Fixed the picture-in-picture presentationMode for THEOlive sources on Web.

### Changed

* Deprecated the use of the `enableTHEOlive` flag in `PlayerConfiguration` as THEOlive support is always enabled.

## \[8.11.0] - 24-12-13

### Added

* Added support for THEOlive on tvOS.

## \[8.10.0] - 24-12-06

### Added

* Added support for THEOlive on iOS.

## \[8.9.1] - 24-12-04

### Added

* Added a `enableTHEOlive` flag to `PlayerConfiguration` to enable play-out of THEOlive sources.

## \[8.9.0] - 24-11-29

### Added

* Added support for the `SURFACE_CONTROL` rendering target on Android, which improves switching from/to fullscreen presentation mode. Rendering target `SURFACE_CONTROL` will be selected instead of `SURFACE_VIEW` on API level 29+.

### Fixed

* Fixed a memory leak on iOS, caused by the wrapping ViewController that was keeping a strong reference to the THEOplayerRCTView.

### Added

* Added support for the experimental media3 player pipeline on Android.

### Changed

* **BREAKING**: Changed the `view` parameter in the `Omid` API from a ref container to a native node handle when registering "friendly" obstructions.

## \[8.8.1] - 24-11-20

### Fixed

* Fixed build issue on tvOS caused by HomeIndicatorViewController

## \[8.8.0] - 24-11-19

### Added

* Added `HomeIndicatorViewController` to iOS, which can be used as an alternative `rootViewController` for the native App. It will automatically show/hide the home indicator when transitioning from/to fullscreen presentationMode.

### Changed

* Simplified the `viewController` reparenting mechanism on iOS that is applied when changing the presentationMode to/from fullscreen.
* The `MediaPlaybackService` on Android is never restarted if a MediaButton event is received after the app was closed.
* Added a consumer R8 config file on Android, telling R8 not to throw errors or warnings because of classes that are expected to be missing.

## \[8.7.0] - 24-11-05

### Fixed

* Fixed an issue on iOS where the dynamic island (iphone 14 plus and higher) briefly disappeared when updating the nowPlayingInfo on for example backgrounding the app.
* Fixed an issue on Android when using Expo, where the Expo plugin would not add THEOplayer's Maven repo to the project's repositories list.

### Added

* Added the `Omid` API for ads, which can be used to manage friendly video controls overlay obstructions.

## \[8.6.0] - 24-10-25

### Added

* Added `AdEvent.AD_CLICKED` and `AdEvent.AD_TAPPED` ad events for iOS and Android. The events are dispatched when a user taps or clicks on an ad that has a `clickThrough` link.

### Changed

* Upgrade example app to support React Native v0.75.

## \[8.5.0] - 24-10-21

### Added

* Added `SdkVersion` interface to be used by the sdk and its connectors to report version info.
* Added the `THEOads` SGAI ad integration for Android. See [THEOads](https://www.theoplayer.com/product/theoads) for more details.

### Fixed

* Fixed an issue on Web where all text tracks other than the selected would be set to `disabled` when enabling a text track.
* Fixed an issue on iOS where the player would crash when changing the presentationMode from fullscreen to picture-in-picture during ad playout.

### Changed

* On iOS, after closing picture-in-picture the player returns back to the previous presentationMode instead of always returning to inline.

## \[8.4.0] - 24-10-10

### Added

* Added a `posterStyle` property on `THEOplayerView` to allow overriding the default 16:9 poster style.
* Added a `theoads` property on `PlayerConfiguration.ads` to allow play-out of THEOads sources on Web platforms.
* Added a `hlsDateRange` property on `SourceDescription` to enable parsing and exposing date ranges from HLS playlists. This flag was already available on `PlayerConfiguration`, which applies for all HLS sources.

### Fixed

* Added support for a breaking change to `ContentProtectionIntegrationFactory`'s signature in THEOplayer Android 8.2.0.

## \[8.3.1] - 24-10-07

### Fixed

* Fixed an issue on Android where on some Android SDK versions controlling playback with the notification buttons would not work.
* Fixed an issue on Web and Android where a text track with attribute `DEFAULT` was not set as the player's `selectedTextTrack` property.

### Added

* Added `sdkVersions` to react-native-theoplayer, which contains the current RN SDK version and the version of the underlying native THEOplayer SDK.

## \[8.3.0] - 24-09-30

### Added

* Added the option to specify the AVAudioSession mode for iOS (moviePlayback versus spokenAudio).

## \[8.2.2] - 24-09-28

* Fixed a build issue on iOS for applications that run without the GOOGLE\_IMA feature flag

## \[8.2.1] - 24-09-27

### Fixed

* Fixed a build issue on Android when pinning a specific Android player SDK version, while also disabling the Google IMA extension.

## \[8.2.0] - 24-09-26

### Added

* Added the `PlaybackSettings` API for Android, allowing control of playback behaviour across all THEOplayer instances.

## \[8.1.0] - 24-09-23

### Added

* Added support for `bitrate` config on the GoogleIMAConfiguration, to be passed to the IMA SDK rendering settings.
* Added support on iOS and Android for `allowedMimeTypes` config on the AdsConfiguration, to be passed to the IMA SDK rendering settings.

### Fixed

* Fixed an issue where cast events were not forwarded from the native Android SDK.
* Fixed an issue where presentationMode changes on iOS would cause a UIViewControllerHierarchyInconsistency when an ad is playing.
* Fixed an issue where some ad event types could not be resolved at runtime when excluding the IMA integration on Android.

## \[8.0.3] - 24-09-14

### Fixed

* Fixed an issue on Android where the THEO Maven repository would not be picked up by all dependencies.

## \[8.0.2] - 24-09-14

### Fixed

* Fixed an issue on Android where not all dependencies would be correctly resolved.

## \[8.0.1] - 24-09-11

### Fixed

* Fixed an issue on Android where registering a content protection integration would fail.

## \[8.0.0] - 24-09-11

### Added

* Added support for THEOplayer 8.0.

### Changed

* Deprecated Jitpack.io in favor of the THEOplayer Maven repository on Android.

### Fixed

* Fixed an issue on iOS where the initial `duration` property of the player would be `0` instead of `NaN`.

## \[7.9.0] - 24-09-06

### Added

* Added THEOlive source integration type to `SourceDescription`.
* Added THEOads as `AdIntegrationKind`.
* Added a `headers` property to `TypedSource`. The player will add the headers to the HTTP requests for the given resource.

## \[7.8.2] - 24-08-21

### Changed

* Modified the poster behavior on iOS and Android to remain visible until the first frame is displayed.

## \[7.8.1] - 24-08-14

### Fixed

* Fixed an issue on Android where the notification background would be displayed in low resolution on recent Android versions.

### Added

* Added support on iOS for 'album' and 'artist' in the nowPlayingInfo.

## \[7.8.0] - 24-08-09

### Added

* Added shouldResumeAfterInterruptions to the BackgroundAudioConfiguration which toggles playback resume after an interruption (e.g. phone call) on the lockscreen.
* Added the option to set a nil source on the iOS Bridge, to 'unset' the previous source.
* Added the fast-forward & rewind buttons for the Android notification when `mediaControl.mediaSessionEnabled` is set to `true`.
* Added a `mediaControl.convertSkipToSeek` player config property to allow seeking with the `NEXT` and `PREVIOUS` media buttons. Its default value is `false`.

### Fixed

* Fixed an issue where the Lockscreen showed enabled controls when the player has no valid source.
* Fixed an issue on Android where the notification would not disappear when setting an undefined source.

### Changed

* Replaced the `MediaBrowserService` with a regular `Service` to facilitate background playback on Android.

## \[7.7.1] - 24-07-29

### Fixed

* Fixed an issue on tvOS where native cache functionality was not excluded correctly resulting in build errors.

## \[7.7.0] - 24-07-25

### Added

* Added ActiveQualityChanged event support for iOS.

### Fixed

* Fixed an issue where on iOS a cached asset would not play when setting the tasks's source on the player.
* Fixed an issue where on iOS the createTask method (CacheAPI) was not returning the created task.
* Fixed an issue where on iOS the Ad and AdBreak protocols where extended in the underlying native SDK and required some modifications.
* Fixed an issue where on Android the native module preparation would fail due to a change in the Android SDK 7.8.0 on eventDispatching.

## \[7.6.0] - 24-07-01

### Added

* Added `'root'` as an alternative id for the root div element in Web applications, supporting fullscreen presentation mode in Expo-based apps.
* Added `renderingTarget` property to `THEOplayer` API for Android, enabling the option to choose between either rendering to a `SurfaceView` (default) or `TextureView`.

### Changed

* Lowered the required node version to v16+.

## \[7.5.1] - 24-06-20

### Added

* Added ad event support for custom SSAI integrations.

## \[7.5.0] - 24-06-18

### Fixed

* Fixed an issue where the Cast API wouldn't be initialized yet when in the `onPlayerReady` callback.
* Added support for THEOplayer Android v7.6.0.

## \[7.4.0] - 24-06-11

### Added

* Added support for `SourceDescription.poster` for Android & iOS.
* Made the intervals for the forward and backward skip buttons on the iOS lockScreen configurable.
* Added preferredPeakBitRate and preferredMaximumResolution to ABRConfiguration for iOS

## \[7.3.0] - 24-06-03

### Changed

* Disabled skip forward/backward remote control buttons by default for Live content on Android TV platforms.

### Added

* Added support for React Native 0.74 and upgraded the example application to depend on `react-native-tvos` 0.74.1.

### Fixed

* Fixed an issue where on the iOS bridge the wrong value was extracted from the CachingParameters to configure the bandwidth setting on the MediaCache.

## \[7.2.0] - 24-05-12

### Added

* Added `resize` player event enabling monitoring of player resizes.
* Added `width` and `height` properties to `THEOplayer` containing the player's current dimensions in pixels.
* Added the possibility to set the player volume on iOS programmatically via the player API.
* Added `AD_CLICKED`, `AD_TAPPED`, `AD_ICON_TAPPED` and `AD_ICON_FALLBACK_IMAGE_CLOSED` ad events for Android platforms.

### Fixed

* Fixed an issue on Android where the `scheduledAdBreaks` list did not include the pre-roll ad on play-out of a Google DAI stream.

## \[7.1.1] - 24-04-26

### Fixed

* Fixed an issue where the selectedAudioTrack and selectedVideoTrack were not in sync with the actual selected mediatracks on the native player.

## \[7.1.0] - 24-04-23

### Fixed

* Fixed a build issue on tvOS example app due to the deprecated `prepare` method.

### Added

* Added multiple configuration options to `GoogleImaConfiguration` for both iOS and Android. These map to the corresponding IMASettings from the underlying native Google IMA SDKs.
* Added `skipForwardInterval` and `skipBackwardInterval` properties to `MediaControlConfiguration` for Android and Web, enabling configurable skip intervals for media sessions.
* Added ios bridging code to make 'forced' property available from native iOS TextTrack API.

### Removed

* Removed support for the web-based native iOS SDK on the RN iOS Bridge.

## \[7.0.0] - 24-04-10

### Fixed

* Fixed an issue where the player had the wrong layout in fullscreen presentationMode, after changing the source.
* Fixed an issue where not enabling autoplay would explicitly pause the stream, reverting a possible play() request right after setting up the source.

### Added

* Added support for THEOplayer native SDK 7.0.
* Aligned SDK major version with native player SDKs.

### Changed

* Raise minimal ios deployment target to 13.4, to match react native 0.73's minimal deployment target

## \[3.10.3] - 24-03-22

### Fixed

* Fixed a crash on iOS when playing an IMA Ad after reparenting the THEOplayerView to a different native Viewcontroller.

## \[3.10.2] - 24-03-22

### Changed

* Downgraded default `androidx.core:core-ktx` dependency version to support Android target sdk 33.

## \[3.10.1] - 24-03-19

### Changed

* Updated ios sdk version to 6.12.1

## \[3.10.0] - 24-03-15

### Changed

* Updated dependencies and example app to support ReactNative v0.73.
* Updated ios sdk version to 6.11

### Fixed

* Improved NowPlayingInfo updates for iOS by setting playbackRate on pause/playing events and processing the final info on player desctruction.
* Fixed an issue with misinterpretation of `targetVideoQuality = 0` (use video track with `uid == 0`) as `targetVideoQuality = undefined` (use ABR across all video qualities).
* Fixed an issue where the `srclang` property of a `textTrack` passed to a `SourceDescription` would not be parsed on Android.

### Added

* Added an optional `THEOplayer_reparent_on_fullscreen` build property on Android to disable `THEOplayerView` reparenting when transitioning to fullscreen presentation mode.

## \[3.9.2] - 24-03-06

### Changed

* Never pause play-out when losing audio focus while playing an advertisement.

## \[3.9.1] - 24-03-05

### Changed

* Bumped google-cast-sdk dependency to v4.8.0 for iOS.

## \[3.9.0] - 24-03-04

### Changed

* Reduce audio volume (duck) on Android when another app gains transient audio focus and ducking is allowed. In other cases the player will pause, and optionally resume if the audio focus loss was transient.

### Fixed

* Fixed an issue on iOS where the lockscreen controls and displayed asset metadata would remain visible after the player has been destroyed.
* Fixed an issue on iOS where the castState was not initialized correctly.

## \[3.8.0] - 24-02-23

### Changed

* Renamed native modules to avoid name collisions with external packages.

### Added

* Added `adbreakbegin` and `adbreakend` events for Google IMA on Android.
* Added `liveOffset` property to `PlayerConfiguration`, allowing to set a custom offset from the live point.
* Added a second, alternative config filename to the iOS podspec setup to prevent a react-native-theoplayer module resolving clash.

## \[3.7.1] - 24-02-09

### Fixed

* Fixed a dependency issue on iOS when using chromecast or Google IMA features.

## \[3.7.0] - 24-02-09

### Added

* Added fullscreen presentation mode support for iOS and Android. More info on the [documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/fullscreen.md) page.

## \[3.6.0] - 24-02-02

### Fixed

* Fixed a build issue on the iOS bridge caused by the deprecated DispatchDispatch protocol.
* Fixed an issue on Android where the `MediaPlaybackService` would sometimes crash with a `ForegroundServiceDidNotStartInTimeException` exception.

### Added

* Added the ability to override both small and large notification icons in Android with `ic_notification_small` and `ic_notification_large` resources respectively.

## \[3.5.0] - 24-01-30

### Added

* Added the ability to toggle `keepScreenOn` on Android. By default, screen timeout is disabled while the player is visible.

## \[3.4.2] - 23-12-22

### Fixed

* Fixed an issue in the Expo plugin for Android where it would fail to execute when no properties are passed.

## \[3.4.1] - 23-12-21

### Changed

* Take the Kotlin Gradle plugin version from the root project, if specified.

## \[3.4.0] - 23-12-21

### Added

* Added `ui` configuration object to `PlayerConfiguration` to configure the ads UI language.
* Added support for Android 14.
* Added Expo plugin to support Android dependency configuration.

### Changed

* Changed the Android notification channel name to `Notification channel`. It can be renamed by defining the `notification_channel_name` resource string.

## \[3.3.2] - 23-12-12

### Fixed

* Fixed an issue on iOS & Android where timestamps in ad events were not consistently defined in seconds.
* Fixed an issue on tvOS where unknown AdIntegrationKind values resulted in build issues.

## \[3.3.1] - 23-12-11

### Fixed

* Fixed an issue on Android where a `ContentResumeRequested` ad event was never broadcasted.
* Fixed an issue on iOS where the ad duration was provided in milliseconds instead of seconds.

## \[3.3.0] - 23-12-11

### Changed

* Extended event dispatching mechanism with broadcast functionality.

## \[3.2.1] - 23-12-07

### Fixed

* Fixed an issue on Android where `EnterCue` and `ExitCue` text track events did not contain the `trackUid` property.

## \[3.2.0] - 23-11-29

### Fixed

* Fixed an issue on iOS and Android were selecting an audio, video or text track that has a `uid` with value `0`, would fail.

### Added

* Added support for HLS #EXT-X-DATERANGE timed metadata tags. The tags appear as cues in a dedicated text track with type `daterange`.

## \[3.1.0] - 23-10-27

### Changed

* Revised audio focus protocol on Android. When resuming an app, audio focus is retrieved only if the player is not paused.
* Changed the behaviour of the Android component supporting background playback. It is stopped but not disabled when setting `backgroundAudioConfiguration.enabled = true`.

### Fixed

* Fixed an issue on Android where during play-out of a locally stored media asset the `seekable` property would not update.
* Fixed an issue on iOS where the error was not forwarded to theoplayer if a drm request fails on the iOS bridge

## \[3.0.2] - 23-10-17

### Fixed

* Fixed an issue on Android where compilation would fail when depending on player SDK 6.2.0.

## \[3.0.1] - 23-10-12

### Fixed

* Fixed compilation issues caused by Caching API not being supported on tvOS

## \[3.0.0] - 23-10-06

### Fixed

* Fixed sourceDescription processing on iOS for offline playback.

### Changed

* Added support for THEOplayer 6.0. See [THEOplayer's changelog](https://www.theoplayer.com/docs/theoplayer/changelog/) for details.
* Bumped minimal version for SideloadedTextTracks connection on iOS to v6.1.1 which contains fix for iOS 17.0.

### Added

* Added `MediaCache` API, enabling download of media assets for offline playback.

## \[2.16.1] - 23-09-27

### Added

* For iOS, added a subtitlePTS property to the TextTrackDescription that syncs a sideloaded textTrack with the video content.

## \[2.15.0] - 23-09-26

### Changed

* Upgraded the iOS side-loaded text track connector.

### Fixed

* Fixed an issue where the Android mediaSession connector would still process media button events when the app was in the background, and `enableBackgroundPlayback` was false.
* Fixed an issue on Android where play-out would still start when the app was put to the background during initial buffering, and `enableBackgroundPlayback` was false.
* Fixed an issue on Android where the MediaButtonReceiver would crash the app when it did not find a registered MediaBrowserService instance, when setting `enableBackgroundPlayback` to false while backgrounding the app.

## \[2.14.0] - 23-09-25

### Fixed

* Fixed an issue on Android where the MediaButtonReceiver would crash the app when it did not find a registered MediaBrowserService instance.

### Added

* Added support for side-loaded metadata tracks on iOS.

## \[2.13.0] - 23-09-15

### Fixed

* Fixed an issue where setting a new source on iOS, during DRM handling, would crash the application due to unsafe array access by different threads.

## \[2.12.1] - 23-09-14

### Fixed

* Fixed an issue on Android where the player SDK dependency could resolve to version 6.+.
* Fixed an issue on iOS where the player integration dependencies could resolve to version 6.+.

## \[2.12.0] - 23-09-04

### Added

* Added an `AnalyticsDescription` property to `SourceDescription` to configure additional source-specific properties for analytics connectors.
* Added support for sideloaded webVTT and SRT texttracks on iOS.
* Added Audio Focus for Android, pausing play-out on audio focus loss and resuming play-out once focus has been regained.
* Added Audio Focus and Audio Becoming Noisy manager for Android.

### Fixed

* Fixed an issue on Android that would cause the player not to reset when setting an empty source.
* Fixed an issue where a text track cue was not properly removed from the cue list on a TextTrackEventType.REMOVE\_CUE event.
* Fixed an issue on tvOS that allowed the user to pause a CSAI ad using the apple remote control.
* Fixed an issue on iOS where the cue event listeners were not cleanup up when destroying the player instance, resulting in memory build-up.

## \[2.11.0] - 23-08-10

### Added

* Added DAI support through iOS Native pipeline, using new THEOplayerGoogleIMAIntegration functionality
* Added `TextTrackStyle` API for iOS and Android.

### Fixed

* Fixed an issue on Android where the player would sometimes crash when requesting the current active video track.

### Changed

* Switched to 'displayIconUri' in sourceDescription.metadata as primary field for artwork selection in NowplayingInfo/MediaSession, 'poster' in sourceDescription is now the fallback.
* Removed the play/pause icon in the PiP window on Android while playing an ad.

## \[2.10.0] - 23-07-25

### Fixed

* Fixed an issue on Android where the media button receiver would not accept button events in case multiple receivers are registered.
* Fixed an issue on Android where `react-native-theoplayer` would not build when depending on Android player SDK v5.6.0.
* Fixed an issue on Android where a `pause` event would not be dispatched when putting the app to the background during play-out of an ad, while background playback is enabled. The ad would also restart when bringing the app back to the foreground.

### Changed

* Removed restrictions on media session playback actions for AndroidTV.
* Upgraded `react-native` version of the example app to `react-native-tvos@0.71.12-0`.

### Added

* Added a `version` property to `THEOplayer` for querying the `player` version (e.g., `'5.5.0'`) and `playerSuite` (e.g., `'2023.3.0'`) versions.

## \[2.9.0] - 23-06-16

### Changed

* Moved React Native UI to separate `@theoplayer/react-native-ui` package.

### Removed

* Removed `react-native-theoplayer` dependencies on packages `@react-native-community/slider`, `react-native-google-cast`, `react-native-svg`, `react-native-svg-web`, `react-native-url-polyfill` and `url-polyfill`.

### Added

* Added an overview of the available React Native connectors.

### Fixed

* Fixed an issue on Android where the background media service would crash the app in case it was started from the background.
* Fixed an issue on iOS where the delayed contentId extraction resulted in an incorrect value being passed to the license request setup.

## \[2.8.0] - 23-06-01

### Added

* Added `ignoreAvailabilityWindow` property to `SourceDescription.dash` for Android and Web.
* Added `needsTimescaleShifting`, `desiredTimescale` and `forceSeekToSynchronize` properties to `SourceDescription.dash` for Web.

### Fixed

* Fixed an issue where text track cue changes were not applied to the TextTrack's `cue` property.
* Fixed an issue on Android where play-out of an MP4 stream would sometimes crash the player.
* Fixed an issue on Android where a `pause` event would not be dispatched while pausing during play-out of an ad.
* Fixed an issue on Android where hardware buttons, such as `play` and `pause`, were not handled anymore after toggling background audio support.
* Fixed an issue on Android where the app would crash when toggling background playback while multiple `MediaBrowserServiceCompat` instances are registered.

### Changed

* Improved fullscreen support to use non-native fullscreen on Safari for iPad and Mac.
* Limited the set of available media session actions on Android when an ad or live stream is playing.
* Removed pausing the stream when disabling background playback on Android.

## \[2.7.0] - 23-05-15

### Changed

* Approved player behaviour on iOS and Android when doing player operations such as `play` and `pause` in case no source was set.

### Fixed

* Fixed an issue on Android where if an invalid view tag is passed to the native bridge, it would crash the player.
* Fixed an issue on Web where preview thumbnails would fail to load.

### Added

* Updated UI documentation with necessary dependencies.
* Added improved debug logging on iOS.

## \[2.6.0] - 23-05-05

### Fixed

* Fixed an issue on Android where the `currentProgramDateTime` property of `TimeUpdateEvent` would not be formatted in milliseconds.
* Fixed an issue on Android where the order of text and media tracks would change when adding tracks.
* Fixed an issue on Web where an exception would be thrown when accessing the player API after the player had been destroyed.
* Fixed an issue with Google IMA where the main content wasn't resumed after a pre-roll ended.

### Changed

* Use `enum` instead of a string union for `ABRStrategyType`.
* Changed the way artwork is fetched for NowPlayingInfo on the iOS Lockscreen, to prevent a crash caused by threading issues.

## \[2.5.0] - 23-04-26

### Added

* Added an `aspectRatio` property on the `THEOplayer` instance that can be either `FIT` (default), `FILL` or `ASPECT_FILL`.

### Changed

* Set `theoplayer` Web SDK as optional peer dependency.

## \[2.4.0] - 23-04-21

### Fixed

* Fixed an issue on iOS and Android where cue event properties `startTime` and `endTime` with value `Infinity` or `NaN` were not passed correctly.
* Fixed an issue on iOS Safari where switching to fullscreen presentation during an ad would not work.
* Fixed an issue on iOS Safari where an ad could be skipped during unmuted autoplay.
* Fixed a memory leak on iOS where the player would be allocated after being destroyed.
* Fixed an issue on Android where building the SDK would require IMA to be enabled.

### Changed

* Changed Web media session controls to only show trick-play buttons if the player is in foreground, or `backgroundAudioEnabled` is `true`, and never for ads and live stream.
* Changed Web media session controls to only show a play/pause button if the player is in foreground, or `backgroundAudioEnabled` is `true`, and never for ads.

### Added

* Added the `crossOrigin` property to `SourceDescription` for requesting CORS access to content.

## \[2.3.0] - 23-04-14

### Changed

* Updated picture-in-picture controls on Android to include forward/rewind buttons and disabled pause button for ads.

## \[2.2.0] - 23-04-12

### Fixed

* Fixed an issue on Android and iOS where error codes were not correctly formatted.

### Added

* Added `RetryConfiguration` on `PlayerConfiguration` for Web and Android.

### Changed

* Set minimum THEOplayer dependency version to 5.0.1 for Web, iOS and Android.
* Set `MediaPlaybackService` disabled by default on Android.

## \[2.1.0] - 23-04-09

### Fixed

* Fixed invalid location of the typescript declaration file.
* Fixed an issue on Android where the player would not pause when closing the app while background playback is disabled.

### Changed

* Removed `backgroundAudioConfiguration.mediaPlaybackServiceEnabled` property on Android. Disabling background playback disables the service as well.

## \[2.0.0] - 23-04-06

### Added

* Released 2.0.0 version.

## \[Unreleased 2.0.0-pre9]

### Changed

* Set the player container on Web to by default have a width and height not larger than the devices width and height.
* Use `enum` type for `PresentationMode`, `CastState` and`AdIntegrationKind`.
* Changed the methods of the Cast API, such as `casting` and `state`, to be synchronous.
* Applied `backgroundAudioConfig` properties on Android when closing picture-in-picture window.
* Applied `backgroundAudioConfig` properties on Android when showing Notifications.
* Disable iOS lockscreen controls when backgroundAudioConfig is set to `disabled`.

### Added

* Added `enableMediaPlaybackService` option to `backgroundAudioConfiguration` to optionally disable the MediaBrowserService that provides background audio support on Android.
* Added support for the `enabled` flag of `BackgroundAudioConfiguration` for Web.
* Added serviceId and contentId to NowPlayingInfo
* Feature flag extraction from custom iOS builds

### Fixed

* Fixed an issue on Android where the media session would become inactive when going to picture-in-picture mode, removing all transport controls.
* Fixed an issue where removing a player listener within a listener callback would sometimes result in events not being dispatched.

## \[Unreleased 2.0.0-pre7]

### Fixed

* Fixed an issue where the media session connector for Web would report an error when passing an Infinite duration for live streams.
* Fixed an issue on iOS where ID3 metadata content would not be correctly passed to cue instances.
* Fixed an issue on Android where the `'picture-in-picture'` permission was not checked.
* Fixed an issue on Android where the aspect ratio of the `'picture-in-picture'` window could be outside the valid range.
* Fixed an issue on iOS and Android where for a live stream the `duration` property of a `loadedmetadata` event was not properly passed as being `Infinite`.

### Changed

* Replaced deprecated systemUiVisibility code in Android's PresentationManager.
* Use `enum` types for `TextTrackMode`, `TextTrackType` and `TextTrackKind`.
* Allow go-to-live on iOS and Android by setting `currentTime` to `Infinity`.

### Added

* Added a `mediaControl` property to `PlayerConfiguration` to configure Media Session, Now Playing and Remote Command Center functionality across all platforms. It currently only contains a media session toggle for Web.
* Added a `backgroundAudioConfiguration` property to `THEOplayer` to allow dynamically configuring background audio functionality.
* Added a `pipConfiguration` property to `THEOplayer` to allow dynamically configuring picture-in-picture behavior.
* Added support for background audio playback on iOS and Android.
* Added `keepScreenOn` as a default player view property on Android to keep the device awake.

## \[Unreleased 2.0.0-pre6]

### Fixed

* Fixed an issue where the IMA player container would be rendered collapsed on Web.
* Fixed a missing check for picture-in-picture permission on Android.

### Added

* Added media session connector for Web.

## \[Unreleased 2.0.0-pre5]

### Added

* Added `onPlayerReady` callback on `THEOplayerView` to pass a `THEOplayer` instance once it is ready for access. More info on the [migration documentation](https://github.com/THEOplayer/react-native-theoplayer/blob/v7.0.0/doc/migrating-v2.md) page.
* Added `canplay` event, which is dispatched when the player can start play-out.
* Added `waiting` event, which is dispatched when the player has stopped play-out because of a temporary lack of data.
* Added `nativeHandle` property on `THEOplayer` to access the native player instance on web, and view id on mobile.
* Added `entercue` and `exitcue` events for text tracks, which are dispatched when a cue becomes (in)active.
* Added `ratechange` event, which is dispatched when the player's playback rate was changed.
* Added `seekable` property on `THEOplayer`, containing the time ranges of the media the player is able to seek to.
* Added `buffered` property on `THEOplayer`, containing the time ranges of the media the player has currently buffered.
* Added `buffered` property to the payload of the `onprogress` event.
* Added `duration`, `seeking`, `preload`, `textTrack`, `videoTracks` and `audioTracks` properties to `THEOplayer`.
* Added `libraryLocation` property to `PlayerConfiguration` to allow passing custom location for web workers.
* Added `mutedAutoplay` property to `PlayerConfiguration` to allow autoplay on web browsers with different autoplay policies.
* Added mode `hidden` as a value for a text track's `TextTrackMode` property, which is typically used for metadata tracks.
* Added `TextTrackStyle` API to support text track styling. This feature is currently supported on web only.
* Added support for 'picture-in-picture' presentation mode. More information on the [documentation page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/pip.md)
* Added `muted` state in `volumechange` event payload.
* Added media session connector for Android.
* Added public accessor on the `THEOplayerRCTView` that exposes the underlying iOS `THEOplayer` instance. So you can use the underlying THEOplayer from other packages.

### Changed

* Moved all player properties such as `paused`, `muted` and `volume`, from `THEOplayerView` component to `THEOplayer` instance. More info on the [migration documentation](https://github.com/THEOplayer/react-native-theoplayer/blob/v7.0.0/doc/migrating-v2.md) page.
* Removed `onEventName` callback methods from `THEOplayerView` component in favor of `THEOplayer` event listener's interface. More info on the [migration documentation](https://github.com/THEOplayer/react-native-theoplayer/blob/v7.0.0/doc/migrating-v2.md) page.
* Changed documentation sample code to reflect API changes.
* Exposed the `activeQuality` of a `MediaTrack` as a `Quality` instance instead of the quality's `uid`.
* Set the default container style for web to let the player cover the whole container.

### Removed

* Removed `seek` method on `THEOplayer`. It is replaced with a `currentTime` setter.
* Removed `fullscreen` setter and getter in favor of `presentationMode`.

### Fixed

* Fixed an issue on Android where an exception is thrown when an empty source description would be passed.
* Fixed the Webpack configuration in the sample application to copy web workers to `libraryLocation`.
* Fixed an issue on web where in case multiple player instances are created, the players would overlap.
* Fixed an issue on iOS Safari where switching to fullscreen presentation would not work.
* Fixed an issue on Android where passing an invalid empty source description would result in a crash.
* Fixed an issue on Android where the `framerate` property of a `VideoQuality` instance would not be filled in.
* Fixed an issue on iOS where the `TextTrackMode` property of a text track would be incorrect.
* Fixed an issue on iOS where after enabling/disabling a text track, metadata tracks would be set to `disabled` as well.
* Fixed missing `volumechange` events on mobile platforms.
* Fixed an issue on iOS where after toggling the mute state during an ad playout, succeeding mute toggles had no effect.

## \[1.8.4] - 23-04-27

### Fixed

* Fixed an issue on Android where the `pause` event was not dispatched during play-out of an ad.

### Added

* Added a `videoAspectRatio` property on the `THEOplayerView` for iOS and Android.
* Added a `PlayerEventTypes.WAITING` event that is dispatched when play-back stops due to lack of media data.

## \[1.8.3] - 23-04-06

### Fixed

* Fixed an issue on Android where building the SDK would fail when depending on player SDK v5.x.

## \[1.8.2] - 23-04-05

### Fixed

* Fixed an issue on Android where building the SDK would fail when depending on player SDK v4.12.0.

## \[1.8.1] - 23-02-09

### Changed

* Restructured iOS bridge code to extensions based on features.

### Fixed

* Fixed an issue on Android where the system UI would not be restored when unmounting THEOplayerView with `fullscreen` enabled.
* Fixed an issue with the availability of the cast button and play buttons in the example application.
* Fixed an issue on iOS where the player was not destroyed correctly on the iOS bridge.
* Added support for `DRMConfig` through `SourceDescription` for SSAI sources on iOS.

## \[1.8.0] - 23-01-16

### Added

* Support for Chromecast and Airplay.

### Fixed

* Fixed an issue where moving the sender app to the background while playing a DAI source on an Airplay device, would pause playback.

### Changed

* Upgraded Web SDK to v4.6.0.
* Updated the custom build setup to support both iOS and tvOS.

## \[1.7.2] - 22-12-05

### Fixed

* Fixed an issue on tvOS where a feature flag was incorrectly used for ads-related code.

## \[1.7.1] - 22-11-28

### Fixed

* Fixed an issue on Android where the player would consider unusable custom drm integrations.
* Fixed missing kotlin classpath property on Android.

## \[1.7.0] - 22-11-23

### Added

* Support for content protection integration (DRM connectors).
* Support for subscribing to ad events.
* Support for Google DAI ads.
* Support for Google IMA ads.
* Support for ABR configuration on Android and Web.
* Support for video quality selection on Android and Web.

### Fixed

* Fixed an issue where the player would not be correctly released when destroying the view on Android.
* Fixed a warning during debugging when a stream would have duration INF or NaN.
* Fixed an issue in the example app where it would not be possible to select a specific text track.
* Fixed conflicting npm dependencies in the example app.

## \[1.6.1] - 22-10-07

### Added

* Improved source handling for iOS.

## \[1.6.0] - 22-09-28

### Fixed

* Fixed jitpack.io repository url for Android.
* Fixed an issue where play-out of HLS streams would fail on Android.

### Changed

* Excluded folders from bob build config.
* Upgraded gradle versions for Android.

## \[1.5.0] - 22-09-26

### Fixed

* Fixed disabling all debug logs for iOS/tvOS release builds.
* Fixed duration from seconds to milliseconds on iOS/tvOS.

### Added

* Support for DRM pre-integrations on Android.
* Support for additional source properties on Android: `liveOffset`, `hlsDateRange`, `timeServer` and `hls`.

## \[1.4.0] - 22-08-11

### Fixed

* Fixed an issue on iOS where subtitles upon disappearing would sometimes leave a thin black line on the image.
* Fixed an issue on iOS where the player would not be destroyed after going to fullscreen.

### Added

* Improved determination of the stream source type on Android.

## \[1.3.0] - 22-07-26

### Fixed

* Fixed an issue where the app would crash due to the configured Flipper version.
* Fixed duplicate classes issue for Android when having dependencies on local libs folder.
* Fixed documentation feature matrix.
* Fixed duration scale in loadedmetadata event properties for Web.

## \[1.2.0] - 22-06-30

### Fixed

* Fixed a crash when removing text tracks event listeners on iOS.
* Fixed a number of broken links in the documentation.
* Removed unused files.

## \[1.1.0] - 22-06-06

### Added

* Initial release.

---

# Getting started with React Native THEOplayer

The `react-native-theoplayer` package provides a `THEOplayerView` component supporting video playback on the following platforms:

* Android, Android TV & FireTV
* iOS & tvOS (Apple TV)
* HTML5, Tizen & webOS (web, mobile web, smart TVs, set-top boxes and gaming consoles).

This document covers the creation of a minimal app including a `THEOplayerView` component, and an overview of the accompanying example app with a user interface provided by the `@theoplayer/react-native-ui` package.

It also gives a description of the properties of the `THEOplayerView` component, and a list of features and known limitations.

## Prerequisites

For each platform, a dependency to the corresponding THEOplayer SDK is included through a dependency manager:

* Gradle & Maven for Android
* Cocoapods for iOS
* npm for Web

In order to use one of these THEOplayer SDKs, it is necessary to obtain a valid THEOplayer license for that specific platform, i.e. HTML5, Android, and/or iOS. You can sign up for a THEOplayer SDK license through [our portal](https://portal.theoplayer.com/).

If you have no previous experience in React Native, we encourage you to first explore the [React Native Documentation](https://reactnative.dev/docs/getting-started), as it gives you a good start on one of the most popular app development frameworks.

## How to use these guides

These are guides on how to use the THEOplayer React Native SDK in your React Native project(s) and can be used linearly or by searching the specific section. It is recommended that you have a basic understanding of how React Native works to speed up the way of working with THEOplayer React Native SDK.

## Features

Depending on the platform on which the application is deployed, a different set of features is available.

If a feature missing, additional help is needed, or you need to extend the package, please reach out to us for support.

| Feature                                               | Android, Android TV, Fire TV                                                                                          | Web                                    | iOS, tvOS                                                         |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------- |
| **Streaming**                                         | MPEG-DASH (fmp4, CMAF), HLS (TS, CMAF), Progressive MP4, MP3, M4A                                                     |                                        | HLS (TS, CMAF), Progressive MP4, MP3, M4A                         |
| **Content Protection**                                | Widevine                                                                                                              | Widevine, PlayReady, Fairplay          | Fairplay                                                          |
| **DRM Connectors**                                    | BuyDRM, EZDRM, Anvato, Titanium, Axinom, Irdeto, VuDRM, Comcast, Verimatrix, Azure, …                                 |                                        |                                                                   |
| **Analytics Connectors**                              | Adobe, Agama, Comscore, Conviva, Mux, Nielsen, Youbora                                                                |                                        |                                                                   |
| **Other Connectors**                                  | Yospace SSAI                                                                                                          |                                        |                                                                   |
| **Subtitles & Closed Captions**                       | CEA-608/708, SRT, TTML, WebVTT                                                                                        |                                        |                                                                   |
| **Metadata**                                          | Event stream, emsg, ID3, EXT-X-DATERANGE, EXT-X-PROGRAM-DATE-TIME                                                     |                                        |                                                                   |
| **Advertising Integration**                           | Google IMA, Google DAI, THEOads                                                                                       |                                        |                                                                   |
| **Cast Integration**                                  | Chromecast                                                                                                            | Chromecast, Airplay                    |                                                                   |
| **Presentation Mode**                                 | Inline, Picture-in-Picture, Fullscreen                                                                                |                                        |                                                                   |
| **Audio Control Management**                          | Audio focus & Audio-Becoming-Noisy mgmt                                                                               | (Audio control management by platform) |                                                                   |
| **Advanced APIs**                                     | Background playback,<br />Media Session,<br />Media Cache (offline playback)                                          |                                        | Background playback,<br />NowPlaying,<br />Media Cache (iOS only) |
| **User Interface**<br />`@theoplayer/react-native-ui` | Basic playback, media & text track selection, progress bar, live & vod, preview thumbnails, customisable & extensible |                                        |                                                                   |

## Available connectors

The `react-native-theoplayer` package can be combined with any number of connectors to provide extra functionality. Currently, the following connectors are available:

| Connector                                                 | npm package                                                                                                                                                                                                                                                            | Source                                                                                           |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Adobe Heartbeat analytics using the Media Collections API | [![%40theoplayer/react-native-analytics-adobe](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-adobe?label=%40theoplayer/react-native-analytics-adobe)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-adobe)                | [`Adobe`](https://github.com/THEOplayer/react-native-connectors/tree/main/adobe)                 |
| Adobe Media Edge analytics                                | [![%40theoplayer/react-native-analytics-adobe-edge](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-adobe-edge?label=%40theoplayer/react-native-analytics-adobe-edge)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-adobe) | [`Adobe Edge`](https://github.com/THEOplayer/react-native-connectors/tree/main/adobe-edge)       |
| Agama analytics                                           | [![%40theoplayer/react-native-analytics-agama](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-agama?label=%40theoplayer/react-native-analytics-agama)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-agama)                | [`Agama`](https://github.com/THEOplayer/react-native-connectors/tree/main/agama)                 |
| Comscore analytics                                        | [![%40theoplayer/react-native-analytics-comscore](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-comscore?label=%40theoplayer/react-native-analytics-comscore)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-comscore)    | [`Comscore`](https://github.com/THEOplayer/react-native-connectors/tree/main/comscore)           |
| Conviva analytics                                         | [![%40theoplayer/react-native-analytics-conviva](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-conviva?label=%40theoplayer/react-native-analytics-conviva)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-conviva)        | [`Conviva`](https://github.com/THEOplayer/react-native-connectors/tree/main/conviva)             |
| Mux analytics                                             | [![%40theoplayer/react-native-analytics-mux](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-mux?label=%40theoplayer/react-native-analytics-mux)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-mux)                        | [`Mux`](https://github.com/THEOplayer/react-native-connectors/tree/main/mux)                     |
| Nielsen analytics                                         | [![%40theoplayer/react-native-analytics-nielsen](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-nielsen?label=%40theoplayer/react-native-analytics-nielsen)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-nielsen)        | [`Nielsen`](https://github.com/THEOplayer/react-native-connectors/tree/main/nielsen)             |
| Youbora analytics                                         | [![%40theoplayer/react-native-analytics-youbora](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-analytics-youbora?label=%40theoplayer/react-native-analytics-youbora)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-analytics-youbora)        | [`Youbora`](https://github.com/THEOplayer/react-native-connectors/tree/main/youbora)             |
| Yospace SSAI                                              | [![%40theoplayer/react-native-yospace](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-yospace?label=%40theoplayer/react-native-yospace)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-yospace)                                                | [`Yospace`](https://github.com/THEOplayer/react-native-connectors/tree/main/yospace)             |
| Content protection (DRM)                                  | [![%40theoplayer/react-native-drm](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-drm?label=%40theoplayer/react-native-drm)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-drm)                                                                | [`DRM`](https://github.com/THEOplayer/react-native-theoplayer-drm)                               |
| React Native Open UI                                      | [![%40theoplayer/react-native-ui](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-ui?label=%40theoplayer/react-native-ui)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-ui)                                                                    | [`Open UI`](https://github.com/THEOplayer/react-native-theoplayer-ui)                            |
| A template for<br />`react-native-theoplayer` connectors. | [![%40theoplayer/react-native-connector-template](https://img.shields.io/npm/v/%40theoplayer%2Freact-native-connector-template?label=%40theoplayer/react-native-connector-template)](https://www.npmjs.com/package/%40theoplayer%2Freact-native-connector-template)    | [`Connector template`](https://github.com/THEOplayer/react-native-theoplayer-connector-template) |

## Creating your first app

This section starts with creating a minimal demo app that integrates the `react-native-theoplayer` package, followed by an overview of the available properties and functionality of the THEOplayerView component. An example application including a basic user interface and demo sources is included in the [git repository](https://github.com/THEOplayer/react-native-theoplayer/tree/develop/example), and discussed in the next section.

* [Creating a minimal demo app](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/creating-minimal-app.md)

  * [Getting started on Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/creating-minimal-app.md#getting-started-on-android)
  * [Getting started on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/creating-minimal-app.md#getting-started-on-ios-and-tvos)
  * [Getting started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/creating-minimal-app.md#getting-started-on-web)

* [The THEOplayerView component](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/theoplayerview-component.md)

* [The example application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/example-app.md)

## Knowledge Base

This section gives an overview of features, limitations and known issues:

* [Adaptive Bitrate (ABR)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/abr.md)
* [Advertisements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/ads.md)
* [Android Media3 Pipeline](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/media3.md)
* [Audio Control Management](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/audio-control.md)
* [Background playback and notifications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/background.md)
* [Casting with Chromecast and Airplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/cast.md)
* [Common Media Client Data (CMCD)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/cmcd.md)
* [Digital Rights Management (DRM)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/drm.md)
* [Expo](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/expo.md)
* [Fullscreen presentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/fullscreen.md)
* [Media Caching](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/media-caching.md)
* [Migrating to THEOplayer 9.x](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/migrating-to-react-native-theoplayer-9.md)
* [Migrating to THEOplayer 10.x🔥](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/migrating-to-react-native-theoplayer-10.md)
* [Millicast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/millicast.md)
* [Picture-in-Picture (PiP)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/pip.md)
* [Subtitles, Closed Captions and Metadata tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/texttracks.md)
* [Limitations and known issues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/limitations.md)

## API Reference

See the [API Reference](https://theoplayer.github.io/react-native-theoplayer/api/) for detailed documentation about all available components and functions.

---

# Creating a minimal demo app

In this section we start from an empty React Native template, include a dependency to `react-native-theoplayer`, and deploy it on an Android or iOS device.

A user interface is added using the `@theoplayer/react-native-ui` package.

## Setting up a new project

In the following steps we will be using `npm` as the Node.js package manager.

First initialize a new project with a React Native app template:

```bash
npx @react-native-community/cli init rntheodemo
cd rntheodemo
```

Alternatively use a template that also provides support for tvOS, as it will create a dependency to `react-native-tvos`, a fork of the main React Native branch:

```bash
npx @react-native-community/cli init rntheodemo --template=react-native-template-typescript-tv@6.5.8-0
cd rntheodemo
```

Next, include the dependency to `react-native-theoplayer`.

```bash
npm i
npm i react-native-theoplayer
```

or optionally specifying a specific version of the package:

```bash
npm i react-native-theoplayer@<version>
```

Note: depending on your node version, an extra `--legacy-peer-deps` option has to be added:

```bash
npm i react-native-theoplayer --legacy-peer-deps
```

Finally, replace the `App.tsx` with this minimal code:

```tsx
import React from 'react';
import {View} from 'react-native';
import {PlayerConfiguration, SourceDescription, PlayerEventType, THEOplayer, THEOplayerView} from 'react-native-theoplayer';

const playerConfig: PlayerConfiguration = {
  license: undefined,     // insert THEOplayer React Native license here
};

const source: SourceDescription = {
  sources: [
    {
      src: "https://cdn.theoplayer.com/video/elephants-dream/playlist-single-audio.m3u8",
      type: "application/x-mpegurl"
    },
  ],
};

const onReady = (player: THEOplayer) => {
  player.autoplay = true
  player.source = source;
  player.addEventListener(PlayerEventType.ERROR, console.log);
}

const App = () => {
  return (
    <View style={{position: 'absolute', top: 0, left: 0, bottom: 0, right: 0}}>
      <THEOplayerView config={playerConfig} onPlayerReady={onReady}/>
    </View>
  );
};

export default App;
```

When configuring a stream that is hosted on another server than `cdn.theoplayer.com`, a license for the React Native SDK needs to be obtained through the 'Licenses' built in the [THEOplayer portal](https://portal.theoplayer.com/).

![license\_portal](/pr-932/assets/images/license_portal-b7f8c3d779e5f1ad28c8e3f1f3f2d6ad.png)

## Getting started on Android

After completing the [initial project setup](#setting-up-a-new-project), which is shared for all platforms, the following Gradle buildConfig fields can be used in your `gradle.properties` file to override or set various Android-specific react-native-theoplayer options:

```groovy
# Version of the (Android) THEOplayer SDK, if not specified, the latest available version is set.
#THEOplayer_sdk=9.6.1

# Override Android sdk versions
#THEOplayer_compileSdkVersion = 35
#THEOplayer_minSdkVersion = 21
#THEOplayer_targetSdkVersion = 35

# Toggle player event logging using tag 'VideoPlayer' (default: false)
#THEOplayer_logPlayerEvents = true

# Toggle playerView event logging using tag 'ReactTHEOplayerView' (default: false)
#THEOplayer_logViewEvents = true

# Toggle media session event logging (default: false)
#THEOplayer_logMediaSessionEvents = true

# Enable THEOplayer Extensions (default: disabled)
#THEOplayer_extensionGoogleIMA = true
#THEOplayer_extensionGoogleDAI = true
#THEOplayer_extensionCast = true
#THEOplayer_extensionMediaSession = true
#THEOplayer_extensionTHEOads = true
#THEOplayer_extensionMediaSession = true
#THEOplayer_extensionMillicast = true

# Optionally limit timeUpdate rate, which could improve performance.
# Possible values: (default: UNLIMITED)
# - com.theoplayer.TimeUpdateRate.UNLIMITED
# - com.theoplayer.TimeUpdateRate.LIMITED_ONE_HZ
# - com.theoplayer.TimeUpdateRate.LIMITED_TWO_HZ
# - com.theoplayer.TimeUpdateRate.LIMITED_THREE_HZ
#THEOplayer_timeUpdateRate = com.theoplayer.TimeUpdateRate.LIMITED_TWO_HZ

# Toggle whether to use a media service for background playback
#THEOplayer_usePlaybackService = true

# Toggle whether to reparent the playerView to the top-most node of the view hierarchy when going
# into fullscreen.
# See https://github.com/THEOplayer/react-native-theoplayer/blob/develop/doc/fullscreen.md.
#THEOplayer_reparent_on_fullscreen = true

# Toggle whether to reparent the playerView to the top-most node of the view hierarchy when going
# into PiP.
#THEOplayer_reparent_on_PiP = false
```

For optimal performance, make sure to build your app in release mode, and optionally limit the number of `timeupdate` events send by the player as shown in the config above. A `timeupdate` event typically triggers a number of React Native component updates and could affect performance in negative way.

## Getting started on iOS and tvOS

To define which extra THEOplayer integrations need to be loaded for additional features, a config file needs to be added to you application folder:

Create a json file **\[YourApplicationFolder]/react-native-theoplayer.json**, or **\[YourApplicationFolder]/theoplayer-config.json**, on the same level as the node\_modules folder (both alternatives offer the same functionality).

Edit the file to reflect the features required for your application. The following example adds Google IMA and DAI, Chromecast, THEOads, Millicast and Sideloaded textTracks to the setup. If one of these is out of your applications scope, you can leave it out to reduce the app's size. When using only basic functionality, leave the features array empty.

Example:

```text
{
	"ios": {
		"features": [
			"GOOGLE_IMA",
			"CHROMECAST",
			"THEO_ADS",
			"MILLICAST",
			"SIDELOADED_TEXTTRACKS"
		]
	}
}
```

* **GOOGLE\_IMA**: adds an additional dependency to the THEOplayer-Integration-GoogleIMA cocoapod that delivers the IMA and DAI functionality
* **CHROMECAST**: adds an additional dependency to the THEOplayer-Integration-GoogleCast cocoapod that delivers the chromecast functionality
* **THEO\_ADS**: adds an additional dependency to the THEOplayer-Integration-TheoAds cocoapod that delivers Server Guided Ad Insertion (SGAI) functionality
* **MILLICAST**: adds an additional dependency to the THEOplayer-Integration-Millicast cocoapod that delivers the Millicast functionality
* **SIDELOADED\_TEXTTRACKS**: adds an additional dependency to the THEOplayer-Connector-SideloadedSubtitle cocoapod that delivers the sideloaded texttracks functionality

Once the project has been setup correctly, define a valid HLS, Millicast or THEOlive source, eg.

```typescript
const source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
      type: 'application/x-mpegurl',
    },
  ],
};
```

Some RN templates miss a specific Swift version setting for tvOS. To fix this add a custom build setting to your tvOS app target:

```text
SWIFT_VERSION 5.0
```

Run pod install in your app's ios folder

```bash
pod install
```

## Getting started on Web

Make sure to first complete the [initial project setup](#setting-up-a-new-project), which is shared for all platforms. Deploying a web app requires a little more work. The example uses [react-native-web](https://necolas.github.io/react-native-web/) to support web-based platforms, which translates React Native components to React DOM components. In addition, the project relies on webpack to create the bundle that is loaded in the hosting web page.

We refer to the [example application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/example-app.md) and its [code](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/example/web/) for a full demonstration.

### libraryConfiguration

When passing the `PlayerConfiguration` object while creating the player, the [`libraryConfiguration`](https://www.theoplayer.com/docs/theoplayer/v10/api-reference/web/interfaces/PlayerConfiguration.html#libraryLocation) parameter specifies where the THEOplayer web worker files are located. The worker files are dynamically loaded and necessary to play-out MPEG-TS based HLS streams. By default it is set to the location where npm installed THEOplayer ('./node\_modules/theoplayer').

## Building and running the app

Finally, build and deploy the app. Make sure an emulator is available, or there is a physical device connected to deploy to.

```bash
$ npm run android
$ npm run ios
$ npm run web
```

## Adding a user interface

The `react-native-theoplayer` package does not contain a user interface by default. There is however a separate package that builds a UI on top of the `THEOplayerView` component, `@theoplayer/react-native-ui`.

We refer to the [documentation](https://github.com/THEOplayer/react-native-theoplayer-ui) of `@theoplayer/react-native-ui` on how to install and use it.

---

# The `THEOplayerView` Component

THEOplayer React native SDK is an NPM package, which exposes the THEOplayerView component that can be added to your React Native projects.

![react-native-theoplayer](/pr-932/assets/images/react-native-theoplayer-50e1e6e2dbf74294addbeeed5baa8e36.png)

This section will discuss the most important properties of `THEOplayerView`. The component's properties are also described in detail in its [THEOplayerViewProps interface](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/THEOplayerView.ts).

THEOplayer React Native SDK uses HTML5/ Tizen/ webOS SDK, Android/ Fire TV SDK, and iOS/ tvOS SDK under the hood through bridges that map each THEO SDK API to the THEOplayerView component.

## Properties

The `THEOplayerView` component supports the following list of properties.

| Property          | Description                                                                                                                                                                 | Platforms |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `config`          | The player configuration containing the THEOplayer license and other player-setup related properties                                                                        | All       |
| `style`           | The style applied to the player view.                                                                                                                                       | All       |
| `onPlayerReady`   | A callback that provides the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts) when the player instance is ready. | All       |
| `onPlayerDestroy` | A callback is called when the internal player instance will be destroyed.                                                                                                   | All       |

## Configuration

The `THEOplayerView` component accepts a `config` property that contains basic player configuration.

```typescript
const player: PlayerConfiguration = {
  license: undefined, //'insert THEOplayer license for react-native here'
  chromeless: true,
};
```

The `license` is an obfuscated string that contains the THEOplayer license needed for play-out, and which can be found in your THEOplayer Portal account. You can generate a license specifically for react-native, but if separate licenses per platform are needed, `Platform.select()` could be used to configure them:

```typescript
const license = Platform.select(
  {
    'android': undefined, // insert Android THEOplayer license here
    'ios': undefined,     // insert iOS THEOplayer license here
    'web': undefined,     // insert Web THEOplayer license here
  });
```

If no license is provided, only sources hosted on the `theoplayer.com` domain can be played. On Web platforms, CORS rules applied on `theoplayer.com` will also prohibit playing sources from this domain.

### Adaptive Bitrate (ABR) configuration

On Android and Web platforms, you can control the ABR configuration using `player.abr` on the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts). We refer to the [Adaptive Bitrate (ABR)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/abr.md) page for detailed information, including examples.

### Chromeless vs. Chromefull

`PlayerConfiguration.chromeless` relates to whether the underlying *native* SDK provides the UI or not. If `chromeless = true`, the player does not include the native UI provided by the SDK and it is expected the UI is created in React Native. The accompanying example application provides a basic UI created in React Native.

### Native UI language

`PlayerConfiguration.ui` has a configuration property 'language' that allows you to set the language for localisation when native UI elements (e.g. 'skip ad' being displayed on the skip butten in the ad UI) are presented to the user. This only applies to UI elements rendered by the native SDK's and not to other UI elements added via your react-native view stack.

## Setting a source

You can set a source using the `source` property on the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts). The type definition of `SourceDescription` maps to the type used in the [Web SDK's documentation](https://www.theoplayer.com/docs/theoplayer/v10/api-reference/web/interfaces/SourceDescription.html).

```typescript
player.source = {
    "sources": {
        "src": "https://cdn.theoplayer.com/video/elephants-dream/playlist-single-audio.m3u8",
        "type": "application/x-mpegurl"
    }
}
```

## Seeking to a position in a stream

Changing the player's current time, or seeking to a specific timestamp, is done by setting `currentTime` on the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts). Timestamps are measured in milliseconds.

```typescript
player.currentTime = 20_000; // msec
```

## Text tracks and media tracks

The text tracks and media tracks available in the stream are provided by the `PlayerEventType.LOADED_METADATA` event, which is dispatched by the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts).

```typescript
import { PlayerEventType } from "./PlayerEventMap";
import { LoadedMetadataEvent } from "./PlayerEvent";

const onLoadedMetadata = (event: LoadedMetadataEvent) => {
  console.log(TAG, 'loadedmetadata', JSON.stringify(event));
};

player.addEventListener(PlayerEventType.LOADED_METADATA, onLoadedMetadata)
```

The `PlayerEventType.TEXT_TRACK_LIST` event can be used to dynamically listen to text tracks that are being added, removed or changed. Similarly, for text track cues, the `PlayerEventType.TEXT_TRACK` event provides knowledge on cues being added or removed.

The `PlayerEventType.MEDIA_TRACK_LIST` event can be used to dynamically listen to audio and video tracks (being added, removed or changed). On Android and Web, media tracks trigger the `PlayerEventType.MEDIA_TRACK` callback with information on quality changes. This information is not available on iOS systems.

## Preview thumbnails

Preview thumbnails are contained in a dedicated thumbnail track, which is a text track of kind `metadata` with label `thumbnails`. The track can be either side-loaded to the stream source, or contained in a stream manifest, as the demo sources in the [example application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/example-app.md) demonstrate. The example also contains an implementation of a thumbnail viewer.

## Buffering state changes

The `PlayerEventType.WAITING` event is dispatched to indicate that the player has stopped playback because the next frame's data is currently unavailable, but is expected to come in soon. It could be coupled to an activity indicator that is part of the UI. The `PlayerEventType.PLAYING` event is dispatched once playback continues.

Alternatively, changes in `readyState` could be observed through the `PlayerEventType.READYSTATE_CHANGE` event. Since this value can sometimes switch radically, it is advised to add a time-out when using `PlayerEventType.READYSTATE_CHANGE` in combination with a UI loading indicator.

The UI of the [example application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/example-app.md) illustrates a possible implementation.

---

# Example Application

The example application on our `react-native-theoplayer` [git repository](https://github.com/THEOplayer/react-native-theoplayer/tree/develop/example) demonstrates how the use the player with the `THEOplayerView` component and the UI components from `@theoplayer/react-native-ui`.

The example app depends on [`react-native-tvos`](https://github.com/react-native-tvos/react-native-tvos), a fork of the main `react-native` repository, to properly include support for Apple TV.

In this section we cover building and running the example app. If you would like to know more about the `DefaultTHEOplayerUi` and all the other UI components, visit [our React Native UI project](https://github.com/THEOplayer/react-native-theoplayer-ui).

| ![basic-ui](/pr-932/assets/images/example-app-player-ui-028fd4ae776c8d714aa787cd82c253ab.png) | ![basic-ui-source](/pr-932/assets/images/example-app-source-selection-979c83bc37ef94a4fcbb927019a82470.png) | ![basic-ui-source](/pr-932/assets/images/example-app-thumbnails-c6e829c4ae972be8051033369e3d3629.png) |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| The `DefaultTHEOplayerUi` in action.                                                          | Choosing a demo source from a custom UI component.                                                          | Preview thumbnails.                                                                                   |

## Building the example application

Clone the repository and install the dependencies for the `react-native-theoplayer` package:

```bash
$ git clone react-native-theoplayer
$ cd react-native-theoplayer
$ npm i
```

Install dependencies for the example application:

```bash
$ (cd example && npm i)
```

For iOS and tvOS, also make sure to install pod dependencies

```bash
$ (cd example/ios && pod install)
```

Make sure to configure your [THEOplayer license](https://portal.theoplayer.com/) in the [app config](https://github.com/THEOplayer/react-native-theoplayer/blob/-/example/src/App.tsx).

Finally, after making sure the necessary development tools are installed, build & deploy the example:

```bash
$ cd example
$ npm run android
$ npm run ios
$ npm run web
```

---

# Adaptive Bitrate (ABR)

## Overview

The playback quality during play-out of a stream is determined by the ABR algorithm. On starting play-out of a stream, the ABR `strategy` determines which quality to prefer, while during play-out the network's bandwidth is monitored to select an optimal quality.

More information on ABR can be found on our [THEOplayer website](https://www.theoplayer.com/blog/abr-bandwidth-usage) and [demo page](https://www.theoplayer.com/theoplayer-demo-optimized-video-abr).

In this document we will outline how to affect the ABR algorithm, setting a preferred quality or set of qualities and subscribe to related events.

## ABR Configuration

The [ABR Configuration](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/abr/ABRConfiguration.ts) determines which initial quality the player will download, depending on the chosen strategy, as well as various parameters of the playback buffer.

```tsx
 const onPlayerReady = (player: THEOplayer) => {
  player.abr.strategy = ABRStrategyType.quality;
  player.abr.targetBuffer = 20;
  player.abr.bufferLookbackWindow = 30;
  player.abr.maxBufferLength = 30;
}

<THEOplayerView
  config={playerConfig}
  onPlayerReady={onPlayerReady}
/>
```

| Property               | Description                                                                                                                                                     | Supported Platforms |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `strategy`             | The adaptive bitrate strategy. Possible values are `'performance'`, `'quality'`, `'bandwidth'` or a `ABRStrategyConfiguration` object. Default is **bandwidth** | Android & Web       |
| `targetBuffer`         | The amount that the player should buffer ahead of the current playback position, in seconds. Default is **20**s.                                                | Android & Web       |
| `bufferLookbackWindow` | The amount of data which the player should keep in its buffer before the current playback position, in seconds. Default is **30**s.                             | Web                 |
| `maxBufferLength`      | The maximum length of the player's buffer, in seconds.                                                                                                          | Web                 |

When specifying the strategy, apart from the values `'performance'`, `'quality'`, `'bandwidth'`, an `ABRStrategyConfiguration` object can be set with an estimate for the initial bitrate value (in bits per second):

```typescript
const strategyConfig: ABRStrategyConfiguration = {
  type: ABRStrategyType.bandwidth,
  metadata: {
    'bitrate': 1200000
  }
}
player.abr.strategy = strategyConfig;
```

## Setting Target Video Quality

By default, the ABR algorithm will choose, depending on the available bandwidth, from all the video qualities that are available in the manifest or playlist.

It is possible to set a specific quality, or subset of qualities, that should be retained as a source set by passing the `uid` to the `targetVideoQuality` property on the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts).

```tsx
const selectedVideoQuality: number | number[] | undefined = [33, 34, 35]
player.targetVideoQuality = selectedVideoQuality;
```

## Subscribing to track events

The `onMediaTrackListEvent` and `onMediaTrackEvent` callback properties on `THEOplayerView` provide a way to perform actions when the track list is modified, or when a track's current quality changes:

| Event name              | Event                                                                                                                                                         | Supported Platforms |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `onMediaTrackListEvent` | when a media track list event occurs, for `trackType` with value `Audio` or `Video`, and event `type` with values `AddTrack`, `RemoveTrack` or `ChangeTrack`. | Android & Web       |
| `onMediaTrackEvent`     | when a media track event occurs, for `trackType` with value `Audio` or `Video`, and event `type`, which currently is only `ActiveQualityChanged`.             | Android & Web       |

### Setting a preferred video quality across period switches and discontinuities

Subscribing to the `AddTrack` event on `onMediaTrackListEvent` for video tracks makes it possible set a fixed preferred video quality, even when a stream's track list changes due to a DASH period switch or an HLS discontinuity (for example during an ad break).

```tsx
const onMediaTrackListEvent = (event: MediaTrackListEvent) => {
  const {subType, trackType} = event;
  if (trackType === MediaTrackType.VIDEO && subType === TrackListEventType.ADD_TRACK) {
    const {qualities, activeQuality: currentActiveQuality} = event.track;

    // Try to set a preferreed quality
    const targetQuality = qualities.find(q => q.bandwidth === preferredBandwidth);
    if (targetQuality) {
      const {uid} = targetQuality;
      this.player.targetVideoQuality = uid;
    }
  }
};

const onPlayerReady = (player: THEOplayer) => {
  this.player = player;
  this.player.addEventListener(PlayerEventType.MEDIA_TRACK_LIST, onMediaTrackListEvent)
}

<THEOplayerView
  config={playerConfig}
  onPlayerReady={onPlayerReady}
/>
```

---

# Advertisements

## Overview

A good starting point to get acquainted with THEOplayer's advertising features is THEOplayer's [Knowledge Base](https://www.theoplayer.com/docs/theoplayer/knowledge-base/advertisement/user-guide/).

While THEOplayer supports a wide range of different [ad types](https://www.theoplayer.com/docs/theoplayer/knowledge-base/advertisement/user-guide/#an-overview-of-theoplayers-different-ad-types), `react-native-theoplayer` currently supports:

* client-side ad insertion (CSAI) through [Google IMA](#getting-started-with-google-ima)
* server-side ad insertion (SSAI) through [Google DAI](#getting-started-with-google-dai).
* server-guided ad insertion (SGAI) through [THEOads](#getting-started-with-theoads).

In the next section we discuss how to integrate them on each platform.

Additional functionality, such as scheduling ads at runtime, is provided by the [ads API](#using-the-ads-api).

The final section describes how to subscribe and add custom logic to [ad events](#subscribing-to-ad-events).

## Getting started with Google IMA

### Configuration

First enable Google IMA support, which requires a different approach on each platform.

Android/AndroidTV

The Android SDK is modular-based, so enabling Google IMA is limited to including the ima extension in gradle by setting this flag in your `gradle.properties`:

```text
# Enable THEOplayer Extensions (default: disabled)
THEOplayer_extensionGoogleIMA = true
```

iOS/tvOS

To enable Google IMA you can add the "GOOGLE\_IMA" [feature flag](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/creating-minimal-app.md#getting-started-on-ios-and-tvos) to `react-native-theoplayer.json` (or `theoplayer-config.json`)

Web

To enable Google IMA on web, it suffices to add this script in the web page's header section, as shown in the example app's [index.html](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/example/web/public/index.html):

```html

<head>
  <!-- Optionally load Google IMA/DAI libraries -->
  <script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
</head>
```

### Source description

When providing the player with a source that includes a list of ads, make sure to set the `integration` property to `"google-ima"`, as shown in one of the sources of the example app:

```typescript
const imaSource = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/dash/webvtt-embedded-in-isobmff/Manifest.mpd',
      type: 'application/dash+xml',
    },
  ],
  ads: [
    {
      integration: 'google-ima' as AdIntegrationKind,
      sources: {
        src: 'https://cdn.theoplayer.com/demos/ads/vast/dfp-preroll-no-skip.xml',
      },
    },
  ],
};
```

The API's [`AdSource`](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/source/ads/Ads.ts) description provides additional information on the configurable properties.

It is also possible to pass a configuration to the IMA SDK via the `ads` API. For more information see the [GoogleImaConfiguration API](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/src/api/ads/GoogleImaConfiguration.ts).

## Getting started with Google DAI

First enable Google DAI support, which requires a different approach on each platform.

Android/AndroidTV

The Android SDK is modular-based, so enabling Google DAI is limited to including the dai extension in gradle by enabling this flag in your `gradle.properties`:

```text
# Enable THEOplayer Extensions (default: disabled)
THEOplayer_extensionGoogleDAI = true
```

Note that DAI support for Android is available as of SDK version 4.3.0.

iOS

Google DAI is part of the Google IMA SDK. To enable it, you add the "GOOGLE\_IMA" [feature flag](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/creating-minimal-app.md#getting-started-on-ios-and-tvos) to react-native-theoplayer.json (or theoplayer-config.json)

Web

To enable Google DAI on web, it suffices to add this script in the web page's header section, as shown in the example app's [index.html](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/example/web/public/index.html):

```html

<head>
  <!-- Optionally load Google IMA/DAI libraries -->
  <script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
</head>
```

### Source description

Providing a Google DAI source description to the player requires providing an `ssai` object and specifying `"google-dai"` as integration type:

```typescript
const daiSource = {
  sources: {
    ssai: {
      integration: 'google-dai',
      availabilityType: 'vod',
      contentSourceID: '2528370',
      videoID: 'tears-of-steel',
    } as GoogleDAIVodConfiguration,
  },
};
```

A full description of the available source properties can be found in the [API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/source/ads/ssai/GoogleDAIConfiguration.ts) definition.

## Getting started with THEOads

THEOads is an ad-insertion service for both VOD and LIVE content, created by THEO Technologies, utilizing Server-Guided Ad-Insertion (SGAI). For more information we refer to the [THEOads](https://www.theoplayer.com/docs/theoads/) documentation.

## Using the Ads API

[THEOplayer](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts) provides an [AdsAPI](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/ads/AdsAPI.ts) that enables additional features such as:

* Querying whether an ad is currently playing;
* Skipping the current ad (if possible);
* Getting the ad break that is currently playing;
* Getting a list of ads that are currently playing (only available for web);
* Getting a list of ad breaks that are still scheduled. Once an ad break starts, it is removed from the list;
* Manually scheduling a client-side ad.

The `THEOplayer` is provided with a callback on the `THEOplayerView` component:

```tsx
const onPlayerReady = (player: THEOplayer) => {
  this.player = player;
}

<THEOplayerView onPlayerReady={onPlayerReady}/>
```

After which the AdsAPI can be used:

```typescript
const isPlayingAd = () => {
  return this.player.ads.playing();
};
```

Google DAI has its own [API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/ads/GoogleDai.ts), which includes DAI-specific features, such as converting time stamps between stream time and content time, and manipulating the `snapback` flag that prevents users from seeking across ad breaks.

```typescript
// Convert timestamps using the DAI ads api.
const streamTimeForContentTime = (contentTime: number): Promise<number> | undefined => {
  return this.player.ads.dai?.streamTimeForContentTime(contentTime);
};
```

### Manually scheduling a client-side ad

The Ad API allows you to manually schedule an ad break at runtime:

```tsx
player.ads.schedule({
  integration: AdIntegrationKind.google_ima,
  timeOffset: 1e-3 * (player?.currentTime ?? 0) + 3, // in 3 seconds from now
  // timeOffset: 10,    // at 10 seconds in the content
  // timeOffset: '50%', // at 50% of the content duration
  sources: {
    src: 'https://cdn.theoplayer.com/demos/ads/vast/dfp-preroll-no-skip.xml',
  },
});
```

## Subscribing to ad events

[THEOplayer](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts) allows you to subscribe to ad events:

```typescript
const onAdEvent = (event: AdEvent) => {
  console.log(event)
}
player.addEventListener(PlayerEventType.AD_EVENT, onAdEvent);
```

See [AdEvent](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/event/AdEvent.ts), [Ad](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/ads/Ad.ts) and [AdBreak](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/ads/AdBreak.ts) for more information.

Note that the availability of the events being dispatched depends on the platform.

---

# Audio Control Management on Android

## Overview

Android allows multiple apps to play audio concurrently, but this can lead to a disruptive user experience due to mixed audio streams. To enhance user experience, Android offers an API for apps to control **audio focus**, ensuring only one app possesses audio focus, thus delivering a more favorable user experience.

This section details how `react-native-theoplayer` addresses changes in audio focus, which is available as of version 2.12.0.

References:

* [Android for Developers: Audio focus](https://developer.android.com/reference/android/media/AudioFocusRequest)
* [Android for Developers: "Don't be Noisy"](https://developer.android.com/guide/topics/media/platform/output#becoming-noisy)

## Audio Focus

The `react-native-theoplayer` package is equipped with inherent audio focus management. It initiates an audio focus request upon the start of playback and responds to the loss of audio focus by pausing playback.

If the loss was *transient*, i.e. lasting only for a short while such as during an incoming phone call, the player will regain audio focus afterward and play-out while resume.

### Audio "ducking"

When another app seeks audio focus, it can optionally indicate that the current audio focus holder can lower its playback volume to continue playing (`AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK`). The new focus holder does not require other apps to be silent. This behavior is known as "ducking."

In summary:

| Event                                          | Action                            |
| ---------------------------------------------- | --------------------------------- |
| `AUDIOFOCUS_LOSS`, `AUDIOFOCUS_LOSS_TRANSIENT` | Pause play-out                    |
| `AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK`           | Lower volume                      |
| `AUDIOFOCUS_GAIN`                              | Resume play-out or restore volume |

## Audio Becoming Noisy

When headphones are unplugged or a Bluetooth device is disconnected, the audio stream automatically reroutes to the device's built-in speaker. This can lead to an abrupt increase in volume, which is an undesired outcome.

The "Audio Becoming Noisy" situation is also managed by pausing playback for the `react-native-theoplayer` package.

---

# Background Playback and Notifications

## Overview

One of the key features of `react-native-theoplayer` is its support for background playback, notifications, and lock-screen controls. This feature allows your users to continue listening to audio when the app is not in the foreground, and control playback using notifications and lock-screen controls.

## Configuration

The `backgroundAudioConfiguration` player configuration affects the play-out behaviour when the app is moved to the background: in case the `enabled` property is set to `true`, the current media asset will continue playing when the app is moved to the background, otherwise play-out will pause.

The configuration can be modified at run-time, allowing the player to pause depending on the current media asset's properties, or whether an ad is playing or not.

```typescript
player.backgroundAudioConfiguration = { enabled: true };
```

Other properties of the `backgroundAudioConfiguration` can be used to further customize the background playback:

| Field                           | Platform           | Purpose                                                                                                                                                               | Default                           |
| ------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `enabled`                       | Web, iOS & Android | If enabled, playback continues when transitioning to background.                                                                                                      | `false`                           |
| `stopOnBackground`              | Web, iOS & Android | If enabled, fully stop playback when the app goes to the background. The player will need to be provided with a new source when the app comes back to the foreground. | `false`                           |
| `shouldResumeAfterInterruption` | iOS                | Controls whether playback should automatically resume after an interruption, such as an incoming phone call.                                                          | `false`                           |
| `audioSessionMode`              | iOS                | Specifies the [AVAudioSession.Mode](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode)                                                           | `AudioSessionMode.MOVIE_PLAYBACK` |

A use case for enabling `stopOnBackground` could be a live stream that should not be allowed to continue in the background, neither in paused nor playing state. The app should be designed to reload the source or the player page when coming back to the foreground.

### Android

On Android, a [service](https://developer.android.com/guide/components/services) is used to continue playback in the background while the user is not interacting with the app.

It is possible to disable the service at build time by setting the build config field `'THEOplayer_usePlaybackService = false'`. In that case the background playback feature is always disabled, no notifications are displayed, and the player will always pause when the hosting app goes to the background.

## Notifications, Metadata and Lockscreen Controls

During play-out of a media asset, a notification is displayed that provides some metadata and enables basic control. The source description passed to the player should provide the necessary metadata properties:

```typescript
const source = {
  // ...
  poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
  metadata: {
    title: 'My stream title',
    subtitle: 'A subtitle or artist',
    nowPlayingServiceIdentifier: 'serviceId',
    nowPlayingContentIdentifier: 'contentId',
    displayIconUri: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
  }
}
```

The following fields from the source description are used to display information in the lockscreen:

| Field                                                                | Purpose           |
| -------------------------------------------------------------------- | ----------------- |
| `source.metadata.title`                                              | Lockscreen title  |
| `source.metadata.artist` with fallback to `source.metadata.subtitle` | Lockscreen artist |
| `source.metadata.displayIconUri` with fallback to `source.poster`    | Lockscreen image  |

The following fields allow additional configuration for the lockscreen behaviour on iOS:

| Field                                         | Purpose                          |
| --------------------------------------------- | -------------------------------- |
| `source.metadata.nowPlayingServiceIdentifier` | Info property service identifier |
| `source.metadata.nowPlayingContentIdentifier` | Info property content identifier |

| ![notification\_android](/pr-932/assets/images/notification_android-d782297b7b92dc30e196b0000efdd7a7.png) | ![notification\_ios](/pr-932/assets/images/notification_ios-3ac8d1563482c7b4728aa098f9034dbc.png) | ![notification\_web](/pr-932/assets/images/notification_web-9e1124ac683eb295ff71adea39052c50.png) |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Android                                                                                                   | iOS                                                                                               | Web                                                                                               |

### Configuration

The `mediaControl` property of `PlayerConfiguration` hosts properties that affect the notifications, media sessions and controls on each platform. The following table describes the available configuration options:

| Field                  | Platform           | Purpose                                                                                                                                                                        | Default                         |
| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
| `mediaSessionEnabled`  | Web & Android      | If disabled, no media session properties or actions will be set.                                                                                                               | `true`                          |
| `skipForwardInterval`  | Web, iOS & Android | If disabled, no media session properties or actions will be set.                                                                                                               | `5` (Web & Android), `15` (iOS) |
| `skipBackwardInterval` | Web, iOS & Android | If disabled, no media session properties or actions will be set.                                                                                                               | `5` (Web & Android), `15` (iOS) |
| `convertSkipToSeek`    | iOS & Android      | A flag that allows next/previous track commands to be interpreted as skip forward/backward commands, according to the configured skip intervals.                               | `false`                         |
| `allowLivePlayPause`   | iOS & Android      | A flag that indicates whether play/pause controls for live streams are enabled.                                                                                                | `true` (iOS), `false` (Android) |
| `seekToLiveOnResume`   | iOS & Android      | A flag that controls whether to seek to the live edge when resuming a paused live stream. Note that `allowLivePlayPause` needs to be enabled for this property to have effect. | `false`                         |

---

# Casting with Chromecast and Airplay

## Overview

The basics of both Chromecast and Airplay are well-described in THEOplayer's [Knowledge Base](https://www.theoplayer.com/docs/theoplayer/how-to-guides/cast/chromecast/introduction/). The `react-native-theoplayer` package has support for both.

This page first outlines the setup needed for Chromecast and Airplay, and then describes the player's cast API and events subscription, which is common for both.

## Chromecast

### Setup

To enable Chromecast, react-native-theoplayer provides a cast module on the player (player.cast) that allows you to start/stop/join/leave chromecast sessions. The THEOplayer SDK will take care of the interactions with the cast receiver (communicating source updates, seeking, play/pause, ...) and route all cast events through its API.

We can also recommend the [`react-native-google-cast`](https://github.com/react-native-google-cast/react-native-google-cast) package, which comes with native support for both iOS and Android. It is fully-featured and provides the possibility to manage devices and cast sessions, send new source descriptions and listen for cast events. It also includes a `<CastButton>` component that can be added to the app's UI, as demonstrated in the [example app](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/example-app.md).

```tsx
<CastButton
  style={styles.castButton}
  tintColor={chromecastConnected ? '#ffc50f' : 'white'}
/>
```

This button represents a native media route button that shows the connection state and opens a device dialog when tapped. Using `react-native-google-cast`'s functionality does require some extra steps, such as communicating source updates, managing player status on both sender and receiver and handling the cast events. Our react-native-theoplayer integration already takes care of these tasks. The [installation instructions](https://react-native-google-cast.github.io/docs/getting-started/installation) for `react-native-google-cast` cover the steps to enable support for Chromecast in your app through that component.

For the rest of this document we assume that THEOplayer handles this logic. Enabling the player with Chromecast support requires a different approach on each platform.

Android

The Android SDK is modular-based, so enabling Chromecast is limited to:

1. Including the cast extension in gradle by setting this flag in your `gradle.properties`:

```bash
# Enable THEOplayer Extensions (default: disabled)
THEOplayer_extensionCast = true
```

2. Adding a native `CastOptionsProvider` class and referring to it from the app's Android manifest:

```xml
<meta-data
  android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
  android:value="com.reactnativetheoplayer.cast.CastOptionsProvider" />
```

Check the example app for details on this setup.

3. Initializing the `CastContext` in your app's MainActivity:

```java
@Override
public void onCreate(Bundle savedInstanceState) {
    CastContext castContext = CastContext.getSharedInstance(this);
}
```

iOS

#### Add feature flag to config

To enable Chromecast you need to add the "CHROMECAST" [feature flag](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/creating-minimal-app.md#getting-started-on-ios-and-tvos) to react-native-theoplayer.json (or theoplayer-config.json)

#### iOS Configuration

Specify NSBonjourServices in your Info.plist to allow local network discovery to succeed on iOS 14. You will need to add both \_googlecast.\_tcp and \_\[your-app-id].\_googlecast.\_tcp as services for device discovery to work properly.

Update your applications info.plist with the following example NSBonjourServices definition, replacing "ABCD1234" with your appID.

```xml

<key>NSBonjourServices</key>
<array>
<string>_googlecast._tcp</string>
<string>_ABCD1234._googlecast._tcp</string>
</array>
```

We also recommend that you customize the message shown in the Local Network prompt by adding an app-specific permission string in your app's Info.plist file for the NSLocalNetworkUsageDescription such as to describe Cast discovery and other discovery services.

```xml

<key>NSLocalNetworkUsageDescription</key>
<string>${PRODUCT_NAME} uses the local network to discover Cast-enabled devices on your WiFi
network.
</string>
```

#### Combining with react-native-google-cast

When using react-native-google-cast to render the CastButton, their documentation suggest to setup the CastContext as soon as possible. We noticed that waiting to prepare this context to a later point in time (i.e. till the AppId is bridged from RN) fails to display that CastButton. To prevent this follow the [instructions](https://react-native-google-cast.github.io/docs/getting-started/setup#ios) (or check our example application) to setup the GCKCastContext in the AppDelegate.

The following options on the GCKCastOptions can be set as desired:

1. options.startDiscoveryAfterFirstTapOnCastButton = false; (set up how/when the castbutton is shown)
2. options.suspendSessionsWhenBackgrounded = false; (set up the connection response be when backgrounding the app)

In addition, react-native-google-cast currently does not include a full featured (guest mode combined with Apple M1 support) setup of the Google Cast SDK. Our THEOplayerCastIntegration however does, but combining both results in a clash of dependencies (both delivering a GoogleCast.xcframework). To overcome this double dependency we suggest to use a [fork of react-native-google-cast](https://github.com/Danesz/react-native-google-cast/tree/feature/guestmode_apple_silicon) that depends on the same GoogleCast.xcframework. To achieve this:

1. Add the following to your applications podFile:

```ruby
pod 'react-native-google-cast', :git => 'https://github.com/Danesz/react-native-google-cast.git', branch: 'feature/guestmode_apple_silicon'
```

2. Prevent the autolinking of the original by updating your react-native.config.js with:

```json
'react-native-google-cast': {
	platforms: {
		ios: null,
	},
},
```

Web

The `react-native-google-cast` package has no support for Web yet. If the THEOplayer Web SDK's default UI is used however, the cast button will be included here and there is no need to install `react-native-google-cast`.

The web page hosting the player just needs to load the Google cast sender module:

```html

<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
```

### THEOplayerView configuration

In the configuration of a `THEOplayerView` component you can set the receiver's appID. This only makes sense on a Web platform, as for mobile platforms this value is already set natively through `CastOptionsProvider` on Android and `AppDelegate` on iOS:

```javascript
const playerConfig: PlayerConfiguration = {
  cast: {
    chromecast: {
      appID: '<receiverAppID>'
    },
    strategy: 'auto'
  }
}
```

The [example app](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/example-app.md) sets appID to `'CC1AD845'`, which refers to Google's default V3 receiver. This receiver implementation will know how to play the manifest/playlist URL sent by THEOplayer, but it does not have knowledge on how to handle any additional information from the source description provided through the `MediaInfo.customData` [field](https://developers.google.com/android/reference/com/google/android/gms/cast/MediaInfo.Builder#public-mediainfo.builder-setcustomdata-jsonobject-customdata). As a consequence, to enable playback of for example DRM-protected streams or ads, a custom receiver needs to be created that also handles these parts of the source description.

We refer to our [sample-google-cast-v3-receiver](https://github.com/THEOplayer/samples-google-cast-v3-receiver/) repository for an example on how to interpret a THEOplayer source description and handle a custom DRM flow.

### Cast strategy

The `strategy` property indicates the *join strategy* that will be used when starting/joining sessions:

* `auto`: The player will automatically join a cast session if one exists when play is called.
* `manual` (**default**): The player needs to start or join the session manually using its cast API. See next section for details.
* `disabled`: The player is not affected by cast sessions and is not castable.

In case the join strategy `manual` is chosen and a cast session is started by `react-native-google-cast`, it is necessary to explicitly let the player either join or take over the current session. This can be done by listening to the cast state and using the player's cast API to either start or join:

```typescript
import CastContext, {CastState} from "react-native-google-cast";

useEffect(() => {
  const subscription = CastContext.onCastStateChanged((castState) => {
    if (castState === CastState.CONNECTED) {
      // Let the player either start or join the session.
      player.cast.chromecast?.start();
    }
  })
  return () => subscription.remove()
}, [])
```

The [example app](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/example-app.md) uses strategy `auto` so the player will automatically send its source description when a session is created.

### Providing metadata

The `metadata` object, as part of the source configuration, is used to send additional information to the receiver. Common fields include `poster`, `title`, `subtitle`, `album` and `artist`.

```json
{
  "sources": [
    {
      "src": "https://cdn.theoplayer.com/video/dash/bbb_30fps/bbb_with_multiple_tiled_thumbnails.mpd",
      "type": "application/dash+xml"
    }
  ],
  "poster": "https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg",
  "metadata": {
    "title": "Big Buck Bunny",
    "subtitle": "a Peach Open Movie Project",
    "album": "React-Native THEOplayer demos",
    "artist": "THEOplayer"
  }
}
```

| ![Chromecast](/pr-932/assets/images/chromecast-7c3da07d98fad160f3f582a8b7459607.png) |
| ------------------------------------------------------------------------------------ |
| Casting a stream with metadata.                                                      |

## AirPlay

On iOS and Web Safari, along with Chromecast, AirPlay is also supported. Similar to Chromecast, you can listen to or check the AirPlay cast state and use the player's AirPlay API to either start or join an AirPlay session. When implementing a simple AirPlay button you can toggle AirPlay using:

```typescript
player.cast.airplay?.state().then((airplayCastState) => {
  const inConnection = airplayCastState === 'connected' || airplayCastState === 'connecting'
  if (inConnection) {
    player.cast.airplay?.stop()
  } else {
    player.cast.airplay?.start()
  }
})
```

## Cast API

The `THEOplayerView` provides the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts) using the `onPlayerReady` callback, where you can access the [CastAPI](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/event/CastEvent.ts) to control or start cast sessions, either Chromecast or AirPlay.

## Subscribing to Cast Events

The `THEOplayerView` provides the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts) using the `onPlayerReady` callback, where you can subscribe to cast events:

```tsx
const onCastEvent = (event: CastEvent) => {
    console.log(event);
}

const onReady = (player: THEOplayer) => {
    player.addEventListener(PlayerEventType.CAST_EVENT, onCastEvent);
}

<THEOplayerView onPlayerReady={onReady}/>
```

---

# Getting started with CMCD on React Native

Media player clients can transmit useful information to Content Delivery Networks (CDNs) with each object request. This implementation supports Common Media Client Data (CMCD) as defined in [CTA-5004](https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf), published in September 2020.

## Usage

To enable CMCD, developers can set the `cmcd` parameter inside a SourceDescription.

```tsx
const source = {
  sources: [ /* ... */ ],
  /* ... */
  cmcd: {
    transmissionMode: CmcdTransmissionMode.SDK_DEFAULT
    /* ... */
  }
} as SourceDescription;
player.source = source;
```

By specifying the `transmissionMode` as `SDK_DEFAULT`, we let each SDK decide which transmission mode to use:

* Web: HTTP query argument
* iOS: custom HTTP request header (only option)
* Android: HTTP query argument

On Web and Android, you can force a specific transmission mode by providing a different value, e.g.

```tsx
const source = {
  sources: [ /* ... */ ],
  /* ... */
  cmcd: {
    transmissionMode: CmcdTransmissionMode.HTTP_HEADER
    /* ... */
  }
} as SourceDescription;
player.source = source;
```

On Web, there are additional configuration options. For more details, visit the API references.

## Remarks

* Note that CMCD is only supported on iOS 18.0+.
* Note that CMCD is only supported with the [Media3 integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/media3.md) on Android.
* Note that using a custom HTTP header from a web browser user-agent will trigger a preflight OPTIONS request before each unique media object request. This will lead to an increased request rate against the server. As a result, for CMCD transmissions from web browser user-agents that require CORS-preflighting per URL, the preferred mode of use is query arguments.

---

# Digital Rights Management (DRM)

## Overview

This section outlines how play-out of DRM protected content can be achieved with `react-native-theoplayer`. A detailed explanation on how DRM (Digital Rights Management) works can be found in [THEOplayer's knowledge base](https://www.theoplayer.com/docs/theoplayer/knowledge-base/content-protection/introduction/).

## Configuration

THEOplayer supports Fairplay, PlayReady and Widevine by default. Configuring a DRM protected stream source with `react-native-theoplayer` is very similar to how it is done for the Web SDK, by providing a `contentProtection` object in the source description.

```javascript
const source = {
  src: "<manifest>",
  type: "application/dash+xml",
  contentProtection: {
    widevine: {
      licenseAcquisitionURL: "https://widevine-dash.ezdrm.com/proxy?pX=..."
    },
    playready: {
      licenseAcquisitionURL: "https://playready.ezdrm.com/cency/preauth.aspx?pX=..."
    },
    fairplay: {
      certificateURL: 'https://fps.ezdrm.com/demo/video/eleisure.cer',
      licenseAcquisitionURL: 'https://fps.ezdrm.com/api/licenses/...'
    }
  }
}
const onReady = (player: THEOplayer) => {
  player.source = source;
}

<THEOplayerView onPlayerReady={onReady}/>
```

## Content Protection Integrations

### Pre-integrations

THEOplayer is [pre-integrated](https://www.theoplayer.com/docs/theoplayer/how-to-guides/drm/introduction/#pre-integrations) with a number of commercial multi-DRM vendors, which means support for these vendors is already included and enabled in the SDK.

In addition to these pre-integrations, the `react-native-theoplayer` SDK as well as all native THEOplayer SDKs, come with the ability to create and register a custom DRM integration.

### Creating a custom protection integration

The implementation of a custom DRM integration for `react-native-theoplayer` is almost identical to the implementation for the Web SDK, and is explained in detail on our [THEOplayer DRM integrations](https://github.com/THEOplayer/samples-drm-integration) repository. This repository also contains a number of examples for well-known multi-DRM vendors.

### Registering a custom protection integration

Once the custom DRM integrations is created, it needs to be registered up-front as follows:

```text
import { ContentProtectionRegistry } from 'react-native-theoplayer';
import { MyCustomFairplayContentProtectionIntegrationFactory } from './drm/MyCustomFairplayContentProtectionIntegrationFactory';

ContentProtectionRegistry.registerContentProtectionIntegration(
  'myCustomDRM',
  'fairplay',
  new MyCustomFairplayContentProtectionIntegrationFactory()
);
```

Finally, the `integrationId` used on registration (in this case `"myCustomDRM"`) should be added to the sourceDescription so that THEOplayer knows which integration to use for this source. Any additional `integrationParameters` needed by the custom integration can be passed here as well.

```javascript
const source = {
  src: "<manifest>",
  type: "application/dash+xml",
  contentProtection: {
    fairplay: {
      certificateURL: 'https://example.domain.com/Certificate.cer',
      licenseAcquisitionURL: 'https://example.domain.com/FairPlay'
    },
    integration: "myCustomDRM",
    integrationParameters: {
      authToken: "<token>",
    }
  }
}
```

---

# Expo

## Overview

[Expo](https://expo.dev/) is an open-source platform built around React Native that simplifies the development of cross-platform mobile applications. It provides a powerful set of tools, libraries, and services that handle much of the native configuration and boilerplate typically required when working directly with React Native.

React Native THEOplayer integrates with Expo through a **dedicated plugin** that allows you to configure the app **without modifying native files**. Currently, the plugin is focused on enabling configuration of THEOplayer extensions.

### THEOplayer Extensions

The `react-native-theoplayer` package includes an Expo plugin that enables THEOplayer extensions through configuration in your app’s `app.json`.

You can configure it globally for all platforms:

```json
{
  "expo": {
    "plugins": [
      [
        "react-native-theoplayer",
        {
          "extensions": ["cast", "dai", "ima", "millicast", "theoads"]
        }
      ]
    ]
  }
}
```

Or specify extensions per platform:

```json
{
  "expo": {
    "plugins": [
      [
        "react-native-theoplayer",
        {
          "ios": {
            "extensions": ["cast", "ima", "millicast", "sideloaded-texttracks","theoads"]
          },
          "android": {
            "extensions": ["cast", "dai", "ima", "millicast", "theoads"]
          }
        }
      ]
    ]
  }
}
```

---

# A Fullscreen Video Player Component

## Fullscreen Video on Web platforms

Transitioning to fullscreen on Web platforms varies depending on the browser.

Browsers that support the [Fullscreen API](https://fullscreen.spec.whatwg.org/) (Chrome, Firefox, Edge, etc.), allow any element to enter fullscreen mode. However, some - like Safari on iOS - restrict fullscreen access to `<video>` elements only.

While this mechanism is hidden from users of the `react-native-theoplayer` SDK, it does affect the resulting user interface.

On browsers that support the Fullscreen API, the player view together with its UI (a child component) will enter fullscreen mode. On the others, a UI with limited **native controls** will be displayed instead.

| ![](/pr-932/assets/images/fullscreen_chrome-6083662fda8a3afc00c6b8e6fa28cb3d.png) | ![](/pr-932/assets/images/fullscreen_ios_safari-5f157710d5ae0aed7fb8584e7fcd22c3.png) |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Fullscreen presentation mode in a Chrome browser.                                 | Fullscreen presentation mode with native controls in iOS Safari.                      |

## Fullscreen Video on iOS and Android

Presenting a fullscreen video player on iOS and Android through React Native poses challenges due to the need to seamlessly transition between the regular view and fullscreen mode, while maintaining playback continuity. This involves managing UI layers, native view hierarchies, and minimizing disruptions during the transition process.

In this section we will present two ways of presenting a fullscreen player component. One that **opens a new screen to present the player**, and a second that **transitions to fullscreen from an inline player**. We will also discuss the related concept of "React Portals", which, when paired with a video player component, offer versatile applications beyond fullscreen display.

### Presenting a fullscreen video player

A native iOS or Android video player that transitions into fullscreen typically creates another activity or view that *overlays the existing view stack*, while activating an immersive mode to maximize screen size. This also introduces a new user interface layer that includes essential playback controls and a method for exiting fullscreen mode.

React Native, as a UI framework, makes it possible to create a screen with UI elements such a buttons and text elements, and provides a means to create stacked views with packages such as [react-native-navigation](https://reactnavigation.org/). It manages the lifecycle of the native UI elements, and may encounter issues when elements are generated outside its control.

When an app integrates a video player that needs the ability to present itself in fullscreen mode, there are typically two possibilities to transition to the fullscreen player:

### 1. A separate player screen

Navigate to a *separate player screen* that contains only the video player presented in an immersive mode.

The first option has the advantage that it is simple and straightforward to implement. The main disadvantage is that transitioning to another screen means recreating (remounting) the player, causing a visual interruption in playback. Typically, this option is used when the first screen has an inline preview image that transitions to a fullscreen player screen when tapped.

### 2. An inline video player

Make the current *inline video player* component stretch itself while covering all elements in the current screen.

The second option is able to let a video play inline with the other screen elements. The player is a part of the view hierarchy and will need to cover the whole screen without remounting the player component.

| ![](/pr-932/assets/images/fullscreen_android-f913c5b9498410bbd0d02e4a622cdff2.gif) | ![](/pr-932/assets/images/fullscreen_ios-eff1f4d528cc8f9f413d3e9ff2d3ddaf.gif) |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Transitioning from an inline player to fullscreen on Android.                      | Transitioning from an inline player to fullscreen on iOS.                      |

The `react-native-theoplayer` SDK supports this option on iOS and Android by **re-parenting** the native view to the top-most node of the view hierarchy when the player's presentation mode is set to `fullscreen`, creating a seamless experience.

```ts
import { PresentationMode } from './PresentationMode';

player.presentationMode = PresentationMode.fullscreen;
```

When the player transitions back to inline mode, the view hierarchy will be restored.

Any child of the`THEOplayerView` component, typically the user interface, will move as well through the view hierarchy.

### Disable re-parenting on Android

On Android, it is possible to disable the re-parenting mechanism by setting build flag `THEOplayer_reparent_on_fullscreen=false` in the app's gradle properties. This could be useful if your app wants to implement its own logic, or re-parent to a different node than the top-most one. [Immersive mode](https://developer.android.com/develop/ui/views/layout/immersive) will still be enabled in this case.

### iOS home indicator

On iOS, a visual bar at the bottom of the screen called the home indicator, allows the user to return to the device's home screen when dragging it up. This is often preceived as a disturbing visual element when viewing a stream in fullscreen mode. To hide the home indicator, The rootViewController of the application needs to be setup accordingly, via inheritance. As part of react-native-theoplayer we've prepared a basic ViewController setup (HomeIndicatorViewController) that takes care of this. To hide the home indicator you change the default rootViewcontroller from a basic UIViewController to our HomeIndicatorViewController:

Import the react-native-theoplayer swift code:

```swift
@import react_native_theoplayer;
```

And, when using RCTAppDelegate in the native app:

```swift
- (UIViewController *)createRootViewController {
  return [HomeIndicatorViewController new];
}
```

or otherwise:

```swift
HomeIndicatorViewController *rootViewController = [HomeIndicatorViewController new];
...
self.window.rootViewController = rootViewController;
```

Our iOS presentationMode changing code checks if the `rootViewController` is of type `HomeIndicatorViewController` and will, in that case, automatically take care of showing/hiding the home indicator.

## Portals for iOS and Android

A [Portal](https://react.dev/reference/react-dom/createPortal#usage) is a well-known concept in React that enables rendering a component in a different location in the DOM view hierarchy. Normally, when a component is rendered, it is mounted into the DOM as a child of the nearest parent node. Sometimes, however, it is useful to let the child mount at a different location in the DOM tree. Internally, the portal will also re-parent the view to a different node in the view hierarchy, similar to the approach `react-native-theoplayer` takes when going to fullscreen.

A typical use case is when the child component needs to "break out" of its container. Examples are dialogs, tooltips, and floating or fullscreen video components. In the next section we will outline the creation of an in-app mini player.

### Using Portals to transition to an in-app mini player

This section introduces a basic example illustrating how Portals facilitate the creation of an inline video component capable of transitioning to a mini player at the bottom of the screen, overlaying the other components.

There are many packages available that bring Portal functionality to React Native. However, we will use [a package](https://www.npmjs.com/package/@alexzunik/rn-native-portals-reborn) that not only renders the component to an alternate location in the DOM tree, but also *relocates the native view to a different parent in the native view hierarchy*. This approach aims to prevent the remounting of the complex video component.

```tsx
export default function App() {
  const [isMiniPlayer, setMiniPlayer] = useState(false);

  const onPlayerReady = (player: THEOplayer) => {
    // set-up player
  }

  return (
    <View style={styles.container}>
      <PortalOrigin destination={isMiniPlayer ? 'miniplayer' : null}>
        <View style={isMiniPlayer ? styles.videoContainerMini : styles.videoContainer}>
          <THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}>
            {player !== undefined && (<UiContainer>{/*left out for clarity*/}</UiContainer>)}
          </THEOplayerView>
        </View>
      </PortalOrigin>

      <View style={styles.contentContainer}>
        <Text style={{ color: '#ffffff' }}>This text will remain on screen when play-out continues into the mini-player.</Text>
      </View>

      <View style={isMiniPlayer ? styles.miniContainer : styles.miniContainerInactive}>
        <PortalDestination name="miniplayer" />
      </View>
    </View>);
}
```

The player component along with its UI container in the example above is wrapped in a `PortalOrigin`. Its destination is left `null` as long as the player is presented inline.

When the `isMiniPlayer` state property is set to `true`, the screen is re-rendered with destination set to `'miniplayer'`. The player component will become a child of the `PortalDestination` with the same name. On a native level the view will also be re-parented to the miniPlayer container at the bottom of the screen.

| ![](/pr-932/assets/images/miniplayer_android-717e2a8d9844bf570d423d5dfe954ff8.gif) | ![](/pr-932/assets/images/miniplayer_ios-0682a98a45d38d6ff021b3aa2b39c82f.gif) |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| A mini-player using Portals on Android                                             | A mini-player using Portals on iOS                                             |

Variants of the approach discussed above put the `PortalDestination` on a dedicated route in a [`NavigationContainer`](https://reactnavigation.org/docs/navigation-container/). This is especially useful in a more complex app that has different routes towards showing the player component.

---

# Limitations and Known Issues

This sections lists any limitations and known issues in the current package version.

## Custom-built THEOplayer SDKs

Dependencies to the underlying THEOplayer SDKs are currently configured in the `react-native-theoplayer` package using various dependency managers:

* Android: Gradle & Maven
* iOS & tvOS: Cocoapods
* Web: npm

This currently poses a limitation on the ability to include a SDK that is custom-built through [THEOplayer Portal](https://portal.theoplayer.com/). A custom-built library (an .aar of Android, framework for iOS and JavaScript library for web) including a specific set of features currently still needs to be configured inside `react-native-theoplayer` package itself.

---

# Media Cache

## Overview

The Media Cache API is available as of v3.0.0 and facilitates the download of media assets for offline playback. This section provides an overview of how to utilize the Media Caching API, create caching tasks, and control the media cache.

The process of caching a media asset involves several steps to enable offline playback. It starts with the creation and initiation of a CachingTask, which downloads the media content for local storage. Once cached, the asset can be played offline seamlessly.

The Media Cache feature is accessible on all platforms except for tvOS.

This page is structured as follows:

* [Caching Workflow](#caching-workflow)
* [Creating a CachingTask](#creating-a-cachingtask)
* [Controlling the CachingTask](#controlling-the-cachingtask)
* [Listening for Cache events](#listening-for-cache-events)
* [Using React hooks](#using-react-hooks)
* [The Example App](#the-example-app)

### Caching Workflow

Caching a media asset encompasses the following stages:

* CachingTask creation: The caching process commences by creating a CachingTask, which orchestrates the downloading of the media content for offline access.

* Starting the CachingTask: Once the CachingTask is established, the download process is initiated using the start() method. This triggers the download of the complete media stream to the device's local storage.

* Offline Playback: After successful caching, the cached media asset can be played offline. This is accomplished by providing the original source to the player. The player checks if the asset is available offline; if it is, playback occurs from the local cache. If not, the player fetches the content from the network.

## Creating a CachingTask

To initiate the download process of a media asset, you need to create a `CachingTask`. This task requires two essential parameters: a `SourceDescription` specifying the asset to be cached, and `CachingTaskParameters` that define caching settings.

Below is an example of creating a caching task:

```typescript
// The source we want to cache.
const source = {
    sources: [
        {
            src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8",
            type: "application/x-mpegurl"
        }
    ],
    metadata: {
        title: "Big Buck Bunny"
    }
} as SourceDescription;

// Caching parameters
const parameters = {
    // Cache the whole stream
    amount: '100%',

    // Cache for 24 hours
    expirationDate: new Date(Date.now() + 24 * 60 * 60 * 1000),

    // Cache quality
    bandwidth: 2000000,
} as CachingTaskParameters;

// Create a caching task
const task = await MediaCache.createTask(source, parameters);
```

## Controlling the CachingTask

Once the `CachingTask` is created, it enters the `idle` state. To initiate the download process:

```typescript
task.start();
```

Additionally, you can pause or remove the task from the media cache using these methods:

```typescript
task.pause();
task.remove();
```

## Listening for Cache events

Both `MediaCache` and `CachingTask` instances dispatch events to notify about changes and status updates.

### MediaCache events

The `MediaCache` dispatches the following events:

| Event name    | Purpose                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------ |
| `statechange` | Dispatched if the status of the Media Cache changes from `uninitialised` to `initialised`. |
| `addtask`     | Dispatched if a new `CachingTask` is added to the `MediaCache.tasks` list.                 |
| `removetask`  | Dispatched if `CachingTask` is removed from the `MediaCache.tasks` list.                   |

As an example, listening to the `addtask` event is done as follows:

```typescript
MediaCache.addEventListener(CacheEventType.addtask, (event: AddCachingTaskEvent) => {
    console.log('[MediaCache] a new task was added: ', event.task.id);
  }
);
```

### CachingTask events

Each individual `CachingTask` also dispatches events to advertise changes in `progress` or `status`.

| Event name    | Purpose                                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| `statechange` | Dispatched if the status of the task changes. Possible values are `idle`, `loading`, `done`, `error` or `evicted`. |
| `progress`    | Dispatched on a regular interval while `loading`.                                                                  |

As an example, listening for `progress` events is done as follows:

```typescript
task.addEventListener(CachingTaskEventType.progress, () => {
    console.log('[MediaCache]', `Progress for task ${task.id}: ${task.percentageCached}`);
});
```

## Using React hooks

For convenience, React hooks are available to simplify handling caching tasks without the need to subscribe or unsubscribe to listeners.

### useCachingTaskList

This hooks listens for updates in the `MediaCache.tasks` list, and returns the updated list.

```jsx
function TaskListView(props: {debug: boolean}) {
    const tasks = useCachingTaskList(props.debug);
    return <View style={styles.container}>
        {tasks.map((task, index) => <Text key={index} style={styles.taskListItem}>{task.id}</Text>)}
    </View>
}
```

### useCachingTaskProgress and useCachingTaskStatus

These hooks listen for updates in both progress and status of a `CachingTask`.

```jsx
function CachingTaskView(props: {task: CachingTask, debug: boolean}) {
    const { task, debug } = props;
    const status = useCachingTaskStatus(task, debug);
    const progress = useCachingTaskProgress(task, debug);
    return <View>
        <Text>{`status: ${status}`}</Text>
        <Text>{`progress: ${progress}`}</Text>
    </View>
}
```

## The Example App

The example app that is part of this repository demonstrates the Media Cache features through a basic user interface. It provides a menu with options to start caching the currently selected source, and show a list of the currently available caching tasks.

| ![main](/pr-932/assets/images/media_caching_1-291dc509ba26ee47cc721f8bd89e0e30.png) | ![main](/pr-932/assets/images/media_caching_2-980927a546367feead24e464ea8aaa0e.png) |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |

---

# Android Media3 Pipeline

## Overview

The THEOplayer Android Media3 pipeline is an integration for the THEOplayer Android SDK that serves as a **new and rebuilt base layer for playback of video and audio files**. It is based on [Jetpack Media3](https://developer.android.com/media/media3) components, and it provides more stable playback covering a broader range of use cases, all while being lighter in size and more performant.

For more information, refer to the [Getting started with Media3 on Android](https://www.theoplayer.com/docs/theoplayer/how-to-guides/android/media3/getting-started/) section in our Android SDK documentation.

The Media3 pipeline is available as of `react-native-theoplayer` v8.9.0.

### Usage

> \[!IMPORTANT] As of THEOplayer 9.0, Media3 is the default playback pipeline on Android. In this version, it is still possible to opt-out and use the legacy pipeline with the `playbackPipeline` parameter in the `SourceDescription`.

> \[!IMPORTANT] As of THEOplayer 10.0, the legacy pipeline has been removed.

The rest of this section **applies to THEOplayer 8.x only**.

Except for **THEOads sources**, where Media3 is **enabled by default**, the "legacy" pipeline remains the default on THEOplayer v8.x.

To enable the new Media3 extension, set the `THEOplayer_extensionMedia3` in the app's gradle configuration, such as the `gradle.properties` file:

```text
THEOplayer_extensionMedia3=true
```

Additionally, pass the `useMedia3` flag in the [player configuration](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/config/PlayerConfiguration.ts) as shown below:

```tsx
const playerConfig: PlayerConfiguration = {
  // ...
  useMedia3: true
};
```

### Multimedia tunneling

The Media3 pipeline provides support for multimedia tunneling, as described in the [Android documentation](https://source.android.com/docs/devices/tv/multimedia-tunneling). This is disabled by default.

To enable multimedia tunneling, pass the `tunnelingEnabled` flag in the [player configuration](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/config/PlayerConfiguration.ts) as shown below:

```tsx
const playerConfig: PlayerConfiguration = {
  // ...
  tunnelingEnabled: true
};
```

---

# Migrating to THEOplayer React Native SDK 10.x

This article will guide you through updating to THEOplayer React Native SDK version 10 (from version 9), and the changes needed in your code.

## Update React Native THEOplayer

Run the following command to install THEOplayer React Native SDK version 10:

```bash
npm install react-native-theoplayer@10
```

## Breaking Changes on Web

The breaking changes for the native Web SDK are listed in the v10 [changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-breaking-changes).

## Breaking Changes on iOS

The breaking changes for the native Web SDK are listed in the v10 [changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-breaking-changes-2).

## Breaking Changes on Android

The breaking changes for the native Android SDK are listed in the v10 [changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-breaking-changes-1).

The following updates in particular impact the React Native SDK on Android.

### Media3 became the only available playback pipeline on Android

On Android platforms, the Media3 playback pipeline is now the only available pipeline. **The legacy pipeline has been removed.**

### Cache storage type `legacy` removed

With the removal of the legacy pipeline, the option to cache media content for this pipeline by setting `CachingTaskParameters.storageType` was also removed.

### PlaybackSettingsAPI removed on Android

The `PlaybackSettingsAPI`, which allowed to control start-up and lip sync correction on the legacy pipeline, has been removed.

### Update `compileSdk` to 36 or higher

The underlying Android SDK depends on the AndroidX Core library, which requires `compileSdk 36` as of version 1.17.0.

Update the `compileSdk` to be `36` (or higher) in your module-level `build.gradle` file.

We also recommend updating the Android Gradle Plugin to the latest version. In Android Studio, go to Tools → AGP Upgrade Assistant and follow the steps to update AGP in your project.

### Updated `minSdk` to API 23 on Android

This aligns with [other Android Jetpack libraries requiring API 23 as of June 2025](https://developer.android.com/jetpack/androidx/versions#version-table).

---

# Migrating to THEOplayer React Native SDK 9.x

This article will guide you through updating to THEOplayer React Native SDK version 9 (from version 8), and the changes needed in your code.

## Update React Native THEOplayer

Run the following command to install THEOplayer React Native SDK version 9:

```bash
npm install react-native-theoplayer@9
```

## Removed `chromeless` config parameter

To extend React Native THEOplayer with a user interface, it's recommended to either use the [`@theoplayer/react-native-ui`](https://github.com/THEOplayer/react-native-theoplayer-ui) package or create a custom UI in React Native. Support for the native `chromefull` UI has been removed.

## Removed `enableTHEOlive` config parameter

THEOlive is now always enabled, eliminating the need for an additional configuration parameter.

## Media3 as default playback pipeline on Android

On Android platforms, the Media3 playback pipeline is now enabled by default. This new pipeline is built on top of [Jetpack Media3](https://developer.android.com/media/media3), which aims to provide more stable playback on a wider range of devices. See [our Media3 guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/android/media3/getting-started.md) for more information.

We highly recommend using the Media3 playback pipeline. However, if you need some more time to make the switch, you can still revert to the legacy playback pipeline from version 8.x by setting `playbackPipeline` to `PlaybackPipeline.LEGACY` in the [`SourceDescription`](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/source/SourceDescription.ts) passed to the player.

### Warning

The legacy playback pipeline is scheduled to be removed in THEOplayer version 10.

If you run into an issue that prevents you from switching to Media3, please contact our Service Desk.

## Media3 as default backend for caching

Newly created caching tasks now use the Media3 backend by default. Sources cached with this backend can only be played using the Media3 playback pipeline.

If you need some more time to make the switch, you can still revert to the legacy cache storage from version 8.x by setting `CachingParameters.storageType` to `CacheStorageType.LEGACY` during creation of a caching task.

### Warning

The legacy cache storage is scheduled to be removed in THEOplayer version 10.

If you run into an issue that prevents you from switching to Media3, please contact our Service Desk.

## Removed Media3 integration package on Android

The Media3 playback pipeline now ships with the THEOplayer Android SDK, and is no longer published as an extension. This means the build flag `THEOplayer_extensionMedia3` can be dropped from your app's `gradle.properties`.

---

# Getting started with Millicast on React Native

[Dolby Millicast](https://dolby.io/products/real-time-streaming/) delivers broadcast quality live streaming at sub-second latency, enabling interactivity and fan engagement. Using the THEOplayer Millicast integration, you can play your Millicast streams directly through THEOplayer.

## Usage

1. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/getting-started.md) to set up THEOplayer in your React Native app. The Millicast integration is available in the main [react-native-theoplayer](https://www.npmjs.com/package/react-native-theoplayer) package on npm.
2. Add a Millicast source to your player's source.

### Add a Millicast source

After setting up THEOplayer in your app, set its source to a `SourceDescription` containing a `MillicastSource`. You'll need a Millicast account ID and stream name to identify your Millicast stream:

```tsx
const source: MillicastSource = {
  type: 'millicast',
  src: 'multiview',
  streamAccountId: 'k9Mwad',
  subscriberToken: '<token>', // This is only required for subscribing to secure streams and should be omitted otherwise.
  apiUrl: 'https://director.millicast.com/api/director/subscribe' // Required for support on Android
};
player.source = source;
```

### Add configuration

Optionally, you can provide additional configuration to the source, specific for working with Millicast streams. To configure these settings, add a `connectOptions` property to the source object and specify the options.

In the example below, the configuration is used to disable any audio from the Millicast stream. For an exhaustive list of these options, visit the [API documentation](https://theoplayer.github.io/react-native-theoplayer/api/interfaces/MillicastConnectOptions.html).

```tsx
const source: MillicastSource = {
  type: 'millicast',
  /* ... */
  connectOptions: {
    disableAudio: true
    /* ... */
  }
};
```

## More information

* [API references](https://theoplayer.github.io/react-native-theoplayer/api/interfaces/MillicastSource.html)
* [Millicast documentation](https://docs.dolby.io/streaming-apis/docs/)

---

# Picture-in-Picture (PiP)

## Overview

The Picture-in-Picture feature allows you to watch a stream in a floating window that is always on top of other apps or windows.

Transitioning the player to a PiP window can be done in two ways:

* Explicitly, using the player API
* Automatically, when transitioning to background in mobile apps.

This page describes how to configure PiP with react-native-theoplayer.

## Configuration

### Transitioning to PiP automatically

The `pipConfiguration` property that is set on the player instance allows native mobile apps on iOS and Android to automatically transition into PiP presentation mode when the app goes to the background. The property can be changed at run-time, allowing to change the behaviour depending on the active media asset.

```typescript
player.pipConfiguration = { startsAutomatically: true }
```

### Using presentationMode

The picture-in-picture presentation mode can also be triggered explicitly using the `THEOplayer` API:

```typescript
// Change presentation mode (inline, fullscreen or pip).
player.presentationMode = PresentationMode.pip;
```

### Listening for presentationMode changes

Each time the player transitions from one presentationMode to another, either automatically or manually through the API, the player dispatches a `presentationmodechange` event that can be used to update the user-interface.

```typescript
player.addEventListener(
  PlayerEventType.PRESENTATIONMODE_CHANGE,
  (event: PresentationModeChangeEvent) => {
    const newPresentationMode = event.presentationMode;
  }
);
```

Additional configuration is necessary depending on the platform the app runs on.

## Android

Picture-in-picture support for Android was added in Android 8.0 (API level 26).

A react-native app on Android is typically a single-activity application. Launching picture-in-picture mode means the whole activity transitions to an *out-of-app* PiP window.

### Enabling PiP support

To enable PiP support, make sure to set `android:supportsPictureInPicture=true` in the app's manifest, and specify that the activity handles layout configuration changes so that it does not relaunch when layout changes occur during PiP mode transitions.

```xml
<activity
  android:name=".MainActivity"
  android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation"
  android:supportsPictureInPicture="true">
</activity>
```

Also, add these methods to the `MainActivity` to let react-native know when the app makes PiP, background and foreground transitions:

```kotlin
public override fun onUserLeaveHint() {
    // Notify the app is backgrounded in case the user taps home or back, and
    // the app needs to transition to PiP automatically.
    this.sendBroadcast(Intent("onUserLeaveHint"))
    super.onUserLeaveHint()
}

override fun onPictureInPictureModeChanged(
    isInPictureInPictureMode: Boolean,
    newConfig: Configuration
) {
    // Notify that the app is changing its picture-in-picture mode.
    super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)
    val intent = Intent("onPictureInPictureModeChanged")
    intent.putExtra("isInPictureInPictureMode", isInPictureInPictureMode)
    this.sendBroadcast(intent)
}
```

### Enabling early transitioning to PiP event

You might want to enable [transitioning to PiP](https://developer.android.com/reference/android/app/PictureInPictureUiState#isTransitioningToPip\(\)) event for Android 15+ (API 35+). To enable it make sure that the compile SDK version is set to 35 in your build.gradle `compileSdkVersion = 35`. Also the appropriate intent should be sent from the `MainActivity` to let react-native know when the app starts the PiP animation:

```kotlin
override fun onPictureInPictureUiStateChanged(pipState: PictureInPictureUiState) {
    super.onPictureInPictureUiStateChanged(pipState)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM &&
        pipState.isTransitioningToPip
    ) {
        Intent("onPictureInPictureModeChanged").also {
            it.putExtra("isTransitioningToPip", true)
            sendBroadcast(it)
        }
    }
}
```

Then it should set the `context?.pip` to `PresentationModeChangePipContext.TRANSITIONING_TO_PIP` in the event `PlayerEventType.PRESENTATIONMODE_CHANGE`.

### PiP controls

The PiP window will show the default controls to configure, maximize and close the PiP window. In addition, the active media session enables a play/pause toggle button and (disabled) play-list navigator buttons.

| ![pip1](/pr-932/assets/images/pip_android_1-c2cde1b49f69cfe79a441bbaf8cb47ee.png) | ![pip2](/pr-932/assets/images/pip_android_2-a34aebe9117fe159534751493076b242.png) | ![pip3](/pr-932/assets/images/pip_android_3-715cef9dba8c741424f9b0f8247bc56d.png) |
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |

### User interface

As mentioned before, when choosing `picture-in-picture` presentation mode on Android the whole activity moves to the PiP window, including the react-native UI that potentially lies on top. For this reason it is necessary to disable the UI on Android in PiP mode, as opposed to iOS and web where the video view is separated from the rest

More information on Android PiP support can be found on the [Android developer pages](https://developer.android.com/develop/ui/views/picture-in-picture).

## iOS

No additional configuration is required to support picture-in-picture on iOS.

## Web

On web platforms, only the "out-of-app" PiP presentation mode is supported, allowing the PiP window to float independently from the browser window on the desktop. The THEOplayer Web SDK refers to this as [native-picture-in-picture](https://www.theoplayer.com/docs/theoplayer/v10/api-reference/web/types/PresentationMode.html) , distinguishing it from the "in-app" floating player window used in picture-in-picture mode. Note that except for the native PiP controls, any user interface defined in React Native will not be shown in the PiP window.

---

# Subtitles, Closed Captions and Metadata tracks

THEOplayer's `TextTrack` api gives developers the capability to manage and manipulate various types of text-based content. Some of its key functionalities include text track selection, styling, and listening to track and cue events.

## Types of text tracks

In this document we will differentiate between the following kinds of text tracks:

* **Subtitles**, which are text-based translations of the dialogue or narrative of a video;
* **Closed Captions (CC)**, which go beyond subtitles by providing additional information about sound effects, music, and other audio cues;
* **Metadata tracks**, which are used for providing non-textual information about the video, such as thumbnail urls or program boundaries in a live stream.

In addition, a distinction can be made between how a text track is delivered to the player:

* **In-band** refers to text tracks that are embedded within the video or audio media stream itself.
* **Out-band**, or *out-of-band*, is used to describe text tracks that are delivered separately from the media file. They are typically described in the playlist or manifest.
* **Side-loaded** text tracks are those that are manually added or loaded by the user through the source description.

## Side-loaded text tracks

In contrast to in-band and out-band text tracks, which are delivered to the player through the media content itself, the side-loaded text tracks can be configured by the user when setting a source to the player:

```typescript
player.source = {
  "sources": [
    {
    "src": "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8",
    "type": "application/x-mpegurl"
    }
  ],
  "textTracks": [
    {
      "default": true,
      "src": "https://cdn.theoplayer.com/dash/theoplayer/thumbnails/big_buck_bunny_thumbnails.vtt",
      "label": "thumbnails",
      "kind": "metadata",
      "format": "webvtt",
      "srclang": "en"
    }
  ]
}
```

### iOS/tvOS

On iOS and tvOS, support for side-loaded tracks is provided by a separate connector, which is enabled by adding the feature to the `react-native-theoplayer.json` (or `theoplayer-config.json`) file in your app folder.

```json
{
  "ios": {
    "features": ["SIDELOADED_TEXTTRACKS"]
  }
}
```

## Listening to text track events

Out-band and side-loaded text tracks become accessible via the text track API once the player has loaded the media source. This event is signaled by the `PlayerEventType.LOADED_METADATA` event, which is dispatched by the [THEOplayer API](https://github.com/THEOplayer/react-native-theoplayer/blob/-/src/api/player/THEOplayer.ts):

```typescript
player.addEventListener(PlayerEventType.LOADED_METADATA, (event: LoadedMetadataEvent) => {
  console.log(TAG, 'loadedmetadata', JSON.stringify(event));
})
```

Alternatively, the `PlayerEventType.TEXT_TRACK_LIST` event can be used to dynamically listen to text tracks that are being added, removed or changed. In-band text tracks, in particular, are created when their first cue is loaded, which can occur at any point during playback.

```typescript
player.addEventListener(PlayerEventType.TEXT_TRACK_LIST, (event: TextTrackListEvent) => {
  const { subType, track } = event;
  switch (subType) {
    case TrackListEventType.ADD_TRACK: /*A text track has been added*/ break;
    case TrackListEventType.REMOVE_TRACK: /*A text track has been removed*/ break;
    case TrackListEventType.CHANGE_TRACK: /*A text track has changed*/ break;
  }
});
```

Similarly for text track cues, the `PlayerEventType.TEXT_TRACK` event provides knowledge on cues being added or removed. The cue contains a reference to the track it belongs too.

```typescript
player.addEventListener(PlayerEventType.TEXT_TRACK, (event: TextTrackEvent) => {
  const { subType, cue } = event;
  switch (subType) {
    case TextTrackEventType.ADD_CUE: /*A text track cue has been added to the text track*/ break;
    case TextTrackEventType.ENTER_CUE: /*A text track cue has entered; it became active*/ break;
    case TextTrackEventType.EXIT_CUE: /*A text track cue has exited; it became inactive*/ break;
    case TextTrackEventType.REMOVE_CUE: /*A text track cue has been removed from the text track*/ break;
  }
})
```

## Enabling a text track

A subtitle or closed caption can be enabled by setting the player's `selectedTextTrack` property to the `uid` of the track, or `undefined` to select none.

```typescript
const track: TextTrack;
player.selectedTextTrack = track.uid;
```

Note that [THEOplayer React-Native UI](https://github.com/THEOplayer/react-native-theoplayer-ui) package provides a visual representation of the list of available text tracks, as well as the ability to enable/disable them.

Metadata tracks are by default 'hidden', as they do not visually represent a textTrack but contain valuable data (e.g. id3 cues, HLS DataRange cues, ...). While 'hidden', these metadata tracks will actively 'enter' and 'exit' their cues.

## Preview thumbnails

Preview thumbnails is a feature that allows users to see a visual representation of different points or scenes within a video, making it easier to navigate and locate specific content of interest.

The thumbnails are typically contained in a dedicated thumbnail track, which is a text track of kind `metadata` with label `thumbnails`. The track can be either be side-loaded to the stream source, or contained in a stream manifest, as the demo sources in the [example application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/example-app.md) demonstrate:

```json
{
  "sources": [
    {
    "src": "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8",
    "type": "application/x-mpegurl"
    }
  ],
  "textTracks": [
    {
      "default": true,
      "src": "https://cdn.theoplayer.com/dash/theoplayer/thumbnails/big_buck_bunny_thumbnails.vtt",
      "label": "thumbnails",
      "kind": "metadata",
      "format": "webvtt"
    }
  ]
}
```

The [`@theoplayer/react-native-ui`](https://github.com/THEOplayer/react-native-theoplayer-ui) package provides a thumbnail viewer the interprets thumbnail cues and displays them above the progress bar.

![thumbnails](/pr-932/assets/images/thumbnails-c17c05ef4018a5a2ad04327f820ed6be.png)

## Styling subtitles and closed captions

In this section, we showcase the functionality of THEOplayer's `TextTrackStyle` API, which enables the customization of subtitles and closed captions' appearance. We will illustrate the practical implementation of this API through some examples.

### Style properties

| Property          | Purpose                                                           | Value                                                                                   | Support                                                            |
| ----------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `fontFamily`      | The font of the text track.                                       | A string, e.g. `'serif'`, `'monospace'`, `'arial'`.                                     | All platforms,                                                     |
| `fontColor`       | The font color of the text track.                                 | A string, e.g.`'red'`, `'#ff0000'`, `'#ffc50f'` or `'rgba(255, 0, 0, 1)`.               | All platforms. The `rgba()` formatting is supported on Web only.   |
| `fontSize`        | The font size of the text track.                                  | A percentage string, e.g.`'50%'`, `'100%'` (default), `'175%'`.                         | All platforms,                                                     |
| `backgroundColor` | The color of the area directly behind the text.                   | A string, e.g.`'red'`, `'#ff0000'`, `'#ffc50f'` or `'rgba(255, 0, 0, 1)`.               | All platforms. The `rgba()` formatting is supported on Web only.   |
| `windowColor`     | The color of the area covering the full width of the text track.  | A string, e.g.`'red'`, `'#ff0000'`, `'#ffc50f'` or `'rgba(255, 0, 0, 1)`.               | Web and Android. The `rgba()` formatting is supported on Web only. |
| `edgeStyle`       | The edge style of the text.                                       | An enum value, either `none` (default), `dropshadow`, `raised`, `depressed`, `uniform`. | All platforms.                                                     |
| `marginTop`       | The top margin of the area where subtitles are being rendered.    | A positive numeric value specifying the number of pixels.                               | All platforms.                                                     |
| `marginLeft`      | The left margin of the area where subtitles are being rendered.   | A positive numeric value specifying the number of pixels.                               | All platforms.                                                     |
| `marginBottom`    | The bottom margin of the area where subtitles are being rendered. | A positive numeric value specifying the number of pixels.                               | Web and Android.                                                   |
| `marginRight`     | The right margin of the area where subtitles are being rendered.  | A positive numeric value specifying the number of pixels.                               | Web and Android.                                                   |

### Examples

|                                                                                                     |                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| ![background](/pr-932/assets/images/texttrackstyle_background-c95e54ee5b2a2bc17a69cc40d280344f.png) | ```typescript
player.textTrackStyle.backgroundColor = 'red';
player.textTrackStyle.marginLeft = 45;
```                                               |
| ![size](/pr-932/assets/images/texttrackstyle_size-cba477b68686174a985054911bb4b474.png)             | ```typescript
player.textTrackStyle.windowColor = 'black';
player.textTrackStyle.fontColor = '#ffff00ff';
player.textTrackStyle.fontSize = '250%';
``` |
| ![size](/pr-932/assets/images/texttrackstyle_family-4ec69c505c8ee26bc7fa89802503ca25.png)           | ```typescript
player.textTrackStyle.fontFamily = 'monospace';
```                                                                                    |

---

# Getting started

## Usage

1. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/frameworks/react-native/getting-started.md) to set up THEOplayer in your React Native app.
2. Add an OptiView Live source to your player's source.

### Add an OptiView Live source

After setting up your THEOplayer on your web page, set its source to a `SourceDescription` containing a `THEOliveSource`. You'll need an OptiView Live channel ID:

```javascript
player.source = {
  sources: {
    type: 'theolive',
    src: 'your-channel-id',
  },
};
```

## More information

* [API references](https://theoplayer.github.io/react-native-theoplayer/api/)

---

# Token based security

OptiView Live offers the option to enable JWT token security on channel distribution level. This can be interesting if you only want valid users to access your stream. Read more about the feature and configuring it on your channels on the [token based security guide](https://docs-preview.optiview.dolby.com/pr-932/theolive/distribution/security/token-based-security.md).

This page will demonstrate how to configure the React Native Player SDK for playback of channels with token based security enabled.

## Setting up the React Native THEOplayer SDK for OptiView Live

Refer to the [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/react-native/theolive/getting-started.md) for the prerequisite steps in getting the React Native SDK up and running for OptiView Live playback.

## Configuring THEOplayer to pass the token

The OptiView Live API provides a simple property to configure your token:

```javascript
const token = getToken(); // Generate or request your token, for more information check the token based security guide linked above.
player.theolive.authToken = token;
```

This will ensure the player includes your token in the authorization header on all subsequent requests it performs for playback of your OptiView Live channel.

## Dealing with token expiry and rotation

If your tokens are short-lived, you want to make sure to update the token being passed to the player and requests before it expires, to allow playback to continue beyond expiry. This can simply be done by updating the header on the player in the same way. For example, one could check on an interval that makes sense for your token lifespan whether the token is about to expire and update when necessary, for example:

```javascript
let token;

// Helper function to check whether your token will expire within one minute from now
function tokenWillExpireSoon() {
  const payload = JSON.parse(atob(token.split('.')[1]));
  const exp = payload.exp; // in seconds
  const now = Math.floor(Date.now() / 1000); // current time in seconds
  return exp - now <= 60;
}

function maybeUpdateToken() {
  if (!token || tokenWillExpireSoon(token)) {
    token = getToken(); // Generate or request your token, for more information check the token based security guide linked above.
    player.theolive.authToken = token;
  }
}

maybeUpdateToken();
setInterval(maybeUpdateToken, 30000); // Check every 30 seconds
```

## Clearing the token

If the token isn't needed anymore, e.g. when switching to an unprotected channel or a non-OptiView Live source altogether, the header can be simply removed as follows:

```javascript
player.theolive.authToken = undefined;
```

## Enabling Token Based Security for Safari browsers on iOS <17

Apple devices running an iOS version lower than 17.1 do not support MSE, therefore there are limitations with what is possible when playing an OptiView Live stream. One such limitation is that the above network API approach does not work on those devices. Instead, a service worker needs to be registered to support playback of JWT enabled streams.

The service worker needs to intercept the `fetch` requests originating from the app, to be able to include the `Authorization` header to the requests.

A code snippet for the service worker code is shared below.

> **Note**
>
> Service worker registration is only possible in a secure environment (`https://`) or on `localhost`. There can also only be one service worker active, so if your environment or application already has a service worker active, you will need to include the additional functionality in that service worker.

iOS Safari service worker

```javascript
self.addEventListener('install', () => {
  console.log('Service worker installed!');
  self.skipWaiting();
});

self.addEventListener('activate', (event) => {
  console.log('Service Worker activated');
  // Claim clients so the service worker is in effect immediately
  event.waitUntil(self.clients.claim());
});

// Intercept the fetch event and add in your JWT
self.addEventListener('fetch', (event) => {
  event.respondWith(
    (async function () {
      try {
        const url = new URL(event.request.url);
        if (!url.origin.endsWith('theo.live')) {
          // Requests not made by the player for playback of the OptiView Live channel should not be modified.
          return fetch(event.request);
        }
        const token = getToken(); // Generate or request your token, for more information check the token based security guide linked above.
        // Clone the request and add the JWT header
        const modifiedRequest = new Request(event.request, {
          headers: {
            ...Object.fromEntries(event.request.headers.entries()),
            Authorization: `Bearer ${token}`,
          },
        });
        return fetch(modifiedRequest);
      } catch (error) {
        console.error('Error in fetch handler:', error);
        return new Response('Service Worker Error', { status: 500 });
      }
    })()
  );
});
```

> **Note**
>
> In order for the service worker to be able to intercept requests made from the player library, its scope must include the player SDK files. That means the player and service worker must be hosted on the same path or the player must be hosted in a subfolder of the path where the service worker is hosted.

To register this service worker in to your code, you can attach it this way.

Register service worker

```javascript
function registerServiceWorker() {
  if (!('serviceWorker' in navigator)) {
    console.error('Service worker not supported!');
    return;
  }
  const serviceWorkerScope = "/service/worker/path" // Replace with your own path to the service worker location.
  const serviceWorkerPath = "${root}/service-worker.js"; // Replace with the filename of your service worker.

  // We recommend unregistering actively before (re-)registering as we've seen issues where hard reloads could cause issues if the service worker wasn't unregistered.
  const registration = await navigator.serviceWorker.getRegistration(serviceWorkerPath);
  await registration?.unregister();

  navigator.serviceWorker
    .register(serviceWorkerPath, {
      scope: serviceWorkerScope,
    })
    .then((reg) => {
      if (reg.active) console.log('Service worker registered!');
    })
    .catch((err) => {
      console.error('Could not register service worker!', err);
    });
};

// Initialise the service worker some time early in the process.
if (!(window.MediaSource || window.ManagedMediaSource)) {
  registerServiceWorker();
}
```

---

# Connectors for THEOplayer React Native SDK

## [Adobe](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/adobe)

[Integrate with Adobe analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/adobe)

## [Adobe Edge](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/adobe-edge)

[Integrate with Adobe Edge analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/adobe-edge)

## [Adscript](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/adscript)

[Integrate with Adscript analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/adscript)

## [![](/pr-932/assets/images/agama-4f500b478e23a543d4eb189b5168dd78.png)Agama](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/agama)

[Integrate with Agama analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/agama)

## [Bitmovin](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/bitmovin)

[Integrate with Bitmovin analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/bitmovin)

## [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/comscore)

[Integrate with Comscore analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/comscore)

## [![](/pr-932/img/conviva.svg)![](/pr-932/img/conviva_dark.svg)Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/conviva)

[Integrate with Conviva analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/conviva)

## [🔒DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/drm)

[Integrate with the DRM connector.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/drm)

## [Engage](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/engage)

[Integrate with the Engage connector.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/engage)

## [![](/pr-932/img/gemius.svg)![](/pr-932/img/gemius_dark.svg)Gemius](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/gemius)

[Integrate with Gemius analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/gemius)

## [![](/pr-932/assets/images/mux-1d56b7f17d515324f1547519db52c2ba.png)Mux](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/mux)

[Integrate with Mux analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/mux)

## [Nielsen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/nielsen)

[Integrate with Nielsen analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/nielsen)

## [![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAy0SURBVHgB7d1PbhRJFsfxiLIxs+iW2DbuaZVvwNzASGB6iU+AOQGuHd2YwSVhYId9AsMJYNmYkewb2DdwafjjWXoBEvUvYzKqSMqmjV1ZlZnxIuL7kVpqoZaM6M5f53svMp5SAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAORwt3q8fpn8pAKXQSij78Ju5S7tKmXr6m1z/0vm0tbC3eawAFEZkABwurl6Zm/tpN/3NXRv9qm4lpt/89e2TFwpAIcQFwNkP/ykH7U5veWHvWUsBmIqoABjj4f/GaP2i0+42CQJgcmICIM/DP6JbSidbV99sbCoAuYkIgMke/pPoDwCTcB4A0z/8I5QFQD5OA6DIh/+k4diw95IgAM7nLADKevhHKAuAizgJgPIf/pN0q93pXudtAPi7ygOg2od/hP4A8HeVBoCrh/+E4/Rnb/6y87ipAFQXAAIe/hPoDwBWJQEg6+EfoSxA7EoPAKkP/ylab7bb3S2CALEpNQC8ePi/oSxAfEoNgPc31zZrWt1TXhkEwXIaBAcKCFxNlUhrc0V5x9Rrurb/4dbDbW4jQuhKDQCfaWNWLs/NHh4trT1SQKAIgAsYpdY/Lj08fH/zzxUFBIYAGMugLNj+uLT2irIAISEA8rltywL6AwgFATCBYX/g0i5lAXxHAEwsKwseHr67sbaoAA8RAFMz9Zma2qUsgI8IgIIwNoSPCICCMTaETwiAUnwbG+5TFkAyAqBc1xgbQjICoALZ2PDjrQerChCEAKiMqSujn9v+wIelP24rQAACoHJ23fnMK8oCSEAAOHJybGgvTlGAAwSAY3ZseHnu533GhnCBABBhdKyYsgBVIgBEMXXGhqgSASBQNjbkWDHKRgCIZeocK0bZCADxhv0BygKUgQDwRDY2/Hjr4XOCAEUhAHxjzCq3EaEoBICXRmPDNAg82LoEqQgAr7HEBNMhAALwtT+wz9gQeREA4bjC2BB5EQDBYYkJxkcAhIslJrgQARA4lpjgPARAFFhigrMRAFFhiQlOIwAixBITZAiAiDE2BAEQPZaYxIwAQIYlJhEiAHAKY8O4EAA4w2hsyBKTsBEAOAdLTEJHAOBCLDEJFwGAsbHEJDwEAHJiiUlICABMiCUmISAAMBWWmPiNAEABWGLiKwIABWKJiW8IABTu9NiQIJCMAEBphmNDjhVLRgCgZIwNJSMAUBHGhhIRAKgUS0xkIQDgAktMhCAA4BBLTFwjACABS0wcIQAgBrcRVY8AgDCjsWEaBNcUSkUAQKhBEOxTFpSLAIBoLDEpFwEALzA2LAcBAI8M+wNHN9d2KQuKQQDAO0arRcaGxSAA4C3GhtMjAOA5lphMgwBAIFhiMgkCAEFhiUk+pQaASdSBAhxgicl4tCrZ0e/36yaZ2U1/VF0Bbhy0O73lhb1nLYVTSg+AjE3imtaPCAK4YrR+0Wl3mwTBSGUBYB0url+Zm+utpj+UY51wRLeUTrauvtnYVKg2ADK2LEiSmXWt9B0FOKFbiek3f3375IWKmJMAyLy7sbY4UzPblAVwJfaywGkAZOgPwLX0QVj/0um9jC0IRASAZcuCfn92tabVPQU4EV9ZICYAMvQH4J5utTvd6zG8DYgLgAxlAVyLoT8gNgAyBAEcO04fks1fdh43VYDEB4BFWQD3wuwPeBEAmeGx4tnn6d/y2Sdced3u9BqhlAVeBUCGsgDOab3Zbne3fA8CLwMg82FpLS0LzB2CAG74XxZ4HQAW/QG4NwiC5TQIvPv83fsAyHztD7xK/5ZtMnDCx7FhMAGQoT8A1+yxYl/GhsEFQGbYHxgcK+ZaKDjgR38g2ACw6A/ANW3U3pdu767UsiDoAMhwLRlck9ofiCIAMvQH4Ja8siCqALC4lgzu6ZZRvcb8ztPXyrHoAiBDfwCuSSgLog2ATFoWXEvLgleUBXDF5dgw+gDI0B+AW276AwTACcOyYHaF/gAcqnSJCQFwBvoDcK2q/gDLQc/wy1/PWvM7Gyumr5bTfxUtBVRssOT08kzp917wBjAG+gOolFF77Zne3YW/yi8DCIAxURagfKbVT/Tdf/7n8Z6qCAGQE0GAEhwbpbY6nU+bC3ubx6pCBMCEKAtQBKNN2uz73Kj6wc8QAFN6f+PBaq1mPzvWdQWMK63z+0Y1q3zdPwsBUADKAuRwnLb4m1LWkxMABRp8dtyf3U7/VBcV8J20zm+6qPPPQwCUgP4ATqlwrJcXAVAiriWLXfVjvbwIgJLRH4jSYKw3v/N4XQkXVAC8u7G2OKvVo6SmW9KuX+La8ji4HuvlFUQAHC3er6vLlx4ZY1ZO/rrE65npDwRKyFgvL68D4HBx9co/5n66l75uraof1tkyr2f+2h/gs2P/HScmafi6HszbAPjv0h+3Z5XdFGzq4/zzEq9npj/gN4ljvby8C4CszjcTztolXs/MtWSeETzWy8ubALCv+5fnfk5fmc2qmppuKZ1sSTmNlaE/IJ38sV5eXgTA0dLao/Pr/EnJ6w9wbblI3oz18hIdAPZ1f6amt8et8yclsSygPyBDYtRWt/tp3ec6/zwiA2Aw1rs0u22qPlOv9Wa73d2SFATDEDTblAUV83Ssl5eoACi2zp+UzLEh/YHKeD3Wy0tMAPzv5r/vJTpZV2LOzeu04WNENXxsWdDvz67W9OD7AhTL2a08LjkPAPuKW6up51roEVn6AxEIaKyXl7MAcFbnT8geK/7S+bQl6f8OlAXTCm+sl1flATDe8V2p6A8EItixXl6VBsDwP9Tac+X99/G61e50r1MW+Cf0sV5elQTAtMd3pZLaHzCJ/UZClb5VxiuRjPXyKjUAfvSZbmCO0z/ETT47lsqkZZsRV7ZJUWoAfFh68CKeV1Kh/YF4ry2PcqyXFwFQvNftTq9Bf8ChiMd6eREAJRHbHwj62nLGenmxHrwkg/XOc5d2bS2uhLBrz6++fXw9McndwNae22Ubjas7Gws8/PnwBlAJ3TKq15jfefpaCRLCteWM9aZDAFSIY8UFYqxXCALAgeGx4t5LeecHZnblTwtMq6eSxm/C3qZ8RQ/AgXQ8tS6yP5DW0IL7A3as12x3Pv+Lh784vAE4Nzg/sPzr2ycHShBR15Yz1isNbwDOmXpN1/Y/3Hq4fWhPTgphP5TRtd6CUealciT92Qf9RF23kwse/nLwBiCM0G1GVV9bbsd6TWm3NoeINwBhbH/g49LDQ0n9AVueVNUfsGO9dufTAg9/NXgDkO2g3ektyxsbzq4U3h9grOcEAeCBsM8PMNZziRLAA9mx4o+3Hji8Lfk0Ozac39lYMX21PGFZwFhPAN4AvBPEtWSv27Veg86+ewSAp6SWBeddW27HekmiG9T5chAAvhO4zeiM/gBjPaEIgCDILQu0rtW5lUcuAiAo8rYZQTamAEEx9Zma2pV2rBhyEQABGo4NZw+PltYe2UUsCvgBAiBgw8+Of96XdKwYshAAwRt8bbhtvy+gLMD3CIBomLotC+gP4CQCIDJf+wP7tj+gED0CIE5XJH52jOoRAFEb9geObq7tUhbEiQCAslub6Q/EiQDAN9lnx4e/EwKxIAAwYtSevaGYz3TjMasAlmpGiwCIm72VZ6vT+czXepEiAOLFrTwgAKLD7bs4gQCIx/BWnh1u5cEIARABu2yj2/20Tp2P7xEAIWOpJi5AAASJsR7GQwCEhbEeciEAAmG0edFpf27w4CMPAsB338Z6G3sKyIkA8NdxYpKGtF0A8AsB4CG7VJNlGygCAeATxnooGAHgBcZ6KAcBINtgrDe/s7GugBIQAEJxfBdVIACk4Ws9VIgAkIOxHipHALj39fguYz1UjwBwibEeHCMAnGCsBxkIgGoNb+V5w608kIEAqAhjPUhEAJSNsR4EIwBKY1o9lTR+e/v0tQKEIgCKx6088AYBUCyWbcArBEABjDIHSaIb1PnwDQEwncFYb56xHjxFAEyIsR5CQADklY71EjX4aOdAAZ4jAMbG8V2EhwC4GGM9BIsAOMdg2YbuNxnrIVQEwFlYtoFIlBoAxpg9rfUd5Y/h13o7jPUQB61K9v7mnys1XdtWwrFsAzEqPQAs0SHArTyIWCUBYMkLAcZ6QGUBYAkJAS7hBL6qNAAslyEwGOu1Pzd48IGhygPAqjwEuJUHOJOTALAqCgGWbQDncBYAVpkhwFgPuJjTALAKDwHGesDYnAeAVUwIMNYD8hIRANYUITAY683vPF5XAHIREwBW3hDgVh5gOqICwBorBBjrAYUQFwDWj0PAtBJjmoz1gGKIDADruxDg+C5QArEBYA1CQNXuMNYDAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABALP4PxPhKst9YjwYAAAAASUVORK5CYII=)Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/yospace)

[Integrate with Yospace analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/yospace)

## [![](/pr-932/assets/images/youbora-0b7d7160409d9f3e1c31532385bf7698.png)Youbora](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/youbora)

[Integrate with Youbora analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/react-native/youbora)

---

# THEOplayer React-Native Adobe Connector

An Adobe analytics connector for `@theoplayer/react-native`.

## Installation

The `@theoplayer/react-native` package has a peer dependency on `react-native-device-info`, which has to be installed as well:

```sh
npm install \
  react-native-device-info \
  @theoplayer/react-native-analytics-adobe
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, the Media Collection API's end point, Visitor Experience Cloud Org ID, Analytics Report Suite ID and the Analytics Tracking Server URL.

```tsx
import { useAdobe } from '@theoplayer/react-native-analytics-adobe';

const uri = "<Media Collection API's end point>";
const ecid = "<Visitor Experience Cloud Org ID>";
const sid = "<Report Suite ID>";
const trackingUrl = "<Tracking Server URL>";
const metadata = {}; // Optionally provide initial metadata
const userAgent = "<Custom User-Agent>"; // Optionally provide a custom user-agent header value.
const debug = true; // Optionally provide a debug flag for extra logging.
const useNative = true; // Use a native connector on iOS & Android; `false` by default.

const App = () => {
  const [adobe, initAdobe] = useAdobe(uri, ecid, sid, trackingUrl, metadata, userAgent, debug, useNative);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize Adobe connector
    initAdobe(player);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

The Adobe connector will dispatch player events to Adobe with standard metadata the player has access to, such as duration or whether it is a live or vod.

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
import { AdobeMetaData } from "./Types";

const onUpdateMetadata = () => {
  const metadata: AdobeMetaData = {
    "params": {
      "media.channelName": "channelName",
      "media.id": "mediaId"
    },
    "customMetadata": {
      "customTag1": "customValue1",
      "customTag2": "customValue2"
    }
  };
  adobe.current?.updateMetadata(metadata);
};
```

---

# @theoplayer/react-native-analytics-adobe

## 1.17.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.17.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.16.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.15.1

### 🐛 Issues

* Fixed an issue where heart-beat requests could continue after destroying a session on Web.

## 1.15.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/adobe/LICENSE) file for more information.

## 1.14.3

### 🐛 Issues

* Fixed an issue on Android where the playhead for Live events would exceed the maximum value.

## 1.14.2

### 🐛 Issues

* Fixed an issue on Android where the properties from the passed metadata was not included with the `sessions` request.
* Fixed an issue where the required `visitor.marketingCloudUserId` property was not included with the `sessions` request.

## 1.14.1

### 🐛 Issues

* Fixed an issue on Android where the connector could crash when adding new events because of a `ConcurrentModificationException`.

## 1.14.0

### ✨ Features

* Fixed an issue on Android where the event payload would be partially obfuscated when enabling minification with R8.
* Fixed an issue on Android where the `playhead` and `contentLength` payload properties should be integers.

## 1.13.0

### ✨ Features

* Fixed an issue on Android where chapter events would not be properly reported.
* Updated Android's target SDK version to 36.

## 1.12.2

### 🐛 Issues

* Fixed an issue where player API was used on the wrong thread, resulting in a crash due to concurrent access of player internals.

## 1.12.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.12.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.11.0

### ✨ Features

* Added optional native connector implementations for iOS and Android.

## 1.10.0

### ✨ Features

* Bumped dependency on react-native-device-info

## 1.9.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.8.0

### ✨ Features

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors

## 1.7.1

### 🐛 Issues

* Fixed a build issue where the `Settings` object would not be found when using the connector with react-native-web.

## 1.7.0

### ✨ Features

* Dropped usage of the NativeModules import to make the connector ready for the new architecture

### 📦 Dependency Updates

* Updated dependency `react-native-device-info` to version `>=10.0.0 <14.0.0`.

## 1.6.0

### ✨ Features

* Added support for THEOplayer 8.0

## 1.5.0

### 🐛 Issues

* Fixed an issue on Web where an asset with a pre-roll ad would report an invalid media duration.

### ✨ Features

* Added `debug` flag for extra logging.

## 1.4.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

## 1.3.1

### 🐛 Issues

* Fixed an issue where the `media.length` would be not be correctly converted to seconds for VOD and Live streams.

## 1.3.0

### 🐛 Issues

* Fixed an issue where the `media.length` would be wrong when starting a session for a stream with a pre-roll ad.

## 1.2.1

### 📦 Dependency Updates

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.2.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.1.0

### ✨ Features

* Added a `userAgent` property to the connector's constructor to allow setting a custom `User-Agent` header value when doing requests.
* Changed the default `User-Agent` header value on Android to custom value that contains `Mozilla/5.0 (Linux; U; ${operatingSystem}; ${localeString}; ${deviceName} Build/${deviceBuildId})`.
* Changed the default `User-Agent` header value on iOS to custom value that contains `Mozilla/5.0 (${model}; CPU OS ${osVersion} like Mac OS X; ${localeIdentifier})`.

## 1.0.0

### ✨ Features

* Added `useAdobe` hook to create and initialize an Adobe connector. See README.md for usage.

## 0.7.0

### 🐛 Issues

* Fixed sending play/pause on program boundaries.
* Fixed sending ad ping events if a program boundary occurs mid ad.

## 0.6.0

### ✨ Features

* Add `media.name` to `sessionStart` request if `player.source.metadata.title` is set.
* Add functionality to stop the current session and start a new one.

## 0.5.0

### ✨ Features

* Removed numeric separators for constants.

## 0.4.0

### ✨ Features

* Optional metadata field to the constructor.

## 0.3.0

### 🐛 Issues

* Fixed correctly passing the `playHead` property.
* Fixed correctly passing custom metadata to the session request.
* Fixed an issue where the `chapterStart` parameters would be missing.
* Fixed some http issues during `sendEventRequest`.

### ✨ Features

* Improved sending error event.
* Improved property typing.

## 0.2.0

### 🐛 Issues

* Removed a `postinstall` script from package.json.
* Fixed an issue where the session would not be ended when destroying the connector.

## 0.1.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Adobe Edge Connector

An Adobe analytics connector for `@theoplayer/react-native` using the [Media Edge API](https://developer.adobe.com/client-sdks/edge/media-for-edge-network/).

Media Edge API is the third generation of solution for tracking Media Events. It features more analytics data, and the delay before the data can be analysed is much shorter: \~15 minutes compared to \~45 minutes with Media Heartbeats.

To set up terminology, in chronological order, media tracking solutions were:

1. Media Heartbeats solution
2. Media Collection API
3. Media Edge API

## Installation

```sh
npm install @theoplayer/react-native-analytics-adobe-edge
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance and a configuration object with separate parts for Web and mobile platforms.

```tsx
import {useAdobe} from '@theoplayer/react-native-analytics-adobe-edge';

const config = {
  web: {
    datastreamId: 'abcde123-abcd-1234-abcd-abcde1234567',
    orgId: 'ADB3LETTERSANDNUMBERS@AdobeOrg',
    edgeBasePath: 'ee',
    edgeDomain: 'my.domain.com',
    debugEnabled: true,
  },
  mobile: {
    environmentId: 'abcdef123456/abcdef123456/launch-1234567890abcdef1234567890abcdef12',
    debugEnabled: true,
  },
}

/**
 * An optional custom identity map to associate the media session with user identities.
 */
const customIdentityMap = {
  EMAIL: [
    {
      id: 'user@example.com',
      authenticatedState: 'authenticated',
      primary: false,
    },
  ],
}

const App = () => {
  const [adobe, initAdobe] = useAdobe(config, /* optional */ customIdentityMap);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize Adobe connector
    initAdobe(player);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

The Adobe connector will dispatch player events to Adobe with standard metadata the player has access to, such as duration or whether it is a live or vod.

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
import {AdobeCustomMetadataDetails} from "@theoplayer/react-native-analytics-adobe-edge";

const onUpdateMetadata = () => {
  const metadata: AdobeCustomMetadataDetails[] = [
    {name: 'title', value: 'test'},
    {name: 'custom1', value: 'value1'},
  ]
  adobe.current?.updateMetadata(metadata);
};
```

### Setting an custom identity map

Besides passing a custom identity map during initialization, you can also set or update the identity map at any time:

```typescript
import {AdobeIdentityMap} from "@theoplayer/react-native-analytics-adobe-edge";

const onUpdateIdentityMap = () => {
  const identityMap: AdobeIdentityMap = {
    CUSTOMER_ID: [
      {
        id: 'customer-12345',
        authenticatedState: 'authenticated',
        primary: true,
      },
    ],
  };
  adobe.current?.setIdentityMap(identityMap);
};
```

### Starting a new session during a live stream

By default, the connector will start a new session when a new asset is loaded. However, during live streams, you might want to start a new session periodically when a new program starts. You can do this by calling `stopAndStartNewSession` with the new program's metadata:

```typescript
const onNewProgram = () => {
  adobe.current?.stopAndStartNewSession({
    'friendlyName': 'Evening News',
  });
};
```

---

# @theoplayer/react-native-analytics-adobe-edge

## 1.3.4

### 🐛 Issues

* On web, retire potentially stale Adobe media sessions after prolonged suspension and restart tracking when content playback resumes. Preserve custom metadata, discard stale queued events, and ignore late confirmations from retired sessions. Keep Alloy's automatic tracking API; reliable cancellation of its retired-session pings requires the paired Alloy cleanup fix.

## 1.3.3

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.3.2

### 🐛 Issues

* Upgraded @adobe/alloy dependency to v2.35.0.

## 1.3.1

### 🐛 Issues

* Fixed an issue on Web where media events (e.g. `media.bitrateChange`) would fail with "Session ID is not available for playerId" when the media session start was not yet confirmed by the edge network. The session is now only marked as started after confirmation, failed session starts are retried, and tracker promise rejections no longer surface as unhandled promise rejections.
* Fixed an issue on Web where a playback session would not be tracked at all if the player's `loadedmetadata` event fired before the Adobe media tracker was initialized.
* Fixed an issue on Web where a media session would be left open on the edge network when the viewer changed source before the session start was confirmed.
* Fixed an issue where the Adobe VA Edge API would reject media events such as `adStart` and `adComplete` with a 400 Bad Request ("Playhead must be in range \[0, 86400] seconds") during live playback on platforms that report the playhead as an absolute presentation timestamp (e.g. Samsung Tizen). The playhead is now always clamped to the range accepted by the API.

## 1.3.0

### ✨ Features

* Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.2.1

### 🐛 Issues

* Bumped @adobe/alloy dependency to v2.34.1.

## 1.2.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.1.1

### 🐛 Issues

* Fixed an issue on Web where the `bitRate` property would not be passed as an integer value.
* Fixed an issue where the metadata set with `updateMetadata` would not be passed when starting a session.

## 1.1.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/adobe-edge/LICENSE) file for more information.

## 1.0.0

### 💥 Breaking Changes

* Updated the connector to use the latest Adobe Experience Platform Mobile and Web SDKs.

## 0.7.0

### ✨ Features

* Added optional native connector implementations for iOS and Android.

## 0.6.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 0.5.0

### ✨ Features

* Bumped dependency on react-native-device-info

## 0.4.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 0.3.2

### 🐛 Issues

* Fixed a build issue where the `Settings` object would not be found when using the connector with react-native-web.

## 0.3.1

### 📦 Dependency Updates

* Updated dependency `react-native-device-info` to version `>=10.0.0 <14.0.0`.

## 0.3.0

### ✨ Features

* Added support for THEOplayer 8.0

## 0.2.0

### ✨ Features

* Fixed an issue where ad duration was reported as a floating-point value instead of an integer.

## 0.1.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native AdScript Connector

A [Nielsen AdScript](https://adscript.admosphere.cz/) analytics connector for `@theoplayer/react-native`.

## Installation

```sh
npm install @theoplayer/react-native-analytics-adscript
```

## Prerequisites

### Android

On Android, the connector requires downloading the private [AdScript client library](https://adscript.admosphere.cz/download/AdScriptApiClient_v1.0.10.aar.gz) module into the app's `libs/` folder. Pass the SDK location to the connector by setting the `adScriptSdkDir` in your app's `gradle.properties` file:

```bash
# Location of the AdScript SDK
adScriptSdkDir=./app/libs/
```

### iOS & tvOS

On Apple platforms, the connector requires downloading the private `AdScriptAPIClient` archive.

Create a `Frameworks` folder in your app's `ios` folder, copy the Adscript SDK XCFramework in it and add this `AdScriptApiClient.podspec` file inside, which describes the structure and metadata of Adscript's CocoaPod:

```ruby
Pod::Spec.new do |spec|
  spec.name         = "AdScriptApiClient"
  spec.version      = "1.0.8"
  spec.summary      = "The Adscript Api Client for iOS"

  spec.homepage     = 'https://github.com/THEOplayer/iOS-Connector'
  spec.license      = { :type => 'MIT', :file => 'LICENSE' }
  spec.author       = "Dolby Laboratories, Inc."
  spec.source       = { :git => 'https://github.com/THEOplayer/iOS-Connector.git', :tag => spec.version.to_s }

  spec.source_files  = "Classes", "Classes/**/*.{h,m}"
  spec.ios.vendored_frameworks = "AdScriptApiClient.xcframework"
end
```

To enable IDFA (Identifier for Advertisers), replace the framework reference:

```text
spec.ios.vendored_frameworks = "AdScriptApiClient.xcframework"
```

with

```text
spec.ios.vendored_frameworks = "AdScriptApiClient_withidfa.xcframework"
```

Finally, include the AdScript SDK as dependency in your app's `Podfile`:

```ruby
  pod 'AdScriptApiClient', :path => 'Frameworks/'
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, an `implementationId`, and a `metadata` object.

```tsx
import { useAdScript, AdScriptMetadata } from '@theoplayer/react-native-analytics-adscript';

const adscriptImplementationId = "myImplementionId";
const adscriptContentMetadata: AdScriptMetadata = {
  assetId: "abc98731568435405",
  type: "content"
};

const App = () => {
  const [adscript, initAdScript] = useAdScript(adscriptImplementationId, adscriptContentMetadata, true /*debug*/);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize AdScript connector
    initAdScript(player);
  };

  return <THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady} />;
};
```

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
const onUpdateMetadata = () => {
  adscript.current?.updateMetadata({
    assetId: 'updatedId',
    type: "content",
    // ...
  });
}
```

### Passing additional information

Additional information about the logged-in user from the client database:

```typescript
const onUpdateUser = () => {
  adscript.current?.updateUser([
    "866d3a3c-aa87-4fe7-9066-8286641edd17",     // client-side user identifier (customerId)
    "cf895a00-a987-4501-ac00-6adb57014129",     // client-side user device identifier (Android_ID)
    "9530321a-d3d0-4bda-8704-1eb94a5940c3",     // client-side profile identifier of the logged-in user (profileId)
    "jsg75682-k276t-kw82-k8d5-8926sh6528j2",    // optional - SW device identifier for a situation where there are multiple device IDs in the client DB (typically a) HW ID - fill in i2, b) SW ID - fill in i4).
    "ef3c6dc72a26912f07f0e733d51b46c771d807bf"  // fingerprint of the user's email address
  ]);
}
```

---

# @theoplayer/react-native-analytics-adscript

## 1.5.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.5.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.4.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.3.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/adscript/LICENSE) file for more information.

## 1.2.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.1.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.1.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Agama Connector

An Agama analytics connector for `@theoplayer/react-native`. Currently only the Android/Android TV platforms is supported.

## Installation

### Dependencies

The `@theoplayer/react-native` package has peer dependencies on these packages, which have to be installed as well:

* `react-native-device-info` to obtain extra device information;
* `@react-native-async-storage/async-storage` to persistently store a unique deviceId across sessions;
* `@react-native-community/netinfo` to obtain information on network connection and quality.

```sh
npm install \
  react-native-device-info \
  @react-native-async-storage/async-storage \
  @react-native-community/netinfo \
  @theoplayer/react-native-analytics-agama
```

Some of these dependencies explicitly rely on `react-native` as a peer dependency. If you are using the `react-native-tvos` fork, it is necessary to specify this override in your package.json:

```json
  "overrides": {
    "react-native": "npm:react-native-tvos@^0.76.5-0"
  }
```

### Agama library

The Agama libraries need to be provided by the hosting app. Since they are privately hosted, you need to download them from [Agama's support site](https://support.agama.tv/). Put the libraries next to the source and load them at the start of the app, along with the necessary polyfills:

```typescript
import { AgamaPolyfills } from "@theoplayer/react-native-analytics-agama";

AgamaPolyfills.install();
require('./static/empclient.min');
require('./static/empclient.compat5.min');
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance and a [configuration object](https://github.com/THEOplayer/react-native-connectors/blob/-/agama/src/api/AgamaConfiguration.ts). A `useAgama` React hook is provided for convenience. It takes care of initialization and clean-up of the connector. It is also possible to create the connector explicitly by creating an instance of `AgamaConnector`, in which case the `destroy()` method must be called when destroying either the connector or the player.

```tsx
import { useAgama, AgamaConfiguration } from '@theoplayer/react-native-analytics-agama';

const config: AgamaConfiguration = {
  config: 'emp_service=http://127.0.0.1:8191/report;report_interval=60;id_report_interval=240;operator_id=fooSoo',
  logLevel: 'debug',
  application: 'React-Native THEOplayer',
  applicationVersion: '1.0.0'
}

const App = () => {
  const [agama, initAgama] = useAgama(config);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize Agama connector
    initAgama(player);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

### Source description

Source-related [analytics properties](https://github.com/THEOplayer/react-native-connectors/blob/-/agama/src/api/AgamaSourceConfiguration.ts) can be passed in the source description as follows:

```typescript
player.source = {
  "sources": {
    "src": "https://cdn.theoplayer.com/video/adultswim/clip.m3u8",
    "type": "application/x-mpegurl"
  },
  "analytics": [{
    "integration": "agama",
    "asset": "The Venture Bros",
    "cdn": "theoplayer",
    "serviceName": "svod",
    "contentTitle": "The Venture Bros",
    "streamType": "vod",
    "contentType": "movie",
    "contentDescription": "Agama demo movie"
  }]
}
```

As it is possible to configure more than one analytics integration, it is important to include the `integration: 'agama'` property to let the connector known which object to use.

---

# @theoplayer/react-native-analytics-agama

## 1.13.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.13.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.12.1

### 🐛 Issues

* Fixed an issue where the measuring network interceptor would cause ABR to break and make the player stall during play-out.

## 1.12.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.11.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/agama/LICENSE) file for more information.

## 1.10.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.9.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.8.0

### ✨ Features

* Bumped dependency on react-native-device-info

## 1.7.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.6.1

### 📦 Dependency Updates

* Updated dependency `react-native-device-info` to version `>=10.0.0 <14.0.0`.

## 1.6.0

### ✨ Features

* Added support for THEOplayer 8.0

## 1.5.0

### 🐛 Issues

* Fixed an issue where the player would jump to a different time stamp as result of a test left-over.

## 1.4.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

## 1.3.0

### ✨ Features

* Added optional `deviceType` property to `AgamaConfiguration` to overwrite the physical device type. By default, the `deviceType` is derived from the platform.

## 1.2.1

### 📦 Dependency Updates

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.2.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.1.1

### ✨ Features

* Added `SourceConfiguration` and `AgamaConfiguration` types to package exports.

### 🐛 Issues

* Fixed the location of `manifest.json` in order to make it discoverable for web platforms.

## 1.1.0

### 📦 Dependency Updates

* Set upper boundary on THEOplayer's Android SDK version.

## 1.0.3

### 🐛 Issues

* Fixed an issue where creating a build manifest would fail due to a missing dependency.

## 1.0.2

### 🐛 Issues

* Fixed an issue where creating a build manifest would fail due to a missing dependency.

## 1.0.1

### 🐛 Issues

* Fixed the keywords list in `package.json`.
* Fixed missing `manifest` script in npm package.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Bitmovin Connector

A Bitmovin analytics connector for `@theoplayer/react-native`.

## Installation

Using npm:

```sh
npm install @theoplayer/react-native-analytics-bitmovin
```

Using yarn:

```sh
yarn add @theoplayer/react-native-analytics-bitmovin
```

## Usage

### Configuring the connector

Create the connector using the `useBitmovin` hook with the initial configuration.

Once the player is ready, initialize the connector by calling the `initBitmovin` function with the `THEOplayer` instance and the **default metadata**, which contains properties that do not change during the session.

Finally, before the player source is set, update first the **source metadata** by calling the `updateSourceMetadata` function.

> **IMPORTANT:** Call `updateSourceMetadata` before setting the player source, otherwise the source metadata will not be included in the analytics events.

```tsx
import {
  useBitmovin,
  AnalyticsConfig,
  DefaultMetadata,
  SourceMetadata
} from '@theoplayer/react-native-analytics-bitmovin';

const bitmovinConfig: AnalyticsConfig = {
  licenseKey: 'license-key-here',
  logLevel: 'DEBUG'
}

const defaultMetadata: DefaultMetadata = {
  cdnProvider: 'akamai',
  customUserId: 'custom-user-id-1234',
  customData: {
    customData1: 'value1',
    customData2: 'value2'
  }
};

const sourceMetadata: SourceMetadata = {
  title: 'Sample Video',
  videoId: 'video-1234',
  cdnProvider: 'akamai',
  path: '/home/videos/sample-video',
  isLive: false,
  customData: {
    customData10: 'value10',
    customData11: 'value11'
  }
}

const App = () => {
  const [bitmovin, initBitmovin] = useBitmovin(bitmovinConfig);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize connector with player & default metadata.
    initBitmovin(player, defaultMetadata);

    // Update source metadata.
    bitmovin.updateSourceMetadata(sourceMetadata);

    // Set player source after updating source metadata.
    player.source = {/*...*/}
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

### Dynamically updating custom data

The connector allows updating the **custom data** at any time during the playback session, which will cause the new custom data to be merged with the existing custom data and included in all subsequent analytics events:

```tsx
bitmovin.updateCustomData({
  customData0: 'newValue0',
  customData1: 'newValue1'
});
```

### Updating source metadata during a live stream

The connector allows dynamically updating the **source metadata**, for example during a live stream when the program changes:

```tsx
bitmovin.programChange({
  title: 'New Live Program',
  videoId: 'live-program-5678',
  customData: {
    customData10: 'newValue10'
  }
});
```

### Getting the current impression ID

The current impression ID can be retrieved asynchronously. The promise resolves to `undefined` when there is no active impression or analytics session:

```tsx
const impressionId = await bitmovin.getImpressionId();
```

---

# @theoplayer/react-native-analytics-bitmovin

## 1.6.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.6.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.5.0

### ✨ Features

* Added a getter for the current Bitmovin `impressionId`.

## 1.4.1

### 🐛 Issues

* Fixed an issue on Android where R8 would obfuscate `setCustomData` methods of the Bitmovin collector API.

## 1.4.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.3.0

### ✨ Features

* Relax iOS Bitmovin collector dependency lock to major versions

## 1.2.0

### ✨ Features

* Updated `updateCustomData` to merge incoming `customData` with the existing data on iOS and Android.

## 1.1.0

### ✨ Features

* Added `sendCustomDataEvent` for Web.
* Upgraded Bitmovin Web SDK to GA release v2.51.

## 1.0.1

### 🐛 Issues

* Fixed an issue on iOS where the updateCustomData method was not correctly bridged.

## 1.0.0

### ✨ Features

* Updated Android Bitmovin player SDK dependency to version range `[3.24.0, 4.0.0)`.
* Changed `customData` to allow up to 100 custom fields.

## 1.0.0-alpha.12

### 🐛 Issues

* Fixed an issue where a wrong value for `customUserId` would be set on Android.

### 📦 Dependency Updates

* Upgraded iOS Bitmovin collector to GA release to prevent app store validation rejections.
* Upgraded Android Bitmovin collector to GA release v3.23.0.

## 1.0.0-alpha.11

### ✨ Features

* Added `programChange` method to allow passing new source metadata during a live stream.
* Added support for Web and iOS platforms.

## 1.0.0-alpha.10

### ✨ Features

* Initial release.

---

# THEOplayer React-Native Comscore Connector

A Comscore analytics connector for `@theoplayer/react-native`.

## Installation

```sh
npm install @theoplayer/react-native-analytics-comscore
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, a ComscoreConfiguration (which contains your publisher id) and the ComscoreMetadata of the first source you will set to the player (you can change it dynamically throughout the entire lifecycle of the connector):

```jsx
import { useComscore } from '@theoplayer/react-native-analytics-comscore';

export const comscoreMetadata: ComscoreMetadata = {
    mediaType: ComscoreMediaType.longFormOnDemand,
    uniqueId: 'testuniqueId',
    length: 634.566,
    stationTitle: 'THEOTV',
    programTitle: 'Big Buck Bunny',
    episodeTitle: 'Intro',
    genreName: 'Animation',
    classifyAsAudioStream: false,
    customLabels: {
        testcustomlabel: 'testcustomvalue'
    }
};

const comscoreConfig: ComscoreConfiguration = {
    publisherId: '<your publisher id (aka c2 id)',
    applicationName: '<your app name>',
    userConsent: ComscoreUserConsent.granted,
    usagePropertiesAutoUpdateMode: ComscoreUsagePropertiesAutoUpdateMode.foregroundOnly,
    debug: true
};

const App = () => {
    const [comscore, initComscore] = useComscore(COMSCORE_METADATA, comscoreConfig);

    const onPlayerReady = (player: THEOplayer) => {
        // Initialize Comscore connector
        initComscore(player);
    };

    return <THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady} />;
};
```

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
const onUpdateMetadata = () => {
    comscore.current.update({
        mediaType: ComscoreMediaType.longFormOnDemand,
        uniqueId: 'testuniqueId',
        length: 634.566,
        stationTitle: 'THEOTV',
        programTitle: 'Big Buck Bunny',
        episodeTitle: 'Intro',
        genreName: 'Animation',
        classifyAsAudioStream: false,
        customLabels: {
            testcustomlabel: 'testcustomvalue'
        }
    });
};
```

### ComscoreMetadata fields

Based on the `ComscoreMetadata` type, you can tell which fields are mandatory and which aren't. Note that this is purely for the integration to work correctly. Depending on the Comscore solution you are using, different fields are required/optional. The mandatory fields in the `ComscoreMetadata` type are the ones that are mandatory for all three Comscore solutions:

* Video Metrix (V)
* Cross Platform Product Suite (X)
* Cross Media Audience Measurement (C)

| Property                           | Required | Optional |
| ---------------------------------- | -------- | -------- |
| `mediaType`                        | All      |          |
| `uniqueId`                         | All      |          |
| `length`                           | All      |          |
| `c3?`                              | V        |          |
| `c4?`                              | V        |          |
| `c6?`                              | V        |          |
| `stationTitle`                     | All      |          |
| `stationCode?`                     |          | All      |
| `networkAffiliate?`                |          | All      |
| `publisherName?`                   | X C      | V        |
| `programTitle`                     | All      |          |
| `programId?`                       |          | V C      |
| `episodeTitle`                     | All      |          |
| `episodeId?`                       |          | X C      |
| `episodeSeasonNumber?`             | X C      |          |
| `episodeNumber?`                   | X C      |          |
| `genreName`                        | All      |          |
| `genreId?`                         |          | All      |
| `carryTvAdvertisementLoad?`        | X        |          |
| `classifyAsCompleteEpisode?`       | X        |          |
| `dateOfProduction?`                |          | C        |
| `timeOfProduction?`                |          | C        |
| `dateOfTvAiring?`                  | X C      |          |
| `timeOfTvAiring?`                  |          | X C      |
| `dateOfDigitalAiring?`             | X C      |          |
| `timeOfDigitalAiring?`             |          | X C      |
| `feedType?`                        | X        |          |
| `classifyAsAudioStream`            | Al       |          |
| `deliveryMode?`                    |          | All      |
| `deliverySubscriptionType?`        |          | All      |
| `deliveryComposition?`             |          | All      |
| `deliveryAdvertisementCapability?` |          | All      |
| `mediaFormat?`                     |          | All      |
| `distributionModel?`               |          | All      |
| `playlistTitle?`                   |          | C        |
| `totalSegments?`                   |          | V C      |
| `clipUrl?`                         |          | V C      |
| `videoDimension?`                  |          | C        |
| `customLabels?`                    |          | All      |

---

# @theoplayer/react-native-analytics-comscore

## 1.15.2

### 🐛 Issues

* Fixed Android builds failing with `Dependency 'com.comscore:android-analytics:6.16.0' requires ... compile against version 37 or later of the Android APIs` on apps compiled against android-36. The connector's floating `6.+` dependency now defaults to `6.15.+`, staying below the version that declares `minCompileSdk=37`, which is unsupported by current Android Gradle plugin releases. Apps that already target a newer compileSdk can still override via `THEOplayerComscore_comscoreVersion`.

## 1.15.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.15.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.14.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.13.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/comscore/LICENSE) file for more information.

## 1.12.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.11.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.11.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.10.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.9.0

### ✨ Features

* Passing the usagePropertiesAutoUpdateMode configuration property to the native iOS connector.

## 1.8.2

### 🐛 Issues

* Fixed an issue on iOS where the podspec files did not contain all references when not using the New Architecture.

## 1.8.1

### 🐛 Issues

* Fixed an issue on iOS where the project would not build when used in a project that has New Architecture enabled.

## 1.8.0

### ✨ Features

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors

## 1.7.1

### 🐛 Issues

* Deleted dependency on the removed ad module for Android.

## 1.7.0

### ✨ Features

* Added support for THEOplayer 8.0

## 1.6.0

### 📦 Dependency Updates

* Removed setup for Mux connector on tvOS. The Mux pod is only available for iOS.
* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

## 1.5.0

### 🐛 Issues

* Fixed an issue on Android where `notifyPlay()` was not called when the player would resume play-out.
* Fixed an issue on Android where the user consent variables were not properly passed.
* Fixed an issue on Web where the player position is reported as a decimal value instead of an integer.

### ✨ Features

* Added the `usagePropertiesAutoUpdateMode` option to `ComscoreConfiguration` to indicate whether background playback is supported.

## 1.4.1

### ✨ Features

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.4.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.3.0

### 🐛 Issues

* Fixed an issue on Web where some `duration` and `currentTime` values were reported wrong.

## 1.2.0

### 🐛 Issues

* Fixed an issue on Android where the usage properties would not update when the app transitions to the background.

## 1.1.0

### 📦 Dependency Updates

* Updated Web dependency to Comscore SDK v7.7.0

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Conviva Connector

A Conviva analytics connector for `@theoplayer/react-native`.

## Installation

```sh
npm install @theoplayer/react-native-analytics-conviva
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, some initial metadata and a config object:

```jsx
import { useConviva } from '@theoplayer/react-native-analytics-conviva';

const convivaMetadata: ConvivaMetadata = {
  ['Conviva.applicationName']: 'THEOplayer',
  ['Conviva.viewerId']: 'your_viewer_id'
};

const convivaConfig: ConvivaConfiguration = {
  customerKey: 'your_customer_key',
  debug: true,
  gatewayUrl: 'https://[account]-test.ts-testonly.conviva.com'
};

const App = () => {
  const [conviva, initConviva] = useConviva(convivaMetadata, convivaConfig);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize connector
    initConviva(player);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

The `convivaMetada` object contains key-value pairs that are passed directly to the Conviva SDK. Most media related properties, such as its streamURL, duration or whether it is a live or vod stream, are passed by the connector itself. Any metadata related properties can be passed through the open key-value map:

| Key                   | Value                           |
| --------------------- | ------------------------------- |
| `'Conviva.assetName'` | Asset name of the next program. |
| `'customTag'`         | Any custom value.               |

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
const onUpdateMetadata = () => {
  const metadata: ConvivaMetadata = {
    ['customTag1']: "customValue1",
    ['customTag2']: "customValue2",
  };
  conviva.current?.setContentInfo(metadata);
};
```

---

# @theoplayer/react-native-analytics-conviva

## 1.15.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.15.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

### 🐛 Issues

* * Bumped the default Conviva Core SDK version on Android to v4.0.51.

## 1.14.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.13.1

### 🐛 Issues

* Fixed an issue on iOS where the native ios connector version was locked to 10.8 patch updates.

## 1.13.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/conviva/LICENSE) file for more information.

## 1.12.0

### ✨ Features

* Passing initial metadata as persistent conviva metadata on iOS

## 1.11.1

### 🐛 Issues

* Fixed an issue where a platform-based import could cause compilation issues on Android and iOS platforms.

## 1.11.0

### ✨ Features

* Added support for Amazon Vega OS.
* Updated Android's target SDK version to 36.

### 🐛 Issues

* Fixed an issue where on iOS the stopAndStartNewSession was blocked when the player was in a paused state.

## 1.10.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.10.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.9.1

### 🐛 Issues

* Fixed an issue where the connector would output a `HashMap` conversion build error for Android platforms.

## 1.9.0

### ✨ Features

* Added support for THEOplayer 9.0.

### 🐛 Issues

* Fixed an issue on Android where an app would crash when accessing the connector's `stopAndStartNewSession` method.

## 1.8.3

### 🐛 Issues

* Fixed an issue on Android where the optional `debug` property in `ConvivaConfiguration` was treated as being required.

### ✨ Features

* Added the option on Android to allow setting a different connector version using `THEOplayerName_connectorVersion`.

## 1.8.2

### 🐛 Issues

* Fixed an issue on iOS where the podspec files did not contain all references when not using the New Architecture.

## 1.8.1

### 🐛 Issues

* Fixed an issue on iOS where the project would not build when used in a project that has New Architecture enabled.

## 1.8.0

### ✨ Features

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors

## 1.7.1

### 🐛 Issues

* Deleted dependency on the removed ad module for Android.

## 1.7.0

### ✨ Features

* Added support for THEOplayer 8.0

## 1.6.0

### ✨ Features

* Added support for broadcasted ad events.

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

### 🐛 Issues

* Fixed an issue where on iOS (^17.2) bitrate reporting was broken due to a deprecated iOS notification name.

## 1.5.1

### 📦 Dependency Updates

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.5.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.4.0

### 📦 Dependency Updates

* Upgraded connector for Web to 1.2.0.

## 1.3.0

### 📦 Dependency Updates

* Upgraded connector for Android to 5.10.0-1 with dependency on Conviva sdk 4.0.33.
* Upgraded Android compileSdk and targetSdk versions to 33.

### ✨ Features

* Updated example app to use @theoplayer/react-native-ui.

## 1.2.1

### 📦 Dependency Updates

* Updated connector for Web to v1.1.7.

## 1.2.0

### 📦 Dependency Updates

* Updated connector for Web to v1.1.6.
* Updated connector for Android to v5.6.0-1.

## 1.1.0

### 🐛 Issues

* Fixed an issue on iOS where the bitrate was not reported after a stop and start new session action.

## 1.0.0

### ✨ Features

* Initial release

---

# React Native THEOplayer DRM

The `@theoplayer/react-native-drm` package provides a set of connectors for [react-native-theoplayer](https://github.com/THEOplayer/react-native-theoplayer), allowing playback of DRM-protected content.

## Installation

```sh
npm install @theoplayer/react-native-drm
```

## Usage

The connector needs to be registered to the `ContentProtectionRegistry`, providing both `integrationId` and `keySystemId`:

```typescript
import { ContentProtectionRegistry } from 'react-native-theoplayer';
import { EzdrmFairplayContentProtectionIntegrationFactory } from 'react-native-theoplayer-drm';

ContentProtectionRegistry.registerContentProtectionIntegration(
  'ezdrm',   // integrationId
  'fairplay', // keySystemId
  new EzdrmFairplayContentProtectionIntegrationFactory()
);
```

The combination of both `integrationId` and `keySystemId` points the player towards the connector for a specific source, in this case the `ezdrm` connector for `fairplay`:

```typescript
const source = {
  "sources": {
    "src": "<source_url>",
    "contentProtection": {
      "integration": "ezdrm",
      "fairplay": {
        "certificate": "<base64encoded_certificate>",
        "licenseAcquisitionURL": "<license_url>"
      },
    }
  }
};
```

## Connectors

The [THEOplayer DRM integrations repository](https://github.com/THEOplayer/samples-drm-integration) contains a list of integrations for native Web, Android & iOS THEOplayer SDKs.

As the content protection API of `react-native-theoplayer` is very similar to that of THEOplayer's native Web SDK, the available Web connectors can mostly be reused as-is. These connectors are not available as npm packages however, and sometimes have dependencies on web-specific utilities. Because of this, the `@theoplayer/react-native-drm` package provides the following connectors, readily available to be used by `react-native-theoplayer`:

| Vendor                       | Widevine | Playready | FairPlay |
| ---------------------------- | -------- | --------- | -------- |
| BuyDRM KeyOS                 | ✓        | ✓         | ✓        |
| EZDRM                        | ✓ (\*)   | ✓ (\*)    | ✓        |
| Verimatrix MultiDRM Core DRM | ✓        | ✓         | ✓        |
| Anvato                       | ✓        | ✗         | ✓        |
| Axinom                       | ✓        | ✗         | ✓        |
| CastLabs                     | ✓        | ✓         | ✓        |
| PallyCon                     | ✗        | ✗         | ✓        |
| MediaKind                    | ✓ (\*)   | ✓ (\*)    | ✓        |

(\*) No connector is needed for these DRM vendors; it is handled by the player's default DRM flow.

---

# @theoplayer/react-native-drm

## 1.14.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.13.0

### ✨ Features

* Added integration for MediaKind DRM.

## 1.12.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.11.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/drm/LICENSE) file for more information.

## 1.10.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.9.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.8.1

### 🐛 Issues

* Prevent warning on named export for version API

## 1.8.0

### ✨ Features

* Add sdkVersions to connector API

## 1.7.1

### 🐛 Issues

* Fixed an issue where the npm package would not contain the proper build files.

## 1.7.0

### ✨ Features

* Added support for THEOplayer 8.0.

## 1.6.0

### ✨ Features

* Changed the BuyDRM KeyOS connector to work without the `x-keyos-authorization` header.

## 1.5.0

### ✨ Features

* Added BuyDRM KeyOS connector for fairplay, widevine and playready.
* Added support for `react-native-theoplayer` v7.0.0.

## 1.4.0

### ✨ Features

* Added Axinom connector for fairplay and widevine.

## 1.3.1

### 🐛 Issues

* Fixed an issue where the PallyCon connector was not included in the module exports.

## 1.3.0

### ✨ Features

* Added CastLabs connector.
* Added PallyCon connector.
* Optimized `readStreamAsArrayBuffer` method.

## 1.2.0

### 🐛 Issues

* Fixed an issue in the Anvato DRM connector where the license request response body was not correctly processed.

## 1.1.0

### ✨ Features

* Added license request error result for Anvato connector.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Engage Connector

An Engage connector for `@theoplayer/react-native`. Currently only Android platforms are supported.

## Overview

The Engage connector aims to **re-engage users** with your app by offering interesting content, promotions and deals. Users can be driven directly to a relevant page within your app using **deep links**.

Typical use-cases are the **"Continue Watching"** feature, which allows users to continue media play-back from where they left off bookmarks, **(personalized) recommendations** promoting content that might be of interest to the user, or a **sign-in** option that navigates users to the sign-in page of your app.

Currently, the engage connector only supports the [Android Engage SDK](https://developer.android.com/guide/playcore/engage).

### Terminology

In this document, we will refer to the following concepts:

* **Entity**: A content asset, which can be a "*movie*", "*tvShow*", "*tvSeason*", "*tvEpisode*", "*liveStream*", "*videoClip*", "*signIn*" or "*subscription*".

* **Cluster**: A collection of entities grouped together in single UI view. Available types are:

  * "*Continuation*" or "*Continue Watching*": Contains unfinished videos and relevant newly released episodes.
  * "*Featured*": Showcases a selection of entities.
  * "*Recommendation*": Shows personalized content suggestions.

## Installation

In addition to installing the engage connector module, it is also necessary to add a dependency to `react-native-mmkv` to allow persistently storing engage data.

```sh
npm install \
  @theoplayer/react-native-engage \
  react-native-mmkv
```

The Engage SDK is set as a peer dependency, so the Android app using it still has to add an explicit dependency in Gradle, for mobile applications:

```text
implementation "com.google.android.engage:engage-core:1.5.4"
```

or, for Android TV:

```text
implementation "com.google.android.engage:engage-tv:1.0.0"
```

## Usage

### Creating a connector instance

Create an instance of an Engage client, using either the convenient `useEngage` hook or by creating a direct instance of the connector:

```tsx
const engageConfig = {
  debug: true,
  recommendationTitle: "Because you enjoyed",
};

// Creating a client instance using the connector
const client = await EngageConnector.createClient(engageConfig);

// ... or, alternatively, by using a hook
const engage = useEngage(engageConfig);
```

### Creating clusters

Using the Engage connector API, a *cluster* can be created, or requested if it already exists on the device. A cluster is a grouped set of data which can be of type "Continuation" (or "Continue Watching"), "Featured" or "Recommendation".

```tsx
import { ClusterType, ContinuationClusterConfig } from "@theoplayer/react-native-engage";

const continuationConfig: ContinuationClusterConfig = {
  accountProfile: {
    accountId: 'accountId',
    profileId: 'profileId'
  },
  syncAcrossDevices: false
}

// Create or get the "Continuation" cluster.
const continuation = client.getCluster(ClusterType.Continuation, continuationConfig);
```

Alternatively, the `useCluster` hook can be used:

```tsx
const continuation = useCluster(engage, ClusterType.Continuation, continuationConfig);
```

### Updating or "publishing" cluster data

The cluster data can be updated either **manually** by manipulating its entities:

```tsx
// Add or remove continuation entities.
continuation.addEntity({
  id: "id0",
  name: "The Dark Knight",
  posters: [/**/],
  // ...
});
```

or when requested **by the connector**. For example, on Android platforms when a broadcast message is sent to the app, or when a scheduled update request is set (e.g., each 12 hours).

### Persisting cluster data

The cluster data is persistently stored on the device each time it is changed. When the app reopens and creates a new Engage client, the stored that will be loaded first.

### Personalized experience

#### SignIn entity

An optional "*signIn*" entity can be displayed on the engage surface, which directs users to a sign-in page of the app.

```typescript
const signIn: SignIn = {
  type: EntityType.SignIn,
  name: "Sign In Demo",
  subtitle: "Demonstrates usage of sign-in card",
  actionUri: "https://xyz.com/signin",
  actionText: "Sign In",
  posters: [
    {
      uri: "https://xyz.com/signin.png",
      width: 320,
      height: 180,
      theme: ImageTheme.Light
    }
  ]
}

engage?.setSignInEntity(signIn);
```

#### Subscription and entitlement data

In addition, it is possible to share app subscription and entitlement data via the Engage SDK, allowing users to easily find content they are entitled to and enable Google TV to deliver highly relevant content recommendations to users, directly within their Google TV experiences on TV, mobile and tablet.

Subscription information can be published whenever the user performs one of the following actions:

* The user logs in to the app;
* The user switches between profiles, if the app supports single account with multiple profiles;
* The user purchases a new subscription;
* The user upgrades an existing subscription;
* An existing user subscription or tiered subscription expires;

```typescript
const accountProfile = {
  accountId: 'testAccountId',
  profileId: 'testProfileId'
}

const subscription: Subscription = {
  type: EntityType.Subscription,
  providerPackageName: 'testProviderPackage',
  subscriptionType: SubscriptionType.Active
}

engage?.setSubscription(accountProfile, subscription);
```

The "*subscription*" entity that contains one or more entitlements.

## Validating the published items

On Android, the [Verification App ](https://developer.android.com/guide/playcore/engage/workflow#shared-files)can be used to check the state and contents of all published clusters. Warnings are shown in case the published data does not satisfy the requirements.

| ![](/pr-932/assets/images/verification_app_1-ae90dab88fff325e81c2ea7f8fc6daa9.png) | ![](/pr-932/assets/images/verification_app_2-b2a56fe09fe65b7c138c71903eb21a86.png) |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Published Continuation cluster**                                                 | **Published Feature cluster with warnings**                                        |

## Example application

The example app showcases the integration of the Engage connector in a React Native application.

### Manipulating clusters

Tapping items (or entities) will add them to the "Continuation" cluster, while tapping items in the Continuation cluster will remove them again. On each update the cluster is persistently stored and published to the platform.

### Unpublished clusters

Tapping the bin icon results in removing and unpublishing (deleting) the cluster from the platform.

| ![](/pr-932/assets/images/example_app_1-bb6d1f16fc649a29ec6467ff7999ace3.png) | ![](/pr-932/assets/images/example_app_2-6fed560d9d0480fc9d1407dbb4bf0afc.png) |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Continuation and Featured clusters**                                        | **Swimlanes with entities**                                                   |

---

# @theoplayer/react-native-engage

## 0.6.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 0.6.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/engage/LICENSE) file for more information.

## 0.5.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 0.4.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 0.3.0

### ✨ Features

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors

## 0.2.1

### 🐛 Issues

* Enforced mandatory entity attributes.

## 0.2.0

### ✨ Features

* Added support for React Native v0.75.

## 0.1.2

### 🐛 Issues

* Fixed an issue where bundling the connector for Web would result in a recursive import error.

## 0.1.1

### ✨ Features

* Downgraded to default Kotlin dependency to version 1.8.22.
* Upgraded to version 1.5.4 of the Android Engage SDK.
* Made the engage SDK a peer dependency by using `compileOnly` in Gradle.
* Added the `Subscription` and `SignIn` entities with an API to set the current user subscription and signIn card.

### 📦 Dependency Updates

* Replaced async-storage with react-native-mmkv for persistent key-value storage.

## 0.1.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Gemius Connector

A Gemius analytics connector for `@theoplayer/react-native`.

## Installation

```sh
npm install @theoplayer/react-native-analytics-gemius
```

## Prerequisites

### Android

The Gemius Android SDK is not publicly available as a Maven module, so additional work is needed to include it as connector dependency. It requires downloading the private `GemiusSDK_2.0.8.aar` module into the app's `libs/` folder. The SDK location needs to be passed to the connector by setting the `gemiusSdkDir` in your app's `gradle.properties` file:

```bash
# Location of the Gemius SDK
gemiusSdkDir=./app/libs/
```

If a different version of the Gemius SDK is used than the default (v2.0.8), make sure to update the version in the `gradle.properties` file accordingly:

```text
THEOplayerGemius_gemiusVersion=2.0.8
```

### iOS & tvOS

On Apple platforms, the connector requires downloading the private `GemiusSDK_iOS` archive, which contains a multiplatform binary platform module for both iOS and tvOS.

Create a `Frameworks` folder in your app's `ios` folder, copy the Gemius SDK XCFrameworks in it and add this `GemiusSDK.podspec` file inside, which describes the structure and metadata of Gemius's CocoaPod:

```ruby
Pod::Spec.new do |spec|
  spec.name         = "GemiusSDK"
  spec.version      = "2.0.6"
  spec.summary      = "The Gemius SDK for iOS"

  spec.homepage     = 'https://github.com/THEOplayer/iOS-Connector'
  spec.license      = { :type => 'MIT', :file => 'LICENSE' }
  spec.author       = "Dolby Laboratories, Inc."
  spec.source       = { :git => 'https://github.com/THEOplayer/iOS-Connector.git', :tag => spec.version.to_s }

  spec.source_files  = "Classes", "Classes/**/*.{h,m}"
  spec.ios.vendored_frameworks = "GemiusSDK.xcframework"
  spec.tvos.vendored_frameworks = "GemiusSDKtvOS.xcframework"
end
```

Finally, include the Gemius SDK as dependency in your app's `Podfile`:

```ruby
  pod 'GemiusSDK', :path => 'Frameworks/'
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance and a `GemiusConfiguration` object.

```tsx
import { useGemius, GemiusConfiguration, ProgramType } from '@theoplayer/react-native-analytics-gemius';

const gemiusConfig: GemiusConfiguration = {
  applicationName: "Demo",
  applicationVersion: "1.0",
  hitCollectorHost: "your_hit_collector_host",
  gemiusId: "your_gemius_id",
  debug: true
}

const App = () => {
  const [gemius, initGemius] = useGemius(gemiusConfig);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize Gemius connector
    initGemius(player);
  };

  return <THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady} />;
};
```

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
const onUpdateMetadata = () => {
  gemius.current?.update('programId', {
    name: 'Demo asset',
    duration: 1200,
    programType: ProgramType.VIDEO,
    customKey: 'customValue',
    // ...
  });
}
```

---

# @theoplayer/react-native-analytics-gemius

## 1.5.2

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.5.1

### 🐛 Issues

* Fixed a compilation error on iOS with THEOplayer SDK 11, where the `Ad.adBreak` property became optional.

## 1.5.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.4.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.3.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/gemius/LICENSE) file for more information.

## 1.2.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.1.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.1.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Mux Connector

A Mux analytics connector for `@theoplayer/react-native`, supporting Web, iOS and Android.

## Installation

```sh
npm install @theoplayer/react-native-analytics-mux
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, some initial metadata and a config object:

```jsx
import { useMux } from '@theoplayer/react-native-analytics-mux';

const muxOptions = {
  debug: true,
  data: {
    env_key: 'ENV_KEY', // required
    // Site Metadata
    viewer_user_id: '12345',
    experiment_name: 'player_test_A',
    sub_property_id: 'cus-1',
    // Player Metadata
    player_name: 'My Main Player',
    player_version: '1.0.0',
    player_init_time: 1451606400000,
    // Video Metadata
    video_id: 'abcd123',
    video_title: 'My Great Video',
    video_series: 'Weekly Great Videos',
    video_duration: 12000, // in milliseconds
    video_stream_type: 'on-demand', // 'live' or 'on-demand'
    video_cdn: 'Akamai'
  }
};

const App = () => {
  const [mux, initMux] = useMux();

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize connector
    initMux(player, muxOptions);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

### Change program within a stream

In some cases, you may have the program change within a stream, and you may want to track each program as a view on its own. An example of this is a live stream that streams multiple programs back to back.

For this purpose, the `changeProgram` method can signal the start of a new program and pass updated metadata to the connector.

```typescript
mux.current?.changeProgram({
  video_title: 'New program',
  video_duration: 160000
});
```

---

# @theoplayer/react-native-analytics-mux

## 1.14.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.14.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.13.1

### 🐛 Issues

* * Bumped Mux SDK version to v0.8.0 to support OptiView player SDK v11.

## 1.13.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.12.0

### ✨ Features

* Updated Mux SDK to support OptiView player v10.

## 1.11.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/mux/LICENSE) file for more information.

## 1.10.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.9.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.9.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.8.0

### 📦 Dependency Updates

* Updated iOS Mux dependency to v0.13.

## 1.7.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.6.3

### 📦 Dependency Updates

* Updated dependencies on Android, allowing THEOplayer v8 and using latest Mux connector version.

## 1.6.2

### 🐛 Issues

* Fixed an issue on iOS where the podspec files did not contain all references when not using the New Architecture.

## 1.6.1

### 🐛 Issues

* Fixed an issue on iOS where the project would not build when used in a project that has New Architecture enabled.

## 1.6.0

### ✨ Features

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors

## 1.5.0

### 📦 Dependency Updates

* Updated the mux connector on Android to be compatible with THEOplayer v8 versions.

### 🐛 Issues

* Changed the `useMux` hook to allow the `MuxOptions` to be passed with the initialize instead of directly passing it into the hook itself.
* Fixed an issue on iOS where an incorrect THEOplayer version would be passed.

## 1.4.1

### 🐛 Issues

* Deleted dependency on the removed ad module for Android.

## 1.4.0

### ✨ Features

* Fixed a issue where the connector would crash when using Mux-Stats-THEOplayer 0.7 in combination with recent react-native-theoplayer releases.

## 1.3.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

## 1.2.0

### 🐛 Issues

* Fixed and issue on Android where Mux's Maven repository was not included in the root repository list.

## 1.1.1

### 📦 Dependency Updates

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.1.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Nielsen Connector

A Nielsen analytics connector for `@theoplayer/react-native`.

## Installation

```sh
npm install @theoplayer/react-native-analytics-nielsen
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, the `appId` provided by Nielsen, and `instanceName` that describes the player or site, and an optional set of `NielsenOptions`:

```tsx
import { useNielsen, NielsenOptions } from '@theoplayer/react-native-analytics-nielsen';

const appId = 'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX';

const instanceName = 'THEOplayer demo';

const nielsenOptions: NielsenOptions = {
  // Enables Debug Mode which allows output to be viewed in console
  nol_sdkDebug: 'debug'

  // HTML DOM element id of the player container (if implementing Viewability/Audibility)
  // containerId: 'player1',

  // Optout on initialization of the SDK
  // optout: false,
};

const App = () => {
  const [nielsen, initNielsen] = useNielsen(appId, instanceName, nielsenOptions);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize Nielsen connector
    initNielsen(player);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

### Passing metadata dynamically

The connector allows passing or updating the current asset's metadata at any time:

```typescript
const onUpdateMetadata = () => {
  nielsen.current?.updateMetadata({
    'title': 'Episode Title',
    'assetid': 'unique_id_500291'
  });
};
```

---

# @theoplayer/react-native-analytics-nielsen

## 1.13.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.13.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.12.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.11.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/nielsen/LICENSE) file for more information.

## 1.10.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.9.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.9.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.8.1

### 🐛 Issues

* Fixed an issue where the connector would output a `HashMap` conversion build error for Android platforms.

## 1.8.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.7.3

### 🐛 Issues

* Fixed an issue where the `NielsenOptions` type would not be properly provided by the package.

### ✨ Features

* Added the option on Android to allow setting a different connector version using `THEOplayerName_connectorVersion`.

## 1.7.2

### 🐛 Issues

* Fixed an issue on iOS where the podspec files did not contain all references when not using the New Architecture.

## 1.7.1

### 🐛 Issues

* Fixed an issue on iOS where the project would not build when used in a project that has New Architecture enabled.

## 1.7.0

### ✨ Features

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors

## 1.6.0

### ✨ Features

* Apply correct update mechanism for nielsen options dictionary

## 1.5.1

### 🐛 Issues

* Deleted dependency on the removed ad module for Android.

## 1.5.0

### ✨ Features

* Added support for THEOplayer 8.0

## 1.4.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

## 1.3.0

### 📦 Dependency Updates

* Upgraded Nielsen Android SDK to v9.2.0.0.
* Depend on latest Nielsen Android connector from Maven repository.
* Upgraded Nielsen web connector to v1.1.2.

## 1.2.0

### ✨ Features

* Removed any existing connector from the player on Android before attaching a new instance, avoiding duplicates.

## 1.1.1

### 📦 Dependency Updates

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.1.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Yospace Connector

A Yospace Server-Side Ad Insertion (SSAI) connector for `@theoplayer/react-native`. The connector only supports Android platforms for now.

## Installation

```sh
npm install @theoplayer/react-native-yospace
```

The connector uses the **private Yospace SDK**, for which credentials need to be configured.

### Android

On Android, configure the Maven repository credentials either setting project properties, for example in the `gradle.properties` file:

```text
YOSPACE_USERNAME=myUserName
YOSPACE_PASSWORD=myPassword
```

or, alternatively, by setting both `YOSPACE_USERNAME` and `YOSPACE_PASSWORD` as environment variables on your build system. Make sure not to expose them!

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, some initial metadata and a config object:

```tsx
import { useYospace, YospaceSSAIConfiguration } from '@theoplayer/react-native-yospace';

const App = () => {
  const [yospace, initYospace] = useYospace();

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize connector
    initYospace(player);

    // Set source with ssai integration 'yospace', and optional session properties.
    player.source = {
      sources: [
        {
          src: 'https://csm-e-sdk-validation.bln1.yospace.com/csm/extlive/yospace02,hlssample42.m3u8?yo.br=true&yo.av=4',
          type: 'application/x-mpegurl',
          ssai: {
            integration: 'yospace',

            // Optional, the default is 'live'.
            streamType: 'live',

            // Optional session properties
            //
            // @see YospaceSessionProperties.ts for available properties.
            sessionProperties: {
              prefetchResources: true
            }
          } as YospaceSSAIConfiguration
        }
      ]
    }
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

---

# @theoplayer/react-native-yospace

## 1.8.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.8.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.7.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.6.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/yospace/LICENSE) file for more information.

## 1.5.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.4.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.4.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.3.1

### 🐛 Issues

* Fixed an issue where the connector would throw an error while building on Android.

## 1.3.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.2.3

### 🐛 Issues

* Fixed an issue on iOS where the podspec files did not contain all references when not using the New Architecture.

## 1.2.2

### 🐛 Issues

* Fixed an issue on iOS where the project would not build when used in a project that has New Architecture enabled.

## 1.2.1

### 🐛 Issues

* Deleted dependency on the removed ad module for Android.

## 1.2.0

### ✨ Features

* Added support for THEOplayer 8.0

## 1.1.0

### ✨ Features

* Passed default debug flags to disable any logging.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer React-Native Youbora Connector

A Youbora analytics connector for `@theoplayer/react-native`.

## Installation

```sh
npm install @theoplayer/react-native-analytics-youbora
```

## Usage

### Configuring the connector

Create the connector by providing the `THEOplayer` instance, the `appId` provided by Youbora, and `instanceName` that describes the player or site, and an optional set of `YouboraOptions`:

```tsx
import { useYoubora, youbora } from '@theoplayer/react-native-analytics-youbora';

const youboraOptions: youbora.Options = {
  'accountCode': 'powerdev',
  // 'username': 'dev',
  // 'parse.HLS': true,
  // 'parse.CDNNode': true,
  // 'network.ip': '1.1.1.1',
  // 'network.isp': 'MyISP',
  // 'network.connectionType': 'dialup',
  // 'content.transactionCode': 'myTransCode',
  // 'content.resource': 'mysrc.mp4',
  'content.isLive': true,
  'content.title': 'My Title',
  // 'content.title2': 'My Title2',
  // 'content.duration': 100,
  // 'content.fps': '100',
  // 'content.bitrate': 1000000,
  // 'content.throughput': 8000000,
  // 'content.rendition': 'My Rendition',
  // 'content.cdn': 'NICE264',
  // 'content.metadata': {
  //   custom_info: 'info'
  // },
  // 'ad.metadata': {
  //   custom_info: 'info'
  // },
  // 'extraparam.1': 'myExtraParam1',
  // 'extraparam.2': 'myExtraParam2'
};

const App = () => {
  const [_youboraConnector, initYoubora] = useYoubora(youboraOptions, youbora.Log.Level.DEBUG);

  const onPlayerReady = (player: THEOplayer) => {
    // Initialize Youbora connector
    initYoubora(player);
  }

  return (<THEOplayerView config={playerConfig} onPlayerReady={onPlayerReady}/>);
}
```

### Configuration on iOS

As outlined on the native iOS connector's [git repository](https://bitbucket.org/npaw/theoplayer-adapter-ios), the app's Podfile still needs to include a dependency to the THEOplayerSDK by adding a pre-install script:

```ruby
  pre_install do |installer|
    ios_youbora_target = installer.pod_targets.find { |t| t.name == "YouboraTHEOPlayerAdapter-iOS" }
    ios_theoplayer_target = installer.pod_targets.find { |t| t.name == "THEOplayerSDK-core-iOS"}
    puts "Adding THEOplayerSDK-core-iOS as a target dependency to YouboraTHEOPlayerAdapter-iOS"
    ios_youbora_target.dependent_targets <<= ios_theoplayer_target
    tvos_youbora_target = installer.pod_targets.find { |t| t.name == "YouboraTHEOPlayerAdapter-tvOS"}
    tvos_theoplayer_target = installer.pod_targets.find { |t| t.name == "THEOplayerSDK-core-tvOS"}
    puts "Adding THEOplayerSDK-core-tvOS as a target dependency to YouboraTHEOPlayerAdapter-tvOS"
    tvos_youbora_target.dependent_targets <<= tvos_theoplayer_target
  end
```

If you are using a single target project this reduces to

```ruby
  pre_install do |installer|
    youbora_target = installer.pod_targets.find { |t| t.name == "YouboraTHEOPlayerAdapter" }
    theoplayer_target = installer.pod_targets.find { |t| t.name == "THEOplayerSDK-core"}
    puts "Adding THEOplayerSDK-core as a target dependency to YouboraTHEOPlayerAdapter"
    youbora_target.dependent_targets <<= theoplayer_target
  end
```

---

# @theoplayer/react-native-analytics-youbora

## 1.8.1

### 🐛 Issues

* Fixed a Gradle configuration failure on Android Gradle Plugin 9, where the connector's explicit `kotlin-android` plugin collided with AGP's built-in Kotlin support and failed with `Cannot add extension with name 'kotlin'`. The plugin is now applied only when nothing has registered the `kotlin` extension yet, so AGP 8 is unaffected.

## 1.8.0

### ✨ Features

* * Restricted the supported OptiView (THEOplayer) player versions to v10 and v11. On Android, the default `THEOplayer_sdk` version range is now `[10.0.0, 12.0.0)` for every connector.

## 1.7.0

### ✨ Features

* Added support for THEOplayer v11 and React Native THEOplayer v11.

## 1.6.0

### ✨ Features

* Changed license to BSD 3-Cause Clear. See [LICENSE](https://github.com/THEOplayer/react-native-connectors/blob/-/youbora/LICENSE) file for more information.

## 1.5.0

### ✨ Features

* Updated Android's target SDK version to 36.

## 1.4.1

### 🐛 Issues

* Fixed an issue where the native connector would not be properly destroyed in case the player's native handle would become unavailable.

## 1.4.0

### ✨ Features

* Added support for THEOplayer v10 and React Native THEOplayer v10.

## 1.3.0

### ✨ Features

* Added support for THEOplayer 9.0.

## 1.2.4

### 🐛 Issues

* Fixed an issue on iOS where the podspec files did not contain all references when not using the New Architecture.

## 1.2.3

### 🐛 Issues

* Fixed an issue on iOS where the project would not build when used in a project that has New Architecture enabled.

## 1.2.2

### 🐛 Issues

* Added sdkVersions API to Nielsen, Mux, Conviva, Comscore, Adobe and Engage connectors
* Added THEOplayer 8.x to peerDependency setup

## 1.2.1

### 🐛 Issues

* Deleted dependency on the removed ad module for Android.

## 1.2.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v7.0.0 and native player SDK v7.0.0.

### ✨ Features

* Simplified pre-install step in podFile to setup THEOplayer dependency for iOS/tvOS.
* Updated setup documentation.

## 1.1.1

### 📦 Dependency Updates

* Relax restriction on `react-native-theoplayer` peer dependency versions.

## 1.1.0

### 📦 Dependency Updates

* Added support for `react-native-theoplayer` v3.0 and THEOplayer 6.0.

## 1.0.0

### ✨ Features

* Initial release

---

# THEOplayer Flutter SDK

Dolby OptiView Player (formerly THEOplayer) is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀 Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/flutter/getting-started.md)

[Set up your first OptiView Player in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/flutter/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/flutter/guides/abr.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/flutter/guides/abr.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/flutter/changelog.md)

[Find out what's new in the OptiView Player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/flutter/changelog.md)

## [![](/pr-932/img/github.svg)![](/pr-932/img/github_dark.svg)GitHub](https://github.com/THEOplayer/flutter-theoplayer-sdk)

[Browse the source code or report issues on GitHub.](https://github.com/THEOplayer/flutter-theoplayer-sdk)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

![](https://raw.githubusercontent.com/THEOplayer/flutter-theoplayer-sdk/main/doc/theoplayer_flutter_sdk_logo.png)

# THEOplayer Flutter SDK

## Table of Contents

1. [Overview](#overview)
2. [Prerequisites](#prerequisites)
3. [How to use these guides](#how-to-use-these-guides)
4. [Features](#features)
5. [Getting Started](#getting-started)
6. [Contributing](#contributing)

## Overview

The `theoplayer` package provides a `THEOplayer` component supporting video playback on the following platforms:

* Android, Android TV & FireTV
* iOS
* HTML5 (web, mobile web)
* **OUT OF SCOPE**: Tizen and WebOS (smart TVs, set-top boxes and gaming consoles).

This document covers the creation of a minimal app including a `THEOplayer` component, and an overview of the accompanying example app.

It also gives a description of the properties of the `THEOplayer` component, and a list of features and known limitations.

## Prerequisites

For each platform, a dependency to the corresponding THEOplayer SDK is included through a dependency manager:

* Gradle & Maven for Android
* Cocoapods for iOS
* npm for Web \*

\**the initial version of the SDK relies on a local copy of `THEOplayer.chromeless.js` (and additional modules), so adding it manually is required!*

In order to use one of these THEOplayer SDKs, it is necessary to obtain a valid THEOplayer license for that specific platform, i.e. HTML5, Android, and/or iOS. You can sign up for a THEOplayer SDK license through [our portal](https://portal.theoplayer.com/).

If you have no previous experience in Flutter, we encourage you to first explore the [Flutter Documentation](https://docs.flutter.dev/), as it gives you a good start on one of the most popular app development frameworks.

## How to use these guides

These are guides on how to use the THEOplayer Flutter SDK in your Flutter project(s) and can be used linearly or by searching the specific section. It is recommended that you have a basic understanding of how Flutter works to speed up the way of working with THEOplayer Flutter SDK.

## Features

Depending on the platform on which the application is deployed, a different set of features can be available.

If a feature is missing, additional help is needed, or you need to extend the package, please reach out to us for support.

| Feature                                                                                                            | Android, Android TV, Fire TV                                                                                                                                                                                          | Web                                             | iOS, tvOS                                                     |
| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------- |
| **Streaming**                                                                                                      | MPEG-DASH (fmp4, CMAF), HLS (TS, CMAF), Progressive MP4, MP3                                                                                                                                                          |                                                 | HLS (TS, CMAF), Progressive MP4, MP3                          |
| **Content Protection**                                                                                             | Widevine                                                                                                                                                                                                              | Widevine, Fairplay                              | Fairplay                                                      |
| **DRM Connectors**                                                                                                 | Through hooking into native implementation… check guides!                                                                                                                                                             |                                                 |                                                               |
| **Subtitles & Closed Captions**                                                                                    | In-stream subtitles supported by the platform.<br />Note: If you use Texture-based rendering (SURFACE\_TEXTURE and SURFACE\_PRODUCER) on Android, you need to implement the subtitle rendering based on track events. |                                                 |                                                               |
| **Metadata**                                                                                                       | Event stream, emsg, ID3, EXT-X-DATERANGE                                                                                                                                                                              |                                                 |                                                               |
| **Fullscreen**                                                                                                     | Supported through `player.presentationMode` API                                                                                                                                                                       |                                                 |                                                               |
| **[Picture-in-Picture](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/picture-in-picture.md)** | Supported through `player.allowAutomaticPictureInPicture` API                                                                                                                                                         | Supported through `player.presentationMode` API | Supported through `player.allowAutomaticPictureInPicture` API |
| **Advertising Integration**                                                                                        | Coming soon… (Can not wait? [Check our in-app integration branches](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/custom-branches.md))                                                           |                                                 |                                                               |
| **Analytics Connectors**                                                                                           | Coming soon…                                                                                                                                                                                                          |                                                 |                                                               |
| **Cast Integration**                                                                                               | Coming soon… (Can not wait? [Check our in-app integration branches](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/custom-branches.md))                                                           |                                                 |                                                               |
| **[THEOlive](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/theolive.md)**                     | Supported through `THEOliveSource` and `player.theolive` API                                                                                                                                                          |                                                 |                                                               |
| **[Adaptive Bitrate (ABR)](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/abr.md)**            | Supported through `player.abr` API                                                                                                                                                                                    |                                                 |                                                               |

## Getting Started

This section starts with creating a minimal demo app that integrates the `theoplayer` package, followed by an overview of the available properties and functionality of the THEOplayer component. A minimal example application including a basic user interface and demo sources is included in [this repository](https://github.com/THEOplayer/flutter-theoplayer-sdk/tree/main/flutter_theoplayer_sdk/flutter_theoplayer_sdk/example), and discussed in the next section. Finally, an overview of features, limitations and known issues is listed.

* [Creating a minimal demo app](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/creating-minimal-app.md)

  * [Getting started on Android](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/creating-minimal-app.md#getting-started-on-android)
  * [Getting started on iOS](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/creating-minimal-app.md#getting-started-on-ios)
  * [Getting started on Web](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/creating-minimal-app.md#getting-started-on-web)

* [The THEOplayer component](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/theoplayer-component.md)

* Knowledge Base

  * [Using custom DRM connectors](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/custom_drm.md)
  * [Limitations and known issues](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/limitations.md)
  * [Picture-in-picture](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/picture-in-picture.md)
  * [Adaptive Bitrate (ABR)](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/abr.md)
  * [Debug Flags](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/debug-flags.md)
  * [Custom branches](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/custom-branches.md): custom forks to expose native functionality

## Contributing

All contributions are welcomed!

Please read our [Contribution guide](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/CONTRIBUTING.md) on how to get started!

---

# Changelog

## 10.12.2

* Fixed an issue when playing OptiView Live streams (THEOlive) the player did not jump to the live point after a fallback.

## 10.12.1

* Updated THEOplayer to 10.12.1.
  * For underlying native SDK changes please consult with the [THEOplayer SDK 10.12.1 changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-10121-20260317)).

## 10.12.0

* Updated THEOplayer to 10.12.0.
* Added `AbrStrategyConfiguration` API to configure initial ABR selection on `player.abr`.
* Added `DebugFlags` API to help debugging underlying native SDK issues via `player.debugFlags` and `player.showDebugPanel(context)`

## 10.6.1

* Updated THEOplayer to 10.6.1.
  * iOS: minimum required XCode version is 16.2 [from THEOplayer iOS SDK 10.x](https://optiview.dolby.com/docs/theoplayer/changelog/#-breaking-changes-3)
* Android: Fixed an issue where calling `player.dispose()` did not destroy the native player completely.

## 10.3.0

* Updated THEOplayer to 10.3.0.

## 10.0.0

* Updated THEOplayer to 10.0.0.

  * For underlying native SDK changes please consult with the [THEOplayer SDK 10.0.0 changelog](https://optiview.dolby.com/docs/theoplayer/changelog/#-1000-20250912)).
  * Android: Updated Kotlin version to 2.2.10 (to match with THEOplayer Android SDK).
  * Android: Updated Gradle version to 8.13.0.
  * Android: Update minSdkVersion to 23.
  * Android: Update compileSdkVersion to 36.

* Added **experimental** WASM compilation support for web builds.

* **BREAKING CHANGE**: Renamed all "publication"-related APIs to "distribution" for consistency with THEOplayer native SDKs:

  * **State Management**: `PublicationState` → `DistributionState`, `publicationState` → `distributionState`
  * **Event Types**: `PUBLICATIONLOADSTART` → `DISTRIBUTIONLOADSTART`, `PUBLICATIONLOADED` → `ENDPOINTLOADED`, `PUBLICATIONOFFLINE` → `DISTRIBUTIONOFFLINE`
  * **Event Classes**: `PublicationLoadStartEvent` → `DistributionLoadStartEvent`, `PublicationLoadedEvent` → removed (replaced by `EndpointLoadedEvent`), `PublicationOfflineEvent` → `DistributionOfflineEvent`
  * **Event Parameters**: `event.publicationId` → `event.distributionId` in distribution events

* **BREAKING CHANGE**: Removed Android PlaybackPipeline configuration support:

  * **Removed**: `PlaybackPipeline` enum (`media3`, `legacy` options)
  * **Removed**: `AndroidTypedSourceConfiguration.playbackPipeline` parameter
  * **Default**: Media3 is now the only supported playback pipeline (legacy pipeline removed)

### Migration Notes

This release contains significant breaking changes that require code updates:

1. **THEOlive API Renaming**: All publication-related APIs have been renamed to distribution equivalents
2. **Android Configuration Simplification**: PlaybackPipeline configuration is no longer needed (Media3 is default)
3. **Event Parameter Changes**: Event handlers need to use `distributionId` instead of `publicationId`
4. **Class Name Updates**: Some event classes have been renamed for consistency

**Migration Required**: Existing code using THEOlive APIs will need updates to compile and function correctly.

For detailed migration instructions, automated find/replace patterns, and complete examples, see the [Migration Guide](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/migrations/migration_from_9.x_to_10.x.md).

## 9.11.0

* Updated THEOplayer to 9.11.0.

## 9.7.1

* Added `TypedSource.type` property.
* Added `WebConfig.libraryLocation` to specify a different path for THEOplayer WEB SDK through `THEOplayerConfig`.

## 9.7.0

* Updated THEOplayer to 9.7.0.
* Added `TheoLiveConfiguration.discoveryUrl` to support custom discovery URLs for OptiView live streams (formerly known as THEOlive).

## 9.3.1

* Updated THEOplayer to 9.3.1.

## 9.3.0

* Updated THEOplayer to 9.3.0.
  * Fixed an issue where `THEOplayer.allowAutomaticPictureInPicture` was not respected after setting a source.

## 9.2.0

* Updated THEOplayer to 9.2.0.
* Added `TypedSource.headers` to set custom headers for requests (Applied on master playlist, media playlist and segment requests).
  * Supported only on Android (PlaybackPipeline.MEDIA3) and iOS.
* Fixed an issue where calling `player.dispose()` would not release resources properly on iOS.

## 9.0.0

* Updated THEOplayer to 9.0.0.

* Added `TypedSource.androidSourceConfiguration` to change playback pipelines on Android (legacy/media3)

* **BREAKING CHANGE**: Changed default media playback pipeline on Android

  * Starting from THEOplayer 9.0, the new Media3 Playback pipeline is now the default for all [Android SDK playback](https://www.theoplayer.com/docs/theoplayer/changelog/#-900-20250403).
  * The legacy playback pipeline from version 8.x is still available, and can be activated by setting `TypedSource.androidSourceConfiguration.playbackPipeline` to `PlaybackPipeline.LEGACY`.
  * The legacy playback pipeline is scheduled to be removed in version 10.

* Known issues:

  * Combining `AndroidViewComposition.SURFACE_PRODUCER` or `AndroidViewComposition.SURFACE_TEXTURE` with the new default pipeline doesn't play DRM (content protected) sources.
  * As a workaround please use `PlaybackPipeline.LEGACY` with these rendering engines, or `AndroidViewComposition.HYBRID_COMPOSITION` with `PlaybackPipeline.MEDIA3`.

## 8.14.0

* Updated THEOplayer to 8.14.0.

## 8.13.2

* Updated THEOplayer to 8.13.2.
* Added [THEOlive support](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/theolive.md) for Android and iOS.
* Added `THEOplayer.isWaiting` state.
* Added experimental `THEOplayer.addAllEventListener(...)` to listen on all player events at once.

## 8.11.0

* Updated THEOplayer to 8.11.0.
* Added support for Flutter 3.29.0.

## 8.4.0

* Updated THEOplayer to 8.4.0.

## 8.3.0

* Updated THEOplayer to 8.3.0.
* Added [THEOlive support](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/theolive.md) for Flutter WEB.
* Deprecated getX and setX methods on THEOplayer API in favor of properties.
* Added new properties on THEOplayer API. (`muted`, `played`, `buffered`, `videoTracks`, etc... for the full list check the API.)
* **BREAKING CHANGE**: Changed `THEOplayer.allowBackgroundPlayback()` to `THEOplayer.allowBackgroundPlayback`.
* **BREAKING CHANGE**: Changed `THEOplayer.allowAutomaticPictureInPicture()` to `THEOplayer.allowAutomaticPictureInPicture`.
* **BREAKING CHANGE**: Changed `THEOplayer.isEnded()` to `THEOplayer.isEnded`.
* **BREAKING CHANGE**: Changed `THEOplayer.isPlaying()` to `THEOplayer.isPlaying`.
* **BREAKING CHANGE**: Changed `THEOplayer.isSeeking()` to `THEOplayer.isSeeking`.

## 8.2.0

* Fixed an issue where play/pause buttons were not connected in the Picture-in-Picture window on Android.
* Updated THEOplayer to 8.2.0.
* Updated Kotlin version to 1.9.25 (to match with THEOplayer Android SDK)

## 8.0.0

* Updated THEOplayer to 8.0.0.
* Added Picture-in-Picture support with `THEOplayer.setPresentationMode(PresentationMode.PIP)` API for WEB and `THEOplayer.setAllowAutomaticPictureInPicture(bool)` for Android and iOS.
* Removed iOS 12 support. The minimum supported iOS version is now iOS 13.

## 7.12.0

* Updated THEOplayer to 7.12.0.

## 7.3.1

* Fixed an issue where playback failed with license error when using Texture-based (SURFACE\_TEXTURE, SURFACE\_PRODUCER) rendering.
* Fixed an issue where player lifecycle callbacks were triggered multiple times when using Texture-based (SURFACE\_TEXTURE, SURFACE\_PRODUCER) rendering.

## 7.3.0

* Updated THEOplayer to 7.3.0.

* Added `AndroidConfig.viewComposition` to support Texture-based rendering.

* Added `AndroidViewComposition.SURFACE_TEXTURE` to use SurfaceTexture on native Android (instead of PlatformViews).

* Added `AndroidViewComposition.SURFACE_PRODUCER` to use SurfaceProducer on native Android (instead of PlatformViews).

  * Only works from [Flutter 3.22.0](https://docs.flutter.dev/release/breaking-changes/android-surface-plugins#timeline)
  * Supports [Texture-based rendering with Impeller](https://docs.flutter.dev/release/breaking-changes/android-surface-plugins#summary) rendering engine

* Added Support for continuing playback when transitioning the app into background with `THEOplayer.setAllowBackgroundPlayback(boolean)`.

* Added Fullscreen support with `THEOplayer.setPresentationMode(PresentationMode)`.

* Deprecated `AndroidConfig.useHybridComposition` in favor of `AndroidConfig.viewComposition` (use `AndroidViewComposition.HYBRID_COMPOSITION` for the previous behaviour).

## 7.0.0

* Updated THEOplayer to 7.0.0.

### Versioning changes

We are updating the version numbering for THEOplayer Flutter SDK to more closely match the underlying native THEOplayer SDKs.

Here are the notable changes:

* The **major** version will be matching the underlying native SDK major version.
* The **minor** version will reflect new features added in THEOplayer Flutter SDK.
* The **patch** version will be increased when there is a need for a hotfix on top of the minor version bump.

> Note: Breaking changes in THEOplayer Flutter SDK will only occur while increasing the **major** version.

## 1.0.3

* Updated THEOplayer to 6.10.1.
* Added and coupled application lifecycle listener.

## 1.0.2

* Service release, no new features.

## 1.0.1

* Updated minimum Dart version to 3.3.0.
* Updated minimum Flutter version to 3.19.0.

## 1.0.0

* Initial release.

---

# Adaptive Bitrate (ABR)

## Overview

The playback quality during play-out of a THEOlive stream is determined by the ABR algorithm. On starting play-out, the ABR **strategy** determines which quality to prefer, while during play-out the network's bandwidth is monitored to select an optimal quality.

More information on ABR can be found on the [THEOplayer website](https://www.theoplayer.com/blog/abr-bandwidth-usage) and [demo page](https://www.theoplayer.com/theoplayer-demo-optimized-video-abr).

## ABR Configuration

The ABR configuration is accessible through `player.abr`. It allows you to control the ABR strategy, target buffer, and preferred peak bitrate.

### Setting the ABR Strategy

The strategy determines which quality the player initially selects when starting playback:

| Strategy      | Description                                                                 |
| ------------- | --------------------------------------------------------------------------- |
| `performance` | Prefer the **lowest** quality for faster startup and lower bandwidth usage. |
| `quality`     | Prefer the **highest** quality for the best visual experience.              |
| `bandwidth`   | Estimate available bandwidth and select the best matching quality.          |

The default strategy is **bandwidth**.

```dart
// Set the ABR strategy to "quality" (prefer highest quality)
player.abr.setStrategy(
  AbrStrategyConfiguration(type: AbrStrategyType.quality),
);

// Set the ABR strategy to "performance" (prefer lowest quality)
player.abr.setStrategy(
  AbrStrategyConfiguration(type: AbrStrategyType.performance),
);

// Read the current strategy
final config = await player.abr.strategy;
print("Current ABR strategy: ${config.type}");
```

### Setting an Initial Bitrate Cap

You can pass optional `metadata` with a `bitrate` value (in bits per second) to cap the initial quality selection:

```dart
player.abr.setStrategy(
  AbrStrategyConfiguration(
    type: AbrStrategyType.bandwidth,
    metadata: AbrStrategyMetadata(bitrate: 1200000), // 1.2 Mbps
  ),
);
```

This is useful when you have an estimate of the user's available bandwidth and want to avoid buffering on startup.

### Target Buffer

The target buffer controls how many seconds of video the player should buffer ahead of the current playback position. This only applies to HLS (non-THEOlive) streams.

```dart
// Get the current target buffer (default: 20 seconds)
final buffer = await player.abr.targetBuffer;

// Set the target buffer to 10 seconds
player.abr.setTargetBuffer(10.0);
```

### Preferred Peak Bitrate (iOS only)

On iOS you can set the desired limit for network bandwidth consumption. This only applies to HLS (non-THEOlive) streams and is a no-op on other platforms.

```dart
// Cap bandwidth to 2 Mbps
player.abr.setPreferredPeakBitRate(2000000);

// Remove the cap (default: 0 = no limit)
player.abr.setPreferredPeakBitRate(0);
```

## Setting Target Video Quality

By default, the ABR algorithm will choose from all the video qualities available in the stream. You can pin the player to a specific quality or a subset of qualities using the `targetQuality` / `targetQualities` properties on a video track:

```dart
final videoTrack = player.videoTracks.first;

// Pin to a single quality (disables ABR)
videoTrack.targetQuality = videoTrack.qualities.first;

// Pin to a subset of qualities (ABR selects among these)
videoTrack.targetQualities = [
  videoTrack.qualities[0],
  videoTrack.qualities[1],
];

// Reset to automatic (let ABR choose freely)
videoTrack.targetQuality = null;
```

## Subscribing to Quality Change Events

You can listen for quality changes on video and audio tracks:

```dart
// Listen for new video tracks
player.videoTracks.addEventListener(VideoTracksEventTypes.ADDTRACK, (event) {
  final track = (event as AddVideoTrackEvent).track;
  print("Video track added: ${track.uid}");

  // Print all available qualities
  for (final quality in track.qualities) {
    print("  quality: ${quality.width}x${quality.height}, "
        "bandwidth: ${quality.bandwidth}");
  }

  // Listen for active quality changes on this track
  track.addEventListener(
    VideoTrackEventTypes.ACTIVEQUALITYCHANGED,
    (event) {
      final q = (event as VideoActiveQualityChangedEvent).quality;
      print("Active quality changed: ${q.width}x${q.height}, "
          "bandwidth: ${q.bandwidth}");
    },
  );
});
```

## Supported Platforms

| Property               | Android | iOS | Web |
| ---------------------- | ------- | --- | --- |
| `strategy`             | ✅      | ✅  | ✅  |
| `targetBuffer`         | ✅      | ✅  | ✅  |
| `preferredPeakBitRate` | ❌      | ✅  | ❌  |
| `targetQuality`        | ✅      | ✅  | ✅  |
| Quality change events  | ✅      | ✅  | ✅  |

**Notes**: On **iOS**, the ABR strategy configuration only affects **THEOlive** (HESP) streams. For other stream types, the player uses the platform-native ABR algorithm that cannot be configured through this API.

On **Android** and **Web**, the ABR strategy is applied to all adaptive streams.

---

# Creating a minimal demo app

In this section we start from an empty Flutter project, include a dependency to `flutter_theoplayer_sdk`, and deploy it on an Android or iOS device.

## Table of Contents

* [Setting up a new project](#setting-up-a-new-project)
* [Getting started on Android](#getting-started-on-android)
* [Getting started on iOS](#getting-started-on-ios)
* [Getting started on Web](#getting-started-on-web)

## Setting up a new project

### Getting a new project ready

After [setting up your Flutter development environment](https://docs.flutter.dev/get-started/install) you can run the following command to create a new project from Terminal. (You can use Android Studio too)

```bash
$ flutter create -a kotlin -i swift -t app --org com.theoplayer --description "New THEOplayer project" --project-name "flutter_theoplayer_sample_app" --platform web,ios,android flutter_theoplayer_sample_app
```

This will generate a basic project as a starting point for Android, iOS and Web development.

```text
Signing iOS app for device deployment using developer identity: "Apple Development: XXXXXXXXXXX"
Creating project flutter_theoplayer_sample_app...
Resolving dependencies in flutter_theoplayer_sample_app... 
Got dependencies in flutter_theoplayer_sample_app.
Wrote 81 files.

All done!
You can find general documentation for Flutter at: https://docs.flutter.dev/
Detailed API documentation is available at: https://api.flutter.dev/
If you prefer video documentation, consider: https://www.youtube.com/c/flutterdev

In order to run your application, type:

  $ cd flutter_theoplayer_sample_app
  $ flutter run

Your application code is in flutter_theoplayer_sample_app/lib/main.dart.
```

Following the guidance from the script you can have your basic app running:

```bash
$ cd flutter_theoplayer_sample_app
$ flutter run
```

### Adding THEOplayer Flutter SDK

#### Option 1: Adding THEOplayer Flutter SDK as dependency (Recommended)

To add THEOplayer Flutter SDK as a dependency, you can simply fetch it from [pub.dev](https://pub.dev) using:

```bash
$ flutter pub add theoplayer
```

##### Option 1/b (optional) Referencing a custom branch from the official THEOplayer Flutter SDK repository

In certain scenarios (e.g. you would like to test an un-released feature), you can reference any commit/branch/tag from the [THEOplayer Flutter SDK repository](https://github.com/THEOplayer/flutter-theoplayer-sdk).

In your `package.yaml` file you need to change the way you reference the `theoplayer` package with Dart's `dependency_override` feature:

From:

```yaml
dependencies:
  flutter:
    sdk: flutter

  theoplayer: ^8.11.0
```

To:

```yaml
dependencies:
  flutter:
    sdk: flutter

  theoplayer: ^8.11.0

dependency_overrides:
  theoplayer:
    git:
      url: https://github.com/THEOplayer/flutter-theoplayer-sdk.git
      ref: feature/NEW_UNRELEASED_FEATURE
      path: flutter_theoplayer_sdk/flutter_theoplayer_sdk

  theoplayer_ios:
    git:
      url: https://github.com/THEOplayer/flutter-theoplayer-sdk.git
      ref: feature/NEW_UNRELEASED_FEATURE
      path: flutter_theoplayer_sdk/flutter_theoplayer_sdk_ios

  theoplayer_android:
    git:
      url: https://github.com/THEOplayer/flutter-theoplayer-sdk.git
      ref: feature/NEW_UNRELEASED_FEATURE
      path: flutter_theoplayer_sdk/flutter_theoplayer_sdk_android

  theoplayer_platform_interface:
    git:
      url: https://github.com/THEOplayer/flutter-theoplayer-sdk.git
      ref: feature/NEW_UNRELEASED_FEATURE
      path: flutter_theoplayer_sdk/flutter_theoplayer_sdk_platform_interface
```

As you can see, removing `theoplayer: ^8.11.0` is not necessary as `dependency_override` takes precedence over standard `dependencies`.

You can even move this new piece into a separate `dependency_overrides.yaml` file too, if you wish. (and you can use it during development and not commit the file into the repository)

Dependency override makes sure that `theoplayer` and its dependencies `theoplayer_ios`, `theoplayer_android`, and `theoplayer_platform_interface` are pulled from the correct branch.

After running `pub get` you will see that the overrides are in place:

```bash
...
! theoplayer 8.11.0 from git https://github.com/THEOplayer/flutter-theoplayer-sdk.git at d292cf in flutter_theoplayer_sdk/flutter_theoplayer_sdk (overridden)
! theoplayer_android 8.11.0 from git https://github.com/THEOplayer/flutter-theoplayer-sdk.git at d292cf in flutter_theoplayer_sdk/flutter_theoplayer_sdk_android (overridden)
! theoplayer_ios 8.11.0 from git https://github.com/THEOplayer/flutter-theoplayer-sdk.git at d292cf in flutter_theoplayer_sdk/flutter_theoplayer_sdk_ios (overridden)
! theoplayer_platform_interface 8.11.0 from git https://github.com/THEOplayer/flutter-theoplayer-sdk.git at d292cf in flutter_theoplayer_sdk/flutter_theoplayer_sdk_platform_interface (overridden)
  vm_service 14.3.0 (15.0.0 available)
  web 1.1.0 (1.1.1 available)
...
```

#### Option 2: Adding THEOplayer Flutter SDK as submodule

As an alternative, you can add the SDK as a submodule in your git project. This can be useful if you are trying to fork the project to [contribute](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/CONTRIBUTING.md) with us.

```bash
$ git submodule add https://GITHUB_USERNAME:GITHUB_PASSWORD@github.com/THEOplayer/flutter-theoplayer-sdk flutter-theoplayer-sdk
```

Then, your project structure will look like this:

```bash
➜  flutter_theoplayer_sample_app git:(master) ✗ ls
README.md                         flutter-theoplayer-sdk            pubspec.lock
analysis_options.yaml             flutter_theoplayer_sample_app.iml pubspec.yaml
android                           ios                               test
build                             lib                               web
```

After the submodule added, you can add the THEOplayer Flutter SDK as a dependency in your project's `pubspec.yaml` file manually, or just by running this command:

```bash
$ flutter pub add 'theoplayer:{"path":"./flutter-theoplayer-sdk/flutter_theoplayer_sdk/flutter_theoplayer_sdk"}' --directory .
```

You should get an output like this after executing the command, meaning `flutter` found and added the SDK as a dependency, and fetched the necessary packages too.

```diff
Resolving dependencies... 
  collection 1.17.2 (1.18.0 available)
  flutter_lints 2.0.3 (3.0.1 available)
+ theoplayer_sdk_android 1.0.0 from path ../flutter-theoplayer-sdk/flutter_theoplayer_sdk/flutter_theoplayer_sdk_android
+ theoplayer_sdk_ios 1.0.0 from path ../flutter-theoplayer-sdk/flutter_theoplayer_sdk/flutter_theoplayer_sdk_ios
+ theoplayer_sdk_platform_interface 1.0.0 from path ../flutter-theoplayer-sdk/flutter_theoplayer_sdk/flutter_theoplayer_sdk_platform_interface
+ theoplayer_sdk_web 1.0.0 from path ../flutter-theoplayer-sdk/flutter_theoplayer_sdk/flutter_theoplayer_sdk_web
+ flutter_web_plugins 0.0.0 from sdk flutter
+ js 0.6.7
  lints 2.1.1 (3.0.0 available)
  material_color_utilities 0.5.0 (0.8.0 available)
  meta 1.9.1 (1.11.0 available)
+ plugin_platform_interface 2.1.6
  stack_trace 1.11.0 (1.11.1 available)
  stream_channel 2.1.1 (2.1.2 available)
  test_api 0.6.0 (0.6.1 available)
+ theoplayer 1.0.0 from path ../flutter-theoplayer-sdk/flutter_theoplayer_sdk/flutter_theoplayer_sdk
  web 0.1.4-beta (0.4.0 available)
Changed 8 dependencies!
```

To make sure the submodule references the platform-specific SDKs from within the repository run `melos bootstrap`.

If your main project doesn't pick up the changes, it is possible you need to configure `melos` to include your project too.

You can do it in 2 ways.

1. Create your `melos.yaml` file in your root project and configure it according to your setup (including the `theopalyer` submodule and its packages).
2. Or, modifiy the `flutter-theoplayer-sdk/melos.yaml` to include your project by adding `../` into the `packages` section of the melos file.

Don't forget to run `melos bootstrap` again in the directory according to your choice from above.

### Adding THEOplayer to your view hierarchy

1. Initialize THEOplayer (e.g. in your StatefulWidget)

```dart
  late THEOplayer player;

  @override
  void initState() {
    super.initState();

    player = THEOplayer(
        theoPlayerConfig: THEOplayerConfig(
          license: "YOUR_LICENSE_STRING",
        ),
        onCreate: () {
          print("THEOplayer is created and ready to use");
        });
  }
```

Keep in mind, you need to have a valid license from [THEOportal](https://portal.theoplayer.com).

Without a license you can only play sources hosted on `theoplayer.com` domain. (If you want to try this, just delete the `license` String from the `THEOplayerConfig`)

2. Adding THEOplayer to the view hierarchy

```dart
SizedBox(
    height: 300,
    // player.getView() is now deprecated. Use 'view' like below
    child: player.view,
),
```

3. Setting a source and start playback on a button press:

```dart
FilledButton(
    onPressed: () {
      // player.setSource() is now deprecated. Use 'source' like below
        player.source = SourceDescription(sources: [
            TypedSource(src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"),
        ]);
        player.play();
    },
    child: const Text("Play BBB source"),
),
```

***

You are (almost) ready to play with THEOplayer 😉

Is there anything else to configure on the specific platforms?

Check it below ⬇️

## Getting started on Android

The generated sample project doesn't have Internet permission by default (only in debug/profile mode).

By declaring the `INTERNET` the `AndroidManifest.xml`, your app can reach the Internet.

```xml
<uses-permission android:name="android.permission.INTERNET"/>
```

As noted in the [limitations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/flutter/guides/limitations.md), THEOplayer on Android supports Android 5 (API level 21) and above, so defining this in the `android/app/build.gradle` is necessary:

```java
defaultConfig {
    // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html).
    applicationId "com.theoplayer.theoplayer_example"
    // You can update the following values to match your application needs.
    // For more information, see: https://docs.flutter.dev/deployment/android#reviewing-the-gradle-build-configuration.
    minSdkVersion 21
    targetSdkVersion flutter.targetSdkVersion
    versionCode flutterVersionCode.toInteger()
    versionName flutterVersionName
}
```

By using the `flutter run android` command, you can try out your application on an Android device.

## Getting started on iOS

No changes are required.

By using the `flutter run ios` command, you can try out your applicaiton on an iOS device.

## Getting started on Web

You need to acquire THEOplayer HTML5 SDK from [THEOportal](https://portal.theoplayer.com/) (or from an NPM package, e.g. from [6.9.0](https://registry.npmjs.org/theoplayer/-/theoplayer-6.9.0.tgz)).

**The current iteration of the THEOplayer Flutter SDK is not able to automatically pull THEOplayer HTML5 SDK from NPM, so this is now a manual procedure.**

If you have all the files at your hand (`THEOplayer.chromeless.js`, `common` and `transmux` files) copy them into the root of your Web project. (Next to the `index.html`, which is the entry point of your Flutter Web application)

Load the `THEOplayer.chromeless.js` Javascript in the `<HEAD>` of your `index.html` page:

```html
<!-- This script adds the flutter initialization JS code, don't change it -->
<script src="flutter.js" defer></script>

<!-- Loading THEOplayer -->
<script src="THEOplayer.chromeless.js" type="application/javascript"></script>
```

After these steps, you are good to go.

By using the `flutter run chrome` command, you can try out your application in the Chrome browser.

### Custom path for THEOplayer WEB SDK

You can also place the THEOplayer WEB SDK files on a custom path. (not in the root).

For that you will need some extra steps:

1. Place the files in the desired directory within your Flutter Web project. (e.g. `web/theoplayer_lib/`)
2. Reference THEOplayer in the `index.html` from that path:

```html
<!-- Loading THEOplayer -->
<script src="theoplayer_lib/THEOplayer.chromeless.js" type="application/javascript"></script>
```

3. Setup THEOplayer in Flutter with the custom library location through `THEOplayerConfig.webConfiguration`:

```dart
    player = THEOplayer(
      theoPlayerConfig: THEOplayerConfig(
        license: PLAYER_LICENSE,
        webConfiguration: WebConfig(libraryLocation: "/theoplayer_lib")
      ),
      onCreate: () {
        print("THEOplayer - loaded");
      }
    );
```

---

# Custom branches

THEOplayer Flutter SDK is built on top of the existing THEOplayer iOS, Android, and Web SDKs. However, not all native SDK features are available in Flutter from the start.

These features will be gradually introduced to the Flutter SDK based on thoughtful prioritization.

We understand that sometimes you may need these features before they are fully implemented on the Flutter side and require a working solution as soon as possible.

To address this need, we introduced custom branches prefixed with `poc/`, showcasing sample implementations of existing native features in a custom Flutter SDK fork. These versions are stable enough to start experimenting with and making necessary modifications if needed.

(Please note that these branches may not always be up-to-date with the latest releases.)

These versions also serve as a starting point for custom integration needs. By examining the source code and reviewing changes commit by commit, you can gain a basic understanding of how to expose additional native THEOplayer APIs to Flutter, especially if you are already familiar with the underlying SDKs.

## Available custom branches

| Branch                              | Description                                              |
| ----------------------------------- | -------------------------------------------------------- |
| `poc/in-sdk-chromecast-support-7.x` | Exposing Chromecast capabilities on Android, iOS and Web |
| `poc/in-sdk-google-ima-support-7.x` | Exposing Google IMA capabilities on Android and iOS      |

## How to make and use your own custom fork?

1. Create a fork of the THEOplayer Flutter SDK repo on [GitHub](https://github.com/THEOplayer/flutter-theoplayer-sdk/).
2. Configure your project to use your forked custom [THEOplayer SDK as a submodule](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/main/doc/creating-minimal-app.md#option-2-adding-theoplayer-flutter-sdk-as-submodule) in your project.
3. Import THEOplayer and start using it in your application.

---

# Using a custom DRM integration

The initial version of the THEOplayer Flutter SDK only support generic Widevine and Fairplay DRM playback.

In a later release the Flutter SDK will also add functionality to utilize the well-known [THEOplayer Custom DRM Integration](https://github.com/THEOplayer/samples-drm-integration/tree/master) on the Flutter/Dart level.

The good news is that **the underlying platforms already support this functionality, so if you need to play a custom DRM stream, you can leverage this knowledge, and you can implement a *(temporary)* hybrid solution**.

## Configuration in Flutter

The current Flutter API is already taking into account the future custom extension of the DRM configurations. It already contains a `customIntegrationID` and an `integrationParameters` property to pass custom data:

```dart
SourceDescription(sources: [
    TypedSource(
        src: "https://fps.ezdrm.com/demo/video/ezdrm.m3u8",
        drm: DRMConfiguration(
            customIntegrationId: "YourCustomDRMIntegrationID",
            integrationParameters: {
                "custom_key": "custom_value",
            },
            fairplay: FairPlayDRMConfiguration(
                licenseAcquisitionURL: "https://yourlicenseurl.com",
                certificateURL: "https://yourcertificateurl.com",
                headers: null,
            ),
            widevine: WidevineDRMConfiguration(
                licenseAcquisitionURL: "https://yourlicenseurl.com",
            ),
        )),
    ])
)
```

By specifying these values the underlying platform knows it has to use a custom DRM logic. Somehow we just have to make sure that the custom DRM logic is available on the native side.

## Registering a custom DRM connector on Android

You can rely on any existing native Java/Kotlin implementation you have already, or take one from our [samples repository](https://github.com/THEOplayer/samples-drm-integration/tree/master).

After you copied over the code into your Android application project (`projectRoot/android/app/src/main`), you can hook it up when the application gets initialized.

For example, you can use the `MainActivity` class as a starting point (if you don't have any other platform-specific code).

```kotlin
import com.theoplayer.android.api.THEOplayerGlobal
import com.theoplayer.android.api.contentprotection.KeySystemId
import io.flutter.embedding.android.FlutterActivity

class MainActivity: FlutterActivity() {
    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        THEOplayerGlobal.getSharedInstance(context).registerContentProtectionIntegration(
            "YourCustomDRMIntegrationID",
            KeySystemId.WIDEVINE,
            YourCustomWidevineContentProtectionIntegrationFactory()
        )
    }
}
```

By using the exact same `customIntegrationId` on the native side, the underlying THEOplayer will know what to do when it sees a source with the same custom DRM ID.

## Registering a custom DRM connector on iOS

You can rely on any existing native Swift/ObjC implementation you have already, or take one from our [samples repository](https://github.com/THEOplayer/samples-drm-integration/tree/master).

After you copied over the code into your Android application project (`projectRoot/ios/Runner`), you can hook it up when the application gets initialized.

For example, you can use the `AppDelegate` class as a starting point (if you don't have any other platform-specific code).

```swift
import UIKit
import Flutter
import THEOplayerSDK

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    
    THEOplayer.registerContentProtectionIntegration(integrationId: "YourCustomDRMIntegrationID" , keySystem: .FAIRPLAY, integrationFactory: YourCustomFairplayContentProtectionIntegrationFactory())
      
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}
```

By using the exact same `customIntegrationId` on the native side, the underlying THEOplayer will know what to do when it sees a source with the same custom DRM ID.

## Registering a custom DRM connector on Web

You can rely on any existing native Javascript/Typescript implementation you have already, or take one from our [samples repository](https://github.com/THEOplayer/samples-drm-integration/tree/master).

After you copied over the code into your Android application project (`projectRoot/web/`), you can hook it up when the application gets initialized.

For example, you can use the `index.html` class as a starting point (if you don't have any other platform-specific code).

```html
<head>
  <!-- ... -->
  <script src="THEOplayer.chromeless.js" type="application/javascript"></script>
  <!-- after THEOplayer is loaded, you can load your custom DRM code/file -->
  <script src="customdrm.js" type="application/javascript"></script>
  <!-- and connect it with THEOplayer -->
  <script type="application/javascript">
    THEOplayer.registerContentProtectionIntegration(
        'YourCustomDRMIntegrationID',
        'widevine',
        new ContentProtectionIntegrations.YourCustomContentProtectionIntegrationFactory()
    );
  </script>

</head>
```

By using the exact same `customIntegrationId` on the native side, the underlying THEOplayer will know what to do when it sees a source with the same custom DRM ID.

---

# Debug Flags (Experimental)

## Overview

**Note**: This is an experimental API. It may change in future releases.

THEOplayer exposes internal debug flags that control verbose logging for various subsystems of the player. These flags can be toggled at runtime through the `player.debugFlags` API, making it easy to enable detailed logging for specific areas without recompiling.

A built-in UI panel is also provided so you can toggle flags interactively during development.

## Programmatic API

The debug flags API is available through `player.debugFlags`:

### Listing Available Flags

```dart
final flags = await player.debugFlags.getAvailableFlags();
for (final flag in flags) {
  print("${flag.key}: enabled=${flag.isEnabled} (default=${flag.defaultValue})");
  print("  ${flag.description}");
}
```

Each `DebugFlag` contains:

| Property       | Type   | Description                                 |
| -------------- | ------ | ------------------------------------------- |
| `key`          | String | Unique identifier for the flag.             |
| `description`  | String | Human-readable description of what it logs. |
| `defaultValue` | bool   | Compile-time default (usually `false`).     |
| `isEnabled`    | bool   | Current runtime state.                      |

### Toggling Individual Flags

```dart
// Enable a specific flag
await player.debugFlags.enableFlag("some_flag_key");

// Disable it
await player.debugFlags.disableFlag("some_flag_key");
```

### Bulk Operations

```dart
// Enable all flags
await player.debugFlags.enableAll();

// Disable all flags
await player.debugFlags.disableAll();

// Reset all flags to their compile-time defaults
await player.debugFlags.resetAll();
```

### File Logging (iOS only)

On iOS, you can enable file logging which writes debug output to a log file in addition to the console. This is a no-op on Android.

```dart
await player.debugFlags.enableFileLogging();
```

## Built-in Debug Panel

The SDK includes a ready-to-use `DebugFlagsPanel` widget that provides a full UI for managing debug flags, including search, individual toggles, and bulk actions.

### Showing the Panel

The simplest way is to use the convenience method on the player:

```dart
// Push the debug panel as a full-screen route
player.showDebugPanel(context);
```

Alternatively, you can use the panel widget or its static helper directly:

```dart
// Using the static helper
DebugFlagsPanelNavigation.show(context, player.debugFlags);

// Or embed it in your own layout
DebugFlagsPanel(api: player.debugFlags);
```

### Panel Features

* **Search** — filter flags by key or description
* **Toggle switches** — enable/disable individual flags
* **Status bar** — shows how many flags are currently enabled
* **Overflow menu** — Enable All, Disable All, Reset to Defaults, Enable File Logging (iOS)
* **Visual indicators** — overridden flags (different from default) are highlighted in bold

## Platform Differences

| Feature          | Android                             | iOS                                        |
| ---------------- | ----------------------------------- | ------------------------------------------ |
| Available flags  | Logger tags from the native SDK     | `DebugConfig.availableFlags` from THEOlive |
| Enable / Disable | `Logger.enableTags` / `disableTags` | `DebugConfig.enable` / `disable`           |
| Reset            | Disables all tags                   | Resets to compile-time defaults            |
| File logging     | No-op                               | Writes to OS log + file via `DebugConfig`  |

---

# Limitations and Known Issues

This sections lists any limitations and known issues in the current package version.

## Platform support

THEOplayer Flutter SDK is capable of running on

* iOS 13 and above
* Android 5 and above
* Mainstream web browsers (Firefox 120+, Chrome 119+, Safari 17+, Microsoft Edge 119+)

However, it is not optimized for those devices.

**For the best experience, we suggest to target**

* iOS 14 and above
* Android 10 and above

In a later phase, we will optimize the SDKs for lower operating system versions as much as possible.

### Smart TV support

THEOplayer Flutter SDK **officially doesn't support Smart TVs**. However, if your application is compiled for WEB, it should be able to run on modern Smart TVs (like Tizen 7+ and WebOS 23+) with smaller modifications on how the webapp loads the Flutter library.

Supporting Smart TVs is not a priority for the THEOplayer Flutter SDK (yet).

## Platform differences

The underlying native platform SDKs have different feature set. First check the Dart documentation if you see behaviour differences on certain platforms. We try to keep the documentation in sync as much as possible. If you see no difference mentioned in behaviour, please consult with the [native SDK documentations](https://www.theoplayer.com/docs/theoplayer/).

## Version limitations

THEOplayer Flutter SDK only compatible with THEOplayer 6.x and above.

## UI

Currently, THEOplayer Flutter SDK is completely chromeless, the UI needs to be implemented on top of the public APIs on the Flutter level.

The `example` project within the SDK package contains a sample UI.

## Missing features

THEOplayer Flutter SDK is not in feature parity yet with the native SDKs, new features will be added continuously.

For the current feature list, please visit the [README](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/flutter/getting-started.md) page.

---

# Migration Guide: From THEOplayer Flutter SDK 9.x to 10.x

This guide covers the breaking changes introduced when renaming "publication"-related APIs to "distribution" for consistency and clarity.

## Overview

The THEOplayer Flutter SDK has renamed all "publication"-related APIs to use "distribution" terminology instead. This change affects state management, event types, and property names.

## Breaking Changes

### 1. State Enum Renamed

**Before:**

```dart
enum PublicationState { idle, loading, loaded, intentToFallback, offline }
```

**After:**

```dart
enum DistributionState { idle, loading, loaded, intentToFallback, offline }
```

### 2. State Property Renamed

**Before:**

```dart
PublicationState state = player.theoLive?.publicationState;
```

**After:**

```dart
DistributionState state = player.theoLive?.distributionState;
```

### 3. Event Types Updated

**Before:**

```dart
player.theoLive?.addEventListener(THEOliveApiEventTypes.PUBLICATIONLOADSTART, (e) {
    print("Publication load started");
});

player.theoLive?.addEventListener(THEOliveApiEventTypes.PUBLICATIONLOADED, (e) {
    print("Publication loaded");
});

player.theoLive?.addEventListener(THEOliveApiEventTypes.PUBLICATIONOFFLINE, (e) {
    print("Publication offline");
});
```

**After:**

```dart
player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONLOADSTART, (e) {
    print("Distribution load started");
});

player.theoLive?.addEventListener(THEOliveApiEventTypes.ENDPOINTLOADED, (e) {
    print("Endpoint loaded");
});

player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONOFFLINE, (e) {
    print("Distribution offline");
});
```

### 4. Event Class Renamed

**Before:**

```dart
// In custom event handling code
if (event is PublicationLoadedEvent) {
    print("Publication loaded.");
}

if (event is PublicationLoadStartEvent) {
    print("Publication load started.");
}

if (event is PublicationOfflineEvent) {
    print("Publication offline.");
}
```

**After:**

```dart
// In custom event handling code
if (event is EndpointLoadedEvent) {
    print("Endpoint loaded.");
}

if (event is DistributionLoadStartEvent) {
    print("Distribution load started.");
}

if (event is DistributionOfflineEvent) {
    print("Distribution load started.");
}
```

### 5. Android Source Configuration Simplified

**Before:**

```dart
import 'package:theoplayer/theoplayer.dart';

// PlaybackPipeline enum and configuration
enum PlaybackPipeline { media3, legacy }

AndroidTypedSourceConfiguration config = AndroidTypedSourceConfiguration(
    playbackPipeline: PlaybackPipeline.media3
);

TypedSource source = TypedSource(
    src: "https://example.com/stream.m3u8",
    androidSourceConfiguration: config
);
```

**After:**

```dart
import 'package:theoplayer/theoplayer.dart';

// PlaybackPipeline enum removed - Media3 is now the default
AndroidTypedSourceConfiguration config = AndroidTypedSourceConfiguration();

TypedSource source = TypedSource(
    src: "https://example.com/stream.m3u8",
    androidSourceConfiguration: config
);
```

## Migration Steps

### Step 1: Update Import Statements

No changes needed - all imports remain the same.

### Step 2: Update State References

Replace all instances of:

* `PublicationState` → `DistributionState`
* `publicationState` → `distributionState`

**Example:**

```dart
// Before
void handleStateChange() {
  PublicationState currentState = player.theoLive?.publicationState;
  if (currentState == PublicationState.loaded) {
    // Handle loaded state
  }
}

// After
void handleStateChange() {
  DistributionState currentState = player.theoLive?.distributionState;
  if (currentState == DistributionState.loaded) {
    // Handle loaded state
  }
}
```

### Step 3: Update Event Listeners

Replace event type constants:

* `THEOliveApiEventTypes.PUBLICATIONLOADSTART` → `THEOliveApiEventTypes.DISTRIBUTIONLOADSTART`
* `THEOliveApiEventTypes.PUBLICATIONLOADED` → `THEOliveApiEventTypes.ENDPOINTLOADED`
* `THEOliveApiEventTypes.PUBLICATIONOFFLINE` → `THEOliveApiEventTypes.DISTRIBUTIONOFFLINE`

**Example:**

```dart
// Before
void setupEventListeners() {
  player.theoLive?.addEventListener(THEOliveApiEventTypes.PUBLICATIONLOADSTART, (e) {
    print("Starting to load publication");
  });

  player.theoLive?.addEventListener(THEOliveApiEventTypes.PUBLICATIONLOADED, (e) {
    print("Publication has loaded");
  });

  player.theoLive?.addEventListener(THEOliveApiEventTypes.PUBLICATIONOFFLINE, (e) {
    print("Publication went offline");
  });
}

// After
void setupEventListeners() {
  player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONLOADSTART, (e) {
    print("Starting to load distribution");
  });

  player.theoLive?.addEventListener(THEOliveApiEventTypes.ENDPOINTLOADED, (e) {
    print("Endpoint has loaded");
  });

  player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONOFFLINE, (e) {
    print("Distribution went offline");
  });
}
```

### Step 4: Update Event Class References

If you have custom event handling code that checks event types:

**Before:**

```dart
void handleEvent(Event event) {
    if (event is PublicationLoadedEvent) {
        print("Publication has loaded.");
    }
    ...
    
    if (event is PublicationLoadStartEvent) {
        print("Publication loading started.");
    }
    ...
    
    if (event is PublicationOfflineEvent) {
        print("Publication went offline.");
    }
}
```

**After:**

```dart
void handleEvent(Event event) {
    if (event is EndpointLoadedEvent) {
        print("Endpoint has loaded.");
    }
    ...
    
    if (event is DistributionLoadStartEvent) {
        print("Distribution loading started.");
    }
    ...
    
    if (event is DistributionOfflineEvent) {
        print("Distribution went offline.");
    }
}
```

### Step 5: Update Integration Tests

If you have integration tests that check publication state:

**Before:**

```dart
expect(player.theoLive?.publicationState == PublicationState.loaded, isTrue);
```

**After:**

```dart
expect(player.theoLive?.distributionState == DistributionState.loaded, isTrue);
```

### Step 6: Update Android Source Configuration

Remove PlaybackPipeline configurations from Android sources:

**Before:**

```dart
AndroidTypedSourceConfiguration config = AndroidTypedSourceConfiguration(
    playbackPipeline: PlaybackPipeline.media3
);
```

**After:**

```dart
AndroidTypedSourceConfiguration config = AndroidTypedSourceConfiguration();
```

### Step 7: Update Event Parameter Access

Change event parameter names in custom event handlers:

**Before:**

```dart
void onDistributionEvent(DistributionLoadStartEvent event) {
    String id = event.publicationId;  // Old parameter name
}
```

**After:**

```dart
void onDistributionEvent(DistributionLoadStartEvent event) {
    String id = event.distributionId;  // New parameter name
}
```

## Automated Migration

You can use find-and-replace in your IDE to automate most of the migration:

1. **Find:** `PublicationState` **Replace:** `DistributionState`
2. **Find:** `publicationState` **Replace:** `distributionState`
3. **Find:** `PUBLICATIONLOADSTART` **Replace:** `DISTRIBUTIONLOADSTART`
4. **Find:** `PUBLICATIONLOADED` **Replace:** `ENDPOINTLOADED`
5. **Find:** `PUBLICATIONOFFLINE` **Replace:** `DISTRIBUTIONOFFLINE`
6. **Find:** `PublicationLoadedEvent` **Replace:** `EndpointLoadedEvent`
7. **Find:** `PublicationLoadStartEvent` **Replace:** `DistributionLoadStartEvent`
8. **Find:** `PublicationOfflineEvent` **Replace:** `DistributionOfflineEvent`
9. **Find:** `event.publicationId` **Replace:** `event.distributionId`
10. **Find:** `PlaybackPipeline.media3` **Replace:** *(remove - no longer needed)*
11. **Find:** `PlaybackPipeline.legacy` **Replace:** *(remove - no longer supported)*
12. **Find:** `playbackPipeline: PlaybackPipeline.` **Replace:** *(remove entire parameter)*

## What Remains Unchanged

* All other THEOlive APIs
* Event listener registration/removal methods
* Source configuration (`TheoLiveSource`)
* Player initialization and setup

## Rationale

These changes were made to:

* **Align with THEOplayer 10.0.0**: Update to the latest native SDK with improved APIs
* **Consistent terminology**: Match THEOplayer's native SDK distribution/endpoint terminology
* **Simplified configuration**: Remove deprecated PlaybackPipeline options (Media3 is now the standard)
* **Clearer parameter names**: `distributionId` better represents the actual data than `publicationId`
* **Improved developer experience**: More intuitive and predictable API surface

## Need Help?

If you encounter issues during migration or have questions about the new API, please:

1. Check the updated documentation in `doc/theolive.md`
2. Review the example app for working code samples
3. Open an issue in the repository with specific migration questions

---

# Picture-in-Picture support

THEOplayer Flutter SDK supports native Picture-in-Picture on iOS, Android and Web platforms. However, there are some differences and limitations.

## Android and iOS

Entering Picture-in-Picture (PiP) is possible through the `THEOplayer.setAllowAutomaticPictureInPicture(bool)` API.

This will not put the player into Picture-in-Picture mode immediately, but enables the player to enter PiP when the application moves to the background.

### Necessary configurations on app-level

#### Android

Enable [Picture-in-Picture support](https://developer.android.com/develop/ui/views/picture-in-picture#declaring) for your main Activity in the `AndroidManifest.xml` file.

```xml
<activity android:name=".MainActivity"
    android:supportsPictureInPicture="true"
    android:configChanges=
        "screenSize|smallestScreenSize|screenLayout|orientation|..."
    ...
```

#### iOS

Enable `Background Audio mode` for your application target in [XCode](https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/MediaPlaybackGuide/Contents/Resources/en.lproj/ConfiguringAudioSettings/ConfiguringAudioSettings.html#//apple_ref/doc/uid/TP40016757-CH9-SW4).

![](https://raw.githubusercontent.com/THEOplayer/flutter-theoplayer-sdk/main/doc/xcode_background_modes.png)

### Limitations

* Picture-in-Picture is only supported from Android O (Oreo, API level 26).

* Picture-in-Picture is only supported from iOS 14.

* In multi-player scenarios there can be only one player that has `allowAutomaticPictureInPicture` set to `true`. Failing to do so might lead to unpredictable behaviour.

* On iOS paused player can not enter PiP mode.

* Calling `THEOplayer.setPresentationMode(PresentationMode.PIP)` API to explicitly enter PiP mode doesn't work on iOS and Android.

  * This limitation is due to the differences on how native iOS and Android handles the PiP mode.

    * iOS moves the player into PiP, while keeping the ViewController on the screen.
    * Android moves the whole Activity into PiP.

  * Aligning these will be investigated in the next iterations of the THEOplayer Flutter SDK.

  * You can try use the [`go_home`](https://pub.dev/packages/go_home) package to simulate "Home button press" on Android and iOS to trigger application backgrounding (which will start the automatic PiP mode).
    * **NOTE**: there could be issues in the App Stores with the way this plugin simulates the "Home button press", use it on your own risk.

## Web

Entering Picture-in-Picture (PiP) is possible through the `THEOplayer.setPresentationMode(PresentationMode.PIP)` API.

### Limitations

* Picture-in-Picture is not supported in Firefox.
* `THEOplayer.setAllowAutomaticPictureInPicture(bool)` API is not supported.

---

# THEOlive support

High-quality real-time video streaming at scale for providers of sports betting, iGaming and interactive entertainment

For more info, visit [THEOlive website](https://www.theoplayer.com/product/theolive).

## Limitations

* Only Flutter Web is supported.
* Android and iOS will follow later. (You can check out our dedicated [THEOlive Flutter SDK](https://github.com/THEOplayer/flutter-theolive-sdk))

## THEOlive playback

THEOlive playback is becoming crucial part of THEOplayer's playback engine instead of being available as a separate SDK.

The WEB support is already added, Android and iOS support as part of the THEOplayer SDK will come later. (Right now you can use the [dedicated THEOlive Flutter SDK](https://github.com/THEOplayer/flutter-theolive-sdk) for Android and iOS support)

### Setting a THEOlive source

```js
player.source = SourceDescription(sources: [
    TheoLiveSource(src: "2vqqekesftg9zuvxu9tdme6kl"),
]);
```

Instead of using a remote HTTPS url, you can just specify your `channelID` from the [THEOlive Console](https://console.theo.live/) and you can start the playback.

**NOTE:** your THEOplayer license has to contain the `HESP` feature to make it work. (HESP is the underlying technology of THEOlive).

Once the playback starts, you can listen to playback-specify events on THEOplayer.

#### Additional configuration options on `THEOPlayerConfig`

By setting a `THEOliveConfiguration` object on `THEOplayerConfig` you are able to specify extra configuration for THEOlive (e.g. a custom sessionId to follow the requests on the backend)

```js
    player = THEOplayer(
        theoPlayerConfig: THEOplayerConfig(
          license: PLAYER_LICENSE,
          theolive: TheoLiveConfiguration(externalSessionId: "mySessionID"),
        ),
        onCreate: () {
          print("player is created, ready to use");
    
        });
```

### Listening for THEOlive-specific events

```js
    player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONLOADSTART, (e) {
        print("DISTRIBUTIONLOADSTART");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONOFFLINE, (e) {
        print("DISTRIBUTIONOFFLINE");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.ENDPOINTLOADED, (e) {
        print("ENDPOINTLOADED");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.INTENTTOFALLBACK, (e) {
        print("INTENTTOFALLBACK");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.ENTERBADNETWORKMODE, (e) {
        print("ENTERBADNETWORKMODE");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.EXITBADNETWORKMODE, (e) {
        print("EXITBADNETWORKMODE");
    });
```

## Migration from THEOlive Flutter SDK to THEOplayer Flutter SDK

### setStateListener

From

```js
theoLive.setStateListener(...)
```

to

```js
player.theoLive.setStateListener(...)
```

### loadChannel

From

```js
theoLive.loadChannel("2vqqekesftg9zuvxu9tdme6kl")
```

to

```js
player.source = SourceDescription(sources: [
    TheoLiveSource(src: "2vqqekesftg9zuvxu9tdme6kl"),
]);
```

### addEventListener

From

```js
theoLive.addEventListener(this)
```

to THEOlive-related events

```js
    player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONLOADSTART, (e) {
        print("DISTRIBUTIONLOADSTART event");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.DISTRIBUTIONOFFLINE, (e) {
        print("DISTRIBUTIONOFFLINE event");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.ENDPOINTLOADED, (e) {
        print("ENDPOINTLOADED event");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.INTENTTOFALLBACK, (e) {
        print("INTENTTOFALLBACK event");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.ENTERBADNETWORKMODE, (e) {
        print("ENTERBADNETWORKMODE event");
    });
    player.theoLive?.addEventListener(THEOliveApiEventTypes.EXITBADNETWORKMODE, (e) {
        print("EXITBADNETWORKMODE event");
    });
```

and to playback-related events

```js
    player.addEventListener(PlayerEventTypes.PLAY, (e) {
        print("PLAY event");
    });
    player.addEventListener(PlayerEventTypes.PLAYING, (e) {
        print("PLAYING event");
    });
    player.addEventListener(PlayerEventTypes.PAUSE, (e) {
        print("PAUSE event");
    }););
```

### Playback-related actions

From

```js
theoLive.play()
```

to

```js
player.play()
```

### Channel events

The channel related events:

```js
ChannelLoadStart,
ChannelLoaded,
ChannelOffline
```

are renamed to `Publication` events

```js
PublicationLoadStart,
PublicationLoaded,
PublicationOffline
```

### Anything missing?

Please reach out to us!

---

# The THEOplayer component

## Architecture

![](https://raw.githubusercontent.com/THEOplayer/flutter-theoplayer-sdk/main/doc/theoplayer_flutter_sdk_arch.png)

THEOplayer Flutter SDK utilizes the well-known THEOplayer native SDKs under the hood and exposes the APIs on a single API layer in Flutter to speed up prototyping and development.

## Available APIs

* Basic player APIs (play, pause, seek, etc...) on the `THEOplayer` instance
* `SourceDescription`-related classes
* Player events (`CANPLAY, PLAYING, TIMEUPDATE`, etc..)
* Track APIs (acive tracks, cues, enable, disable) on the `THEOplayer.[audio|video|text]track` objects
* `Track`-related classes
* Track events (`ADD_TRACK, REMOVE_TRACK, ADD_CUE, ENTER_CUE`, etc..)

## API Reference

*To be completed.*

Please use your IDE's features to discover the available APIs.

Read [`theoplayer.dart`](https://github.com/THEOplayer/flutter-theoplayer-sdk/blob/-/flutter_theoplayer_sdk/flutter_theoplayer_sdk/lib/theoplayer.dart) for all the details.

---

# WASM support (experimental)

When compiling the THEOplayer Flutter SDK for WEB, you can now specify [WASM support](https://docs.flutter.dev/platform-integration/web/wasm).

## Flutter Compatibility

Use **Flutter 3.35.3 or later** for the best performance and compatibility. (earlier versions could have rendering issues with the video element)

## Run or build your app

To run the app with Wasm for development or testing, use the `--wasm` flag with the `flutter run` command.

```bash
flutter run -d chrome --wasm
```

To build a web application with Wasm, add the `--wasm` flag to the existing `flutter build web` command.

```bash
flutter build web --wasm
```

The command produces output into the `build/web` directory relative to the package root, just like `flutter build web`.

## Changes required in your app

### Bootstrapping

Make sure your app's `web/index.html` is updated to the [latest Flutter web app initialization](https://docs.flutter.dev/platform-integration/web/initialization) (it was introduced from Flutter 3.22).

It depends on your project structure, but most of the times this only means you need to make sure that `flutter_bootstrap.js` is properly included in your `index.html`.

### Include THEOplayer WEB SDK as asset

Define the path of the folder that contains THEOplayer Web SDK as an `asset` in your `pubspec.yaml` file to make sure the Javascript files will be included.

For example, if the THEOplayer WEB SDK is located under `web/theoplayer`, then

```yaml
  assets:
    - web/theoplayer/
```

## Browser support

Not all browsers support the Flutter WASM renderer. Please always check the status of the compatibility [here](https://docs.flutter.dev/platform-integration/web/wasm#learn-more-about-browser-compatibility).

## Host it on a compatible server

Extra [configuration is needed](https://docs.flutter.dev/platform-integration/web/wasm#serve-the-built-output-with-an-http-server) on the server-side to make sure WebAssembly runs properly.

During debugging the `flutter run -d chrome --wasm` command will serve your webapp properly, but once you build a release version and host it on your own server, you need to make sure the server is configured properly.

For example don't expect that any basic web serving command e.g. (`python3 -m http.server 8000`) will just to run with WebAssembly support.

On the other hand most of the hosting solutions (e.g. Netlify or [Netlify Drop](https://app.netlify.com/drop)) will have this configured out of the box.

Always consult with your hosting provider first!

---

# Getting started

## Usage

We have migrated OptiView Live Flutter support to be a feature of the THEOplayer Flutter SDK.

To use Flutter for OptiView Live playback, you must use the [THEOplayer Flutter SDK](https://pub.dev/packages/theoplayer) which now supports Web, Android, and iOS devices. The following steps will ensure your project is setup optimally:

1. Review the [THEOplayer Flutter SDK limitations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/limitations.md) to ensure your use case needs are supported before starting development.
2. Follow along with the [THEOplayer Flutter SDK minimal setup guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/creating-minimal-app.md) to setup a basic OptiView Live project.
3. Check the [THEOlive support guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/theolive.md) for the latest OptiView Live Flutter updates.

For customers currently using the now deprecated OptiView Live SDK for playback, please migrate to using the THEOplayer SDK with the following [THEOlive migration guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter/guides/theolive.md#migration-from-theolive-flutter-sdk-to-theoplayer-flutter-sdk) to always have the latest updates.

### Flutter project setup

Run the following script to generate boilerplate code for your Flutter project:

```bash
$ flutter create -a kotlin -i swift -t app --org com.theoplayer --description "New THEOlive project" --project-name "theolive_sample_app" --platform ios,android theolive_sample_app
```

### Initializing a THEOplayer instance

Configure the THEOplayer by setting your THEOplayer license on the `license` property and optionally providing a `theolive` property for custom configuration:

```dart
late THEOplayer player;

@override
void initState() {
  super.initState();

  player = THEOplayer(
      theoPlayerConfig: THEOplayerConfig(
        license: "YOUR_PLAYER_LICENSE_STRING",
        // Extra THEOlive configuration - set a custom sessionId to follow the requests on the backend
        theolive: TheoLiveConfiguration(externalSessionId: "mySessionID"),
      ),
      onCreate: () {
        print("THEOplayer is created and ready to use");
      });
}
```

### Add an OptiView Live source

After initializing a THEOplayer instance in your Flutter project, set its source with a `SourceDescription` containing a `TheoLiveSource`:

```text
// a THEOlive channel ID is entered for the theoLiveSource 'src' property
player.source = SourceDescription(sources: [
    TheoLiveSource(src: "2vqqekesftg9zuvxu9tdme6kl"),
]);
```

### Next steps

If you've followed the steps above, you should now have a boilerplate OptiView Live Flutter application to further develop your project from.

Use Flutter documentation along with our [basic playback guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/flutter/theolive/basic-playback-guide.md) for Flutter to develop your project.

## More information

* [THEOplayer Flutter SDK GitHub](https://github.com/THEOplayer/flutter-theoplayer-sdk/tree/main)

---

# Basic Playback Guide

After following our [Getting Started with Flutter guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/flutter/theolive/getting-started.md) or the [Player Setup](#player-setup) section below, you will be ready to programmatically perform common playback actions. These include increasing/decreasing the volume, playing/pausing the stream, enabling full screen, and selecting quality layers.

## Player Setup

To get started with OptiView Live playback using Flutter, you must first initialize a THEOplayer instance and set an OptiView Live source.

Here is example code of initializing a THEOplayer instance with Flutter:

```dart
late THEOplayer player;

@override
void initState() {
  super.initState();

  player = THEOplayer(
      theoPlayerConfig: THEOplayerConfig(
        license: "YOUR_PLAYER_LICENSE_STRING",
        // Extra THEOlive configuration - set a custom sessionId to follow the requests on the backend
        theolive: TheoLiveConfiguration(externalSessionId: "mySessionID"),
      ),
  )
}

player.source = SourceDescription(sources: [
    TheoLiveSource(src: "2vqqekesftg9zuvxu9tdme6kl"),
]);
```

## Adjust Volume

To adjust the volume of your stream during playback, you can set the `volume` property to a floating point number in the range of 0.0 (0%) minimum and 1.0 (100%) maximum.

The following code sets the player's volume to 50%:

```dart
// the stream's volume will now be 50%
player.volume = 0.5;
```

## Play/Pause Stream

To play or pause your stream, you can use the `play` and `pause` methods available on your player variable.

To pause your stream:

```dart
player.pause();
```

To play your stream:

```dart
player.play();
```

## Enable Full Screen

To make your stream take up the full screen of the device it is being viewed upon, you must use the `setPresentationMode` method.

The `setPresentationMode` method can accept the following arguments:

* `'INLINE'`: The player is shown in its original location on the page. (default presentation mode)
* `'FULLSCREEN'`: The player fills the entire screen.
* `'PIP'`: (Picture-in-picture) The player is shown on top of the page (see PiPConfiguration for more options).

To make the current stream take up the full screen, pass a presentationMode of 'fullscreen' to the requestMode method with the following code:

```dart
// stream will take up the full screen which it is being viewed on
player.setPresentationMode('FULLSCREEN');
```

To confirm that the change has occurred, check the `getPresentationMode` property to ensure it now returns `fullscreen` as its value:

```dart
// should return a value of 'fullscreen' to the console
print('this is the current presentation mode being used --> ${player.getPresentationMode()}');
```

## Select Quality Layer

To select a specific quality layer during the playing of your stream, you must set the `targetQuality` property of your player's `videoTracks` property.

The `videoTracks` property leverages the Video Tracks API and will allow you to see all quality layers available, the current active quality layer, and set a new target quality layer.

To see what qualities you have available, use the following code:

```dart
// import needed to use the 'inspect' function
import 'dart:developer';

// inspect all available quality layers
var qualities = player.videoTracks.first.qualities.innerList;
inspect("this is an array containing all available qualities --> ${qualities}");
```

Once you know what options you have available, you can set the stream to be a specific quality with the following:

```dart
// set the first quality layer in the array to be the target quality layer
player.videoTracks.first.targetQuality = player.videoTracks.first.qualities.first;
```

## More information

* [THEOplayer Flutter SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/flutter.md)

---

# THEOplayer Chromecast SDK

Dolby OptiView Player (formerly THEOplayer) is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/chromecast/getting-started.md)

[Set up your first THEOplayer in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/chromecast/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md)

## [📰Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog.md)

[Find out what's new in the OptiView Player.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog.md)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

# Getting started on Chromecast

This how-to guide describes how to set up a Chromecast Receiver application using the Dolby OptiView Player SDK.

> **Info**
>
> This guide is intended for developing a Chromecast Receiver application with Google Cast SDK v2. Since Google Cast SDK v2 is deprecated by Google, we highly recommend developing your Chromecast SDK with CAF instead of v2. You can find the THEOplayer Cast Receiver Reference app [here](https://github.com/THEOplayer/samples-google-cast-v3-receiver).

## Prerequisite:

You need to build a THEOplayer Chromecast Receiver SDK from THEOportal.

## Set up a web project

A Chromecast Receiver application is a web project. Create a sample project, add a `_receiver_` folder, and create an index.html file in this folder with the following skeleton code.

## Integrate the Google Cast Receiver SDK

By including the Google Cast Receiver SDK, you have access to the Receiver API. The THEOplayer Receiver SDK leverages this API.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Chromecast Receiver Sample Application</title>
    <script src="//www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js"></script>
  </head>
  <body></body>
</html>
```

## Integrate the THEOplayer Chromecast Receiver SDK

By including the THEOplayer Chromecast Receiver SDK, you have access to the THEOplayer Receiver SDK. This SDK consists of a JavaScript library (consisting of four files) and a CSS file. Create a *release* folder, and put the 5 files belonging to the THEOplayer Chromecast Receiver SDK in this folder.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Chromecast Receiver Sample Application</title>
    <script src="//www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js"></script>
    <script src="../release/THEOplayer-cast-receiver.js"></script>
    <link rel="stylesheet" type="text/css" href="../release/ui.css" />
  </head>
  <body></body>
</html>
```

## Set up THEOplayer instance

Setting up a THEOplayer instance in a Chromecast Receiver application is similar to our Web SDK. More information on setting up the THEOplayer Web SDK can be found at [Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md).

You need to add a DOM-element which will contain the user interface of THEOplayer, and you need to initialize the THEOplayer instance through JavaScript code.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Chromecast Receiver Sample Application</title>
    <script src="//www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js"></script>
    <script src="../release/THEOplayer-cast-receiver.js"></script>
    <link rel="stylesheet" type="text/css" href="path/to/theoplayer/ui.css" />
  </head>
  <body>
    <div id="my-player"></div>
    <script>
      var player = new THEOplayer.Player(document.getElementById('my-player'), {
        libraryLocation: 'path/to/theoplayer/',
        license: 'your-license-here',
      });
    </script>
  </body>
</html>
```

## Optional: alter default UI

The CSS snippet added to the code-block below have the following effect:

1. `.THEO-cast-receiver-player .THEO-cast-receiver-logo`: Change the default splash image when your receiver app is loading. This default splash image will show a THEOplayer-branded image, but you might want to replace it with a different image.
2. `.THEO-cast-receiver-player .THEO-cast-receiver-watermark`: Change the default watermark logo which is shown when pausing (or buffering). This default watermark logo will show a THEOplayer-branded image, but you might want to replace it with a different image.

In each of the examples, be sure to set the image source correctly, by replacing the '...'.

Note that you can also use the easy UI skinning colors to modify the UI as described in <http://demo.theoplayer.com/ui-skinning>. You can reuse the CSS you use in the THEOplayer Web SDK in your Chromecast receiver as well!

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Chromecast Receiver Sample Application</title>
    <script src="//www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js"></script>
    <script src="../release/THEOplayer-cast-receiver.js"></script>
    <link rel="stylesheet" type="text/css" href="../release/ui.css" />
    <style>
      .THEO-cast-receiver-player .THEO-cast-receiver-logo {
        position: static;
        margin: 0 auto;
        width: 100%;
        height: 100%;
        background:
          url('...') no-repeat,
          no-repeat center;
        background-size: cover;
      }

      .THEO-cast-receiver-player .THEO-cast-receiver-watermark {
        width: 124px;
        height: 65px;
        background-image: url('...');
      }
    </style>
  </head>
  <body>
    <div id="my-player"></div>
    <script>
      var player = new THEOplayer.Player(document.getElementById('my-player'), {
        libraryLocation: '../release/',
      });
    </script>
  </body>
</html>
```

## Publish the application

Before you can deploy your application, you should upload your web project to an HTTPS location. (e.g. [https://cdn.your-website.com/cast/chromecast/sample-project/)](https://cdn.your-website.com/cast/chromecast/sample-project/)) Ensure that your folder structure respects the aforementioned structure.

## Deploy the application

This has to be done through the [Google Cast SDK Developer Console](https://developers.google.com/cast/docs/registration)

Your Chromecast Receiver sample application is now in a state where it can be deployed as a real application. If you have a Google Cast SDK Developer Console, you can log in to <https://cast.google.com/u/1/publish/#/overview>.

![](/pr-932/assets/images/image2018-5-25_15-31-6-f47e2f0c62571237adcdd11a2395b28d.png)

![](/pr-932/assets/images/image2018-5-25_15-31-19-7317abb73b4c3cb9e2e6ebdd98181107.png)

![](/pr-932/assets/images/image2018-5-25_15-31-26-cb0e373616c71ae98bf52259fe449ad6.png)

You have to go through the following steps:

1. Click "ADD NEW APPLICATION".
2. Select "Customer Receiver".
3. Enter information and refer to the HTTPS location of your web project.
4. Press start and wait.

## Test it

Once your application is published, you can start casting from your THEOplayer Web SDK, iOS SDK or Android SDK. You need to set the correct [appID](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/CastConfiguration), enable Chromecast and press the Chromecast icon. Additionally, you can start casting through the [Cast API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/GlobalCast).

## Related articles

* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)
* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/how-to-configure-to-a-different-stream.md)
* [Chromecast on my webplayer does not work any longer despite no change in my implementation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/chromecast-on-weblayer-does-not-longer-work.md)
* [Connecting from custom Sender applications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/connecting-from-custom-sender-applications.md)

---

# Chromecast Application Customization

This article provides information on how to customize the look and feel of a Chromecast [Sender application](https://developers.google.com/cast/glossary#sender) or a Chromecast [Receiver Application](https://developers.google.com/cast/glossary#receiver). ![Casting approaches](/pr-932/assets/images/casting-approaches-45dc2983f20d11409d27d3248b57a6ef.png "Casting approaches")

## Background

This section provides background information on Google, THEOplayer SDKs, Sender apps and Receiver apps. Feel free to skip directly to the sections on [Customizing a Sender Application](#customizing-a-sender-application) or [Customizing a Receiver application](#customizing-a-receiver-application) if you are already familiar with these background topics.

### Google, Chromecast and THEOplayer

Google's point of entry to Chromecast is located at <https://developers.google.com/cast/docs/developers>. In this article, they write about sender applications and their three Cast APIs, and about receiver applications and their four options.

#### Sender applications

Google describes three Cast APIs: the Android API, the iOS API and the Web Sender API. The THEOplayer SDKs integrate these Cast APIs and expose a wrapper API for developers to use instead.

1. The THEOplayer Android SDK implements the [Android API](https://developers.google.com/android/reference/com/google/android/gms/cast/package-summary).
2. The THEOplayer iOS SDK implements the [iOS API](https://developers.google.com/cast/docs/reference/ios).
3. The THEOplayer Web SDK implements the [Web Sender API](https://developers.google.com/cast/docs/reference/web_sender).

#### Receiver applications

Google describes four types of receiver applications:

1. [Default Media Receiver](https://developers.google.com/cast/docs/web_receiver#default_media_web_receiver)
2. [Styled Media Receiver](https://developers.google.com/cast/docs/styled_receiver)
3. [Custom Receiver](https://developers.google.com/cast/docs/web_receiver#custom_web_receiver)
4. [Android TV Receiver](https://developers.google.com/cast/docs/android_tv_receiver)

The THEOplayer Chromecast Receiver SDK fits in the category of a "Custom Receiver". You integrate this THEOplayer SDK in your HTML5 Chromecast Receiver application.

### Sender application vs Receiver application

When talking about customizing a Chromecast application, one needs to make a distinction between customizing [a Sender application versus a Receiver application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/introduction.md).

A **Chromecast Sender application** is the application on a "sender device" (e.g. smartphone, browser, ...) which initiates the Chromecast session. You use the Sender application to start (and stop) Chromecast playback, to pause the video or to mute it, to seek to a different position in the scrub bar, and so on. The unique UI components related to Chromecast in a Sender application are limited to a Chromecast button which starts/stops a Chromecast session. The default controls (e.g. play, pause, scrub bar) are used to control the Receiver application.

**In a Sender application, you use either the THEOplayer [Web](https://www.theoplayer.com/sdk/html5), [iOS](https://www.theoplayer.com/sdk/ios) or [Android](https://www.theoplayer.com/sdk/android) SDK.**

A **Chromecast Receiver application** is the application which is loaded on your Chromecast-enabled device (e.g. Chromecast Ultra, Android TV, ...). The UI of a Receiver application is typically quite simple:

1. When a video is playing, the video is playing fullscreen without any elements overlaying it.
2. When a video is paused, there is timeline indicating the playhead position and an element (e.g. a pause button) indicating that the playback is paused. Sometimes, when a video is paused, a poster image (i.e. thumbnail) and some text are shown to describe the active content.
3. When an app and/or stream starts to load, you might see a brand logo and/or a spinning wheel.

**In a Receiver application, you use the THEOplayer [Chromecast Receiver SDK](https://www.theoplayer.com/sdk/chromecast).**

## Customizing a Sender application

*If you are using the THEOplayer Web, iOS or Android SDK in your Sender application, confirm that the `chromecast` [module is enabled](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/theoplayer-features-modules.md) for your SDK. This feature exposes a Chromecast API you can benefit from. Additionally, ensure that you [include the Chromecast library](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/enable-chromecast-on-the-sender.md).*

*Please refer to ["Connecting from custom Sender applications"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/connecting-from-custom-sender-applications.md) if you are not using THEOplayer's `chromecast` feature.*

Generally speaking, there are three types of user interfaces:

1. Default UI: you use THEOplayer's default UI, and you're happy with it.
2. Chromeless UI: you've build a Chromeless UI from scratch on top of THEOplayer.
3. Altering Default UI: you use THEOplayer's default UI, but you've changed some things around. (e.g. different colors, a new button, ....)

### Default UI

THEOplayer automatically inserts a Chromecast button in its default video player UI if you are using THEOplayer's default UI. ![Chromecast button](/pr-932/assets/images/chromecast-active-53e1680cf7234d5d0c029e99356dd548.png "Chromecast button") The UI of this button changes when the [Chromecast state](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/CastState) changes. Please see below if you want to alter this default UI.

### Chromeless UI

You are in charge of all UI components if you are using THEOplayer's Chromeless UI. Typically, you want to insert a Chromecast button, and connect that button with our Cast API to start (e.g. `player.cast.chromecast.start()`) and stop (`player.cast.chromecast.stop()`) a Chromecast session. Additionally, you might want to change the appearance of this button when the state of your casting session transitions (e.g. `player.cast.chromecast.addEventListener('statechange', function() {...});`).

* Web: [Chromecast API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Chromecast), [Cast API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VendorCast), [Cast Events API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VendorCastEventMap)
* iOS: [Chromecast API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/Chromecast), [Chromecast Events API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/ChromeCast%20Events#/s:13THEOplayerSDK16StateChangeEventC)
* Android: [Chromecast API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/cast/chromecast/Chromecast), [Chromecast Events API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/chromecast/CastStateChangeEvent)

Familiarize yourself with the above APIs if you want to change the appearance of your Chromeless UI and its relation to Chromecast.

### Altering Default UI

If you are using THEOplayer's default UI, but want to use your own button instead, then you can hide THEO's default button, and [insert a new one](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-insert-a-button.md) instead. You also need to use our Cast API described in the above "Chromeless UI" section.

## Customizing a Receiver application

[Three Receiver application set-ups](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/introduction.md) are common:

1. You connect with THEOplayer's default Receiver application.
2. You connect with a custom Receiver application powered by the THEOplayer Chromecast Receiver SDK.
3. You connect with a custom Receiver application which doesn't contain any THEOplayer SDK or code.

You can provide Chromecast metadata in all three set-ups. Providing [Chromecast metadata](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SourceDescription#metadata) will make your Receiver application show relevant info (e.g. a title, a thumbnail, ...) when your application is buffering or paused.

### Default Receiver application

If you are connected to THEOplayer's default Receiver application, you cannot modify its appearance.

If you want to change the UI, you need to [connect your sender application with a different Receiver application ID](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/connecting-from-custom-sender-applications.md).

### Custom Receiver application with THEOplayer Chromecast SDK

You can build a custom Receiver application by using our [Chromecast Receiver SDK](https://www.theoplayer.com/sdk/chromecast). Once you went through its [Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/chromecast/getting-started.md), you'll notice that the UI is similar to the default UI. However, through this approach, you have the option to alter the UI as described by the [Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/chromecast/getting-started.md#optional-alter-default-ui).

### Custom Receiver application without THEOplayer Chromecast SDK

You can [connect your sender application with a custom Receiver application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/connecting-from-custom-sender-applications.md) which does not use the THEOplayer Chromecast SDK. Naturally, you're responsible for the look and feel of this custom Receiver application.

## Conclusion

Identify whether you want to adjust the UI and UX of the Sender application or the Receiver application.

* If it's the Sender application, determine whether you are changing a Sender app which leverages the THEOplayer Web, iOS or Android SDK to enable casting.
* If it's the Receiver application, determine whether you are changing our default Receiver application, a custom Receiver application using the THEOplayer Chromecast SDK or 3) a custom Receiver application which is not using the THEOplayer Chromecast.

Then, decide which states and which components you want to customize. Finally, identify which THEOplayer APIs are relevant for your use-cases.

## Notes

* Google describes their Chromecast UX guidelines at <https://developers.google.com/cast/docs/ux_guidelines/>.
* This article is currently categorized under the "Getting Started" guides of our Chromecast SDK, which is also known as our Chromecast Receiver SDK. Naturally: you leverage a Chromecast Receiver SDK in a Chromecast Receiver application. In result, this categorization might be confusing to some readers, because we have discussed concepts and APIs which relate to a Sender application. However, we do feel that it's valuable to discuss the bigger picture surrounding a Chromecast Receiver SDK, and that includes its relationship with a Sender application, and how to customize both.

## Resources

* [Getting started on Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/chromecast/getting-started.md). This article contains sample code. Note that the THEOplayer Chromecast SDK also contains a sample Receiver application.
* [Enable Chromecast on the Sender](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/enable-chromecast-on-the-sender.md)
* [Chromecast Introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/introduction.md)
* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/how-to-configure-to-a-different-stream.md)

---

# THEOplayer Roku SDK

Dolby OptiView Player (formerly THEOplayer) is the universal video player solution from Dolby. It offers support for HLS, MPEG-DASH, advertisements, DRM and much more.

On these pages, you'll learn how to get started with Dolby OptiView Player, how to use the various features, and explore the many examples.

## [🚀Getting started](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/roku/getting-started.md)

[Set up your first THEOplayer in just a few minutes!](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/roku/getting-started.md)

## [📖How-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md)

[Learn how to implement our rich set of features and integrations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md)

## [🔌Connectors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/roku.md)

[Integrate third-party solutions with THEOplayer using our pre-built connectors.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/roku.md)

## [\*️⃣API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/roku.md)

[Discover all properties and functions of THEOplayer.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/roku.md)

## [🧠Knowledge base](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

[Learn about topics in the video industry from our experts.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base.md)

## [❔FAQ](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

[Answers to common questions we've received from our customers over the years.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/faq.md)

---

# Player API

The attributes, methods and events.

## Enums

| Name          | Type              | Description                                                       |
| ------------- | ----------------- | ----------------------------------------------------------------- |
| ErrorCategory | associative array | Provides a dictionary of Error category names and integer values. |
| ErrorCode     | associative array | Provides a dictionary of Error code names and integer values.     |
| Event         | associative array | Provides a dictionary of Event type names and string values.      |

## Attributes

| Name                         | Type                        | Default | Access Permission | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ---------------------------- | --------------------------- | ------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ads                          | Ads                         | Ads     | read              | Provides events, properties and methods relating to ad playback in the player. See below for more info.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| audioTracks                  | array of associative arrays | \[]     | read              | Provides information about audio tracks detected automatically in video. Each Associative array has the following fields: id - track identifier, label - track name, language - track language, enabled - true if track is current track                                                                                                                                                                                                                                                                                                                   |
| autoplay                     | boolean                     | false   | read,write        | Whether the player should play the video as soon as it is able after the source has been set.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| controls                     | boolean                     | true    | read,write        | Allows to enable or disable player controls (`true` to show controls, `false` to hide controls).                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| currentTime                  | integer                     |         | read,write        | Current timestamp of video.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| duration                     | integer                     |         | read              | Duration of video.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| enableTrickPlay              | boolean                     | true    | read,write        | Whether trick playback of the media is enabled, and whether the remote buttons will allow trickplay. NOTE: `controls` must be set to `true` for this to have any effect.                                                                                                                                                                                                                                                                                                                                                                                   |
| subtitleSelectionPreferences | associative array           |         | write             | The significance and priority order of the attributes and values for the subtitle tracks available in the video stream. The selected subtitle track is reflected in the `textTracks` with `mode` as "showing" when visible in full screen or "hidden" when not in full screen. Refer to `subtitleSelectionPreferences` section of Roku's [video node](https://developer.roku.com/en-au/docs/references/scenegraph/media-playback-nodes/video.md) documentation. To select a subtitle track, based on user input, use the `mode` field of the `textTracks`. |
| ended                        | boolean                     | false   | read              | Whether playback of the media is ended.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| errorObject                  | associative array           |         | read              | The last error that occurred for the current source, if any.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| loop                         | boolean                     | false   | read,write        | Whether playback of the media is looped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| muted                        | boolean                     | false   | read,write        | Set `true` to mute and `false` to un-mute the currently playing video                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| network                      | NetworkApi                  |         | read              | API node for network operations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| paused                       | boolean                     | true    | read              | Whether the player is paused.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| poster                       | string                      |         | read,write        | The poster of the current source.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| seeking                      | boolean                     |         | read              | `true` when player is seeking, `false` when player is not seeking now.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| source                       | Source Description          |         | read,write        | Describes source of current video.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| src                          | string                      |         | read              | The current URL of the media resource.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| theolive                     | THEOlive API                |         | read              | API node for THEOlive operations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| textTracks                   | array of associative arrays | \[]     | read,write        | Provides information about text and metadata tracks detected automatically in video. Each Associative array has the following fields: id - track identifier, label - track description, language - track language, mode - determines track state, available values: disabled, showing, hidden, activeCues: the current cue for this track                                                                                                                                                                                                                  |

### Source Description

The following key/value pairs are supported on the `source` attribute of the `THEOsdk:THEOplayer` :

| Name                | Type               | Description                                                                                                                                                                                                                                               |
| ------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sources             | roArray            | An array of Typed Sources. When specifying multiple source descriptions, the sources attribute will be interpreted as a playlist where the first typed source will play first and subsequent sources will play when its preceding typed source has ended. |
| title               | String             | The title of the media resource.                                                                                                                                                                                                                          |
| poster              | string             | The URL of an image to optionally use as the poster for the media source. This is used for SDPosterUrl, HDPosterUrl, and FHDPosterUrl.                                                                                                                    |
| live                | boolean            | Whether the asset is live or not.                                                                                                                                                                                                                         |
| drmHttpAgentHeaders | roAssociativeArray | An optional key-value dictionary that contains additional HTTP headers that will be sent for DRM key/license requests. The keys represent the HTTP header names and the values represent their corresponding values.                                      |
| ads                 | roArray            | An optional array of AdDescriptions.                                                                                                                                                                                                                      |
| headers             | roArray            | An optional array of strings representing headers to include on the content requests. The strings follow the format of `"headerName:headerValue"`. Defaults to an empty array to clear any headers that were set on HttpAgent.                            |

### Typed Source

The following key/value pairs are supported on the `sources` attribute of a Source Description:

| Name              | Type                             | Description                                                                                                                            |
| ----------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| src               | String                           | The URL of the media resource.                                                                                                         |
| type              | String                           | The content type (MIME type) of the media resource. Possible values are `application/dash+xml`, `application/x-mpegURL` and `theolive` |
| description       | String                           | The description of the media resource.                                                                                                 |
| playStart         | Number                           | The position in the stream the user starts playback at. Use negative numbers to offset from the live edge.                             |
| contentProtection | Content Protection               | Parameters for DRM playback                                                                                                            |
| SDBifUrl          | String                           | "Base Index Frames" URL for SD trick mode.                                                                                             |
| HDBifUrl          | String                           | "Base Index Frames" URL for HD trick mode.                                                                                             |
| FHDBifUrl         | String                           | "Base Index Frames" URL for FHD trick mode.                                                                                            |
| ads               | roArray of AdDescriptions        | Array of the ad description for the ads to play during the content.                                                                    |
| profile           | String                           | Optional. The profile to use when making the discovery call for THEOlive streams.                                                      |
| ssai              | GoogleDaiConfiguration           | Optional. The configuration for playing this as a dynamic ad insertion asset.                                                          |
| embeddedTextTrack | string                           | Name of the embedded text track in the asset. Not necessary if the track is explicitly defined in the manifest.                        |
| textTracks        | roArray of TextTrackDescriptions | Optional. An array of descriptions representing external text track files.                                                             |

"Base Index Frames" or BIF, is an archive file format that contains a set of still images, also known as "trick play thumbnails", supporting enhanced fast-forward and rewind modes during video playback.

### Text Track Descriptions

| Name    | Type    | Description                                                                                                                           |
| ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| default | Boolean | Optional. Is this the default text track. If true and no track is currently selected, this will be used over the Roku system default. |
| format  | String  | Optional. The format of the text track. Valid values are "ttml" and "webvtt". Use "ttml" for SMPTE-TT files.                          |
| kind    | String  | Optional. The kind of text track. Supported values are "captions" and "subtitles".                                                    |
| label   | String  | Optional. The label to show in menus for the text track.                                                                              |
| src     | String  | The URL for the text track file.                                                                                                      |
| srclang | String  | Optional. The language used in the text track. Can be the language name or an ISO 2 or 3 letter abbreviation.                         |

See [Roku's caption support guide](https://developer.roku.com/docs/developer-program/media-playback/closed-caption.md#closed-caption-support-summary) for what is supported for different stream and text track combinations.

### Ad Descriptions

| Name           | Type               | Description                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sources        | AdSource or string | Either an AdSource or the URL of the ad XML to load.                                                                                                                                                                                                                                                                                                                                                                       |
| integration    | string             | The kind of ad integration this uses. Currently the only supported value is `csai`.                                                                                                                                                                                                                                                                                                                                        |
| timeOffset     | string or number   | An optional value determining when to show the ad. It can either be the number of seconds representing the timecode in the video when the ad should play, or it can be `start` or `end` to play the ad either before or after the video. Additionally it could be a percent of the content's duration, like `25%`, or a timecode in the format `HH:MM:SS`. NOTE: This is for VAST ads only. Do not use this with VMAP ads. |
| replaceContent | boolean            | An optional value for whether this ad tag should replace content when the ad plays. Valid only for midrolls. Defaults to false.                                                                                                                                                                                                                                                                                            |

NOTE: when scheduling ads, VAST ads cannot be scheduled in the middle of the time covered by a VMAP ad tag. For instance, if you have a VMAP preroll and postroll in a single ad tag, you could not schedule midrolls in between them. However, if you had separate VMAP preroll and postroll tags, you could place a VAST midroll tag in between the two.

#### Ad Sources

| Name | Type   | Description                                                                                                                                                        |
| ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| src  | string | The URL of the XML file to load for the ad break.                                                                                                                  |
| type | string | The optional type of the ad. Supported values are either `vast` or `vmap`. Otherwise the default value is inferred from the AdDescription's `timeOffset` property. |

### SSAI/DAI Configuration

The player supports Dynamic Ad Insertion (DAI) using Google DAI. This integration currently supports doing Server Side Ad Insertion (SSAI) on live streams. To enable this, add the `ssai` property to your source with your Google DAI information. You can listen for ad events emitted by Google DAI on the Ads API.

The following key/value pairs are supported on the `ssai` attribute of a Typed Source:

| Name             | Type               | Description                                                                      |
| ---------------- | ------------------ | -------------------------------------------------------------------------------- |
| integration      | string             | The type of DAI integration. The supported values are "google-dai" or "theoads". |
| apiKey           | string             | The API key for your DAI account.                                                |
| availabilityType | string             | The type of asset you are playing ("live" or "vod").                             |
| networkCode      | string             | The network code for your DAI account.                                           |
| assetKey         | string             | Optional. The asset key for your live asset. Not required for VOD assets.        |
| adTagParameters  | roAssociativeArray | Optional. Map of ad tag parameters configurable for ad targeting.                |

NOTE: It is not supported to use SSAI through this API at the same time as Client-side Ad Insertion (CSAI) through the Ad Sources configuration.

### Content Protection

The following key/value pairs are supported on the `contentProtection` attribute of a Typed Source:

| Name        | Type           | Description                                                                                                                                                     |
| ----------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| integration | String         | *Optional attribute.* The key system the player should use. Possible values are `playready`, `widevine`.                                                        |
| licenseUrl  | String         | The license acquisition URL                                                                                                                                     |
| certificate | String         | The actual certificate string for Widevine purposes, which must be obtained out-of-band (OOB) by the channel. Leave this unset unless Widevine is used for DRM. |
| drmParams   | DRM Parameters | An alternative way to set parameters for DRM playback. *This attribute is only used when the `integration` attribute is not set.*                               |

**Example DRM source with VuDRM specific headers**

To play videos protected using VUDRM, you need to supply a token. Replace the token `vualto-demo|2018-06-19T09:18:24Z|YSnJPmEceo` in the code below with your own token as well as the associated values of the keys `src` and `licenseUrl`.

```brightscript
vuDrmSource = {
  sources: [
    {
      src: "https://d1chyo78gdexn4.cloudfront.net/vualto-demo/big-buck-bunny/big-buck-bunny.ism/manifest.mpd"
      type: "application/dash+xml"
      contentProtection: {
        integration: "widevine"
        licenseUrl: "https://widevine-proxy.drm.technology/proxy"
      }
    }
  ]
  drmHttpAgentHeaders: {
    "x-vudrm-token": "vualto-demo|2018-06-19T09:18:24Z|YSnJPmEceo"
    "Content-Type": "application/json"
  }
}
```

### DRM Parameters

The following key/value pairs are supported on the `drmParams` attribute of a Content Protection:

| Name             | Type   | Description                                                                                                                                                                                                                                                                                                                                                          |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| KeySystem        | String | "playready" or "widevine". This value is case-insensitive. The default is an empty string.                                                                                                                                                                                                                                                                           |
| licenseRenewURL  | String | A URL location for sending license renewal requests. If not specified, the Roku OS will send renewal requests to the URL specified in the licenseServerURL. This only works with widevine.                                                                                                                                                                           |
| licenseServerURL | String | A URL location of a license server. This URL may include CGI parameters.                                                                                                                                                                                                                                                                                             |
| serializationURL | String | A server address used for device provisioning                                                                                                                                                                                                                                                                                                                        |
| serviceCert      | String | The actual certificate string for Widevine purposes, which must be obtained out-of-band (OOB) by the channel. Leave this unset unless Widevine is used for DRM.                                                                                                                                                                                                      |
| lic\_acq\_window | String | The maximum amount of time (in milliseconds) that a channel waits before rotating its Widevine DRM keys. The channel can generate a random wait time between 0 and the value specified in the **lic\_acq\_window** field, and use the random wait time to instruct when the Video node should make its next Widevine license request. *Available since Roku OS 10.5* |

### Ads API

The Ads API exposes the following properties, methods, and events.

| Property          | Type                 | Access Permission | Description                                                                                                   |
| ----------------- | -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------- |
| currentAdBreak    | AdBreak              | read              | The current AdBreak if ads are playing, or invalid if they are not playing.                                   |
| currentAds        | array of Ads         | read              | Array of the current Ads in the current AdBreak, or invalid if ads are not playing.                           |
| events            | assocarray           | read              | Map of the event types the Ads API will emit.                                                                 |
| playing           | boolean              | read              | Whether an ad is currently playing.                                                                           |
| rafProxy          | RafProxyNode         | read              | roSGNode that exposes data from the internal RAF library.                                                     |
| scheduledAdBreaks | array of assocarrays | read              | Array of the scheduled breaks that haven't played. These may either be a source object or a resolved AdBreak. |
| scheduledAds      | array of Ads         | read              | Array of the ads that are scheduled and have not played. Only shows one break's ads with VAST.                |

| Method                                                                                       | Description                                       |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| addEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string)    | Add a listener for the specified player event.    |
| removeEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string) | Remove a listener for the specified player event. |
| schedule(adDescription as AdDescription)                                                     | Schedule an ad break.                             |

| Event            | Class        | Description                                                  |
| ---------------- | ------------ | ------------------------------------------------------------ |
| adbegin          | AdEvent      | The current creative has begun playing.                      |
| adbreakbegin     | AdBreakEvent | The player is entering an ad break.                          |
| adbreakend       | AdBreakEvent | The player is exiting an ad break.                           |
| adbuffering      | AdEvent      | The current ad is buffering during playback.                 |
| addadbreak       | AdBreakEvent | An ad break has been manually added.                         |
| adend            | AdEvent      | The current ad has completed playing.                        |
| aderror          | Event        | There was an error loading or playing an ad.                 |
| adfirstquartile  | AdEvent      | The viewer has watched the first quartile of the current ad. |
| adimpression     | AdEvent      | The ad has begun playing.                                    |
| adloaded         | Event        | The XML for an ad has been loaded.                           |
| admidpoint       | AdEvent      | The viewer has watched the half of the current ad.           |
| adsmanagerloaded | Event        | When the RAF ad manager has been initialized.                |
| adthirdquartile  | AdEvent      | The viewer has watched the third quartile of the current ad. |

#### AdEvent and AdBreakEvent

The AdEvent is an event object with the follow properties:

| Property | Type    | Description                                                                 |
| -------- | ------- | --------------------------------------------------------------------------- |
| type     | string  | The current AdBreak if ads are playing, or invalid if they are not playing. |
| date     | integer | The current epoch time in milliseconds.                                     |
| ad       | Ad      | The ad associated with the event.                                           |

The AdBreakEvent exposes the same properties as the AdEvent, but adds in a property with the current ad break:

| Event   | Class   | Description                        |
| ------- | ------- | ---------------------------------- |
| adBreak | AdBreak | The ad break the event relates to. |

#### AdBreak

The AdBreak object is an associative array that can have the following properties:

| Property    | Type       | Description                                                                                                          |
| ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------- |
| ads         | roArray    | An array containing the Ads in the AdBreak.                                                                          |
| customData  | assocarray | An associative array with any additional information for this ad break.                                              |
| id          | string     | The identifier of the ad break. For Google DAI, this is the pod index of the ad break.                               |
| integration | string     | The integration that generated the AdBreak. Currently the only supported value is `csai`.                            |
| maxDuration | integer    | The length of the break in seconds.                                                                                  |
| timeOffset  | integer    | The time in the video at which the ad break should play, in seconds. 0 indicates preroll, and -1 indicates postroll. |

The Ad object is an associative array that can have the following properties:

| Property     | Type       | Description                                                                          |
| ------------ | ---------- | ------------------------------------------------------------------------------------ |
| adBreak      | AdBreak    | The AdBreak this Ad belongs to.                                                      |
| adSystem     | string     | The ad system used to load this ad.                                                  |
| clickThrough | string     | The clickthrough URL for this ad.                                                    |
| companions   | roArray    | An array of any CompanionAds associated with this ad.                                |
| creativeId   | string     | The creative ID for this ad.                                                         |
| customData   | assocarray | An associative array with any additional information for this ad.                    |
| duration     | integer    | The duration of this ad.                                                             |
| height       | integer    | The height of the creative for this ad.                                              |
| id           | string     | The ad ID for this ad.                                                               |
| integration  | string     | The integration that generated the ad. Currently the only supported value is `csai`. |
| resourceUri  | string     | The URI for the creative played in this Ad.                                          |
| type         | string     | The type of ad. Currently only `linear` is supported.                                |
| width        | integer    | The width of the creative for this ad.                                               |

The CompanionAd object is an associative array that can have the following properties:

| Property     | Type    | Description                                         |
| ------------ | ------- | --------------------------------------------------- |
| adSlotId     | string  | The ad slot id for this companion ad, if any.       |
| clickthrough | string  | The clickthrough URL for this companion ad, if any. |
| height       | integer | The height of the creative.                         |
| resourceUri  | string  | The URI of the creative.                            |
| provider     | string  | The provider of the companion ad, if any.           |
| width        | integer | The width of the creative.                          |

#### RafProxyNode

The RAF proxy node has several fields that can be observed to consume data generated by the internal RAF library. This way, an application can access information traditionally available via the `getLibVersion`, `setRafTrackingCallback` and `setAdBufferRenderCallback` methods on RAF.

| Property           | Type       | Access Permission | Description                                                               |
| ------------------ | ---------- | ----------------- | ------------------------------------------------------------------------- |
| bufferRenderUpdate | assocarray | read              | An associative array with the properties `adUrl`, `eventType`, and `ctx`. |
| libVersion         | string     | read              | The string indicating the version of the RAF library.                     |
| trackingUpdate     | assocarray | read              | An associative array with the properties `adUrl`, `eventType`, and `ctx`. |

## Methods

| Method                                                                                       | Description                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| addEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string)    | Add a listener for the specified player event.                                                                                                                                     |
| addIntegration(integration as object)                                                        | Adds an Integration.                                                                                                                                                               |
| configure(configuration as THEOPlayerConfiguration)                                          | Configure the SDK, passing in the license (`{license: "MY_THEO_LICENSE"}`).                                                                                                        |
| destroy                                                                                      | Destroy the player.                                                                                                                                                                |
| getVideoNode                                                                                 | Returns the interior Roku video node.                                                                                                                                              |
| pause                                                                                        | Pause playback.                                                                                                                                                                    |
| play                                                                                         | Start playback.                                                                                                                                                                    |
| removeEventListener(eventType as string, listenerOwner as roSGNode, eventListener as string) | Remove the specified listener for the specified player event.                                                                                                                      |
| removeIntegration(integration as object)                                                     | Removes an Integration.                                                                                                                                                            |
| setCopyGuardManagementSystem(cgms as Integer)                                                | Sets Copy Guard Management System. Acceptable Values: `0` - No Copy Restriction,`1` - Copy No More,`2` - Copy Once Allowed,`3` - No Copying Permitted.                             |
| setDestinationRectangle(w as Integer, h as Integer, x as Integer, y as Integer)              | Sets width, height, x, y of player.                                                                                                                                                |
| setMaxVideoResolution(width as Integer, height as Integer)                                   | Sets maximum video resolution.                                                                                                                                                     |
| setPlayerFocus(focused as Boolean, focusReceiver (optional) as roSGNode)                     | Gives or removes the focus from the internal player. If passing `false`, you may pass an optional roSGNode to receive the focus. If not passed, the THEOplayer SDK receives focus. |

### Player Configuration

The PlayerConfiguration object is passed to the configure method. It is an associative array with the following properties:

| Property   | Type       | Description                                                                       |
| ---------- | ---------- | --------------------------------------------------------------------------------- |
| license    | string     | Your THEO license. Optional if `licenseUrl` is specified.                         |
| licenseUrl | string     | The URL from which to load your THEO license. Optional if `license` is specified. |
| theolive   | assocarray | The configuration for THEOlive. Optional.                                         |

#### THEOlive Configuration

| Property          | Type             | Description                                                                                                                                                 |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| discoveryUrl      | string           | Optional. The discovery URL for your THEOlive deployment. If present, it will be tried before `discoveryUrls`.                                              |
| discoveryUrls     | Array of strings | Array of discovery URLs for your THEOlive deployment. If `theoLive` config is omitted, the default URL is '<https://discovery.theo.live/v2/publications/>'. |
| externalSessionId | string           | A session ID to use for your THEOlive session. This can tie an application session to a THEOlens session.                                                   |

## THEOlive API

The THEOlive API exposes the following property.

| Property  | Type   | Description                                                                                                |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| authToken | string | Optional. The JWT to be included on THEOlive media requests in the Authorization header as a bearer token. |

## Network API

The Network API exposes the following methods.

| Method                                                 | Description                                                                                      |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| setHeader(headerName as string, headerValue as string) | Adds or overwrites a header for all media requests. Returns true if successful, false if not.    |
| removeHeader(headerName as string)                     | Sets the value of the named header to an empty string. Returns true if successful, false if not. |
| getHeaders() as object                                 | Returns a map of all headers currently configured through the network API.                       |

## Events

The event consists of:

* date (timestamp) of occurrence
* type (string) of the event
* extra data

There are several player events being emitted.

* `activequalitychanged`: Fired when the playing rendition changes, the extra data emitted is the rendition's quality
* `addedaudiotrack`: Fired when audio track has been added
* `addedtexttrack`: Fired when text track has been added
* `bitratechange`: Deprecated. Use `activequalitychanged` instead. Fired when the bitrate changes, the extra data emitted is the bitrate
* `canplay`: Fired when the player can resume playback of the media data, the extra data emitted is the currentTime
* `canplaythrough`: Fired when the player can resume playback of the media data and buffering is unlikely, the extra data emitted is the currentTime
* `destroy`: Fired when the the player is destroyed, there is no extra data emitted along
* `durationchange`: Fired when the duration changes, the extra data emitted is the duration
* `emptied`: Fired when the player's source is cleared, there is no extra data emitted along
* `ended`: Fired when playback has stopped because the end of the media resource was reached, the extra data emitted is the currentTime
* `error`: Fired when an error occurs, the extra data emitted is an associative array e.g.:
  ```brightscript
  {
      "error": "<string:error>",
      "errorObject": {
          "code": <integer:code>,
          "message": <string:message>
      }
  }
  ```
* `intenttofallback`: Fired when the player has encountered an error playing a THEOlive stream and is going to try to playback a different stream. It also includes data about the error that is triggering fallback.
* `loadeddata`: Fired when the player can render the media data at the current playback position for the first time, the extra data emitted is the currentTime
* `loadedmetadata`: Fired when the player determines the duration and dimensions of the media resource, the extra data emitted is the currentTime
* `pause`: Fired when the "paused" changes to true, the extra data emitted is the currentTime
* `play`: Fired when the "paused" changes to false, the extra data emitted is the currentTime
* `playing`: Fired when playback is ready to start after having been paused or delayed due to lack of media data, the extra data emitted is the currentTime
* `endpointloaded`: Fired when the player has loaded the data for a THEOlive source and is ready to begin loading the stream
* `distributionloadstart`: Fired when the player begins to load the data for a THEOlive source
* `distributionloaded`: Fired when a THEOlive distribution has been successfully loaded.
* `distributionoffline`: Fired when a THEOlive stream is not available for playback
* `seeked`: Fired when the "seeking" changes to false after the current playback position was changed, the extra data emitted is the currentTime
* `seeking`: Fired when "seeking" changes to true, and the player has started seeking to a new position, the extra data emitted is the currentTime
* `sourcechange`: Fired when the player's source changes, the extra data emitted is an associative array e.g.:
  ```brightscript
  {
      "source": {
          "sources": [
              {
                  "liveOffset": 4,
                  "nativeUiRendering": false,
                  "contentProtection": {
                      "drmParams": {
                          KeySystem: "widevine"
                          licenseServerURL: "https://example.com/license"
                      }
                  },
                  "src": "https://example.com/stream.mpd",
                  "type": "dash"
              }
          ]
      }
  }
  ```
* `timeupdate`: Fired when the current playback position changed as part of normal playback or in an especially interesting way, for example discontinuously, the extra data emitted is the currentTime

---

# Getting Started on Roku

This getting started guide gets you familiar with Roku and the Dolby OptiView Player Roku SDK. Upon completion of this guide, you'll have integrated the Player SDK in Roku's Hello World! sample project, configured a video, and used an event listener.

If you're looking for our Roku API reference, you can find them [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/roku.md).

Consider using the [quickstart guide](#quickstart) if you're looking for a recap because you already went through this article.

## Introduction

The THEOplayer Roku SDK is designed specifically for the Roku platform. It is a custom video component allowing your channel to embed the video player easily.

### Purpose

This guide is created to help you get started with including the THEOplayer Roku SDK inside a Roku channel. This article will show you how to include, load, and create an instance of the THEOplayer Roku SDK. It will also explain how to play a video, and how you can add an event listener.

### Prerequisites

To start this guide you need the following items:

1. A Roku account ([read more about Roku account](https://support.roku.com/en-gb/article/115004382968)) linked with a Roku device ([see how to activate and link a Roku device](https://support.roku.com/en-gb/article/235180868)).

2. A Roku device with development mode activated ([read more about how to enable roku developer mode](https://blog.roku.com/developer/developer-setup-guide)). It is worth mentioning that you need to enroll for a developer program in order to activate the development mode on a Roku device ([you can enroll for a developer program here](https://developer.roku.com/enrollment/standard)).

3. A television/screen which supports an HDMI input.

4. Development workstation with an IDE and a web browser (Firefox, Chrome, Safari etc.).

5. Make sure that the Roku device and workstation are on the same local network (you should be able to ping the Roku device from your workstation).

6. An internet connection.

7. A Roku development environment which is needed to create a sample Roku channel and sideload it to a Roku device ([How to setup a Roku development environment](https://developer.roku.com/en-gb/docs/developer-program/getting-started/developer-setup.md)).

## System requirements

Roku keeps all devices up-to-date by issuing automatic updates. We aim to support all the up to date Roku devices.

## Certification changes

There are certification updates that may affect THEOplayer and channels using THEOplayer. Updates regarding certification are announced two times a year. Every update is announced 6 months before the date of implementation.

After announcing changes, we may need to update the THEOplayer Roku SDK to fulfill these new certification criteria.

## Support Roku OS

Our main focus is to support the two latest versions of Roku OS. Support for older versions might be limited.

# Building your own channel using the THEOplayer SDK

In this section, we will go through the process of creating a Roku channel and using the THEOplayer Roku SDK.

## Starting point

First of all, we need to create a Roku channel. You can either [create a new Roku project in eclipse](https://www.youtube.com/watch?v=suQ0qxFs0jw) or [VS Code](https://rokucommunity.github.io/vscode-brightscript-language/index.html) or start from the [Roku “Hello world” channel example](https://github.com/rokudev/hello-world) (Here is some [extra documentation](https://developer.roku.com/en-gb/docs/developer-program/getting-started/hello-world.md) about the “hello world” example).

When you have created a Roku channel, you can copy the THEOplayer Roku SDK ("THEOplayerSDK.pkg") into the directory of your project. You can download the most recent THEOplayer SDK from <https://portal.theoplayer.com>.

## Project structure:

![Roku Project Structure](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAARkAAAGlCAIAAABBehVOAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAAEnQAABJ0Ad5mH3gAACH2SURBVHhe7Z3xryVXdaXnX4lFLEQsDxmEkkaR0agzjgUOaiABYUAOCcjqZKR2RklLo9c/mCayWzZu23QTt+0mpmMgiaMhCckfOJ9Zysp2Vd269d49995T9y3pU2nXrn32OfXeXu/Uu/1q93/7jd/8rRDC7kRLIbQhWgqhDdFSCG2IlkJoQ7QUQhuipRDaEC2F0IZoKYQ2REshtOEiWvrtz/7ea/ce/eTn/1G5++MPPvO7nx9EhnB5uIiWrjz1v1770U85zniW8OxXvvnOT/9FUsTgdBAwD/FvvP3zc0365P+4wjo144s3bw+utoJZXn79Xd9OnXR+3pdeuT+4Okg14Jvf+QunZezg6ibGs4QmfExLj3/q0/X0E5988rHHn6geQfnef+9DfxdnmNmsqAOSWAmcgq9WqCTqiaoa2BegltH1G2fkWZ5wvqwrNVJfK98ap399647sJcxPSlpLaE8KIe2m70sY8F9a+tJXv/XDe4+euvpFnfIg98rdh89/74YDzHItVbVUcC7fx2q5Ly/9MZN1uTzhfFlXauSOtTg/adVStRsSLS3nv7R07WvPP3j/l28++AVyQkh33nj43ge/+s4LfznemnbX0sw3nurxExFhlJGfA//P//0b27okGfDz+OatOxrFEQ95vEiOZ7fv6mc2x7qkmpyEINsPnMQzliE/ePVtr0ord7BntIdVSQBMxNXJr0CtUds2xqlwDr4yCvOX0TZHvhrcAouvQxzpWcYJdVUehtv2PYYZPvaMx9aEnF679+gHrz5ASJObErhMt1ILt8L3CWwrmG8n3zCXjguRU5z6Xk7aZFD1YzNEeTA0hVbr6bjKXC6OmtAQo8pjlG+BGK/NAYoB/PcffuirWk9Nji3daiBHwpTBtozJVHV2f2W4qmxc1Y0rie5OTt84ftmaZTIhAUpoFFw9YRPDzx4kpxkhAV/0HbXkIjB8F3EOMk9W5NhmrCtGtoujOmXbo4KrCTni1NS6Wgdy6uLD6UWCCm4cOVgG4GSjw6g1alvGplTjrwyR9niIszEEmwzyE687VcA44R89913foHG2sJWhluAL177x9W+/MHBWBt+GGTZpiW/Y4CM4SkHf4EHxgYtgk81YV5LsGmanbMEl1Y0jgalVN5OZPQR7nHAysuYUOLdqaTLV5FeGYIZUDzgbwdhkkN83pYBxwskpnC1sZUJLW+HLvaOWgHLhO+fvNKd8z1R8riThIthk1+KTrTwuKZYhJ79IaCxOxEwGJ7FHSbQ2ZVNmTolUAJkHt4bfPx24qn1Dfj+w6VRaIi1liqHlaakq3MlUzD7+ynBVSSqu/sEQ/LIVMJmQS4OEzha2cjQtAd9IR6p2cdbkcuq7zqkrQDYVtklLGFylCokkmz97YJQyKwOempAYXSLtODMoQNXmYFCqwXAWoFFeCVhjvk2OLEAZXLiTqcZfGYIHpQ+1+usQRzpg5ksNunEifVXDwyaOqaWDUcsr5KuxJy6ipcm/IZqEMIIHww8MP9QHv5tdZvg6sMnkq7EPLqKlVcBPX+nZj1WXHD+/6eEtNOdktRTCgYmWQmhDtBRCG6KlENoQLYXQhmgphDZESyG0IVoKoQ3RUghtiJZCaEO0FEIboqUQ2hAthdCGaCmENhxIS2mbHE6eA2lp/ApaXkoLJ8auWjpk2+S18GTpshIuDztp6ZBtk1dEtHQ52UlLh2ybDFSnWwspxi+iu1HOi6UfMrba6IA773Dp+o0zOf22tjNvinSzESfUjOMwvwoOLK+eOkk4SXZ9xjtY22Sc7l8nqFSQjSpkY6jBg2aUkyJ26dvphOAWdnZODseQB5gIJsPA+1IdEk6bBp89HKVtMvXKqSMxqGOOKnEFuKA5YuNxmEYpmMwaUp010jb+ulQtYBw2mBpt1/zhVGmgJThA22SVuE+PpaUaWS9Vu04tGMWtMZE94fRoo6WtUGE7aonSrM2EAS2BbIpVtst9k5bIr5rGnn/GG4uEgYPlTYaNtQSM9WrDSbIaLQHlWGMoWWpXHgxOidmqJSI9yhuFM9upSK2k2iSvkfNhiGewZi6FU2VNWtqdWu4htOVAWuqkbXK0FPbHgbTUCdFS2B+XS0sh7I9oKYQ2REshtCFaCqEN0VIIbYiWQmhDtBRCG6KlENoQLYXQhmgphDZESyG0oV8tpaVeWBdH09Inn/jMZPcvM/471PP+ZapecBq/gYdn02t5JB90lajUN6b0llQI5jha+sOvfPPHD/95smORoawXvvK0abPS64AD+aGTN9/++dntu/YsBwVaQtdvnJHfl0I4jpYo/Vffen9TAzCxXEubXh+UlqDuIdg3b925gJaUbdOWFcLRnvHm++lBKy2xgXDUHkIY2xQePePVKaQ3BXDUa+2ojktqEsZVYsZzcWlT1z7lnEw1Dgtr55ifPXzu839w791/orx45Btcglro88xridqlatXFgSOFy1FaMgyXhGxIIapyjo5X/wZiLM7B71eey7NPphqHYYdVc/r7EmUq8QxOFUNxK4l2jKolgiWYanuU5FRTAR78XhgQME515amnx2FOElbK6f++RPnK4NFOvyZZAN4lHLlQS44nA4z99sA4FVoah4W1cxwttf0cb6uWsLX/6Me/tcRRSiBGLfJmtIQA+J1HHgLGvfUEOZXcjFNhj8PC2jnaM96Sf19qqCUCqF0VtLXEJR7tyIAwkBCnhM3sSwz0pJKlssmjZRDm5zd5JlONw5QtrJdjfvYwD+W1o5ZCOCT9aqmTlnohLKRfLYWwLqKlENoQLYXQhmgphDZESyG0IVoKoQ3RUghtiJZCaEO0FEIboqUQ2hAthdCGaCmENhxIS2l2F06eA2npyn++FzTjmYfImc51IRydXbX0+Kc+XU8/8cknd2zekM0qrJSdtPSlr37rh/cePXX1izrlQe6Vuw+f/94NB5jlWsqLfWGl7KSla197/sH7v3zzwS+Q03xfod21hFPPhDKu3zhT8NVnrullb456D1ytHWoqjpqd49ntu+528tLHO9Q5TD2JFBPCQnZ9xmNrQk6v3Xv0g1cfIKTJTQlcpluxAAbgtJaIUcMGNKC6V/sE92AQXAVdqmqRTQbFE6C2EIrX2BDOS4PPHiSnGSGBinggm0mWaEkGTsQgUYG1wSXPhbPGgwRTW5cIxoIMRYZwLhpoCb5w7Rtf//YLA2el1vc8O2oJvz/u01VstwECa0l7kZwVhuQZL1yANlraCiV+GC2hAbSkq3hAWxCXlIT8epDTVY0dIL0NnCHMc2pakqFUVgsCUx88kvuzh/qYp0nx6xS/97EQFrIaLbXCkguhLQfSUifN7uoTYAhtOZCWjouf+vKhQtgfl0JLIRyAaCmENkRLIbQhWgqhDdFSCG2IlkJoQ7QUQhuipRDaEC2F0IZoKYQ29KulmT/h+9E7/+gmEyF0Qr9aulLerag89vgTN25+/613/iFyCl2xPi3BQjkxtnlLPb/1tL8XN7a+ibg1IByFVWoJJKc3/vZnB26mV98+3BPR0kpZk5aw77/3oV8WHAccgGgpbOKUtVQD6mvq8vilJmL0RjoFevPWHU6rs4KQNERJnBP8yDeYqL7Ga5uJNGpSlpPLIBUJlba2+NMlwtQwEHRp4PQaPDVJCCBM/rA7a33Gg+UBMPjFiSJ2HVNesjH0sqB+KXL9VXAqmLD7Dz9UTuefnGigJa/KMQPGy5BhkSAn2UIercoLqE4yMJwkGDg1NRlshyasQ0vP/cmf/9Fzf1avQg2YxAHUkKpKUFWceqDDKC/XaLUrToVRAxQ/mAg4xVltCQMwHFapU8tmbYx1fA0Ar79erU7bdWANCE1YgZY+87uff/3HH7z8+nuf+u+fnQyozooDag3B/rQ0HjXWkmy2DjYfpRpQk8gmeNziTzZ4/fVqddquC6gBoQkr0BKVwfP9ex/86uvffuGjj+/++vuAsbUaHEAt+nlMUFWuY/LLVhXaabtiLdWcTKEnq/FETk4Mz1QuZXkm1z9ehrYyjVUeOdUus2bG9jOek9smBkOaJEOe8drSu5bQz9t/9//06/Irdx/+1dkrP/nZv8ONm9//3Of/wOUyiWsImzJSEhWQqlOeWl6gsdWukMcidE5QKVenJgIMnTIRV+2poyqTy0Ae/khDnz1ULZHZt6OccnIc2CxeYfnsoTlda+n1+3//6lvv63s/5Gf//lE13HuUaqhSWQ4irM+NYXe61pJ/fm+CgL1qyT/FxeQ2siPsMHUK70jLuZiWuLULzBVm6FdLS9pT7rUx5VpYriU/KIKfVEMr+tVSCOsiWgqhDdFSCG2IlkJoQ7QUQhuipRDaEC2F0IZoKYQ2REshtCFaCqEN/Wop/fHCuuhXS5v+zCz98UKfrE9LcNr98WZg0vxNaresUktwwv3xZoiWemZNWsK+fwn6480QLfXMKWupBtR3vOWhKPVJBjF+R72H/nieRWvwUyVpWd5gCKfXb5wxl+MHTsc77cuvv6uX2+UPrVjrMx4sD4Bx2zoXGZUtG4N6JUzlaw1UcCqYsH30x2PqQaEzSjNqVbLr1frTQa/K2un1gFfLGnSbyhBasQ4tXar+eIRZHoOlzudHHmrhUJ2y60ACsi/tgxVo6bL1xwMWg5xY1dVnvlzvsUpCDHJu0lJdWLS0J1agJYqAp/zL0x9PuOIZrpXgIV7ZOCoVhjyyFemrtsnDCjUXp3nG2we9a+my9cerC9MCHF8/e7BaMEDxXpivVptsCkOi2Zf2QddaSn+8rVTZLISvmH/EhIZ0rSX//N4EAXutCf/IF+et2iV4uxCTm+EMF9ASUzBq4Ay706+W0h9vCQu1VH8w+Zk2tKVfLYWwLqKlENoQLYXQhmgphDZESyG0IVoKoQ3RUghtiJZCaEO0FEIboqUQ2tCvltIfL6yLfrW06c+Z0x8v9Mn6tARH7I834KWp/40cz8I/994auTxVODqr1BIcqz/eEpYLYGvk8lTh6KxJS9j3j90fbwnLBbA1cnmqcHROWUs1gCe9d3bujwfEaJRep/PrQ+QkM36OZ7fvSgD1hfPJt4wmZ5xMJXRH12+cKacuDZyeCEOevJR+GNb6jAfLA2Dctk5iACpSNoaaikgD4+ofzygtKd6VjQawcbqCxwPFeMbJVI6XR6vF1k1VJxkYThL8aYh3YNahpU7646nQAUMeaYmxGHZqLE5KXDsDTFZzncWjxqlkg5dar1an7XrLZMu+dABWoKWu+uMBRYkwVKkcqVo8FOtYS/PLgzqL7MlUsmGQU1er03YdGC0dhhVoiZrg53on/fGEM0tLFCunGLrkZzycM0mgziJ7MhW2JpLHV/2Mp8XIKRt/GuIdmN611FV/PAb6sU0FrRLHoFKpV+X3BwY13rNUJmecTGUtkccr19RychzYDFQYm1L2pQPQtZbSH29AlcpyLjYqnJeuteQf6psgYK8lwm5Qp9M+cGG8UQhtOOfiYqpgIm5k4AzN6VdL6Y83ZrmWiJl/vAzN6VdLIayLaCmENkRLIbQhWgqhDdFSCG2IlkJoQ7QUQhuipRDaEC2F0IZoKYQ29Kul9McL66JfLW3627P0xwt9sj4twcn0x5th5vZDn6xSS3Aa/fFmiJZWx5q0hH3/tPrjzdDt3YVNnLKWakB98Vsev+dHjN9RP3B/PJy6Wtcgz0dvDX/87pjr+o0zzVLjz9VhL+yPtT7jwfIA6LA/Xg0QpGKswshgWzCXPdiabrzmycUoQ9gr69DSqfbHY1QVDKPIJtur0iloLtmkQofMWNfpeevAGhD2ygq0dML98YAA5ESkVrW7liYXIzvslRVoiVLg5/pJ9scTROphjwwMkQwYqC0Lp5ZX14yhzBw9hezJxSgg7JXetXTC/fHqGjwXCeXxZw8DLemqPFDXaXtyMWHfdK2l9MeroB/p9lxcbFS4AF1ryT/UN0HAXrXkfUDsWJTsDzXbebeLC6iCDcqdkMO+6VdL6Y83YLmW/CNg8sPDsCf61VII6yJaCqEN0VIIbYiWQmhDtBRCG6KlENoQLYXQhmgphDZESyG0IVoKoQ39ain98cK66FdLVza8npT+eKFP1qclWN4fb1OGEJqzSi3Bkv540VI4JGvSEvb9i/b0CmHfXBYt+bVt8FtAGPK8/Pq76riwKVJwibCbt+7Uq9Xp94X8/jkeLr30n6+UhxNmrc94sDyA+nbvFE7VK686UYVkUJ2OVDbAJsw9FfTKanVylGw4ypCooqXLwDq0tHt/vPpCODbgdIlT8e4ENI70KQGEuQUKw4mvTtlXnnpa2RRWJwonzAq0tHt/vEmFVJ201dLVZ75cFxYtXRJWoCWqmV88WvXH49TPeO4rQrnPPOOB1FKvcvQz3kBL2IhHIsRmDdHSZaB3LTXvjwfYCpBKAQGARDKOtEIwSIiEuCTt1avVZtL7v26iRFg+e7gkdK2lg/XHq6qbocpmOYMHxXCqdK0l/WifwZ+P7wi1vmTruICWWJ4eFAf+cHr0q6V998erWmVTWqKQ5Vry0yP4kTKcNv1qKYR1ES2F0IZoKYQ2REshtCFaCqEN0VIIbYiWQmhDtBRCG6KlENoQLYXQhn61lP54YV30q6UrG/52O/3xQp+sT0vQVk4vnef/VN4a+eyv2z/cf+/Db/3p/57/Q1hSDf44ndO8nbFeVqklWNIfbyFtteSYrX9UPtZSWDVr0hI2P+/9ztI44GJES6EJp6wl6pgAfVxB4Sr++o0zefw0peqvwS5xv4YkD0eGs4AaU8HpeGnpXH3zOJUOMTwR8RKkbh8Px7Pbd/M02BtrfcaDrQGDH/yqRXmw/bqrK1hQuGiAS+P8RJIBTx0+wNm4imBU8Rw1L0cZEpVs47EYmkg2wxWvbPi5Gi31xjq0dLH+eLWaYRCPX5dcwRz5qS+wVb6gbaFGDuyK/czuZzzZV556mqteAGGcyhYeW5Nr7KBPmBcf+mEFWrpwfzxBzUkbg/iBlsCyGZQyglTRV3+1K/aPtbS1b57H1uQa+8fPfdfZIFrqkBVoSWK4QH88o6olkkcj1Sj24BmPWVTZNUx4olri1a7YP9YSNlelAWxyakbiZXgshjyyGaJ4XdUKo6Xe6F1Lu/THo/I0UL97KCHIqboEVbAKVMGqWnsc7Fof2BX7J7XknPWzB+JleCwGaGpdUhJG4SFDPnvokK611LY/HpHz2js6VUuTQjVbA8Lh6VpL3hY2QcARtTRY4bkWM6Yub14qbFA8oDa8kdCEfrXUvD9eLdau0O9C3I4f2ya1hFN3zZMechpcDUenXy2FsC6ipRDaEC2F0IZoKYQ2REshtCFaCqEN0VIIbYiWQmhDtBRCG6KlENrQr5bSHy+si361tOnP59IfL/TJ+rQE3fbHm1mzGAe8uOy/cA/9s0otQZ/98ebXDFsDwnpZk5aw7/fdH2/rklqtOXTIKWvJ7wUBGlD8XvvjDaaw8Jzno3eBP75mLmklHG/euqM1+B69qvpOe+iTtT7jwdYASrkWH5HUqDzY++iPh99TkJPhZMOwNhCMbVG15Jf8sJWEowyJSnbok3VoaS398eoUtpnFkTVAeBk2QGFXn7kmVctJkmipZ1agpRX1x6tT2K6RNUB4GTZAYc9+5bkaTBItI/TJCrREhSGGVfTHc2S1CcOQSplFz3hMrS5flhDHGqbFcNRV/FyVM/RJ71paV388TcFxYBOsPP7sYVJLeNgDCSNGoiJSa8hnD/3TtZYuQ3+8qiUZm9gaEI5L11rytrAJAo6opcEKz7UYwebjTxfmpULmyU8OQz/0q6WT74+nBz8/tk1qCY9vdvxIGbqiXy2FsC6ipRDaEC2F0IZoKYQ2REshtCFaCqEN0VIIbYiWQmhDtBRCG6KlENrQr5bSHy+si361tOnP59IfL/TJ+rQE3fbHm6H+SbjAzn+HfkqsUkvQZ3+8GcZaCifGmrSEfb/v/ngzREsnzylrifIlQB9XoAHF77U/3mBGPBx1ipDGz3h4GCLj5q07dSB49nFXvdAha33Gg60BFGWteCKRgTzY++iPN5iRgPsPP1QYl9z+zletJfcew9YvUcT7pwaXbIduWYeW1tIfbzAjAbYtUZ0Cdt2XBrN4ebD1TkMPrEBLK+qPJzyjp4DzaqnmX3in4bisQEsqzVX0xzNcIoD8/tQbj57xLCpLCMOPghz9jGdts7Y84/VP71paV388PIp36esHASAbSWhSS8yIhAiT3pSNKTQ2nz2sgq61dNr98aqWZAwCzNaA0ANda8nbwib8438JzbU0WOG5FgNsWYCxVSpsUIoMPdOvlk64P54eBa29SS3h5HlPt4mW6qXQJ/1qKYR1ES2F0IZoKYQ2REshtCFaCqEN0VIIbYiWQmhDtBRCG6KlENoQLYXQhmgphDYcSEuTf1x398cf7N5FKIROOJCWxn9X2s9fmobQhF219PinPl1PP/HJJx97/InqEWhm6wsUIptVWCk7aelLX/3WD+89cvNUHuReufvw+e/dcIBZrqXzvgUUQifspKVrX3v+wfu/fPPBL5ATQrrzxsP3PvjVd174y/HWtLuWnhy1nqtv+NjjF4Fsk42BZ7fv6vVvj/JEfrGcsJkX8kKYZ9dnPLYm5PTavUc/ePUBQprclGB3LVHx9ZU4JOF+I8SrEQpMaomcei/VkUoCNa1fdA3hAjT47EFymhES7K4lBMB+4lpHA7XuJYNNWvKHHANBAqPq7IOrISyngZbgC9e+8fVvvzBwVnbXklDpI4mLaUlhHjXpCeFitNHSVlppCbS3IJXxM54NnChEv//gtJbqKEG2rTOGsITVaImiHwTYA9gKQ0LysCmN96XJPB4CzhPCeVnfvhRCnxxIS0sadIlztekKoR8OpKUQTp5oKYQ2REshtCFaCqEN0VIIbYiWQmhDtBRCG6KlENoQLYXQhmgphDZESyG0oV8tzfwJ34/e+Uc3mQihE/rV0uBdCfPY40/cuPn9t975h8gpdMX6tAT7k9OLN29vfU392fL2bgimdy198cvP+cWn+mqT5PTG3/7s8M30oqUwySr3JbE1YE9ES2GSU9aSAq7fONOedvWZa5xic5QS/Ha6dzw8gMGTHgO1JQ6e+qSlm7fuaKxea5cT6kS+Gi4Da3rGMyp9BUgDk3CJSCkBhajXJCpi1KDELaGqJc8yaKmH7e5i2FwlRk6l5bj1l65wepz+vqSAWt8YKnouWaiWnLVkvVUbkE19xtPV6qxiC5eHE9+XZrSE3xuOrzbRkiAPS60Dw2lzefclql+PZ/Lo6oyW0AlqYRS4yZ6TYAy0BHXScPJc3n1JhhJi6OpCLZEWCTFQv4MRU7VEcF2nkoST55T3pRAOSbQUQhv61dKS9pRpTBn6oV8thbAuoqUQ2hAthdCGaCmENkRLIbQhWgqhDdFSCG2IlkJoQ7QUQhuipRDacCAtpdldOHkOpKX6d6jVTrO7cDIcQUuD09OW0+DGx3DJr/eGVXPkfUkcsdndvhnfbDhVjr8vbfKcBqd6X2FMF/vSJucAHoTe+em//KS8++2XzBmr98NfvHn75q07nOLE9uvieuFcs6hjngLsPLt9Vy+ck0fDPcpJNMvgtC5DCQFDHtIS5vvCqK/cE6bZOeot90HbvbAiVrMvcWnwewUVDLIpStkYkgTxVK2c1CXJqfvqdEI5JQNi1NRBAYy6+sw1ewYBgmyqe1/i1Gonre0KYQRrSbpxPO4Ehq2WLHVI6JzV7EsUqDQgqEJOHe/h1OJYFePC1SgFVydHSt/7hmTJRFUP9ZScjHU8sE5ySl1KOL6vungHeJGKIcBJwio4gpYokXcf/eu7f/9vf/7irccef2IcMIlFImo5goc7jICLaWlyGXjQD5dU6z698tTTnsVUGUwmnAyIltbOobX02c/9z1fuPsSAV996/3d+7/cHAR4ygFJzVzpBtYFsJCF7q5bQgGoU2894npoYbGUYUBPW07oMQX6SEIBNKm1iXoNXKDw7AeO2ew4L/XNoLQG1pcchFdkgwEPGUKN1oOpenlq7qlTXOrbrWLN4lEVVp8bwCn/tf9rxZK6TeiJ7fEeoSx5/9qA1/PFz39XHJ4Iwz04ABhLCr2dLrSesheN89jBma0ATDjPLxbDgB/6wFqKlXoiW1s6BtNRJs7toKeyPA2kphJMnWgqhDdFSCG2IlkJoQ7QUQhuipRDaEC2F0IZoKYQ2REshtCFaCqENB9JS+uOFk+dAWtr0h3DpjxdOhiNrCQ4sp5deuT947yivr4YmHFRLX/zyc5MvAh6lPx4SGrwPO8O5gsPl5Pj7ktga0JxoKbRlNVpSgFrbsaddfeYap9gc9c4PT26DHQ+Pe+U5DEkgDKjBz4467zmb4mXn1fEww9Ge8YzKVwGq40m4RKQ2BwpdZa3feaj1GslV2BQmbWBwVLb6Ep6c48U4OIRNrGxfUkCtbGuDSxaqrlpU1Xa8k2BY2PDrWT7qlwISWA0OYRNr2pccUCtb2sCvBl316nItOVuFbGxr8zEhmBPZl6h7N5TDo6sLtcTYQec940mjpbCVE9mXZCghhq4u1JJsr4cwZvE6FSxPPnsIM6xmXwqhc6KlENpwIC110h8vhP1xIC2FcPJESyG0IVoKoQ3RUghtiJZCaEO0FEIboqUQ2hAthdCGaCmENkRLIbThQFpKf7xw8hxIS5v+dDX98cLJcGQtwRI5qWFD3c30KlF9QwnwnN2+i8FEfgGpvnREsDPUgWNmFnwBmEuvaVXnN7/zF3L6lSrBzb78+rusub5V5VetZmBI/vfoI3JQLe3eH4/yqlU1o6WxEojE6VIjz0yBTma4MEz95ts/HwtGUwxuypKofox6p5NES8fl+PuSWFi7F9YSl/wSu1A147ensnA9C2GRzFULnXm5EWCKwVy+qXqzgxufJFo6LpdFS5O1iAe/gtV5D5TQGShNDF0iXqeMUgaClRaPYrhKjIazGD+L3rx1p0qXUcyoKXSqnIx1WF1ztUGyIacm1Vg5yYDBvLoRjophMZ4u7IOjPeMZPewpYOt3elBSLhSjq+QZPEwSqdqqyKlgD1Q/I4zBelzlXsPYAzWnZ5TTYVzFULtMTeFL1kN1ckokp9iiqgVbW67Gkra2ZNLtYxNsO+yDS70vqb4HwcpZncRYqzVetUuhE+8AYKI6fJxzPMXgkkbVee0UnlqnzEgwTn4rqz2VarY6XdgHq9+XapHNaIlLm35fGgQrp53MiKGqVckqBkNHD9FwMZlTBg9mEtsgBuefXf8rXZJncLMVlj2pJYQEWpX9sgfTheZcln0JGIhT9ccRW6kIQ8+qOezBMx75x2EE4AScnOIcPD55uE69TgbybOaENeajJA8/1PrtUaSx/sH7D8fBM57XydG3zAIGiwxtOdl9qU6kwgKC7fRATQ012OtxKo54dFVSrFPXzMR4uK86mBVKA4MYTeSlAvaMlhiLhJjO/4DGUZuVUmksR62Keet0oTkr25f2wQWmdk0P/AfDshn4Z7jAkHAuoqWLTM2OwZAj1uUFhMEGVTfS0JwDaann/njn0hLlSzBPUEeRvVmoJcJ4AtSXd/C4GJpzIC2FcPJESyG0IVoKoQ3RUghtiJZCaEO0FEIboqUQ2hAthdCGaCmENkRLIbQhWgqhBb/5W/8fqTLANob0B9oAAAAASUVORK5CYII=)

1. **Components**: Contains all your components ( ".brs" and ".xml" files ). This folder should contain all UI and logic elements.

2. **"Images"**: The folder that contains channel artworks like splash screens, icons, logos etc.

3. **"Source"**: Typically only contains the "Main.brs" file. Roku starts running the channel from this file.

4. **"Manifest"**: This file should contain all the necessary information about the channel, like name, version, URI to splash screen etc. ([read more about the manifest file](https://developer.roku.com/en-gb/docs/developer-program/getting-started/architecture/channel-manifest.md))

5. **"THEOplayer.pkg"**: This is the packaged THEOplayer SDK. This package does not have to be here if you wish to load the THEOplayer SDK via HTTPS. In this case you have to pass the link to the packaged THEOplayer SDK instead of the relative path while loading the component library.

### Include THEOplayer SDK

To include the THEOplayer SDK into the channel, follow these steps:

1. Load the THEOplayer SDK as a component library.

   To do this we have to add the following line into the `helloworld.xml` file, between the `<children>` tags.

   ```xml
   <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayer.pkg"/>
   ```

   It is worth mentioning that the "URI" field can also be an HTTPS link to the THEOplayer package. (In our case, we will add it to the: "pkg:\components\MainScene\MainScene.xml" file.)

2. Add the THEOplayerContainer group.

   We will need this group to append THEOplayer into our channel. In our case, we will add it to the `helloworld.xml` file, next to the `<ComponentLibrary>` node.

   ```xml
   <Group id="THEOplayerContainer"></Group>
   ```

3. Wait until THEOplayer SDK is loaded.

   We just want to be sure that THEOplayer is loaded correctly. We add the following code to our BrightScript `<script>`.

   ```brightscript
   function init()
     m.THEOsdk = m.top.findNode("THEOsdk")
     m.THEOsdk.observeField("loadStatus", "THEOsdkLoaded")
   end function

   function THEOsdkLoaded()
     ' this is the moment when THEOplayer is fully included on your channel
   end function
   ```

   It is worth mentioning that "m" works like the "this" keyword from other languages. "m" keyword points to the current component local namespace. So if you want to have access to variables across different functions inside the same component, use "m" to do so.

After these 3 steps, your `helloworld.xml` should resemble the following snippet:

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="HelloWorld" extends="Scene">
  <children>
    <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayer.pkg"/>
    <Group id="THEOplayerContainer"></Group>
  </children>
<script type="text/brightscript" >
<![CDATA[
  function init()
    m.THEOsdk = m.top.findNode("THEOsdk")
    m.THEOsdk.observeField("loadStatus", "THEOsdkLoaded")
  end function

  function THEOsdkLoaded()
    ' this is moment when theo player is fully included to Your channel
  end function
]]>
</script>
</component>
```

When you deploy this app to your local Roku device, it should still be an empty, gray channel.

### Create an instance of the THEOplayer SDK using BrightScript

In this simple example we will create an instance inside the `THEOsdkLoaded` function, but remember that once the component library is loaded, you can use it across the whole channel.

There is also no need to load this component again. (In our case we will add it to the "pkg:\components\MainScene\MainScene.brs" file.)

```brightscript
function THEOsdkLoaded()
  m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
  m.playerContainer = m.top.findNode("THEOPlayerContainer")
  m.playerContainer.appendChild(m.THEOplayer)
end function
```

When you deploy your project to your local Roku device, the channel should now be a plain black background. (It's now black because it's an empty video player container.)

Make sure your files resemble this:

* pkg:/source/main.brs:

  ```brightscript
  sub Main()
      print "in showChannelSGScreen"
      'Indicate this is a Roku SceneGraph application'
      screen = CreateObject("roSGScreen")
      m.port = CreateObject("roMessagePort")
      screen.setMessagePort(m.port)

      'Create a scene and load /components/helloworld.xml'
      scene = screen.CreateScene("HelloWorld")
      screen.show()

      while(true)
          msg = wait(0, m.port)
          msgType = type(msg)
          if msgType = "roSGScreenEvent"
              if msg.isScreenClosed() then return
          end if
      end while
  end sub
  ```

* pkg:/manifest file:

  ```brightscript
  ##   Channel Details
  title=Hello World
  major_version=1
  minor_version=0
  build_version=00001

  ##   Channel Assets
  ###  Main Menu Icons / Channel Poster Artwork
  #### Image sizes are FHD: 540x405px | HD: 290x218px | SD: 214x144px
  mm_icon_focus_fhd=pkg:/images/channel-poster_fhd.png
  mm_icon_focus_hd=pkg:/images/channel-poster_hd.png
  mm_icon_focus_sd=pkg:/images/channel-poster_sd.png

  ###  Splash Screen + Loading Screen Artwork
  #### Image sizes are FHD: 1920x1080px | HD: 1280x720px | SD: 720x480px
  splash_screen_fhd=pkg:/images/splash-screen_fhd.jpg
  splash_screen_hd=pkg:/images/splash-screen_hd.jpg
  splash_screen_sd=pkg:/images/splash-screen_sd.jpg

  splash_color=#000000
  splash_min_time=1
  ```

* pkg:/components/helloworld.xml:

  ```xml
  <?xml version="1.0" encoding="utf-8" ?>
  <component name="HelloWorld" extends="Scene">
    <children>
      <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayerSDK.pkg"/>
      <Group id="THEOplayerContainer"></Group>
    </children>
  <script type="text/brightscript" >
  <![CDATA[
    function Init()
      m.THEOsdk = m.top.findNode("THEOsdk")
      m.THEOsdk.observeField("loadStatus", "THEOsdkLoaded")
    end function

    function THEOsdkLoaded()
      m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
      m.playerContainer = m.top.findNode("THEOplayerContainer")
      m.playerContainer.appendChild(m.THEOplayer)
    end function
  ]]>
  </script>
  </component>
  ```

Great! You have included the THEOplayer SDK into your channel now! If you run this channel, you will only see a black screen because we did not set any source and we did not start the playback. Follow the next sections to start video playback.

### Create an instance of the THEOplayer SDK using XML

There is an alternative way to include the THEOplayer SDK. You can include the component library using only XML. In this approach, you want to make sure that the component library is fully loaded before including the component into the scene graph.

An example of this approach is demonstrated through our [basic-playback-app project on GitHub](https://github.com/THEOplayer/samples-roku-sdk/tree/master/basic-playback-app). In this project, `MainScene.xml` loads the SDK, and the instance is created through (for example) `<THEOsdk:THEOplayer id="VideoPlayerChromefull" controls="true" />` in `ChromefullView.xml`.

### Configure license

You need to configure your THEOplayer Roku SDK license value through the following snippet:

```brightscript
m.THEOplayer.callFunc("configure", {license: "your-license"})
```

Add these 3 lines after `m.playerContainer.appendChild(m.THEOplayer)`.

Note that you have to replace `your-license` with your actual license value as specified on the [THEOplayer Development Portal](https://portal.theoplayer.com/) for your THEOplayer Roku SDK.

![](/pr-932/assets/images/roku-portal-sdk-82cbb1f9e8d639efd2c8924109f29d73.png)

### Video playback example

To play videos using the THEOplayer SDK, we need to take a few steps:

1. Include the THEOplayer SDK and create an instance of it. (described in above section)

2. Set a player source. To accomplish this we will edit the `THEOsdkLoaded` function. (Added later in the "Using the THEOplayer SDK" section.)

   ```brightscript
   function THEOsdkLoaded()
     m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
     m.playerContainer = m.top.findNode("THEOplayerContainer")
     m.playerContainer.appendChild(m.THEOplayer)
     m.THEOplayer.callFunc("configure", {license: "your-license"})
     m.THEOplayer.source = {
       "sources": [
         {
           "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
           "type": "application/x-mpegURL"
         }
       ]
     }
   end function
   ```

3. Set focus to the THEOplayer SDK to make sure that remote controls will work properly.

   ```brightscript
   function THEOsdkLoaded()
     m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
     m.playerContainer = m.top.findNode("THEOplayerContainer")
     m.playerContainer.appendChild(m.THEOplayer)
     m.THEOplayer.callFunc("configure", {license: "your-license"})
     m.THEOplayer.source = {
       "sources": [
         {
           "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
           "type": "application/x-mpegURL"
         }
       ]
     }
     m.THEOplayer.setFocus(true)
   end function
   ```

4. Play a video with the "play" method.

   ```brightscript
   function THEOsdkLoaded()
     m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
     m.playerContainer = m.top.findNode("THEOplayerContainer")
     m.playerContainer.appendChild(m.THEOplayer)
     m.THEOplayer.callFunc("configure", {license: "your-license"})
     m.THEOplayer.source = {
       "sources": [
         {
           "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
           "type": "application/x-mpegURL"
         }
       ]
     }
     m.THEOplayer.setFocus(true)
     m.THEOplayer.callFunc("play")
   end function
   ```

After these 4 steps, your `helloworld.xml` file should resemble the following snippet:

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="HelloWorld" extends="Scene">
  <children>
    <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayerSDK.pkg"/>
    <Group id="THEOplayerContainer"></Group>
  </children>
<script type="text/brightscript" >
<![CDATA[
  function Init()
    m.THEOsdk = m.top.findNode("THEOsdk")
    m.THEOsdk.observeField("loadStatus", "THEOsdkLoaded")
  end function

  function THEOsdkLoaded()
    m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
    m.playerContainer = m.top.findNode("THEOplayerContainer")
    m.playerContainer.appendChild(m.THEOplayer)
    m.THEOplayer.callFunc("configure", {license: "your-license"})
    m.THEOplayer.source = {
      "sources": [
        {
          "src": "https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
          "type": "application/x-mpegURL"
        }
      ]
    }
    m.THEOplayer.setFocus(true)
    m.THEOplayer.callFunc("play")
  end function
]]>
</script>
</component>
```

Deploying this app should result in the start-up of your configured video, as demonstrated by the screenshot below.

![](/pr-932/assets/images/roku-loading-source-89d4166a78190aad5683764e487da9f3.jpg)

### Add a player event listener

Adding an event listener in the Roku THEOplayer SDK is straightforward. All you have to do is follow these steps:

1. Create Callback function

   This code will be executed when the event will be propagated. (In this example we will add the function to the `helloworld.xml` file.)

   ```brightscript
   function onPlaying(params)
     print("I am playing")
     print(params)
   end function
   ```

2. Add the callback function to the component interface. (In this example we will edit the `helloworld.xml` file.)

   ```xml
   <?xml version="1.0" encoding="utf-8" ?>
   <component name="HelloWorld" extends="Scene">
     <interface>
       <function name="onPlaying"/>
     </interface>
     <children>
       <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayerSDK.pkg"/>
       <Group id="THEOplayerContainer"></Group>
     </children>
   </component>
   ```

3. Set a listener and call the `addEventListener` method. (In this example we will edit the `helloworld.xml` file, and add a line inside the `THEOsdkLoaded` function.)

   ```brightscript
   m.THEOplayer.callFunc("addEventListener", "playing", m.top, "onPlaying")
   ```

4. Now You will be able to see the following output in the debug console. ([How to use the debug console in Roku.](https://developer.roku.com/en-gb/videos/courses/rsg/debugging.md))

   ```brightscript
   I am playing
   <Component: roAssociativeArray> =
   {
       currentTime: 0
       date: "2020-09-08T11:06:09Z"
       type: "playing"
   }
   ```

5. Check your code and make sure `pkg:/components/helloworld.xml` resembles the following snippet:

   ```xml
   <?xml version="1.0" encoding="utf-8" ?>
   <component name="HelloWorld" extends="Scene">
     <interface>
       <function name="onPlaying"/>
     </interface>
     <children>
       <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayerSDK.pkg"/>
       <Group id="THEOplayerContainer"></Group>
     </children>
   <script type="text/brightscript">
   <![CDATA[
     function Init()
       m.THEOsdk = m.top.findNode("THEOsdk")
       m.THEOsdk.observeField("loadStatus", "THEOsdkLoaded")
     end function

     function THEOsdkLoaded()
       m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
       m.playerContainer = m.top.findNode("THEOplayerContainer")
       m.playerContainer.appendChild(m.THEOplayer)
       m.THEOplayer.callFunc("configure", {license: "your-license"})
       m.THEOplayer.source = {
         "sources": [
           {
             "src": "https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
             "type": "application/x-mpegURL"
           }
         ]
       }
       m.THEOplayer.setFocus(true)
       m.THEOplayer.callFunc("addEventListener", "playing", m.top, "onPlaying")
       m.THEOplayer.callFunc("play")
     end function

     function onPlaying(params)
       print("I am playing")
       print(params)
     end function

   ]]>
   </script>
   </component>
   ```

### Remove a player event listener

In order to remove an event listener, call the line below:

```brightscript
 m.THEOplayer.callFunc("removeEventListener", "playing", m.top, "onPlaying")
```

You can put this line anywhere you want. Just make sure that `m.THEOplayer` is used in the proper context. For example, in `pkg:/components/helloworld.xml` you can do something like this:

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="HelloWorld" extends="Scene">
  <interface>
    <function name="onPlaying"/>
  </interface>
  <children>
    <ComponentLibrary id="THEOsdk" uri="pkg:/THEOplayerSDK.pkg"/>
    <Group id="THEOplayerContainer"></Group>
  </children>
<script type="text/brightscript">
<![CDATA[
  function Init()
    m.THEOsdk = m.top.findNode("THEOsdk")
    m.THEOsdk.observeField("loadStatus", "THEOsdkLoaded")
  end function

  function THEOsdkLoaded()
    m.THEOplayer = CreateObject("RoSGNode","THEOsdk:THEOplayer")
    m.playerContainer = m.top.findNode("THEOplayerContainer")
    m.playerContainer.appendChild(m.THEOplayer)
    m.THEOplayer.callFunc("configure", {license: "your-license"})
    m.THEOplayer.source = {
      "sources": [
        {
          "src": "https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
          "type": "application/x-mpegURL"
        }
      ]
    }
    m.THEOplayer.setFocus(true)
    m.THEOplayer.callFunc("addEventListener", "playing", m.top, "onPlaying")
    m.THEOplayer.callFunc("play")
  end function

  function onPlaying(params)
    print("I am playing")
    print(params)
    m.THEOplayer.callFunc("removeEventListener", "playing", m.top, "onPlaying")
  end function

]]>
</script>
</component>
```

In this example, the `onPlaying` callback will be executed only once, because we have called `removeEventListener` inside of the `onPlaying` function.

### Quickstart

Use this section if you are already familiar with setting up the THEOplayer Roku SDK.

1. Build a THEOplayer Roku SDK at <https://portal.theoplayer.com>.
2. Setup Roku's [`hello-world` sample project](https://github.com/rokudev/hello-world).
3. Add (and rename) your THEOplayer Roku SDK to the `hello-world` project.
4. Replace the code in `source/components/helloworld.xml` with the codeblock above.
5. Update the value of `license` in your updated `source/components/helloworld.xml` with your actual license value according to <https://portal.theoplayer.com>.
6. Confirm playback by deploying this project to your local Roku device.

## Next steps

Consider the following actions to improve your knowledge on the THEOplayer Roku SDK:

* Clone (or download) our sample Roku applications at <https://github.com/THEOplayer/samples-roku-sdk>. These applications provide an alternative perspective on using THEOplayer in Roku.
* Go through the [how-to guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides.md). We try to provide the "Roku implementation" in as many articles as we can. (e.g. ["How to programmatically enable or disable text tracks"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-programmatically-disable-text-tracks.md))

---

# Migrating to THEOplayer Roku SDK 10.x

This article will guide you through updating to THEOplayer Roku SDK version 10 (from version 9.x), and the changes needed in your code. If you are upgrading from a version before 9.x, please follow the [migration guide for 9.x](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v9/getting-started/sdks/roku/migrating-to-theoplayer-9) first.

## Update THEOplayer

Download the new pkg file from [the THEOplayer portal](https://portal.theoplayer.com). If you're including the pkg file when packaging your application, replace the previous pkg file with the new pkg file. If you're loading the pkg from the remote URL at runtime, change the URL in your ComponentLibrary node to point to the new SDK's URL.

```xml
<ComponentLibrary id="THEOsdk" uri="pkg:/components/THEOplayerSDK.pkg" />
```

## Update Connectors to the 10.x version

If you are using any of the connectors for Roku, update them to the 10.x version as well. Either download them from [the THEOplayer portal](https://portal.theoplayer.com) and add them to your application, or load them directly from a URL.

```xml
<ComponentLibrary id="THEOConvivaConnector" uri="pkg:/components/THEOConvivaConnector.pkg" />
<ComponentLibrary id="THEOComscoreConnector" uri="pkg:/components/THEOComscoreConnector.pkg" />
<ComponentLibrary id="THEOAEPConnector" uri="pkg:/components/THEOAEPConnector.pkg" />
```

## Replace or remove usages of deprecated APIs

* Removed `THEOplayer.network.getHeader()`. Use `THEOplayer.network.getHeaders()` instead.

---

# Playing ads with THEOplayer Roku SDK

This article will provide the steps needed to play video ads with your content using the THEOplayer Roku SDK. The THEOplayer Roku SDK currently only supports Client-side Ad Insertion (CSAI) for VOD assets and some Server-side Ad Insertion (SSAI) using Google Ad Manager or THEOads. It does not yet support Client-side Ad Stitching (CSAS), Server Guided Ad Insertion (SGAI) or live CSAI ads.

## First Steps

* Make sure you are using a version of the SDK that supports ads. CSAI is available for VOD content in v9.3 and higher of the SDK. SSAI with Google IMA is available starting in v10.3.
* Include the RAF advertising library in your application's manifest file by adding this line: `bs_libs_required=roku_ads_lib`
* To support Google DAI, include the Google IMA library as well by adding `googleima3` after the RAF ads library: `bs_libs_required=roku_ads_lib,googleima3`

## Client-side Ad Insertion

The THEOplayer Roku SDK supports CSAI by using the Roku Advertising Framework (RAF), which is provided by Roku. It supports VMAP and VAST ad tags. For more information about specific features of VAST or VMAP supported by RAF, please visit their [support page](https://developer.roku.com/docs/developer-program/advertising/roku-advertising-framework.md).

### Create your ad descriptions

Ads are added to your content by adding ad sources to your source descriptions that are set on the `source` property of the THEOplayer. Here is an example for VAST ad tags:

```brightscript
m.player.source = {
    "title": "My VOD Asset",
    "live": false,
    "sources": {
        "src": "https://example.com/my_vod_asset.m3u8",
        "type": "application/x-mpegurl"
    },
    "ads": [
        {
            integration: "csai",
            sources: "https://exampleadserver.com/preroll.xml",
            timeOffset: "start"
        },
        {
            integration: "csai",
            sources: "https://exampleadserver.com/midroll.xml",
            timeOffset: 30
        },
        {
            integration: "csai",
            sources: "https://exampleadserver.com/midroll2.xml",
            timeOffset: 190
        },
        {
            integration: "csai",
            sources: "https://exampleadserver.com/postroll.xml",
            timeOffset: "end"
        }
    ]
}
```

For VMAP ads, the timing is contained within the VMAP file itself, so the configuration is simpler:

```brightscript
m.player.source = {
    "title": "My VOD Asset",
    "live": false,
    "sources": {
        "src": "https://example.com/my_vod_asset.m3u8",
        "type": "application/x-mpegurl"
    },
    "ads": [
        {
            integration: "csai",
            sources: "https://exampleadserver.com/vmap.xml",
        }
    ]
}
```

Note that the `timeOffset` property must be omitted for VMAP ads.

You may also specify the timings for VAST ads either by using a timecode or by specifying the percent of the asset that should play before displaying the ad. Timecodes should be in the format `HH:MM:SS`.

```brightscript
m.player.source = {
    "title": "My VOD Asset",
    "live": false,
    "sources": {
        "src": "https://example.com/my_vod_asset.m3u8",
        "type": "application/x-mpegurl"
    },
    "ads": [
        {
            integration: "csai",
            sources: "https://exampleadserver.com/midroll.xml",
            timeOffset: "00:05:30"
        },
        {
            integration: "csai",
            sources: "https://exampleadserver.com/midroll2.xml",
            timeOffset: "25%"
        }
    ]
}
```

#### Mixing VAST and VMAP Ads

Mixing VAST and VMAP ads is supported to an extent. A VMAP tag may contain multiple ad breaks. VAST tags may not be scheduled in between any of the breaks in a single VMAP tag. So, for instance, if you have a VMAP tag that contains a preroll and a postroll, you could not schedule any VAST midrolls between those breaks. However, if the preroll and postroll were in separate VMAP tags, you could schedule a midroll in between them.

### Listen for ad events

To detect events emitted for the ads, you can call the `addEventListener` method on the Ads API. You can see the list of ad events on [the API reference page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/roku.md#ads-api). Note that the method used for the listener needs to be exposed through the interface of the node that owns the listener function.

```brightscript
adEvents = m.player.ads.events
m.player.ads.callFunc("addEventListener", adEvents.adbreakbegin, m.top, "onAdBreakBegin")
m.player.ads.callFunc("addEventListener", adEvents.adbreakend, m.top, "onAdBreakEnd")
```

To clean up, you can simply call `removeEventListener` the same way.

```brightscript
m.player.ads.callFunc("removeEventListener", adEvents.adbreakbegin, m.top, "onAdBreakBegin")
m.player.ads.callFunc("removeEventListener", adEvents.adbreakend, m.top, "onAdBreakEnd")
```

Also, if you just want to see whether ads are playing or not, observe the `playing` field on the Ads API. You can see the other fields available on [the API reference page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/roku.md#ads-api).

```brightscript
m.player.ads.observeField("playing", "onAdsPlayingChange")

sub onAdsPlayingChange( event as object )
    adsPlaying = event.getData()
end sub
```

### Monitoring RAF

The THEOplayer Roku SDK does not expose RAF directly. However, you can still get the data from RAF's callbacks for tracking, buffering, and library version. On the Ads API, there is the `rafProxy` node. This field exposes data from RAF on fields of its own. To substitute for the output from RAF's `setTrackingCallback` method, you could do the following:

```brightscript
m.player.ads.rafProxy.observeField("trackingUpdate", "onRafTrackingUpdate")

sub onRafTrackingUpdate(event as object)
    update = event.getData()
    m.myRafObserver.rafTrackingCallback(m.myRafObserver, update.eventType, update.ctx)
end sub
```

Similarly, you can listen for RAF's `setAdBufferRenderCallback` output by observing the `bufferRenderUpdate` field on the Ads API.

```brightscript
m.player.ads.rafProxy.observeField("bufferRenderUpdate", "onRafBufferUpdate")

sub onRafBufferUpdate(event as object)
    update = event.getData()
    m.myRafObserver.rafBufferingCallback(m.myRafObserver, update.eventType, update.ctx)
end sub
```

The `rafProxy` field also exposes the library version of RAF via its own `libVersion` field.

### Scheduling Ads at Runtime

If you need to add an ad break to your asset when the asset has already begun playing, you can use the `schedule` method on the Ads API. It takes an ad description as the parameter. It will return a true or false value, based on whether adding the ad appears to have succeeded. In some cases when adding VMAP, it may not be able to report accurately whether the ad break was added or not. In that case you can observe the `scheduledAdBreaks` property to see if the ad break was correctly added.

```brightscript
adDesc = {
    integration: "csai",
    sources: "https://exampleadserver.com/midroll.xml",
    timeOffset: "00:05:30"
}
success = m.player.ads.callFunc("schedule", adDesc)
```

There are some restrictions on what you can schedule:

1. You cannot schedule preroll ads via the `schedule` method.
2. You cannot schedule an ad at the same time as an already scheduled ad.
3. You cannot schedule a VMAP before any previously scheduled breaks, unless that previously scheduled break is a VAST postroll.
4. If you schedule a VMAP midroll after it would have already played, it will play immediately.
5. You cannot schedule a midroll in between ad breaks that are in the same VMAP tag.
6. You cannot schedule a midroll before a previously scheduled VMAP tag.

### Limitations

Currently the Ads API does not support:

* Playing VAST tags in the middle of breaks from a VMAP tag.
* Reporting the exact media file that is being played for a creative.

## Server-side Ad Insertion

The THEOplayer Roku SDK supports SSAI by using the Google IMA library, which is provided by Roku and can be added in your application's manifest file. It supports SSAI through two methods: Google-registered streams and THEOlive streams with THEOads.

### Google IMA Streams

To play a DAI stream that is registered with Google IMA, add an `ssai` config on the source description you pass to the THEOplayer. Set the `src` property of the `sources` object to an arbitrary, non-empty string and set the `type` to the MIME type for the manifest. Then fill in your Google DAI information in the `ssai` config, making sure to set the `integration` property of the `ssai` config to `"google-dai"`.

```brightscript
m.player.source = {
    "title": "Google DAI Stream",
    "sources": {
        "src": "ssai",
        "type": "application/x-mpegurl",
        "ssai": {
            integration: "google-dai",
            availabilityType: "live",
            assetKey: "<MY_ASSET_KEY>",
            networkCode: "<MY_NETWORK_CODE>",
            apiKey: "<MY_API_KEY>",
        },
    }
},
```

### THEOlive and THEOads

To play a THEOlive SSAI stream that is configured in THEOlive to use THEOads with Google IMA, add an `ssai` config on the source description you pass to the THEOplayer. Set the `src` property of the `sources` object to your THEOlive distribution ID and set the `type` to `"theolive"`. Then on the `ssai` config, set the `integration` property to `"theoads"`. You may additionally add ad tag parameters for Google IMA by setting the `adTagParameters` property of the `ssai` config to an associative array with the URL params as properties and values.

```brightscript
m.player.source = {
    "title": "THEOlive DAI Stream",
    "sources": {
        "src": "<MY_THEOLIVE_DISTRIBUTION_ID>",
        "type": "theolive",
        "ssai": {
            integration: "theoads",
            adTagParameters: {
                "iu": "<MY_IU_VALUE>"
            }
        }
    }
},
```

### Listening for Ad Events

With SSAI, the AdsAPI still will emit ad beacon events. You can add listeners for these ad events on the AdsAPI just like CSAI by following the instructions in the CSAI section. Unfortunately, monitoring RAF via the RAF proxy is not available for SSAI.

---

# Getting started

## Usage

1. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/roku/getting-started.md) to set up THEOplayer in your Roku app.
2. Add an OptiView Live source to your player's source.

### Add an OptiView Live source

After setting up your THEOplayer on your App, set its source to a `SourceDescription` containing a `THEOliveSource`. You'll need an OptiView Live channel ID:

```brightscript
m.THEOsdk.source = {
    "live": true,
    "sources": {
      "src": "your-channel-id",
      "type": "theolive"
    }
}
```

Please note that the playlist feature cannot be used with OptiView Live. On Roku the OptiView Live source falls back to the HLS stream.

### Configure OptiView Live

On the player configuration object, you may add extra configuration using the `theoLive` property on the player configuration. For instance, if you would like to provide an external ID to track the session, you may add it to the `theoLive` configuration:

```brightscript
playerConfiguration = {
  license: "<YOUR_LICENSE_HERE>",
  theoLive: {
    externalSessionId: "my-unique-id"
  }
}
m.player.callFunc("configure", playerConfiguration)
```

## More information

* [API references](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/api-reference/roku.md)
* [Migrating to OptiView Live v2](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/roku/theolive/migrating-to-v2.md)

---

# Token based security

OptiView Live offers the option to enable JWT token security on channel distribution level. This can be interesting if you only want valid users to access your stream. Read more about the feature and configuring it on your channels on the [token based security guide](https://docs-preview.optiview.dolby.com/pr-932/theolive/distribution/security/token-based-security.md).

This page will demonstrate how to configure the Roku Player SDK for playback of channels with token based security enabled.

## Setting up the Roku THEOplayer SDK for OptiView Live

Refer to the [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/roku/theolive/getting-started.md) for the prerequisite steps in getting the Roku SDK up and running for OptiView Live playback.

## Configuring THEOplayer to pass the token

The OptiView Live API provides a simple property to configure your token:

```brightscript
token = getToken() // Generate or request your token, for more information check the token based security guide linked above.
player.theolive.authToken = token
```

This will ensure the player includes your token in the authorization header on all subsequent requests it performs for playback of your OptiView Live channel.

## Dealing with token expiry and rotation

If your tokens are short-lived, you want to make sure to update the token being passed to the player and requests before it expires, to allow playback to continue beyond expiry. This can simply be done by updating the header on the player in the same way. For example, one could check on an interval that makes sense for your token lifespan whether the token is about to expire and update when necessary, for example:

Add a Timer to your SceneGraph component to check the token at an interval:

```brightscript
...
  <children>
    <Timer id="tokenTimer" repeat="true" duration="30" />
  </children>
...
```

And in your BrightScript code:

```brightscript
sub init()
    ...

    m.token = ""
    m.player = getPlayer()

    maybeUpdateToken()
    m.tokenTimer = m.top.findNode("tokenTimer")
    m.tokenTimer.observeField("fire", "maybeUpdateToken")
    m.tokenTimer.control = "start"
end sub

sub maybeUpdateToken()
    if m.token = "" or tokenWillExpireSoon(m.token) then
        m.token = getToken() ' Generate or request your token, for more information check the token based security guide linked above.
        m.player.theolive.authToken = m.token
    end if
end sub

function tokenWillExpireSoon(token as String) as Boolean
    parts = token.split(".")
    if parts.count() < 2 then return true

    payloadBase64 = parts[1]
    ba = CreateObject("roByteArray")
    ba.FromBase64String(payloadBase64)
    decodedJson = ParseJson(ba.ToAsciiString())
    if decodedJson = invalid then return true

    exp = decodedJson.exp
    if exp = invalid then return true
    now = Int(CreateObject("roDateTime").AsSeconds())

    return exp - now <= 60
end function
```

## Clearing the token

If the token isn't needed anymore, e.g. when switching to an unprotected channel or a non-OptiView Live source altogether, the header can be simply removed as follows:

```brightscript
player.theolive.authToken = ""
```

---

# Migrating to OptiView Live v2

If you are using OptiView Live v2 for your live streams, you will need to do some extra configuration to successfully play back your OptiView Live streams on Roku.

## Initial Setup

1. Follow [our Getting Started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/getting-started/sdks/roku/getting-started.md) to set up THEOplayer in your Roku app.
2. Add an OptiView Live source to your player's source.

### Configure OptiView Live for v2

OptiView Live v2 sources do not use the default discovery URL (<https://discovery.theo.live/v2/publications/>). In order to use v2, you will need to specify one or more discovery URLs. On the player configuration object, you may add the discovery URLs using the `theoLive` property on the player configuration.

```brightscript
playerConfiguration = {
  license: "<YOUR_LICENSE_HERE>",
  theoLive: {
    discoveryUrls: ["https://discovery.theo.live/v2/distributions/"]
  }
}
m.player.callFunc("configure", playerConfiguration)
```

---

# Connectors for THEOplayer Roku SDK

## [![](/pr-932/img/conviva.svg)![](/pr-932/img/conviva_dark.svg)Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/roku/conviva)

[Integrate with Conviva analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/roku/conviva)

## [Comscore](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/roku/comscore)

[Integrate with Comscore analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/roku/comscore)

## [Adobe Edge](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/roku/adobe-edge)

[Integrate with Adobe Edge analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/roku/adobe-edge)

## [![](/pr-932/assets/images/mux-1d56b7f17d515324f1547519db52c2ba.png)Mux](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/roku/mux)

[Integrate with Mux analytics.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/connectors/roku/mux)

---

# Getting started with the Conviva Connector for the Roku SDK

Here's how to get started integrating the Conviva Connector with the THEOplayer Roku SDK.

## Prerequisites

In order to set up the Conviva Connector in your Roku application, you'll need the following:

* Your Conviva customer key (available in your Conviva Pulse dashboard)
* An app with the THEOplayer SDK for Roku already integrated, see our [Getting Started guide](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/roku/getting-started/).
* Optionally for debug and testing, your Conviva Touchstone gateway URL, which should be in the format of `"https://MY_TOUCHSTONE_DOMAIN.ts-testonly.conviva.com/"`

## Integration

1. First you must download the THEO Conviva Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOConvivaConnector` and providing the URI for the THEOConvivaConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 1.5.0:

```xml
<ComponentLibrary id="THEOConvivaConnector" uri="https://cdn.myth.theoplayer.com/roku/{SDK_VERSION}/THEOConvivaConnector.pkg" />
```

2. Then in the BrightScript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field.

```brightscript
sub Init()
    THEOConvivaNode = m.top.findNode("THEOConvivaConnector")
    THEOConvivaNode.observeField("loadStatus", "onLibraryLoadStatusChanged")
end sub

sub onLibraryLoadStatusChanged(event as object)
    THEOConvivaNode = event.getROSGNode()

    if THEOConvivaNode = invalid
        return
    end if

    if THEOConvivaNode.loadStatus = "ready"
		' Success
    else if THEOConvivaNode.loadStatus = "failed"
		? "Failed to load component library, please check URL. "; THEOConvivaNode.uri
	end if
end sub
```

3. Add the THEOConvivaConnector component to the SceneGraph file where your THEOplayer is defined

```xml
<THEOsdk:THEOplayer id="THEOplayer" controls="true" />
<THEOConvivaConnector:THEOConvivaConnector id="THEOConvivaConnector" />
```

4. Then in the BrightScript file, configure the connector by calling the configure method, passing the player instance and your Conviva customer key.

```brightscript
m.player = m.top.findNode("THEOPlayer")
m.convivaConnector = m.top.findNode("THEOConvivaConnector")
m.convivaConnector.callFunc("configure", m.player, "MY_CUSTOMER_KEY")
```

NOTE: that if you want to debug first and use Conviva's Touchstone service to validate your integration, you can include the gateway URL and a debug parameter in the configure call: `m.convivaConnector.callFunc("configure", m.player, "MY_CUSTOMER_KEY", "MY_TOUCHSTONE_GATEWAY_URL", true)`

5. Next, when you start playing the asset, call the `startSession` method and pass it the content metadata for the asset you're playing:

```brightscript
m.player.source = sourceDescription
contentMetadata = {
    defaultReportingResource: "MyCDN",
    playerName: "My Player",
    assetName: "My Asset Name",
    encodedFramerate: 24
}
m.convivaConnector.callFunc("startSession", contentMetadata)
```

See the [API documentation](https://www.theoplayer.com/docs/theoplayer/connectors/roku/conviva/API-reference/) for more on how to structure the content metadata for Conviva.

6. If you desire to monitor for CDN changes, you can optionally add a configuration for that after starting the session. `m.convivaConnector.callFunc("monitorCdnChanges", { mycdn: ["my-cdn.net"], theo: ["cdn.theoplayer.com"] })`
7. If the content metadata needs to change, you can update it by calling `setContentInfo`. This method accepts partial content metadata: `m.convivaConnector.callFunc( "setContentInfo", {assetName: "New Program"})`
8. When the video has stopped playing because it ended or the user exited, end the Conviva session `m.convivaConnector.callFunc("endSession")`
9. If you are exiting the player screen altogether, and destroying the player, make sure to destroy the connector at the same time, but before calling destroy on the SDK:

```brightscript
m.convivaConnector.callFunc("destroy")
m.convivaConnector = invalid

m.player.callFunc("destroy")
m.player = invalid
```

---

# Conviva Connector API reference

The attributes, methods and events for the THEOConvivaConnector.

## Attributes

| Name | Type   | Default | Access Permission | Description         |
| ---- | ------ | ------- | ----------------- | ------------------- |
| id   | string |         | read, write       | The ID of this node |

## Methods

| Method                 | Params                                                                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| configure              | player: THEOplayer, customerKey: string, gatewayUrl: string (Optional), debug: boolean (Optional) | Configure the Conviva SDK for use. The `gatewayUrl` param is the URL for the Touchstone service for use in validating your Conviva integration. Omit this for production builds.                                                                                                                                                                                                                                |
| destroy                | none                                                                                              | Destroy the connector. It also ends the current session, if any.                                                                                                                                                                                                                                                                                                                                                |
| endSession             | none                                                                                              | End the current Conviva session, but do not destroy the connector.                                                                                                                                                                                                                                                                                                                                              |
| getContentInfo         | none                                                                                              | Returns the content metadata for the current session.                                                                                                                                                                                                                                                                                                                                                           |
| monitorCdnChanges      | mappings: CDNMonitoringConfig, defaultCdn: string (optional)                                      | Updates the CDN monitoring settings. If passed a CDN monitoring config (see below), it will begin monitoring the downloaded segments for changes in CDN. This will update the defaultReportingResource for the current session if a CDN change is detected If passed invalid as the first parameter, it will stop the monitoring and use any string passed as the second param as the defaultReportingResource. |
| reportPlaybackEvent    | eventType: string, eventDetail: AssociativeArray                                                  | Reports a playback event with the associated data to Conviva.                                                                                                                                                                                                                                                                                                                                                   |
| reportPlaybackFailed   | errorMessage: string                                                                              | Reports a playback failure to Conviva.                                                                                                                                                                                                                                                                                                                                                                          |
| setAdInfo              | adInfo: AssociativeArray                                                                          | Sets the supplied ad info to Conviva. adInfo should be in the form of ConvivaContentInfo                                                                                                                                                                                                                                                                                                                        |
| setContentInfo         | contentMetadata: AssociativeArray                                                                 | Sets or updates the content metadata for the current session. Partials are supported and will be merged with the existing content metadata. See below for the schema of content metadata.                                                                                                                                                                                                                       |
| startSession           | contentMetadata: AssociativeArray                                                                 | Starts a Conviva session with the supplied content metadata. See below for the schema of content metadata.                                                                                                                                                                                                                                                                                                      |
| stopAndStartNewSession | contentMetadata: AssociativeArray                                                                 | Stops the existing Conviva session and starts a new one with the supplied content metadata. See below for the schema of content metadata.                                                                                                                                                                                                                                                                       |

### DPI Methods

The THEO Conviva Connector now exposes methods for Conviva DPI (Digital Product Insights) integration that the application can use to report application level analytics. If you are using Conviva for both DPI and Video, call `configureDPI` first for application analytics, then call `configure` when you have access to the player. In depth documentation for the parameters passed to these methods is provided in the (Conviva DPI Integration guide)\[<https://pulse.conviva.com/learning-center/content/sensor_developer_center/sensor_integration/roku/roku_stream_sensor.htm#ConvivaDPISensorIntegrationforRoku>]:

| Method              | Params                                                                                       | Description                                                                                                                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| configureDPI        | appId: string, customerKey: string, gatewayUrl: string (Optional), debug: boolean (Optional) | Configure the Conviva SDK for use for Conviva DPI. The `gatewayUrl` param is the URL for the Touchstone service for use in validating your Conviva integration. Omit this for production builds. |
| setUserId           | userId: string                                                                               | Set the user ID for this DPI session.                                                                                                                                                            |
| setChannelInfo      | channelInfo: assocarray                                                                      | Set the channel load times for this DPI session.                                                                                                                                                 |
| trackCustomEvent    | eventName: string, eventData: assocarray                                                     | Report a custom DPI event to Conviva.                                                                                                                                                            |
| trackClick          | clickDetails: assocarray                                                                     | Report a click event.                                                                                                                                                                            |
| trackAppError       | error: assocarray                                                                            | Report an application error.                                                                                                                                                                     |
| trackNetworkRequest | requestDetails: assocarray                                                                   | Report the stats for a network request.                                                                                                                                                          |
| setCustomTags       | customTags: assocarray                                                                       | Add custom tags to this DPI session.                                                                                                                                                             |
| unsetCustomTags     | customTags: array of strings                                                                 | Remove custom tags from this DPI session.                                                                                                                                                        |

### CDN Monitoring Config

The configuration for CDN monitoring should be an AssociativeArray with keys that are the name of the CDN and values that are arrays of strings to search for in segment URLs.

```brightscript
cdnMappings = {
	akamai: ["akamaized.net"],
	theo: ["dev.theoads.live", "cdn.theoplayer.com"]
	level3: ["llnw.com"]
}
```

Passing a config as the only param will start CDN change monitoring with the provided configuration, or update the config if it is already started. `m.theoConvivaConnector.callFunc("monitorCDNChanges", cdnMappings)` However, if you want to stop CDN change monitoring, pass `invalid` as the first parameter, and the string you want to use for the defaultReportingResource as the second parameter. `m.theoConvivaConnector.callFunc("monitorCDNChanges", invalid, "theo")`

### Content Metadata

Content metadata should be an AssociativeArray following [Conviva's schema](https://pulse.conviva.com/learning-center/content/sensor_developer_center/sensor_integration/roku/roku_stream_sensor.htm#PredefinedVideoandContentMetadata). However, the THEOConviaConnector does provide a shortcut for c3 data. You may specify the c3 data by its full name:

```brightscript
contentMetadata = {
	customMetadata: {
		myCustomTag: "Value",
		"c3.cm.contentType": "DVR",
		"c3.cm.name": "CMS"
	}
}
```

However, we also support using an object notation:

```brightscript
contentMetadata = {
	customMetadata: {
		myCustomTag: "Value",
		c3: {
			cm: {
				contentType: "DVR",
				name: "CMS"
			}
		}
	}
}
```

---

# Getting started with the Comscore Connector for the Roku SDK

Here's how to get started integrating the Comscore Connector with the THEOplayer Roku SDK.

## Prerequisites

In order to set up the Comscore Connector in your Roku application, you'll need the following:

* Your Comscore publisher ID and publisher secret (available in your Comscore Direct dashboard under Mobile Apps > Get Tag).
* An app with the THEOplayer SDK for Roku already integrated, see our [Getting Started guide](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/roku/getting-started/).

## Integration

1. First you must download the THEO Comscore Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOComscoreConnector` and providing the URI for the THEOComscoreConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 1.5.0:

```xml
<ComponentLibrary id="THEOComscoreConnector" uri="https://cdn.myth.theoplayer.com/roku/{SDK_VERSION}/THEOComscoreConnector.pkg" />
```

2. Then in the BrightScript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field.

```brightscript
sub Init()
    THEOComscoreNode = m.top.findNode("THEOComscoreConnector")
    THEOComscoreNode.observeField("loadStatus", "onLibraryLoadStatusChanged")
end sub

sub onLibraryLoadStatusChanged(event as object)
    THEOComscoreNode = event.getROSGNode()

    if THEOComscoreNode = invalid
        return
    end if

    if THEOComscoreNode.loadStatus = "ready"
		' Success
    else if THEOComscoreNode.loadStatus = "failed"
		? "Failed to load component library, please check URL. "; THEOComscoreNode.uri
	end if
end sub
```

3. Add the THEOComscoreConnector component to the SceneGraph file where your THEOplayer is defined

```xml
<THEOsdk:THEOplayer id="THEOplayer" controls="true" />
<THEOComscoreConnector:THEOComscoreConnector id="THEOComscoreConnector" />
```

4. Then configure the connector by calling the configure method, passing the player instance and your Comscore customer key.

```brightscript
m.player = m.top.findNode("THEOplayer")
m.comscoreConnector = m.top.findNode("THEOComscoreConnector")
m.comscoreConnector.callFunc("configure", m.player, { publisherId: "MY_PUBLISHER_ID", publisherSecret: "MY_PUBLISHER_SECRET", applicationName: "MY_APPLICATION_NAME"})
```

5. Next, when you start playing the asset, call the `startSession` method and pass it the content metadata for the asset you're playing:

```brightscript
m.player.source = sourceDescription
contentMetadata = {
	adLoadFlag: false,
	assetId: "myAssetId",
	c3: "Arbitrary C3 value",
	c4: "*null",
	c6: "*null",
	clipLength: 600,
	completeEpisodeFlag: true,
	contentGenre: "Sports",
	digitalAirDate: "2025-03-04",
	episodeNumber: "59",
	episodeSeasonNumber: "5",
	episodeTitle: "The Game Last Night",
	programTitle: "The Sports Show",
	publisherBrandName: "Sports Publisher Network",
	stationTitle: "KXYZ",
	tvAirDate: "2025-03-04"
}
m.comscoreConnector.callFunc("startSession", contentMetadata)
```

See the [API documentation](https://www.theoplayer.com/docs/theoplayer/connectors/roku/comscore/API-reference/) for more on how to structure the content metadata for Comscore.

6. Comscore requests a call to their `tick` method when the main event loop executes. If you update a global field called `tccTick`, the THEOComscoreConnector will automatically observe that field and call `tick` for you. Otherwise, you can manually call the `sendTick` method on the THEOComscoreConnector.

```brightscript
m.global.addField("tccTick", "integer", false)
m.global.tccTick = 0

while true
    m.global.tccTick = m.global.tccTick + 1
    msg = wait(1000, m.port)
    msgType = type(msg)
    if msgType = "roSGScreenEvent"
        if msg.isScreenClosed() then return
    end if
end while
```

NOTE: the `wait` method is running for 1000ms here, making the `tccTick` field get updated every second. Setting it to 0ms will cause the `tccTick` field to not get updated regularly.

7. If the content metadata needs to change, you can update it by calling `update`. This method accepts partial content metadata: `m.comscoreConnector.callFunc( "update", contentMetadata)`
8. When the video has stopped playing because it ended or the user exited, end the Comscore session `m.comscoreConnector.callFunc("endSession")`
9. If you are exiting the player screen altogether, and destroying the player, make sure to destroy the connector at the same time, but before calling destroy on the SDK:

```brightscript
m.comscoreConnector.callFunc("destroy")
m.comscoreConnector = invalid

m.player.callFunc("destroy")
m.player = invalid
```

---

# Comscore Connector API Reference

The attributes, methods and events for the THEOComscoreConnector.

## Attributes

| Name         | Type             | Default              | Access Permission | Description                                  |
| ------------ | ---------------- | -------------------- | ----------------- | -------------------------------------------- |
| id           | string           |                      | read,write        | The id of the node.                          |
| MEDIA\_TYPES | associativeArray | Comscore Media Types | read              | Constant with the Comscore media type enums. |
| AD\_TYPES    | associativeArray | Comscore Ad Types    | read              | Constant with the Comscore ad type enums.    |

## Methods

| Method               | Params                                                                                                                                      | Description                                                                                                                                                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| configure            | player: THEOplayer, configuration: THEOConnectorConfiguration, metadata: (optional) THEOComscoreReadableMetadata or THEOComscoreTagMetadata | Add a player to monitor, configure the Comscore SDK, and also pass in optional metadata for your content.                                                                                                                                  |
| destroy              | none                                                                                                                                        | Destroy the connector. It also ends the current session, if any.                                                                                                                                                                           |
| endSession           | none                                                                                                                                        | End the current Comscore session, but do not destroy the connector.                                                                                                                                                                        |
| update               | metadata: THEOComscoreReadableMetadata or THEOComscoreTagMetadata                                                                           | Updates the content metadata for the current session.                                                                                                                                                                                      |
| sendTick             | none                                                                                                                                        | Sends a tick to Comscore. This is only needed if you do not implement the `tccTick` field in your main event loop.                                                                                                                         |
| startSession         | mediaType: string, metadata: (optional) THEOComscoreReadableMetadata or THEOComscoreTagMetadata                                             | Starts a Comscore streaming session with the specified media type, and optionally applies the content metadata. If not passing content metadata, you will need to add it separately with the `update` method before calling `startSession` |
| reportPlaybackEvent  | eventType: string, eventDetail: AssociativeArray                                                                                            | Reports a playback event with the associated data to Comscore.                                                                                                                                                                             |
| reportPlaybackFailed | errorMessage: string                                                                                                                        | Reports a playback failure to Comscore.                                                                                                                                                                                                    |
| setAdInfo            | adInfo: AssociativeArray                                                                                                                    | Sets the supplied ad info to Comscore. adInfo should be in the form of ComscoreContentInfo                                                                                                                                                 |
| setContentInfo       | contentMetadata: AssociativeArray                                                                                                           | Sets or updates the content metadata for the current session. Partials are supported and will be merged with the existing content metadata. See below for the schema of content metadata.                                                  |
| startSession         | contentMetadata: AssociativeArray                                                                                                           | Starts a Comscore session with the supplied content metadata. See below for the schema of content metadata.                                                                                                                                |

### Comscore Config

The configuration the Comscore connector is the THEOConnectorConfiguration interface.

```brightscript
configuration = {
	publisherId: "MY_PUBLISHER_ID",
	publisherSecret: "MY_PUBLISHER_SECRET",
	applicationName: "MY_APPLICATION_NAME"
}
```

The `applicationName` property is optional. If omitted, Comscore will automatically collect it from the manifest file.

To get your publisher ID and secret, log into your Comscore account. Go to the Direct dashboard, and switch to the Mobile App tab. Then click the Get Tag button, and a dialog should show with the ID and secret in it.

### Content Metadata

Content metadata should be an AssociativeArray following Comscore's schema for streaming tags. However, the THEOComscoreConnector also will accept a more human readable format. These are in the THEOComscoreReadableMetadata and THEOComscoreTagMetadata interfaces. NOTE: if you omit a string value, replace it with `"*null"`, which is the value requested by Comscore for empty fields.

#### THEOComscoreReadableMetadata

```brightscript
comscoreMetadata = {
	adLoadFlag: false,
	assetId: "myAssetId",
	c3: "Arbitrary C3 value",
	c4: "*null",
	c6: "*null",
	clipLength: 600,
	completeEpisodeFlag: true,
	contentGenre: "Sports",
	digitalAirDate: "2025-03-04",
	episodeNumber: "59",
	episodeSeasonNumber: "5",
	episodeTitle: "The Game Last Night",
	programTitle: "The Sports Show",
	publisherBrandName: "Sports Publisher Network",
	stationTitle: "KXYZ",
	tvAirDate: "2025-03-04"
}
```

#### THEOComscoreTagMetadata

NOTE: all values must be strings for this object, with Booleans being represented as `"0"` and `"1"`.

```brightscript
comscoreMetadata = {
	ns_st_ia: "0",
	ns_st_ci: c3.cm.id,
	c3: "Arbitrary C3 value",
	c4: "*null",
	c6: "*null",
	ns_st_cl: "600",
	ns_st_ce: "1",
	ns_st_cg: "Sports",
	ns_st_ddt: "2025-03-04",
	ns_st_en: "59",
	ns_st_sn: "5",
	ns_st_ep: "The Game Last Night",
	ns_st_pr: "The Sports Show",
	ns_st_pu: "Sports Publisher Network",
	ns_st_st: "KXYZ",
	ns_st_tdt: "2025-03-04"
}
```

### Sending Ticks

Comscore wants a tick to be sent to it on every run of the main event loop. You can do this manually by calling the `sendTick` method on the THEOComscoreConnector: `m.comscoreConnector.callFunc("sendTick")`

However, if you want to have the connector automatically send the tick for you, in your `main.brs` file, add an integer field to the global node called `tccTick`. Set it equal to 0 and then increment it on each run of your event loop. Note that the `wait` line will make it run every 1000 milliseconds.

```brightscript
m.global.addField("tccTick", "integer", false)
m.global.tccTick = 0

while true
	m.global.tccTick = m.global.tccTick + 1
	msg = wait(1000, m.port)
	msgType = type(msg)
	if msgType = "roSGScreenEvent"
		if msg.isScreenClosed() then return
	end if
end while
```

---

# Getting started with the Adobe Edge Connector for the Roku SDK

Here's how to get started integrating the Adobe Edge Connector with the THEOplayer Roku SDK.

## Prerequisites

In order to set up the Adobe Edge Connector in your Roku application, you'll need the following:

* Your Adobe Edge domain and config ID (also known as data stream ID)
* An app with the THEOplayer SDK for Roku already integrated, see our [Getting Started guide](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/roku/getting-started/).

## Integration

1. First you must download the THEO Adobe Edge Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOAEPConnector` and providing the URI for the THEOAEPConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 9.2.0:

```xml
<ComponentLibrary id="THEOAEPConnector" uri="https://cdn.myth.theoplayer.com/roku/{SDK_VERSION}/THEOAEPConnector.pkg" />
```

2. Then in the BrightScript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field.

```brightscript
sub Init()
    THEOAEPNode = m.top.findNode("THEOAEPConnector")
    THEOAEPNode.observeField("loadStatus", "onLibraryLoadStatusChanged")
end sub

sub onLibraryLoadStatusChanged(event as object)
    THEOAEPNode = event.getROSGNode()

    if THEOAEPNode = invalid
        return
    end if

    if THEOAEPNode.loadStatus = "ready"
		' Success
    else if THEOAEPNode.loadStatus = "failed"
		? "Failed to load component library, please check URL. "; THEOAEPNode.uri
	end if
end sub
```

3. Add the THEOAEPConnector component to the SceneGraph file where your THEOplayer is defined

```xml
<THEOsdk:THEOplayer id="THEOplayer" controls="true" />
<THEOAEPConnector:THEOAEPConnector id="THEOAEPConnector" />
```

4. Then in the BrightScript file, configure the connector by calling the configure method, passing the player instance and your Adobe Edge configuration.

```brightscript
m.player = m.top.findNode("THEOPlayer")
m.aepConnector = m.top.findNode("THEOAEPConnector")
aepConfig = {
    configId: "<MY_AEP_CONFIG_ID>",
    domainName: "<MY_EDGE_DOMAIN>",
    mediaChannel: "My Channel",
    mediaPlayerName: "My Player",
    mediaAppVersion: "1.0",
    logLevel: 3
}
m.aepConnector.callFunc("configure", m.player, aepConfig)
```

5. Next, when you start playing the asset, call the `startSession` method and pass it the session details for the asset you're playing. You may also include an optional session configuration:

```brightscript
m.player.source = sourceDescription

aepSessionConfig = {}
aepSessionConfig["config.channel"] = "My Channel"
aepSessionConfig["config.adpinginterval"] = 5
aepSessionConfig["config.mainpinginterval"] = 30

aepSessionDetails = {
    name: "my-asset-id",
    friendlyName: sourceDescription.title,
    contentType: "video",
    streamType: "vod",
    length: 300,
    customMetadata: {
        key1: "value1",
        key2: "value2",
    }
}
m.aepConnector.callFunc("startSession", aepSessionDetails, aepSessionConfig)
```

See the [API documentation](https://github.com/adobe/aepsdk-roku/blob/main/Documentation/api-reference.md) for more on how to structure the data for Adobe Edge.

6. When the video has stopped playing because it ended or the user exited, end the Adobe Edge session. `m.aepConnector.callFunc("endSession")`
7. If you are exiting the player screen altogether, and destroying the player, make sure to destroy the connector at the same time, but before calling destroy on the SDK:

```brightscript
m.aepConnector.callFunc("destroy")
m.aepConnector = invalid

m.player.callFunc("destroy")
m.player = invalid
```

---

# Adobe Edge Platform Connector API

The attributes, methods and events for the THEOAEPConnector.

## Attributes

| Name          | Type             | Default          | Access Permission | Description                              |
| ------------- | ---------------- | ---------------- | ----------------- | ---------------------------------------- |
| id            | string           |                  | read,write        | The id of the node.                      |
| ecid          | string           | invalid          | read              | User's Experience Cloud ID.              |
| MEDIA\_EVENTS | associativeArray | AEP Media Events | read              | Constant with the AEP media event enums. |

## Methods

| Method                 | Params                                                                       | Description                                                                                                                                                                               |
| ---------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| configure              | player: THEOplayer, configuration: THEOAEPConfiguration                      | Adds the THEOplayer instance to monitor, and applies a configuration to the AEP SDK.                                                                                                      |
| destroy                | none                                                                         | Destroy the connector. It also ends the current session, if any.                                                                                                                          |
| endSession             | none                                                                         | End the current AEP session, but do not destroy the connector.                                                                                                                            |
| getExperienceCloudId   | none                                                                         | Retrieves the ECID for the user. The ECID will be added to the `ecid` field on the connector once it has been retrieved.                                                                  |
| resetIdentities        | none                                                                         | Resets the identities used in the SDK for the user.                                                                                                                                       |
| sendMediaEvent         | eventXDM: AssociativeArray                                                   | Send a media event to AEP.                                                                                                                                                                |
| setContentInfo         | contentMetadata: AssociativeArray                                            | Sets or updates the content metadata for the current session. Partials are supported and will be merged with the existing content metadata. See below for the schema of content metadata. |
| setExperienceCloudId   | ecid: string                                                                 | Sets a pre-existing ECID for the user on the SDK.                                                                                                                                         |
| startSession           | sessionDetails: THEOAEPMediaSessionDetails, sessionConfig: (optional) object | Starts a AEP session with the supplied session details and optional config. See below for the schema of details and config.                                                               |
| stopAndStartNewSession | sessionDetails: THEOAEPMediaSessionDetails, sessionConfig: (optional) object | Stops the existing session if any. Starts a AEP session with the supplied session details and optional config. See below for the schema of details and config.                            |

### AEP Connector Config

The configuration the AEP connector is the THEOConnectorConfiguration interface.

```brightscript
configuration = {
	configId: "<MY_CONFIGURATION_ID>",
    domainName: "<MY_EDGE_DOMAIN>",
    mediaChannel: "My Channel",
    mediaPlayerName: "My Player",
    mediaAppVersion: "1.0.0"
    logLevel: 3
}
```

The `logLevel` property is optional. The accepted values are (VERBOSE: `0`, DEBUG: `1`, INFO: `2`, WARNING: `3`, ERROR: `4`).

### Session Details and Config

The session details and session config control the metadata for the session you're starting. See the [AEP SDK documentation](https://github.com/adobe/aepsdk-roku/blob/main/Documentation/api-reference.md#createMediaSession) for expected values. The `customMetadata` property is optional. Values on that object must be strings.

#### THEOAEPMediaSessionDetails

```brightscript
aepSessionDetails = {
	streamType: "vod"
    friendlyName: "My Asset",
    name: "my-media-id",
    length: 596,
    contentType: "video",
    customMetadata: {
		key1: "value1",
		key2: "value2"
	}
}
```

#### Session Config

The optional session config should follow the schema described in the [AEP SDK documentation](https://github.com/adobe/aepsdk-roku/blob/main/Documentation/api-reference.md#createMediaSession).

```brightscript
aepSessionConfig = {}
aepSessionConfig["config.channel"] = "My Channel"
aepSessionConfig["config.adpinginterval"] = 5
aepSessionConfig["config.mainpinginterval"] = 30
```

### Getting the Experience Cloud ID

To get an ECID for a user, you'll need to observe the `ecid` field on the connector, and then call `getExperienceCloudId` on the connector. The field will update with the ECID when it is available and trigger your observer.

```brightscript
m.aepConnector.observeField("ecid", "onEcidChange")

sub onEcidChange( event as object )
	m.myEcid = event.getData()
end sub

m.aepConnector.callFunc("getExperienceCloudId")
```

### Reusing an existing AEP SDK library

The AEP SDK allows you to reuse instances of the SDK in case you're already using the AEP SDK in your application. This is done by adding a Task node to the scene. The THEO AEP Connector can reuse this Task node. In the MainScene.brs:

```brightscript
m.aepSDK = AdobeAEPSDKInit()
m.top.appendChild(m.aepSDK.getTaskNode())
```

As long as the task node is on the Scene before the connector is configured, the THEO AEP connector can pick up the AEP Task node and reuse it.

### Supported media events

The THEO AEP Connector will automatically detect most media events and send them to AEP for you, including player commands such as play or pause and events like bitrate change. It will not send media events related to chapters in this version:

* `media.chapterStart`
* `media.chapterComplete`
* `media.chapterSkip`

For these you may use the `sendMediaEvent` method and construct your own XDM payload:

```brightscript
chapterStartXDM = {
  "xdm": {
    "eventType": m.aepConnector.MEDIA_EVENTS.CHAPTER_START
    "mediaCollection": {
      "playhead": m.theoPlayer.currentTime,
      "chapterDetails": {
        "friendlyName": "My Chapter",
        "index": 1,
        "length": 300,
        "offset": 0
      }
    }
  }
}

m.aepConnector.callFunc("sendMediaEvent", chapterStartXDM)
```

---

# Getting started with the Mux Connector for the Roku SDK

Here's how to get started integrating the Mux Connector with the THEOplayer Roku SDK.

## Prerequisites

In order to set up the Mux Connector in your Roku application, you'll need the following:

* Your Mux environment key
* An app with the THEOplayer SDK for Roku already integrated, see our [Getting Started guide](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/roku/getting-started/).

## Integration

1. First you must download the THEO Mux Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOMuxConnector` and providing the URI for the THEOMuxConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 10.9.0:

```xml
<ComponentLibrary id="THEOMuxConnector" uri="https://cdn.myth.theoplayer.com/roku/{SDK_VERSION}/THEOMuxConnector.pkg" />
```

2. Then in the BrightScript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field.

```brightscript
sub Init()
    THEOMuxNode = m.top.findNode("THEOMuxConnector")
    THEOMuxNode.observeField("loadStatus", "onLibraryLoadStatusChanged")
end sub

sub onLibraryLoadStatusChanged(event as object)
    THEOMuxNode = event.getROSGNode()

    if THEOMuxNode = invalid
        return
    end if

    if THEOMuxNode.loadStatus = "ready"
		' Success
    else if THEOMuxNode.loadStatus = "failed"
		? "Failed to load component library, please check URL. "; THEOMuxNode.uri
	end if
end sub
```

3. Add the THEOMuxConnector component to the SceneGraph file where your THEOplayer is defined.

```xml
<THEOsdk:THEOplayer id="THEOplayer" controls="true" />
<THEOMuxConnector:THEOMuxConnector id="THEOMuxConnector" />
```

4. Then in the BrightScript file, configure the connector by calling the configure method, passing the player instance and your Mux configuration.

```brightscript
m.player = m.top.findNode("THEOPlayer")
m.muxConnector = m.top.findNode("THEOMuxConnector")
muxConfig = {
    env_key: "<MY_MUX_ENV_KEY>",
}
m.muxConnector.callFunc("configure", m.player, muxConfig)
```

5. Next, when you start playing the asset, call the `startSession` method and pass it the metadata for the asset you're playing:

```brightscript
m.player.source = sourceDescription

muxContentMetadata = {
    video_id: "<MY_VIDEO_ID>",
    video_title: "<MY_VIDEO_TITLE>"
}

m.muxConnector.callFunc("startSession", muxContentMetadata)
```

There are more properties available to add to the metadata, but `video_id` and `video_title` are required. See [Mux's schema for streaming metadata](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata#optional-configurable-metadata) for more properties that are available for Mux.

6. If you are using the THEOplayer in a size other than fullscreen, before you start the session, you can set the presentation mode to reflect the different size. This is also referred to as the playback mode.

```brightscript
m.muxConnector.callFunc("setPresentation", m.muxConnector.PRESENTATION_MODES.INLINE)
m.muxConnector.callFunc("startSession", muxContentMetadata)
```

The `setPresentation` method can also be called mid-session if the presentation mode changes during a session. The available presentation modes are `FULLSCREEN`, `INLINE`, `MINI`, and `PIP`.

7. If you desire to monitor for CDN changes, you can optionally add a configuration for that to start monitoring. `m.muxConnector.callFunc("monitorCdnChanges", { mycdn: ["my-cdn.net"], theo: ["cdn.theoplayer.com"] })`

8. When the video has stopped playing because it ended or the user exited, end the Mux session. `m.muxConnector.callFunc("endSession")`

9. If you are exiting the player screen altogether, and destroying the player, make sure to destroy the connector at the same time, but before calling destroy on the player:

```brightscript
m.muxConnector.callFunc("destroy")
m.muxConnector = invalid

m.player.callFunc("destroy")
m.player = invalid
```

---

# Mux Connector API

The attributes, methods and events for the THEOMuxConnector.

## Attributes

| Name                | Type             | Default                | Access Permission | Description                                    |
| ------------------- | ---------------- | ---------------------- | ----------------- | ---------------------------------------------- |
| id                  | string           |                        | read,write        | The id of the node.                            |
| CONTENT\_TYPES      | AssociativeArray | Mux Content Types      | read              | Constant with the Mux content types enums.     |
| PRESENTATION\_MODES | AssociativeArray | Mux Presentation Modes | read              | Constant with the Mux presentation mode enums. |

## Methods

| Method            | Params                                                                                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| configure         | player: THEOplayer, configuration: THEOMuxConfiguration, metadata: (optional) AssociativeArray                                   | Add a player to monitor, configure the Mux SDK, and also pass in optional metadata for your content.                                                                                                                                                                                                                                                                                                            |
| destroy           | none                                                                                                                             | Destroy the connector. It also ends the current session, if any.                                                                                                                                                                                                                                                                                                                                                |
| endSession        | none                                                                                                                             | End the current Mux session, but do not destroy the connector.                                                                                                                                                                                                                                                                                                                                                  |
| monitorCdnChanges | mappings: CDNMonitoringConfig, defaultCdn: string (optional)                                                                     | Updates the CDN monitoring settings. If passed a CDN monitoring config (see below), it will begin monitoring the downloaded segments for changes in CDN. This will update the defaultReportingResource for the current session if a CDN change is detected If passed invalid as the first parameter, it will stop the monitoring and use any string passed as the second param as the defaultReportingResource. |
| notifyError       | code: integer, message: string, context: string (optional), severity: string (optional), isBusinessException: boolean (optional) | Report an error to Mux. Note that most errors should be automatically reported. Severity defaults to "fatal".                                                                                                                                                                                                                                                                                                   |
| setPresentation   | presentationMode: MuxPresentationModes, data: (optional) AssociativeArray                                                        | Change the reported presentation mode (also called playback mode) for the player. Can also take optional arbitrary data about the mode.                                                                                                                                                                                                                                                                         |
| startSession      | metadata: (optional) THEOMuxMetadata                                                                                             | Starts a Mux streaming session with the specified media type, and optionally applies the content metadata. See below for the schema of content. If not passing content metadata, you will need to add it separately with the `update` method before calling `startSession`                                                                                                                                      |

### Mux Config

The configuration the Mux connector is the THEOMuxConfiguration interface. All properties except for `env_key` are optional.

```brightscript
configuration = {
  env_key: "<MY_MUX_ENV_KEY>",
  viewer_user_id: "<END_USER_ID>",
  mux_base_url: "<CUSTOM_MUX_BASE_URL>"
}
```

In order to get debug output from Mux in your console, you need to add the settings to your application's manifest file.

```text
mux_debug_events=partial
mux_debug_beacons=partial
```

The accepted values for the debug properties are `full`, `partial`, and `none`, defaulting to `none`.

### CDN Monitoring Config

The configuration for CDN monitoring should be an AssociativeArray with keys that are the name of the CDN and values that are arrays of strings to search for in segment URLs.

```brightscript
cdnMappings = {
	akamai: ["akamaized.net"],
	theo: ["dev.theoads.live", "cdn.theoplayer.com"]
	level3: ["llnw.com"]
}
```

Passing a config as the only param will start CDN change monitoring with the provided configuration, or update the config if it is already started. `m.muxConnector.callFunc("monitorCDNChanges", cdnMappings)` However, if you want to stop CDN change monitoring, pass `invalid` as the first parameter, and the string you want to use for the defaultReportingResource as the second parameter. `m.muxConnector.callFunc("monitorCDNChanges", invalid, "theo")`

### Content Metadata

Content metadata should be an AssociativeArray following [Mux's schema for streaming tags](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata#optional-configurable-metadata). All properties on it are optional, except for `video_id` and `video_title`.

For content type metadata values, there is an enum property on the THEOMuxConnector named `CONTENT_TYPES`. Its values are SHORT, MOVIE, CLIP, EPISODE, TRAILER, and EVENT. For example: `metadata.video_content_type = m.muxConnector.CONTENT_TYPES.MOVIE`.

### Presentation Modes

The THEOMuxConnector supports reporting changes in the presentation mode (also called playback mode) your application uses the player in, such as fullscreen or inline. The `PRESENTATION_MODES` enum property on the THEOMuxConnector holds the possible values (FULLSCREEN, INLINE, MINI, and PIP). For example, if your application changes the THEO player so it is in a list row component, you could call:

```brightscript
m.muxConnector.callFunc("setPresentation", m.muxConnector.PRESENTATION_MODES.INLINE)
```

There is also an optional `data` parameter for that method that can be an arbitrary associative array, as long as it can be converted to JSON.

```brightscript
presentationModeData = { reason: "Viewed Asset", timestamp: 1767735434 }
m.muxConnector.callFunc("setPresentation", m.muxConnector.PRESENTATION_MODES.FULLSCREEN, presentationModeData)
```

---

# Frequently asked questions (FAQ)

In this section we will list all the frequently asked questions we received over the years.

For our customers with a support plan package, if you have additional questions or can't find your answer here please contact our [Service Desk](https://opentelly.atlassian.net/servicedesk/customer/portal/1) for further support.

## Questions

* [How to combat autoplay policies](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-combat-autoplay-policies.md)
* [Why does fullscreen not behave as expected on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-does-fullscreen-not-behave-as-expected-on-ios.md)
* [Why does the Network API not work on iOS devices](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-does-network-api-not-work-on-ios-devices.md)
* [Why does Chromecast not work on iOS Chrome?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-does-chromecast-not-work-on-ios-chrome.md)
* [Why can't I select another video quality on iOS/tvOS?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-cant-we-select-other-video-quality-on-ios-tvos.md)
* [Is YouTube supported](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/is-youtube-supported.md)
* [Why does the player load only one audio track (even though there are several in the manifest)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-does-player-load-only-one-audio-track.md)
* [Is it possible to see 360 degrees photo with THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/is-it-possible-to-see-360-picture.md)
* [Why the Visibility API does not work through an iframe on Safari and IE11](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-visibilty-api-doesnt-work-in-iframe-on-safari-and-ie11.md)
* [What is an impression](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-is-an-impression.md)
* [How to know whether a live stream is playing](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-know-when-livestream-is-playing.md)
* [Why did my subtitles stop working](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-did-subtitles-stop-working.md)
* [How does Media Engagement Index (MEI) affect Autoplay on Chrome](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-does-mei-affect-autoplay-on-chrome.md)
* [Why are not all response headers exposed](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-are-not-all-response-headers-exposed.md)
* [Why does the currentTime seem off in my livestream & what can I do about it](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-does-currentime-seem-to-be-off.md)
* [How to remove CORS restrictions from a reproduction stream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-remove-cors-restrictions.md)
* [Which network calls (or requests) does THEOplayer do](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/which-network-calls-does-THEOplayer-do.md)
* [Why does the playback not work when using the Chrome iPhone/iPad simulator](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-does-playback-not-work-using-chrome-iphone-simulator.md)
* [How to remove unwanted CC track in iOS or Safari](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-remove-unwanted-cc-track-ios-safari.md)
* [MediaTek limitations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/mediatek-limitations.md)
* [How to use ProGuard with THEOplayer Android SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-use-proguard-with-android-sdk.md)
* [Self-hosting and versioning of THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/self-hosting-theoplayer.md)
* [Does THEOplayer support EXT-X-DATERANGE](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/does-theoplayer-support-ext-x-daterange.md)
* [Can clipping be used on a playlist](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/can-clipping-be-used-in-a-playlist.md)
* [Can timeline thumbnails be made available before playback start](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/can-timeline-thumbnails-be-made-available-before-playback-start.md)
* [What are the benefits of preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-are-the-benefits-of-preloading.md)
* [What are the player seeking and seeked events and when are they fired](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-are-the-player-seeking-and-seeked-events.md)
* [Can we use HLS or DASH ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/can-we-use-hls-or-dash-ads.md)
* [How to change text in THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-change-text-in-theoplayer.md)
* [Change text when AirPlaying](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-change-text-when-airplaying.md)
* [ITP2.1 problems using THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/itp21-problems-using-theoplayer.md)
* [Removing context menu 'Powered by THEOplayer...'](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/removing-context-menu-powered-by.md)
* [What aspects of THEOplayer do we need to take into account to deploy a proper Content Security Policy (CSP)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/whats-aspects-to-take-into-account-when-developing-csp.md)
* [How can we avoid that the player keeps looking for chunks/segments if they are not found](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-avoid-loading-chuncks-when-not-found.md)
* [Can we show a custom message on 403 on mp4](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/can-we-show-custom-message-on-403-on-mp4.md)
* [Can we prevent UpNext feature from redirecting](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/prevent-up-next-from-redirecting.md)
* [Is it possible to preload VOD content while the pre-roll is playing](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/preload-vod-content-when-pre-roll-is-playing.md)
* [Why is my video not playing automatically](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-is-video-not-playing-automatically.md)
* [Is it possible to have multiple player instances play at the same time](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/possible-to-have-multiple-player-instances-at-same-time.md)
* [Is it a problem if the viewer pauses a live stream for longer than the DVR window](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/is-it-a-problem-if-viewer-pauses-live-stream-longer-than-dvr-window.md)
* [THEOplayer Features & Modules](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/theoplayer-features-modules.md)
* [Chromecast on my webplayer does not work any longer despite no change in my implementation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/chromecast-on-weblayer-does-not-longer-work.md)
* [How to track network errors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-track-network-errors.md)
* [How to use the CDN fallback/backup stream feature](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/cdn-fallback-backup-stream-feature.md)
* [How to apply accurate buffering strategy](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-apply-accurate-buffering-strategy.md)
* [How can I distribute 4K content?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-can-i-distribute-4k-content.md)
* [What is the collaboration between Azure Media Services and THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-is-the-collaboration-between-azure-media-services-and-THEOplayer.md)
* [Is Portrait mode supported](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/is-portrait-mode-supported.md)
* [How to prevent screen recording](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-prevent-screen-recording.md)
* [The provided video source is incompatible with the license for this player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/the-provided-video-source-is-incompatible-with-the-license-for-this-player.md)
* [Page and Source domains](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/page-and-source-domains.md)
* [Why is my PlayReady stream not working in Chromium Edge?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/Why-is-my-Playready-stream-not-working-in-Chromium-Edge.md)
* [Which subtitle and CC formats are supported on native Safari](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/which-subtitle-and-cc-formats-are-supported-on-native-safari.md)
* [How to navigate through the documentation and resources](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-navigate-through-the-documentation-and-resources.md)
* [What are the limitations of AirPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-are-the-limitations-of-AirPlay.md)
* [What are the Uplynk challenges](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-are-the-uplynk-challenges.md)
* [How to use the Media Session API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-use-media-session-api.md)
* [How to use THEOplayer iOS SDK on an M1 mac](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-use-theoplayer-ios-sdk-on-m1.md)
* [Widevine CDM deprecation notice for old browser versions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/old-widevine-cdm-deprecation-notice.md)
* [Which source is the one being played](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/which-source-is-the-one-being-played.md)
* [What PiP options to use to make the video stay visible while browsing or on other applications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-make-pip-video-stay-visible-while-browsing.md)
* [Why are the FairPlay license and certificate being requested again on iOS after ads?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-is-DRM-license-retrieved-again-after-ads-on-iOS.md)
* [How to detect if the user changes the video quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-detect-if-user-changes-video-quality.md)
* [List of supported platforms](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/supported-platforms.md)

## Error handling

* [Which error related events does the player expose](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/which-error-related-events-does-player-expose.md)
* [What does the error message 'Unknown CDM error' mean](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-does-error-unknown-cdm-mean.md)
* [What does the error message 'Something went wrong with Native playback' mean](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-does-error-something-went-wrong-during-playback-mean.md)
* [What does the error message 'can only be initiated by a user gesture' imply? Can I still force the desired action](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-does-error-can-only-be-initiated-by-user-gesture-mean.md)
* [What does the error message “Something went wrong determining the initial period of the provided MPEG-DASH stream” mean](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/error-message-initial-period-provided-MPEG-DASH.md)
* [What is the "WebAssembly.compileStreaming failed" warning and what does it mean?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-is-the-webAssembly-compileStreaming-failed-warning.md)

## Support

* [What is the support for Wowza](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-is-the-support-for-wowza.md)
* [How to create a (great) ticket](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-create-a-ticket.md)
* [How to investigate a ticket](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-investigate-a-ticket.md)

---

# How to combat autoplay policies

This short article explains what autoplay is, where autoplay is restricted, and what THEOplayer does to facilitate working with autoplay.

When you enable [autoplay](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#autoplay) for a HTML5 video, you instruct the viewer's browser to automatically play the content as soon as possible without action from the viewer.

## Restrictions

Browsers are restricting their autoplay capabilities. These policies are the result of the continuous misuse of autoplay which causes bad user experiences.

There are two types of autoplay:

* Unmuted Autoplay: autoplay with audio enabled.
* Muted Autoplay: autoplay with audio disabled.

The first type is considered more abrupt, while the second type is considered more user-friendly. Some browsers which normally disallow unmuted autoplay allow it when the viewer explicitly indicates so\*.

## API

##### Web SDK

An HTML5 video player can't circumvent these technical limitations, but it can offer an API which enables you in a smart way to switch between muted and unmuted autoplay.

THEOplayer has the `mutedAutoplay` property in the `PlayerConfiguration`. When you set this property to all, THEOplayer will run in unmuted autoplay on browsers where this is allowed, and in muted autoplay where autoplay with sound is not allowed. You can find a valid example below:

```js
// ...
var player = new THEOplayer.Player(element, {
  // ...
  mutedAutoplay: 'all',
  // ...
});
// ...
player.autoplay = true;
// ...
```

There's a possibility that new restrictions will be introduced in the future, so it's advised to keep autoplay restrictions in mind when developing your product.

---

# Why does fullscreen not behave as expected on iOS

One of the most frequently encountered issues on iOS devices is unexpected behavior concerning fullscreen playback.

This is in fact an iOS limitation, since iOS + Safari does not allow showing non-video elements in fullscreen, as mentioned on this [support matrix](https://caniuse.com/#feat=fullscreen).

THEOplayer's workaround involves playback in full-window, which sets THEOplayer's container to a `width` and `height` of 100%. Other elements can be placed on top of this view by giving it the CSS property `position: absolute;` (Combined with a top/bottom/right/left value) If this is not desired, reduce the `z-index` of these other elements.

Note that this solution keeps the THEOplayer UI intact, but doesn't get rid of the address bar as desired in some cases.

Alternatively, developers can use the [allowNativeFullscreen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerConfiguration#allowNativeFullscreen) property mentioned here, which pushes the video element to fullscreen as seen below.

```js
<script>
    var element = document.querySelector('.theoplayer-container');
    var player = new THEOplayer.Player(element, {
        libraryLocation : '/your_library_location/',
        license: "your_license",
        allowNativeFullscreen: true,
        ui : {
            width : '500px',
            height : '100px'
        }
    });

    player.source = {
        sources : [{
            src : '//cdn.example.com/index.m3u8',
            type : 'application/x-mpegurl'
        }]
    };
</script>
```

The downside of this approach is that the iOS native look & feel will replace the custom UI, although the address bar will be gone.

When you go full-window in an iframe, you won't see the container of the video grow because the iframe can't get any larger.

---

# Why does the Network API not work on iOS devices

Most Network API capabilities are not available on iOS devices. Generally speaking, video playback on iOS behaves like a black box. This black box handles the requests (and responses) related to video manifests and segments, which makes them impossible to intercept. This limits the possible uses of the Network API on such devices.

The Network API can still be used to intercept and alter requests and responses unrelated to video playback manifests and segments (e.g.: DRM-related requests and responses).

---

# Why does Chromecast not work on iOS Chrome?

iOS Chrome used to support Chromecast. However, Google silently removed support for it at some point. It is also documented [on their Web Sender guide here](https://developers.google.com/cast/docs/web_sender) that:

> **Info**
>
> Casting (Chromecast) is not supported on the iOS Chrome browser.

You can still implement Chromecast inside a native iOS app following our guide [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/enable-chromecast-on-the-sender.md).

---

# Why can't I select another video quality on iOS/tvOS?

**In short**: Apple technically restricts video players from doing this, and there is no workaround.

#### The case for iOS Safari, macOS Safari, iOS SDK and tvOS SDK

Any HTML5 video player, like THEOplayer, needs to use native technologies to do video playback, decoding and decryption. On web browsers, video players typically leverage the MSE and EME API by default. If this API is not available, then video players have to rely on native playback to handle video playback, decoding, decryption and ABR selection.

On iOS browsers, THEOplayer has to use the native playback pipeline, instead of the [MSE](https://developer.mozilla.org/en-US/docs/Web/API/Media_Source_Extensions_API) and [EME](https://developer.mozilla.org/en-US/docs/Web/API/Encrypted_Media_Extensions_API) API. The native playback pipeline on iOS also exposes an API, but this API doesn't expose any information on the available qualities in a HLS stream, nor does it indicate which quality is currently active.

When a FairPlay DRM protected stream is used, we are limited by the same scenario on macOS Safari since for DRM playback we rely on the native pipeline.

The underlying AVFoundation stack on iOS/tvOS SDKs, which THEOplayer has to use, brings along the technical limitation that you cannot select a specific video quality. Instead, you can set a maximum resolution or bitrate as explained [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-select-video-track-quality.md#ios-tvos-sdk).

In result, THEOplayer cannot offer functionality to developers and viewers to change qualities on these scenarios.

## Resources

The following resources provide more information:

* <https://developer.mozilla.org/en-US/docs/Web/API/Media_Source_Extensions_API>
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-select-video-track-quality.md#ios-tvos-sdk)

---

# Is YouTube supported

This question above is typically asked by customers who have experience with the YouTube embedded player. It's also related to the following questions:

* Does THEOplayer support the playback of YouTube videos?
* How do you embed YouTube inside THEOplayer?

It is not legal to embed YouTube videos inside any video player, and overlay any custom UI elements. You can not use the YouTube embedded player inside THEOplayer.

Source: <https://developers.google.com/youtube/terms/required-minimum-functionality>:

> You must not display overlays, frames, or other visual elements in front of any part of a YouTube embedded player, including player controls. Similarly, you must not use overlays, frames or other visual elements to obscure any part of an embedded player, including player controls.

Links:

* <https://developers.google.com/youtube/terms/api-services-terms-of-service>
* <https://developers.google.com/youtube/terms/required-minimum-functionality>
* <https://developers.google.com/youtube/terms/developer-policies>

---

# Why does the player load only one audio track (even though there are several in the manifest)

You may be asking this question if you notice a discrepancy in the number of audio tracks present in the manifest and the audio tracks that you can select from the player UI.

Similar questions may be:

* How to make all audio tracks in of my stream appear in THEOplayer
* Why the player does not return the correct audio tracks?
* Why does the player detect only one of the audio tracks of my manifest?

First of all, a reassuring word: if your manifest is well-formed and contains multiple audio tracks, you do not need to do anything to import them all, as the player does this by default.

However, if your audio tracks are missing, it usually means that something in the manifest is wrong. **If the manifest is indeed correct according to specs, this kind of behavior may occur if the video track includes also audio** (even in the presence of separated audio tracks). In this case, the player considers that audio track as primary and ignores all the others.

In other words, when you want to be able to switch between different audio tracks, take care that all of them are included in the manifest separately from the video and that the video track does not include any audio track. This will also result in a slightly faster download time.

---

# Is it possible to see 360 degrees photo with THEOplayer

This question is asked by those users and developers that are wondering if the player 360 degree functionality can be used to view also images.

No, this cannot be done. The player is intended for video sources, so an image as input is not officially supported, which is also true for 3D images.

---

# Why the Visibility API does not work through an iframe on Safari and IE11

This question may be asked when you observe a different behavior of the Visibility API on different browsers.

The [Visibility API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Visibility) provides developers a way to observe how much of the player is visible.

When the player is embedded in an iframe, this API does not work on Safari and IE11. This depends on the fact that the player uses the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#Browser_compatibility) if it's available in the browser. Unfortunately, IE and Safari do not have support for this, so the player necessarily falls back to scroll events for these environments.

This is the reason why on those browsers the Visibility API works correctly when the player is on the page but it is not functional through an iframe.

February 2019: A piece of good news: the Intersection Observer API is now in beta in Safari: <https://webkit.org/blog/8582/intersectionobserver-in-webkit/>

---

# What is an impression

This article explains what an impression is and how THEOplayer calculates impressions.

THEOplayer will count an impression when the video or audio source is being played for the first time by our SDK. This can be triggered by a user clicking the Play button, or by playing the video automatically (autoplay). When you pause, play or seek within the same video or audio source, it still will be counted as only one impression. If a user refreshes the page or reloads the application, a second impression will be counted. If the content contains ads, these will not be counted towards the impression count. Except when the content only contains ads, then these will be counted towards the impression count.

As an example, if you start a video, pause the video and then resume again it is only considered one impression. If on the other hand you start a video and then refresh your browser, or reload your application, it would be considered 2 impressions.

---

# How to know whether a live stream is playing

You can check if a stream being played is live or VOD by checking its duration. If the duration returns `Infinity`, the stream would be live. Examples:

##### Web SDK

```js
var isLive = player.duration === Infinity; // true or false
```

##### Android SDK

```java
boolean isLive = Double.isNaN(tpv.getPlayer().getDuration()); // true or false
```

---

# Which error related events does the player expose

THEOplayer exposes different types of errors. Refer to "[How to do error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/error/how-to-do-error-handling.md)" for information on how to programmatically detect an `error` event through an event listener.

Note that only the `error` events in the "Player API" are fatal. Error events dispatched in different APIs (e.g. Ads API) are considered non-fatal, because some level of playback might still be possible, or the video player might recover from it.

| API                    | Event                                        | Use                                                                            | Example/how to trigger                                                           |
| ---------------------- | -------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Player                 | error                                        | Triggered for media issues, NOT network issues                                 | A poorly encoded segment                                                         |
|                        | segmentnotfound (not on iOS + only for DASH) | A segment was not found                                                        | A 404 returned on a segment                                                      |
| Ads API                | aderror                                      | Something went wrong during ad handling                                        | Empty ad tag / Adblocker                                                         |
| Network API (web only) | offline                                      | Thrown to indicate that the stream is offline                                  | DASH: take whole stream offline<br /><br />HLS: take 1 segment offline is enough |
| Chromecast API         | error                                        | Thrown to indicate that there was an error while casting / trying to cast      | Unplugged Chromecast power cable during casting                                  |
| Android Player API     | NoSupportedRepresentationFoundEvent          | Indicates that none of the provided representations is supported by the player | Trying to play a 4k stream encoded in AV1                                        |

---

# Why did my subtitles stop working

This question is occasionally asked by developers who've configured the latest release of THEOplayer.

### Before version 2.80

The most common reason on an older build why closed captions are no longer working is because the **`texttrackrendering` feature isn't enabled**. To verify whether this feature is enabled you can execute the query below.

```js
var subsEnabled = THEOplayer.features.indexOf('texttrackrendering') > -1;
```

### After version 2.80

Starting in THEOplayer version 2.80 the `texttrackrendering` feature is no longer an optional feature. It is instead part of the default build, and is always enabled.

### Other frequent reasons:

* A new stream is configured which does not list any subtitles in its manifest.
* The subtitle file can't be retrieved. (e.g. 404)
* There are CORS issues with the subtitle file.
* The subtitle file is encoded in a non-compatible format.

---

# How does Media Engagement Index (MEI) affect Autoplay on Chrome

The question above is related to the following questions:

* Why is autoplay not working on Chrome?
* Is THEOplayer limited by the Media Engagement Index?

In summary, **it's possible that on the desktop-version of Chrome (unmuted) autoplay is no longer working on your web page due to the Media Engagement Index**. The following two strategies can help you resolve this issue:

1. Increase your MEI.
2. Enable muted autoplay. ([How to combat autoplay policies](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-combat-autoplay-policies.md))

You can read more about Chrome's autoplay policy at <https://www.theoplayer.com/blog/chrome-autoplay-policy-what-you-need-to-know>. A demo illustrating this policy can be viewed at <http://demo.theoplayer.com/autoplay-policy>.

Remarks

* The following scenario is possible due to the Chrome autoplay policy: when you first land on a web page, unmuted autoplay is not permitted. When you click through to another page, or refresh the page, unmuted autoplay is permitted, due to the additional user interactions which affect the MEI.
* You can check your MEI at chrome://media-engagement/.

---

# What does the error message 'Unknown CDM error' mean

If you got to see this page, you probably know that CDM stands for Content Decryption Module, which is a component in the DRM pipeline, a part of the content protection process.

There are 2 scenarios where this error can be triggered:

* If a user is watching a DRM-protected stream, and then tries to Airplay **their whole screen** (In the device status bar as opposed to AirPlaying by clicking the icon in THEOplayer when watching in Safari). Because it cannot be guaranteed that the content is not being hijacked in this scenario, the player throws the "Unknown CDM error". This scenario is Mac/Safari specific.
* A second scenario where you would see this error is when, on iOS, you record your screen with built-in or third-party software while playing DRM-protected content. This scenario is iOS specific. Safari uses media error code 5, according to VideoJS documentation (<https://docs.videojs.com/mediaerror>)

Using this knowledge, developers could handle this error by capturing the 2 cases under one, more generic message towards the user e.g. 'This content is protected and can't be viewed this way.'

---

# What does the error message 'Something went wrong with Native playback' mean

This error, "Something went wrong with Native playback", occurs whenever the player struggles on the native rendering pipeline of the browser in use. The error code itself can be different, and it reflects the HTML5 MediaError interface.

"Something went wrong with Native playback" is a possible error message which can be exposed by THEOplayer. Although it sounds generic, it is related to native rendering, as explained above.

## Native Rendering

Native rendering is used when THEOplayer leverages the native media playback pipeline. Usually, THEOplayer leverages this when this pipeline is the only possible pipeline, for example when you can't use MSE.

Examples:

* When doing playback on iOS Safari, THEOplayer will do native playback, because native rendering is the only option on iOS Safari.
* When a plain MP4 asset is configured, instead of an HLS or MPEG-DASH stream, THEOplayer will do native rendering.

Native rendering can log an error due to multiple causes, but they relate to MediaError code. There are several MediaError codes, but for this case the ones relevant are:

* `MEDIA_ERR_DECODE: 3` – This is shown when a media resource was deemed as usable, but when trying to decode the media resource in question it appears to have some problems in it (can be segments missing,...).
* `MEDIA_ERR_SRC_NOT_SUPPORTED: 4` – The source added to the player is not suitable for this playback. A good example would be trying to play a DRM protected DASH stream on Safari (Safari only supports HLS-FairPlay)

The THEOplayer API can be used to access the MediaError code: `player.error.code`

This line will return the MediaError together with the specific code. This makes it easier to find out what the error exactly means, and allows developers to plan for further actions.

## Related articles

* <https://developer.mozilla.org/en-US/docs/Web/API/MediaError>

---

# Why are not all response headers exposed

You may ask this question if, for example, you are trying to intercept a certain XHR response to use data contained in custom headers but you don't find these among the exposed headers (see documentation below regarding network interceptors).

This happens because by default, only some headers are exposed by default. You can however decide to specify which additional headers you want exposed. This is done through the Access-Control-Expose-Headers response header. It "indicates which headers can be exposed as part of the response by listing their names" (see [documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers)).

---

# Why does the currentTime seem off in my livestream & what can I do about it

THEOplayer has a currentTime property, which returns you the current playback position in the video (in seconds). For VOD this works as you would expect. If you have a video, let it play for 30 seconds and query the currentTime, the player will report 30 seconds. However, if you start watching a livestream and query the currentTime after 30 seconds, you won't get 30 seconds reported. Nor will you get the time that would have elapsed if you watched the segments in the most recent manifest file until the point where you queried the currentTime. This might seem odd, but there's a very good reason for this, which we'll explain in a bit, along with some workarounds if you do want to use one of the aforementioned definitions of currentTime in a live streaming context.

To calculate the currentTime, THEOplayer follows the HTML5 specification. However, for livestreams, this is not specified. Hence, if you try to use currentTime for synchronization between players, you'd get different behavior among different players. It's even possible to see different behavior among different streaming protocols in conjunction with the same player.

The internal implementation THEOplayer uses, is constructed to never have a negative currentTime. A few things are being checked to ensure this:

* Check if it's a VOD. In this case the timeline starts at 0
* In case it's a live stream, there are two options

**It's a live-EVENT stream**

* Manifest contains `EXT-X-PLAYLIST-TYPE: EVENT`
* All renditions started at the same time, so the first segment would have timestamp 0

**It's a livestream with a DVR window**

* For these some players choose to start the 0-offset at the start of the first segment
* However, segments are not necessarily aligned across multiple renditions:
* Switching renditions can cause new content to become available before the start timestamps of the first rendition
* Such a segments would halve a negative start timestamp
* To avoid negative timestamps, THEOplayer keeps an offset of 3 target durations from the start as its zero-reference

How can you deal with this if you want to synchronize players or get a zero-based timestamp? You have **3 options**:

1. Use `EXT-X-PROGRAM-DATE-TIME`, which gives you an absolute time reference.
2. Make your stream an event stream by including `EXT-X-PLAYLIST-TYPE: EVENT` in the manifest
3. Use the player's seekable property (which is based on the manifest) and query seekable.start(0) to find the starting time of your stream 3.1 Attach an event listener for the 'durationchange' event (triggered the first time a media playlist is loaded) 3.2 Upon this event, store player.seekable.start(0) in a variable 'timeOffset' and remove the eventlistener 3.3 Subtract the value of 'timeOffset' from the player's currentTime to get a zero-based timestamp

Here's a code snippet for option 3 :

```js
function AbsoluteTimeline(player) {
  var timeOffset = 0;

  function durationchangeHandler() {
    timeOffset = player.seekable.start(0);
    player.removeEventListener('durationchange', durationchangeHandler);
  }
  player.addEventListener('durationchange', durationchangeHandler);

  return {
    getOffset: function () {
      return timeOffset;
    },
    getCurrentTime: function () {
      return player.currentTime - timeOffset;
    },
    seek: function (timestamp) {
      player.currentTime = timestamp + timeOffset;
    },
  };
}

var timeline = AbsoluteTimeline(player);
```

---

# How to remove CORS restrictions from a reproduction stream

A "CORS-issue" is a common cause of a stream not starting. In a nutshell, a CORS issue implies that the origin is not allowed to fetch the resource. This issue has to be resolved from the server-side.

Additionally, sometimes we ask customers to alter their CORS-policy in order to playback streams from a development environment. A CORS-issue blocks us from deploying the stream in our development environment.

---

# Which network calls (or requests) does THEOplayer do

The question above is related to the following questions:

* What is the call to license.theoplayer.com?
* Why is THEOplayer sending a request to licensing.theoplayer.com?
* What is the call to licenseapi.theoplayer.com, and why is it failing?

THEOplayer can do three different network requests to `*.theoplayer.com` which are not related to your stream.

1. `license.theoplayer.com`: this request logs an impression to THEOplayer's analytics server. THEOplayer uses impressions to know how many views you've received, because it's taken into account for billing purposes. The analytics server does not track personal information on your users.
2. `licensing.theoplayer.com/t?`: this request serves as a fallback request when the call to license.theoplayer.com fails.
3. `licenseapi.theoplayer.com/api/v1/check`: this request happens when your current license is invalid, for example on a domain (or IP-address) which hasn't been whitelisted. This request will not be successful because there's no service configured for this request. (This might change in the future.)

---

# Why does the playback not work when using the Chrome iPhone/iPad simulator

You might need an answer to this question if you are testing your page using the Chrome iPhone/iPad simulator and notice that, reloading the page, the video player stops working (even though the ads, if any, are displayed correctly) and some errors are displayed in the console.

Similar questions are:

* Why does the playback not work when using Mozilla in Responsive Design Mode?
* Why does the playback not work when using the Edge emulator to test my page on other platforms?
* Why does the playback not work when testing device-specific viewports with the browser dev tools?

The simple answer is that this occurs because the video player gets confused between the user agent (set as iOS during the simulation) and the browser actually in use. This does not imply that there is any problem with the video player. In fact, when the tested page will be accessed by an actual iOS device, the video player will work fine, in absence of other (unrelated) issues.

The same behavior is to be expected in similar tests, that is to say when a platform is emulated on another and they do not share the same playback logic of the native video element.

Some more details:

If you use Chrome + iOS simulator, your user-agent will change to iOS/Safari. THEOplayer detects this new user-agent, and because it's iOS it'll think that the MSE API is not available, and that they need to use the playback logic of the native video element. However, you're still on Chrome, so this alternate native iOS playback logic is not available. These circumstances lead to playback failure. It works for ads because they typically do not use the HLS protocol, so we do not have to leverage MSE.

It is not advisable to use (or rely on) the Chrome + iOS simulator mode to test anything else than the view mode. The native APIs which iOS offers are not available in this mode, so it's not really a useful testing mode.

---

# What does the error message 'can only be initiated by a user gesture' imply? Can I still force the desired action

You may get this error if you are trying to have the player execute an action without it being initiated by the user. A typical example is going fullscreen or automatically starting playback (often on mobile).

Related questions are:

* Why can’t I set the player to fullscreen mode on screenrotation? (Related error message: “Failed to execute 'requestFullScreen' on 'Element': API can only be initiated by a user gesture.”)
* Why is an error generated if I want to automatically start playback when certain conditions are met (Related error message: DOMException: play() can only be initiated by a user gesture)

The short answer is no, you cannot (and should not) force an action that gets this kind of error message: this is a block implemented by the browser to protect the user.

The details:

In some cases, the browser deems that a certain behavior cannot be initiated automatically and needs instead to be started by the user (or user action). This happens because these behaviors may be perceived as bad or harmful by a user, if automated. In other words, this limitation is implemented by the browser to protect the user from (for example) invasive pop ups, advertisement, etc., as well as from more serious threats to a good and safe web surfing.

To our knowledge, there is no way to force the browser to ignore this error, and you probably shouldn't want to do so, for the above-mentioned reasons. Therefore, if you incur in this situation you may want to find an alternative way to achieve the desired result (or take the hint from the browser and reconsider whether what you want to achieve is appropriate for your use case and good for the user).

Update 7/12/2018

This behavior is common on devices and on Safari.

Chrome 71, released a few days ago, also introduces the need for user interaction to go fullscreen.

---

# How to remove unwanted CC track in iOS or Safari

This article is intended to show how to remove any unwanted CC tracks that might be showing up in iOS or Safari. This can be done by editing the HLS master playlist.

**Unwanted CC in Safari native**

![Unwanted CC in Safari](/pr-932/assets/images/unwanted-cc-safari-afa200bfd56332b7a019c6a8b4d2ce62.png)

**Unwanted CC in THEOplayer iOS**

![Unwanted CC in iOS](/pr-932/assets/images/unwanted-cc-ios-9ca2c0569660319c77f96ecf29561a5a.png)

## How to remove unwanted cc tracks?

To remove any unwanted cc tracks, the “CLOSED-CAPTION” attribute has to be set to “NONE” inside the HLS master playlist. This is to be compatible with the HLS specification: <https://tools.ietf.org/html/rfc8216#section-4.3.4.2>

If it is a multi-variant stream, this has to be done for all variants.

```text
CLOSED-CAPTION=NONE
```

---

# MediaTek limitations

This page overviews a list of known issues caused by the MediaTek chipset.

## 1. Switching to fullscreen halts playback for approximately 10 seconds

The MediaTek decoder seems lackluster at handling a transition to fullscreen when **experimental rendering** is enabled because THEOplayer uses a separate Android Activity for fullscreen. Using the default rendering pipeline does not trigger this issue. A workaround is doing fullscreen without detaching the SurfaceView from the window.

### Why does THEOplayerView use a separate activity for fullscreen?

THEOplayerView uses a separate Activity for fullscreen so that the fullscreen view is completely isolated from the Activity the THEOplayerView is in. The Activity has its own orientation, window settings, and back button behavior. By using a separate Activity, we can leave those settings and the view hierarchy intact in the Activity in which the THEOplayerView is embedded.

A downside of this in case of experimental rendering is that we need to move the SurfaceView that holds the Surface on which video is rendered. This, however, means that the Surface is destroyed and a new one is created. On newer devices, this is normally no problem because the decoder is decoupled from the Surface. When the Surface is destroyed, a new one can be attached to the same decoder. On devices with an API lower than 23 (and some other devices which bug) however, the decoder can not change the Surface on which it draws without re-initialization. This means that on older and some buggy devices, switching to fullscreen will make the video hang until the next keyframe is reached in the stream.

### Solution: Fullscreen without detaching the SurfaceView from the window

If an implementer does not want the Surface to be destroyed when going fullscreen, the implementer needs to implement this themselves to fit within the Activity.

A few things are needed for this:

1. FullscreenCoupling needs to be disabled (with `getTPV().getSettings().setFullScreenOrientationCoupled(false)`).
2. If the UI is enabled, the fullscreen button needs to be hidden or overwritten. This needs to be done with [custom CSS and/or custom JavaScript](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).
3. Orientation needs to be handled in the Activity. 3.1 To change the orientation of the Activity, [`setRequestedOrientation`](https://developer.android.com/reference/android/app/Activity.html#setRequestedOrientation\(int\)) has to be called on the Activity or the Activity needs to be allowed to rotate. Allowing the activity to rotate means that the android:screenOrientation property in the [manifest](https://developer.android.com/guide/topics/manifest/manifest-intro) needs to be set to multiple values or not set. 3.2 To make sure that the Activity is not recreated on an orientationchange,android:configChanges field in the manifest need to include "orientation|screenSize". 3.3 To detect the change, the onConfigurationChanged method needs to be overridden in the Activity. In the implementation the orientation can be checked and fullscreen can be initiated or stopped depending on it.
4. To make the THEOplayerView fill the whole Activity without moving the view, the THEOplayerView and all of its parents view's width and height layout parameters need to be set to "match\_parent" and they all need to be the first child-view (with a non-zero surface area).
5. To hide the navigation buttons and status bar, the Activity should change the window and visibility flags. this can be done with: 5.1 getWindow().getDecorView().[setSystemUiVisibility](https://developer.android.com/reference/android/view/View#setSystemUiVisibility\(int\))(SYSTEM\_UI\_FLAG\_LOW\_PROFILE|SYSTEM\_UI\_FLAG\_FULLSCREEN|SYSTEM\_UI\_FLAG\_LAYOUT\_STABLE| SYSTEM\_UI\_FLAG\_IMMERSIVE\_STICKY|SYSTEM\_UI\_FLAG\_LAYOUT\_HIDE\_NAVIGATION|SYSTEM\_UI\_FLAG\_HIDE\_NAVIGATION); 5.2 getWindow().[setFlags](https://developer.android.com/reference/android/view/Window.html#setFlags\(int,%20int\))(FLAG\_FULLSCREEN, FLAG\_FULLSCREEN);
6. To let the player exit fullscreen on a back button press instead of stopping the Activity, the onBackPressed method of the Activity should be overridden with the desired behavior.
7. When going back from fullscreen, the original settings for the window and back button behavior need to be set back to desired values.

---

# How to use ProGuard with THEOplayer Android SDK

ProGuard is a popular tool to obfuscate and optimize Java code in Android projects. Depending on the settings, this tool can clash with the THEOplayer Android SDK.

Below, you can find a list of rules tested against THEOplayer Android SDK on 28 Nov 2018.

```text
-keep class com.theoplayer.android.** {*;}
-dontwarn com.theoplayer.android.**
-keep public class com.google.android.gms.* { public *; }
-dontwarn com.google.android.gms.**
-keep class android.support.v7.app.MediaRouteActionProvider {*;}
-dontwarn android.support.v7.app.MediaRouteActionProvider

# In case of using yospace integration
-keep class com.yospace.util.** {*;}
-dontwarn com.yospace.util.**

# For native Google IMA integration
-keep class com.google.obf.** { *; }
-keep interface com.google.obf.** { *; }
-keep class com.google.ads.interactivemedia.** { *; }
-keep interface com.google.ads.interactivemedia.** { *; }

# And in case of using a CastOptionsProvider and/or custom MediaRouteActionProvider for chromecast, you have to keep those classes too.
# eg:
# -keep class com.yourcomp.yourchromecastpackage.** {*;}
# -dontwarn com.yourcomp.yourchromecastpackage.**
```

---

# Self-hosting and versioning of THEOplayer

Your licensed THEOplayer can also be hosted on your own servers or CDN. This can be useful when you do not want to have a dependency on a third-party hosting infrastructure, for using THEOplayer on internal/local (and even offline) networks or for using THEOplayer inside mobile apps.

There are two approaches to download the THEOplayer SDK for self-hosting purposes:

1. Use [NPM](https://www.npmjs.com/package/theoplayer).
2. Download the SDK through <https://portal.theoplayer.com>.

> **Important**
>
> When self-hosting THEOplayer, it is important you regularly update your self-hosted THEOplayer files in order to benefit from the latest improvements.

In order to download the THEOplayer package and host it on your server, you will first have to determine which version of the player you want to use. Read up about version changes in the [changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog.md).

## Configuring self-hosting

Once you extracted the ZIP package to your server, you must configure THEOplayer and provide the information where the resources can be found. For this, you should configure 1 parameter correctly:

* `libraryLocation`: This parameter should point to the location of the library. It is the location where the ZIP package has been extracted and the resources are available on the server.

Of course, also keep in mind to correctly link to the correct JavaScript library and CSS file.

```html
<script type="text/javascript" src="/path/to/THEOplayer.js"></script>
<link rel="stylesheet" type="text/css" href="/path/to/ui.css" />
```

## Common mistakes

* Configuring the libraryLocation incorrectly. The referred location/folder should contain `theoplayer.d.js`, `theoplayer.e.js`, `theoplayer.p.js`, `THEOplayer.js`, and so on, and they need to all have the same version.
* Using the THEOplayer library on a web page which resides on a non-whitelisted domain (e.g. <http://localhost/index.html>). Although you can host your library assets anywhere, you can only use the actual video player on white-listed domains.
* Linking to an unreachable JavaScript or CSS library.

---

# Does THEOplayer support EXT-X-DATERANGE

Yes, the HLS tag `#EXT-X-DATERANGE` is supported in THEOplayer as of 2.61.0. To enable it, hlsDateRange needs to be added to either the player configuration or the source description and be set to true. The date range metadata will be made available through the TextTrack API.

`#EXT-X-DATERANGE` is a way of providing timed metadata in an HLS manifest. It is used to define date range metadata in a media playlist. A possible use case is defining timed metadata for interstitial regions such as advertisements, but can be used to define any timed metadata needed by your stream.

As indicated above, `#EXT-X-DATERANGE` is supported in THEOplayer as of 2.61.0. However, the feature is not enabled by default. To enable it, add hlsDateRange to the player configuration and set it to true. You can also choose (instead) to enable/disable the feature per source by adding the same option to a source in your source description.

The TextTrack API is used to retrieve the timed metadata. A MetadataTextTrack will provide cues which contain the timed metadata and will dispatch an event when started and ended.

## Remarks

* A manifest with EXT-X-DATERANGEs needs to have an EXT-X-PROGRAM-DATE-TIME to be able to calculate dates from playback times. This is also a specification requirement.
* If the tag name for a date range tag in the manifest is incorrect, the tag will be ignored
* If the name of any attribute is misspelled in a date range tag in the manifest, the attribute will not be parsed
* When using native browser playback features such as FairPlay content protection, the player might use more resources to parse date ranges from the manifest than in other scenarios.

## Resources

The following resources provide more information:

* [HLS Specification - #EXT-X-DATERANGE](https://tools.ietf.org/html/draft-pantos-hls-rfc8216bis-04#section-4.4.2.7)
* [API reference - TextTrackType](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/TextTrackType)

---

# Can clipping be used on a playlist

Yes. This is in principle not different from using it on a single video: a startTime and an endTime must be given for each video and applied when the video is loaded/played.

Let’s expand slightly the idea. You can have 2 use cases:

* The same start and end time can be used for all contents.
* Each content has a different start and end time.

## The same start and end time can be used for all contents

In this case, you can apply the Clip API without any further precaution or modification. You can find an example at the page Video clipping in THEOplayer (see below). Please remember to make sure that clipping happens after the source is set (e.g.: use a `durationchange` event).

## Each content has a different start and end time.

In this case, some adjustment is needed to be able to provide and read the right custom start and end time for each content. One possible way to do it is to simply pass such data together with the source data and read it directly from there when clipping the video, like in the example below.

```js
// an array is provided, containing multiple player.source. Each source contains startTime and endTime.
var playlist = [
  {
    source: {
      sources: {
        src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
        startTime: 100,
        endTime: 150,
      },
      title: 'Big Buck Bunny',
      description: 'Big Buck Bunny',
      poster: 'https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
    },
  },
  {
    source: {
      sources: {
        src: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
        startTime: 120,
        endTime: 180,
      },
      title: 'Star Wars Reel',
      description: 'Star Wars Reel',
      poster: 'https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/poster.jpg',
    },
  },
  {
    source: {
      sources: {
        src: 'https://cdn.theoplayer.com/video/tears_of_steel/index.m3u8',
        startTime: 50,
        endTime: 150,
      },
      title: 'Tears of Steel',
      description: 'Tears of Steel',
      poster: 'https://cdn.theoplayer.com/video/tears_of_steel/poster.jpg',
    },
  },
];

// the desired source is set in the player -
// this is not reported here as it depends on your implementation,
// but an example can be seen in the resources linked below.
// For the purpose of this example
// player.source = playlist[0];

// the following lines make sure that
// when the first playing event is fired for each (new) content
// clipping times are read from directly within the player.source

function firstplaying() {
  player.clip.startTime = player.source.sources.startTime;
  player.clip.endTime = player.source.sources.endTime;
  THEOplayer.players[0].removeEventListener('durationchange', firstplaying);
}

THEOplayer.players[0].addEventListener('sourcechange', function () {
  THEOplayer.players[0].removeEventListener('durationchange', firstplaying);
  THEOplayer.players[0].addEventListener('durationchange', firstplaying);
});
```

Notes:

* In this example, we are only describing how to apply the clipping, not how to play a playlist. For this, please consult the linked resources.
* The example is provided only in JavaScript because clipping is currently available only for the JavaScript SDK. It may be used also in other SDKs through JavaScript injection.

## Resources

The following resources provide more information:

API reference - [Clip API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Clip)

Clipping - [How-to guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/clipping.md)

---

# Can timeline thumbnails be made available before playback start

Yes, this is possible using the preload feature, provided your timeline is already visible. Both “metadata” and “auto” will be effective values to this end.

If the player on your implementation shows the timeline before playback start (differently than on our demo pages), you may indeed be interested to show the timeline thumbnails, and possibly other data (e.g.: video duration). As explained above, this may be achieved using the preload. Both values “metadata” and “auto” will work for this. The advantage of using “auto” is that also some media files will be buffered, reducing the start-up time. To know more about preload, please visit the linked resources.

In case your timeline is not visible before playback start, however, using preload will have no visible impact on the timeline thumbnails.

## Resources

The following resources provide more information:

* [Preloading - How to](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/preloading.md)
* [What are the benefits of preloading?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-are-the-benefits-of-preloading.md)
* [PreloadType API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/PreloadType)

---

# What are the benefits of preloading

Choosing whether to preload parts of the video before it starts playing will help you considerably improve the user experience.

Preloading involves loading parts of a video source before the video starts playing. When the video later starts playing, it can do this much faster because it has already downloaded some data. This can improve the user experience dramatically when you expect the user will want to play the video. On the other hand, when the video is less likely to be played, you can configure the player to not preload it and save bandwidth.

Interactive video experiences are one example use case for this functionality. In an interactive video, the user must choose between multiple options at the end of a video, with each option leading to a different video. Using preloading will help you ensure a smooth transition between videos (to this purpose you may also want to use other THEOplayer features, such as Cache API and Canvas API - see Resources).

Choosing to preload your video content will also make some data regarding the current source available before the user initiates playback. Such data include, for example, the video duration and the timeline thumbnails.

## Resources

The following resources provide more information:

* <https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-preload>: HTML5 specification
* [Preloading - How-to](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/preloading.md)
* [API reference: preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/PreloadType)
* [API reference: Cache API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Cache)
* [API reference: Canvas API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Canvas)

---

# What are the player seeking and seeked events and when are they fired

They are events related to the playback of media files. `seeking` is fired when the user starts seeking/moving to a new position. `seeked` is fired when the user is finished seeking/moving to a new position and the player has buffered a video portion, being therefore ready to play.

The player `seeking` and `seeked` events are not to be confused with the homonym `<video>` element events, although they mainly coincide in meaning and occurrence. In this regard, in THEOplayer you find both the player events and the video events.

*Seeking* and *scrubbing* are not considered equal in THEOplayer. *Seeking* is the action of starting to move to a new position and it has the corresponding `seeking` event. *Scrubbing* is the action to keep seeking to new positions while maintaining `mousedown` for a prolonged time. It has no corresponding event. Scrubbing can contain multiple seeking actions. While the viewer is scrubbing, the CSS class `vjs-scrubbing` is added on the `.theoplayer-container` element.

In other words, if the viewer does not seek directly to a new position with one click (`mousedown` and `mouseup`) but scrubs on the timeline instead, multiple `seeking` and `seeked` events may be fired. This is due to the not uniform movement while scrubbing. For example, if the pointer stays briefly in the same position while scrubbing and then resumes its motion, multiple `seeking` events may be thrown, as this is interpreted as different seeking actions. Even during scrubbing, if the pointer is temporarily staying in the same position, the player will try to buffer the corresponding video portion. If enough video is buffered and playback could start from that position, the `seeked` event will also be thrown at that moment, although the user may still be scrubbing.

## Remarks

The player events and `<video>` element events `seeking` and `seeked` should behave similarly, be fired on the same occasions and the same number of times. If they don’t, please report it in a ticket in our Service Desk.

## Resources

The following resources provide more information:

* <https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Media_events>: MDN reference
* [Player API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/Player)

---

# Can we use HLS or DASH ads

Yes, we support HLS and DASH ads through a `THEOAdDescription` for the THEOplayer Web SDK 2.84.0 and up. HLS and DASH ads are currently not supported on any other SDKs. Our Google IMA integration does not support HLS or DASH ads.

To be able to play HLS or DASH advertisements, make sure to add `allowedMimeTypes` with the corresponding mime-types to your player configuration. When no `allowedMimeTypes` are specified, THEOplayer will only play progressive media types (non-streaming) as advertisements. When `allowedMimeTypes` are specified, THEOplayer will first prioritize DASH, then HLS, then progressive media types.

```js
new THEOplayer.Player(element, {
  ads: {
    allowedMimeTypes: [
      'application/dash+xml',
      'application/x-mpegURL',
      'application/vnd.apple.mpegurl',
      'video/mp4',
      'video/3gpp', // See the Remark about 3gpp at the bottom.
      'video/webm',
    ],
  },
});
```

This is currently only supported using the web pipeline. There is no support for native iOS or Android.

Using HLS ads is useful for preloading advertisements on low-end devices such as older smart TVs.

THEOplayer supports various media file formats for ads. This includes mp4-based progressive download, by far the most used format for ads, currently providing the widest coverage across devices.

If your reason for using HLS ads is the wish to use ABR to be more flexible regarding bandwidth, rest assured: VAST can (and usually does) contain multiple media files in several resolutions, qualities and formats. Among these, the most appropriate will be chosen to be played on your device or desktop browser.

## Remarks

* With the Google IMA integration, HLS and DASH ads are never played, even on platforms with native support.
* Although browsers consider `3gpp` a video codec, sometimes their support is just for the audio part. There could be cases where no video is shown. Avoid this legacy format when possible.

## Resources

The following resources provide more information:

* [IAB Standards, Guidelines & Best Practices](https://www.iab.com/guidelines/?post_type=iab_guideline)
* [API reference – Ads interface](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Ads)
* [THEOplayer Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/user-guide.md)

---

# How to change text in THEOplayer

Using language localization, you should be able to change any text in the player to the one you desire.

Language localization is not limited to only translating. It can also be used to change any text in the player.

You can change the language localization in the player configuration.

```js
ui: {
    // your other ui configuration
    language: 'fr',
    languages: { 'fr':
        {
            "Something went wrong during native playback." : "Une erreur s'est produite pendant la lectue native."
            // any other translation
        }
    }
}
```

An example on how to use language localization can be found [here](https://www.theoplayer.com/theoplayer-demo-language-localization).

---

# Change text when AirPlaying

You will need to add the 'metadata' parameter to the SourceDescription with the 'title' property filled with the title to be displayed.

In order for the Airplay title text to be changed, you will need to add a MetadataDescription. Within this MetadataDescription you have to provide metadataKeys (which can be set to nil to ignore) and a title. This title is the variable that changes the text shown when using Airplay.

## Code example

```swift
 public static var bigBuckBunny : SourceDescription {
    let typedSource = TypedSource(src: bigBuckBunnyURL, type: StreamType.hls)
    let metadataDescription = MetadataDescription(metadataKeys: nil, title: "A title")
    return SourceDescription(source : typedSource, metadata: metadataDescription)
}
```

---

# ITP2.1 problems using THEOplayer

Apple’s Intelligent Tracking Prevention 2.1 causes cookies to be only saved for 7 days unless the Safari user directly interacts with the website again.

**There will be no issues**

* If a third party CDN provider isn’t used.

**Could be issues**

* If a third party CDN provider is being used. Please check with the provider regarding ITP2.1 policy.
* Check with provider if they are using authentication that uses third party cookies

With ITP 2.1, all persistent client-side cookies, i.e. persistent cookies created through document.cookie, are capped to a 7-day expiry. This causes cookies older than seven days to be destroyed, which leads to the user being identified as a new user who hasn't seen the site before.

# Resources

The following resources provide more information:

* <https://www.seerinteractive.com/blog/what-is-intelligent-tracking-prevention/>
* <https://webkit.org/blog/8613/intelligent-tracking-prevention-2-1/>

---

# Removing context menu 'Powered by THEOplayer...'

The context menu can be removed while building your player by disabling the "contextmenu" feature or by adding a CSS rule on your page.

You can disable the context menu in the style sheet like this:

```html
<link rel="stylesheet" type="text/css" href="/path/to/ui.css" />

<style>
  .theo-context-menu {
    display: none;
  }
</style>
```

## Related articles

* [How can we disable the right click?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/context-menu/how-to-disable-right-click.md)
* [How to change the Context Menu?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/context-menu/how-to-change-context-menu.md)

---

# What aspects of THEOplayer do we need to take into account to deploy a proper Content Security Policy (CSP)

The script-src 'self' and 'inline' should be allowed. The player also requires doing calls to \*.theoplayer.com and to wherever the JavaScript files and workers are located. Additionally, depending on your active features, you may need to add some other source (e.g.: if you are using Chromecast, you will need to allow <https://www.gstatic.com/>, as its library is hosted there).

Designed to be fully compatible with browser versions that don’t support it, Content Security Policy (CSP) is an additional layer of security that helps to detect and mitigate certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks. Configuring Content Security Policy involves adding the Content-Security-Policy HTTP header to a web page and giving it values to control resources the user agent is allowed to load for that page. (source: <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>)

When configuring CSP on your pages including THEOplayer, you will need to allow:

* \*.theoplayer.com, as the license needs to contact this domain
* the domain(s) where your JavaScript and worker files are hosted
* script-src: 'self' and 'inline'
* any domains hosting the libraries related to the features of THEOplayer that you are using. For example, Google IMA, Chromecast, FreeWheel, Youbora, Conviva, etc.

## Resources

The following resources provide more information:

* <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP/>

---

# How can we avoid that the player keeps looking for chunks/segments if they are not found

You can use the Network API events to detect whether the stream is offline and implement the behavior you prefer. This is working for HLS and is being implemented (2020) for DASH as well.

When a playlist is loaded that returns 404, the player fails and returns error. However, when the playlist is present but the segments are not available (404), the player will keep looking for segments, if left on its own, in an attempt to play back the video as soon as it’s available.

In this case, however, you can decide to implement a behavior managing this situation by using the Network API, and more precisely the offline event. After some attempts, this event is thrown to indicate that the stream is offline.

The opposite event, online, is also present in the API, and it is Thrown to indicate that the stream has come back online and the player can continue playback. As this usually occurs after an 'offline' event is thrown, the two events may be used in combination to provide more elaborate behaviors.

## Remarks

* On some platforms (e.g.: iPads) when the segments are unavailable, an `error` event is thrown, differently than for the majority of platforms. This inconsistency is due to the lack of MSE (and EME) support on such platforms, which triggers the more generic error event.

## Resources

The following resources provide more information:

* [Network API events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/NetworkEventMap)
* [Network: How to use the Network API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/network/introduction.md)

---

# Can we show a custom message on 403 on mp4

Yes, this is possible, but not as easy as for DASH and HLS. To address this specific use case no internal THEOplayer tool exists yet (2019) and a separate XHR call needs to be done to determine the exact status of the request. Custom texts, overlays and buttons can be showed on the player following the instructions from the related linked resource.

It is easier to address this question in two steps: detection and message.

## Detection

The current (2019) error detection and differentiation in THEOplayer is not yet as specific as we would like and as detailed as some particular use cases, such as this one, may have a use for.

For HLS and DASH, the Network API (see Resources) can be used to intercept, filter and “read” the requests one is interested in, to determine whether something should happen (an error message, for example).

This is not possible with mp4, however, as it is played natively and the Network API cannot be applied. The solution in this case is to do a separate XHR request and read its status. Something along the lines of:

```js
var XMLHttpRequestObject;
var requestObject;

function reqListener() {
  XMLHttpRequestObject = this;
}
requestObject = new XMLHttpRequest();
requestObject.addEventListener('load', reqListener);
requestObject.open('GET', 'https://httpstat.us/403?sleep=100');
requestObject.send();

XMLHttpRequestObject.status; // result should be 403 - this may be used for a control that, if true, prints on the overlay the desired error message.
```

One disadvantage of this is that additional data is requested and it may slow down the page and increase the start-up time, especially if you implement an autoplay behavior.

## Message

Back to our specific use case, once you have determined that your mp4 returns a 403 status, you will need to add a custom overlay on the player, showing a message of your choosing. This is because the generic error message “Something went wrong during native playback” that will show up is no longer editable at this point (see remarks), so you will need to cover it up with your own message. This can be done player following the instructions from the related linked resource: “Adding buttons and text to the default UI”.

## Remarks

* This specific use case is different from the more generic personalization of texts and messages on the player, that can be done through language localization (please check the linked resources). Language localization is applied at the moment in which the player instance is created, so it cannot be used to alter texts once the player has been generated.

## Resources

The following resources provide more information:

* [API reference - Network API events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/NetworkEventMap)
* [How to use Network API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/network/introduction.md)
* [What does the error message "Something went wrong with Native playback" mean?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-does-error-something-went-wrong-during-playback-mean.md)
* [Demo page - Adding buttons and text to the default UI](http://demo.theoplayer.com/adding-buttons-text-overlay-to-theoplayer)
* [How to change text in THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-change-text-in-theoplayer.md)
* [Which error related events does the player expose?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/which-error-related-events-does-player-expose.md)
* [How to do error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/error/how-to-do-error-handling.md)

---

# Can we prevent UpNext feature from redirecting

Yes, this is possible. You need to modify the countdownDuration value in your UpNextPanel to Infinity.

The THEOplayer UpNext feature is generally used to play another content or redirect to another page, after a small delay. It is also possible to simply suggest the next content, but never actually redirect to it.

This is done by setting the value of the countdownDuration property of your UpNextPanel interface to Infinity: no countdown will happen, only the play button will appear to go to the video that is up next.

## Resources

The following resources provide more information:

* [API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UpNextPanel#countdownDuration)
* [Demo page – Up Next](https://www.theoplayer.com/theoplayer-demo-up-next)

---

# Is it possible to preload VOD content while the pre-roll is playing

Yes, it is done with the preload feature. Before setting your source, you need to activate preload on your player. We advise to use the value ‘auto’: this allows the first segments of the stream to be downloaded during the ad, reducing the start-up time of the video content.

For more details regarding preload and how to implement it, please visit the resources linked below.

## Resources

The following resources provide more information:

* [Preloading - how to](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/preloading.md)
* [Demo page](https://demo.theoplayer.com/preloading-vod)
* [What are the benefits of preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-are-the-benefits-of-preloading.md)
* [API reference - PreloadType](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/PreloadType)

---

# Why is my video not playing automatically

There is a wide variety of possible causes that bring to a video not being automatically played. These may have to do with autoplay policies, iframes, Media Engagement Index and more. Please read the full answer in this article for more information. Also, please keep in mind that this is not an extensive list of causes for autoplay failure and that, as time goes by, browsers autoplay management and autoplay policies may change.

If you want your video to play automatically once the player is available, you should set the `autoplay` feature to `true`.

However, sometimes this does not lead directly to the desired result: different issues may be preventing the automatic reproduction of your video. In the following we will be listing some of the most common causes for this.

### Play

Some issues depend on the fact that autoplay is not really implemented, but the method `play()` is called on the player instead. Although in specific cases this may work, we do not advise to use this instead of the autoplay, as often this is more strictly blocked by autoplay policies and may produce, in certain cases, desync with the UI buttons (e.g.: the button suggests that the stream is playing although it’s not) or other issues.

**Solution**: for autoplay behavior, use the provided `autoplay` feature.

### Autoplay policies

Different browsers have different autoplay policies. For the specifics, please consult the policies themselves, as they may get updated. In general, though, when an autoplay policy is applied, it is possible to still autoplay a video if the player is muted.

**Solution**: to enable this, please use the `mutedAutoplay` property in your player configuration and set it to `all`.

### Chrome Media Engagement Index (MEI)

On the desktop-version of Chrome (unmuted) autoplay may also appear not to be working on your web page (while it does on your localhost). In this case the problem may be due to the Media Engagement Index. The MEI measures an individual's propensity to consume media on a site. The MEI score is highest on sites where media are played on a regular basis. When it is high enough, media playback is allowed to autoplay on desktop only.

**Solution**: the following article explains two ways to avoid this problem.

[How does Media Engagement Index (MEI) affect Autoplay on Chrome?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-does-mei-affect-autoplay-on-chrome.md)

### Iframes

When playing a video through an iframe, your autoplaying issues may be due to the iframe itself. In this case the issue comes from the fact that the iframe does not allow autoplay. Although this shouldn’t be a common problem when using a player, there have been cases in which this piece of advice was useful.

**Solution**: include the attribute `allow="autoplay"` in your iframe.

### iOS 11 and following

Apple made it that from iOS 11 and onwards autoplay is automatically muted from the start and added some settings that can remove autoplay from any site.

So it is possible that on your device autoplay is not working on Safari while it is working elsewhere.

**Solution**: check if the feature is disabled on the device. If it's explicitly disabled, the setting would be under Accessibility > Per App Settings > Add App > Safari > Safari > Auto-Playing Video Previews. Otherwise it would be enabled.

## Resources

The following resources provide more information:

* [Autoplay policy in Chrome](https://developer.chrome.com/blog/autoplay/)
* [Stop autoplay videos in Safari on Mac](https://support.apple.com/en-gb/guide/safari/ibrw29c6ecf8/mac)
* [Allow or block media autoplay in Firefox](https://support.mozilla.org/en-US/kb/block-autoplay)
* [How does Media Engagement Index (MEI) affect Autoplay on Chrome?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-does-mei-affect-autoplay-on-chrome.md)
* [API reference - mutedAutoplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerConfiguration#mutedAutoplay)
* [How to combat autoplay policies](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-combat-autoplay-policies.md)

---

# Is it possible to have multiple player instances play at the same time

Yes, this is possible, provided there are enough bandwidth and RAM for this to work (considering both server and client side). Although we don’t explicitly advise against this, we see how this could not be an ideal solution for the viewers. Please also keep in mind that this incurs into some limitations.

If your use case reckons on having multiple player instances play at the same time, this is indeed possible. In addition to the concerns expressed above, some precautions are to be considered. In fact, you may want to:

* find an alternative solution for mobile devices and in case of slow connection or low RAM, not to aggravate the user experience
* set to 0 the volume of all players (or all except one), to avoid cacophony
* consider strategies to activate and pause player instances when they are not used (e.g.: when they are out of the visible portion of the screen) to reduce RAM and bandwidth consumption
* check whether your use case can be achieved with gif replacing some of the player instances, especially in the case of short loop videos (e.g.: used as icons or to give a brief preview of your content).

One other thing to take into account are the possible platform/browser limitations.

From iOS-Specific Considerations:

> Currently, all devices running iOS are limited to playback of a single audio or video stream at any time. Playing more than one video—side by side, partly overlapping, or completely overlaid—is not currently supported on iOS devices. Playing multiple simultaneous audio streams is also not supported. You can change the audio or video source dynamically, however.

## Remarks

It is also worth mentioning that iOS loads a maximum of 16 (non-simultaneous) videos on a single web page and then gives a black display for any additional one. The page documenting this has disappeared (fall 2019), though, so this may have changed (or be changed) in newer iOS versions.

## Resources

The following resources provide more information:

* <https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/Using_HTML5_Audio_Video/Device-SpecificConsiderations/Device-SpecificConsiderations.html#//apple_ref/doc/uid/TP40009523-CH5-SW1>

---

# Is it a problem if the viewer pauses a live stream for longer than the DVR window

In general, this is no problem as the player will continue playback, once exhausted the current buffer, from the nearest point available, in this case the end of the sliding window.

The viewer may perceive this as a peculiar behavior. They will see at first a small video portion still player that connects to what they were watching before pausing the video: this is what was contained in the current buffer. Then the player will appear to seek on its own, without the user requesting it, to a new position.

In case you wish to avoid this behavior and skip the current buffer, this is also possible with a simple snippet that on resume checks whether the current position is still within the DVR window, and if it is not, then it seeks directly to a new position (without playing the current buffer).

This is a JavaScript example for this, where the DVR window is 60 sec long and the new custom position to seek to is in the middle of it.

```js
player.addEventListener('play', () => {
  player.currentTime = player.seekable.end() - player.currentTime > 60 ? player.seekable.end() - 30 : player.currentTime;
});
```

---

# THEOplayer Features & Modules

The THEOplayer SDK consists of modular features.

When building an SDK (i.e. license), you can specify which features are enabled. Only a subset of features are enabled by default, such as "HLS", "MPEG-DASH", "UI", "Chromecast", "Airplay", "Ads", and "Text Track Rendering".

This modular approach allows you to optimize the file size of your THEOplayer SDK.

## How do I enable or disable certain features?

You can do this through our [Portal](https://portal.theoplayer.com/).

![Portal: enabling features of a new SDK](/pr-932/assets/images/portal-features-new-sdk-c6a364411cedbb1fc26bdb8fd66f9631.png)

* If you're creating a new SDK, you can enable (and disable) features.
* If you want to toggle certain features for an existing SDK, you need to navigate to your SDK, update it, and re-publish it.

## My feature isn't working?

Many features sit behind this modular structure. For example, the VR API or Up Next API won't work unless you've enabled the feature when creating your SDK.

## How do I know which features are enabled?

You can log in to [portal.theoplayer.com](https://portal.theoplayer.com/) and navigate to your account. Once you're there, you further navigate to your desired SDK and check how you've customized your features.

![Portal: enabling features of a new SDK](/pr-932/assets/images/portal-features-existing-sdk-c4750657976aabfcf780be702fa46cbe.png)

If you're a developer (and you're only interested in this answer for the THEOplayer Web SDK), then you can also figure this out at runtime through JavaScript. You can call [`THEOplayer.features`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/variables/features) to identify which features are enabled.

```js
THEOplayer.features;
// (29) ["dash", "hls", "chromecast", "ads", "airplay", "yospace", "spotx", "vr", "conviva", "cache", "visibility", "webaudio", "youbora", "mediamelon", "moat", "google-dai", "streamone", "v-nova", "freewheel", "agama", "ui", "relatedcontent", "social", "upnext", "contextmenu", "texttrackstyle-ui", "activequalitylabel", "upcomingadnotification"]
```

## How do I quantify my optimizations?

After optimizing your SDK, by enabling and disabling certain features, you might want to quantify those actions.

* You could compare the file size of your THEOplayer.js files. For example, when building THEOplayer 2.78.1, with only the "HLS" and "UI" feature enabled, the library size is 315 kB. THEOplayer 2.78.1, with almost all features enabled, is almost 77% larger at 558 kB.
* You could [measure the loading time of your THEOplayer library](https://codesandbox.io/s/github/THEOplayer/samples-web?file=/reference-apps/utility/measure-loading-time/index.html).

Note that optimizing a video player goes way beyond reducing your file size. As a developer, you could consider [async library loading](https://demo.theoplayer.com/async-library-loading), you could change your [ABR strategy](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/ABRStrategyType) (as [demonstrated](https://demo.theoplayer.com/increase-viewer-experience-optimizing-video-abr)), you want to optimize your [time-to-first-frame](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/how-to-measure-time-to-first-frame.md), and much more!

---

# Chromecast on my webplayer does not work any longer despite no change in my implementation

This or a similar question may be asked in case your Chromecast stops working. There may indeed be different causes why your Chromecast is not working, especially if

* you changed or updated something in your implementation (Steps: review which change broke the feature)
* it's the first time you are trying it out (Steps: make sure your license includes the `chromecast` feature; have a look at our online documentation)
* you are trying to connect to a custom Chromecast Receiver application (Steps: check our online setup documentation and this article; check this article for a guide to debug your custom Chromecast Receiver application)

(Note: if the error is not found, please log a ticket into our service desk)

> However, in this article we are not covering all possible causes for a broken Chromecast: we are here referring specifically to a previously working implementation that has not been changed, and on which the Chromecast icon is no longer appearing.

So, if there have been no changes on your page but the Chromecast icon in your webplayer does not appear any longer, you might want to check that:

* The Chromecast device is connected and on the same network as the sender webplayer
* If on Chrome version 72.0.3626.81 or superior, you are casting over https (not on http)

Chrome does indeed no longer allow casting over http, but this will work properly over https.

---

# How to track network errors

THEOplayer currently doesn't throw an `error` event for all network request errors on all platforms. Sometimes you might want an event to listen for to track network related issues in your QoS/QoE dashboards. To enable this, you can use our Network API.

## Web

You can use the Network API as follows to track network requests with status codes 4xx and 5xx

```js
function httpErrorInterceptor(response) {
  if (response.status >= 400 && response.status <= 599) {
    var errorDetails = {
      status: response.status,
      fileType: response.request.type,
      url: response.request.url,
    };
    var networkErrorEvent = new CustomEvent('THEOnetworkerror', {
      detail: errorDetails,
    });
    document.dispatchEvent(networkErrorEvent);
  }
}

player.network.addResponseInterceptor(httpErrorInterceptor);
document.addEventListener('THEOnetworkerror', console.log);
```

## Android

For Android, you'll also use the Network API as you would with our Web SDK but you need to do it through JavaScript injection and pass a message to your Java environment. You need to follow these steps:

1. Make an `assets` folder, for instance under `android/app/src/main/assets` and add a JavaScript file, say `interceptor.js`

2. Add your network interceptor code but include a line to send a message with to be able to use the event's information in your Java code

   ```js
   function createHttpErrorInterceptor() {
     var player = THEOplayer.players[0];
     var interceptor = function (response) {
       if (response.status >= 400 && response.status <= 599) {
         var errorDetails = {
           status: response.status,
           fileType: response.request.type,
           url: response.request.url,
         };
         theoplayerAndroid.sendMessage('THEOplayer.network.error', JSON.stringify(errorDetails));
       }
     };
     player.network.addResponseInterceptor(interceptor);
     THEOplayer.HttpErrorInterceptor = interceptor;
   }

   function destroyHttpErrorInterceptor() {
     if (THEOplayer.HttpErrorInterceptor) {
       var player = THEOplayer.players[0];
       player.network.removeResponseInterceptor(THEOplayer.Interceptor_404);
       THEOplayer.HttpErrorInterceptor = undefined;
     }
   }
   ```

3. Link the JavaScript file to your THEOplayer instance as follows

   ```xml
   <com.theoplayer.android.api.THEOplayerView
       android:id="@+id/theoPlayerView"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       app:layout_behavior="@string/appbar_scrolling_view_behavior"
       app:jsPaths="interceptor.js"/>
   ```

4. In the Java file where you configure THEOplayer add the following:

   ```java
   protected void onCreate(Bundle savedInstanceState) {
       // Code to configure the player
       // ...
       // ...

       CreateInterceptor();
       SetSource();
   }

   protected void SetSource(){
       // bad url to test if the network response interceptor works
       String url =  "https://cdn.theoplayer.com/video/elephants-dream/playlist2.m3u8";

       TypedSource typedSource = TypedSource.Builder
               .typedSource()
               .src(url)
               .type(SourceType.HLS)
               .build();

       SourceDescription sourceDescription = SourceDescription.Builder
               .sourceDescription(typedSource)
               .build();

       theoPlayer.setSource(sourceDescription);
       theoPlayer.play();

   }

   protected void HandleNetworkError(String message){
       //Do something with the network error
       Log.i("THEO", "Network error: " + message);
   }

   protected void CreateInterceptor(){
       viewBinding.theoPlayerView.evaluateJavaScript("createHttpErrorInterceptor();", null);
   }

   protected void DestroyInterceptor(){
       viewBinding.theoPlayerView.evaluateJavaScript("destroyHttpErrorInterceptor();", null);
   }
   ```

## iOS

On iOS, there are platform-specific constraints that prevent us from giving you the control over network call like you can on Web. Therefore, we expose an event type for this on the network object. You can set up a listener as follows

```swift
self.player.network.addEventListener(type: NetworkEventTypes.ERROR) { (everror) in
    // handle the event
}
```

---

# What is the support for Wowza

Wowza and THEOplayer are partners in the streaming industry. When developers use both products,

* Wowza Streaming Cloud and Engine are used as the back-end to manage live streams.
* THEOplayer is used on the client-side to playout the live streams.

In this set-up, THEOplayer can play out the streams hosted by Wowza.

## Related Articles

* [Integrate Wowza with THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/integrations/wowza-streaming-engine-with-secure-token-version-2.md)

## Demo application

There is an open-source reference application at <https://github.com/THEOplayer/samples-html5-sdk/tree/master/reference-apps/wowza>. The purpose of this application is to enhance offline-to-online-to-offline transition.

## Resources

Cross-product documentation resources:

* <https://www.wowza.com/blog/wowza-streaming-cloud-getting-started>
* <https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine>
* <https://www.theoplayer.com/blog/theoplayer-joins-wowza-media-systems-technology-alliance-partner-program>

---

# How to use the CDN fallback/backup stream feature

THEOplayer offers a feature to detect more sources of content in manifest or playlist, so that the player can automatically switch to a fallback URL, in case any of the main content source is unavailable or not reachable. This feature works for both MPEG-DASH and HLS streams out of the box, and does not require any additional configuration to the player.

## For MPEG-DASH Streams

MPEG-DASH allows you to define multiple `<BaseURL>` elements, which points towards the root source of the content. By default, the player starts playing using the first BaseURL but if it is no longer available or not reachable, player automatically tries to use second url available. The `<BaseURL>` can be added at different layers, it is recommended to provide it on the `<MPD>` or `<Period>` level like an example below:

```xml
<?xml version="1.0"?>
<MPD type="static" ...>
	<BaseURL>https://example.com/path/to/your/content/cdn1</BaseURL>
	<BaseURL>https://example.com/path/to/your/content/cdn2</BaseURL>
	<BaseURL>https://example.com/path/to/your/content/cdn3</BaseURL>
	<Period>...</Period>
</MPD>
```

## For HLS Streams

As per HLS Specification for Apple Devices, playback on stream failover for a rendition is supported, if a redundant variant stream with a different URI is available in the manifest. A variant stream is considered to be redundant, if it has the exact same EXT-X-STREAM-INF tag as the original one. In case the first occurrence of the variant stream is unavailable or not reachable, player by default would use the redundant variant stream for continuing playback. An example of the manifest is like below:

```text
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-STREAM-INF:BANDWIDTH=2689440,CODECS="avc1.100.31,mp4a.40.2",RESOLUTION=1120x700
../../687317/6059a27e_1_2728/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=2689440,CODECS="avc1.100.31,mp4a.40.2",RESOLUTION=1120x700
../../687317-b/6059a27e_1_2728/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1808481,CODECS="avc1.77.40,mp4a.40.2",RESOLUTION=768x480
../../687317/6059a27e_1_1728/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1808481,CODECS="avc1.77.40,mp4a.40.2",RESOLUTION=768x480
../../687317-b/6059a27e_1_1728/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1225508,CODECS="avc1.77.32,mp4a.40.2",RESOLUTION=576x360
../../687317/6059a27e_1_1152/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1225508,CODECS="avc1.77.32,mp4a.40.2",RESOLUTION=576x360
../../687317-b/6059a27e_1_1152/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=712202,CODECS="avc1.66.30,mp4a.40.2",RESOLUTION=460x288
../../687317/6059a27e_1_640/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=712202,CODECS="avc1.66.30,mp4a.40.2",RESOLUTION=460x288
../../687317-b/6059a27e_1_640/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=560232,CODECS="avc1.66.30,mp4a.40.2",RESOLUTION=288x180
../../687317/6059a27e_1_448/chunklist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=560232,CODECS="avc1.66.30,mp4a.40.2",RESOLUTION=288x180
../../687317-b/6059a27e_1_448/chunklist.m3u8
```

## Resources

* [Apple Variant Stream Documentation](https://developer.apple.com/documentation/http_live_streaming/example_playlists_for_http_live_streaming/creating_a_master_playlist)
* [MPEG-DASH Base URL Documentation](https://dashif.org/docs/DASH-IF-IOP-v4.3.pdf)

---

# How to apply accurate buffering strategy

By default, THEOplayer buffers 20 seconds of video including audio/subtitles in order to guarantee smooth playout. THEOplayer (alike other Web players) is relying on [HTML SourceBuffer API](https://developer.mozilla.org/en-US/docs/Web/API/SourceBuffer) for buffering purposes. Unfortunately there is no method which informs you how big the buffer size of given browser/device is. Of course, it can be different for device, and even browser. In consequence in edge circumstances might happen that the following error is encountered: `Player error: Failed to execute 'appendBuffer' on 'SourceBuffer': The SourceBuffer is full, and cannot free space to append additional buffers.`

## Proactive strategy

One of the approach to deal with above issue is to apply proactive strategy which adjust `player.abr.targetBuffer` depending on what quality is currently used. The below table presents what approximately bandwidth is required for video streaming:

| Resolutions     | Required Bandwidth (H264) | Required Bandwidth (H265) |
| --------------- | ------------------------- | ------------------------- |
| 1280x720 (HD)   | 3Mbps                     | 1.5Mbps                   |
| 1920x1080 (FHD) | 6Mbps                     | 3Mbps                     |
| 3840x2160 (UHD) | 25Mbps                    | 12Mbps                    |
| 4096x2160 (4K)  | 32Mbps                    | 15Mbps                    |

Taking above table into account, the logic responsible for the proactive strategy can look like:

```javascript
player.addEventListener('representationchange', function (event) {
  // specifies how big bandwidth is required for the current quality
  var representationBandwidth = event.representation.bandwidth;
  // player.abr.targetBuffer is 20 by default
  var targetBuffer = player.abr.targetBuffer;

  // SD
  if (representationBandwidth < 3000000) {
    targetBuffer = 20;
  } else if (representationBandwidth > 3000000 && representationBandwidth < 6000000) {
    // HD
    targetBuffer = 10;
  } else if (representationBandwidth > 6000000) {
    //FHD, UHD, 4K
    targetBuffer = 5;
  }

  player.abr.targetBuffer = targetBuffer;
  console.log('representationchange - updated player.abr.targetBuffer: ' + player.abr.targetBuffer);
});
```

Please note that the above numbers should be adjusted depending on the video content used.

## Resources

* [Bandwidth Required For HD FHD 4K Video Streaming](https://www.synopi.com/bandwidth-required-for-hd-fhd-4k-video/)

---

# How can I distribute 4K content?

The ability to play 4k mostly depends on hardware. While the video player is responsible for passing on the data to the decoders, limitations to 4K playback often stem from the device, hardware, operating system or platform (e.g. Chrome, iOS app, Android TV app, ...). When either of these is unable to handle 4K content, you might be out of luck. It's important to ensure all of these boxes are checked.

*Why?* Streams above 1080p, like 4K (i.e. 2160p) and 8K, are usually packaged through codecs like HEVC (H.265), VP9 and AV1. Your device, hardware, operating system or platform might not be able to decode the selected codec. For example, Chrome lacks support for decoding HEVC. It's also possible that your platform doesn't support a specific codec profile or feature (e.g. HDR through Dolby Vision at 60fps) of a selected codec. While technically you can also do 4K streaming with AVC (H.264), it is often too inefficient from a bandwidth perspective. We will leave this out of scope for the remainder of the document.

## Common issues when playing 4K content

Let's zoom in on our previous statement:

> Limitations to playback of 4K often stem from the device, hardware, operating system or platform.

One of these individual components could be disrupting support for 4K streaming.

* Device ─ Your device might not have the capabilities to render the codec which represents your stream, or you might be using a model which doesn't support the selected codec. For example, Chromecast devices from Generation 1, 2, 3 and 4 only support H.264 and VP8 up until 1080p, and don't offer any support for 4K. However, the [Chromecast Ultra](https://developers.google.com/cast/docs/media#video_codecs) does offer 4K streaming through HEVC and VP9 including HDR at 60fps.
* Hardware ─ You might be connecting a device to a monitor incapable of rendering 4K, or you might be using a cable which cannot transfer your stream at the required rate. The leveraged hardware will usually downscale your video or even provide no feed at all.
* Operating System & Environment ─ Your operating system might not offer decoding support for a specific codec. For example, Apple didn't add support for 4K to iPhones until iOS 11 through HEVC. Chrome still doesn't support HEVC across any platform (except for on the iOS platform), and you have to use VP9 or AV1 to decode a 4K stream when using the browser.
* Platform ─ Your platform might not offer decoding support for a specific codec. For example, Android offers decoding support for 4K through HEVC through Android applications, but not through Android browsers like Chrome.

## 4K supported platforms

It's tough to provide a global view on platforms which support 4K streaming. In theory, you would have to maintain an overview of all supported codecs (and codec profiles and features) per version per model per platform. You could then consult this overview to check if your selected codec (and profiles/features) are supported on your targeted platforms. This overview would be challenging to maintain, because updates to platforms change the support for certain codecs, and new models of a specific platform could offer different support for a specific codec. For example, while the Chromecast Generation 4 offers no support for 4K through HEVC, Chromecast Ultra does.

Please consider the table below as a generic snapshot in time. The platforms below can handle 4K streaming, but only if the appropriate codecs, platform versions and device (models) are used. It's perfectly possible that you're not able to get your 4K stream to run on one of the platforms listed below, for example because you're using an unsupported codec.

| Platform                                                                                        | Notes                                                                                                   | THEOplayer SDK          |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------- |
| Browser                                                                                         | Depends on the device, browser and codec                                                                | Web SDK                 |
| [iOS](https://www.apple.com/iphone/)                                                            | Depends on the device and codec, but could support:<br />HDR10, Dolby Vision, HEVC                      | iOS/tvOS SDK            |
| [iPadOS](https://www.apple.com/ipad-pro/specs/)                                                 | Depends on the device and codec, but could support:<br />HDR10, Dolby Vision, HEVC                      | iOS/tvOS SDK            |
| [Apple TV](https://www.apple.com/lae/apple-tv-4k/specs/)                                        | Depends on the device and codec, but could support:<br />HDR10, Dolby Vision, HEVC SDR with 60fps, HEVC | iOS/tvOS SDK            |
| [Android](https://developer.android.com/guide/topics/media/media-formats)                       | Depends on the device and codec                                                                         | Android/Fire TV SDK     |
| [Android TV](https://developer.android.com/guide/topics/media/media-formats)                    | Depends on the device and codec                                                                         | Android/Fire TV SDK     |
| [AirPlay](https://www.apple.com/airplay/)                                                       | Depends on the device and codec                                                                         | Web SDK, iOS SDK        |
| [AirPlay 2](https://www.apple.com/lae/ios/home/accessories/#section-tv)                         | Depends on the device and codec                                                                         | Web SDK, iOS SDK        |
| [Chromecast Receiver](https://developers.google.com/cast/docs/media)                            | Depends on the device and codec, but could support:<br />HDR10, Dolby Vision, HEVC, VP9, 60fps          | Web SDK, Chromecast SDK |
| [Chromecast TV](https://www.google.com/chromecast/built-in/tv/)                                 | Depends on the device and codec.                                                                        | Web SDK, Chromecast SDK |
| [Fire TV](https://developer.amazon.com/docs/fire-tv/device-specifications.html)                 | Depends on the device and codec, but could support:<br />HDR10, Dolby Vision, HEVC, VP9, AV1, 60fps     | Android/Fire TV SDK     |
| [Roku](https://developer.roku.com/en-gb/docs/specs/streaming.md)                                | Depends on the device and codec, but could support:<br />HDR10, Dolby Vision, HEVC, VP9, 60fps          | Roku SDK                |
| [Tizen](https://developer.samsung.com/smarttv/develop/specifications/media-specifications.html) | Depends on the device and codec, but could support:<br />HEVC, VP9, AV1, 60fps, 8K                      | Web SDK                 |
| [webOS](https://webostv.developer.lge.com/develop/specifications/video-audio-230)               | Depends on the device and codec, but could support:<br />HEVC, AV1, 60fps, 8K                           | Web SDK                 |
| [Xbox](https://www.xbox.com/en-US/consoles/xbox-one-x)                                          | Depends on the device and codec                                                                         | Web SDK                 |
| [PlayStation](https://www.playstation.com/en-us/ps5/ps5-entertainment)                          | Depends on the device and codec                                                                         | Web SDK                 |

As this table is in flux, when you decide to implement 4K we encourage you to investigate if anything has changed for the platforms you are targeting (tip: searching for keywords like "Chromecast Media Capabilities 4K" often provides good results) or to reach out to the THEO support team with specific questions.

## Video players and decoding

Video players usually don't do software decoding and instead rely on the native decoding capabilities offered by the selected platform through a native API as player-based decoding would be highly inefficient for power consumption and often requires a lot of computational performance. For example, on Desktop Chrome, video players leverage the [Media Source Extensions API](https://developer.mozilla.org/en-US/docs/Web/API/Media_Source_Extensions_API) to decode the actual H.264 (or VP9 or AV1 or ...) codec representing your stream.

That being said, a video player might still be the one to blame when your viewers aren't seeing the beautiful 4K representation of your stream. Your video player should be able to correctly parse, extract and leverage the 4K stream from your HLS or MPEG-DASH manifest when your 4K representation can be applied. This functionality might not be implemented in your video player.

THEOplayer supports 4K streaming out of the box. For specific devices, specific configuration recommendations can apply in order to achieve 4K streaming efficiently.

---

# What is the collaboration between Azure Media Services and THEOplayer

> **Warning**
>
> Azure Media Services has been retired since June 30th, 2024.

Azure Media Services has a rich ecosystem of partners that provide their customers with the flexibility of choosing the best solution for their needs.

### What is the collaboration about?

Azure Media Services supports all the popular streaming formats including Microsoft Smooth Streaming, MPEG-DASH and HTTP Live Streaming (HLS). Azure Media Services also provides Microsoft Azure Media Player, a cross-platform HTML5 player framework that plays back content streamed from Azure Media Services.

With the collaboration with THEOplayer, customers now have an additional choice of using a proven and integrated fully HTML5-based player that can playback HLS or LL-HLS on all popular platforms without the need for any plug-ins.

### How can I use THEOplayer with AMS?

Azure Media Services has set up a GitHub repository to help get users started. Here, users can insert the streaming URLs they get from the Microsoft Azure Management portal and see them in action. They can also find all the information on getting started with THEOplayer.

* <https://github.com/Azure-Samples/media-services-3rdparty-player-samples/tree/master/docs/THEOplayer>

---

# Is Portrait mode supported

Yes. THEOplayer supports vertical video playback, which is also known as portrait mode.

More specifically, you can configure the aspect ratio of the container which holds the THEOplayer video player instance.

* If your video is shot in 9:16 (i.e. portrait), you can configure your container to respect this aspect ratio, and THEOplayer will fill the container.
* If your video is shot in 16:9 (i.e. landscape), you can configure your container to respect this aspect ratio, and THEOplayer will fill the container.

Of course, you can also configure your container to respect any other aspect ratio, like 5:4, which is employed by Instagram.

## Demo

A demo is available at <https://cdn.theoplayer.com/demos/vertical/index.html>. This demo provides a sample implementation which allow you to switch between popular viewing modes. This demo is best viewed on a mobile browser.

![Screenshot of Portrait Mode](/pr-932/assets/images/screenshot_portrait_mode-0633aae3f80f661cad0ea0595a439820.png)

---

# How to prevent screen recording

This article explains what screen recording is, and how to counter it.

## What is screen recording

We define "screen recording" (also known as "screen capturing") as the malpractice of illegally recording video streams on a website or application of a content provider.

* These screen recordings may be redistributed on platforms which are not owned by the content provider.
* This unconsented redistribution may impact the business of the content provider.

Screen recordings - and redistribution of screen recordings - is considered a major, (arguably) unsolved issue in the video industry. All content providers - including Netflix, Disney+ and Hulu - struggle to counter screen recordings. Most popular providers employ strategies to counter screen recordings, or to reduce the impact of screen recordings.

Creating a screen recording doesn't have to be difficult.

* The camera of a smartphone can be aimed at a screen. Your screen wouldn't know that a smartphone is recording it.
* The record function of Apple's QuickTime Player (or Window's Xbox Game Bar) can be used to record video content playing on Chrome on Windows, macOS and Linux. Chrome on Windows, macOS and Linux doesn't offer a native mechanism to prevent screen recording, even when DRM protects the content.

The quality (and bitrate) of a video stream degrades through a screen recording, which is a useful property when the recording leaks.

Details

Screen recording versus downloading

We do not define "screen recording" as the malpractice of illegally downloading and/or decrypting the original video streams on the website or application of a content provider.

* For example, if a pirate (i.e. a user with the intention to steal and/or illegally redistribute content) downloads the source files of an HLS stream (and perhaps removes the encryption), then they are not doing "screen recording".
* On the other hand, if a "pirate" uses QuickTime Player to record their screen (which is playing a video in Chrome), then they are doing "screen recording".

## How to counter screen recording

There are strategies to prevent screen recordings, and strategies to cope with screen recordings.

* A preventive strategy involves making it more challenging to create screen recordings. (e.g. DRM, plug-ins)
* A coping strategy involves responding to unprevented screen recordings. (e.g. watermarking, limited quality)

You want to consider both strategies as a content provider.

### Strategies to prevent screen recording

Strategies such as [using DRM](#drm) and [restricting the allowed platforms](#restrict-allowed-platforms) make it more challenging to create a screen recording.

However, never assume that you can make screen recording impossible, as "content pirates" will keep identifying and using workarounds. For example, a common workaround is "Digital-to-Analog", where a smartphone camera could record a screen. Alternatively, dedicated hardware may also be able to screen recording, such as an HDMI recorder which does follow HDCP, but uses leaked certificates to record the output regardless.

#### DRM

Using an appropriate multi-DRM set-up prevents screen recording. Many devices and platforms allow you to configure FairPlay, PlayReady and Widevine in such a way that the device and platform automatically prevents screen recording tools. These configurations rely on the availability on support for hardware DRM.

Reach out to your multi-DRM provider to understand which options they offer to prevent screen recordings, and how these options affect your targeted platforms.

The following statements are generally true for multi-DRM:

* You can prevent screen recordings on platforms which support hardware DRM. The list below represents a set of popular platforms which support hardware DRM:

  * Windows Edge
  * macOS Safari
  * iOS and iPadOS, both for apps and browsers
  * Android, but only for apps
  * Chromecast

* You cannot prevent screen recordings on platforms which do not support hardware DRM. The list below represents a set of popular platforms which do not support hardware DRM:
  * Chrome browsers (neither Windows nor Apple), because this platform only supports Widevine L3 (and not Widevine L1)

#### Restrict allowed platforms

The previous section establishes that you can prevent screen recordings on many platforms, but not all platforms. As a content provider, you could decide to only distribute your content on the set of platforms which allow for the prevention of screen recording through multi-DRM.

In this strategy, you could be forcing users to use another platform than their preferred choice. For example, disallowing your viewers to use Chrome, means that about 50% of your browser viewers need to switch to another browser.

#### Conclusion on the prevention of screen recording

There are other strategies beyond only allowing your users to watch content on platforms where DRM prevents screen recording.

* For Desktop users, you could try to force your viewers to install a desktop app which prevents screen recording. For example, you could offer a HTML5 Electron app which utilizes the [`setContentProtection`](https://www.electronjs.org/docs/api/browser-window#winsetcontentprotectionenable-macos-windows) method to prevent screen recording.

* You could try to use technology which prevents screen recording through third-party plugins.

  * This approach (usually) requires the viewer to install an additional piece of software.
  * For example, the viewer may have to install a Chrome extension which monitors computer services, and prevent video playback.

* You could try to use technology which renders the video in such a way that screen recording programs cannot properly capture the video.

The arguably primary industry problem w\.r.t. screen recording is the prevention of screen recording on Chrome for Windows and Apple machines, due to the sheer popularity of this platform. Should Windows and Apple add support for Widevine L1, then screen recording becomes more challenging on Chrome. This change would grant a large coverage of protection on the browser market through multi-DRM.

That being said, platform developers are engaging in efforts to make hardware DRM available on an increasing amount of platforms.

### Strategies to cope with screen recording

When you are not able to prevent screen recording, you can employ strategies to cope with it. For example, you can use [watermarking](#watermarking), or only [allow a limited stream quality](#restrict-qualities) on platforms which cannot prevent screen recording.

#### Watermarking

A forensic or digital watermark allows you to embed an identifier in a video stream. You can trace the identifier of a leaked screen recording. This tracking allows you to take punitive actions towards users who created the screen recording.

A forensic watermark should be imperceptible and robust.

* It should not be possible to visually recognize the watermark.
* It should not be possible to remove the watermark.

#### Restrict qualities

You can restrict the available video stream quality to users. For example, if your viewer is accessing the video stream on a platform which doesn't prevent screen recording through DRM, you don't allow them to access any quality above 720p. (*This is a popular strategy among top content providers, including Netflix and Disney+.*)

A low-quality, leaked recording (which is even further degraded through the recording process) may reduce its appeal.

#### Conclusion on coping with screen recordings

Watermarking and restricting the quality allow you to react to leaks, and to further reduce its impact.

You may also consider different strategies to reduce the impact of screen recordings. For example, an AVOD business model would arguably suffer less from this, because viewers can access your content for free, but you would monetize it through advertisements.

## Video players and screen recording

The influence of a video player on the prevention of screen recording is mainly through its support for DRM. Meaning, a video player can "indirectly" support the prevention of screen recording, if the video player is running on a website or app where screen recording is not allowed by the platform due to the employed DRM strategy.

For example,

* a video player prevents the screen recording of HLS streams protected with FairPlay on macOS, because the macOS platform prevents this for FairPlay on Safari.
* a video player does not prevent the screen recording of MPEG-DASH streams protected with Widevine on macOS, because the macOS platform doesn't prevent this for Chrome.

The technological limitations of a platform are also the technological limitations of a video player. The strategies discussed in this article are used in combination with a video player, but they are not the responsibility of a video player. For these strategies to work, the implementation and configuration of additional components (e.g. multi-DRM, watermarking, third-party plugin) is mandatory. These components are not offered by a single video player SDK out-of-the-box. This means that you have to combine a video player which external components.

### THEOplayer and screen recording

The previous section explains that video players indirectly prevent screen recordings when using the appropriate multi-DRM set-up. This statement is also true for THEOplayer.

Additionally, THEOplayer is partnered with vendors which offer multi-DRM and watermarking. These partners are listed at <https://www.theoplayer.com/partners>.

## Conclusion

You should tailor your strategy to your needs. Four valid strategies are listed below.

1. Do prevention through DRM, and coping through watermarking and restricting the qualities. On platforms which do not prevent screen recording through DRM, you limit your video quality (e.g. 720p). If a screen recording leaks, you have reduced the impact. Additionally, through the watermark, you can identify the source of the leak. This strategy might frustrate viewers, because they might not be able to view the best quality on their preferred platform. (*This approach is used by popular streaming services, including Netflix.*)

2. Do prevention through DRM and restricting the allowed platforms, and coping through watermarking. You don't allow viewers to watch your content on platforms which do not prevent the screen recording of DRM-protected streams. You identify the source of leaks through watermarks. This strategy might frustrate viewers, because they might not be able to view the stream on their preferred platform.

3. Do prevention through DRM and plugins, and coping through watermarking. You force viewers to install a plugin to view the stream on a platform which don't prevent the screen recording of DRM-protected streams. You identify the source of leaks through watermarks. This strategy might frustrate viewers, because they need to install a plugin to view the stream on their preferred platform.

4. Do coping through watermarking. This strategy doesn't prevent screen recording, but doesn't frustrate viewers. You identify the source of leaks through watermarks.

---

# The provided video source is incompatible with the license for this player

The player throws this error when the source of the player is incompatible with the license. This occurs when the domain of the source is not in the list of source domains of the license. For example, when you have **yourfirstcdn.com** and **yoursecondcdn.com** as source domains, but you use a video stream (i.e. source) from **<https://yourthirdcdn.com/video.m3u8>**, then the player will throw the above error because **yourthirdcdn.com** is not included in the source domains (**yourfirstcdn.com** and **yoursecondcdn.com**).

To resolve this issue you can do the following:

* Use another source which is compatible with your SDK.
* Verify the source domains of your SDK on the [Developer Portal](https://portal.theoplayer.com).
* Change the source domains of your SDK to whitelist all domains.

Additionally, you could see this error on an edge case where you are setting a `source` object with an empty `source` URL but with any other valid URL, such as a `poster`. In this case, since the source object passes a valid URL, the license check would be triggered and the empty array would cause to return this error. To work around this, you could consider setting both the `source` and any other URL contained at the same time or if possible, setting the other URLs outside the source object to avoid license check with an empty source.

---

# Page and Source domains

Page and Source domains prevent unauthorized users from embedding your SDK on their website. We highly recommend configuring both Page and Source domains carefully to protect your THEOplayer license.

## Page domains

Page domains (available only on Web SDK, React Native SDK and Flutter SDK) specify on which domains the player can be loaded.

Imagine your website has the following domain: `example.com`, you have configured your Page domains and the THEOplayer SDK is installed on your website. When a malicious user copies your SDK and installs it on their domain, `other.com`, the player will throw an error that the license is invalid.

Whitelisting `example.com` will also whitelist all its subdomains such as `a.example.com` or `a.b.example.com` so you don't have to enter each of them one by one. Please note that whitelisting `*.example.com` *will not* whitelist the subdomains.

Your page domains are included on your player [license](https://www.theoplayer.com/docs/theoplayer/how-to-guides/license/introduction/). If you make any changes on your page domain configuration, you should update the license on your website.

## Source domains

Source domains specify from which domains the player is allowed to play streams. When the Source domains are configured to `example.com` the player will only play streams from this domain. If the player attempts to play a stream from `other.com`, it will result in an error stating that the license is invalid.

Similar to Page domains, whitelisting `example.com` will also whitelist all its subdomains such as `a.example.com` or `a.b.example.com` so you don't have to enter each of them one by one. Please note that whitelisting `*.example.com` *will not* whitelist the subdomains.

Your source domains are included on your player [license](https://www.theoplayer.com/docs/theoplayer/how-to-guides/license/introduction/). If you make any changes on your source domain configuration, you should update the license on your application/website.

## How to configure Page and Source domains

Page and Source domains can be configured in the [Developer Portal](https://portal.theoplayer.com) when creating a license or a custom SDK. On an existing license/SDK, you can find the Page and Source domains under the “Configure” section of the SDK overview page. The “Allow all” option can be selected when you are not certain on which domains the player will be loaded or from which domains the player will play streams. This option is separately configurable for both Page and Source domains.

---

# What does the error message “Something went wrong determining the initial period of the provided MPEG-DASH stream” mean

This error, "Something went wrong determining the initial period of the provided MPEG-DASH stream", occurs whenever the player struggles to play a DASH stream due to problems determining the availability of the segments for that stream. The recommended solution for this is to make sure that the segments result available, based on the data provided in the manifest, at the time at which the manifest is requested.

## Long Answer

A number of fixes and improvements we made available in several releases throughout 2020 brought THEOplayer to apply the DASH specification regarding segments availability more strictly than in previous versions. In other words, the player now requires, for successful playback, that the manifest indicates correctly the availability of segments. This is especially relevant for dynamic Media Presentations (MPD\@type="dynamic").

**How to check whether your segments are available at the right time** For the segments to be correctly played, they must be available at the time when the manifest is requested/served. In other words,

*“start of segment availability” < “manifest is requested/served” < “end of segment availability”*

How is the segment availability time calculated? The DASH specification indicates that:

> For services with MPD\@type='dynamic', the Segment availability start time of a Media Segment is the sum of
>
> * the value of the MPD\@availabilityStartTime,
> * the PeriodStart time of the containing Period as defined in 5.3.2.1,
> * the MPD start time of the Media Segment, and
> * the MPD duration of the Media Segment.
>
> \[…] The Segment availability end time of a Media Segment is the sum of the Segment availability start time, the MPD duration of the Media Segment and the value of the attribute @timeShiftBufferDepth for this Representation.
>
> If the @availabilityTimeOffset attribute is present for a Representation, then the adjusted segment availability start time is determined by subtracting the value of @availabilityTimeOffset from the Segment availability start time. This adjusted segment availability start time provides a time instant in wall-clock time at which a Segment becomes an available Segment. Note that if the @availabilityTimeComplete flag is set to true for such a Representation, then the entire Segment may not yet be available at the adjusted segment availability start time.

---

# Why is my PlayReady stream not working in Chromium Edge?

If you are having problems playing PlayReady streams in Chromium Edge, this may be due to a conflict between player and browser, regarding the DRM system to use. If this is the case, you may solve the issue indicating PlayReady as your first option with the [*preferredKeySystems* property](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/DRMConfiguration#preferredkeysystems).

## Long Answer

Chromium Edge supports both PlayReady and Widevine DRM systems and by default both flags are active (<edge://flags/>) - see *Related issues* for exceptions.

In 2.78, we fixed an issue that was preventing specific streams to play in Edge Chromium with PlayReady (in certain cases) and with Widevine (in other cases) when both flags were enabled on the browser. In recent versions of the player, we also added the property *preferredKeySystems* (documentation linked above), which helps the player choose the preferred DRM system.

We noticed that, due to their default settings, a conflict arises (regarding which DRM system is to be given priority) between the player and the browser. This may lead to playback failure for certain PlayReady streams. This is solved directly on the implementer’s side by using the following values order for the *preferredKeySystems* property.

```js
preferredKeySystems: ['playready', 'widevine', 'fairplay'];
```

Please note that this will not hinder playback in case also/only Widevine is present, nor on other browsers.

### Related issues

In the same use cases, playback may also fail on the user’s side due to other causes, independent of the player, for example:

* the flag for the DRM system used in the current DRM configuration in the *player.source* is disabled
* the machine/platform/browser version does not provide full support for a certain DRM system. For example, you can check the following link for PlayReady: <https://testweb.playready.microsoft.com/Tool/Hwdrm>
* other issues related to the stream, DRM system or server

---

# Which subtitle and CC formats are supported on native Safari

The Safari browser on iOS uses the native Safari video player. Safari on the desktop also uses its native player when using FairPlay or when the `useNativePlayback` flag is enabled.

### WebVTT

For displaying webvtt subtitles, Safari on iOS requires the `SUBTITLES` attribute in the `EXT-X-STREAM-INF` tag of the m3u8 file. This `SUBTITLES` attribute is optional on browsers such as Chrome and Firefox and when Safari does not use its native video player.

### TTML

TTML subtitles aren't supported through native Safari. However, THEOplayer should be able to handle TTML subtitles on desktop Safari as long as FairPlay is not being used and the `useNativePlayback` flag is not enabled.

### CEA608 and CEA708

CEA608 and CEA708 subtitles are supported.

## Known Limitation

When multiple subtitles with mode `hidden` are configured, only one will fire its events such as `addcue` and `cuechange` when using Safari's native player.

## Resources

The following resources provide more information:

* [HLS Specification - #EXT-X-STREAM-INF](https://datatracker.ietf.org/doc/html/rfc8216#section-4.3.4.2)
* [THEOplayer introduction to subtitles and closed captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/subtitles-and-closed-captions/introduction.md)
* [THEOplayer introduction texttracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/introduction.md)

---

# How to navigate through the documentation and resources

THEOplayer offers documentation and resources through a number of channels.

* The central THEO documentation at <https://docs.theoplayer.com> contains

  * Getting started guides that help you set up a THEOplayer SDK or framework (e.g. [Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md), [React Native](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/frameworks/react-native/getting-started.md), ...)
  * How-to guides articles that cover specific topics (e.g. [how to do ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/introduction.md), [how to do DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md), [how to detect the active video quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-qualities.md), ...)
  * FAQ articles that address specific questions (e.g. [what is an impression](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-is-an-impression.md), [is portrait mode supported](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/is-portrait-mode-supported.md), ...)
  * Knowledge base articles that explain media streaming concepts or related topics (e.g. [AES-128](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/content-protection/aes-128-encryption.md), [CORS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/cors/introduction.md), ...)
  * [Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog.md) that lists the release notes of our SDKs
  * API references that document APIs per SDK (e.g. [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web), [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android))

* Our GitHub at <https://github.com/THEOplayer> contains

  * Samples for all SDKs (e.g. [Basic playback in Android](https://github.com/THEOplayer/samples-android-sdk/tree/master/Basic-Playback), [Google IMA in iOS](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Google-IMA), ...)
  * Sample connectors to integration analytics (e.g. [Conviva](https://github.com/THEOplayer/sample-conviva-analytics-html5-sdk)) and [DRM connectors](https://github.com/THEOplayer/samples-drm-integration)
  * Sample integrations for development frameworks (e.g. [Next.js with TypeScript and NPM](https://github.com/THEOplayer/samples-nextjs/tree/master/typescript-npm))

* Web demos at <https://www.theoplayer.com/demo-zone>

* White papers, webinars, blog posts and more at <https://optiview.dolby.com/resources/blog/>

Customers manage their THEOplayer SDKs through the THEOplayer Developer Portal at <https://portal.theoplayer.com>. You can also use this portal to view your impressions or to acquire (or manage) a support plan.

A support plan gives you access to our Jira Service Desk at <https://servicedesk.theoplayer.com/>. Refer to "[How to create a (great) ticket](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-create-a-ticket.md)" for more information on creating tickets through our Service Desk.

---

# How to create a (great) ticket

Customers can create tickets through our Jira Service Desk at <https://servicedesk.theoplayer.com>. You can obtain a Service Desk account by purchasing a [support plan](https://www.theoplayer.com/supportplans) through <https://portal.theoplayer.com>, or by [contacting our Sales team](https://www.theoplayer.com/pricing).

## Creating a ticket

You use our Jira Service Desk to create tickets and collaborate with our team.

When you go to <https://servicedesk.theoplayer.com>, you'll be asked to enter your credentials. Afterwards, you must locate the *"Need to raise a request? Contact us."*-button, and click it. This action will take you to <https://opentelly.atlassian.net/servicedesk/customer/portal/1/group/1/create/150>, as illustrated by the screenshot below.

![THEOplayer Jira Service Desk](/pr-932/assets/images/jira-service-desk-92889fe2bf14999ebf74156adee051f1.png)

Enter a clear summary, select the appropriate request type, and enter a valuable description.

* Select "Information" as the request type when you're not sure how to implement a specific feature, or when you're not sure whether something is a bug or a feature request.
* Select "Bug" if you think your issue is due to a bug introduced by THEOplayer.
* Select "Feature" if you want to request a change or feature.
* Select "Renewals/Licensing" if you have license issues, or questions about your license.

### Creating a great ticket

A great ticket makes your life - and our life - easier. The collaboration will go smoother, and your tickets will be resolved faster.

A great ticket is **C.R.U.S.P.** (= Collaborative, Reproducible, Use Case, Specific, Proven).

**Collaborative** | Be a team player.

* Include resources that help us understand your ticket. (For example, when documenting a difficult to reproduce bug, attach a [Loom](https://www.loom.com/) video.) Things that are obvious to you, might not be obvious to us.
* Refer to other tickets when they're related.
* Refer to documentation and samples that you think are related.
* Not sure if "something" it's relevant? Mention it regardless.

**Reproducible** | Provide simple & reliable reproduction steps and resources.

* Don't send us the link to your website. Instead, set up a simple reproduction page on <https://codepen.io> or <https://replit.com>.
* Don't send us your .apk or App Store URL. Don't send us complex code bases. Instead, fork our GitHub reference apps (e.g. [Basic Playback for iOS](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Basic-Playback)), include your code that allows us to reproduce the issue, and forward it to us.
* Don't send us obfuscated, minimized or transformed (e.g. Webpack) code. Use simple code in simple environments.
* Ensure that your streams are reliable. Streams that can expire introduce significant overhead and will slow down the resolution time.
* Issues that you (or we) cannot consistently reproduce introduce significant overhead and may be rejected. Identify and describe consistent reproduction steps.
* Avoid credentials, VPNs or geo-restrictions as they introduce significant overhead. (If it's mandatory: specify this in every ticket. Although we might remember it recall it from your other tickets, don't assume that we remember them. Our team is spread over hundreds of customers and thousands of tickets.)

**Use case** | Provide sufficient context.

* What is the use case you're trying to achieve? *Why* are you interested in using this API or feature?
* Providing context helps our team to tailor their answers, recommendations and alternatives. We want to understand your big picture -- give us chance.

**Specific** | Be as specific and detailed as you can.

* Which SDK are you using? Which version?
* What browser or platform is relevant? Which version?
* What is the current behavior? What is the expected behavior?
* What is the reproduction stream? What are the reproduction steps?

**Proven** | Provide as much self-research as possible.

* What have you done to troubleshoot it yourself?
* What happens if you try the latest version of THEOplayer? (Or an older version of THEO?)
* What happens if you try another player (e.g. Safari, Dash.js, ...)?
* What happens if you try another (third-party) stream?
* What happens if you try to implement it in a different way?
* What happens if you try another version of your platform?
* How do you know that the issue is related to THEOplayer?

## Remarks

* Avoid using emails if you're an existing customer. Emails get lost and people are bottlenecks. (Only use emails to refer to tickets when needed.)
* Refer to our article on ["How to investigate a ticket"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-investigate-a-ticket.md) if you are interested in understanding how process your ticket. (You might also find this article interesting if you want to improve your troubleshooting capabilities!)

---

# How to investigate a ticket

This article describes how our team typically investigates an issue (i.e. bug) reported to us through a Service Desk ticket. We encourage you to go through these steps before creating a ticket, and to document your findings in your ticket.

## Prerequisites

* The ticket is well-described and/or [C.R.U.S.P.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-create-a-ticket.md#creating-a-great-ticket).

* The reported 'Current behavior' can be easily understood.
  * Illustrations, screenshots or screen recordings are provided to further elaborate on the issue.

* The reported 'Expected behavior' can be easily understood.

  * The affected SDK(s) are correctly labeled.
  * (The affected browsers are correctly labelled.)

* A reliable and simple reproduction page, stream or application has been shared.
  * Customer-specific application logic has been stripped when a reproduction page or application has been shared.

## Guide

Investigating an issue typically consists of 4 phases:

1. Reproducing the issue;
2. Checking whether it can be reproduced with the latest version (or other versions) of THEOplayer;
3. Pre-investigating the issue, and narrowing down the scope;
4. Investigating the root cause and determine the next action item.

![THEOplayer Jira Service Desk](/pr-932/assets/images/ticket-4-stages-c1b32aaf31118677b8e12ea0a6f913ec.png)

### Reproduce the issue

The first step is to reproduce the issue. Take the reproduction stream/page/application, and confirm the issue.

* If the issue can be reproduced: continue the investigation.
* If the issue cannot be reproduced: request more information from the reporter.

![THEOplayer Jira Service Desk](/pr-932/assets/images/ticket-reproduce-4f68ae49865e31e6696b3dddb622e3ad.png)

### Check other versions

The second step is to check if the issue can still be reproduced with the latest version (or other versions) of THEOplayer.

* If using a more recent version fixes the issue: deploy the latest version of THEOplayer.
* If an older version addresses the issue: investigate a potential regression.
* If this doesn't fix the issue: continue scoping the issue.

### Narrow the scope

The goal of this step is to narrow down the scope of the issue. After this phase, we want to determine the influence of the following components.

* Affected platforms;

  * Affected browsers;
  * Affected operating systems;
  * Affected SDKs;

* Affected THEOplayer versions;

* Affected video players.

![THEOplayer Jira Service Desk](/pr-932/assets/images/tickets-scope-1be0844416f48492be33a162c15ac16b.png)

#### Scope affected platforms

It's always useful to know which browsers, SDKs and operating systems are affected by the issue.

#### Scope affected THEOplayer versions

Whilst it's critical to share which THEOplayer versions are affected, it's even more useful to identify older (or newer) versions which are unaffected by the issue. If that's the case, THEOplayer can identify a regression, which speeds up the R\&D-process.

Check which older versions are unaffected.

#### Scope affected video players

In case of an AV playback issue (e.g. freezes, errors, ...), comparing with other video players can help in understanding whether there's a server-side issue (e.g. encoding, packaging, CDN) or a client-side video player issue. If all video players suffer from the issue, it's possible that the stream is not optimally encoded, packaged, etc.

Tips for comparing with other video players:

* If it's an HLS stream: Native Safari, AVPlayer, HLS.js, Shaka Player
* If it's an MPEG-DASH stream: DASH.js, ExoPlayer, Shaka Player

### Investigation

The goal of this step is to identify the cause. Let's discuss causes related to the API, Playback, Advertisements, Analytics and DRM.

#### API

Developers implement THEOplayer through a specific API related to a specific feature. Sometimes, an issue is caused by using a set of API-logic which triggers an edge-case. Sometimes, a nice-to-have API might break in a new update, which in turn breaks a must-have feature.

If you can identify which API-statement causes the issue,

* you can evaluate if you can temporarily disable the statement, and potentially identify a workaround,
* and the R\&D-team knows to what the root cause is related.

Below is a list of proposed action items:

1. Use a near-empty THEOplayer page (or application). Don't use autoplay or preload, or poster images, or ...; limit the API to the absolute minimum.
2. Gradually, add new statements, until the issue can be reproduced.
3. Try alternative approaches, values and states.

#### Playback

Playback issues are related to video and audio freezes, start-up failures, and crashes during playback.

1. Double-check the pre-investigation.

2. Extract information from the reporter why the issue is surfacing just now. Often, playback issues are caused by server-side changes.

3. Extract information from the reporter whether every asset is suffering from the issue.

4. Check whether the issue can be reproduced with other streams:

   * HLS: [https://cdn.theoplayer.com/video/star*wars\_episode\_vii-the\_force\_awakens\_official\_comic-con\_2015\_reel*(2015)/index.m3u8](https://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_\(2015\)/index.m3u8)
   * MPEG-DASH: <https://amssamples.streaming.mediaservices.windows.net/634cd01c-6822-4630-8444-8dd6279f94c6/CaminandesLlamaDrama4K.ism/manifest(format=mpd-time-csf)>

5. Check if the issue is related to a specific video or audio quality. Manually switch to a specific quality or track, and verify whether the issue can still be reproduced. Often, the issues are caused by glitching quality-changes, or a badly encoded quality.

6. Check what is logged in chrome://media-internals.

7. Check whether there are [CORS-issues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-remove-cors-restrictions.md).

8. In-case DRM is used, check whether the issue can also be reproduced if the asset is unprotected.

#### Advertisements

Advertisement set-ups can be quite complex, and the related issues can be quite subtle.

1. Check whether simpler versions of your set-up suffers from the issue:

   * In-case multiple ads are scheduled, check whether single ads suffer from the issue.
   * In-case pre-rolls/mid-rolls are scheduled, check whether the issue is still present if you schedule it as a post-roll/mid-roll instead.
   * In-case multiple ad pods are used inside an ad-break, check whether the issue can be reproduced with single ad pods.
   * In-case a VPAID is scheduled, check whether a VAST works instead.
   * In-case a VMAP is scheduled, check whether an altered VMAP works instead.

2. In-case Google IMA is used, check whether the issue can be reproduced at <https://developers.google.com/interactive-media-ads/docs/sdks/html5/vastinspector>.

3. In-case a SSAI solution is used, check whether other clients also suffer from the issue.

#### Analytics

Issues related to an analytics service usually comes in three shapes:

1. No data is being logged in the analytics service:
   * Check whether the analytics service requires a third-party SDK. If so, check whether this has been included.

2. Data is being logged incorrectly:

   1. Try alternative configurations. When is it working incorrectly?
   2. Identify the maintainer: is it THEOplayer or the analytics vendor?
   3. Find the reference implementation or documentation, and compare with the current implementation.

#### DRM

Sometimes issues are flagged as a DRM issue, whilst they are actually more generic playback issues:

* Check whether the issue can also be reproduced with unprotected streams.

In-case the issue is related to adding DRM:

* Double-check the pre-investigation. It's valuable information if -for example- the issue can be reproduced on Chrome, but not on Firefox, as this could imply that this is a platform-specific decoding issue.
* Check whether the issue is related to Widevine, PlayReady, FairPlay, or all.
* Extract information from the customer whether every DRM-protected asset is suffering from this issue.
* Check whether the issue can be reproduced with reference DRM streams. (e.g. <https://demo.theoplayer.com/drm-aes-protection-128-encryption>)

## Remarks

* The following resources might assist in your debugging efforts:

  * <https://optiview.dolby.com/resources/demos/test-stream/>: logs a number of events and states.
  * <https://www.chromium.org/audio-video/media-internals>: chrome://media-internals can help with identifying A/V decoding issues.
  * [ffprobe](https://ffmpeg.org/ffprobe.html) can help with analyzing streams and segments.
  * [MP4Box.js](https://gpac.github.io/mp4box.js/test/filereader.html) can help with analyzing MP4 files.
  * Apple's [HLS Tools](https://developer.apple.com/documentation/http_live_streaming/about_apple_s_http_live_streaming_tools) can help (e.g. Media Stream Validator).

---

# What are the limitations of AirPlay

When casting through [AirPlay](https://www.theoplayer.com/theoplayer-demo-airplay) your viewer is relying on the native Apple video player. This setup gives rise to a number of limitations, as a third-party video player (i.e. THEOplayer) cannot circumvent the limitations of this native Apple video player.

Some of these limitations include, but are not limited to, the following:

* AirPlay does not support client-side ad-insertion. Instead, you could consider using server-side ad-insertion, or disabling client-side ad-insertion when allowing AirPlay.
* AirPlay does not support VR/360 videos. Instead, you should disable AirPlay for VR/360 videos.
* AirPlay does not support MPEG-DASH. Instead, you should use HLS if you want to allow AirPlay.
* AirPlay does not support UI customization. Instead, you could implement a [tvOS application](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/tvos/getting-started) to offer a custom playback experience on an Apple TV.
* AirPlay does not support some closed captions and subtitle formats, including CEA-608 and [sideloaded (WebVTT) subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-insert-subtitles.md). Instead, you must use subtitles that are supported natively.
* AirPlay does not support manual quality switches. Instead, viewers can only rely on automatic quality selection.
* AirPlay may not have proper support for LL-HLS. The delay might be greater than you expect, and stuttering may occur.
* AirPlay does not support authentication cookies. AirPlay streams run on a device other than the device initiating the session. This means authentication cookies will not be available to retrieve playlists, encryption keys, ... There is also no way to intercept these requests from the initiating device (other than DRM license requests).

> **Does native Safari support it?**
>
> When you want to know whether the native AirPlay video player supports a certain feature, you can compare the experience with the native Safari video player.
>
> For example, if you want to know whether MPEG-DASH is supported, you can enter your MPEG-DASH URL in the address bar of Safari, hit enter, and observe the results. The same results are most likely true for the native AirPlay video player.

---

# How to use the Media Session API

Developers who implement the Media Session API give viewers the option to control and monitor media playback outside their web page. The first screenshot below demonstrates how a viewer can play/resume/seek a video through their iOS home screen, and the second screenshot below demonstrates the same level of control on a macOS.

![Media Session API iOS](/pr-932/assets/images/media-session-api-ios-e60ae898100d1ece8714233b635a35e3.png)

![Media Session API macOS](/pr-932/assets/images/media-session-api-macos-b7572ea6aaf490644bcc1e8dfa1c97ef.png)

The Media Session API is available on most modern desktop and mobile browsers as documented at <https://developer.mozilla.org/en-US/docs/Web/API/Media_Session_API>. The W3C working draft of the Media Session standard is available at <https://www.w3.org/TR/mediasession/>.

# How to implement the Media Session API in THEOplayer

We recommend developers to implement the Media Session API on top of the THEOplayer API in order to ensure the deepest level of control. A simple example is available below:

First, define the metadata for your MediaSession: [see documentation here](https://developer.mozilla.org/en-US/docs/Web/API/MediaSession/metadata).

```javascript
const mediaSessionMetadata = {
  title: 'Sintel',
  artist: 'Blender',
  album: 'Movie',
  artwork: [
    {
      src: 'https://storage.googleapis.com/media-session/sintel/artwork-96.png',
      sizes: '96x96',
      type: 'image/png',
    },
    {
      src: 'https://storage.googleapis.com/media-session/sintel/artwork-128.png',
      sizes: '128x128',
      type: 'image/png',
    },
    {
      src: 'https://storage.googleapis.com/media-session/sintel/artwork-192.png',
      sizes: '192x192',
      type: 'image/png',
    },
    {
      src: 'https://storage.googleapis.com/media-session/sintel/artwork-256.png',
      sizes: '256x256',
      type: 'image/png',
    },
    {
      src: 'https://storage.googleapis.com/media-session/sintel/artwork-384.png',
      sizes: '384x384',
      type: 'image/png',
    },
    {
      src: 'https://storage.googleapis.com/media-session/sintel/artwork-512.png',
      sizes: '512x512',
      type: 'image/png',
    },
  ],
};
```

Then define a helper function that sets the metadata and attaches all EventListeners to the player. The action handlers inside this function can be customized depending on your needs.

```javascript
function addMediaSessionEventListeners(player) {
  const mediaSession = navigator.mediaSession;
  if (mediaSession === undefined) {
    return;
  }
  mediaSession.setActionHandler('play', () => player.play());
  mediaSession.setActionHandler('pause', () => player.pause());
  mediaSession.setActionHandler('seekto', (details) => {
    if (isNaN(player.duration)) {
      return;
    }
    player.currentTime = details.seekTime;
  });
  mediaSession.setActionHandler('seekbackward', function (details) {
    if (isNaN(player.duration)) {
      return;
    }
    player.currentTime = Math.max(player.currentTime - (details.seekOffset ?? 10), 0);
  });
  mediaSession.setActionHandler('seekforward', function (details) {
    if (isNaN(player.duration)) {
      return;
    }
    player.currentTime = Math.min(player.currentTime + (details.seekOffset ?? 10), player.duration);
  });
  var updateMediaSession = function () {
    if (isNaN(player.duration)) {
      return;
    }
    mediaSession.playbackState = player.paused ? 'paused' : 'playing';
    const seekableLength = player.seekable.length;
    if (seekableLength === 0) {
      return;
    }
    mediaSession.setPositionState({
      duration: Math.max(player.seekable.end(seekableLength - 1), player.currentTime),
      playbackRate: player.playbackRate,
      position: player.currentTime,
    });
  };
  var onFirstPlaying = function () {
    player.removeEventListener(['play', 'playing'], onFirstPlaying);
    // Set MediaSession metadata
    if (mediaSessionMetadata !== undefined) {
      mediaSession.metadata = new MediaMetadata(mediaSessionMetadata);
    }
    // Start monitoring player to update MediaSession
    player.addEventListener(['play', 'pause', 'durationchange', 'timeupdate', 'ratechange'], updateMediaSession);
  };
  var onSourceChange = function () {
    // Remove event listeners
    player.removeEventListener(['play', 'playing'], onFirstPlaying);
    player.removeEventListener(['play', 'pause', 'durationchange', 'timeupdate', 'ratechange'], updateMediaSession);
    // Reset MediaSession
    mediaSession.metadata = undefined;
    mediaSession.playbackState = 'none';
    // Wait for next source playback
    player.addEventListener(['play', 'playing'], onFirstPlaying);
  };
  player.addEventListener('sourcechange', onSourceChange);
}
```

Finally, call the helper and set the source on your player that corresponds with the metadata:

```javascript
addMediaSessionEventListeners(player);

player.source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/sintel/nosubs.m3u8',
    },
  ],
};
```

# SharePlay

Implementing the Media Session API is part of implementing [Apple's SharePlay feature](https://developer.apple.com/shareplay/) on Safari. [Contact us](https://www.theoplayer.com/contact) if you're interested in building SharePlay experiences.

---

# How to use THEOplayer iOS SDK on an M1 mac

The iPhone simulators on M1 MacBooks use the arm64 architecture, therefore any binaries linked during compilation time that do not support the architecture will result in compilation error. Many third party frameworks lack the support for this particular architecture, and this causes unfortunate limitations for development.

Previous to writing this article (specifically with THEOplayer **versions 3.0.0 and below**), THEOplayer depended on few of these frameworks that lack the arm64 architecture, which in turn resulted in deciding to omit it. As of **version 3.1.0** and in part of our effort to optimize our modularization, the THEOplayer framework will be delivered with the arm64 architecture support as long as no feature is included that adds a dependency to an unsupported third party framework.

> **Important**
>
> To include the new architecture, import the **.xcframework** package into your project instead of the **.framework** package. The **.framework** is a fat framework and cannot include two arm64 architectures for device and simulator.

#### What are the features that lack arm64 simulator support?

**Google IMA / Google DAI** The Google IMA & DAI features rely on the [GoogleInteractiveMediaAds](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/download) framework which lacks the architecture in its fat framework binary. You can follow developer requests and updates from the IMA team in this [Google Groups conversation](https://groups.google.com/g/ima-sdk/c/y-5OHtAQ5rk?pli=1).

**Google Cast / Chromecast** The Chromecast feature relies on the [GoogleCast](https://developers.google.com/cast/docs/ios_sender#manual_setup) framework which lacks the architecture in its fat framework binary.

Other features that do not support the architecture are: **Agama, Moat & Yospace.**

#### What is the alternative solution?

In case you require one of the features in the section above to be included in your THEOplayer iOS SDK, then the suggested temporary solution is to use Apple's [Rosetta](https://support.apple.com/en-us/HT211861) to be able to run the framework on an iPhone simulator on an M1 mac. Rosetta will launch the simulator in **x86\_64** architecture instead of **arm64** and the framework will successfully be linked during compilation.

#### What about the future?

Whenever a third party dependency adds support to the architecture, we will address the situation and update our SDK framework. To stay up to date with changes related to our iOS SDK, check out our [changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog.md) where we post new updates and features with every new release.

---

# Widevine CDM deprecation notice for old browser versions

Google announced that the current version of the Widevine Content Decryption Module (CDM), which is a closed environment responsible for handling the DRM restrictions and decryption of media, will stop working on 6 December 2022.

## What is the effect of this?

Users will not be able to view Widevine-protected streams if they are on an older version of their browser since Google is deactivating the older versions of the Widevine CDM.

## What should you do if a certain user has an issue with your DRM-protected streams?

If you get a question on why your DRM streams wouldn't work for some of your users, especially around 6 December 2022, it is best to ask them to make sure they are on the latest version of their browser. Almost every browser nowadays have an auto-update mechanism, however many of us ignore the big `Update` button on Chrome or never fully restart the browser to let it finish an update.

## Which platforms are affected?

According to Google, only desktop browsers are affected. Mobile browsers and Chromium-based Smart TVs like LG webOS or Samsung Tizen SmartTVs are not affected.

## Should you update your THEOplayer SDK if you are on an older version?

The deprecation from Google does not require any changes from our side. If you are on an older THEOplayer version, your Widevine streams will still work as expected as long as the browser you are using the SDK on is on the latest version. However, as always, we recommend staying up to date and using the latest version of our SDKs to make use of the new features and improvements we constantly make.

To summarize, since this change from Google only affects the old CDM versions integrated with the older versions of Widevine supporting browsers, as long as you are on the latest version of your browser of choice, everything should still work after 6 December 2022.

## Related pages

* [How to update an SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/how-to-update-a-sdk.md)
* [THEOplayer Platform Support](https://www.theoplayer.com/platform-support)
* [THEOplayer Changelog](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/changelog.md)

---

# Which source is the one being played

In THEOplayer, `player.source.sources` can be used to provide alternative sources for playback, for cross-platform support. What is the actual source being played, if more than one is provided that is supported on the current platform/browser?

The player will select the first source (top to bottom) of a type that is supported on the current platform and try to play it. The player will *not* automatically select a new source from the list if the current one is failing to play for any reason unrelated to platform support.

You can also find out which the source is that the player selects with the `currentsourcechange` event ([documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/CurrentSourceChangeEvent)).

A few additional notes:

* It is of course possible to make the player attempt to play a different source if the one being played errors or never starts to play, but this is to be done in the implementation.
* `player.source.sources` is not intended as a playlist. Playlists can also be accomplished on the implementation side. Here is a simple [example](https://www.theoplayer.com/theoplayer-demo-playlist-and-caching) for the Web SDK.
* This mechanism is based on what the platform declares to support. It does not ensure that all codecs/features included in the stream are supported correctly on the current platform.

---

# What is the "`WebAssembly.compileStreaming` failed" warning and what does it mean?

When starting playback in THEOplayer, you might be seeing a warning in console that reads<br />`'WebAssembly.compileStreaming' failed because your server does not serve wasm with 'application/wasm' MIME type. Falling back to 'WebAssembly.compile' which is slower. Original error: TypeError: Failed to execute 'compile' on 'WebAssembly': Incorrect response MIME type. Expected 'application/wasm'.`

The current HLS pipeline, default since THEOplayer 4.0, works (where possible) with a wasm worker. Some implementations cannot or choose not to serve *wasm*, and we have a fallback mechanism for those cases, which avoids impact on user experience. If this fallback is triggered, this warning appears in console.

In other words, *wasm* allows for better overall performance and the player will try to use this solution first. If this is not possible, it will use different logic, but this doesn't impact the end users. You can safely ignore this warning.

> **Important**
>
> The *wasm* file must be served with the correct MIME type ('application/wasm'), otherwise the player will not recognize it properly and fall back onto the alternative (in this case, the warning will also be shown). If the file is served with the wrong MIME type (e.g.: text/html), this must be corrected on the server side.

---

# What PiP options to use to make the video stay visible while browsing or on other applications

When it comes to Picture-in-Picture (PiP), there are different options, each with its advantages and disadvantages. To have the floating video remain visible during browsing, you need an out-of-app PiP, but not all features are available (or the same) everywhere.<br />The following gives a short general description of the most commonly used options.

## THEOplayer PiP

[This guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/picture-in-picture.md) will help you get started with THEOplayer PiP in your implementation.<br />Highlights:

* *Pros*: easily configured within the playerConfig; it will automatically trigger when the visible video portion is below the declared threshold; the pause/resume behavior with a click on any part of the video is maintained; CSAI ads and subtitles are correctly rendered in the floating window
* *Cons*: the floating player can't be resized at runtime and it sticks to its predefined position; it is in-app, meaning that it won't stay visible if you browse to other tabs or applications

## Native PiP

The [documentation available here](https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API) describes the API and you can easily get it working with the described methods.<br />Highlights:

* *Pros*: the user is in control of when the feature is active; this is out-of-app, meaning that the floating video element can be resized and moved, and it stays visible while browsing other tabs or apps.
* *Cons*: this requires a user action to be triggered; CSAI ads and subtitles may not be rendered in the floating video; resetting the source while in PiP may need additional logic for correct handling; it is not supported on all platforms (e.g.: Firefox and old versions of Safari, see [browser compatibility](https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API#browser_compatibility)); different browsers may have a somewhat different UI in the floating video;

## Firefox PiP

Firefox has its own version of PiP, which includes by default a button on the video element. [More information](https://support.mozilla.org/en-US/kb/about-picture-picture-firefox).<br />Highlights:

* pros and cons are mainly the same as for the native PiP, although the UI is different
* as this is a native Firefox feature, the button and context menu option to enable PiP cannot be hidden by the implementer. The users can, however, decide in their settings if the button will be visible for them.

---

# Why are the FairPlay license and certificate being requested again on iOS after ads?

The DRM license and certificate are retrieved when a DRM-protected stream starts to be played. This is usually enough for a full playback session since in most cases the DRM context can be maintained.<br />However, certain combinations of features may prevent this.

The most common case is when we indicate that on iOS browsers the native fullscreen should be used (`allowNativeFullscreen: true`). In this case, on these browsers ads and content will be played through the same `<video>` element, regardless of whether the user is actually playing in fullscreen.

This means that when a midroll is played, the previous DRM context is lost, so upon resuming content playback it must be re-established and the DRM license and certificate need to be requested again.

---

# How to detect if the user changes the video quality

It is possible to distinguish between when the quality is changed by ABR or by the user and, in the latter case, which quality has been selected.

This can be easily achieved listening to the `targetqualitychanged` event ([documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TargetQualityChangedEvent)) such as in the snippet below:

```js
player.videoTracks[0].addEventListener('targetqualitychanged', (e) => {
  let selectedTrack = e.qualities[0];
});
```

**The possible cases**

* *ABR changes the quality being played*: this event is not fired
* *the user selects a specific quality*: an Object describing the quality is returned: the `height` and `bandwidth` properties may be checked to distinguish it from the other qualities
* *the user restores ABR*: `undefined` is returned

**Notes**

* The event returns an Array because the implementer may also use the targetQuality feature to select a subset of the available qualities to limit ABR to those qualities. If this is part of your use case, the snippet above might need to be tweaked to account for that case (e.g.: filter it out).
* when resetting the player.source, the videoTracks object is also reset, so the event will need to be appended again

---

# List of supported platforms

## THEOplayer HTML5 / Tizen / webOS SDK

|                                              | HLS                                                                                    |                                                                           | MPEG-DASH                                                                              |                                                            | HESP [1](#user-content-fn-hesp)                                                        |                                                   |
| -------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------- |
|                                              | Version                                                                                | Content Protection & DRM                                                  | Version                                                                                | Content Protection & DRM                                   | Version                                                                                | Content Protection & DRM                          |
| ### Desktop Browser Platforms                |                                                                                        |                                                                           |                                                                                        |                                                            |                                                                                        |                                                   |
| Chrome (and Chromium based)                  | Evergreen [2](#user-content-fn-evergreen)<br />(last 3 major versions)                 | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | ClearKey<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | Widevine DRM                                      |
| Edge (Chromium)                              | Evergreen<br />(last 3 major versions)                                                 | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM (on Windows) | Evergreen<br />(last 3 major versions)                                                 | ClearKey<br />Widevine DRM<br />PlayReady DRM (on Windows) | Evergreen<br />(last 3 major versions)                                                 | Widevine DRM<br />PlayReady DRM (on Windows)      |
| Firefox                                      | Evergreen<br />(last 3 major versions)                                                 | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | ClearKey<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | Widevine DRM                                      |
| Safari                                       | Evergreen<br />(last 3 major versions)                                                 | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | Evergreen<br />(last 3 major versions)                                                 | ClearKey                                                   | Evergreen<br />(last 3 major versions)                                                 | FairPlay DRM                                      |
| ### Mobile Browser Platforms                 |                                                                                        |                                                                           |                                                                                        |                                                            |                                                                                        |                                                   |
| Chrome for Android                           | Evergreen<br />(last 3 major versions)                                                 | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | ClearKey<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | Widevine DRM                                      |
| Firefox for Android                          | Evergreen<br />(last 3 major versions)                                                 | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | ClearKey<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)                                                 | Widevine DRM                                      |
| Safari for iOS                               | Evergreen<br />(last 3 major versions)                                                 | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | N/A [3](#user-content-fn-na)                                                           | N/A                                                        | iOS 14+                                                                                | FairPlay DRM                                      |
| ### Connected devices and smart TV platforms |                                                                                        |                                                                           |                                                                                        |                                                            |                                                                                        |                                                   |
| Samsung Tizen                                | 2.3+                                                                                   | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 2.3+                                                                                   | ClearKey<br />Widevine DRM<br />PlayReady DRM              | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/) |
| LG webOS                                     | 3.0+                                                                                   | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 3.0+                                                                                   | ClearKey<br />Widevine DRM<br />PlayReady DRM              | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/) |
| HbbTV                                        | N/A                                                                                    | N/A                                                                       | 1.5, 2.0.1+<br />[Contact us](https://optiview.dolby.com/contact/)                     | ClearKey<br />PlayReady DRM                                | N/A                                                                                    | N/A                                               |
| Hisense Vidaa U                              | 3.0+                                                                                   | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | 3.0+                                                                                   | ClearKey<br />Widevine DRM                                 | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/) |
| Vizio                                        | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/)                         | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/)          | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/) |
| RDK<br />WPE & Lightning                     | 2.20+<br />[Contact us](https://optiview.dolby.com/contact/)                           | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 2.20+<br />[Contact us](https://optiview.dolby.com/contact/)                           | ClearKey<br />Widevine DRM<br />PlayReady DRM              | 2.20+<br />[Contact us](https://optiview.dolby.com/contact/)                           | Widevine DRM<br />PlayReady DRM                   |
| Xbox                                         | One, Series S, Series X                                                                | [Contact us](https://optiview.dolby.com/contact/)                         | One, Series S, Series X                                                                | [Contact us](https://optiview.dolby.com/contact/)          | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/) |
| PlayStation                                  | PS4<br />PS5<br />[Contact us](https://optiview.dolby.com/contact/)                    | PlayReady DRM                                                             | PS4<br />PS5<br />[Contact us](https://optiview.dolby.com/contact/)                    | PlayReady DRM                                              | [Contact us](https://optiview.dolby.com/contact/)                                      | [Contact us](https://optiview.dolby.com/contact/) |
| Web based                                    | Chromium 38+<br />WebKit 537.3+<br />[Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)                         | Chromium 38+<br />WebKit 537.3+<br />[Contact us](https://optiview.dolby.com/contact/) | PlayReady DRM                                              | Chromium 38+<br />WebKit 537.3+<br />[Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |

## THEOplayer iOS / tvOS SDK

|        | HLS     |                                           | MPEG-DASH |                          | HESP (\*) |                          |
| ------ | ------- | ----------------------------------------- | --------- | ------------------------ | --------- | ------------------------ |
|        | Version | Content Protection & DRM                  | Version   | Content Protection & DRM | Version   | Content Protection & DRM |
| iOS    | 13+     | AES-128<br />SAMPLE-AES<br />FairPlay DRM | N/A       | N/A                      | 13+       | FairPlay DRM             |
| iPadOS | 13+     | AES-128<br />SAMPLE-AES<br />FairPlay DRM | 13+       | ClearKey                 | 13+       | FairPlay DRM             |
| tvOS   | 13+     | AES-128<br />SAMPLE-AES<br />FairPlay DRM | 13+       | ClearKey                 | 13+       | FairPlay DRM             |

## THEOplayer Android / Fire TV SDK

|                                         | HLS                                               |                                                              | MPEG-DASH                                         |                                                   | HESP (\*)                                         |                                                   |
| --------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- |
|                                         | Version                                           | Content Protection & DRM                                     | Version                                           | Content Protection & DRM                          | Version                                           | Content Protection & DRM                          |
| Android                                 | 5.0+                                              | AES-128<br />SAMPLE-AES<br />Widevine DRM                    | 5.0+                                              | ClearKey<br />Widevine DRM                        | 5.0+                                              | Widevine DRM                                      |
| Android TV                              | 7+                                                | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM | 7+                                                | ClearKey<br />Widevine DRM<br />PlayReady DRM     | 7+                                                | Widevine DRM<br />PlayReady DRM                   |
| Fire TV                                 | 5+                                                | AES-128<br />SAMPLE-AES<br />Widevine DRM                    | 5+                                                | ClearKey<br />Widevine DRM                        | 5+                                                | Widevine DRM                                      |
| AOSP<br />(Android Open Source Project) | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)            | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |

## THEOplayer Roku SDK

|                               | HLS                                    |                                                              | MPEG-DASH                              |                                               | HESP (\*)                                         |                                                   |
| ----------------------------- | -------------------------------------- | ------------------------------------------------------------ | -------------------------------------- | --------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- |
|                               | Version                                | Content Protection & DRM                                     | Version                                | Content Protection & DRM                      | Version                                           | Content Protection & DRM                          |
| Roku OS                       | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM | Evergreen<br />(last 3 major versions) | ClearKey<br />Widevine DRM<br />PlayReady DRM | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| ### Casting                   |                                        |                                                              |                                        |                                               |                                                   |                                                   |
| Apple Airplay                 | Safari<br />iOS & iPadOS               | FairPlay DRM                                                 | N/A                                    | N/A                                           | N/A                                               | N/A                                               |
| Google Cast<br />(Chromecast) | Chrome<br />Android<br />iOS & iPadOS  | AES-128<br />SAMPLE-AES<br />Widevine DRM                    | Chrome<br />Android<br />iOS & iPadOS  | ClearKey<br />Widevine DRM<br />PlayReady DRM | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |

## THEOplayer React Native SDK

|                                                                   | HLS                                               |                                                                           | MPEG-DASH                                         |                                                              | HESP (\*)                                         |                                                   |
| ----------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- |
|                                                                   | Version                                           | Content Protection & DRM                                                  | Version                                           | Content Protection & DRM                                     | Version                                           | Content Protection & DRM                          |
| ### Desktop Browser Platforms                                     |                                                   |                                                                           |                                                   |                                                              |                                                   |                                                   |
| Chrome (and Chromium based)                                       | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)            | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Edge (Chromium)                                                   | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM (on Windows) | Evergreen<br />(last 3 major versions)            | ClearKey<br />Widevine DRM<br />PlayReady DRM (on Windows)   | Evergreen<br />(last 3 major versions)            | Widevine DRM<br />PlayReady DRM (on Windows)      |
| Firefox                                                           | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)            | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Safari                                                            | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | Evergreen<br />(last 3 major versions)            | ClearKey                                                     | Evergreen<br />(last 3 major versions)            | FairPlay DRM                                      |
| ### Mobile Browser Platforms                                      |                                                   |                                                                           |                                                   |                                                              |                                                   |                                                   |
| Chrome for Android                                                | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)            | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Firefox for Android                                               | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions)            | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Safari for iOS                                                    | Evergreen<br />(last 3 major versions)            | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | N/A                                               | N/A                                                          | iOS 14+                                           | FairPlay DRM                                      |
| ### Connected devices and smart TV platforms                      |                                                   |                                                                           |                                                   |                                                              |                                                   |                                                   |
| Samsung Tizen                                                     | 2.3+                                              | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 2.3+                                              | ClearKey<br />Widevine DRM<br />PlayReady DRM                | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| LG webOS                                                          | 3.0+                                              | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 3.0+                                              | ClearKey<br />Widevine DRM<br />PlayReady DRM                | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| Hisense Vidaa U                                                   | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)                         | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)            | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| Vizio                                                             | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)                         | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)            | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| RDK<br />WPE & Lightning<br />(e.g. Liberty Global, Comcast, Sky) | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)                         | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/)            | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| ### Native Apps                                                   |                                                   |                                                                           |                                                   |                                                              |                                                   |                                                   |
| iOS                                                               | 13+                                               | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | N/A                                               | N/A                                                          | 13+                                               | FairPlay DRM                                      |
| iPadOS                                                            | 13+                                               | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | 13+                                               | ClearKey                                                     | 13+                                               | FairPlay DRM                                      |
| tvOS                                                              | 13+                                               | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | 13+                                               | ClearKey                                                     | 13+                                               | FairPlay DRM                                      |
| Android                                                           | 5.0+                                              | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | 5.0+                                              | ClearKey<br />Widevine DRM                                   | 5.0+                                              | Widevine DRM                                      |
| Android TV                                                        | 7+                                                | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 7+                                                | ClearKey<br />Widevine DRM<br />PlayReady DRM                | 7+                                                | Widevine DRM<br />PlayReady DRM                   |
| Fire TV                                                           | 5+                                                | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | 5+                                                | ClearKey<br />Widevine DRM                                   | 5+                                                | Widevine DRM                                      |
| Xbox                                                              | One, Series S, Series X                           | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | One, Series S, Series X                           | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |
| ### Casting                                                       |                                                   |                                                                           |                                                   |                                                              |                                                   |                                                   |
| Apple Airplay                                                     | Safari<br />iOS & iPadOS                          | FairPlay DRM                                                              | N/A                                               | N/A                                                          | N/A                                               | N/A                                               |
| Google Cast<br />(Chromecast)                                     | Chrome<br />Android<br />iOS & iPadOS             | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Chrome<br />Android<br />iOS & iPadOS             | ClearKey<br />Widevine DRM<br />PlayReady DRM                | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |

## THEOplayer Flutter SDK

|                               | HLS                                    |                                                                           | MPEG-DASH                              |                                                              | HESP (\*)                                         |                                                   |
| ----------------------------- | -------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- |
|                               | Version                                | Content Protection & DRM                                                  | Version                                | Content Protection & DRM                                     | Version                                           | Content Protection & DRM                          |
| ### Desktop Browser Platforms |                                        |                                                                           |                                        |                                                              |                                                   |                                                   |
| Chrome (and Chromium based)   | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions) | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Edge (Chromium)               | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM (on Windows) | Evergreen<br />(last 3 major versions) | ClearKey<br />Widevine DRM<br />PlayReady DRM (on Windows)   | Evergreen<br />(last 3 major versions)            | Widevine DRM<br />PlayReady DRM (on Windows)      |
| Firefox                       | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions) | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Safari                        | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | Evergreen<br />(last 3 major versions) | ClearKey                                                     | Evergreen<br />(last 3 major versions)            | FairPlay DRM                                      |
| ### Mobile Browser Platforms  |                                        |                                                                           |                                        |                                                              |                                                   |                                                   |
| Chrome for Android            | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions) | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Firefox for Android           | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | Evergreen<br />(last 3 major versions) | ClearKey<br />Widevine DRM                                   | Evergreen<br />(last 3 major versions)            | Widevine DRM                                      |
| Safari for iOS                | Evergreen<br />(last 3 major versions) | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | N/A                                    | N/A                                                          | iOS 14+                                           | FairPlay DRM                                      |
| ### Native Apps               |                                        |                                                                           |                                        |                                                              |                                                   |                                                   |
| iOS                           | 13+                                    | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | N/A                                    | N/A                                                          | 13+                                               | FairPlay DRM                                      |
| iPadOS                        | 13+                                    | AES-128<br />SAMPLE-AES<br />FairPlay DRM                                 | 13+                                    | ClearKey                                                     | 13+                                               | FairPlay DRM                                      |
| Android                       | 5.1+                                   | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | 5.1+                                   | ClearKey<br />Widevine DRM                                   | 5.1+                                              | Widevine DRM                                      |
| Android TV                    | 7+                                     | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | 7+                                     | ClearKey<br />Widevine DRM<br />PlayReady DRM                | 7+                                                | Widevine DRM<br />PlayReady DRM                   |
| Fire TV                       | 5+                                     | AES-128<br />SAMPLE-AES<br />Widevine DRM                                 | 5+                                     | ClearKey<br />Widevine DRM                                   | 5+                                                | Widevine DRM                                      |
| Xbox                          | One, Series S, Series X                | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM              | One, Series S, Series X                | AES-128<br />SAMPLE-AES<br />Widevine DRM<br />PlayReady DRM | [Contact us](https://optiview.dolby.com/contact/) | [Contact us](https://optiview.dolby.com/contact/) |

## Footnotes

1. HESP support is not available by default in THEOplayer. Contact our team for more information. [↩](#user-content-fnref-hesp)

2. Evergreen means this platform receives automatic software updates. Customers will be using the last version of software, but for users lagging behind in updates, we ensure compatibility with the latest three versions. [↩](#user-content-fnref-evergreen)

3. N/A: Not available due to platform limitations. [↩](#user-content-fnref-na)

---

# How-to guides

Want to start implementing features to your SDK? Our how-to-guides will help you with all kind of integrations!

## [💰Ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/introduction.md)

[14 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/introduction.md)

## [📊Analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/introduction.md)

[12 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/introduction.md)

## [Cast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/introduction.md)

## [🔐DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md)

[20 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md)

## [🔌Integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/integrations/introduction.md)

[4 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/integrations/introduction.md)

## [🎥Media tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/introduction.md)

[9 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/introduction.md)

## [\*️⃣Miscellaneous](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/introduction.md)

[13 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/introduction.md)

## [📡Network](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/network/introduction.md)

[4 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/network/introduction.md)

## [▶️Player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/introduction.md)

[5 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/introduction.md)

## [💬Text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/introduction.md)

[9 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/introduction.md)

## [🎨UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/introduction.md)

[16 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/introduction.md)

## [🔑License](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/license/introduction.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/license/introduction.md)

## [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/introduction.md)

[7 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/introduction.md)

## [🚦Content Steering](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/content-steering/mpeg-dash-content-steering.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/content-steering/mpeg-dash-content-steering.md)

## [🚀OptiView Live](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/theolive/getting-started.md)

[Integrate OptiView Live streaming into your web app.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/theolive/getting-started.md)

---

# Introduction

The articles in this section describe how to implement common use-cases related to advertisements. These use-cases can range from customizing the UX during advertisements, to detecting ad blockers.

We recommend starting with [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-set-up-vast-and-vmap.md), as this article explains how to set up client-side advertisements.

Consider reading our [Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/user-guide.md) to learn more about advertising and THEOplayer's capabilities.

### Table of Contents

* Client-side advertisement systems

  * [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-set-up-vast-and-vmap.md)
  * [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/google-ima.md)
  * [SpotX](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/spotx.md)
  * [FreeWheel](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/freewheel.md)

* Server-side advertisement systems

  * [Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/yospace.md)
  * [Google DAI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/google-dai.md)
  * [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ads.md)
  * [MediaTailor](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/mediatailor.md)
  * [Custom Server Side Ad Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/custom-ssai-integration.md)

* Other

  * [How to subscribe to events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-subscribe-to-ad-events.md)
  * [Adblock Detection](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/block-detection.md)
  * [Customizing the ad overlay text](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/customizing-the-ad-overlay-text.md)
  * [How to display visual cues on the timeline to mark mid-rolls?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-display-visual-cues.md)
  * [Prebid.js](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/prebidjs.md)

---

# Adblock detection

The THEOplayer Ads API allows developers to detect adblockers, and react accordingly. More specifically, you can either A) specify a stream configuration that disables playback when an ad blocker is detected, and show a default error message, or either B) detect an `aderror` event and implement a custom handler.

The screenshot below illustrates the default error message.

![Ad block detection](/pr-932/assets/images/ad-blocker-detected-2021-8f2264848bf980c284f2e5744c2acd30.png "Adblock detection")

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | N/A         | N/A     | N/A      | N/A            | N/A            |

## Usage

Adblock detection is typically a challenge in browsers. Hence, SDKs other than the Web SDK are considered "N/A" (i.e. not applicable). THEOplayer does not prevent playback by default when an ad blocker is detected.

As explained in the intro, you can either A) configure your stream configuration to prevent playback and show a default error message, or either B) implement an error event handler to implement a custom behavior.

### Stream configuration

When you set the `blockContentIfAdError` to `true` in your stream configuration (i.e. [SourceConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SourceConfiguration#blockContentIfAdError)), then playback will be stopped, and a default error message will be shown.

The snippet below demonstrates how you could implement this `blockContentIfAdError` property in a stream configuration.

```js
player.source = {
  sources: {
    src: '//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
  },
  ads: [
    {
      sources:
        'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=',
    },
  ],
  blockContentIfAdError: true,
};
```

Through localization, you could rename the default error message, as demonstrated below.

```javascript
var player = new THEOplayer.Player(document.querySelector('.video-js'), {
  ui: {
    language: 'en',
    languages: {
      en: {
        'Starting ads was not possible. Turn off your AdBlocker and try again.': 'Disable your AdBlocker.',
      },
    },
  },
  libraryLocation: '<your-library-location>',
});
```

When you go for this approach, it's important that you validate and correctly specify the current default error message. For example, in THEOplayer 2.81.0, the default error message was `Starting ads was not possible. Turn off your AdBlocker and try again.`.

If you want to customize beyond renaming the default error message, then you could try to do custom DOM manipulation and custom CSS queries. However, it might be advised to leverage the `aderror` event, as explained in the next section, if you truly want to customize the behavior.

### Error event

Alternatively, you can detect an ad blocker through the `aderror` event. If you detect this event, you could implement a custom behavior, such as stopping playback (e.g. through `player.stop()`) and drawing an overlay.

The callback event may be differently formatted depending on your selected ad integration.

If you're using the [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/google-ima.md) ad integration, your callback event will have a `problemType` property that will equal `"adblock"`.

```javascript
player.ads.addEventListener('aderror', function (event) {
  // if using the Google IMA SDK, then your event looks like this:
  // {
  //  "type": "aderror",
  //  "date": "2021-03-09T18:18:03.093Z",
  //  "ad": null,
  //  "problemType": "adblock",
  //  "message": "adblock",
  //  "source": {
  //    "src": "https://pubads.g.doubleclick.net/gampad/ads?..."
  //  }
  // }
  // so, to detect an ad blocker, you can do
  if (event.problemType == 'adblock') {
    // and do something else
  }
});
```

If you're using the default ad integration, your callback event will have a `problemType` property that will equal `"network"`.

```javascript
player.ads.addEventListener('aderror', function (event) {
  // if using the default ad integration, then your event looks like this:
  // {
  //   "type": "aderror",
  //   "date": "2021-03-09T19:22:15.171Z",
  //   "ad": null,
  //   "problemType": "network",
  //   "message": "The ad source could not be loaded.",
  //   "errorCode": 100,
  //   "source": {
  //     "src": "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator="
  //   }
  // }
  // so, to detect an ad blocker, you can do
  if (event.problemType == 'network') {
    // and do something else
  }
});
```

## Resources

Below are some resources on adblock detection through the Ads API:

* API reference: [Ads API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Ads)
* Online demo: [Adblock Detection Demo](https://demo.theoplayer.com/adblock-detection)
* Advertisement guide: [Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/user-guide.md) (mentions adblock detection)

---

# Customizing the ad overlay text

This guide explains how to customize the overlay text shown during an ad break. You may ask this question if you want to change the customize the styling or override the texts shown during an ad break.

Depending on the ad integration kind you use, the steps to take differ.

## CSAI integration

The `csai` [ad integration kind](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/AdIntegrationKind) is only available on Web SDK and allows customization.

To customize the text here we will be leveraging the language localization mechanism. You can find the API we will be using [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UIConfiguration#language).

The second step is to customize the styling of texts. This can be done via CSS.

### Changing or localizing the text

In this section, we will explain how to modify the text. We will take the countdown to the content text as an example (another ad overlay text is the "Skip ad" text, if any). When considering a new text to replace the original one, it is important to take into consideration its length (which should be determined accordingly to the available space) and how it is composed.

The current example is composed of 3 parts: one text ("The content will play in"), a dynamic countdown and another text ("seconds"). For this reason, when changing the text, both text parts need addressing.

An example:

```js
var element = document.querySelector('.video-js');
const player = new THEOplayer.Player(element, {
  license: 'your_license_here',
  ui: {
    // your other UI configuration
    language: 'en',
    languages: {
      en: {
        'The content will play in': 'Here your customized text',
        seconds: 'Here your customized text',
        // any other translation or text change
      },
    },
  },
  libraryLocation: 'https://example.com/',
});
```

### Changing the styling

If you are interested in changing the aspect of the overlay or its content, you may do so applying the desired CSS properties to the concerned elements.

As mentioned, the following example is only valid for the `csai` ad integration:

```css
/* This modifies the countdown div */
.theo-ad-remaining-container {
  /* your styles here */
}

/* This modifies the skip ads div */
.theoplayer-ad-skip {
  /* your styles here */
}

/* this can also be further differentiated in 2 cases:*/

/* the countdown */
.theoplayer-ad-skip.theoplayer-ad-skip-countdown {
  /* your styles here */
}

/* the button */
.theoplayer-ad-skip.theoplayer-ad-skip-button {
  /* your styles here */
}
```

## Google IMA/DAI

With Google IMA/DAI, it is not possible to directly edit the default UI. You can pass a locale to IMA to completely localize the ad UI. On the following sections we will explain the possibilities.

### Changing or localizing the text

It is not possible to edit the texts on the default UI on Google IMA/DAI SDKs. However, you can pass a locale to IMA to completely localize its ad UI like the following:

##### Web SDK

```javascript
var element = document.querySelector('.video-js');
const player = new THEOplayer.Player(element, {
  license: 'your_license_here',
  libraryLocation: 'https://example.com',
  ads: {
    googleIma: {
      language: 'nl',
    },
  },
});
```

You can find a list of locales supported by IMA SDK on web [here](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/localization#locale-codes).

##### Android SDK

You can pass [your preferred language](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/ImaSdkSettings.html#setLanguage\(java.lang.String\)) while adding the Google IMA integration to the player:

```kotlin
private fun addGoogleImaIntegration() {
    val settings = ImaSdkFactory.getInstance().createImaSdkSettings()
    settings.language = "nl"

    val imaIntegration = createGoogleImaIntegration(tpv!!, settings)

    tpv?.player?.addIntegration(imaIntegration)
}
```

You can find a list of locales supported by IMA SDK on Android [here](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/localization#locale-codes).

##### iOS SDK

You can pass [your preferred language](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/reference/Classes/IMASettings#language) while adding the Google IMA integration to the player:

```swift
private func setupImaIntegration() {
    let imaSettings = IMASettings()
    imaSettings.language = "nl"

    let imaIntegration: GoogleImaIntegration = GoogleIMAIntegrationFactory.createIntegration(on: self.theoplayer!, with: imaSettings)

    theoplayer.addIntegration(imaIntegration)
    }
```

You can find a list of locales supported by IMA SDK on Android [here](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/localization#locale-codes).

### Changing the styling

##### Web SDK

Currently it is not possible to customize the default UI on Google IMA/DAI SDKs on Web with the exception of toggling certain [UiElements](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima#.UiElements). This can be done like the following:

```javascript
var element = document.querySelector('.video-js');
const player = new THEOplayer.Player(element, {
  license: 'your_license_here',
  libraryLocation: 'https://example.com',
  ads: {
    googleIma: {
      uiElements: [google.ima.UiElements.AD_ATTRIBUTION, google.ima.UiElements.COUNTDOWN],
    },
  },
});
```

##### Android SDK

Please refer to the relevant [Google IMA guide](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/custom-ui) on how to disable the default UI and implement your own ad UI.

##### iOS SDK

Please refer to the relevant [Google IMA guide](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/custom-ui) on how to disable the default UI and implement your own ad UI.

## Remarks

* If you are using [THEOplayer Open Video UI](https://www.theoplayer.com/product/open-video-ui), there could be alternative ways to edit certain elements depending on the platform and the ad integration kind used. For reference, you can find a demo for the `csai` ad integration on Web SDK [here](https://www.theoplayer.com/docs/open-video-ui/web/examples/ads/).
* The `Why this ad?` text or the `?` (question mark) icon that may appear while using the Google IMA/DAI integration is inserted by the IMA SDK itself and is required to be displayed with any ad that was not manually selected. The icon is rendered as a VAST icon and is automatically generated by Ad Manager where required.

## Resources

* [How to change the default UI language to other](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-change-default-UI-language-to-other.md)
* [Language localization](https://www.theoplayer.com/theoplayer-demo-language-localization)
* [THEOplayer advertisement tester](https://www.theoplayer.com/theoplayer-demo-advertisement-tester-vpaid-vast-vmap)

---

# How to set up VAST and VMAP ads?

This article explains how to schedule client-side VAST and VMAP advertisements through THEOplayer.

* A VAST advertisement is a single ad break, and you can position it as a pre-roll, mid-roll or post-roll.
* A VMAP advertisement is a playlist of ad breaks, and can contain any combination of pre-rolls, mid-rolls and/or post-rolls.

Through the THEOplayer API, app developers can define which "ad integration" they want to use.

THEOplayer currently supports 4 types of client-side ad integrations:

1. CSAI
2. [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/google-ima.md)
3. [SpotX](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/spotx.md)
4. [FreeWheel](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/freewheel.md)

This article explains scheduling VAST and VMAP ads. Scheduling VAST and VMAP ads through all ad integrations is very similar, so consider this article as a reference guide.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | No             | No       |

## VAST

Setting up a client-side VAST advertisement means scheduling a VAST ad tag.

As an app developer, you associate a VAST ad tag (URL) (e.g. `https://cdn.theoplayer.com/demos/ads/vast/vast.xml`) with a time offset.

Additionally, when using the default, `csai` ad integration, you can also specify after how many seconds a VAST ad may be skipped. If you are using Google IMA, the skip offset should be set inside the ad tag instead.

You may also schedule multiple ad tags.

Let's consider the following common use-cases:

1. [Scheduling a single pre-roll](#scheduling-a-single-pre-roll)
2. [Scheduling two pre-rolls, two mid-rolls and one post-roll](#scheduling-two-pre-rolls-two-mid-rolls-and-one-post-roll)
3. [Scheduling a skippable mid-roll](#scheduling-a-skippable-mid-roll)

### Scheduling a single pre-roll

The following snippets demonstrate how to schedule a single pre-roll.

#### Web SDK

You configure an [AdDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdDescription) in the `ads` property of your [SourceConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SourceConfiguration).

In this `AdDescription`,

* You set the value of `sources` to an object with the URL of your ad tag as its `src`.
* You set the value of `timeOffset` to `"start"` (or `00:00:00` or `0%`) to indicate that it's a pre-roll.
* Optionally, you set the `type` of that `sources` object to `"vast"`. When this isn't provided, the player will still try to figure out its `type` after making the ad request.

```js
player.source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
    },
  ],
  ads: [
    {
      sources: { src: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml', type: 'vast' },
      timeOffset: 'start',
      integration: 'csai', // When no integration is provided, the player defaults to `csai`.
    },
  ],
};
```

If you wanted to schedule a post-roll instead of a pre-roll, you set the value of `timeOffset` to `"end"`.

If you want to schedule a mid-roll instead of a pre-roll, you set the value of `timeOffset` to the `HH:MM:SS` format.

For example, to schedule an advertisement at the 15s mark, you set the value of `timeOffset` to `"00:00:15"`.

If you wanted to use Google IMA as an example, you would replace `integration: "csai"` with `integration: "google-ima"`. Before doing so, make sure you have [set up Google IMA](https://www.theoplayer.com/docs/theoplayer/how-to-guides/ads/google-ima/) correctly.

#### Android SDK

We will be using Google IMA here so [make sure to set it up](https://www.theoplayer.com/docs/theoplayer/how-to-guides/ads/google-ima/) before starting.

You configure a [GoogleImaAdDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/source/addescription/GoogleImaAdDescription.Builder) in the `ads` property of your [`SourceDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/source/SourceDescription.Builder#ads-com.theoplayer.android.api.source.addescription.AdDescription...-).

In this `GoogleImaAdDescription`,

* You set an ad tag URL.
* You set the value of [`timeOffset`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/source/addescription/GoogleImaAdDescription.Builder#timeOffset-java.lang.String-) to `"start"` (or `00:00:00` or `0%`) to indicate that it's a pre-roll.

```kotlin
theoPlayer.source = SourceDescription.Builder(
    TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8").build())
    .ads(
        GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/dfp-linear-inline-no-skip.xml")
            .timeOffset("start")
            .build())
    .build()
```

If you wanted to schedule a post-roll instead of a pre-roll, you set the value of `timeOffset` to `"end"`.

If you want to schedule a mid-roll instead of a pre-roll, you set the value of `timeOffset` to the `HH:MM:SS` format.

For example, to schedule an advertisement at the 15s mark, you set the value of `timeOffset` to `"00:00:15"`.

#### iOS/tvOS SDK

We will be using Google IMA here so [make sure to set it up](https://www.theoplayer.com/docs/theoplayer/how-to-guides/ads/google-ima/) before starting.

You configure a [GoogleImaAdDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/GoogleImaAdDescription) in the `ads` property of your [`SourceDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/SourceDescription#/s:13THEOplayerSDK17SourceDescriptionC3adsSayAA02AdD0_pGSgvp).

In this `GoogleImaAdDescription`,

* You set an ad tag URL.
* You set the value of [`timeOffset`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOAdDescription#/c:@M@THEOplayerSDK@objc\(cs\)THEOAdDescription\(py\)timeOffset) to `"start"` (or `00:00:00` or `0%`) to indicate that it's a pre-roll.

```swift
private var source: SourceDescription {
    // Declare a TypedSource object with a stream URL and its type
    let typedSource = TypedSource(
        src: videoUrl,
        type: mimeType
    )

    // The AdDescription object that defines the IMA ad to be played.
    let offset = "start",
    let adDescription: GoogleImaAdDescription = GoogleImaAdDescription(src: adTagUrl, timeOffset: offset)

    // Returns a computed SourceDescription object
    return SourceDescription(
        source: typedSource,
        ads: [adDescription],
        poster: posterUrl
    )
}
```

If you wanted to schedule a post-roll instead of a pre-roll, you set the value of `timeOffset` to `"end"`.

If you want to schedule a mid-roll instead of a pre-roll, you set the value of `timeOffset` to the `HH:MM:SS` format.

For example, to schedule an advertisement at the 15s mark, you set the value of `timeOffset` to `"00:00:15"`.

### Scheduling two pre-rolls, two mid-rolls and one post-roll

Scheduling multiple VAST ads is only slightly different from scheduling a single VAST ad. Instead of passing along one ad description to your array, you pass along multiple ad descriptions to the array.

The following snippets demonstrate how you would configure two pre-rolls, two mid-rolls and one post-roll through the usage of VAST ads.

#### Web SDK

```js
player.source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
    },
  ],
  ads: [
    {
      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
      timeOffset: 'start',
    },
    {
      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
      timeOffset: 'start',
    },
    {
      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
      timeOffset: '00:00:15',
    },
    {
      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
      timeOffset: '00:00:30',
    },
    {
      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
      timeOffset: 'end',
    },
  ],
};
```

#### Android SDK

```kotlin
val typedSource = TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8")
val sourceDescription = SourceDescription.Builder(typedSource.build())

sourceDescription.ads(
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
        .timeOffset("start")
        .build(),
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
        .timeOffset("start")
        .build(),
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
        .timeOffset("00:00:15")
        .build(),
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
        .timeOffset("00:00:15")
        .build(),
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
        .timeOffset("end")
        .build()
)

theoPlayer.source = sourceDescription.build()
```

#### iOS/tvOS SDK

```swift
let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")

let vastAdTag = "https://cdn.theoplayer.com/demos/ads/vast/vast.xml"
let ad1 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "start")
let ad2 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "start")
let ad3 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "00:00:15")
let ad4 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "00:00:15")
let ad5 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "end")
let source = SourceDescription(source : typedSource, ads: [ad1, ad2, ad3, ad4, ad5])

theoplayer.source = source
```

### Scheduling a skippable mid-roll

When using the `csai` ad integration, you can define when an VAST ad can be skipped through the `skipOffset` property.

However, it is recommended to leverage the `skipOffset` property in your VAST (or VMAP) file instead, and adhere to the [VAST standard](https://iabtechlab.com/standards/vast/), because this offers the widest support across ad integrations and platforms.

The following snippets demonstrate how to allow viewers to skip a mid-roll after 5 seconds.

Note that the `skipOffset` property is not supported when using other ad integrations, such as Google IMA, SpotX and FreeWheel because we are dependent on third-party APIs.

#### Web SDK

```javascript
player.source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
    },
  ],
  ads: [
    {
      sources: { src: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml', type: 'vast' },
      timeOffset: '00:00:15',
      skipOffset: '5',
    },
  ],
};
```

## VMAP

Scheduling a VMAP advertisement is similar to scheduling a VAST advertisement. However, you don't define the `timeOffset`, because the VMAP playlist defines the offsets of each ad break it contains. The time offset helps VAST ads to play at a specific timestamp. VMAP ads can define that behavior inside their manifest file, thus they should not have a timeOffset parameter. This property may not be configured for ad types other than `VAST`. Setting a `timeOffset` on a `VMAP` ad will cause your ads not to be scheduled correctly, unless you explicitly configured an `AdSource.type`, in which case `timeOffset` will be ignored. This is because the player must decide up front when to load the ad source: `VMAP` ads must be loaded immediately in order to schedule them correctly, while loading a `VAST` ad can be deferred until right before the `timeOffset` at which to play them. Therefore, if a `timeOffset` is configured without an explicit `AdSource.Type`, the player will assume that it's a `VAST` ad.

The snippets below demonstrate how to configure a VMAP advertisement.

#### Web SDK

```js
// Declare a VMAP ad source. No timeOffset here, because the VMAP itself arranges this.
player.source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
    },
  ],
  ads: [
    {
      sources: { src: 'https://cdn.theoplayer.com/demos/ads/vmap/single-pre-mid-post-no-skip.xml', type: 'vmap' },
      integration: 'csai', // When no integration is provided, the player defaults to `csai`.
    },
  ],
};
```

#### Android SDK

```kotlin
val typedSource = TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8")
val sourceDescription = SourceDescription.Builder(typedSource.build())

sourceDescription.ads(
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vmap/single-pre-mid-post-no-skip.xml")
        .build()
)

theoPlayer.source = sourceDescription.build()
```

#### iOS/tvOS SDK

```swift
let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")

let vmapSource = "https://cdn.theoplayer.com/demos/ads/vmap/single-pre-mid-post-no-skip.xml"
let ad = GoogleImaAdDescription(src : vmapSource)

let source = SourceDescription(source : typedSource, ads: [ad])
theoplayer.source = source
```

## Dynamic scheduling

If you've read our [Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/user-guide.md#dynamic-ad-scheduling), you might have picked up that you can also dynamically schedule VAST advertisements in THEOplayer. All previous samples in this article use static, pre-defined scheduling; you schedule the ads whenever you schedule the stream. With dynamic scheduling, you schedule ads at runtime.

You use the `Ads` interface to schedule an `AdDescription` at runtime. More specifically, you invoke the `ads.schedule(<yourAdDescription>)` function when your video is already playing.

Note that specifying the `timeOffset` is optional, and that this value is an absolute value. For example, let's consider that your current playhead position is at the 20 seconds mark, and that you want a and you schedule an ad at the 30 seconds mark. To achieve this, you would set `timeOffset: "00:00:30"`, and not to `timeOffset: "00:00:10"`, because this would be 10 seconds in the past, and the ad would instantly start playing.

The following samples illustrate the `schedule` function across different SDKs. Invoking the following example functions when the video is already playing will instantly schedule the VAST ad to be played:

#### Web SDK

```javascript
player.ads.schedule({
  sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
});
```

#### Android SDK

```kotlin
theoPlayer.ads.schedule(
    GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
        .build()
)
```

#### iOS/tvOS SDK

```swift
theoplayer.ads.schedule(adDescription: GoogleImaAdDescription(src: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml"))
```

## Resources

* [Samples for Web SDK](https://github.com/THEOplayer/samples-html5-sdk)
* [Samples for Android SDK](https://github.com/THEOplayer/samples-android-sdk)
* [Samples for iOS SDK](https://github.com/THEOplayer/samples-ios-sdk)

---

# Yospace

Yospace is a Server-Side Ad Insertion solution. A demo for the Web SDK can be found [here](https://demo.theoplayer.com/ssai).

##### Web SDK

You need to set up [THEOplayer Yospace Connector for Web](https://github.com/THEOplayer/web-connectors/tree/main/yospace). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/web/yospace) section to learn all about how to integrate and use the Yospace connector on Web SDK.

##### Android (TV) SDK

You need to set up [THEOplayer Yospace Connector for Android](https://github.com/THEOplayer/android-connector/tree/master/connectors/yospace). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/android/yospace) section to learn all about how to integrate and use the Yospace connector on Android (TV) SDK.

##### iOS (/tvOS) SDK

You need to set up [THEOplayer Yospace connector for iOS](https://github.com/THEOplayer/iOS-Connector/tree/main/Code/Yospace). Please refer to [this](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/connectors/ios/yospace) section to learn all about how to integrate and use the Yospace connector on iOS (/tvOS) SDK.

## Conclusion

THEOplayer partnered with Yospace to fully integrate their Server-Side Ad Insertion solution, allowing you to play their streams in a breeze.

This partnership means that we are compatible with each other: THEOplayer has a long history with and is optimized to play Yospace streams. We regularly validate our connectors and are the first to know about changes to the Yospace infrastructure.

## Resources:

* [Getting started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)
* [Getting started on Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/getting-started.md)
* [Getting started on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/ios/getting-started.md)
* [Yospace website](https://www.yospace.com/)

---

# How to display visual cues on the timeline to mark mid-rolls?

You may ask this question if you want to let the user know when and how many mid-rolls there are during the video.

Similar questions may be:

* Can I show where my ad is during the video?
* How can I let the user know when the ads will be during the video like in YouTube?
* Can ad markers be added to the timeline?

Showing visual cues indicating the moment in which the ads will start is certainly useful. **This is not (yet) a THEOplayer standard feature, but what follows is a first step in that direction**. Please keep in mind that this solution is still in development and has to date several limitations.

## Prerequisites and limitations

* It only works for THEOplayer ad integration

* A timeOffset for each roll must be included in the AdDescription

* timeOffset values must be one of the following:

* a keyword (“start” and “end” allowed);

* a number (seconds from video beginning);

* undefined (which indicates a pre-roll).

* it has only been tested on Chrome, Firefox and Edge for Win 10 and with the standard THEOplayer UI.

## The code

Add this line to your CSS

```css
.adCue {
  width: 0.3em;
  height: 100%;
  background-color: white;
  position: absolute;
  top: 0;
}
```

Your AdDescription should look something like this

```js
player.source.ads: [
    {
        "sources": "path/to/your-pre/midroll1.xml",
            "timeOffset": value //valid values: ["start", "end", numbers]
    },
    {
        "sources": "path/to/your-pre/midroll2.xml",
            "timeOffset": value //valid values: ["start", "end", numbers]
    },
    {...}
]
```

Include (or call) this JavaScript snippet on your page:

THEOdisplayCues.js

```js
var adsPresent = !!player.source.ads;
var contentDuration = 0;
var to = [];
var checker = true;
var playedAds = [];

player.addEventListener('pause', () => {
  checker = false;
});
player.addEventListener('playing', () => {
  var adIsPlaying = player.ads.playing;
  detectTimeOffset();
  detectDuration(adIsPlaying);
  if (!checker) {
    checker = adIsPlaying;
  }
  if (checker) {
    !adIsPlaying ? drawCues() : destroyCues();
  }
});

player.addEventListener('sourcechange', function () {
  playedAds.length = 0;
});

player.ads.addEventListener('adend', (adEvent) => {
  playedAds.push(adEvent.ad.adBreak.timeOffset);
});

function drawCues() {
  var progressBar = element.querySelector('.vjs-progress-control.vjs-control');

  for (var i = 0; i < to.length; i++) {
    var timeOffset = to[i];

    if (playedAds.indexOf(timeOffset) === -1) {
      var left = (to[i] * progressBar.offsetWidth) / contentDuration;
      var div = document.createElement('div');
      div.setAttribute('to', to[i]);
      div.classList.add('adCue');
      div.style.left = left + 'px';
      progressBar.children[0].appendChild(div);
    }
  }
}

function destroyCues() {
  var cues = element.querySelectorAll('.vjs-progress-control.vjs-control .adCue');
  for (cue of cues) {
    cue.parentNode.removeChild(cue);
  }
}

function detectDuration(adIsPlaying) {
  if (!adIsPlaying) {
    contentDuration = player.duration;
    //console.log("Duration ",contentDuration)
  }
  var t = 0;
  for (var ad of player.source.ads) {
    to[t] = to[t] == 'end' ? contentDuration : to[t];
    t++;
  }
}

function detectTimeOffset() {
  if (adsPresent) {
    var t = 0;
    for (var ad of player.source.ads) {
      to[t] = ad.timeOffset == undefined ? 0 : ad.timeOffset == 'start' ? 0 : ad.timeOffset;
      t++;
    }
  }
  //console.log("TimeOffsets ",to);
}
```

---

# FreeWheel

This guide explains how to set up THEOplayer in combination with FreeWheel, an advertisement vendor.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | No          | No      | No       | No             | N/A            |

## Prerequisites

There are prerequisites when using FreeWheel through THEOplayer.

1. You must enable the `freewheel` module when building your THEOplayer SDK through the [THEOplayer Development Portal](https://portal.theoplayer.com).
2. This guide expects that you are a FreeWheel client and that you have ad campaigns ready for use. Information on FreeWheel can be found at <https://freewheel.com>.
3. You must have access to the `FreeWheel SDK`, as explained further in this guide.

## How to integrate FreeWheel

### Code Examples

This example explains how you do a basic implementation of FreeWheel in THEOplayer.

##### Web SDK

The FreeWheel integration is currently only available on the Web SDK.

After setting up your basic page containing THEOplayer, you need to add the FreeWheel MRM client SDK to the page:

`<script type='text/javascript' src='https://mssl.fwmrm.net/libs/adm/6.xx.x/AdManager.js'></script>`

Next, you add a [`FreeWheelAdDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/FreeWheelAdDescription) to your source that specifies the FreeWheel tokens. An example sourceDescription could look like this:

```html
...
<!-- make sure to link to a valid version number -->
<script type="text/javascript" src="https://mssl.fwmrm.net/libs/adm/6.xx.x/AdManager.js"></script>
... player.source = { sources : [{ src : 'your.m3u8', type : 'application/x-mpegurl' }], ads: [{ integration: 'freewheel', networkId: 96749, assetId:
'DemoVideoGroup.01', profile: 'global-js', assetDuration: 22, adServerUrl: 'https://demo.v.fwmrm.net/ad/g/1', siteSectionId: 'DemoSiteGroup.01',
cuePoints: [{ adUnit: 'preroll' }] }] };
```

We configure cuePoints in this example. This is needed for some set-ups or completely optional for others. THEOplayer will create a FreeWheel temporalSlot behind the screens, which is a request to schedule an advertisement at said point. It is up to FreeWheel (and the campaign settings) to decide whether it will insert an advertisement at this requested time. Not all campaigns need it and for some campaigns the requested cuePoints might even be ignored by FreeWheel.

##### Android SDK

This API is currently not available on the Android (TV) SDK.

##### iOS/tvOS SDK

This API is currently not available on the iOS (/tvOS) SDK.

## Resources

The following resources provide more information:

1. [THEOplayer Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)

2. [FreeWheelAdDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/FreeWheelAdDescription)

3. [FreeWheel website](https://freewheel.com)

---

# SpotX

SpotX is a global video ad serving platform providing digital media owners with a solution that allows them to monetize their content with video advertising across desktop, mobile and connected devices.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | No          | No      | No       | No             | No             |

## Prerequisites

Your THEOplayer SDK must have the `SpotX` module enabled. You can enable this module when building your THEOplayer SDK through the [THEOplayer Development Portal](https://portal.theoplayer.com).

## Integrating SpotX

### Web SDK

Add the SpotX ad integration when configuring the player

```javascript
player.source = {
    sources: ...,
    ads: [{
        integration: 'spotx',
        ...
    }]
}
```

the `{{SpotXAdDescription}}` object provides the following properties:

| Method            | Type             | Optional | Description                                                                                                                                                                                                                                                                                    |
| ----------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| integration       | string           | yes      | Use the value 'spotx' to use the SpotX ad integration. The SpotX integration uses Google IMA. To use Google IMA, it is required to load the SDK first. You can find the getting started of Google IMA sdk at: <https://developers.google.com/interactive-media-ads/docs/sdks/html5/quickstart> |
| id                | number or string | no       | Your SpotX id                                                                                                                                                                                                                                                                                  |
| cacheBuster       | boolean          | yes      | Add the cb parameter with a random number to the SpotX tag.                                                                                                                                                                                                                                    |
| maximumAdDuration | number or string | yes      |                                                                                                                                                                                                                                                                                                |
| custom            | SpotXData        | yes      | SpotX custom data                                                                                                                                                                                                                                                                              |
| app               | SpotXData        | yes      | SpotX app data                                                                                                                                                                                                                                                                                 |
| device            | SpotXData        | yes      | SpotX device data                                                                                                                                                                                                                                                                              |
| user              | SpotXData        | yes      | SpotX user data                                                                                                                                                                                                                                                                                |
| sources           | string           | yes      | SpotX ad tag (to directly set the SpotX source link)                                                                                                                                                                                                                                           |

Example:

```javascript
player.source = {
    sources: ...,
    ads: [{
        integration: 'spotx',
        id: 123456,
        cacheBuster: true,
        app: {
            bundle: 'com.exampleapps.example',
            name: 'My CTV App'
        },
        device: {
            ifa: '38400000-8cf0-11bd-b23e-10b96e40000d',
            ua: 'Mozilla/5.0 (iPhone; CPU iPhone OS 10_3 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) CriOS/56.0.2924.75 Mobile/14E5239e Safari/602.1',
            geo: {
                lat: -24.378528,
                lon: -128.325119
            },
            dnt: 1,
            lmt: 1,
        },
        custom: {
            category: ['category1', 'category2'],
            somekey: 'somevalue'
        },
        user: {
            yob: 1984,
            gender: 'm'
        }
    }
]};
```

### iOS/tvOS SDK

This API is currently not available on the iOS/tvOS SDK.

### Android (TV) SDK

This API is currently not available on the Android (TV) SDK.

---

# Google Dynamic Ad Insertion (DAI)

Google DAI is a Server-Side Ad-Insertion solution offered by Google where THEOplayer is pre-integrated and offers playback for HLS and DASH Streams. A demo can be found at <https://demo.theoplayer.com/google-dai>.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |

## Web SDK

### Prerequisites

1. Your THEOplayer SDK needs to have the `google-dai` module enabled.
2. You need to include the Google DAI JavaScript SDK as this is a dependency.

### Starting Template

The first thing you need is a valid THEOplayer setup. If you have no experience with setting up our player, we have an excellent [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md).

To get THEOplayer to work, you only need to do three things:

1. Reference the THEOplayer JavaScript library (and optionally the default CSS styles).
2. Add a container which can hold your video player with HTML.
3. Create your player through JavaScript using our [API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/Player).

A basic HTML page with a working THEOplayer could like the following:

```html
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>THEOplayer Web SDK: Getting Started</title>
        <metaname="viewport"content="width=device-width, initial-scale=1.0">
        <link rel="stylesheet" type="text/css" href='/path/to/ui.css'><!-- ads THEOplayer CSS -->
    </head>
    <body>

        <div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>

        <script type='text/javascript' src='/path/to/THEOplayer.js'></script><!-- ads THEOplayer library -->
        <script>

            var element = document.querySelector('.theoplayer-container');
            var player = new THEOplayer.Player(element);

            player.source = {
                sources : [{
                    src : 'your.m3u8',
                    type : 'application/x-mpegurl'
                }]
            };

        </script>
    </body>
</html>
```

Pretty self-explanatory, isn't it?

```html
<link rel="stylesheet" type="text/css" href="/path/to/ui.css" />
```

```html
<script type="text/javascript" src="/path/to/THEOplayer.js"></script>
```

The two snippets above are the references to the JS and CSS library.

```html
<div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>
```

The snippet above is your HTML container.

```javascript
<script>

var element = document.querySelector('.theoplayer-container');
var player = new THEOplayer.Player(element);

player.source = {
    sources : [{
        src : 'your.mpd',
        type : 'application/dash+xml'
    }]
};

</script>
```

The snippet above initializes your player, including a HLS source.

### Integrating Google DAI

Add a Google DAI JavaScript library.

```javascript
<script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
```

Add a Google DAI ad configuration to the sources.

```javascript
const TYPES = {
  hls: 'application/vnd.apple.mpegurl',
  dash: 'application/dash+xml',
};

// example and reference tester at https://developers.google.com/interactive-media-ads/docs/sdks/html5/dai/vastinspector
const SOURCES = {
  dash: {
    vod: {
      integration: 'google-dai',
      availabilityType: 'vod',
      apiKey: null,
      contentSourceID: '<contentSourceID>',
      videoID: '<videoID>',
    },
    live: {
      integration: 'google-dai',
      availabilityType: 'live',
      apiKey: null,
      assetKey: '<assetKey>',
    },
  },
  hls: {
    vod: {
      integration: 'google-dai',
      availabilityType: 'vod',
      apiKey: null,
      contentSourceID: '<contentSourceID>',
      videoID: '<videoID>',
    },
    live: {
      integration: 'google-dai',
      availabilityType: 'live',
      apiKey: null,
      assetKey: '<assetKey>',
    },
  },
};
// Configure THEOplayer Source
const MANIFEST_TYPE = 'hls'; // 'hls' / 'dash'
const AVAILABILITY_TYPE = 'vod'; // 'vod' or 'live'

player.source = {
  sources: {
    type: TYPES[MANIFEST_TYPE],
    ssai: SOURCES[MANIFEST_TYPE][AVAILABILITY_TYPE],
  },
};
```

## Android SDK

Using Google DAI in the Android SDK consists of 3 steps:

### Importing Google DAI feature module

Add `implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-dai:+'` to your module `build.gradle` file, as demonstrated below:

```groovy
dependencies {
    // ...
    implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
    implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-dai:+'
    // ...
}
```

### Creating an instance of Google DAI Integration

> **Tip**
>
> If you're using [automatic integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/features.md#adding-integrations-automatically), you can skip this step.

Create a `GoogleDaiIntegration` through the `GoogleDaiIntegrationFactory`, and add it to your player instance, as demonstrated below:

```kotlin
val theoplayerView = THEOplayerView(context)
val daiIntegration = GoogleDaiIntegrationFactory.createGoogleDaiIntegration(theoplayerView)
theoplayerView.player.addIntegration(daiIntegration)
```

### Using a Google DAI Source

Use a [GoogleDaiVodConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/source/ssai/dai/GoogleDaiVodConfiguration) or [GoogleDaiLiveConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/source/ssai/dai/GoogleDaiLiveConfiguration) to create a `GoogleDaiTypedSource` to request stream, as demonstrated below:

```kotlin
theoplayerView.player.source = SourceDescription.Builder(
    GoogleDaiTypedSource.Builder(
        GoogleDaiVodConfiguration.Builder("api_key", "content_source_id", "video_id")
            .build()
    )
    .type(SourceType.DASH)
    .build()
).build()
```

or:

```kotlin
theoplayerView.player.source = SourceDescription.Builder(
    GoogleDaiTypedSource.Builder(
        GoogleDaiLiveConfiguration.Builder("api_key", "asset_key")
            .build()
    )
    .type(SourceType.DASH)
    .build()
).build()
```

### Notes

The Google DAI integration exposes events through the Ads API. More information is available at ["How to subscribe to ad events"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-subscribe-to-ad-events.md#android-sdk).

The integration exposes a number of additional methods. These are available directly on the [`GoogleDaiIntegration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/ads/dai/GoogleDaiIntegration) object, or indirectly through `player.ads.dai` (only for Kotlin). For example:

* [requestStream(StreamRequest, AdsRenderingSettings)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/ads/dai/GoogleDaiIntegration#requestStream\(StreamRequest,AdsRenderingSettings\)) can be used to request stream through the native Google DAI API.
* [contentTimeForStreamTime(double)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/ads/dai/GoogleDaiIntegration#contentTimeForStreamTime\(double\)) / [streamTimeForContentTime(double)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/ads/dai/GoogleDaiIntegration#streamTimeForContentTime\(double\)) can be used to convert content time to stream time and vice versa.

## iOS SDK

To use Google DAI with the THEOplayer iOS SDK, the **THEOplayer GoogleIMA Integration** should be integrated. For instructions on installation, importing and adding the integration, [please refer to this guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/google-ima.md#ios-sdk).

### Usage

Define a `GoogleDAITypedSource` and a `GoogleDAIVodConfiguration` to pass to theoplayer's source:

```swift
let daiConfig = GoogleDAIVodConfiguration(videoID: "tears-of-steel", contentSourceID: "2548831", apiKey: "", authToken: nil, streamActivityMonitorID: nil, adTagParameters: nil)
let typedSource = GoogleDAITypedSource(ssai: daiConfig)
theoplayer.source = SourceDescription(source: typedSource)
```

or

```swift
let daiConfig = GoogleDAILiveConfiguration(assetKey: "c-rArva4ShKVIAkNfy6HUQ", apiKey: "", authToken: nil, streamActivityMonitorID: nil, adTagParameters: nil)
let typedSource = GoogleDAITypedSource(ssai: daiConfig)
theoplayer.source = SourceDescription(source: typedSource)
```

And THEOplayer will take care of the rest.

Additional DAI APIs can be found on the `imaIntegration.dai` endpoint.

## Conclusion

THEOplayer SDK and Google DAI are fully pre-integrate to deliver Server-Side Ad Insertion solution, allowing customers to play streams in a breeze.

Extra resources:

1. [Google DAI Pre-Integration API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/GoogleDAIConfiguration)
2. [THEOplayer Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)
3. [Google DAI website](https://developers.google.com/interactive-media-ads)

Related articles

* [Google DAI HTML Reference](https://developers.google.com/interactive-media-ads/docs/sdks/html5/dai)
* [Google DAI Android Reference](https://developers.google.com/interactive-media-ads/docs/sdks/android/dai)
* [Google DAI iOS Reference](https://developers.google.com/interactive-media-ads/docs/sdks/ios/dai)

---

# Prebid.js

This article explains how you can connect THEOplayer with Prebid.js. Prebid.js is an open-source header bidding solution. On the client-side, you can request bids from multiple ad networks, take a winning bid and select its associated advertisement. You want to configure and play this selected advertisement in THEOplayer.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| N/A     | N/A         | N/A     | N/A      | N/A            | N/A            | N/A      |

N/A was selected because Prebid.js is a separate library.

You can connect Prebid.js with THEOplayer on any platform that supports both Prebid.js and THEOplayer.

## Connecting Prebid.js and THEOplayer

Prebid.js allows you to request bids. This request will respond with bids through a callback function. In this callback function, you have to select a winning bid, extract the ad tag URL. You can configure this URL as THEOplayer's ad source.

### Code Examples

The code example below is based on the documentation offered by Prebid.org [here](https://docs.prebid.org/dev-docs/examples/instream-banner-mix.html).

##### Web SDK

The sample application at <https://cdn.theoplayer.com/demos/prebidjs.html> is an example of implementing Prebid.js on top of the THEOplayer Web SDK.

The example above schedules advertisements as pre-rolls (or mid-rolls or post-rolls). You can also dynamically schedule advertisements with the Ads API, as explained in [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-set-up-vast-and-vmap.md).

##### Android (TV) SDK

Refer to <https://docs.prebid.org/prebid-mobile/pbm-api/android/code-integration-android.html> to integrate on Android SDK. The same THEOplayer API to configure advertisements is available on the Android SDK.

##### iOS/tvOS SDK

Refer to <https://docs.prebid.org/prebid-mobile/pbm-api/ios/code-integration-ios.html> to integrate on iOS/tvOS SDK. The same THEOplayer API to configure advertisements is available on the iOS SDK.

## Resources

The following resources provide more information:

* [What is Prebid?](https://prebid.org/product-suite/prebidjs/)
* [Prebid.js documentation](https://docs.prebid.org/)
* [Prebid.js on GitHub](https://github.com/prebid/Prebid.js)

---

# Google IMA

THEOplayer offer supports for Google IMA as an ad integration system. Users of Google Ad Manager (formerly known as DoubleClick for Publishers) should use this ad integration.

Scheduling and tracking ads through the Google IMA ad integration is similar to the default ad integration, so you're advised to read through ["How to set-up VAST and VMAP](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-set-up-vast-and-vmap.md).

The main difference with the default THEO ad integration is that you need to indicate through the API that you want to use Google IMA as the ad integration, and that you need to include the Google IMA SDK.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | No             |

## Web SDK

To use Google IMA in the Web SDK,

1. You need to include the Google IMA SDK,
2. You need to specify `integration: "google-ima"` in your `AdDescription`.

### Include the IMA SDK

Google IMA has a dependency on the IMA SDK. Hence, this library needs to be included. The following snippet demonstrates how the IMA SDK can be included:

```html
<script type="text/javascript" src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
```

Alternatively, you can include the debug version of the IMA SDK for troubleshooting, which will provide extra logs from IMA on console:

```html
<script type="text/javascript" src="https://imasdk.googleapis.com/js/sdkloader/ima3_debug.js"></script>
```

### Specify the integration

You need to set integration to `"google-ima"`, as demonstrated by the snippet below which configures a pre-roll VAST ad.

```javascript
player.source = {
  sources: [
    {
      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
    },
  ],
  ads: [
    {
      integration: 'google-ima',
      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
      timeOffset: 'start',
    },
  ],
};
```

### Limitations

* There's a known issue within the IMA HTML5 SDK where it does not work well with multiple VPAID ads in a VMAP. More specifically when the `ImaSdkSetting` `vpaidMode` is set to `enabled` and the `AdsRenderingSetting` `enablePreloading` is set to `true`, it will not manage to play all ads (these are the default configurations when using the Google IMA integration in THEOplayer). The production IMA SDK doesn't throw any error in this scenario, the [debug SDK](https://imasdk.googleapis.com/js/sdkloader/ima3_debug.js), however, prints `Vpaid Error: VPAID ad called play on video element before start was called on VPAID manager` in the console in this case. This can be resolved by either using `vpaidMode` `insecure` or by disabling preloading. Both can be achieved by specifying your preference in the [AdsConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsConfiguration).

## Android SDK

Using Google IMA in the Android SDK consists of 3 steps:

1. Add the `integration-ads-ima` dependency to your module's `build.gradle`.
2. Use the `GoogleImaIntegrationFactory` to create and add a `GoogleImaIntegration`.
3. Use a `GoogleImaAdDescription` to schedule ads.

### Add the `integration-ads-ima` dependency

Add `implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-ima:+'` to your module `build.gradle` file, as demonstrated below:

```groovy

dependencies {
    // ...
    implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
    implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-ima:+'
    // ...
}
```

### Use the `GoogleImaIntegrationFactory`

> **Tip**
>
> If you're using [automatic integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/features.md#adding-integrations-automatically), you can skip this step.

Create a `GoogleImaIntegration` through the `GoogleImaIntegrationFactory`, and add it to your player instance, as demonstrated below:

```kotlin
import com.theoplayer.android.api.ads.ima.GoogleImaIntegrationFactory

val theoplayerView = THEOplayerView(context)
val imaIntegration = GoogleImaIntegrationFactory.createGoogleImaIntegration(theoplayerView)
theoplayerView.player.addIntegration(imaIntegration)
```

### Use a `GoogleImaAdDescription`

Use a [`GoogleImaAdDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/source/addescription/GoogleImaAdDescription) to schedule advertisements, as demonstrated below:

```kotlin
val typedSource = TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8")
    .build()

val imaAdDescription = GoogleImaAdDescription.Builder("https://cdn.theoplayer.com/demos/ads/vast/vast.xml")
    .timeOffset("start")
    .build()

val sourceDescription = SourceDescription.Builder(typedSource)
    .ads(imaAdDescription)
    .build()

theoplayerView.player.source = sourceDescription
```

### Next steps

The Google IMA integration exposes events through the Ads API. More information is available at ["How to subscribe to ad events"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-subscribe-to-ad-events.md#android-sdk).

The integration exposes a number of additional methods. These are available directly on the [`GoogleImaIntegration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/ads/ima/GoogleImaIntegration) object, or indirectly through `player.ads.ima` (only for Kotlin). For example, [`schedule()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/ads/ima/GoogleImaIntegration#schedule\(GoogleImaAdDescription\)) can be used to schedule ads dynamically, and [`requestAds()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/ads/ima/GoogleImaIntegration#requestAds\(AdsRequest,AdsRenderingSettings\)) can be used to request ads through the native Google IMA API.

### Updating the Google IMA SDK

The IMA integration depends on Google's [IMA SDK for Android](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/) from [Maven](https://mvnrepository.com/artifact/com.google.ads.interactivemedia.v3/interactivemedia). By adding the THEOplayer IMA integration to your Gradle dependencies, the Google IMA SDK is also automatically added to your app.

Our integration is tested with a specific version of the Google IMA SDK, and by default Gradle will automatically add the same version to your app. However, you can overwrite this [with a later version](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/history) (at your own risk) by manually adding a dependency on `com.google.ads.interactivemedia.v3:interactivemedia` to your `build.gradle`.

## iOS SDK

To use Google IMA with the THEOplayer iOS SDK, the **THEOplayer GoogleIMA Integration** should be integrated. The integration is a lightweight module written in Swift, for serving advertisements from the Google IMA SDK.

> **Info**
>
> The THEOplayer GoogleIMA integration supports both iOS and tvOS platforms.

### Installation

The THEOplayer GoogleIMA integration is published on the following package managers:

#### CocoaPods

Simply add the following to your project's Podfile:

```ruby
pod 'THEOplayer-Integration-GoogleIMA'
```

The above entry automatically manages the fetching of the IMA SDK dependency.

In case where the integrator would want to manage fetching a specific version of the IMA SDK, then replace the Podfile entry with:

```ruby
pod 'THEOplayer-Integration-GoogleIMA/Base'
pod 'GoogleAds-IMA-iOS-SDK', '3.24.0' # specify the desired version
# or
pod 'GoogleAds-IMA-tvOS-SDK', '4.14.1' # specify the desired version
```

#### Swift Package Manager

Please check the [installation instruction found here](https://github.com/THEOplayer/theoplayer-sdk-apple/README.md#installation)

> **Info**
>
> This will not get the IMA SDK, but only the THEOplayer IMA integration. The IMA SDKs can be found at <https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios> and <https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos>. You should add these to your Xcode project's `Package Dependencies` for SPM to fetch.

### Import

Import the framework in the source files where it will be used:

```swift
import THEOplayerGoogleIMAIntegration
```

You will also need the THEOplayer core SDK since the THEOplayer GoogleIMA integration extends its functionality.<br />To import the THEOplayer core SDK framework add:

```swift
import THEOplayerSDK
```

### Usage

Initialize the integration and pass it to the `THEOplayer` instance:

```swift
let configBuilder = THEOplayerConfigurationBuilder()
configBuilder.license = "your_theoplayer_license"
let theoplayer = THEOplayer(configuration: configBuilder.build()
let imaIntegration = GoogleIMAIntegrationFactory.createIntegration(on: theoplayer)
theoplayer.addIntegration(imaIntegration)
```

Optionally, the `createIntegration` accepts a configuration argument of type IMASetting:

```swift
import GoogleInteractiveMediaAds // required to access definitions such as `IMASettings`
..
..
..
let settings = IMASettings()
settings.language = "en"
let imaIntegration = GoogleIMAIntegrationFactory.createIntegration(on: theoplayer, with: settings)
```

Define a `GoogleImaAdDescription` in your source object to specify the advertisement:

```swift
let adSrc = "https://cdn.theoplayer.com/demos/ads/vast/dfp-preroll-skip-5s.xml"
let adDescription = GoogleImaAdDescription(src: adSrc)
// or
let adDescriptionWithOffset = GoogleImaAdDescription(src: adSrc, timeOffset: "10")
```

The time offset helps VAST ads to play at a specific timestamp. VMAP ads can define that behavior inside their manifest file, thus they should not have a timeOffset parameter.

Finally, we pass the ad description to the player either by setting it in the source:

```swift
let source = "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"
let mimeType = "application/x-mpegurl"
let typedSource = TypedSource(src: source, type: mimeType)
let sourceDescription = SourceDescription(source: typedSource, ads: [adDescription])
theoplayer.source = sourceDescription
```

Or by calling the ad schedule API:

```swift
theoplayer.ads.schedule(adDescription: adDescription)
```

> **A VAST ad without a timeOffset argument in the description will be scheduled to play at the player's currentTime. If the source is not loaded yet, it will be scheduled as a preroll.**

### Limitations

1. Prerolls must be loaded after the player view is fully rendered and ready. This means attempting to load the ad in the `viewDidLoad` lifecycle will result in a failed request.
2. There is a known bug by Apple that throws runtime warnings concerning the main thread. If you run into this warning while using the IMA SDK, please check [this thread for more information.](https://developer.apple.com/forums/thread/714467?answerId=734799022#734799022)
3. When using `SwiftUI`, make sure to wrap the `THEOplayer` in a `UIViewControllerRepresentable` rather than a `UIViewRepresentable`, as the Google IMA SDK requires a `UIViewController` as a precondition before making ad requests. Otherwise, the ads will not play.

## Remarks

* The release notes for IMA SDK can be found on their respective pages: [IMA HTML5 SDK release history](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/history), [IMA iOS SDK release history](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/history) and [IMA Android SDK release history](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/history).
* THEOplayer internally supports IMA SDK up until a certain version across different SDKs. We regularly update the internal code to stay up to date with the latest version of IMA SDK. Later versions of IMA SDK should work as expected, however there could be cases where a fix for a breaking change or a newly introduced API is required. Please reach out to us if you require support for a more recent IMA SDK since we intend to rectify this limitation.
* The limitations documented on the support and compatibility pages of IMA SDK also apply to THEOplayer SDK when IMA integration is used. You can find the support matrix of IMA SDK on platform specific pages: [HTML5](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/compatibility), [Android](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/compatibility) and [iOS](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/compatibility).
* You can try out the snippets mentioned here on our samples apps for [Web SDK](https://github.com/THEOplayer/samples-html5-sdk), [iOS SDK](https://github.com/THEOplayer/samples-ios-sdk) and [Android SDK](https://github.com/THEOplayer/samples-android-sdk/).

---

# How to subscribe to ad events

When building a custom UI, or when logging events to an analytics service, app developers often need to be able to listen (and react) to ad events. For example, if an ad break starts, they want to draw a countdown on top of their UI. Alternatively, when an ad error occurs, they want to log this to an analytics server.

This article explains how you can programmatically subscribe to ad-related events across different SDKs.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | No             |

## Subscribing to an event

This subsection explains how you detect ad-related events. The other subsections zoom in on particular use-cases, such as detecting the beginning and end of an ad.

### Client-side ads

If you are scheduling [client-side advertisements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-set-up-vast-and-vmap.md), then you use the `Ads` interface to detect ad events throughout the Web, Android and iOS SDK.

#### Web SDK

The `Player` API exposes an [`ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#ads) property which belongs to the [`Ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Ads) interface. Because this [`Ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Ads) interface inherits from [`EventDispatcher<AdsEventMap>`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap), you can leverage event listeners in this interface.

The ad-related events are documented in [`AdsEventMap`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap).

To subscribe to an event, you select an event from this page, use the `Ads` interface, call the `addEventListener` method, and set the event as the first parameter, and the callback as the second parameter.

For example, if you want to track the start of an ad break, you could use the following snippet:

```javascript
player.ads.addEventListener('adbreakbegin', function (event) {
  console.log(event);
});
```

The following snippet should log most events to the console.

```javascript
player.ads.addEventListener(
  [
    'adbegin',
    'adbreakbegin',
    'adbreakchange',
    'adbreakend',
    'adbuffering',
    'addad',
    'addadbreak',
    'adend',
    'aderror',
    'adfirstquartile',
    'adimpression',
    'adloaded',
    'admetadata',
    'admidpoint',
    'adskip',
    'adthirdquartile',
    'removeadbreak',
    'updatead',
    'updateadbreak',
  ],
  console.log
);
```

Note that when dealing with client-side advertisements, you have different types of integrations, as explained at [How to setup VAST and VMAP](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-set-up-vast-and-vmap.md). The impact of this is that some events are not available throughout all integrations.

For example, if you schedule `https://cdn.theoplayer.com/demos/preroll.xml`, which is a single linear VAST ad, through the "Google IMA integration" [on our advertisement tester](https://www.theoplayer.com/theoplayer-demo-advertisement-tester-vpaid-vast-vmap), the above snippet will trigger the following events:

> `addad`, `updateadbreak`, `updatead`, `adloaded`, `adbreakbegin`, `adbegin`, `adimpression`, `adfirstquartile`, `admidpoint`, `adthirdquartile`, `adend`, `adbreakend`, `removeadbreak`

When you do the same for the `csai` ad integration, you get the following events:

> `adloaded`,`adbreakchange`,`adbreakbegin`,`adbegin`,`adend`,`adbreakend`

#### Android SDK

The `Player` API exposes an [`getAds()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#getAds--) method which belongs to the [`Ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/ads/Ads) interface. Because this `Ads` interface inherits from [`EventDispatcher<AdEvent>`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/ads/AdEvent),you can leverage event listeners in this interface.

The Android SDK currently only allows ad playback through [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/google-ima.md#android-sdk). The available events are documented in [`GoogleImaAdEventType`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/ads/ima/GoogleImaAdEventType).

To subscribe to an event, you select an appropriate `GoogleImaAdEventType` or `AdsEventType`, use the `Ads` interface, call the `addEventListener` method, and set the event as the first parameter, and the callback as the second parameter.

For example, if you want to track the start of an ad break with the Android SDK, you could use the following snippet:

```kotlin
theoPlayer.ads.addEventListener(GoogleImaAdEventType.AD_BREAK_STARTED) {
    Log.d("ADS", "AD_BREAK_STARTED")
}
```

#### iOS/tvOS SDK

The `Player` API exposes an [`ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C3adsAA3Ads_pvp) property which belongs to the [`Ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/Ads) interface. Because this `Ads` interface inherits from [`EventDispatcher`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Ads%20Events), you can leverage event listeners in this interface.

The ad-related events are documented in [AdsEventTypes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/AdsEventTypes).

To subscribe to an event, you select an event from this page, use the `Ads` interface, call the `addEventListener` method, and set the event as the first parameter, and the callback as the second parameter.

For example, if you want to track the start of an ad break, you could use the following snippet:

```swift
player.ads.addEventListener(type: AdsEventTypes.AD_BREAK_BEGIN) { (event) in
    print(event)
}
```

## Ad begin and end

Detecting the start and stop of ad breaks and individual ad pods is a common requirement.

The THEOplayer API exposes event listeners which allow applications to hook into these events.

#### Web SDK

This use-case is an application of [Subscribing to an event](#subscribing-to-an-event), and relates to the following events:

* `adbegin`
* `adbreakbegin`
* `adbreakend`
* `adend`

For example, the following snippet would trigger the callback when an ad break begins:

```javascript
player.ads.addEventListener('adbreakbegin', function (event) {
  console.log(event);
});
```

You can swap `adbreakbegin` for the other events, or supply an array instead:

```javascript
player.ads.addEventListener(['adbegin', 'adbreakbegin', 'adbreakend', 'adend'], function (event) {
  console.log(event);
});
```

#### Android SDK

This use-case is an application of [Subscribing to an event](#subscribing-to-an-event), and relates to the following events:

* `STARTED`
* `AD_BREAK_STARTED`
* `AD_PERIOD_STARTED`
* `AD_BREAK_ENDED`
* `AD_PERIOD_ENDED`
* `COMPLETED`
* `ALL_ADS_COMPLETED`

```kotlin
theoPlayer.ads.addEventListener(GoogleImaAdEventType.AD_BREAK_STARTED) {
    Log.d("ADS", "AD_BREAK_STARTED")
}
```

#### iOS/tvOS SDK

This use-case is an application of [Subscribing to an event](#subscribing-to-an-event), and relates to the following events:

* `AD_BEGIN`
* `AD_BREAK_BEGIN`
* `AD_END`
* `AD_BREAK_END`

```swift
player.ads.addEventListener(type: AdsEventTypes.AD_BREAK_BEGIN) { (event) in
    print(event)
}
```

## Ad error

Ad error events might be triggered when an ad blocker is active, or when an "empty" ad is returned. As an app developer, you might want to detect and possibly react to this.

If you are scheduling [client-side advertisements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-set-up-vast-and-vmap.md) then you use the `Ads` interface to detect the ad errors.

#### Web SDK

This use-case is an application of [Subscribing to an event](#subscribing-to-an-event), specifically the `aderror` event.

The following snippet would trigger the callback when an ad error occurs:

```javascript
player.ads.addEventListener('aderror', function (event) {
  console.log(event);
});
```

#### Android SDK

This use-case is an application of [Subscribing to an event](#subscribing-to-an-event), specifically the `AD_ERROR` event.

The following snippet would trigger the callback when an ad error occurs:

```kotlin
theoPlayer.ads.addEventListener(GoogleImaAdEventType.AD_ERROR) {
    Log.d("ADS", "AD_ERROR")
}
```

#### iOS/tvOS SDK

This use-case is an application of [Subscribing to an event](#subscribing-to-an-event), specifically the `AD_ERROR` event.

The following snippet would trigger the callback when an ad error occurs:

```swift
player.ads.addEventListener(type: AdsEventTypes.AD_ERROR) { (event) in
    print(event)
}
```

### Server-side ads

If you're scheduling server-side ads, you might need to use a different interface than the `Ads` interface which you use when scheduling client-side ads.

* [Google DAI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/google-ima.md): if you're using Google DAI, you can use the same API as the one for client-side ads, as described in the sections above.
* [Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/yospace.md): if you're using Yospace, you must use the Yospace interface. You can read more about detecting ad-related events with Yospace at our [Yospace documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/yospace.md).
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ads.md): if you're using Uplynk, you can use the same API as the one for client-side ads, as described in the sections above. For now, you can also use the Uplynk Ads API. You can read more about detecting ad-related events with Uplynk at our [Uplynk documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ads.md#uplynk-ads-api).

If you're building a custom server-side ad insertion solution, you might be interested in using our `TextTrack` API to detect `id3/emsg/EventStream/EXT-X-DATERANGE` cues, and the `timeupdate` event in the `Player` interface to determine the current playhead position.

## Ad block detection

Refer to the article on [ad block detection](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/block-detection.md) for more information on detecting (and responding) to ad blockers.

## Resources

* More samples are available on our GitHub repository for [Web](https://github.com/THEOplayer/samples-html5-sdk), [Android](https://github.com/THEOplayer/samples-android-sdk) and [iOS](https://github.com/THEOplayer/samples-ios-sdk) SDKs.
* [THEOplayer advertisement tester](https://www.theoplayer.com/theoplayer-demo-advertisement-tester-vpaid-vast-vmap)

---

# MediaTailor

[AWS Elemental MediaTailor](https://docs.aws.amazon.com/mediatailor/index.html) is a service that provides scalable ad insertion and channel assembly. It is able to serve targeted ad content to viewers and create linear streams while maintaining broadcast quality in over-the-top (OTT) video applications. It supports HLS and DASH for both VOD and live workflows.

At the moment of writing only linear ads are supported, but it is possible to expand it to non-linear and companion ads as well.

### Web SDK

#### Configuration

There are three requirements to use a MediaTailor stream with THEOplayer:

* Have a THEOplayer build with the `mediatailor` feature flag set.
* The `src` is set to the session initialization URL.
* The integration parameter is set with the value `mediatailor`.

If everything is set up correctly, THEOplayer will play the stream and send the necessary tracking beacons.

```js
const player = new THEOplayer.Player(element, {
    libraryLocation: 'path/to/theoplayer',
    license: 'your-license-here',
    ...
});

player.source = {
    sources: [
        {
            src: '<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>',
            integration: 'mediatailor'
        }
    ]
}
```

Optionally, you can pass parameters regarding e.g. session data and device type by using the `adsParams` property, as described in the [MediaTailor documentation](https://docs.aws.amazon.com/mediatailor/latest/ug/ad-reporting-client-side.html#ad-reporting-client-side-enabling).

```js
player.source = {
  sources: [
    {
      src: '...',
      integration: 'mediatailor',
      adsParams: {
        param1: 'value1', // key is not case sensitive
        param2: 'value2', // Values can contain spaces. For example, 'value 2' is an allowed value.
      },
    },
  ],
};
```

#### Limitations

The scope of the MediaTailor integration for now is limited to sending the tracking beacons. This encapsulates only the events that can be sent with the default implementation of THEOplayer. For example skipping an ad is not yet supported so the events that correspond to skipping an ad will never occur.

Seeking is only disabled during an ad, no logic is in place for playing an ad if the user *seeked* past it.

### Android SDK

To use a MediaTailor stream with THEOplayer on Android SDK, first import our MediaTailor module dependency in your `build.gradle` file.

```groovy
implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-mediatailor:+' // add MediaTailor dependency
```

Then, add the MediaTailor integration to the `Player`.

> **Tip**
>
> If you're using [automatic integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/features.md#adding-integrations-automatically), you can skip this step.

```kotlin
val theoplayerView = THEOplayerView(context)
val mediaTailorIntegration = MediaTailorIntegrationFactory.createMediaTailorIntegration(theoPlayerView);
theoplayerView.player.addIntegration(mediaTailorIntegration)
```

Finally, set a [`MediaTailorSource`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/source/mediatailor/MediaTailorSource) to play.

```kotlin
val mediaTailorSource = MediaTailorSource(src = "<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>")

theoplayerView.player.source = SourceDescription(listOf(mediaTailorSource))

// or using the Builder pattern

val mediaTailorSource = MediaTailorSource
    .Builder("<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>")
    .build()

theoplayerView.player.source = SourceDescription
    .Builder(mediaTailorSource)
    .build()
```

Optionally, you can pass parameters regarding e.g. session data and device type by using the `adsParams` property, as described in the [MediaTailor documentation](https://docs.aws.amazon.com/mediatailor/latest/ug/ad-reporting-client-side.html#ad-reporting-client-side-enabling).

```kotlin
val adsParams = emptyMap<String, String>().toMutableMap()
adsParams["param1"] = "value1"
adsParams["param2"] = "value 2"
val mediaTailorSource = MediaTailorSource(
    src = "<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>",
    adParams = adsParams    // Note the deprecated parameter name
)

// or using the Builder pattern

val mediaTailorSource = MediaTailorSource
    .Builder("<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>")
    .adsParams(adsParams)
    .build()
```

> **Deprecated**
>
> The source definition currently still uses the deprecated `adParams` property. This will be replaced by the `adsParams` property in a future version.

---

# Custom Server Side Ad Insertion

THEOplayer provides a way to integrate with third-party advertisement providers, and have them report their ads and ad-related events through the THEOplayer APIs.

## Android SDK

### Prerequisites

Your THEOplayer SDK needs to be on version 7.6.0 or higher.

### Integration ID

To make use of the custom server side ad insertion, first you need an integration ID which will identify the provided sources and ads to the specific ad provider.

### ServerSideAdIntegrationFactory

You would also need to register a `ServerSideAdIntegrationFactory` that will receive a `ServerSideAdIntegrationController`. The controller can be used to create the THEOplayer `AdBreak`/`Ad` objects using the `AdBreakInit`/`AdInit` data. Additionally, it can be used to keep the player's state up-to-date such as when an ad begins or ends.

The `ServerSideAdIntegrationFactory` requires an implementation of the `ServerSideAdIntegrationHandler` interface. The handler will provide few callbacks that can be overridden which allows you to setup and clear the integration as needed.

A concrete implementation can be found [in the Yospace Connector](https://github.com/THEOplayer/android-connector/blob/master/connectors/yospace/src/main/java/com/theoplayer/android/connector/yospace/internal/YospaceAdIntegration.kt).

Meanwhile, an empty implementation would look like below. Details to follow.

```kotlin
player.ads.registerServerSideIntegration("integrationID") { controller ->
    object : ServerSideAdIntegrationHandler {

        override suspend fun setSource(source: SourceDescription): SourceDescription {
            return super.setSource(source)
        }

        override fun skipAd(ad: Ad) {
            super.skipAd(ad)
        }

        override suspend fun resetSource() {
            super.resetSource()
        }

        override suspend fun destroy() {
            super.destroy()
        }
    }
}
```

#### Setting a Source

When a new source is loaded into the player the `setSource(source: SourceDescription)` callback is triggered. It allows the integration to transform the source description, e.g. by calling an external service to replace the content URL (`TypedSource.src`), or by adding a fixed pre-roll linear ad to the list of ads (`SourceDescription.ads`).

#### Skipping an Ad

When an ad is requested to be skipped, the `skipAd(ad: Ad)` is called. At this point the controller should call its own `skipAd()` method.

#### Resetting a Source

Before a new source is loaded into the player, or before the player is destroyed, `resetSource()` is triggered. This allows the integration to clean up any source-specific resources, such as scheduled ads or pending HTTP requests.

#### Destroying the player

When the player is destroyed, the `destroy()` is called. This allows the integration to clean up any resources, such as UI views or event listeners.

#### Creating Ad objects

When the advertisement provider reports an ad, an `AdBreak` and an `Ad` object should be created using `createAdBreak(props: AdBreakInit)` and `createAd(props: AdInit, adBreak: AdBreak?)` methods respectively from the controller. For example, for a preroll `AdBreak` containing 2 advertisements it would be:

```kotlin
val adBreak = controller.createAdBreak(AdBreakInit(timeOffset = 0))

val firstAdInit = AdInit(
    type = "linear",
    skipOffset = 5,
    id = "first_ad_id",
    duration = 10,
    clickThrough = first_ad_click_through_url,
    resourceURI = first_ad_resource_url
)
val firstAd = controller.createAd(firstAdInit, adBreak)

val secondAdInit = AdInit(
    type = "linear",
    skipOffset = 5,
    id = "second_ad_id",
    duration = 10,
    clickThrough = second_ad_click_through_url,
    resourceURI = second_ad_resource_url
)
val secondAd = controller.createAd(secondAdInit, adBreak)
```

#### Playing an Ad

When an Ad begins the playback, the controller must inform the player by calling `beginAd(ad: Ad)`, this will trigger the relevant AdBreak and Ad events.

Additionally, during the playback of the Ad, calling `updateAdProgress(ad: Ad, progress: Double)` is needed to keep the player in sync with the progress.

Finally, when the playback of the Ad is completed, `endAd(ad: Ad)` should be called to notify about it.

### CustomSsaiDescriptionSerializer

To hold the configuration parameters specific to your integration, you can create a new class that inherits from `CustomSsaiDescription`. This allows it to be set on a `TypedSource` through [`TypedSource.Builder.ssai()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/source/TypedSource.Builder#ssai\(com.theoplayer.android.api.source.ssai.SsaiDescription\)). Then, register a `CustomSsaiDescriptionSerializer` using the integration ID and provide a way to serialize/deserialize the new `CustomSsaiDescription`.

Below is an example of a [YoSpace integration](https://github.com/THEOplayer/android-connector/tree/master/connectors/yospace) showing `YospaceSsaiDescription` extending `CustomSsaiDescription`:

```kotlin
data class YospaceSsaiDescription constructor(
    /**
     * The type of the requested stream.
     *
     * Default: [YospaceStreamType.LIVE]
     */
    val streamType: YospaceStreamType = YospaceStreamType.LIVE,
    /**
     * Custom properties to set when initializing the Yospace session.
     */
    val sessionProperties: Session.SessionProperties = Session.SessionProperties()
) : CustomSsaiDescription() {
    override val customIntegration = YospaceConnector.INTEGRATION_ID
}
```

And then, the implementation of the `CustomSsaiDescriptionSerializer` specific for YoSpace:

```kotlin
class YospaceSsaiDescriptionSerializer : CustomSsaiDescriptionSerializer {
    override fun fromJson(json: String): YospaceSsaiDescription {
        return Json.decodeFromString(json)
    }

    override fun toJson(value: CustomSsaiDescription): String {
        return Json.encodeToString(value)
    }
}
```

Finally, registering the `YospaceSsaiDescriptionSerializer`:

```kotlin
CustomSsaiDescriptionRegistry.register(YospaceConnector.INTEGRATION_ID, YospaceSsaiDescriptionSerializer())
```

> **Note**
>
> Registering the `CustomSsaiDescriptionSerializer` should happen before registering the `ServerSideAdIntegrationFactory`.

---

# Introduction

*Fast forward to [Integrations with commercial analytics services](#integrations-with-commercial-analytics-services) if you want to know more about our integrations with services like Conviva, Mux and Youbora.*

Video analytics offer all sorts of insights, ranging from the behavior of your viewers, to the performance of your video players.

There are different approaches to collect these insights.

* You can use a commercial video analytics vendor (e.g. Conviva, Mux, Wicket Labs, Youbora, ...).
* You can implement a custom analytics service that you created.
* You can leverage back-end and CDN logs.

Insights are deducted from metrics. Metrics are calculated from raw video data. For example,

1. INSIGHT: "the videos on my website start faster than the industry average (e.g. 4.71s)"
2. METRIC: "because the average video startup time was 1.7s on my website last month"
3. DATA: "that I calculated by measuring the video startup time of 1 million unique video sessions on my website"

The online video streaming industry often talks about Quality of Service (QoS) and Quality of Experience (QoE). When talking about metrics, you'll often hear terms like Startup Time, Buffer Rate, Error Rate, Seek Time, Exit Before Video Start. When talking about raw data, you might hear terms like heartbeat (or ping) events, buffer events, play events, seek events and error events.

## Analytics and video players

As an application developer, you want your video player to expose an API that allows you to track video events and query video states. With this API, a developer can implement an integration with a commercial analytics service, or implement a connection with their custom analytics service.

With a video player, you want to be able to access the raw video data. A video player typically doesn't calculate metrics or insights, because it doesn't have access to historical data.

As an app developer,

1. you want to track raw video data with the assistance of your video player API,
2. do some (optional) processing at runtime,
3. and forward the (processed) data to a remote analytics service.

Then, someone on the back-end, 4. would manage & manipulate this data on this remote analytics service, 5. to convert this raw data into metrics, and the metrics into insights.

## Integrations

THEOplayer *should* be compatible with any industry-standard commercial or custom analytics service. The THEOplayer API gives application developers access to a vast number of video events.

As an app developer, you have the option to leverage one of our existing integrations with commercial analytics services, or the option to create a custom integration.

### Integrations with commercial analytics services

The following commercial video analytics integrations are documented. These articles explain how to leverage an out-of-the-box integration, or how to implement a connector, or how to achieve a custom implementation with a specific vendor.

* [Moat](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/moat.md)
* [Mux](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/mux.md)
* [Youbora](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/youbora.md)
* [Agama](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/agama.md)
* [Conviva](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/conviva/introduction.md)
* [Adobe Analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/adobe-analytics.md)
* [MediaMelon SmartSight](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/mediamelon-smartsight.md)
* [Wicket Labs](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/wicket-labs.md)
* [Google Analytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/custom-analytics-integration.md#integrating-google-analytics)
* [Tealium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/tealium.md)
* [Segment](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/segment.md)

A connector is an open-source integration that is listed on our GitHub at <https://github.com/THEOplayer>. There might be connectors on our GitHub that are missing from the list above.

Alternatively, if you are not able to locate documentation on a specific vendor, then reach out to this vendor, because they might be the maintainer of an integration related to THEOplayer.

### Creating a custom analytics integration

Head over to [Custom Analytics Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/custom-analytics-integration.md) if you want to learn more about creating your own analytics integration using the THEOplayer API.

## THEOplayer Analytics Dashboard

If you've used the THEOplayer Developer Portal - for example to create a THEOplayer SDK -, then you might have noticed that there is an analytics dashboard at <https://portal.theoplayer.com>.

This analytics dashboard is located in the "Usage" tab of your Portal account. The dashboard should resemble the screenshot below.

![THEOplayer Portal Analytics Dashboard](/pr-932/assets/images/analytics-introduction-portal-dashboard-777c17a7b2bbf13b27a40bfdc3a4d1f9.png "THEOplayer Portal Analytics Dashboard")

This dashboard allows you to track your [impressions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-is-an-impression.md) across different periods of times across different SDKs.

We don't *really* consider this dashboard as a "video analytics service". The primary purpose of this dashboard is for you to monitor your impressions, as the impressions might be related to your THEOplayer pricing model. That being said, it is a useful dashboard, as it visualizes the consumption of your videos throughout time.

---

# Moat

Moat is an analytics service maintained by Oracle. THEOplayer offers a pre-integration for this solution. A demo can be found at <https://demo.theoplayer.com/moat-analytics-pre-integration>.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | No       | Yes            | Unverified     |

## Code example

### Prerequisites

##### Android (TV) SDK

The THEOplayer Android SDK supports Moat analytics (version 2.4.3+) out-of-the-box. Below you can find the steps to enable Moat tracking.

1. Include the Moat native Android SDK in the gradle file:

```java
repositories {
    flatDir {
    dirs 'libs'
    }
}

dependencies {
    compile (name: 'moat-mobile-app-kit', ext:'aar')
}
```

2. (Optional for Moat 2.4.2+) Ensure Google Play Ads dependencies are included. If this is omitted, this functionality will be limited.

```java
dependencies {
    compile 'com.google.android.gms:play-services-ads:+'
    compile 'com.android.support:support-v4:+'
}
```

3. Set your application for THEOplayer when the Application is created:

```java
import android.app.Application;
import com.moat.analytics.mobile.moatnamespace.MoatAnalytics;

public class MyApplication extends Application {
    @Overridepublic void onCreate() {
    super.onCreate();
    THEOplayerGlobal.getSharedInstance(this).setApplicationInstance(this);
    }
}
```

##### iOS (/tvOS) SDK

THEOplayer supports Moat Analytics integration from Moat SDK version 3.6.0+. This integration is only available upon request.

Once you've received a build which has THEOplayer's Moat integration, you have to import the Moat framework:

```swift
import DMSMoatMobileAppKit
```

### Configuration

The snippets below explain how you can pass on Moat settings to a THEOplayer configuration object.

##### Web SDK

Configure the Moat partner code.

```js
new THEOplayer.Player(containerElement, {
  libraryLocation: 'https://cdn.theoplayer.com/dash/theoplayer/',
  analytics: [
    {
      integration: 'moat',
      partnerCode: '<PARTNER_CODE>',
    },
  ],
});
```

When you want to make use of Moat for tracking advertisements, you should make use of the [`IMAAdDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/IMAAdDescription).

##### Android (TV) SDK

Configure the Moat **partner code** and **namespace** and enable Google IMA

```java
new THEOplayerConfig.Builder()
    .googleIma(true)
    .analytics(new MoatOptions.Builder("NAMESPACE", "<PARTNER_CODE>").loggingEnabled(true).build())
    .build();
```

When you want to make use of Moat for tracking advertisements, you should make use of the [GoogleImaAdDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/source/addescription/GoogleImaAdDescription).

##### iOS (/tvOS) SDK

Enable Google IMA in your THEOplayer instance:

```swift
let config = THEOplayerConfiguration(defaultCSS: true, googleIMA: true)
let theoplayer = THEOplayer(configuration: config)
```

Configure a Google IMA source with Moat Analytics enabled:

```swift
public static var moatPreroll : SourceDescription {
    let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl")
    return SourceDescription(
        source : typedSource,
        ads: [
            GoogleImaAdDescription(src: "<AD_TAG_URL>")],
        analytics: [MoatOptions(partnerCode: "<PARTNER_CODE>", debugLoggingEnabled: true)]
    )
}
```

## Related links:

* Demo page: <https://demo.theoplayer.com/moat-analytics-pre-integration>
* [Analytics API (Web SDK)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Analytics)
* [Analytics API (Android SDK)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/source/analytics/package-summary)
* [Analytics API (iOS SDK)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Analytics#/c:@M@THEOplayerSDK@objc\(pl\)THEOplayerAnalyticsDescription)

---

# Mux

[Mux /data](https://mux.com/data/) is a video analytics service. Mux is currently the maintainer of the Mux-THEOplayer pre-integration.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK   | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | ---------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Unverified | Unverified     | Unverified     |

## Connecting Mux to THEOplayer

Mux is currently the maintainer of the Mux-THEOplayer pre-integrations. Their documentation is located at the following pages for the respective SDKs:

* **Web SDK**: <https://docs.mux.com/guides/data/monitor-theoplayer-web>

* **Android (TV) SDK**: <https://docs.mux.com/guides/data/monitor-theoplayer-android>

* **iOS (/tvOS) SDK**: <https://docs.mux.com/guides/data/monitor-theoplayer-ios>

If you choose to [build a custom integration](https://docs.mux.com/guides/data/build-a-custom-integration), the following articles from Mux describe how you can achieve this:

* JavaScript: <https://docs.mux.com/guides/data/custom-javascript-integration>
* Java: <https://docs.mux.com/guides/data/custom-java-integration>
* Objective-C: <https://docs.mux.com/guides/data/custom-objectivec-integration>

---

# Youbora (NPAW Plugin)

This article is a good place to start if you are looking for information on how to configure THEOplayer with Youbora.

Youbora adapter (NPAW plugin) for THEOplayer is maintained by the NPAW team and regularly kept up to date to make sure it is compatible with the latest THEOplayer version.

In order to access the links on this guide, you may need to login with your NPAW developer account.

Before you get started, for general information on NPAW plugin, please refer to [this guide](https://documentation.npaw.com/integration-docs/docs/first-steps).

##### Web SDK

For general information on NPAW plugin for Web and how to set it up, please refer to [this guide](https://documentation.npaw.com/integration-docs/docs/js-integration-guide).

For integration with THEOplayer Web SDK, please refer to their integration guide [here](https://documentation.npaw.com/integration-docs/docs/theoplayer-js).

##### Android (TV) SDK

For general information on NPAW plugin for Android (TV) and how to set it up, please refer to [this guide](https://documentation.npaw.com/integration-docs/docs/android-integration-guide).

For integration with THEOplayer Android SDK, please reach out to the NPAW team to get the latest resources.

##### iOS/tvOS SDK

For general information on NPAW plugin for iOS/tvOS and how to set it up, please refer to [this guide](https://documentation.npaw.com/integration-docs/docs/ios-integration-guide).

For integration with THEOplayer iOS/tvOS SDK, please reach out to the NPAW team to get the latest resources.

## Related articles

* [Customize UI during ad playback](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/customize-ui-during-playback.md)

* [Why does fullscreen not behave as expected on iOS browsers?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-does-fullscreen-not-behave-as-expected-on-ios.md)

* [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-set-up-vast-and-vmap.md)

---

# Agama

Agama is an analytics solution maintained by [Agama Technologies](https://www.agama.tv/). THEOplayer offers a pre-integration for this service.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | No          | No      | No       | No             | Unverified     |

## Prerequisites

##### Web SDK

Agama requires you to load the Agama library and configure it through JavaScript. Agama needs to be configured through the PlayerConfiguration and through the SourceConfiguration. The following section describes how this can be done.

##### Android (TV) SDK

Agama requires you to have the `agama` feature enabled in your SDK build. Agama needs to be configured through the PlayerConfiguration and through the SourceConfiguration. The following section describes how this can be done. If you do not have this feature enabled in your SDK, or are unsure, please contact your CSM or Service Desk for confirmation.

##### iOS (/tvOS) SDK

Agama requires you to have the `agama` feature enabled in your SDK build. Agama needs to be configured through the PlayerConfiguration and through the SourceConfiguration. The following section describes how this can be done. If you do not have this feature enabled in your SDK, or are unsure, please contact your CSM or Service Desk for confirmation.

## Documentation

##### Web SDK

The player configuration should include the [AgamaPlayerConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AgamaPlayerConfiguration) object.

```js
var player = new THEOplayer.Player(element, {
  libraryLocation: '/path/to/your-theoplayer-folder/',
  analytics: [
    {
      integration: 'agama',
      config: 'emp_service=http://127.0.0.1:8191/report;report_interval=60;id_report_interval=240;operator_id=fooSoo',
    },
  ],
});
```

Once a player is configured, an Agama EMP client instance is created.

The player's source configuration should include the [AgamaSourceConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AgamaSourceConfiguration) object.

```js
player.source = {
    [...]
    analytics : [{
        integration : 'agama',
        asset : 'Asset Name',
        streamType : 'vod'
    }]
};
```

Once the player's source is set, a dynamic streaming session is started, and Agama EMP is ready to monitor the usage and quality of the video.

##### Android (TV) SDK

The player configuration should include the [AgamaPlayerConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AgamaPlayerConfiguration) object:

```java
public THEOplayerConfig theoplayerConfig = new THEOplayerConfig.Builder()
    ...
    .analytics(
        agamaPlayerConfiguration("//config")
        .application("//applicationName")
        .applicationVersion("//applicationVersion")
        .userAccountID("//userAccountID")
        .logLevel(//AgamaLogLevel)
        .build()
    )
    .castStrategy(CastStrategy.AUTO)
    .hlsDateRange(true);
}
public THEOplayerView tpv = new THEOplayerView(this, theoplayerConfig)
```

Once the player is configured, an Agama EMP client is created. The player source configuration should include the [AgamaSourceConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AgamaSourceConfiguration) object in the analytics tag while configuring the [SourceDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SourceDescription):

```java
public SourceDescription sourceDescription =
    sourceDescription(
            ...
    ).analytics(
        agamaSourceConfiguration(asset: //agama asset name, streamType: //StreamType (.LIVE or .VOD))
            .cdn("Agama CDN")
            .contentDescription("//Your content description")
            .contentTitle("//Your content title")
            .contentType("//Your content type")
            .serviceName(//AgamaServiceName.)
    ).build())
tpv.getPlayer().setSource(sourceDescription)
```

Once the player's source is set, a dynamic streaming session is started, and Agama EMP is ready to monitor the usage and quality of the video.

Example Setup:

```java
public THEOplayerConfig theoplayerConfig = THEOplayerConfig.Builder()
                .chromeless(false)
                .cssPaths("/data/data/com.theoplayer.demo/appDataCss.css",
                        "style.css")
                .jsPaths("script.js")
                .googleIma(true)
                .ads(ads)
                .analytics(
                    agamaPlayerConfiguration("agg_server_ip=test-1.agamatech.se;agg_server_port=8050;report_interval=60;id_report_interval=240;operator_id=fooSoo;")
                    .application("THEO application demo")
                    .applicationVersion("1.0.0")
                    .userAcountID("THEO user demo")
                    .logLevel(AgamaLogLevel.FATAL)
                    .build()
                )
                .castStrategy(CastStrategy.AUTO)
                .hlsDateRange(true);

THEOplayerView tpv = new THEOplayerView(this, theoplayerConfig);

public SourceDescription agamaSourceDescription =
    sourceDescription(
                typedSource("http://contentserver-1.kanto.indigo:8080/videos/dash/big_buck_bunny/BigBuckBunny_10s_simple_2014_05_09.mpd")
                    .setExperimentalRenderingEnabled(experimental)
                    .build()
            ).analytics(
                agamaSourceConfiguration("agama", StreamType.VOD)
                    .cdn("THEO cdn demo")
                    .contentDescription("THEO content description demo")
                    .contentTitle("THEO title demo")
                    .contentType("THEO content type demo")
                    .serviceName(AgamaServiceName.SVOD)
                    .build());

tpv.getPlayer().setSource(agamaSourceDescription);
```

##### iOS (/tvOS) SDK

The player configuration should include the [AgamaPlayerConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AgamaPlayerConfiguration) object:

```swift
let agamaPlayerConfiguration = AgamaPlayerConfiguration(
    config: //String,
    logLevel: //THEOplayerSDK.AgamaLogging,
    application: //String?, automatically detected from host if nil is provided,
    applicationVersion: //String?, automatically detected from host if nil is provided,
    userAccountID: //String?
)
var theoplayer = THEOplayer(configuration: THEOplayerConfiguration(..., analytics: [agamaPlayerConfiguration]))
...
```

Once the player is configured, an Agama EMP client is created. The player source configuration should include the [AgamaSourceConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AgamaSourceConfiguration) object in the analytics tag:

```swift
let agamaSourceConfiguration = AgamaSourceConfiguration(
    asset: //String,
    streamType: //StreamType, either live or vod,
    serviceName: //AgamaServiceName, name of the service,
    cdn: //String?,
    contentTitle: //String?,
    contentType: //String?,
    contentDescription: //String?
)
theoplayer.source = SourceDescription(..., analytics: [agamaSourceConfiguration], ...)
```

Once the player's source is set, a dynamic streaming session is started, and Agama EMP is ready to monitor the usage and quality of the video.

Example Setup:

```swift
let agamaPlayerConfiguration = AgamaPlayerConfiguration(
    config: "emp_service=http://127.0.0.1:8191/report;report_interval=60;id_report_interval=240;operator_id=fooSoo",
    logLevel: .fatal,
)
var theoplayer = THEOplayer(configuration: THEOplayerConfiguration(chromeless: false, analytics: [agamaPlayerConfiguration]))
...
let agamaSourceConfiguration = AgamaSourceConfiguration(
    asset: //String,
    streamType: StreamType.live,
    serviceName: AgamaServiceName.live
)
theoplayer.source = SourceDescription(
    sources: TypedSource(src: "elephantsdream", type: "application/xmpegurl"),
    analytics: [agamaSourceConfiguration]
)
```

## Related resources

* [Custom Analytics Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/custom-analytics-integration.md)

---

# Introduction

Conviva is an analytics service. THEOplayer offers a connector which can be initialized depending upon the customer requirements for measuring all the solutions offered by Conviva (Video Analytics & Ads Analytics).

Please check out our guide on how to integrate the [Conviva Connector for VideoAnalytics & AdsAnalytics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/conviva/conviva-connector.md).

## Things to remember:

* The Conviva connector has full support for Video and Ad Analytics offered by Conviva.

* This connector can be maintained and managed by across teams as it is built using all public APIs of THEOplayer and Conviva. Any new updates or changes can be easily modified and customized as per customer requirements. (There is no dependency on the THEOplayer or Conviva library version)

* More Information about [Conviva Video Experience](https://www.conviva.com/experience-insights/)

* More Information about [Conviva Ad Insights](https://www.conviva.com/ad-insights/)

---

# Conviva Connector for VideoAnalytics & AdsAnalytics

This article describes on how to integrate Conviva for Video Analytics and Ads Analytics offered as a connector with THEOplayer SDK.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK   | Android TV SDK | Chromecast SDK | Tizen | webOS |
| ------- | ----------- | ------- | ---------- | -------------- | -------------- | ----- | ----- |
| Yes     | Yes         | Yes     | Unverified | Unverified     | Unverified     | Yes   | Yes   |

## Web SDK

### Prerequisites

1. A THEOplayer build with a valid license is required. You can

   * either install the [THEOplayer SDK through NPM](https://www.npmjs.com/package/theoplayer),
   * or generate your custom THEOplayer SDK through the [THEOportal](https://portal.theoplayer.com/login) (this includes also a license).

2. Follow the [Getting started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md) guide to include your player on a simple HTML page.

3. For setting up a valid Conviva session, you must have access to a Conviva developer account with access to a debug or production key.

### Installation

Install using your favorite package manager for Node (such as npm or yarn):

**Install via npm**

`npm install @theoplayer/conviva-connector-web`

**Install via yarn**

`yarn add @theoplayer/conviva-connector-web`

### Usage

#### Step 1

Define the Conviva metadata and configuration:

```javascript
const convivaMetadata = {
  ['Conviva.assetName']: 'ASSET_NAME_GOES_HERE',
  ['Conviva.streamUrl']: 'CUSTOMER_STREAM_URL_GOES_HERE',
  ['Conviva.streamType']: 'STREAM_TYPE_GOES_HERE', // VOD or LIVE
  ['Conviva.applicationName']: 'APPLICATION_NAME_GOES_HERE',
  ['Conviva.viewerId']: 'VIEWER_ID_GOES_HERE',
};

const convivaConfig = {
  debug: false,
  gatewayUrl: 'CUSTOMER_GATEWAY_GOES_HERE',
  customerKey: 'CUSTOMER_KEY_GOES_HERE', // Can be a test or production key.
};
```

#### Step 2

Using these configs you can create the Conviva connector with THEOplayer. Alternatives:

* Add as a regular script:

```javascript
<script type="text/javascript" src="path/to/conviva-connector.umd.js"></script>
<script type="text/javascript">
  const player = new THEOplayer.Player(element, configuration);
  const convivaIntegration = new THEOplayerConvivaConnector.ConvivaConnector(
    player,
    convivaMetadata,
    convivaConfig
  );
</script>
```

* Add as an ES2015 module:

```javascript
<script type="module">
  import {ConvivaConnector} from "path/to/conviva-connector.esm.js"; const player = new THEOplayer.Player(element, configuration); const
  convivaIntegration = new ConvivaConnector( player, convivaMetadata, convivaConfig );
</script>
```

The Conviva connector is now ready to start a session once THEOplayer starts playing a source.

#### Notes

* You can download the latest Conviva library from [Conviva Developer Community](https://community.conviva.com/site/global/home/p_home.gsp).
* You can use any version of Conviva library supporting Video and Ads Analytics.
* The THEOplayer instance (variable `player`) needs to be initialized before Conviva connector.
* `convivaConfig` contains the details of the Conviva configuration and `convivaMetadata` is used to add manually metadata associated to that content.
* The Conviva connector has full support for Video and Ad Analytics offered by Conviva. This connector can be maintained and managed by across teams as it is built using all public APIs of THEOplayer and Conviva. Any new updates or changes can be easily modified and customized as per customer requirements. (There is no dependency on the THEOplayer or Conviva library version)

### Usage with Yospace connector

If you have a Yospace SSAI stream and want to also report ad related events to Conviva, you can use this connector in combination with the Yospace connector: [@theoplayer/yospace-connector-web](https://www.npmjs.com/package/@theoplayer/yospace-connector-web)

After configuring the Yospace connector, you can link it to the Conviva connector:

```javascript
async function setupYospaceConnector(player) {
  const source = {
    sources: [
      {
        src: 'https://csm-e-sdk-validation.bln1.yospace.com/csm/extlive/yospace02,hlssample42.m3u8?yo.br=true&yo.av=4',
        ssai: {
          integration: 'yospace',
        },
      },
    ],
  };

  // Create the connectors.
  const yospace = new THEOplayerYospaceConnector.YospaceConnector(player);
  const conviva = new THEOplayerConvivaConnector.ConvivaConnector(player, convivaMetadata, convivaConfig);

  // Link ConvivaConnector with the YospaceConnector.
  conviva.connect(yospace);

  // Set the source.
  await yospace.setupYospaceSession(source);
}
```

## Android SDK

### Prerequisites

1. The THEOplayer Android SDK Conviva Connector requires the application to import the THEOplayer Android SDK since the connector relies on its public APIs. For more details, check out our [Getting started on Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/getting-started.md) guide.
2. For setting up a valid Conviva session, you must have access to a Conviva developer account with access to a debug or production key.

### Installation

After setting up the THEOplayer Android SDK, in your module level `build.gradle` file add the THEOplayer Android SDK Conviva Connector and the Conviva SDK:

```groovy
implementation 'com.theoplayer.android-connector:conviva:+'
implementation 'com.conviva.sdk:conviva-core-sdk:4.0.33'
```

### Usage

#### Setting up the Conviva Connector

```kotlin
val theoplayerView: THEOplayerView

private fun setupConviva() {
    val customerKey = "your_conviva_customer_key"
    val gatewayUrl = "your_conviva_debug_gateway_url"

    val metadata = hashMapOf(
        "Conviva.applicationName" to "THEOplayer",
        "Conviva.viewerId" to "viewerId"
    )
    val config = ConvivaConfiguration(
        customerKey,
        true, // debug
        gatewayUrl,
    )
    convivaConnector = ConvivaConnector(applicationContext, theoplayerView.player, metadata, config)
}
```

#### Setting asset name

Most media related properties, such as its `streamURL`, `duration` or whether it is a `live` or `vod` stream, are determined and passed by the connector itself when setting a new source.

Whenever a new source is set on the player, the metadata title property is used to pass an asset name.

```kotlin
theoplayerView.player.source = SourceDescription.Builder(
        TypedSource.Builder("https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8").build()
    )
    .metadata(MetadataDescription(mapOf("title" to "Big Buck Bunny")))
    .build()
```

Alternatively, the asset name can be passed to the connector at any time along with additional metadata through an open key-value map, for example:

```kotlin
theoplayerView.player.source = sourceDescription
convivaConnector?.setContentInfo(hashMapOf(
    "Conviva.assetName" to "Big Buck Bunny",
    "customTag1" to "customValue1",
    "customTag2" to "customValue2"
))
```

#### Starting a new session on program boundaries

By default, new sessions are only started on play-out of a new source, or when an ad break starts. During a live stream it is possible to manually mark the start of a new session, for example when a new program starts.

```kotlin
convivaConnector?.stopAndStartNewSession(hashMapOf(
    "Conviva.assetName" to "New program",
    "customTag1" to "customValue1",
    "customTag2" to "customValue2"
))
```

#### Destroying / Cleaning up

To release listeners and resources, call `destroy` whenever the Conviva Connector is no longer needed.

```kotlin
convivaConnector?.destroy()
```

After destroying a Conviva Connector instance, it can no longer be used. If needed, a new instance should be created.

## iOS/tvOS SDK

### Installation

#### [Swift Package Manager](https://swift.org/package-manager/)

1. In Xcode, install the Conviva libraries by navigating to **File > Add Packages**
2. In the prompt that appears, select the iOS-Connector GitHub repository: `https://github.com/THEOplayer/iOS-Connector`
3. Select the version you want to use.
4. Choose the Connector libraries you want to include in your app.

#### [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started)

1. Create a Podfile if you don't already have one. From the root of your project directory, run the following command: `pod init`
2. To your Podfile, add the Conviva connector pods that you want to use in your app: `pod 'THEOplayer-Connector-Conviva'`
3. Install the pods using `pod install`, then open your `.xcworkspace` file to see the project in Xcode.

### Usage

Import the `THEOplayerConnectorConviva` module:

```swift
import THEOplayerConnectorConviva
```

Create a `ConvivaConfiguration` that contains the info on how to connect to your conviva endpoint:

```swift
let configuration = ConvivaConfiguration(
    customerKey: "put your customer key here",
    gatewayURL: " put your  gateway URL here ",
    logLevel: .LOGLEVEL_FUNC
)
```

Create a `ConvivaConnector` that uses this `configuration` and your `THEOplayer` instance:

```swift
let connector = ConvivaConnector(
    configuration: configuration,
    player: yourTHEOplayer
)
```

For each asset you play, the **asset name** needs to be reported to Conviva which you can do by providing the asset name as a `title` field inside your `SourceDescription's metadata`:

```swift
let mySource = SourceDescription(source: source, metadata: MetadataDescription(metadataKeys: ["title": "your_asset_name"]))
```

Alternatively, the asset name can be provided as contentInfo (`CIS_SSDK_METADATA_ASSET_NAME`) using the `setContentInfo` method, along with other metadata. For example to report the viewer's ID:

```swift
let contentInfo = [
   CIS_SSDK_METADATA_VIEWER_ID: "your_viewer_id"
]
connector.setContentInfo(contentInfo)
```

**Important note**: setting a new source on the player will reset previously set `contentInfo`. Make sure to use the `setContentInfo` method after receiving the `SOURCE_CHANGE` event.

### Lifecycle

Hold a reference to your connector. Once the connector is released from memory it will clean up itself and stop reporting to Conviva.

## Related links:

* Demo page: [Conviva Analytics Test Page](https://cdn.theoplayer.com/conviva/conviva_test.html)
* [Web SDK connector on GitHub](https://github.com/THEOplayer/sample-conviva-analytics-html5-sdk)
* [Android SDK connector on GitHub](https://github.com/THEOplayer/android-connector/tree/master/connectors/analytics/conviva)
* [iOS SDK connector on GitHub](https://github.com/THEOplayer/iOS-Connector/tree/main/Code/Conviva)
* [Conviva SDK Documentation](https://cdn.theoplayer.com/conviva/Conviva_Documentation_4.0.14/index.html)
* More Information about [Conviva Video Experience](https://www.conviva.com/experience-insights/)
* More Information about [Conviva Ad Insights](https://www.conviva.com/ad-insights/)

---

# Custom Analytics Integration

As mentioned in our [Introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/introduction.md), video analytics provide tremendous insights into your user's QoE, bring extra business intelligence and enhance decision-making. There are a wide selection of analytics systems in the current landscape (e.g. Google Analytics, Conviva, ...), often with their own focus, expertise and value.

What most video analytics systems have in common is that their insights (partly) originate from video events:

* `play` event: a user clicks the play button, or resumes playback after a pause
* `fullscreen` event: a user goes fullscreen on their device
* `quality` change event: the video quality switches from a lower resolution to a higher one
* `waiting` event: the video is stalled and unable to continue playback for some time
* ...

To access these video events, and forward them to a video analytics system, an application developer must hook into the video player API.

This guide explains the role of the THEOplayer API. Additionally, it explains how to do a custom integration with an analytics system, with Google Analytics as a sample case. This guide should be useful when THEOplayer doesn't have an existing sample integration with a specific (commercial) video analytics service, or when you want to fully control the data flow.

Keep in mind that GA is not the only analytics system out there. The APIs and concepts that we'll discuss are relevant for all analytics systems. For example, you can easily swap out the Google Analytics example with something like [Nielsen](http://www.nielsen.com/eu/en/solutions/capabilities/media-analytics.html) or [Youbora](https://nicepeopleatwork.com/youbora/) (Nice People At Work), or even your own custom analytics back-end.

## Prerequisites

There are two prerequisites in order to continue with this guide:

1. You have a THEOplayer license. You can grab a license at <https://portal.theoplayer.com>.

2. You have some [basic knowledge](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md) on how to use THEOplayer, and can navigate comfortable through [the API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web) to find [relevant events](http://demo.theoplayer.com/using-events-examples).

Refer to our [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md) before advancing to the code samples.

## API

You can access the video data through the THEOplayer API. Through the API, you can subscribe to events, and attach a callback. For example, when the `ended` event is triggered (meaning: someone completely watched the video), your callback could be that when this happens, you do a request to a remote video analytics service.

Events are organized across interfaces and subinterfaces, as illustrated by the image below. For example, the [`Player`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap) contains general video player events like `play`, `pause` and `ended`. The [`Ads`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap) interface contains events related to advertisements, like `adbreakbegin` and `adend`.

![THEOplayer API Interfaces and Events](/pr-932/assets/images/analytics-events-185d6ab52b556af08d8300b545ae5876.png "THEOplayer API Interfaces and Events")

When creating a custom analytics implementation, you must familiarize yourself with the relevant interfaces and events. Luckily, all information is available at <https://docs.theoplayer.com/>, and the names of interfaces and events are very similar across all the THEOplayer SDKs.

Below is an (incomplete) list of some common interface event maps.

* Player is the interface the represents the video player instance. You use this interface to detect general video events, like a play, a pause, and so on.

  * [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap)
  * [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/PlayerEventTypes)
  * [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/player/PlayerEventTypes)

* Ads is the interface that represents the advertisements. You use this interface to detect when an ad starts and stops.

  * [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap)
  * [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Ads%20Events)
  * [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/ads/AdsEventTypes)

* AudioTrackList is the interface that represents the list of audio tracks. You use this interface to detect when a new audio track is added, or when another audio track becomes active.

  * [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackListEventMap)
  * [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/AudioTrackListEventTypes)
  * [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/mediatrack/audio/list/AudioTrackListEventTypes)

* VideoTrack is the interface that represents a single video track containing one or more video qualities. You use this interface to detect when another video quality becomes active.

  * [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrackEventMap)
  * iOS: unavailable due to Apple limitations
  * [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/mediatrack/video/VideoTrackEventTypes)

* TextTrackList is comparable AudioTrackList, but for subtitles, closed captions and metadata (e.g. id3, emsg, EventStream, EXT-X-DATERANGE).

  * [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackListEventMap)
  * [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/TextTrackListEventTypes)
  * [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/texttrack/list/TextTrackListEventTypes)

* Cast is the interface that is used to detect events related to Chromecast and AirPlay.

  * [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VendorCastEventMap)
  * iOS: [AirPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/AirPlayEventTypes) & [Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/ChromecastEventTypes)
  * [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/chromecast/package-summary)

* Network is the interface that is used to intercept HTTP(S) requests and responses. You should only use this API on the THEOplayer Web SDK, and only when you can't use [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers) to accomplish the same.
  * [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/network/introduction.md)

Note that maintaining the above list manually is unfortunately a no-go because our interfaces evolve. This means that you should research your events through our automatically managed API references at <https://docs.theoplayer.com/>. For example, interfaces like VR, TextTrackCueList, VideoTrackList, Uplynk and Yospace are omitted because manually maintaining this would be too challenging.

When doing a custom analytics integration, you should also check our [Metrics](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Metrics) API, and our articles on [error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/error/introduction.md).

### Video analytics metrics and events

Let's discuss some popular metrics, and how you could track it with a video player events.

Plays (or Impressions). This metric represents the amount of plays. You can calculate this event by identifying the first [`playing`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#playing) event after every [`sourcechange`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#sourcechange) event.

Video Startup Time (or Time-to-First-Frame or Join Latency). This metric represents the time it takes your video to start. You can calculate this event by calculating the difference between the timestamps of the first [`playing`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#playing) and the first [`play`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#play) event after every [`sourcechange`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#sourcechange) event.

Seek Time (or Seek Latency). This metric represents the time it takes for your video to resume when you scrub to another position. You can calculate this event by calculating the difference between the timestamps of the [`seeking`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#seeking) and the [`seeked`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#seeked) event.

Watch Time. This metric represents how much time is spent watching content by your viewers. You calculate this value by tracking the [`playing`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#playing) event, and halting it when the [`waiting`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#waiting), [`pause`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#pause), [`ended`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#ended) or [`error`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#error) event occurs.

Rebuffer Ratio (or Stalls). This metric represents how often the viewer is watching the "spinner icon" versus the actual video. This metric is closely related to the Watch Time. You can calculate this event by tracking the [`waiting`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#waiting) event, which is triggered when the video starts to stall, and the [`playing`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#playing) event.

Average Bitrate. This metric represents the average video quality that your viewers are watching. You can calculate this metric by tracking the [`activequalitychanged`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrackEventMap#activequalitychanged) event.

Average % Complete (or Watched Ratio). This metric represents the relative completion rate of your videos. This metric is related to the Watch Time, and related in a similar fashion. You could also use the [`duration`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#duration) to determine the length of the asset.

Exit Before Video Start. This metric represents how often your viewers aren't able to start the video, even though they had the intent to watch it. You can calculate this metric by tracking the first [`play`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#play) event, and it never getting to the [`playing`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#playing) event.

Video Playback Failure. This metric represents how often your viewers have a problem with playback once a video starts. You can calculate this metric by tracking the [`error`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#error) event after the first [`playing`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#playing) event.

Note that these proposed calculations are only loosely formulated to help you understand the relationship between video metrics and a video player API.

When talking about metrics, you often apply dimensions or filters to a metric. For example, when talking about the "Plays" metric (see above), the base metric would apply to all logs throughout all time. When analyzing your data, you might want to apply a filter (or dimension), such time (to consider all "Plays" for a specific period of time), asset (to research a specific asset), user (to check a specific user's activity), and so on. It is up to you (or your commercial analytics service) to associate certain dimensions with a raw video player event.

### Session management

It's important to note that THEOplayer doesn't associate a user ID or session ID with an event. (This is pretty normal, because THEOplayer is a client-side video player library. It's not aware of your "back-end" "CMS", "users" or "sessions".)

When you are implementing an analytics service, you usually want to associate a session or user with an event when forwarding the event to your remote analytics database. As an app developer, it is your responsibility to do this association.

## Integrating Google Analytics

This subsection shows you how you could connect the THEOplayer Web SDK with Google Analytics.

### Web SDK

Google Analytics (GA) requires you to [load in the GA library](https://developers.google.com/analytics/devguides/collection/analyticsjs/) and configure it through JavaScript. This script also sets up a default tracker for your tracking ID UA-XXXXX-Y.

```html
<head>
  ... (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new
  Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-XXXXX-Y', 'auto'); ga('send', 'pageview'); ...
</head>
```

Then, you must use the THEOplayer API to "add an event listener". In an event listener, you specify which events you want to track, and what the reaction should be when such an event should be detected.

For example, with Google Analytics, we could subscribe to a list of events, and call the `ga('send')` function from the Google Analytics API to forward this event to your Google Analytics database.

```js
player.addEventListener(['durationchange', 'stalled', 'ended', 'seeking', 'seeked', 'waiting', 'playing', 'pause', 'volumechange'], function (event) {
  ga('send', {
    hitType: 'event',
    eventCategory: 'video',
    eventAction: event.type,
    eventLabel: player.src,
    eventValue: Math.floor(player.currentTime),
  });
});
```

For more advanced integrations, Google Analytics also allows you to [create multiple named trackers](https://developers.google.com/analytics/devguides/collection/analyticsjs/creating-trackers).

Of course, you control the code, so you could send custom "made up" events. A useful example would a `firstplay` event, which would map to the "first play" event for a session.

```js
var firstplay = true;
player.addEventListener('play', function (event) {
  if (firstplay) {
    ga('send', {
      hitType: 'event',
      eventCategory: 'video',
      eventAction: 'firstplay',
      eventLabel: player.src,
      eventValue: Math.floor(player.currentTime),
    });
    firstplay = false;
  }
  ga('send', {
    hitType: 'event',
    eventCategory: 'video',
    eventAction: event.type,
    eventLabel: player.src,
    eventValue: Math.floor(player.currentTime),
  });
});
```

(Keep in mind that you should reset `firstplay` to `true` when you configure another video.)

Another useful "fake" event that you could track is the "video startup time", as discussed at [How to measure time-to-first-frame?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/how-can-we-track-the-first-playing-event.md).

Remember that not every event is accessible through the `Player` interface which is accessible through the `player` property. For example, if you want to notify GA of a video quality change event, you have to subscribe to the correct video track, and leverage the `VideoTrackList` interface and the `VideoTrack` interface.

```js
player.videoTracks.addEventListener('addtrack', function (e0) {
  e0.track.addEventListener('activequalitychanged', function (e1) {
    ga('send', {
      hitType: 'event',
      eventCategory: 'video',
      eventAction: e1.type,
      eventLabel: player.src,
      eventValue: Math.floor(player.currentTime),
    });
  });
});
```

### Android (/TV) SDK & iOS (/tvOS) SDK

Refer to Google Analytics' documentation at <https://developers.google.com/analytics/solutions/mobile> if you’re interested in integrating Google Analytics on an Android or iOS-based platform. Similar to the Web SDK, developers would subscribe to events and properties emitted by THEOplayer and create a custom mapping to the Google Analytics library.

## Conclusion

A custom analytics integration gives you full control over your code, and the data you want to submit to your analytics system. This data is exposed through the THEOplayer API, and allows you to subscribe to events such as the [start of an ad](https://support.theoplayer.com/hc/en-us/articles/115000275789-Ads-API), or a [direction change event in 360/VR](https://support.theoplayer.com/hc/en-us/articles/115003088225-360-Video-and-VR-API) playback.

Extra resources:

1. [THEOplayer API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web)

2. [THEOplayer Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)

---

# Adobe Analytics

[Adobe Streaming Media Collection Add-on](https://experienceleague.adobe.com/en/docs/media-analytics/using/media-overview) is a video analytics service, and is part of [Adobe Experience Cloud](https://business.adobe.com/products/analytics/adobe-analytics.html).

This product was formerly known as "Adobe Heartbeat".

Adobe Streaming Media Collection Add-on or older iterations of this product can be implemented on top of THEOplayer.

Refer to the article on [building a custom analytics integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/custom-analytics-integration.md) for more information on how to build an integration on top of THEOplayer.

## SDKs

As a developer you'll have to [build a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/custom-analytics-integration.md) to support Adobe Analytics through a THEOplayer SDK.

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Custom  | Custom      | Custom  | Custom   | Custom         | Custom         | Custom   |

## Connecting Adobe Analytics to THEOplayer

Adobe Streaming Media Collection Add-on can be integrated on top of THEOplayer.

### Web SDK

You can use the [documentation of the Media Analytics SDK](https://experienceleague.adobe.com/en/docs/media-analytics/using/implementation/analytics-only/media-sdk/web-implementation), and you can [download the Media SDKs](https://experienceleague.adobe.com/en/docs/media-analytics/using/getting-started/download-sdks).

Alternatively, you can use the [RESTful Media Collection API](https://experienceleague.adobe.com/en/docs/media-analytics/using/implementation/analytics-only/streaming-media-apis/mc-api-overview).

### Android SDK

You can use the [Adobe Experience Platform (AEP) Mobile SDKs](https://experienceleague.adobe.com/en/docs/media-analytics/using/implementation/analytics-only/media-sdk/mobile-implementation) for iOS and Android to integrate Adobe Analytics, as the Media Analytics SDK for Android has been [deprecated since 31 August 2021](https://experienceleague.adobe.com/en/docs/media-analytics/using/getting-started/end-of-support/end-of-support-faqs).

The Media API reference is available [here](https://developer.adobe.com/client-sdks/solution/adobe-media-analytics/api-reference/).

Alternatively, you can consider using the [RESTful Media Collection API](https://experienceleague.adobe.com/en/docs/media-analytics/using/implementation/analytics-only/streaming-media-apis/mc-api-overview).

### iOS/tvOS SDK

You can use the [Adobe Experience Platform (AEP) Mobile SDKs](https://experienceleague.adobe.com/en/docs/media-analytics/using/implementation/analytics-only/media-sdk/mobile-implementation) for iOS and Android to integrate Adobe Analytics, as the Media Analytics SDK for iOS has been [deprecated since 31 August 2021](https://experienceleague.adobe.com/en/docs/media-analytics/using/getting-started/end-of-support/end-of-support-faqs).

The Media API reference is available [here](https://developer.adobe.com/client-sdks/solution/adobe-media-analytics/api-reference/).

Alternatively, you can consider using the [RESTful Media Collection API](https://experienceleague.adobe.com/en/docs/media-analytics/using/implementation/analytics-only/streaming-media-apis/mc-api-overview).

### Other platforms

For more information about how to use Adobe Analytics on other platforms, please refer to [Adobe Streaming Media Collection Add-on overview](https://experienceleague.adobe.com/en/docs/media-analytics/using/media-overview).

---

# MediaMelon SmartSight

MediaMelon SmartSight is an analytics service maintained by MediaMelon. The library is maintained by the MediaMelon team.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | No             |

## Prerequisites

1. A valid THEOplayer license.
2. A MediaMelon SDK.
3. A MediaMelon Customer ID (**Note:** If you do not know your Customer ID contact MediaMelon at <support@mediamelon.com>.

## Connecting MediaMelon to THEOplayer

##### Web SDK

For the most up to date information on how to integrate MediaMelon SmartSight with THEOplayer Web SDK, please refer to their integration guide [here](https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/web)

**Step 1: Add THEOplayer and MediaMelon SDK** Include the following scripts in the web page (before `THEOplayer.js` is loaded):

```html
<script type="text/javascript" src="https://PATH_TO_SMARTSIGHT_SDK/mmsmartstreaming_theoplayer.min.js"></script>
<script type="text/javascript" src="THEOplayer.js"></script>
```

**Step 2: Register and Initialize MediaMelon SDK** Note: `<customer_id>` is your MediaMelon-assigned Customer ID. If you do not know your Customer ID, contact MediaMelon at <support@mediamelon.com>.

After the player instance has been created, create a new plugin object, register, report player Info and then initialize the plugin as shown below:

```js
var theoPlayer = new THEOplayer.Player(element, {
  libraryLocation: 'your_library_location',
  license: 'your_license_here',
});

var mmVideoAssetInfo = {
  assetName: 'ASSET_NAME',
  assetId: 'ASSET_ID',
  videoId: 'VIDEO_ID',
  contentType: 'CONTENT_TYPE',
  genre: 'GENRE',
  drmProtection: 'DRM_PROTECTION',
  episodeNumber: 'EPISODE_NUMBER',
  season: 'SEASON',
  seriesTitle: 'SERIES_TITLE',
  videoType: 'VIDEO_TYPE',
  customTags: {
    key1: 'VALUE_STRING1',
    key2: 'VALUE_STRING2',
  },
};

var theoPlugin = new mmTheoJSAdapter();
if (theoPlugin.getRegistrationStatus() === false) {
  theoPlugin.registerMMSmartStreaming('PLAYER_NAME', 'CUSTOMER_ID', 'SUBSCRIBER_ID', 'DOMAIN_NAME', 'SUBSCRIBER_TYPE', 'SUBSCRIBER_TAG');
  theoPlugin.reportPlayerInfo('PLAYER_BRAND', 'PLAYER_MODEL', 'PLAYER_VERSION');
}

theoPlugin.reportAppInfo('APP_NAME', 'APP_VERSION');
theoPlugin.setDeviceInfo('DEVICE_MARKETING_NAME');
theoPlugin.reportVideoQuality('VIDEO_QUALITY');
theoPlugin.reportDeviceId('DEVICE_ID');

var isLive = false; //Set this to true for a live stream or false for a VOD stream
// If isLive is not set here, it will be handled internally by the SDK.
theoPlugin.initialize(theoPlayer, 'STREAM_URL', mmVideoAssetInfo, isLive);

// Call this Error API to report an App Error.
theoPlugin.reportAppError('ERROR_MESSAGE', 'ERROR_CODE');
```

You can find an explanation of the parameters on the snippet above [here](https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/web/theoplayer-web-v2-1#cl-step-4-providing-content-metadata-and-custom-tags).

**Step 3: (Optional) Providing custom metadata and tags**

You can also provide custom metadata and tags as shown below in HTML/JS while setting source information. Please use the `mmVideoAssetInfo` structure to provide this information.

```javascript
player.source = {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
      type: 'application/x-mpegurl',
    },
  ],
  mmVideoAssetInfo: {
    assetName: 'Elephants Dream',
    assetId: 'ASSETID_STRING',
    videoId: 'VIDEOID_STRING',
    customTags: {
      key1: 'VALUE_STRING1',
      key2: 'VALUE_STRING2',
      key3: 'VALUE_STRING3',
    },
  },
};
```

**Step 4: (Optional) Disable Manifest Fetch**

If your workflow restricts the manifest to be accessible from both player and SDK simultaneously, then, you can disable the fetch of manifest via the `disableManifestsFetch` API:

```javascript
var player = new THEOplayer.Player(element, {
  libraryLocation: 'path_to_your_library/',
  license: 'your_license_here',
});

var theoPlugin = new mmTheoJSAdapter();
if (theoPlugin.getRegistrationStatus() === false) {
  theoPlugin.registerMMSmartStreaming('PLAYER_NAME', 'CUSTOMER_ID', 'SUBSCRIBER_ID', 'DOMAIN_NAME', 'SUBSCRIBER_TYPE', 'SUBSCRIBER_TAG');
  theoPlugin.reportPlayerInfo('PLAYER_BRAND', 'PLAYER_MODEL', 'PLAYER_VERSION');
  theoPlugin.disableManifestsFetch(true);
}

theoPlugin.initialize(theoPlayer);
```

If you now host a page with the logic described above implemented correctly, THEOplayer will start sending beacons to your MediaMelon dashboard and you should be seeing data coming in to the MediaMelon dashboard in no time.

##### Android (TV) SDK

For the most up to date information on how to integrate MediaMelon SmartSight with THEOplayer Android (TV) SDK, please refer to their integration guide [here](https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/android) where you can find step by step guidance as well as code examples.

##### iOS/tvOS SDK

For the most up to date information on how to integrate MediaMelon SmartSight with THEOplayer iOS/tvOS SDK, please refer to their integration guide [here for iOS](https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/ios) and [here for tvOS](https://docs.mediamelon.com/mediamelon/smartsight-player-sdk-integration/tvos-sdk), where you can find step by step guidance as well as code examples.

---

# Wicket Labs

[Wicket Labs](https://www.wicketlabs.com/) is an audience insights platform for video, and offers products like the "[Wicket Scoreboard](https://www.wicketlabs.com/wicket-scorecard/)".

To generate these insights, a video player emits playback events to a third-party database service (e.g. Firebase). Wicket Labs provides [guidelines](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/) on how to format these playback events. Wicket Labs then pulls the data from the selected third-party database service, and integrates it into their platform.

THEOplayer and Wicket Labs publish [sample integrations on GitHub](https://github.com/THEOplayer/samples-wicket-labs-html5-sdk) to bootstrap developers.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Custom  | Custom      | Custom  | Custom   | Custom         | Custom         |

## Connecting Wicket Labs with THEOplayer

An integration with Wicket Labs can be integrated on-top of THEOplayer.

1. As a customer of Wicket Labs, you need to verify that Wicket Labs can ingest data from your selected database solution (e.g. Firebase). *(It should be noted that Wicket Labs does not provide its own database service to store playback events. Instead, Wicket Labs plugs into your database service.)*
2. As a customer of Wicket Labs and THEOplayer, you need to emit the playback events ([as defined per Wicket Labs](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/)) to your database service. In other words, you need to hook into certain events emitted by THEOplayer, reformat them, and re-emit them to your database service.

The technologies offered by THEOplayer and Wicket Labs can be combined on all [THEOplayer-supported platforms](https://www.theoplayer.com/).

* To facilitate the implementation of Wicket Labs \[related to THEOplayer], Wicket Labs and THEOplayer collaborate on publicly available code samples. These code samples are published as Git repositories on <https://github.com/THEOplayer>.

* Developers are free to do their custom integration of Wicket Labs and THEOplayer, or may modify the publicly available code samples.

  * Wicket Labs' article on [How to Setup Firebase for OTT Video Services](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/) is a great starting point if you're interested in customizing.
  * THEOplayer's article on [Custom Analytics Integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/custom-analytics-integration.md) may help developers out.

### Web SDK

THEOplayer and Wicket Labs host a GitHub repository at <https://github.com/THEOplayer/samples-wicket-labs-html5-sdk>. This repository provides a sample implementation for the THEOplayer Web SDK with Firebase as the database service.

This repository may also be useful if you're using another database service, because the repository demonstrates the correct order of hooking into the playback events related to Wicket Labs, and how to format them. In other words: if you're using another database service, you just need to emit the events to a different source.

### Android (TV) SDK

THEOplayer and Wicket Labs currently do not host a sample implementation for Android-based platforms on GitHub.

Developers are encouraged to use <https://github.com/THEOplayer/samples-wicket-labs-html5-sdk> and <https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/> as a starting point. Additionally, developers are encouraged to reach out to their contacts at THEOplayer and/or Wicket Labs if they need assistance, which could prompt THEOplayer and Wicket Labs into publishing a sample implementation on GitHub.

### iOS (/tvOS) SDK

THEOplayer and Wicket Labs currently do not host a sample implementation for iOS or tvOS on GitHub.

Developers are encouraged to use <https://github.com/THEOplayer/samples-wicket-labs-html5-sdk> and <https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/> as a starting point. Additionally, developers are encouraged to reach out to their contacts at THEOplayer and/or Wicket Labs if they need assistance, which could prompt THEOplayer and Wicket Labs into publishing a sample implementation on GitHub.

## Related links

* github.com/THEOplayer: <https://github.com/THEOplayer/samples-wicket-labs-html5-sdk>
* wicketlabs.com: [How to Setup Firebase for OTT Video Services](https://www.wicketlabs.com/resources/knowledge-base/how-to-setup-firebase-for-ott-video-services/)

---

# Tealium

Tealium is a [tag management system](https://tealium.com/resource/fundamentals/what-is-tag-management/) and offers [integrations](https://tealium.com/integrations/) with [Google Analytics](https://tealium.com/integrations/google-analytics/), [Adobe Analytics](https://tealium.com/integrations/adobe-analytics/), and others.

Tealium can be implemented on top of THEOplayer as a custom integration. Refer to the article on [building a custom analytics integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/custom-analytics-integration.md) for more information on how to build an integration on top of THEOplayer.

## SDKs

As a developer you will have to [build a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/custom-analytics-integration.md) to support Tealium through a THEOplayer SDK.

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Custom  | Custom      | Custom  | Custom   | Custom         | Custom         | Custom   |

## Connecting Tealium to THEOplayer

Tealium can be integrated on top of THEOplayer.

### Web SDK

The Tealium documentation includes articles that describe:

* [How to install Tealium for JavaScript](https://docs.tealium.com/platforms/javascript/install/).
* [How to implement tracking](https://docs.tealium.com/platforms/javascript/track/), but also mentions that "video tracking often requires a custom solution coding to the specifications of the video platform API".
* [Basic video tracking](https://docs.tealium.com/platforms/getting-started-web/data-layer/definitions/basic-video-tracking/) on the data layer.
* [An introduction to the Data Layer](https://docs.tealium.com/platforms/getting-started-web/data-layer/an-introduction-to-the-data-layer/).

### Android SDK

The Tealium documentation includes articles that describe:

* How to install Tealium [for Java](https://docs.tealium.com/platforms/android-java/install/) or [for Kotlin](https://docs.tealium.com/platforms/android-kotlin/install/).
* How to implement tracking [for Java](https://docs.tealium.com/platforms/android-java/track/) or [for Kotlin](https://docs.tealium.com/platforms/android-kotlin/install/).

The guides linked above for the Data Layer and basic video tracking on it, are also relevant here.

### iOS/tvOS SDK

The Tealium documentation includes articles that describe:

* [How to install Tealium for Swift](https://docs.tealium.com/platforms/ios-swift/install/).
* [How to implement tracking](https://docs.tealium.com/platforms/ios-swift/track/).

The guides linked above for the Data Layer and basic video tracking on it, are also relevant here.

### Other platforms

Refer to the documentation at <https://docs.tealium.com/platforms/> for other platforms.

---

# Segment

Segment is a [Customer Data Platform](https://segment.com/docs/guides/), and offers [integrations](https://segment.com/docs/connections/destinations/catalog/index-all/) with [Google Analytics](https://segment.com/docs/connections/destinations/catalog/google-analytics/), [Adobe Analytics](https://segment.com/docs/connections/destinations/catalog/adobe-analytics/), [Youbora](https://segment.com/docs/connections/destinations/catalog/youbora/), and others.

Segment sets up "[Connections](https://segment.com/docs/connections/)" between "[Sources](https://segment.com/docs/connections/sources/)" and "[Destinations](https://segment.com/docs/connections/destinations/)".

* Sources send messages into Segment (and other tools). They have JavaScript source, an Android source, and so on.
* Destinations (like Google Analytics, Adobe Analytics, Youbora) receive messages from Segment.

Segment can be implemented on top of THEOplayer. Refer to the article on [building a custom analytics integrations](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/custom-analytics-integration.md) for more information on how to build an integration on top of THEOplayer.

## SDKs

As a developer you'll have to [build a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/custom-analytics-integration.md) to support Segment through a THEOplayer SDK.

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Custom  | Custom      | Custom  | Custom   | Custom         | Custom         | Custom   |

## Connecting Segment to THEOplayer

Segment can be integrated on top of THEOplayer.

### Web SDK

You'll (most likely) use the "[Analytics.js](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/)" source to get access to the Segment API.

Then, for each of your destinations, you want to figure out whether you can use the "Video Spec", or whether need to do something specific for some destinations (e.g. [Youbora](https://segment.com/docs/connections/destinations/catalog/youbora/)).

Segment describes a "Video Spec" at <https://segment.com/docs/connections/spec/video/>, but this article also mentions that "not all destinations support video tracking and you should always check with the individual destination documentation to confirm".

### Android SDK

You'll (most likely) use the "[Analytics for Android SDK](https://segment.com/docs/connections/sources/catalog/libraries/mobile/android/)" source to get access to the Segment API.

Then, for each of your destinations, you want to figure out whether you can use the "Video Spec", or whether need to do something specific for some destinations (e.g. [Youbora](https://segment.com/docs/connections/destinations/catalog/youbora/)).

Segment describes a "Video Spec" at <https://segment.com/docs/connections/spec/video/>, but this article also mentions that "not all destinations support video tracking and you should always check with the individual destination documentation to confirm".

### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

You'll (most likely) use the "[Analytics for iOS SDK](https://segment.com/docs/connections/sources/catalog/libraries/mobile/ios/)" source to get access to the Segment API.

Then, for each of your destinations, you want to figure out whether you can use the "Video Spec", or whether need to do something specific for some destinations (e.g. [Youbora](https://segment.com/docs/connections/destinations/catalog/youbora/)).

Segment describes a "Video Spec" at <https://segment.com/docs/connections/spec/video/>, but this article also mentions that "not all destinations support video tracking and you should always check with the individual destination documentation to confirm".

### Other platforms

Refer to the documentation at <https://segment.com/docs/>.

---

# Introduction

In this section you will learn everything about how THEOplayer works with Chromecast.

## API

As a developer, you might need to use the THEOplayer Chromecast API to build a custom Chromecast UI and UX, or to dispatch an event to an analytics service, or for workflow purposes.

The Chromecast interface is a sub-interface of the Cast interface on THEOplayer Web and on both mobile (Android & iOS) SDKs.

The API reference is available through the following links:

* Web SDK: [Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Chromecast), which inherits from [VendorCast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VendorCast)
* Android SDK: [Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/cast/chromecast/Chromecast)
* iOS SDK: [Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/Chromecast)

Use the API as demonstrated below:

### Web SDK

```javascript
// const player = new THEOplayer.Player(...)
const chromecastState = player.cast.chromecast.state;
const isCasting = player.cast.chromecast.casting; // true or false
// ...
// if (want to start Chromecast)
player.cast.chromecast.start();
// ...
// if (want to stop Chromecast)
player.cast.chromecast.stop();
// ...
if (chromecastState != 'unavailable') {
  // Chromecast is possible
  player.cast.chromecast.addEventListener('statechange', function (event) {
    switch (event.state) {
      case 'connecting':
        // show Chromecast trying-to-connect icon
        break;
      case 'available':
        // show Chromecast available icon
        break;
      case 'connected':
        // show Chromecast connected icon
        break;
      case 'unavailable':
        // hide Chromecast icon
        break;
    }
  });
}
```

### Android SDK

```java
// Verify the Cast dependency is present in your build.gradle file.
// Add Cast Integration to the player.
CastIntegration castIntegration = CastIntegrationFactory.createCastIntegration(theoplayerView);
theoplayerView.getPlayer().addIntegration(castIntegration);

// For actions you can use both the THEOplayerView and the CastIntegration object.
theoplayerView.getCast().getChromecast().start();
// or
castIntegration.start();

// For listening to events nothing changed.
theoplayerView.getCast().getChromecast().addEventListener(ChromecastEventTypes.STATECHANGE, event -> {
    // See Android section.
});
```

### iOS SDK

To use Google Cast, also known as Chromecast, with the THEOplayer iOS SDK, the **THEOplayer GoogleCast Integration** should be integrated. The integration is a lightweight module written in Swift, to enable casting playback from an iOS device to a receiver application.

#### Installation

The THEOplayer GoogleCast integration is published on the following package managers:

##### CocoaPods

Simply add the following to your project's Podfile:

```ruby
pod 'THEOplayer-Integration-GoogleCast'
```

The above entry automatically manages the fetching of the GoogleCast SDK dependency.

In case where the integrator would want to manage fetching a specific version of the GoogleCast SDK, then replace the Podfile entry with:

```ruby
pod 'THEOplayer-Integration-GoogleIMA/Base'
pod 'google-cast-sdk-dynamic-xcframework', '4.8.3' # specify the desired version
```

##### Swift Package Manager

Please check the [installation instruction found here](https://github.com/THEOplayer/theoplayer-sdk-apple/README.md#installation)

> **Warning**
>
> This will not get the GoogleCast SDK, but only the THEOplayer GoogleCast integration. You need to manage fetching the GoogleCast SDK dependency.

#### Import

Import the framework in the source files where it will be used:

```swift
import THEOplayerGoogleCastIntegration
```

You will also need the THEOplayer core SDK since the THEOplayer GoogleCast integration extends its functionality.<br />To import the THEOplayer core SDK framework add:

```swift
import THEOplayerSDK
```

#### Usage

First set the context in your `AppDelegate` file's `didFinishLaunchingWithOptions` method:

```swift
THEOplayerGoogleCastIntegration.CastIntegrationHelper.setGCKCastContextSharedInstanceWithDefaultCastOptions()
```

> **Note**
>
> The above method will set the options for `GCKCastContext` with a CAF receiver application. If a custom context must be set, instead of calling the `setGCKCastContextSharedInstanceWithDefaultCastOptions` method, the implementation should specify an `GCKDiscoveryCriteria` in the context with an `applicationID` parameter. You can find the default THEOplayer CAF V3 default application ID at `CastIntegrationHelper.defaultV3ReceiverApplicationID`.

> **Info**
>
> The THEOplayer Google Cast integration only supports CAF receivers.

Second, you will need to provide some privacy permissions and network discovery allowances. For more information on this, please check the [following documentation about permissions and discovery.](https://developers.google.com/cast/docs/ios_sender/permissions_and_discovery)

After initializing your `THEOplayer` instance, initialize the integration and pass it to the `THEOplayer` instance:

```swift
let configBuilder = THEOplayerConfigurationBuilder()
configBuilder.license = "your_theoplayer_license"
let theoplayer = THEOplayer(configuration: configBuilder.build()

let castConfiguration: CastConfiguration = CastConfiguration(strategy: .auto)
let castIntegration: THEOplayerSDK.Integration = GoogleCastIntegrationFactory.createIntegration(on: theoplayer, with: castConfiguration)
theoplayer.addIntegration(castIntegration)
```

> **Info**
>
> Additional APIs can be found on the `castIntegration` or `theoplayer.cast.chromecast` endpoints.

<br />For more extensive example on how to implement GoogleCast with THEOplayer, please check [this sample app](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Native-GoogleCast).

## Related articles

* [Connecting from custom Sender applications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/connecting-from-custom-sender-applications.md)
* [Debugging](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/debugging.md)
* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/how-to-configure-to-a-different-stream.md)
* [Sending messages from/to Sender to/from Receiver](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/sending-messages-from-to-sender-to-from-receiver.md)
* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)
* [Enable Chromecast on the Sender](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/enable-chromecast-on-the-sender.md)

## Sender Applications vs Receiver Applications

When a viewer is streaming through a Chromecast device, they are actually casting content from a sender application (e.g. an Android application) to a receiver application. A sender application informs a physical Chromecast device which receiver application it should load through an application ID.

If you have implemented THEOplayer in your sender application, you can [enable Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/enable-chromecast-on-the-sender.md). Furthermore, you can also [specify the application ID](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/enable-chromecast-on-the-sender.md#custom-receiver-app) in your sender application.

![Casting approaches](/pr-932/assets/images/casting-approaches-45dc2983f20d11409d27d3248b57a6ef.png "Casting approaches")

By specifying the application ID, you implicitly connect it with a type of receiver application. The following three types of receiver applications are common:

| Type                                    | Maintainer             | Info                                                                                                                                                                                                                            | Benefits                                                                                                                                                                                                      | Disadvantages                                                                                                                       |
| --------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Default THEOplayer Receiver Application | THEOplayer             | This is the default receiver application THEOplayer SDKs will connect with. The app ID of this default THEOplayer receiver application is `8E80B9CE`.                                                                           | You (i.e. the developer) do not need to do anything extra on the Chromecast receiver application side. You don't need to create a Chromecast receiver, you don't need to register it at, ... - it just works. | You are limited w\.r.t. customizing the UI and integrating custom logic.                                                            |
| Custom THEOplayer Receiver Application  | Developer + THEOplayer | This is a custom receiver application you can build, and where you integrate the [THEOplayer Chromecast SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/chromecast/getting-started.md). | You (i.e. the developer) can adjust the look and feel, and integrate custom logic.                                                                                                                            | You need to create a Chromecast receiver, register it, maintain it, ...                                                             |
| Customer Receiver Application           | Developer              | This is a custom receiver application you can build, but without using the THEOplayer Chromecast SDK.                                                                                                                           | The THEOplayer Chromecast Receiver SDK is not a dependency.                                                                                                                                                   | You are responsible for building and maintaining the receiver application, and its connection with the various sender applications. |

## Whitelisting Receiver Applications

Streaming services and products often require you to whitelist domain names to allow playback. When viewers are casting content to a Chromecast receiver application, your Chromecast device will actually stream the content on a domain name. In other words: CORS and whitelisting/blacklisting policies do apply to Chromecast sessions. Ensure that you've whitelisted the domain name which hosts your Chromecast receiver application. (You can look up the domain name of your receiver application at <https://cast.google.com/publish/#/overview>.)

If you're using the Default THEOplayer Receiver Application you may whitelist `https://d3ojqkc95d8mrd.cloudfront.net/`.

---

# Connecting from custom Sender applications

## General

In general, the following flow should be followed:

1. Set up Google Cast context with correct receiver application ID.
2. Connect to Chromecast device.
3. Set up Google Cast MediaInfo object with correct contentID and contentType.
4. Send Google Cast LoadRequest with a serialized THEOplayer SourceDescription object as a key in the customData of the LoadRequest. So something like `{sourceDescription: ${SourceDescription you want to cast}}`.

Let's discuss this in more detail for custom [Web](#web), [Android](#android) and [iOS](#ios) applications.

### Web

The following web page should suffice:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Title</title>
    <script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
    <script>
      window['__onGCastApiAvailable'] = function (isAvailable) {
        if (isAvailable) {
          cast.framework.CastContext.getInstance().setOptions({
            receiverApplicationId: '$YOUR_APP_ID', // Adapt this
            autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED, // And this if you want to
          });
        }
      };
    </script>
    <script>
      function startCasting(sourceDescription) {
        var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
        var mediaInfo = new chrome.cast.media.MediaInfo(sourceDescription.sources[0].src, sourceDescription.sources[0].type);
        var request = new chrome.cast.media.LoadRequest(mediaInfo);
        request.customData = { sourceDescription: sourceDescription };
        castSession.loadMedia(request).then(
          function () {
            console.log('Load succeed');
          },
          function (errorCode) {
            console.log('Error code: ' + errorCode);
          }
        );
        var player = new cast.framework.RemotePlayer();
        var playerController = new cast.framework.RemotePlayerController(player);
        return playerController;
      }
    </script>
  </head>
  <body></body>
</html>
```

Load this in Google Chrome, connect to a Chromecast device, and then you can do the following:

```js
startCasting({
  sources: [
    {
      src: 'https://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/manifest(format=mpd-time-csf)',
      type: 'application/dash+xml',
      contentProtection: {
        widevine: {
          licenseAcquisitionURL: 'https://amssamples.keydelivery.mediaservices.windows.net/Widevine/?KID=1ab45440-532c-4399-94dc-5c5ad9584bac',
        },
      },
    },
  ],
});
```

This will start playback.

### Android

First, set up your `CastOptionsProvider`:

```java
package com.yourcomp.chromecastSender;

import android.content.Context;

import com.google.android.gms.cast.framework.CastOptions;
import com.google.android.gms.cast.framework.OptionsProvider;
import com.google.android.gms.cast.framework.SessionProvider;

import java.util.List;

public class THEOCastOptionsProvider implements OptionsProvider {

    public static String DEFAULT_APP_ID = "8E80B9CE";

    @Override
    public CastOptions getCastOptions(Context context) {
        return new CastOptions.Builder()
                .setReceiverApplicationId(DEFAULT_APP_ID)
                .build();
    }

    @Override
    public List<SessionProvider> getAdditionalSessionProviders(Context context) {
        return null;
    }
}
```

And link to it in your `AndroidManifest.xml` file:

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.yourcomp.chromecastSenderApp">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />

    <application
    ...
        <meta-data
            android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
            android:value="com.yourcomp.chromecastSender.CastOptionsProvider" />
    </application>

</manifest>
```

Fill in the correct class name by replacing `com.yourcomp.chromecastSender.CastOptionsProvider`! You can change the `DEFAULT_APP_ID` to direct to your own Chromecast app. Next you can actually do the casting like the following:

```java
package com.yourcomp.chromecastSender;

import android.app.Activity;
import android.support.v7.app.MediaRouteChooserDialog;

import com.google.android.gms.cast.MediaInfo;
import com.google.android.gms.cast.MediaLoadOptions;
import com.google.android.gms.cast.framework.CastContext;
import com.google.android.gms.cast.framework.CastSession;
import com.google.android.gms.cast.framework.SessionManagerListener;

import org.json.JSONException;
import org.json.JSONObject;

public class ChromecastSender {
    public ChromecastSender() {
    }

    public void sendSourceToChromecast(Activity context) throws JSONException {
        CastContext castContext = CastContext.getSharedInstance(context);
        showCastChooserDialog(context, castContext);

        JSONObject sourceDescriptionJson = new JSONObject("{"sourceDescription":{"sources":[{"src":"https://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/manifest(format=mpd-time-csf)","type":"application/dash+xml","contentProtection":{"widevine":{"licenseAcquisitionURL":"https://amssamples.keydelivery.mediaservices.windows.net/Widevine/?KID=1ab45440-532c-4399-94dc-5c5ad9584bac"}}}]}}");
        MediaLoadOptions mediaLoadOptions = new MediaLoadOptions.Builder().setCustomData(sourceDescriptionJson).build();
        MediaInfo mediaInfo = new MediaInfo.Builder("https://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/manifest(format=mpd-time-csf)").setContentType("application/dash+xml")
                .build();

        castContext.getSessionManager().addSessionManagerListener(new SessionManagerListener<CastSession>() {
            @Override
            public void onSessionStarting(CastSession castSession) {

            }

            @Override
            public void onSessionStarted(CastSession castSession, String s) {

                castSession.getRemoteMediaClient().load(mediaInfo,mediaLoadOptions);
            }

            @Override
            public void onSessionStartFailed(CastSession castSession, int i) {

            }

            @Override
            public void onSessionEnding(CastSession castSession) {

            }

            @Override
            public void onSessionEnded(CastSession castSession, int i) {

            }

            @Override
            public void onSessionResuming(CastSession castSession, String s) {

            }

            @Override
            public void onSessionResumed(CastSession castSession, boolean b) {

            }

            @Override
            public void onSessionResumeFailed(CastSession castSession, int i) {

            }

            @Override
            public void onSessionSuspended(CastSession castSession, int i) {

            }
        }, CastSession.class);


    }

    private void showCastChooserDialog(Activity context, CastContext castContext) {
        MediaRouteChooserDialog mediaRouteChooserDialog = new MediaRouteChooserDialog(context);
        mediaRouteChooserDialog.setRouteSelector(castContext.getMergedSelector());
        mediaRouteChooserDialog.show();
    }
}
```

Instantiate this class and then connect to a device. This will start casting the source listed in the class to the Chromecast receiver.

### iOS

When launching your application, start your Google Cast context using the following snippet:

```swift
let options = GCKCastOptions(receiverApplicationID: "8E80B9CE")
GCKCastContext.setSharedInstanceWith(options)
```

Once this is done, it’s necessary to start a session. This is usually done by creating a cast button somewhere in your UI using `GCKUICastButton`, which when pressed opens up a dialog allowing you to select a device and start a session.

Once a session is started, you can start playing back content. The THEOplayer Chromecast receiver is capable of playing back content easily using the default Google Cast APIs (with `GCKMediaInformationBuilder` and `LoadRequest`). However, to use the more advanced functionality, you will need to pass in custom data in the [`GCKMediaLoadOptions`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_load_options) object.

This custom data follows the structure of `SourceDescription` as used in the web version of THEOplayer, except we have to use `NSDictionary` notation.

```swift
let metadata = GCKMediaMetadata()
metadata.setString("Title", forKey: kGCKMetadataKeyTitle)
metadata.setString("Subtitle", forKey: kGCKMetadataKeySubtitle)

let contentURL = "https://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/manifest(format=mpd-time-csf)"
let contentID = "622b189f-ec39-43f2-93a2-201ac4e31ce1"

let informationBuilder = GCKMediaInformationBuilder(contentURL: contentURL)
informationBuilder.contentID = contentID
informationBuilder.streamType = .unknown
informationBuilder.contentType = "application/dash+xml"
informationBuilder.streamDuration = 0.0
informationBuilder.mediaTracks = nil
informationBuilder.metadata = metadata
let information = informationBuilder.build()

let sourceDescription = [
    "sources": [
        [
            "src": "https://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/manifest(format=mpd-time-csf)",
            "type": "application/dash+xml",
            "contentProtection": [
                "widevine": [
                    "licenseAcquisitionURL": "https://amssamples.keydelivery.mediaservices.windows.net/Widevine/?KID=1ab45440-532c-4399-94dc-5c5ad9584bac"
                ]
            ]
        ]
    ]
]

let loadOptions = GCKMediaLoadOptions()
loadOptions.autoplay = true
loadOptions.playPosition = 0.0
loadOptions.customData = ["sourceDescription": sourceDescription]

castSession!.remoteMediaClient?.loadMedia(mediaInfo, with: loadOptions)
```

Note that you should also adapt the contentID and contentType in the arguments for the `GCKMediaInformation` initializer.

You have to use the Chromecast API to implement additional logic such as pausing the Chromecast Receiver application, fetching the video's progress, ...

## Related articles

* [How can we track the first play(ing) event?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/how-can-we-track-the-first-playing-event.md)

* [How to start with a specific quality?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-start-with-specific-quality.md)

* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)

* [How to know whether a live stream is playing?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-know-when-livestream-is-playing.md)

* [Getting started on Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/chromecast/getting-started.md)

---

# Debugging

This how-to guide describes how to debug a Chromecast Receiver application using the THEOplayer Web SDK.

## Step-by-step guide

1. Ensure that you are on the same network as your Chromecast device.
2. Publish a new device at <https://cast.google.com/u/1/publish/#/devices> by clicking "ADD NEW DEVICE". ![Chromecast debugging 1](/pr-932/assets/images/chromecast_debugging_1-0040e1d6eeca0a6b5501cef46a031989.png "Chromecast debugging 1")
3. Wait until the status is "Ready For Testing". ![Chromecast debugging 2](/pr-932/assets/images/chromecast_debugging_2-c399ddb9c096aab91c30293a8a9e9f50.png "Chromecast debugging 2")
4. Find out what the IP-address of your Chromecast device is. (Tip: Use the Google Home app to look this up.)
5. Go to chrome://inspect and add the IP-address (plus port 9222) of your Chromecast device.
6. Start your Chromecast session.
7. Go to chrome://inspect and wait until your Chromecast device appears in the list.
8. Press "inspect". ![Chromecast debugging 3](/pr-932/assets/images/chromecast_debugging_3-ef34a49f03eb6830f56bfdaf20a04fb5.png "Chromecast debugging 3")
9. You should now have access to the Chrome Developer Tools of your Chromecast Receiver application. If you are familiar with debugging through Chrome's Developer Tools, you can look into issues, try out new CSS styles and monitor network traffic. ![Chromecast debugging 4](/pr-932/assets/images/chromecast_debugging_4-17c946d842f3a40de725316bce17a9f7.png "Chromecast debugging 4")

## Related articles

* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)

* [Chromecast SDK Setup](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/chromecast/getting-started.md)

* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/how-to-configure-to-a-different-stream.md)

---

# How to configure a different stream to Chromecast

Some streaming setups require you to cast a different stream to a Chromecast Receiver device than the one playing on a Chromecast Receiver device. For example, if your playing HLS + FairPlay DRM on your iOS application, you need to cast a different source with DASH + Widevine DRM to your Chromecast application, because Chromecast applications aren't able to support FairPlay.

There are two approaches to achieve this use case:

1. [ChromecastConnection API](#chromecastconnection-api) (available as of THEOplayer 2.90.0)
2. [Chromecast source API](#chromecast-source-api) (deprecated as of THEOplayer 2.90.0)

You should no longer use the second approach as of THEOplayer 2.90.0 because this API is no longer maintained (even though it *may* be available).

## ChromecastConnection API

The ChromecastConnection API allows you to implement callbacks related to Chromecast playback. To achieve the described use case you can use the `onStart` (i.e. the start of a Chromecast session) to set a new stream, and `onStop` (i.e. the end of a Chromecast session) to (re)set your previous stream.

You may also be interested in `onJoin` (i.e. joining an existing Chromecast session with a new device) or `onLeave` (i.e. leaving an existing Chromecast session on a device).

### SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Yes     | Yes         | Yes     | N/A      | N/A            | N/A            | N/A      |

#### Web SDK

The snippet below has two [sources](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SourceDescription):

1. `senderSource` is intended for playback on your sender device (i.e. your browser)
2. `chromecastSource` is intended for playback on your Chromecast application

The [`ChromecastConnectionCallback`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/ChromecastConnectionCallback) interface is used to:

1. Set the `chromecastSource` when Chromecast playback starts through the `onStart` callback.
2. Revert to the `senderSource` when Chromecast playback stops through the `onStop` callback.

```js
var senderSource = {
  sources: {
    src: 'https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8',
    type: 'application/x-mpegurl',
  },
};
var chromecastSource = {
  sources: {
    src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
    type: 'application/x-mpegurl',
  },
};
player.source = senderSource;
player.cast.chromecast.connectionCallback = {
  onStart: function (source) {
    return chromecastSource;
  },
  onStop: function (source) {
    return senderSource;
  },
  onJoin: function (source) {
    return source;
  },
  onLeave: function (source) {
    return source;
  },
};
```

The `onJoin` and `onLeave` implementations in the above snippet adhere to the default behavior.

#### Android SDK

The snippet below has two [sources](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/source/SourceDescription.Builder):

1. `senderSource` is intended for playback on your sender device (i.e. your Android app)
2. `chromecastSource` is intended for playback on your Chromecast application

The [`setConnectionCallback`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/cast/chromecast/Chromecast#setConnectionCallback-com.theoplayer.android.api.cast.chromecast.ChromecastConnectionCallback-) method is used to through the [\`THEOplayerView'](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/THEOplayerView) object:

1. Set the `chromecastSource` when Chromecast playback starts through the `onStart` callback.
2. Revert to the `senderSource` when Chromecast playback stops through the `onStop` callback.

```java
SourceDescription senderSource = new SourceDescription.Builder(new TypedSource.Builder("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8").type(SourceType.HLS).build())
        .build();
SourceDescription chromecastSource = new SourceDescription.Builder(new TypedSource.Builder("https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8").type(SourceType.HLS).build())
        .build();
theoPlayerView.getPlayer().setSource(senderSource);
theoPlayerView.getCast().getChromecast().setConnectionCallback(new ChromecastConnectionCallback() {
    @Nullable
    @Override
    public SourceDescription onStart(@Nullable SourceDescription sourceDescription) {
        return chromecastSource;
    }

    @Nullable
    @Override
    public SourceDescription onStop(@Nullable SourceDescription sourceDescription) {
        return senderSource;
    }

    @Nullable
    @Override
    public SourceDescription onJoin(@Nullable SourceDescription sourceDescription) {
        return sourceDescription;
    }

    @Nullable
    @Override
    public SourceDescription onLeave(@Nullable SourceDescription sourceDescription) {
        return sourceDescription;
    }
});
```

The `onJoin` and `onLeave` implementations in the above snippet adhere to the default behavior.

#### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

To achieve this use case on the iOS SDK, you have to leverage the [`ChromecastConnectionDelegate`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/Chromecast_Objc#/c:@M@THEOplayerSDK@objc\(pl\)THEOplayerChromecast\(im\)setConnectionDelegate:) of your [`THEOplayer`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer) object.

The snippet below is an example of how your `ChromecastConnectionDelegate` could look like. This particular snippet has two [sources](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/SourceDescription):

1. `senderSource` is intended for playback on your sender device (i.e. your iOS app)
2. `chromecastSource` is intended for playback on your Chromecast application

The [`ChromecastConnectionCallback`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/ChromecastConnectionCallback) interface is used to:

1. Set the `chromecastSource` when Chromecast playback starts through the `onStart` callback.
2. Revert to the `senderSource` when Chromecast playback stops through the `onStop` callback.

```swift
import UIKit
import THEOplayerSDK

class ChromecastController: ChromecastConnectionDelegate {

    weak var theoplayer : THEOplayer?

    private var senderSource: SourceDescription {
        let typedSource = TypedSource(
            src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8",
            type: "application/x-mpegurl"
        )
        return SourceDescription(source: typedSource)
    }

    private var chromecastSource: SourceDescription {
        let typedSource = TypedSource(
            src: "https://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/manifest(format=mpd-time-csf)",
            type: "application/dash+xml",
            drm: WidevineDRMConfiguration(licenseAcquisitionURL: "https://amssamples.keydelivery.mediaservices.windows.net/Widevine/?KID=1ab45440-532c-4399-94dc-5c5ad9584bac")
        )
        return SourceDescription(source: typedSource)
    }

    init(theo : THEOplayer) {
        self.theoplayer = theo
        self.theoplayer?.cast?.chromecast?.setConnectionDelegate(self)
    }

    func onStart(sourceDescription: SourceDescription?) -> SourceDescription? {
        return chromecastSource
    }

    func onStop(sourceDescription: SourceDescription?) -> SourceDescription? {
        return senderSource
    }

    func onJoin(sourceDescription: SourceDescription?) -> SourceDescription? {
        return sourceDescription
    }

    func onLeave(sourceDescription: SourceDescription?) -> SourceDescription? {
        return sourceDescription
    }

}
```

The `onJoin` and `onLeave` implementations in the above snippet adhere to the default behavior.

Once you've implemented your `ChromecastConnectionDelegate`, you have to initialize an instance of this near the code of your where you're setting your `player.source` (e.g. <https://github.com/THEOplayer/samples-ios-sdk/blob/master/Google-Cast/Google_Cast/PlayerViewController.swift>). The snippet below demonstrates this concept:

```swift
...
class PlayerViewController: UIViewController {

    ...
    var chromecastController : ChromecastController!
    var senderSource: SourceDescription {
        let typedSource = TypedSource(
            src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8",
            type: "application/x-mpegurl"
        )
        return SourceDescription(source: typedSource)
    }
    ...

    override func viewDidLoad() {

        ...
        player.source = senderSource
        chromecastController = ChromecastController(theo: theoplayer)
        ...

    }

    ...

}
...
```

## Chromecast source API

The Chromecast source API is a straightforward technique to configure a different [`source`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SourceDescription) to be loaded for Chromecast playback.

This API is unmaintained (and deprecated) as of THEOplayer 2.90.0, and developers should use the [ChromecastConnection API](#chromecastconnection-api) instead.

### SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Yes     | Yes         | Yes     | N/A      | N/A            | N/A            | N/A      |

#### Web SDK

The [Chromecast API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Chromecast) allows you to configure a different source (i.e. [`SourceDescription`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SourceDescription)) to be Chromecasted. The snippet below demonstrates this API.

```js
const source = {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
      type: 'application/x-mpegurl',
    },
  ],
};
player.cast.chromecast.source = source;
```

#### Android SDK

The [Chromecast API](https://cdn.theoplayer.com/doc/android/2.55.1/com/theoplayer/android/api/cast/chromecast/Chromecast.html#setSource-com.theoplayer.android.api.source.SourceDescription-) allows you to configure a different SourceDescription to be Chromecasted through the [`Cast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/cast/Cast) of your [\`THEOplayerView'](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/THEOplayerView) object.

```java
SourceDescription source = new SourceDescription.Builder("//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8").build();
theoPlayerView.getCast().getChromecast().setSource(source);
```

#### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

The [Chromecast API](https://cdn.theoplayer.com/doc/ios/2.55.1/Protocols/Chromecast.html#/s:13THEOplayerSDK10ChromecastP6sourceAA17SourceDescriptionCSgvp) allows you to configure a different SourceDescription to be Chromecasted through the [`Cast`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/Cast) instance of your [`THEOplayer`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer) object.

```swift
var theoplayerChromecast = theoplayer.cast?.chromecast
theoplayerChromecast?.source = SourceDescription(
    source: TypedSource(
        src: "https://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/manifest(format=mpd-time-csf)",
        type: "application/dash+xml",
        drm: WidevineDRMConfiguration(licenseAcquisitionURL: "https://amssamples.keydelivery.mediaservices.windows.net/Widevine/?KID=1ab45440-532c-4399-94dc-5c5ad9584bac")
    )
)
```

---

# Sending messages from/to Sender to/from Receiver

This article will explain how to send data to an active receiver and how to respond on the receiver.

**On our Web SDK, this functionality was implemented from 2.79.0 onwards.**

## Send data to the receiver

The Google Cast SDK has a global object that everyone can access. This global object is also being used by THEOplayer. The general idea is to retrieve the current active cast session and send a message on a specific namespace.

##### Web SDK

```js
// Retrieve the current cast session
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
// Send message on defined namespace channel
castSession.sendMessage('namespace', 'message');
```

Reference:

* <https://developers.google.com/cast/docs/reference/chrome/cast.framework.CastSession>
* <https://developers.google.com/cast/docs/reference/chrome/cast.framework.CastSession#sendMessage>

##### Android SDK

```java
// Retrieve the current cast session
CastSession castSession = CastContext.getSharedInstance(this).getSessionManager().getCurrentCastSession();
// Send message on defined namespace channel
castSession.sendMessage("namespace", "message");
```

Reference:

* <https://developers.google.com/android/reference/com/google/android/gms/cast/framework/CastSession>

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

On iOS, we need a component that implements the GCKGenericChannelDelegate protocol.

```swift
// Retrieve the current cast session
let castSession = GCKCastContext.sharedInstance().sessionManager.currenCastSession
// Create the defined namespace channel
let channel = GCKGenericChannel(namespace: "namespace")
// Set the delegate for the namespace channel (GCKGenericChannelDelegate)
channel.delegate = self
// Add the channel to the current cast session
castSession?.add(channel)
// Send message on channel (the error parameter is a pointer at which to store the error result, this may be nil)
channel.sendTextMessage("message", error: nil)
```

Reference:

* <https://developers.google.com/cast/docs/reference/ios/protocol_g_c_k_generic_channel_delegate-p>
* <https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_cast_session>
* <https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_generic_channel>
* <https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_cast_session.html#a3514b6933a579d4255702375f542c16a>
* <https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_cast_channel.html#ab7f595487ce145f38b2e82e55126789b>

## Receive data from the receiver

The general idea is to retrieve the current active cast session and add an event listener on the specific namespace.

##### Web SDK

```js
// Retrieve the current cast session
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
// Add an event listener to the defined namespace channel
castSession.addMessageListener('namespace', (namespace, message) => {
  console.log(namespace, message);
});
```

Reference:

* <https://developers.google.com/cast/docs/reference/chrome/cast.framework.CastSession#addMessageListener>

##### Android SDK

```java
// Retrieve the current cast session
CastSession castSession = CastContext.getSharedInstance(this).getSessionManager().getCurrentCastSession();
// Create callback handler
Cast.MessageReceivedCallback callback = new Cast.MessageReceivedCallback() {
    @Override
    public void onMessageReceived(CastDevice castDevice, String namespace, String message) {
        // Do something with the message
    }
};
// Add the message listener to the current cast session
castSession.setMessageReceivedCallbacks("namespace", callback);
```

Reference:

* <https://developers.google.com/android/reference/com/google/android/gms/cast/framework/CastSession.html#setMessageReceivedCallbacks(java.lang.String,%20com.google.android.gms.cast.Cast.MessageReceivedCallback)>

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

The delegate of the channel will handle the receiving of messages.

```swift
extension ChromecastController : GCKGenericChannelDelegate {
    func cast(_ channel: GCKGenericChannel, didReceiveTextMessage message: String, withNamespace protocolNamespace: String) {
        print("Channel didReceiveTextMessage", message)
    }
}
```

Reference:

* <https://developers.google.com/cast/docs/reference/ios/protocol_g_c_k_generic_channel_delegate-p>

## Receive data on the receiver

*This example is for receiver version 2.*

The general idea is to retrieve the receiver manager and add a message listener for the specific namespace. **This needs to be done before a THEOplayer instance is created. THEOplayer will call the start method of the receiverManager on initialization.**

```js
// Retrieve the cast receiver manager
var castReceiverManager = cast.receiver.CastReceiverManager.getInstance();
// Retrieve the message bus from the cast receiver manager
var messageBus = castReceiverManager.getCastMessageBus('namespace');
// Add message listener to the message bus
messageBus.onMessage = function (event) {
  console.log(event);
};
```

Reference:

* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus>
* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus#onMessage>
* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus.Event>

## Send data from the receiver

*This example is for receiver version 2.*

There are multiple possibilities to send data from the receiver:

1. When a message is received on the receiver, you can answer the sender

2. Broadcast to all connected senders

```js
// 1.
messageBus.onMessage = function (event) {
  messageBus.send(event.senderId, 'message');
};
// 2.
messageBus.broadcast('message');
```

Reference:

* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus#broadcast>
* <https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastMessageBus#send>

## Related articles

* [Pass subtitle selection on to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/pass-subtitle-section-on-to-chromecast.md)

* [Chromecast SDK Setup](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/chromecast/getting-started.md)

* [How to configure a different stream to Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/how-to-configure-to-a-different-stream.md)

* [Connecting from custom Sender applications](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/connecting-from-custom-sender-applications.md)

---

# Pass subtitle selection on to Chromecast

Currently, it is intended behavior that when you start casting the player to a Chromecast device the subtitle selection setting isn't carried over. A new player is generated with the `SourceConfiguration` of the sender, but not any adjustments.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | N/A      | N/A            | N/A            |

## Solution

You can work around the default behavior by adding the following eventListeners to the player.

The code adds an event on textTracks `change`. Whenever the subtitles change, this event is called and stores the current active textTrack in `currentTextTrack` by iterating over the textTracks array and checking whether `.mode` is `showing`. Once a Chromecast session is created, the code will check if the ID of the textTracks in the new player corresponds with the ID of the stored currentTextTrack. If so, it will activate that textTrack.

## Code Examples

Here is how you pass the current active subtitle track to the Chromecast session:

##### Web SDK

```js
var currentTextTrack;

player.textTracks.addEventListener('change', function () {
  for (var t in player.textTracks) {
    if (player.textTracks[t].mode === 'showing') {
      currentTextTrack = player.textTracks[t];
    }
  }
});

player.cast.chromecast.addEventListener('statechange', (event) => {
  if (event.state === 'connected') {
    player.addEventListener('playing', function () {
      for (var tt in player.textTracks) {
        if (player.textTracks[tt].id === currentTextTrack.id) {
          player.textTracks[tt].mode = 'showing';
        }
      }
    });
  }
});
```

##### Legacy Android SDK (4.12.x)

```java
final TextTrack currentTextTrack;

tpv.getPlayer().getTextTracks().addEventListener(TextTrackListEventTypes.TRACKLISTCHANGE, new EventListener<TrackListChangeEvent>() {
    @Override
    public void handleEvent(TrackListChangeEvent trackListChangeEvent) {
        for (TextTrack t : tpv.getPlayer().getTextTracks()) {
            if (t.getMode() == TextTrackMode.SHOWING) {
                currentTextTrack = t;
            }
        }
    }
});

tpv.getCast().getChromecast().addEventListener(ChromecastEventTypes.STATECHANGE, new EventListener<CastStateChangeEvent>() {
    @Override
    public void handleEvent(CastStateChangeEvent castStateChangeEvent) {
        if (tpv.getCast().getChromecast().getState() == PlayerCastState.CONNECTED) {
            tpv.getPlayer().addEventListener(PlayerEventTypes.PLAYING, new EventListener<PlayingEvent>() {
                @Override
                public void handleEvent(PlayingEvent playingEvent) {
                    for (TextTrack t : tpv.getPlayer().getTextTracks()) {
                        if (t.getId() == currentTextTrack.getId()) {
                            t.setMode(TextTrackMode.SHOWING);
                        }
                    }
                }
            });
        }
    }
});
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

```swift
var currentTextTrack: TextTrack?

    self.theoplayer.textTracks.addEventListener(type: TextTrackListEventTypes.CHANGE) { (result) in
        for i in 0..<self.theoplayer.textTracks.count {
        if self.theoplayer.textTracks[i].mode == .showing {
            currentTextTrack = self.theoplayer.textTracks[i]
        }
        }
    }

    self.theoplayer.cast?.chromecast?.addEventListener(type: ChromecastEventTypes.STATE_CHANGE, listener: { (result) in
    if result.state == .connected {
            self.theoplayer.addEventListener(type: PlayerEventTypes.PLAYING) { (result) in
                for i in 0..<self.theoplayer.textTracks.count {
                    var tt = self.theoplayer.textTracks[i]
                        if tt.id == currentTextTrack?.id {
                        tt.mode = .showing
                        }
                    }
                }
            }

        })
}
```

---

# Enable Chromecast on the Sender

This article explains how to enable the Chromecast Sender capabilities on the Web SDK, iOS SDK and Android SDK. This article also documents how you can connect with a customer Chromecast Receiver application.

## Prerequisites

1. The Chromecast feature needs to be enabled for your THEOplayer SDK. (THEOplayer is built in a modular fashion, and this feature might be disabled for your SDK.)
2. You need to import the Chromecast Sender SDK

## Import Chromecast Sender SDK

### Web SDK

To allow Chromecast playback you need to include Google's Chromecast Sender SDK, which is a JavaScript file. The JavaScript snippet below illustrates how you include this Sender SDK. You can read more about it at <https://developers.google.com/cast/docs/web_sender>.

```javascript
<script type="text/javascript" src="//www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
```

Once this SDK is imported, THEOplayer will automatically add the Chromecast casting capability to your player (if you've enabled the Chromecast feature for your THEOplayer SDK).

### Android SDK

Importing the Chromecast feature differs between the Android SDK and Legacy Android SDK (4.12.x) but the usage is similar. Therefore, the points 1 & 2 below are SDK specific meanwhile from point 3 and on they are similar.

**Notes**

* Please note that Chromecast support is not available for the Android TV and Fire TV SDKs.

#### Android SDK

In order to enable Chromecast on the THEOplayer Android SDK:

1. Use a version of THEOplayer’s Android SDK ≥ 3.4.0

2. Add the feature integration dependency in your `build.gradle` file.

```java
implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
implementation 'com.theoplayer.theoplayer-sdk-android:integration-cast:+' // add cast dependency
```

#### Legacy Android SDK (4.12.x)

In order to enable Chromecast on the THEOplayer Android SDK:

1. Use a version of THEOplayer’s Android SDK ≥ 1.0.9

2. Include the Cast Framework and Media Router libraries

   To add Chromecast support you need to include the Cast Framework and Media Router libraries under the dependencies node in your `build.gradle` file.

   ```java
   implementation 'androidx.mediarouter:mediarouter:1.1.0'
   implementation 'com.google.android.gms:play-services-cast-framework:19.0.0'
   ```

   Note: you may need to adjust the above snippet to match your Android setup.

3. Set `CastOptionsProvider`:

   To enable Chromecast on Android a `CastOptionsProvider` should be specified. This class contains the configuration for Chromecast on Android. A `DefaultCastOptionsProvider` is provided as part of the THEOplayer Android SDK. This `DefaultCastOptionsProvider` associates the default THEOplayer Chromecast receiver application with your Sender application. You will need to register this class in your `AndroidManifest.xml` file within a meta-data tag under your application node, as demonstrated at <https://github.com/THEOplayer/samples-android-sdk/blob/master/Google-Cast/app/src/main/AndroidManifest.xml#L17-L19>.

   ```java
   <meta-data
       android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
       android:value="com.theoplayer.android.api.cast.chromecast.DefaultCastOptionsProvider"/>
   ```

**Optional: Add routing button to your app**

In order to get this button to appear in your application's Toolbar, the easiest way is to include it in the menu XML file for your Activity.

1. In your `res` folder add a menu folder

2. Add an `activity_main_menu.xml` file

3. Add the following contents to this file:

```xml
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    <item
    android:id="@+id/media_route_menu_item"
    android:title="Cast"
    app:actionProviderClass="android.support.v7.app.MediaRouteActionProvider"
    app:showAsAction="always" />
</menu>
```

4. Initialize this new `MenuItem` in the `onCreateOptionsMenu` method of your Activity. (Make sure you have an `AppCompatActivity`).

```java
@Override
public boolean onCreateOptionsMenu(Menu menu) {
    super.onCreateOptionsMenu(menu);
    getMenuInflater().inflate(R.menu.activity_main_menu, menu);
    CastButtonFactory.setUpMediaRouteButton(getApplicationContext(), menu, R.id.media_route_menu_item);
    return true;
}
```

**Optional: Add MiniController to your app**

In your main activity xml add the following fragment:

```java
<fragment
    android:id="@+id/castMiniController"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_alignParentBottom="true"
    android:visibility="gone"
    class="com.google.android.gms.cast.framework.media.widget.MiniControllerFragment" />
```

**Optional: Set a `CastStrategy` to your THEOplayerConfig**

THEOplayer Android SDK support Chromecast CastStrategy to define the joining behavior.

```java
new THEOplayerConfig.Builder()
    .castStrategy(CastStrategy.AUTO)
    .build();
```

### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

In order to enable Chromecast on the iOS SDK:

1. Use a version of THEOplayer’s iOS SDK ≥ 1.0.3

2. Set up the Cast Framework:

   **iOS 14 Warning:** Changes to iOS 14 local network access permissions have impacted the Google Cast iOS SDK in a number of ways. Please see the [iOS 14 Changes](https://developers.google.com/cast/docs/ios_sender/permissions_and_discovery#ios_14) document to see how your app is affected.

   THEOplayer iOS SDK version 2.85.0 upgrades Google Cast SDK to 4.6.0 which contains the iOS 14 specific changes from Google.

   **iOS 13 Warning:** Apple permissions changes to iOS 13 and Xcode 11 have impacted the Google Cast iOS SDK in a number of ways. Please see the [iOS 13 Changes](https://developers.google.com/cast/docs/ios_sender/ios13_changes) document to see how your app will be impacted.

   **iOS 12 Warning:** If developing using Xcode 10 and targeting iOS devices running iOS 12 or higher, the "Access Wi-Fi Information" capability is required in order to discover and connect to Cast devices.

   <https://developers.google.com/cast/docs/ios_sender_setup>

   **Static vs Dynamic Framework:** Because the THEOplayer iOS SDK is a Dynamic Framework, it should not include any dependency frameworks on which it relies (e.g. the Chromecast SDK). Instead, developers should include the dependencies on which THEOplayer relies. Therefore, using a Dynamic Framework ensures that there are no symbol clashes. More info can be found in this article: <https://medium.com/onfido-tech/reusing-code-and-resources-with-swift-static-libraries-and-resource-bundles-d070e82d3b3d>

   **CocoaPods setup**

   Supported until version '4.3.0', pending further investigation for versions above '4.3.0'.

   ```swift
   # Comment the next line if you are not using Swift and do not want to use dynamic frameworks
   use_frameworks!

   # Uncomment the next line to define a global platform for your project
   # platform :ios, '9.0'

   def target_pods
     pod 'google-cast-sdk'
   end

   target'YourProjectTarget' do
       # Select one of the chromecast versions
       pod 'google-cast-sdk', '4.3.0'
   end
   ```

   **Manual setup**

   Download the Dynamic Cast Framework from the [google developer website](https://developers.google.com/cast/docs/ios_sender/). Libraries without [guest mode](https://developers.google.com/cast/docs/guest_mode) have been provided for situations where your app does not require the feature or you do not wish to require Bluetooth® permissions, which have been introduced in iOS 13. Please see the [iOS 13 Changes](https://developers.google.com/cast/docs/ios_sender/ios13_changes) document for more information.

3. Set GCKCastContext

   To enable Chromecast on iOS the `GCKCastContext` shared instance should be set with a `GCKCastOptions`.

   ```swift
   let options = GCKCastOptions(receiverApplicationID: "A1B2C3D4")
   GCKCastContext.setSharedInstanceWith(options)
   ```

   or use the default THEOplayer cast options.

   ```swift
   THEOplayerCastHelper.setGCKCastContextSharedInstanceWithDefaultCastOptions()
   ```

   That's it. When Chromecast-enabled devices are discovered, the player will display a Chromecast button. The player also works nicely together with the Chromecast controls that are part of the Chromecast Framework, (e.g. [GCKUICastButton](https://developers.google.com/cast/docs/ios_sender_integrate#add_a_cast_button) or [the mini controller](https://developers.google.com/cast/docs/ios_sender_integrate#add_mini_controllers)).

## Connect with custom Chromecast Receiver application

The THEOplayer SDK on your Sender application connects with THEO Chromecast Receiver application by default, but you can connect it to a custom Chromecast Receiver application instead.

### Web SDK

If you have your own Receiver app, then you adjust the [PlayerConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/CastConfiguration) to connect with a specific `appID` as demonstrated below.

```javascript
let customChromecastReceiverAppID = '8E80B9CE';
let player = new THEOplayer.Player(element, {
  libraryLocation: '...',
  license: '...',
  cast: {
    chromecast: {
      appID: customChromecastReceiverAppID,
    },
  },
});
```

### Android SDK

To connect with a custom Chromecast Receiver application, you can create your own `CastOptionsProvider` by subclassing `com.google.android.gms.cast.framework.OptionsProvider` and implementing the `getCastOptions` method. This approach is further demonstrated at <https://github.com/THEOplayer/samples-android-sdk/tree/master/Google-Cast/guides/howto-google-cast-integration#initializing-cast-context>, and in the snippet below.

```java
@Override
public CastOptions getCastOptions(Context context) {
    return new CastOptions.Builder()
        .setReceiverApplicationId(DEFAULT_APP_ID)
        .build();
}
```

### Legacy iOS/tvOS SDK (4.12.x)

By default, THEOplayer’s Receiver app will be set when you set `THEOplayerCastHelper.setGCKCastContextSharedInstanceWithDefaultCastOptions()`.

You can connect with a custom Receiver app by configuring its ID through `GCKCastContext.setSharedInstanceWith(GCKCastOptions(receiverApplicationID: "A1B2C3D4"))`.

This approach is further demonstrated at <https://github.com/THEOplayer/samples-ios-sdk/tree/master/Google-Cast/Guides/howto-google-cast-integration#gckcastcontext>.

---

# Introduction

[AirPlay](https://www.apple.com/airplay/) is a casting technology developed by Apple. AirPlay allows viewers to mirror their videos between AirPlay-enabled sender and receiver devices.

* iPhones, iPads and MacBooks are possible AirPlay-enabled sender devices.
* Apple TVs or AirPlay–enabled smart TVs are possible AirPlay-enabled receiver devices.

THEOplayer offers support for AirPlay on AirPlay-enabled devices through its Web SDK and iOS SDK.

## How to enable AirPlay

AirPlay is a THEOplayer feature. Ensure that the `airplay` feature is enabled when you build a THEOplayer SDK through the [THEOplayer Developer Platform](https://portal.theoplayer.com/), as demonstrated by the screenshot below. Alternative, when someone shares the THEOplayer SDK with you, confirm that they enabled the `airplay` feature.

![Enable Airplay](/pr-932/assets/images/portal-airplay-enabled-1f34336e6078b5eff14cdbfcd3695480.png)

If the `airplay` feature is enabled, the default THEOplayer UI should render the AirPlay icon in the control bar, as demonstrated by the screenshot below. Viewers can click this AirPlay icon and select an AirPlay receiver device to initiate (and stop) the AirPlay session.

Ensure that an AirPlay-enabled receiver device is connected to your network, because you might not see an AirPlay icon otherwise. Additionally, note that AirPlay is only supported by Apple on a limited set of devices and browsers. For example, you cannot do AirPlay on a Chrome browser on a macOS device, even though it's an Apple device.

![AirPlay demo](/pr-932/assets/images/airplay-demo-theoplayer-b38aaa6ad2b2495f333a4316151d5ac4.png)

If you have a custom ([Chromeless](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md)) THEOplayer UI, you need to build your own AirPlay UI and UX. You can use the THEOplayer AirPlay API to help achieve this, as discussed in the next section.

## API

As a developer, you might need to use the THEOplayer AirPlay API to build a custom AirPlay UI and UX, or to dispatch an event to an analytics service, or for workflow purposes.

The AirPlay interface is a sub-interface of the Cast interface on both the THEOplayer Web and iOS SDK.

The API reference is available through the following links:

* Web SDK: [AirPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AirPlay), which inherits from [VendorCast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VendorCast)
* iOS SDK: [AirPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/AirPlay)

For the **THEOplayer Web SDK**, you could use the API as demonstrated below:

```javascript
// const player = new THEOplayer.Player(...)
const airPlayState = player.cast.airplay.state;
const isCasting = player.cast.airlay.casting; // true or false
// ...
// if (want to start AirPlay)
player.cast.airplay.start();
// ...
// if (want to stop AirPlay)
player.cast.airplay.stop();
// ...
if (airPlayState == 'available') {
  // airplay is possible
  player.cast.airplay.addEventListener('statechange', function (event) {
    switch (event.state) {
      case 'available':
        // show AirPlay available icon
        break;
      case 'connected':
        // show AirPlay connected icon
        break;
    }
  });
}
```

Note that the `connected` and `available` state are the only two states offered for AirPlay, because Safari only exposes limited information.

For the **THEOplayer iOS SDK**, you could use the API as demonstrated below:

```swift
private func setupTheoplayer() {
    // player = THEOplayer(...)
    let airPlayState = theoplayer.cast?.airPlay?.state
    let isCasting = theoplayer.cast?.airPlay?.casting
    // ...
    // if (want to start AirPlay)
        theoplayer.cast?.airPlay?.start()
    // if (want to stop AirPlay)
        theoplayer.cast?.airPlay?.stop()
    // ...
    theoplayer.cast?.airPlay?.addEventListener(type: AirPlayEventTypes.STATE_CHANGE, listener: onStateChange)
}

private func onStateChange(event: AirPlayStateChangeEvent) {
    if (event.state == PlayerCastState.available) {
        // show AirPlay available icon
    } else if (event.state == PlayerCastState.connected) {
        // show AirPlay connected icon
    }
    print(event.state)
    print(self.player.cast?.airPlay?.casting)
}
```

## Remarks

* [Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/introduction.md) and AirPlay are comparable technologies.

---

# Introduction

THEOplayer supports FairPlay, PlayReady and Widevine by default. To connect to such a DRM system, developers can use a [ContentProtectionDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SourceDescription) (or DRMConfiguration, depending on the SDK). However, more often than not, developers are working with a multi-DRM vendor. These vendors take care of their DRM needs. The last challenge for developers is to integrate the provided DRM solution in a video player. THEOplayer is partnered with many multi-DRM vendors to lighten this burden. In our partnerships, we validate the compatibly and often provide integrations.

## Pre-integrations

THEOplayer is pre-integrated with a number of commercial multi-DRM vendors.

* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/arris-titanium.md)
* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/axinom.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/buydrm-keyos/introduction.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/castlabs-drmtoday/introduction.md)
* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/comcast.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/nagra-conax-contego.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/uplynk.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/verimatrix-multirights.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vimond.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vualto-vudrm.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/xstream.md)
* [How to play a Clear Key protected stream in THEOplayer?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/how-to-play-clear-key-protected-stream.md)
* [How to do offline DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/how-to-do-offline-drm/introduction.md)

## Custom configuration

Developers can use the generic DRM-functionalities in case in-house DRM-solutions are used, or services from DRM-vendors are used which haven't been pre-integrated by THEOplayer.

##### Web SDK

To configure DRM on the Web SDK, developers can put a [ContentProtectionDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SourceDescription#sources) inside of a [SourceDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SourceDescription).

```js
if (HLS) {
  let drmConfiguration = {
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: 'CERTIFICATE_URL>',
      // "certificate": "<CERTIFICATE_AS_STRING_OR_UInt8Array>",
      // "headers": {"<KEY>": "<VALUE>"},
      // "useCredentials": <true||false>
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (MPEG - DASH) {
  let drmConfiguration = {
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
      // "headers": {"<KEY>": "<VALUE>"},
      // "useCredentials": <true||false>
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
      // "headers": {"<KEY>": "<VALUE>"},
      // "useCredentials": <true||false>
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

To configure DRM on the Android SDK, developers can put a DRMConfiguration inside a SourceDescription.

```java
// Map<String, String> headers =  new HashMap<String, String>();
// headers.put("<KEY>", "<VALUE>");
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration.Builder(
            "<LICENSE_KEY_URL_WIDEVINE>"
            )// , headers, <USE_CREDENTIALS>, <QUERY_PARAMETERS>
            .build()
        )
        .build();
TypedSource typedSource = new TypedSource.Builder("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = new SourceDescription.Builder(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

To configure DRM on the iOS SDK, developers can put a FairPlayDRMConfiguration inside a SourceDescription.

```swift
// let headers = [["<KEY>": "<VALUE>"]]
let drmConfiguration = FairPlayDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>"
        // , headers: headers, licenseType: <LICENSE_TYPE>
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

##### Roku SDK

In order to play DRM protected resources, you will need to pass extra DRM parameters. To see what kind of DRM protection is supported by Roku devices, please visit [this page](https://developer.roku.com/en-gb/docs/specs/media/content-protection.md).

In the following example, there is a function called "setSource", which sets the source of a THEOplayer instance ("m.player.source").

It is worth mentioning that "m" works like the "this" keyword from other languages. An "m" keyword points to the current component local namespace. Therefore, in case you want to access a variable across different functions inside the same component, use "m" to do so.

```brightscript
function setSource(streamFormat)
  if streamFormat = "hls" then
    drmParams = {
      "integration": "Widevine",
      "licenseUrl": "<LICENSE_KEY_URL_WIDEVINE>"
    }
    m.player.source = {
      "poster": "pooster.png",
      "sources": [
        {
          "contentProtection": drmParams,
          "src": "<HLS_STREAM_URL>",
          "type": "application/x-mpegURL"
        }
      ]
	}
  end if
  if streamFormat = "dash" then
    drmParams = {
      "integration": "Widevine",
      "licenseUrl": "<LICENSE_KEY_URL_WIDEVINE>"
    }
    m.player.source = {
        "poster": "pooster.png",
        "sources": [
          {
            "contentProtection": drmParams,
            "src": "<DASH_STREAM_URL>",
            "type": "application/dash+xml"
          }
        ]
    }
  end if
end function
```

## Custom Integration

Developers can make their own custom DRM integration instead of using the pre-integrations offered by THEOplayer. This can be done by making use of the [DRM integration API repository](https://github.com/THEOplayer/samples-drm-integration).

A complete guide on how to create a new integration, and some example integrations can be found in the provided repository.

---

# Arris Titanium

This article describes how to configure Arris Titanium DRM with THEOplayer. Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK    | tvOS SDK   | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ---------- | ---------- | -------------- | -------------- |
| Yes     | Yes         | Unverified | Unverified | Yes            | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'titanium',
    accountName: '<ACCOUNT_NAME>',
    customerName: '<CUSTOMER_NAME>',
    friendlyName: '<FRIENDLY_NAME>',
    portalId: '<PORTAL_ID>',
    authToken: '<AXINOM_TOKEN>',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: 'CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'titanium',
    accountName: '<ACCOUNT_NAME>',
    customerName: '<CUSTOMER_NAME>',
    friendlyName: '<FRIENDLY_NAME>',
    portalId: '<PORTAL_ID>',
    authToken: '<AXINOM_TOKEN>',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = TitaniumDRMConfiguration.Builder
    .titaniumDrm("<ACCOUNT_NAME>", ">CUSTOMER_NAME>", "<PORTAL_ID>")
    // .friendlyName("<FRIENDLY_NAME>")
    // .authToken("<AUTH_TOKEN>")
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

Please refer to [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) (custom configuration).

## Connectors

We are developing open-source DRM connectors that can more easily be maintained and to allow for a modular approach. You can find them in [this GitHub repo](https://github.com/THEOplayer/samples-drm-integration), alongside with guides on how to integrate and use them. When integrating DRM for the first time or updating your integration, the connectors are to be preferred over the pre-integrations.

**Web and Android SDKs** There currently is no ready-made connector for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

**iOS SDKs** The Arris Titanium DRM connector can be found [here](https://github.com/THEOplayer/samples-drm-integration/blob/master/ios/ContentProtectionIntegration/integration/ArrisTitaniumDrmIntegration.swift).

## Resources

* <https://www.arris.com/products/titanium-cas/>
* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/castlabs-drmtoday/introduction.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/nagra-conax-contego.md)

---

# Axinom

This article describes how to configure Axinom DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK   | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | ---------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Unverified | Yes            | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'axinom',
    token: '<AXINOM_TOKEN>',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: 'CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'axinom',
    token: '<AXINOM_TOKEN>',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = new AxinomDRMConfiguration.Builder("<AXINOM_TOKEN>")
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
let drmConfiguration = AxinomDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>",
    token: "<AXINOM_TOKEN>"
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Resources

* <https://www.axinom.com/products/drm>

## Related articles

* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/comcast.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/buydrm-keyos/introduction.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vualto-vudrm.md)

---

# Comcast

This article describes how to configure Comcast DRM with THEOplayer. Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK                                   | iOS SDK                                       | tvOS SDK                                      | Android TV SDK                                | Chromecast SDK |
| ------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | -------------- |
| Yes     | Unverified through CSS/JavaScript injection\* | Unverified through CSS/JavaScript injection\* | Unverified through CSS/JavaScript injection\* | Unverified through CSS/JavaScript injection\* | Unverified     |

\*CSS/JavaScript injection in the project is only possible with the legacy mobile SDKs (up to 4.12.X).

## Code examples

##### Web SDK

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'comcast',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: 'CERTIFICATE_URL>',
      token: '<TOKEN>',
      releasePid: '<RELEASEPID>',
      accountId: '<ACCOUNT_ID>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

There currently is no integration available in the Android SDK for this DRM system.

Legacy SDK (4.12.X): The Web SDK code should be included in your Android (TV) project. The article at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios) explains how you can add CSS and JavaScript files to your project. The sample project at [How to insert a button](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-insert-a-button.md) demonstrates this.

##### iOS/tvOS SDK

There currently is no integration available in the iOS SDK for this DRM system.

Legacy SDK (4.12.X): The Web SDK code should be included in your iOS (TV) project. The article at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios) explains how you can add CSS and JavaScript files to your project. The sample project at [How to insert a button](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-insert-a-button.md) demonstrates this.

## Connectors

We are developing open-source DRM connectors that can more easily be maintained and to allow for a modular approach. You can find them in [this GitHub repo](https://github.com/THEOplayer/samples-drm-integration), alongside with guides on how to integrate and use them. When integrating DRM for the first time or updating your integration, the connectors are to be preferred over the pre-integrations.

**Web** The Comcast DRM connector can be found in [this folder](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/comcastdrm).

**Mobile SDKs** Connectors are also the way forward for the current mobile SDKs. There currently is no ready-made connector for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

## Remarks

* Legacy Mobile SDKs (4.12.X): having this work through JavaScript injection has several limitations (e.g.: this will not work with ExoPlayer on Android).

## Resources

* <https://docs.theplatform.com/help/ent-license-web-services-api-reference>
* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/castlabs-drmtoday/introduction.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/nagra-conax-contego.md)

---

# EZDRM

This article describes how to configure [EZDRM](https://www.ezdrm.com/) with THEOplayer. Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK   | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | ---------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Unverified | Yes            | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'ezdrm',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: 'CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'ezdrm',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
let drmConfiguration = EzdrmDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>",
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

### Connectors

We are developing open-source DRM connectors that can more easily be maintained and to allow for a modular approach. You can find them in [this GitHub repo](https://github.com/THEOplayer/samples-drm-integration), alongside with guides on how to integrate and use them. When integrating DRM for the first time or updating your integration, the connectors are to be preferred over the pre-integrations.

**Web** The EZDRM connector can be found in [this folder](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/ezdrm).

**Android SDK** Connectors are also the way forward for the current mobile SDKs. There currently is no ready-made connector for this DRM provider: you can choose to develop one based on the examples in the repository, or get in contact with us about making one.

**iOS SDK** The EZDRM connector can be found in [here](https://github.com/THEOplayer/samples-drm-integration/blob/master/ios/ContentProtectionIntegration/integration/EzdrmDRMIntegration.swift)

## Resources

* <https://www.ezdrm.com/html/documentation.asp>
* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vualto-vudrm.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vimond.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/verimatrix-multirights.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/doverunner.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/nagra-conax-contego.md)

---

# Intertrust ExpressPlay

This article describes how to configure Intertrust ExpressPlay DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK    | tvOS SDK   | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ---------- | ---------- | -------------- | -------------- |
| Yes     | Unverified  | Unverified | Unverified | Unverified     | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'expressplay',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: 'CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'expressplay',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

**Not verified.**

```java
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

**Not verified.**

```swift
// let headers = [["<KEY>": "<VALUE>"]]
let drmConfiguration = FairPlayDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>"
        // , headers: headers, licenseType: <LICENSE_TYPE>
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Resources

* <https://www.verimatrix.com/partners/profile/theoplayer>

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/castlabs-drmtoday/introduction.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/nagra-conax-contego.md)

---

# Irdeto

This article describes how to configure Irdeto DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK   | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | ---------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Unverified | Yes            | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
    let drmConfiguration = {
        "integration": "irdeto",
        "crmId": "<CRM_ID>",
        "accountId": "<ACCOUNT_ID>",
        "contentId": "<CONTENT_ID>",
        "keyId": "<KEY_ID>",
        "applicationId": "<APPLICATION_ID>"
        "fairplay": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_FAIRPLAY>",
            "certificateURL": "CERTIFICATE_URL>"
        }
    };
    player.source = {
        "sources": {
            "src": "<HLS_STREAM_URL>",
            "type": "application/x-mpegurl",
            "contentProtection": drmConfiguration
        }
    }
} else if (DASH) {
    let drmConfiguration = {
        "integration": "irdeto",
        "crmId": "<CRM_ID>",
        "accountId": "<ACCOUNT_ID>",
        "contentId": "<CONTENT_ID>",
        "keyId": "<KEY_ID>",
        "applicationId": "<APPLICATION_ID>",
        "playready": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_PLAYREADY>"
        },
        "widevine": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_WIDEVINE>"
        }
    };
    player.source = {
        "sources": {
            "src": "<DASH_STREAM_URL>",
            "type": "application/dash+xml",
            "contentProtection": drmConfiguration
        }
    }
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = new IrdetoConfiguration("<CRM_ID>", "<ACCOUNT_ID>", "<CONTENT_ID>",
                "<SESSION_ID>", "<TICKET>", new KeySystemConfiguration("<LICENSE_KEY_URL_WIDEVINE"));
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
let drmConfiguration = IrdetoDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>",
    crmId: "<CRM_ID>",
    accountId: "<ACCOUNT_ID>",
    contentId: "<CONTENT_ID>",
    keyId: "<KEY_ID>",
    applicationId: "<APPLICATION_ID>"
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Resources

* <https://irdeto.com/video-entertainment/multi-drm-and-rights-management/>

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/castlabs-drmtoday/introduction.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/nagra-conax-contego.md)

---

# Microsoft Azure

> **Warning**
>
> Azure Media Services has been retired since June 30th, 2024.

This article describes how to configure Microsoft Azure DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information or head to [Azure Media Services 3rd Party Player Samples - THEOplayer](https://github.com/Azure-Samples/media-services-3rdparty-player-samples/tree/master/docs/THEOplayer) for an implementation reference sample.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK   | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | ---------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Unverified | Yes            | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'azure',
    token: 'AZURE_TOKEN>',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: 'CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'azure',
    token: '<AZURE_TOKEN>',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = new AzureDRMConfiguration.Builder("<CERTIFICATE_URL", "<TOKEN>")
    .widevine(
        new KeySystemConfiguration("<LICENSE_KEY_URL_WIDEVINE>")
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
// let headers = [["<KEY>": "<VALUE>"]]
let drmConfiguration = AzureDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>",
    token: "<AZURE_TOKEN>"
    // , headers: headers
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Resources

* <https://azure.microsoft.com/nl-nl/services/media-services/content-protection/>

## Related articles

* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/comcast.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/buydrm-keyos/introduction.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vualto-vudrm.md)
* [Azure Media Services - THEOplayer Implementation Sample](https://github.com/Azure-Samples/media-services-3rdparty-player-samples/tree/master/docs/THEOplayer)

---

# Nagra Conax Contego

This article describes how to configure [Conax](https://dtv.nagra.com/scalable-service-protection) DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK    | tvOS SDK   | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ---------- | ---------- | -------------- | -------------- |
| Yes     | Yes         | Unverified | Unverified | Yes            | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
  if (CLASSIC_MODEL) {
    let drmConfiguration = {
      integration: 'conax',
      token: '<CONAX_TOKEN>',
      deviceId: '<DEVICE_ID>',
      fairplay: {
        licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
        certificateURL: 'CERTIFICATE_URL>',
      },
    };
    player.source = {
      sources: {
        src: '<HLS_STREAM_URL>',
        type: 'application/x-mpegurl',
        contentProtection: drmConfiguration,
      },
    };
  } else if (UPFRONT_MODEL) {
    let drmConfiguration = {
      integration: 'conax',
      fairplay: {
        licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
        certificateURL: 'CERTIFICATE_URL>',
      },
      headers: {
        PreAuthorization: '<CONAX_PREAUTHORIZATION_TOKEN>',
      },
    };
    player.source = {
      sources: {
        src: '<HLS_STREAM_URL>',
        type: 'application/x-mpegurl',
        contentProtection: drmConfiguration,
      },
    };
  } else {
    // player throws an Invalid Conax configuration error
  }
} else if (DASH) {
  let drmConfiguration = {
    integration: 'conax',
    token: '<CONAX_TOKEN>',
    deviceId: '<DEVICE_ID>',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = ConaxDRMConfiguration.Builder.conaxDrm("<DEVICE_ID>", "<CONAX_TOKEN>")
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/castlabs-drmtoday/introduction.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/microsoft-azure.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/uplynk.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/verimatrix-multirights.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vimond.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vualto-vudrm.md)

---

# Verimatrix MultiRights

This article describes how to configure Verimatrix MultiRights with THEOplayer. [MultiRights](https://www.verimatrix.com/solutions/multirights-ott) is a multi-DRM solution by [Verimatrix](https://www.verimatrix.com/). Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK   | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | ---------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Unverified | Yes            | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'verimatrix',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: 'CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'verimatrix',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
let drmConfiguration = VerimatrixDRMConfiguration(
        licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
        certificateURL: "<CERTIFICATE_URL>"
    )
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Connectors

We are developing open-source DRM connectors that can more easily be maintained and to allow for a modular approach. You can find them in [this GitHub repo](https://github.com/THEOplayer/samples-drm-integration), alongside with guides on how to integrate and use them. When integrating DRM for the first time or updating your integration, the connectors are to be preferred over the pre-integrations.

**Web** The Verimatrix DRM connector can be found in [this folder](https://github.com/THEOplayer/samples-drm-integration/tree/master/web/src/integration/verimatrixcoredrm).

**Android** The Verimatrix DRM connector can be found in [this folder](https://github.com/THEOplayer/samples-drm-integration/tree/master/android/app/src/main/java/com/theoplayer/contentprotectionintegration/integration/verimatrixcoredrm).

**iOS** The Verimatrix DRM connector can be found [here](https://github.com/THEOplayer/samples-drm-integration/blob/master/ios/ContentProtectionIntegration/integration/VerimatrixCoreDRMIntegration.swift).

## Resources

* [THEOplayer GitHub Samples DRM Integration repository](https://github.com/THEOplayer/samples-drm-integration)

## Related articles

* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/comcast.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/buydrm-keyos/introduction.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vualto-vudrm.md)

---

# Vimond

This article describes how to configure Vimond DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK   | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | ---------- | -------------- | -------------- |
| Yes     | Unverified  | Yes     | Unverified | Yes            | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'vimond',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: 'CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'vimond',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
// let headers = [["<KEY>": "<VALUE>"]]
let drmConfiguration = VimondDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>",
    // , headers
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Resources

* <https://vimond.com/products>

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/castlabs-drmtoday/introduction.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/nagra-conax-contego.md)

---

# Vualto VuDRM

This article describes how to configure Vualto VuDRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK   | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | ---------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Unverified | Yes            | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
    let drmConfiguration = {
        "integration": "vudrm",
        "token": "<TOKEN>",
        "fairplay": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_FAIRPLAY>",
            "certificateURL": "CERTIFICATE_URL>"
        }
    };
    player.source = {
        "sources": {
            "src": "<HLS_STREAM_URL>",
            "type": "application/x-mpegurl",
            "contentProtection": drmConfiguration
        }
    }
} else if (DASH) {
    let drmConfiguration = {
        "integration": "vudrm",
        "token": "<TOKEN>"
        "playready": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_PLAYREADY>"
        },
        "widevine": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_WIDEVINE>"
        }
    };
    player.source = {
        "sources": {
            "src": "<DASH_STREAM_URL>",
            "type": "application/dash+xml",
            "contentProtection": drmConfiguration
        }
    }
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = new VudrmDRMConfiguration("<TOKEN>", null,
                new KeySystemConfiguration("<LICENSE_KEY_URL>"));
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
// let headers = [["<KEY>": "<VALUE>"]]
let drmConfiguration = VudrmDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>",
    token: "<TOKEN>"
    //, headers: headers
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Resources

* <https://www.vualto.com/products/vudrm-drm/>
* <https://github.com/Vualto/vuplay-theoplayer>

## Related articles

* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/comcast.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/buydrm-keyos/introduction.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vualto-vudrm.md)

---

# Uplynk

**Important:** Uplynk customers should configure DRM through the [THEOplayer Uplynk integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/preplay.md). More specifically, to configure DRM, developers should use the [`contentProtected`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/preplay.md) flag. (The Uplynk integration provides a pre-integration with Uplynk's Preplay, Ping and Asset Info services, exposes additional APIs, and enhances your UI and UX.)

This article describes how to configure Uplynk DRM with THEOplayer **if** you are not interested in using the aforementioned Uplynk integration.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'uplynk',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: 'CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'uplynk',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>"
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
// let headers = [["<KEY>": "<VALUE>"]]
let drmConfiguration = UplynkDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>",
    // , headers
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Resources

* [Content Protection (Uplynk)](https://docs.uplynk.com/docs/content-protection)

## Related articles

* [Axinom](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/axinom.md)
* [castLabs DRMToday](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/castlabs-drmtoday/introduction.md)
* [EZDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/ezdrm.md)
* [Intertrust ExpressPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/intertrust-expressplay.md)
* [Irdeto](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/irdeto.md)
* [Microsoft Azure](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/microsoft-azure.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/nagra-conax-contego.md)

---

# Xstream

This article describes how to configure Xstream DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK   | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | ---------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Unverified | Yes            | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'xstream',
    streamId: '<STREAM_ID>',
    ticketAcquisitionURL: '<TICKET_ACQUISITION_URL>',
    /*"fairplay": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_FAIRPLAY>",
            "certificateURL": "CERTIFICATE_URL>"
        }*/
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'xstream',
    streamId: '<STREAM_ID>',
    ticketAcquisitionURL: '<TICKET_ACQUISITION_URL>',
    /*"playready": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_PLAYREADY>"
        },
        "widevine": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_WIDEVINE>"
        }*/
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = new XstreamConfiguration.Builder("<STREAM_ID>", "<TICKET_ACQUISITION_URL>")
    .widevine(
        KeySystemConfiguration.Builder.keySystemConfiguration("LA_URL").build()
    )
    .build()
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
let drmConfiguration = XstreamDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>",
    streamId: "<STREAM_ID>",
    ticketAcquisitionURL: "<TICKET_ACQUISITION_URL>"
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Related articles

* [Comcast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/comcast.md)
* [DoveRunner](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/doverunner.md)
* [BuyDRM KeyOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/buydrm-keyos/introduction.md)
* [Arris Titanium](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/arris-titanium.md)
* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vualto-vudrm.md)

---

# How to play a Clear-Key-protected stream in THEOplayer?

This article provides a simple example of how to use Clear Key with THEOplayer.

Usually, DRM systems require you to specify a `licenseAcquisitionURL` and additional optional data (e.g.: certificate, credentials, headers). Clear Key does not need a DRM provider. You can provide the key(s) directly to the player (hence "clear" key) through the `keys` property in its `LicenseAcquisitionDescription` (in fact, this property is only available for Clear Key). Alternatively, you can have the player fetch the keys from a `licenseAcquisitionURL`, which returns a JSON object containing the same keys.

Please check also our related [API documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SourceDescription) on how to set these.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |

## How to use Clear Key

Below you can find examples on how the clear key source descriptions look like on Web and Android SDKs:

##### Web SDK

With keys:

```js
player.source = {
  sources: {
    src: 'your-manifest-URL',
    useCredentials: false,
    contentProtection: {
      clearkey: {
        keys: [
          {
            id: 'id',
            value: 'value',
          },
        ],
      },
    },
  },
};
```

With a license URL:

```js
player.source = {
  sources: {
    src: 'https://storage.googleapis.com/shaka-demo-assets/angel-one-clearkey/dash.mpd',
    useCredentials: false,
    contentProtection: {
      clearkey: {
        licenseAcquisitionURL: 'https://cwip-shaka-proxy.appspot.com/clearkey?_u3wDe7erb7v8Lqt8A3QDQ=ABEiM0RVZneImaq7zN3u_w',
      },
    },
  },
};
```

##### Android SDK

```java
SourceDescription.Builder clearKey = new SourceDescription.Builder(
        new TypedSource.Builder("https://storage.googleapis.com/shaka-demo-assets/angel-one-clearkey/dash.mpd")
                .drm(
                        new DRMConfiguration.Builder()
                                .clearkey(
                                        new ClearkeyKeySystemConfiguration.Builder("https://cwip-shaka-proxy.appspot.com/clearkey?_u3wDe7erb7v8Lqt8A3QDQ=ABEiM0RVZneImaq7zN3u_w")
                                                .useCredentials(false)
                                                .build()
                                )
                                .build()
                )
                .build()
);

tpv.getPlayer().setSource(clearKey.build());
```

## Resources

* [API Reference - ClearkeyDecryptionKey](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/ClearkeyDecryptionKey)
* [Generate MPEG DASH content encrypted with MPEG CENC ClearKey](https://github.com/Dash-Industry-Forum/dash.js/wiki/Generate-MPEG-DASH-content-encrypted-with-MPEG-CENC-ClearKey): DASH IF on GitHub
* [Clear Key license format](https://w3c.github.io/encrypted-media/#clear-key-license-format): W3C - Encrypted Media Extensions

---

# DoveRunner

This article describes how to configure [DoveRunner Multi-DRM](https://doverunner.com/docs/content-security/multi-drm/) with THEOplayer. This content is based on DoveRunner's documentation.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

**Note**: The details in the guide apply for DoveRunner (formerly known as "PallyCon"). While most details, API hostnames and variables have been updated to reflect DoveRunner, certain configurations such as the `pallycon-customdata-v2` HTTP request header will still apply.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Unverified     |

## Code Examples

##### Web SDK

```js
if (HLS) {
    const certificateUrl = "<CERTIFICATE_URL>";

    // a response interceptor for the certificate URL might be required.
    player.network.addResponseInterceptor(function(response) {
        if(response.url == certificateUrl) {
            const rawResponse = response.body;
            const responseText = String.fromCharCode.apply(null, new Uint8Array(rawResponse));
            const raw = window.atob(responseText);
            const rawLength = raw.length;
            let certificate = new Uint8Array(new ArrayBuffer(rawLength));

            for(let i = 0; i < rawLength; i++)
                certificate[i] = raw.charCodeAt(i);
            response.respondWith({body: certificate})
        }
    });

    const drmConfiguration = {
        "fairplay": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_FAIRPLAY>",
            "certificateURL": certificateUrl,
            "headers": {
                "<CUSTOM_HEADER_NAME>" : "<CUSTOM_HEADER_VALUE>" // e.g. 'pallycon-customdata-v2': 'eyJkYXRhIjoibWJLV1NjSUNIU25WMjZQWFB4cGlDQUJVbnZsOGxCOWRNZDhHZ3dhbjZqRDFwNFZoQk51VlhQY2RMaG9nNTNYbngyTjFaalwvQ3BxZ3RUS2k5Rzd3MUZ3PT0iLCJzaXRlX2lkIjoiREVNTyIsImRybV90eXBlIjoiUGxheVJlYWR5In0='
            }
        }
    };
    player.source = {
        "sources": {
            "src": "<HLS_STREAM_URL>",
            "type": "application/x-mpegurl",
            "contentProtection": drmConfiguration
        }
    }
} else if (DASH) {
    const drmConfiguration = {
        "playready": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_PLAYREADY>",
            "headers": {
                "<CUSTOM_HEADER_NAME>" : "<CUSTOM_HEADER_VALUE>"
            }
        },
        "widevine": {
            "licenseAcquisitionURL": "<LICENSE_KEY_URL_WIDEVINE>",
            "headers": {
                "<CUSTOM_HEADER_NAME>" : "<CUSTOM_HEADER_VALUE>"
            }
        }
    };
    player.source = {
        "sources": {
            "src": "<DASH_STREAM_URL>",
            "type": "application/dash+xml",
            "contentProtection": drmConfiguration
        }
    }
}"
```

##### Android SDK

```java
// Map<String, String> headers =  new HashMap<String, String>();
// headers.put("<CUSTOM_HEADER_NAME>", "<CUSTOM_HEADER_VALUE>"); // e.g. "pallycon-customdata-v2", "eyJkYXRhIjoibWJLV1NjSUNIU25WMjZQWFB4cGlDQUJVbnZsOGxCOWRNZDhHZ3dhbjZqRDFwNFZoQk51VlhQY2RMaG9nNTNYbngyTjFaalwvQ3BxZ3RUS2k5Rzd3MUZ3PT0iLCJzaXRlX2lkIjoiREVNTyIsImRybV90eXBlIjoiUGxheVJlYWR5In0="
DRMConfiguration drmConfiguration = new DRMConfiguration.Builder()
    .widevine(
        new KeySystemConfiguration(
            "<LICENSE_KEY_URL_WIDEVINE>", headers, false, null
        )
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

```swift
let drmConfiguration = FairPlayDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>",
    headers: [["<CUSTOM_HEADER_NAME>": "<CUSTOM_HEADER_VALUE>"]] // e.g. "pallycon-customdata-v2": "eyJkYXRhIjoibWJLV1NjSUNIU25WMjZQWFB4cGlDQUJVbnZsOGxCOWRNZDhHZ3dhbjZqRDFwNFZoQk51VlhQY2RMaG9nNTNYbngyTjFaalwvQ3BxZ3RUS2k5Rzd3MUZ3PT0iLCJzaXRlX2lkIjoiREVNTyIsImRybV90eXBlIjoiUGxheVJlYWR5In0="
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Resources

* <https://doverunner.com/docs/content-security/multi-drm/>
* <https://doverunner.com/docs/content-security/multi-drm/clients/html5-player/>
* <https://doverunner.com/docs/content-security/multi-drm/clients/widevine-android/>
* <https://doverunner.com/docs/content-security/multi-drm/clients/fairplay-ios/>

## Related Articles

* [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/uplynk.md)
* [Xstream](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/xstream.md)
* [Vualto VuDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vualto-vudrm.md)
* [Vimond](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/vimond.md)
* [Verimatrix MultiRights](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/verimatrix-multirights.md)
* [Nagra Conax Contego](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/nagra-conax-contego.md)

---

# Multi-key HLS

There are multiple DRM key systems on the market to choose from. The most popular ones are Google Widevine, Microsoft PlayReady and Apple FairPlay. Under the hood, all these systems encrypt the media samples using the AES-128 encryption algorithm. AES-128 is a standardized block-cipher that allows for multiple ways of choosing the blocks. Widevine and PlayReady both use `CTR` and FairPlay uses `CBC`. Therefore, it was possible to share segments between Widevine and PlayReady protected streams, but not with FairPlay protected stream. However, support has been added for Widevine and PlayReady with AES-128 in `CBC` mode. Hence, it is now possible to create HLS streams compatible with all these key systems. Where you previously had to encode the stream twice, this is no longer needed. A multi-key HLS stream will play in all web platforms that support MSE and either Widevine, PlayReady or FairPlay.

## The HLS playlist

A multi-key HLS playlist could look like this:

```text
#EXTM3U
#EXT-X-TARGETDURATION:6
#EXT-X-VERSION:5
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-KEY:METHOD=SAMPLE-AES,KEYFORMAT="urn:uuid:edef8ba9-79d6-4ace-a3c8-27dcd51d21ed",KEYFORMATVERSIONS="1",URI="WIDEVINE_INIT_DATA_URL"
#EXT-X-KEY:METHOD=SAMPLE-AES,KEYFORMAT="com.microsoft.playready",KEYFORMATVERSIONS="1",URI="PLAYREADY_INIT_DATA_URL"
#EXT-X-KEY:METHOD=SAMPLE-AES,KEYFORMAT="com.apple.streamingkeydelivery",KEYFORMATVERSIONS="1",URI="FAIRPLAY_INIT_DATA_URL"
#EXT-X-MAP:URI="init.mp4"
#EXTINF:6,
1.mp4
#EXTINF:6,
2.mp4
#EXTINF:6,
3.mp4
#EXTINF:6,
4.mp4
#EXTINF:6,
5.mp4
#EXT-X-ENDLIST
```

There is an `#EXT-X-KEY` tag for all the key systems which all have method `SAMPLE-AES`. The `KEYFORMAT` specifies the key system:

* `urn:uuid:edef8ba9-79d6-4ace-a3c8-27dcd51d21ed` for Widevine
* `com.microsoft.playready` for PlayReady
* `com.apple.streamingkeydelivery` for FairPlay

The `URI` is either a data URI containing the initialization data, or a URI pointing to the initialization data. For more information, please check out the specifications for [Widevine](https://www.academia.edu/36030972/Widevine_DRM_for_HLS), [PlayReady](https://docs.microsoft.com/en-us/playready/packaging/mp4-based-formats-supported-by-playready-clients?tabs=case4) and [FairPlay](https://developer.apple.com/streaming/fps/).

## Configuring THEOplayer

A corresponding player configuration looks like:

```javascript
player.source = {
  sources: [
    {
      src: 'https://yourdomain.com/playlist.m3u8',
      type: 'application/x-mpegurl',
      contentProtection: {
        widevine: {
          licenseAcquisitionURL: 'https://widevine-server.com/license',
        },
        playready: {
          licenseAcquisitionURL: 'https://playready-server.com/license',
        },
        fairplay: {
          certificateURL: 'https://fairplay-server.com/certificate',
          licenseAcquisitionURL: 'https://fairplay-server.com/license',
        },
      },
    },
  ],
};
```

Note that this feature is available on the current HLS pipeline (default since THEOplayer 4.X). To use it in previous versions, the `lowLatency` flag must be set to true.

---

# Introduction

This article describes how to configure BuyDRM KeyOS DRM with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |

## Code Examples

##### Web SDK

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'keyos',
    customdata: '<CUSTOMDATA>',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: 'CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'keyos',
    customdata: '<CUSTOMDATA>',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = KeyOSDRMConfiguration.Builder
    .keyOsDrm()
    .widevine(
        new KeyOSKeySystemConfiguration("<CUSTOM_DATA>", "<LICENSE_KEY_URL_WIDEVINE>")
    )
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
public static var buyDRMkeyOS: SourceDescription {
    let licenseAcquisitionURL: String = "<LICENSE_KEY_URL_FAIRPLAY>"
    let certificateURL: String = "<CERTIFICATE_URL_FAIRPLAY>"
    let token: String = "<TOKEN_FAIRPLAY>"
    let type: String = "application/x-mpegURL"
    let src = "<HLS_STREAM_URL>"
    let drm: KeyOSDRMConfiguration = KeyOSDRMConfiguration(licenseAcquisitionURL: licenseAcquisitionURL, certificateURL: certificateURL, customdata: token)
    let typedSource: TypedSource = TypedSource(src: src, type: type, drm: drm)
    let source: SourceDescription = SourceDescription(source: typedSource)
    return source
}
```

## Resources

* <https://test.buydrm.com/sites/default/files/pdf/webinar/050217_DeployingKeyOSMulti-DRM_withTHEOPLayer_Webinar.pdf>
* [How to use THEOplayer with KeyOS BuyDRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/buydrm-keyos/how-to-use-with-theoplayer.md)

---

# How to use THEOplayer with KeyOS BuyDRM

This guide explains how you set up THEOplayer in combination with the [KeyOS BuyDRM](https://www.buydrm.com/keyosplayer), a partnered **multi-DRM vendor**. THEOplayer is pre-integrated with KeyOS and provides a user-friendly API to connect to their **Widevine** and **PlayReady** DRM solutions.

If you are already comfortable with the THEOplayer API, you can go straight over to [DRM Pre-Integration API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/DRMConfiguration).

## Prerequisites

This guide expects you to:

1. Have a THEOplayer license. If you aren't using THEOplayer yet, you can start your free trial [here](https://portal.theoplayer.com).

2. Be a client of KeyOS's BuyDRM, and that you are integrated with their streaming infrastructure. Information on BuyDRM can be found at <https://buydrm.com/multikey-demo/>.

If you can place a checkmark next to these two fields, you are good to go.

You will also need a valid THEOplayer set-up. If you have no experience with setting up our player, we have an excellent [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md).

## Integrating KeyOS BuyDRM

Starting from the basic template above, you only need to add your BuyDRM token (=**customdata**) to your source configuration, and tell THEOplayer that you are using KeyOS.

##### Web SDK

```js
player.source = {
  sources: {
    src: 'your.mpd',
    type: 'application/dash+xml',
    drm: {
      integration: 'keyos',
      customdata: 'PEtleU9T...blhNTD4=',
      playready: {
        licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
      },
      widevine: {
        licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
      },
    },
  },
};
```

Your updated starting template would now look like this:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Web SDK: Getting Started</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="/path/to/ui.css" />
    <!-- adds THEOplayer CSS -->
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>

    <script type="text/javascript" src="/path/to/THEOplayer.js"></script>
    <!-- adds THEOplayer library -->

    <script>
      var element = document.querySelector('.theoplayer-container');
      var player = new THEOplayer.Player(element, {
        license: 'your_license_string',
        //...
      });

      player.source = {
        sources: [
          {
            src: 'your.mpd',
            type: 'application/dash+xml',
            drm: {
              integration: 'keyos',
              customdata: 'PEtleU9T...blhNTD4=',
              playready: {
                licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
              },
              widevine: {
                licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
              },
            },
          },
        ],
      };
    </script>
  </body>
</html>
```

##### Legacy iOS/tvOS SDK (4.12.x)

A KeyOS DRM integration is added to the source configuration by adding the keyOsDrm() parameter to drm as such:

```swift
public static var buyDRMkeyOS: SourceDescription {
    let licenseAcquisitionURL: String = "<LICENSE_KEY_URL_FAIRPLAY>"
    let certificateURL: String = "<CERTIFICATE_URL_FAIRPLAY>"
    let token: String = "<TOKEN_FAIRPLAY>"
    let type: String = "application/x-mpegURL"
    let src = "<HLS_STREAM_URL>"
    let drm: KeyOSDRMConfiguration = KeyOSDRMConfiguration(licenseAcquisitionURL: licenseAcquisitionURL, certificateURL: certificateURL, customdata: token)
    let typedSource: TypedSource = TypedSource(src: src, type: type, drm: drm)
    let source: SourceDescription = SourceDescription(source: typedSource)
    return source
}

// Configure the player's source to initilaise playback
        THEOplayer.source = buyDRMkeyOS
```

Where `token` for customdata is the Authentication XML generated from their platform.

##### Android SDK

A KeyOS DRM integration is added to the source configuration by adding the keyOsDrm() parameter to DRM as such:

```java
SourceDescription dashWithDRM = sourceDescription()
        .sources(
            typedSource("//sourceUrl")
                .drm(
                        keyOsDrm()
                            .customdata("//token")
                            .playready("//playReadyKeyServer")
                            .widevine("//widevineKeyServer")
                            .build()
                ).build()
        ).build();
```

Where: `token` for customdata is the Authentication XML generated from their platform.

## Conclusion

THEOplayer partnered with KeyOS to fully pre-integrate their BuyDRM solution, saving you tons of time. This pre-integration brings along multiple advantages:

* It's very simple to set up KeyOS BuyDRM through THEOplayer.
* No surprises - you know that we are compatible with each other. We also regularly validate our integration, and are the first to know about changes to KeyOS.
* It offers extra maintainability. Even if the KeyOS infrastructure changes, we attempt to be backwards compatible.

## Extra resources:

1. [DRM Pre-Integration API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/DRMConfiguration)

2. [THEOplayer Getting Started Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)

3. [KeyOS BuyDRM](https://www.buydrm.com/keyosplayer)

---

# Introduction

This article describes how to configure castLabs DRMToday with THEOplayer.

Head to our page on [DRM](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/drm/introduction.md) for more general information.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |

## Code examples

##### Web SDK

```js
if (HLS) {
  let drmConfiguration = {
    integration: 'drmtoday',
    merchant: '<MERCHANT>',
    sessionId: '<SESSION_ID>',
    token: '<TOKEN>',
    userId: '<USER_ID>',
    fairplay: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_FAIRPLAY>',
      certificateURL: 'CERTIFICATE_URL>',
    },
  };
  player.source = {
    sources: {
      src: '<HLS_STREAM_URL>',
      type: 'application/x-mpegurl',
      contentProtection: drmConfiguration,
    },
  };
} else if (DASH) {
  let drmConfiguration = {
    integration: 'drmtoday',
    merchant: '<MERCHANT>',
    sessionId: '<SESSION_ID>',
    token: '<TOKEN>',
    userId: '<USER_ID>',
    playready: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_PLAYREADY>',
    },
    widevine: {
      licenseAcquisitionURL: '<LICENSE_KEY_URL_WIDEVINE>',
    },
  };
  player.source = {
    sources: {
      src: '<DASH_STREAM_URL>',
      type: 'application/dash+xml',
      contentProtection: drmConfiguration,
    },
  };
}
```

##### Android SDK

```java
DRMConfiguration drmConfiguration = DRMTodayConfiguration.Builder
    .drmToday(
        new KeySystemConfiguration("<LICENSE_KEY_URL_WIDEVINE>")
    )
    .merchant("<MERCHANT>")
    .sessionId("<SESSION_ID>")
    .token("<TOKEN>")
    .userId("<USER_ID>")
    .build();
TypedSource typedSource = new TypedSource.Builder()
    .src("<DASH_STREAM_URL>")
    .drm(drmConfiguration)
    .build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription()
    .sources(typedSource)
    .build();
theoplayer.getPlayer().setSource(sourceDescription);
```

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
let drmConfiguration = DRMTodayDRMConfiguration(
    licenseAcquisitionURL: "<LICENSE_KEY_URL_FAIRPLAY>",
    certificateURL: "<CERTIFICATE_URL>",
    merchant: "<MERCHANT>",
    sessionId: "<SESSION_ID>",
    token: "<TOKEN>",
    userId: "<USER_ID>"
)
let typedSource = TypedSource(src: "<HLS_STREAM_URL>", type: "application/x-mpegurl", drm: drmConfiguration)
let sourceDescription = SourceDescription(source: typedSource)
theoplayer.source = sourceDescription
```

## Resources

* <https://castlabs.com/drmtoday/>

---

# How to do offline playback with DRMToday on iOS

This how-to guide describes how to implement playback of downloadable content-protected HLS streams using the THEOplayer iOS SDK. Currently, FairPlay is supported together with the Irdeto and DRMToday integrations.

## Prerequisites

In order to do offline DRM on iOS, your license key should be downloadable and cacheable. The SDK will not be able to decrypt your content if your key expired.

This feature only works on iOS 10.0 and above.

**Known limitations**

1. If your **manifest gets redirected** when you are caching and playing back a resource, you **need to save your redirected manifest URL** (what is being cached) and **provide that (redirected) URL to the player** when you would like to play back from the cache.
2. Only **completely cached videos can be played offline**. (When the CachingTask status is DONE, then the video is playable without any internet connection)
3. HLS manifests can have a tag **#EXT-X-PLAYLIST-TYPE:VOD** (<https://developer.apple.com/documentation/http_live_streaming/example_playlists_for_http_live_streaming/video_on_demand_playlist_construction>) If this tag is not present in the manifest of the cached quality, THEOplayer will make extra request for the manifest event if the video is completely cached. To avoid from these extra request, you need to provide **EXT-X-PLAYLIST-TYPE:VOD** in your manifests.

## Code example

Download a FairPlay HLS asset.

```swift
//example source
public static var sourceToBeCached: SourceDescription {
    let src = "https://source.m3u8"
    let merchant = "merchant"
    let userId = "userId"
    let sessionId = "sessionId"
    let streamType = "application/x-mpegurl"
    let drmConfig = DRMTodayDRMConfiguration(
                        licenseAcquisitionURL: "https://lic.staging.drmtoday.com/license-server-fairplay/",
                        certificateURL: "https://lic.staging.drmtoday.com/license-server-fairplay/cert/",
                        userId: userId,
                        sessionId: sessionId,
                        merchant: merchant
                    )
    return SourceDescription(source: TypedSource(src: src, type: streamType, drm: drmConfig))
}

//example cache call
var cachingTask: CachingTask?

func cacheSource(SourceDescription source, Date expirationDate) {
            cachingTask = THEOplayer.cache.createTask(source: source, parameters: CachingParameters(expirationDate: expirationDate))
            if cachingTask != nil {
                _ = cachingTask!.addEventListener(type: CachingTaskEventTypes.STATE_CHANGE) { event in
                    print("Received state change on caching task \(self.cachingTask!.source.sources[0].src) Status: \(self.cachingTask!.status)")
                }
                _ = cachingTask!.addEventListener(type: CachingTaskEventTypes.PROGRESS) { event in
                    print("Received progress on caching task \(self.cachingTask!.source.sources[0].src) Cached: ")
                    for timeRange in self.cachingTask!.cached {
                        print(timeRange.start, timeRange.end)
                    }
                }
                cachingTask.start()
            }
}

func playSourceFromCache(SourceDescription source) {
    theoplayer.source = source
    theoplayer.play();
}
```

Delete all cached assets.

```swift
func cleanCache() {
    for cachingTask in THEOplayer.cache.tasks {
        print("Will remove caching task \(cachingTask.source.sources[0].src)")
        cachingTask.remove()
    }
}
```

Renew a DRM license with specific DRM configuration.

```swift
func renewLicense() {
    let newDrmConfig = DRMTodayDRMConfiguration(
                            licenseAcquisitionURL: "https://lic.staging.drmtoday.com/license-server-fairplay/",
                            certificateURL: "https://lic.staging.drmtoday.com/license-server-fairplay/cert/",
                            userId: userId,
                            sessionId: sessionId,
                            merchant: merchant
                        )

    cachingTask.license.renew(newDrmConfig) // or we can renew it with the old drmConfig too: cachingTask.license.renew()
}
```

Handle redirected manifest.

```swift
// cache source

let url = URL(string: "MASTER_MANIFEST_URL_THAT_GETS_REDIRECTED")

let task = URLSession.shared.dataTask(with: url!) { (data, response, error) in

    Streams.SAVED_REDIRECTED_URL = (response?.url)!
    cachingTaskSource.sources[0].src = Streams.SAVED_REDIRECTED_URL!
    self.cachingTask = THEOplayer.cache.createTask(source: cachingTaskSource, parameters: CachingParameters(expirationDate: Date.distantFuture, bandwidth: cachingTaskBandwidth))
    if self.cachingTask != nil {
        _ = self.cachingTask!.addEventListener(type: CachingTaskEventTypes.STATE_CHANGE) { event in
            if let cachingTask = self.cachingTask {
                print("Received state change on caching task \(cachingTask.source.sources[0].src) Status: \(cachingTask.status)")
            }
        }
        _ = self.cachingTask!.addEventListener(type: CachingTaskEventTypes.PROGRESS) { event in
            print("Received progress on caching task \(self.cachingTask!.source.sources[0].src) Cached: ")
            for timeRange in self.cachingTask!.cached {
                print(timeRange.start, timeRange.end)
            }
        }
        print("Did create caching task \(self.cachingTask!.source.sources[0].src)")
    }

}

task.resume()


// playback of cached source

var source = cachingTaskSource
source.sources[0].src = Streams.SAVED_REDIRECTED_URL!
theoplayer.source = source
theoplayer.play()
```

---

# Introduction

This how-to guide describes how to implement playback of downloadable content-protected streams using THEOplayer.

*Currently, Widevine and FairPlay (respectively for Android SDK and iOS SDK) are each supported together with the Uplynk-Verizon, Azure DRM and DRMToday integrations.*

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| No      | Yes         | Yes     | N/A      | Yes            | N/A            |

---

# How to do offline DRM on Android

This how-to guide describes how to implement playback of downloadable content-protected MPEG-DASH using the THEOplayer Android SDK. Currently, Widevine is supported together with the Irdeto and DRMToday integrations.

## Prerequisites

In order to do offline DRM on Android, your license key should be downloadable, and cacheable. The SDK will not be able to decrypt your content if your key expired.

To enable the display of progress notifications for downloading content in your Android application you need to include the following permissions in your AndroidManifest.xml file:

```xml
<manifest>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    <application>
        ...
    </application>
</manifest>
```

* android.permission.FOREGROUND\_SERVICE: This permission allows THEOplayer to run a foreground service, ensuring uninterrupted content downloads even when the application is not in the foreground. See more at [Foreground service permission](https://developer.android.com/guide/components/foreground-services#request-foreground-service-permissions).

* android.permission.POST\_NOTIFICATIONS: This permission is required if an application is targeting API 33 (Android 13) and above. It enables THEOplayer to create and display notifications, keeping users informed about the progress of content downloads. For more information, refer to the [Notification runtime permission](https://developer.android.com/develop/ui/views/notifications/notification-permission).

Including these permissions in your AndroidManifest.xml file is necessary for THEOplayer to run a foreground service and provide progress notifications during content downloads.

## Code example

The snippet below downloads a Widevine MPEG-DASH asset.

```java
private void cacheSource(String sessionId, String src, String amount, Date expirationDate) {
    Cache cache = THEOplayerGlobal.getSharedInstance(this).getCache();
    DRMConfiguration drmToday = createDrmTodayConfiguration(sessionId);
    SourceDescription source = new SourceDescription.Builder(
        new TypedSource.Builder(src)
            .drm(drmToday)
        .build())
    .build();
    CachingParameters cachingParameters = new CachingParameters.Builder()
                .amount(amount)
                .expirationDate(expirationDate)
                .build();
    CachingTask cachingTask = cache.createTask(source, cachingParameters);
    cachingTask.addEventListener(CachingTaskEventTypes.CACHING_TASK_STATE_CHANGE, e -> {
        switch (cachingTask.getStatus()) {
            case DONE:
                // handle success..
                break;
            case ERROR:
                // handle error..
                break;
            default: // do nothing
                break;
        }
    });
    cachingTask.start();
}

private DRMConfiguration createDrmConfiguration(String sessionId) {
    KeySystemConfiguration widevine = new KeySystemConfiguration.Builder()
        .keySystemConfiguration(LICENSE_ACQUISITION_URL)
        .licenseType(LicenseType.PERSISTENT)
        .build();
    return YOUR_DRM_INTEGRATION_WITH_WIVDEVINE(widevine)
}
```

To playback cached material, create and play the stream as per usual. The cached content will be used for the known source.

```java
private void playSourceFromCache(String sessionId, String src) {
    DRMConfiguration drmConf = createDrmConfiguration(sessionId);
    SourceDescription sourceDescription =
        new SourceDescription.Builder(
                new TypedSource.Builder(src)
                        .drm(drmConf)
                        .build())
                .build();
    tpv.getPlayer().setSource(sourceDescription);
    tpv.getPlayer().play();
}
```

A caching task can be paused and restarted through the task object itself.

```java
private void startAndPauseTask(CachingTask task) {
    // When not started, the task will be in the "IDLE" state
    task.start();
    // The status of the task will now be "LOADING"
    task.pause();
    // The task reverts back to "IDLE" after finishing its current segment download
    task.start();
    // The task continues where it was paused
}
```

After creating a caching task, it is possible to check an estimate for the total size of the caching task on disk, and the current progression in bytes (stored).

```java
private void checkStorageRequirements(CachingTask unstartedTask) {
    // We can get an estimate for the amount of space this task will consume. This will be ready once the manifest is preprocessed when the task is created. Starting is not necessary.
    System.out.println(unstartedTask.getBytes());
    unstartedTask.start();

    // ... Additional logic here

    // At any time, we can check the current amount of bytes cached by the task
    System.out.println(unstartedTask.getBytesCached());
}
```

## Listing and restarting caching tasks

An important side note when calling previously cached tasks is that you need to initialize the cache first. Initializing happens asynchronously, so calling upon the cache immediately after initializing may result in an empty list as it is still initializing. (You could initialize the cache as soon as your app opens, such that you can access it later in other pages in the app). To initialize the cache, you need to run the following command:

```java
Cache cache = THEOplayerGlobal.getSharedInstance(this).getCache();
```

If you only want to initialize it at the moment that you need it, you can use an eventListener to see when it's initialized, e.g.

```java
Cache cache = THEOplayerGlobal.getSharedInstance(this).getCache();
cache.addEventListener(CacheEventTypes.CACHE_STATE_CHANGE, new EventListener<CacheStateChangeEvent>() {
    @Override
    public void handleEvent(CacheStateChangeEvent cacheStateChangeEvent) {
        // Logic once cache is initialized.
        // Status can always be fetched using
        // cache.getStatus(), which will return the ENUM CacheStateChangeEvent.INITIALISED or CacheStateChangeEvent.UNINITIALISED
    }
});
```

Once the cache is properly initialized, you can call upon the cache with methods such as "getTasks()" which will return a TaskList that you can iterate through to find previously cached tasks and resume caching or play the resource. Example:

```java
// If you're in a different activity, you can always call upon the previously initialized cache
Cache cache = THEOplayerGlobal.getSharedInstance(this).getCache();

// Loop over previously cached tasks
for (CachingTask cachedVideo : cache.getTasks()) {
    // Do logic with the found cached video e.g.
    CachingTaskStatus status = cachedVideo.getStatus();
    SourceDescription sourceDescription = cachedVideo.getSource();
    Double percentageCached = cachedVideo.getPercentageCached();
    cachedVideo.pause(); // Pause if not already paused
    cachedVideo.start(); // start or resume caching task}
}
```

For all possible API calls, we refer you to the JavaDoc available [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/cache/package-summary)

---

# How to do offline DRM on iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

## Prerequisites

In order to do offline DRM on iOS, your license key should be downloadable and cacheable. The SDK will not be able to decrypt your content if your key expired.

This feature only works on iOS 10.0 and above.

**Known limitations**

1. If your **manifest gets redirected** when you are caching and playing back a resource, you **need to save your redirected manifest URL** (what is being cached) and **provide that (redirected) URL to the player** when you would like to play back from the cache.
2. Only **completely cached videos can be played offline**. (When the CachingTask status is DONE, then the video is playable without any internet connection)
3. HLS manifests can have a tag **#EXT-X-PLAYLIST-TYPE:VOD** (<https://developer.apple.com/documentation/http_live_streaming/example_playlists_for_http_live_streaming/video_on_demand_playlist_construction>) If this tag is not present in the manifest of the cached quality, THEOplayer will make extra request for the manifest event if the video is completely cached. To avoid from these extra request, you need to provide \*\*EXT-X-PLAYLIST-TYPE:VOD \*\*in your manifests.

## Code example

Here we provide some code examples to perform different calls. For all possible API calls, we refer you to the documentation available in the SDK that you have generated/received.

### Download

The snippet below downloads a FairPlay HLS asset.

```swift
//example source
public static var sourceToBeCached: SourceDescription {
    let src = "https://source.m3u8"
    let merchant = "merchant"
    let userId = "userId"
    let sessionId = "sessionId"
    let streamType = "application/x-mpegurl"
    let drmConfig = DRMTodayDRMConfiguration(
                        licenseAcquisitionURL: "https://lic.staging.drmtoday.com/license-server-fairplay/",
                        certificateURL: "https://lic.staging.drmtoday.com/license-server-fairplay/cert/",
                        userId: userId,
                        sessionId: sessionId,
                        merchant: merchant
                    )
    return SourceDescription(source: TypedSource(src: src, type: streamType, drm: drmConfig))
}

//example cache call
var cachingTask: CachingTask?

func cacheSource(SourceDescription source, Date expirationDate) {
            cachingTask = THEOplayer.cache.createTask(source: source, parameters: CachingParameters(expirationDate: expirationDate))
            if cachingTask != nil {
                _ = cachingTask!.addEventListener(type: CachingTaskEventTypes.STATE_CHANGE) { event in
                    print("Received state change on caching task \(self.cachingTask!.source.sources[0].src) Status: \(self.cachingTask!.status)")
                }
                _ = cachingTask!.addEventListener(type: CachingTaskEventTypes.PROGRESS) { event in
                    print("Received progress on caching task \(self.cachingTask!.source.sources[0].src) Cached: ")
                    for timeRange in self.cachingTask!.cached {
                        print(timeRange.start, timeRange.end)
                    }
                }
                cachingTask.start()
            }
}
```

### Playback

To playback cached material:

```swift
func playSourceFromCache(source: SourceDescription) {
    theoplayer.source = source
    theoplayer.play();
}
```

### Pause and restart

A caching task can be paused and restarted through the task object itself.

```swift
let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")
let sourceDescription = SourceDescription(source : typedSource)

let cachingTask = THEOplayer.cache.createTask(source: sourceDescription, parameters: nil)

// starting a caching task
cachingTask?.start()

// pausing a caching task
cachingTask?.pause()

// resuming a caching task
cachingTask?.start()
```

### Check size and progression

After creating a caching task, it is possible to check an estimate for the total size of the caching task on disk, and the current progression in bytes (stored).

```swift
let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")
let sourceDescription = SourceDescription(source : typedSource)

let cachingTask = THEOplayer.cache.createTask(source: sourceDescription, parameters: nil)

// starting a caching task
cachingTask?.start()

if let cachingTask = cachingTask {
    // Listen for state change events
    _ = cachingTask.addEventListener(type: CachingTaskEventTypes.STATE_CHANGE, listener: { event in
        print(cachingTask.status)
    })
    // Listen for progress events
    _ = cachingTask.addEventListener(type: CachingTaskEventTypes.PROGRESS, listener: { event in
        // percentage cached
        print(cachingTask.percentageCached)
        // total bytes cached
        print(cachingTask.bytesCached)
        // the amount of seconds cached
        print(cachingTask.secondsCached)
        // the range that is cached
        for timeRange in cachingTask.cached {
            print(timeRange.start, timeRange.end)
        }
    })
}
```

### Delete

The snippet below deletes all cached assets

```swift
func cleanCache() {
    for cachingTask in THEOplayer.cache.tasks {
        print("Will remove caching task \(cachingTask.source.sources[0].src)")
        cachingTask.remove()
    }
}
```

### Renew a DRM license

Renew a DRM license with specific DRM configuration:

```swift
func renewLicense() {
    let newDrmConfig = DRMTodayDRMConfiguration(
                            licenseAcquisitionURL: "https://lic.staging.drmtoday.com/license-server-fairplay/",
                            certificateURL: "https://lic.staging.drmtoday.com/license-server-fairplay/cert/",
                            userId: userId,
                            sessionId: sessionId,
                            merchant: merchant
                        )

    cachingTask.license.renew(newDrmConfig) // or we can renew it with the old drmConfig too: cachingTask.license.renew()
}
```

### Handle redirected manifest

```swift
// cache source

let url = URL(string: "MASTER_MANIFEST_URL_THAT_GETS_REDIRECTED")

let task = URLSession.shared.dataTask(with: url!) { (data, response, error) in

    Streams.SAVED_REDIRECTED_URL = (response?.url)!
    cachingTaskSource.sources[0].src = Streams.SAVED_REDIRECTED_URL!
    self.cachingTask = THEOplayer.cache.createTask(source: cachingTaskSource, parameters: CachingParameters(expirationDate: Date.distantFuture, bandwidth: cachingTaskBandwidth))
    if self.cachingTask != nil {
        _ = self.cachingTask!.addEventListener(type: CachingTaskEventTypes.STATE_CHANGE) { event in
            if let cachingTask = self.cachingTask {
                print("Received state change on caching task \(cachingTask.source.sources[0].src) Status: \(cachingTask.status)")
            }
        }
        _ = self.cachingTask!.addEventListener(type: CachingTaskEventTypes.PROGRESS) { event in
            print("Received progress on caching task \(self.cachingTask!.source.sources[0].src) Cached: ")
            for timeRange in self.cachingTask!.cached {
                print(timeRange.start, timeRange.end)
            }
        }
        print("Did create caching task \(self.cachingTask!.source.sources[0].src)")
    }
}
task.resume()

// playback of cached source

var source = cachingTaskSource
source.sources[0].src = Streams.SAVED_REDIRECTED_URL!
theoplayer.source = source
theoplayer.play()
```

---

# Customizing Notifications for Downloading Offline DRM on Android

## Text Resources Customization

To customize the text or add translations to the notifications, you can override the following string resources:

1. `<string name="theo_download_progress_title">Downloading video</string>`

   * This resource represents the title displayed during the progress of video downloading.

2. `<string name="theo_download_status_title">Download %s</string>`

   * This resource represents the title displayed during the download process. The `%s` placeholder will be replaced with the actual file name.

3. `<string name="theo_download_status_percentage">%d%%</string>`

   * This resource represents the percentage of download progress displayed in the notification. The `%d` placeholder will be replaced with the actual progress value.

4. `<string name="theo_download_finished_status_title">Download finished</string>`

   * This resource represents the title displayed when the download is completed successfully.

5. `<string name="theo_download_paused_status_title">Download paused</string>`

   * This resource represents the title displayed when the download is paused.

6. `<string name="theo_download_failed_status_title">Download failed</string>`

   * This resource represents the title displayed when the download fails.

7. `<string name="theo_download_stopped_status_title">Download stopped</string>`

   * This resource represents the title displayed when the download is manually stopped.

8. `<string name="theo_cache_notifications_channel_name">Media downloader</string>`

   * This resource represents the name of the notification channel used for media downloading.

9. `<string name="theo_cache_notifications_channel_description">Downloads media to make it available for offline playback</string>`

   * This resource represents the description of the notification channel used for media downloading.

To customize these texts or add translations, create corresponding string resources in your app's resource file (e.g., `strings.xml`) and provide the desired values.

By overriding these resources, you can tailor the text content of the notifications to match your application's branding or localize them for different languages or regions.

## Customization of Notification Builders

The `CacheNotificationsBuilder` interface provides the ability to create customized notification appearances using the NotificationCompat.Builder. This feature allows you to design notifications according to your specific preferences and requirements.

The `CacheNotificationsBuilder` interface includes three methods:

1. `createProgressNotificationBuilder`: This method allows you to customize the `builder` parameter and create a custom progress notification builder for a specific caching task. It takes the `task` parameter, which represents the caching task for which the progress notification is being created, and the `builder` parameter, which is the base notification builder to customize. It returns the customized notification builder for the progress notification.

2. `createStatusNotificationBuilder`: In this method, you have the ability to customize the `builder` parameter and create a custom status notification builder for a given caching task. It takes the `task` parameter, which represents the caching task for which the status notification is being created, and the `builder` parameter, which is the base notification builder to customize. It returns the customized notification builder for the status notification.

3. `createNotificationChannel`: This method enables you to customize the `channel` parameter and create a custom notification channel for caching notifications. It takes the `channel` parameter, which is the base notification channel builder to customize. It returns the customized notification channel builder.

   **Note:** If you decide to return `null` in the `createNotificationChannel` method, the library will not create any notification channel. This means that notifications related to caching will not have a designated channel for grouping or presentation.

These methods allow you to customize the appearance and behavior of notifications and notification channels according to your specific requirements when downloading media files using cache in THEOplayer.

To implement this interface, follow these steps:

1. Obtain an instance of THEOplayer cache by calling `THEOplayerGlobal.getSharedInstance(this).cache`.

2. Assign an object that implements the CacheNotificationsBuilder interface to `theoCache.notificationBuilder`.

   Example:

   ```kotlin
   val theoCache = THEOplayerGlobal.getSharedInstance(this).cache
   theoCache.notificationBuilder = object : CacheNotificationsBuilder {
       override fun createNotificationChannel(channel: NotificationChannelCompat.Builder): NotificationChannelCompat.Builder {
           // Customization logic for the notification channel
           ...
           return channel
       }

       override fun createProgressNotificationBuilder(task: CachingTask, builder: NotificationCompat.Builder): NotificationCompat.Builder {
           // Customization logic for the progress notification builder
           ...
           return builder
       }

       override fun createStatusNotificationBuilder(task: CachingTask, builder: NotificationCompat.Builder): NotificationCompat.Builder {
           // Customization logic for the status notification builder
           ...
           return builder
       }
   }
   ```

In the `createProgressNotificationBuilder` and `createStatusNotificationBuilder` methods, you can refer to the official [NotificationCompat.Builder documentation](https://developer.android.com/reference/androidx/core/app/NotificationCompat.Builder) for detailed information on how to customize the notification appearance, add actions, and handle interactions.

Inside the implementation of each method, you can customize the respective notification channel or builder according to your requirements. Make sure to return the modified notification channel or builder as per the method's return type.

By completing these steps, you will set up the implementation of the CacheNotificationsBuilder interface, allowing you to customize the appearance and behavior of notifications in THEOplayer cache.

## Hiding notifications

To hide a notification, you can simply return `null` in the corresponding method of the `CacheNotificationsBuilder` interface.

For example, if you want to hide the progress notification or status notification for a specific caching task, you can return `null` in the `createProgressNotificationBuilder` or `createStatusNotificationBuilder` method, respectively. This will prevent the notification from being shown.

Please note that when you return `null` in the `createProgressNotificationBuilder` or `createStatusNotificationBuilder` methods to hide the notification, the downloading process will not be performed using a foreground service.

Ensure that you consider the implications of hiding notifications and not using a foreground service for downloading media files. It is recommended to provide alternative ways to inform the user about the download progress or completion if you choose to hide notifications.

---

# Introduction

In this section, you can figure out how THEOplayer integrates with various partners.

## [📄️IRIS.TV](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/integrations/iris-tv.md)

[Iris.TV is a recommendation engine. When hooking THEOplayer to the IrisTV SDK, a UI will be overlaid over the default player UI which can be used to navigate through recommendations.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/integrations/iris-tv.md)

## [📄️Wowza streaming engine with secure token version 2](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/integrations/wowza-streaming-engine-with-secure-token-version-2.md)

[This guide explains how to set up THEOplayer with Wowza Streaming Engine™, using their SecureToken version 2 module, that provides playback protection via a security token that is exchanged between the server and clients. The SecureToken is a challenge/response system that helps to protect content against spoofing threats. Each connection is protected by a random key and a password (shared secret).](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/integrations/wowza-streaming-engine-with-secure-token-version-2.md)

## [📄️Deliver Low-Latency HLS live streams using Wowza Streaming Engine and THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/integrations/deliver-low-latency-hls-live-streams-with-wowza-streaming-engine.md)

[Wowza Streaming Engine™ media server software version 4.7.8 and later together with THEOplayer version 2.65 and later can deliver Low-Latency HLS (LL-HLS) live streams.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/integrations/deliver-low-latency-hls-live-streams-with-wowza-streaming-engine.md)

---

# IRIS.TV

[Iris.TV](https://www.iris.tv/) is a recommendation engine. When hooking THEOplayer to the IrisTV SDK, a UI will be overlaid over the default player UI which can be used to navigate through recommendations.

This guide describes how to do a [custom IrisTV integration](https://iristv.atlassian.net/wiki/spaces/API/pages/38567965/Custom+Adaptive+Plug-in+Integrations) in THEOplayer.

## SDKs

| Web SDK | Android SDK                                   | iOS SDK                                       | tvOS SDK | Android TV SDK                                | Chromecast SDK |
| ------- | --------------------------------------------- | --------------------------------------------- | -------- | --------------------------------------------- | -------------- |
| Yes     | Unverified through CSS/JavaScript injection\* | Unverified through CSS/JavaScript\* injection | No       | Unverified through CSS/JavaScript injection\* | N/A            |

\*CSS/JavaScript injection in the project is only possible with the legacy mobile SDKs (up to 4.12.X).

## How to integrate the player with Iris.TV

### Prerequisites

There are two prerequisites in order to continue with this guide:

1. You have a THEOplayer license and library. If you don't have THEOplayer yet, you can start your free trial [here](https://portal.theoplayer.com/) or contact your THEOplayer account manager.

2. You have some basic knowledge on how to use THEOplayer and have set up a working implementation with THEOplayer in it. You can read on this subject at the following pages:

##### Web SDK

[Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)

##### Android Legacy (4.12.x) SDK

[Getting started on Android Legacy (4.12.x)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/android/getting-started)

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

[Getting started on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/ios/getting-started)

### Include the IrisTV SDK

You need to include the IrisTV JavaScript library in your project:

##### Web SDK

Include the script tag right before where you include the THEOplayer.js library:

```html
<script type="text/javascript" src="https://ovp.iris.tv/libs/adaptive/iris.adaptive.js"></script>
```

##### Legacy Android SDK (4.12.X)

1. Download the JavaScript library available at <https://ovp.iris.tv/libs/adaptive/iris.adaptive.js>

2. Follow these instructions and add it as a custom JS file in your project: [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)

##### Legacy iOS/tvOS SDK (4.12.x)

1. Download the JavaScript library available at <https://ovp.iris.tv/libs/adaptive/iris.adaptive.js>

2. Follow these instructions and add it as a custom JavaScript file in your project: [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)

### Include the custom integration

You need to include the JavaScript script tag referencing the file containing the custom integration code.

##### Web SDK

Include the script tag this right after where you include the THEOplayer.js library.

```html
<script type="text/javascript" src="https://cdn.theoplayer.com/demos/iristv/THEOplayer.iristv.js"></script>
```

You can also add extra styling on top of the IrisTV UI:

```html
<link rel="stylesheet" type="text/css" href="https://cdn.theoplayer.com/demos/iristv/THEOplayer.iristv.css" />
```

##### Legacy Android SDK (4.12.X)

1. Download the JavaScript library available at <https://cdn.theoplayer.com/demos/iristv/THEOplayer.iristv.js>

2. Follow these instructions to add custom JavaScript files in your project: [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)

3. You can also add extra styling on top of the IrisTV UI downloading the following file (and integrating it too as explained in the guide linked at step 2): <https://cdn.theoplayer.com/demos/iristv/THEOplayer.iristv.css>

##### Legacy iOS/tvOS SDK (4.12.x)

1. Download the JavaScript library available at <https://cdn.theoplayer.com/demos/iristv/THEOplayer.iristv.js>

2. Follow these instructions to add custom JavaScript files in your project: [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)

3. You can also add extra styling on top of the IrisTV UI downloading the following file (and integrating it too as explained in the guide linked at step 2): <https://cdn.theoplayer.com/demos/iristv/THEOplayer.iristv.css>

### Initialize THEOplayerIrisTv

##### Web SDK

To start displaying the IrisTV UI, you have to call THEOplayerIrisTv() (from THEOplayer.iristv.js), and pass along the THEOplayer instance and your IrisTV configuration. For example:

```html
<script>
  ...
  var irisOptions = {
      client_token: "51afa098ah",
      platform_id: "5798d994ef995e0d18000176"
  };
  THEOplayerIrisTv(player, irisOptions);
</script>
```

##### Legacy Android SDK (4.12.X)

The Web SDK code should be included in your Android (TV) project. The article at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios) explains how you can add CSS and JS files to your project. The sample project at [How to insert a button](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-insert-a-button.md) demonstrates this.

##### Legacy iOS/tvOS SDK (4.12.x)

The Web SDK code should be included in your iOS project. The article at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios) explains how you can add CSS and JavaScript files to your project. The sample project at [How to insert a button](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-insert-a-button.md) demonstrates this.

## Conclusion

In summary, to integrate IrisTV in THEOplayer, is as simple as including their SDK and some custom code in your project.

## Sample application

A live demo can be viewed at <https://cdn.theoplayer.com/demos/iristv/iristv.html>.

## Resources

* [Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)

* [Getting started on Android Legacy (4.12.x)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/android/getting-started)

* [Getting started on iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/ios/getting-started)

* [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)

* <https://iristv.atlassian.net/wiki/spaces/API/pages/263258113/THEO+Adaptive+Plugin>: [Iris.tv](http://Iris.tv) documentation - THEO adaptive plugin

* <https://iristv.atlassian.net/wiki/spaces/API/pages/38567965/Custom+Adaptive+Plugin> : Iris.tv documentation - Custom adaptive plugin

* <http://www.iris.tv/>: Iris.tv

---

# Wowza streaming engine with secure token version 2

This guide explains how to set up THEOplayer with Wowza Streaming Engine™, using their SecureToken version 2 module, that provides playback protection via a security token that is exchanged between the server and clients. The SecureToken is a challenge/response system that helps to protect content against spoofing threats. Each connection is protected by a random key and a password (shared secret).

An important aspect when generating the hash, is that the client web server should generate the hash when it generates the client webpage. The **client webpage should not** use JavaScript code to generate the hash, as the code is visible in the webpage source and would pose a potential security risk. As a result, our implementation is based on a node/express application to generate the hash.

## SDKs

| Web SDK | Android SDK                                   | iOS SDK                                       | tvOS SDK | Android TV SDK                                | Chromecast SDK |
| ------- | --------------------------------------------- | --------------------------------------------- | -------- | --------------------------------------------- | -------------- |
| Yes     | Unverified through CSS/JavaScript injection\* | Unverified through CSS/JavaScript injection\* | No       | Unverified through CSS/JavaScript injection\* | N/A            |

\*CSS/JavaScript injection in the project is only possible with the legacy mobile SDKs (up to 4.12.X).

## How to set up THEOplayer with Wowza Streaming Engine

### Prerequisites

There are three prerequisites in order to continue with this guide:

1. You have a THEOplayer license. If you are not using THEOplayer yet, you can start your free trial [here](https://portal.theoplayer.com/).

2. You are a Wowza Streaming Engine client and are integrated with their streaming infrastructure. Information on Wowza Streaming Engine can be found [here](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/) and information on how to protect your streams, using SecureToken, can be found [here](https://www.wowza.com/docs/how-to-protect-streaming-using-securetoken-in-wowza-streaming-engine).

3. For the purposes of this example, we created a VOD application (this example would also work for live applications), in the Wowza Streaming Engine manager. We then configured our Wowza stream using the below settings in the Playback Security tab:

   i) SecureToken: **Protect all protocols using hash (SecureToken version 2)**

   ii) Shared Secret: **53a0a16b7cde230b**

   iii) Hash Algorithm: **SHA-256**

   iv) Include client IP address in hash generation: **Ticked (yes)**

   v) Hash Query Parameter Prefix: **wowzatoken**

   vi) Client Restrictions: **No client restrictions**

The application was saved and restarted.

### Integrating THEOplayer with Wowza Streaming Engine

##### Web SDK

[Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)

#### Server-side hash generation code

The below code makes reference to the above configuration settings specified in the Wowza Streaming Engine manager.

```js
var express = require('express');
var app = express();

var crypto = require('crypto');
var address = require('address');

// add CORS headers
app.use('/generate-hash', function (req, res, next) {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept');
  next();
});

const path = require('path');
const port = 3000;

/****************** START OF CONFIGURATION ******************/

// your hash algorithm: 256, 384 OR 512
const hashAlgorithm = '256';

// your shared Secret
const sharedSecret = '53a0a16b7cde230b';

// the content path to the streaming asset and is the part of the URL that starts with the application name
// (excluding the '/' that precedes the application name) and continues through to the end of the stream name or file name.
// Be sure to exclude all HTTP request keywords after the stream name or file name (for example, /manifest.m3u8, /media.ts, /Manifest, /manifest.f4v, and so on)
const contentPath = 'vod/mp4:sample.mp4';

// your token prefix custom parameter
const tokenPrefix = 'wowzatoken';

// your random custom parameter (optional - leave as empty string if none)
const customParameter = 'myrandomcustomparameter';

// include client IP address in hash generation (yes/no)?
const includeClientIPAddress = 'yes';

//const now = new Date();
//const startTime = Math.round(now.getTime() / 1000);
const startTime = '0';
//const validity = 1000; // validity in seconds

//const endTime = Math.round(now.getTime() / 1000) + validity;
const endTime = '0';

/****************** END OF CONFIGURATION ******************/

var params = [];

// create an array with the parameters
if (includeClientIPAddress == 'yes') {
  address(function (err, addrs) {
    params.push(addrs.ip);
  });
}

params.push(
  tokenPrefix + 'startTime=' + startTime,
  tokenPrefix + 'endTime=' + endTime,
  tokenPrefix + 'customParameter=' + customParameter,
  sharedSecret
);

// params should be sorted alphabetically before constructing the hash string
params.sort();

// construct the hash string
var hashString = contentPath + '?';

for (var i = 0; i < params.length; i++) {
  if (i + 1 == params.length) {
    hashString = hashString + params[i];
  } else {
    hashString = hashString + params[i] + '&';
  }
}

// the hash generated at the client should be a URL-safe Base64-encoded string.
app.get('/generate-hash', function (req, res, next) {
  var hash = crypto
    .createHash('sha' + hashAlgorithm)
    .update(hashString, 'utf8')
    .digest('base64');

  // URL-safe Base64 encoding replaces the '+' character with the '-' character and the '/' character with the '_' character.
  hash = hash.replace(/\+/g, '-');
  hash = hash.replace(/\//g, '_');

  console.log(hashString);

  res.send(hash);
});

// Listen for requests
app.get('/', function (req, res) {
  res.sendFile(path.join(__dirname + '/index.html'));
});

app.listen(port);
```

Save this JavaScript file as wowzasecuretoken.js and then run it with `node wowzasecuretoken.js`

#### Client-side hash generation code

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Web SDK: Getting Started</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="path/to/theoplayer/ui.css" />
    <!-- adds THEOplayer CSS -->
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin"></div>
    <script type="text/javascript" src="path/to/thoeplayer/THEOplayer.js"></script>
    <!-- adds THEOplayer library -->
    <script>
      // Initialize player function once the hash has been retrieved
      var initPlayer = function (hash) {
        console.log(hash);
        // Replace http://192.168.1.34:1935/vod/mp4:sample.mp4/playlist.m3u8 with your stream manifest
        var hlsUrl =
          'http://192.168.1.34:1935/vod/mp4:sample.mp4/playlist.m3u8?' +
          'wowzatokenstartTime=0&' +
          'wowzatokenendTime=0&' +
          'wowzatokencustomParameter=myrandomcustomparameter&' +
          'wowzatokenhash=' +
          hash;

        console.log(hlsUrl);

        var element = document.querySelector('.video-js');
        var player = new THEOplayer.Player(element, {
          libraryLocation: 'path/to/theoplayer',
          license: 'your-license-here',
        });

        player.src = hlsUrl;
      };

      // Ajax request for the hash to the node/express app
      var requestHash = function (url) {
        var req = new XMLHttpRequest();
        req.open('GET', url, true);
        req.onreadystatechange = function () {
          if (req.readyState === 4) {
            var response = req.responseText;
            if (req.status === 200) {
              initPlayer(response);
            } else {
              console.log('Could not get hash');
            }
          }
        };
        req.onerror = function () {
          console.log('Could not get hash');
        };
        req.send();
      };

      // Start the request to your node/express server. Be sure to replace http://127.0.0.1:3000 with your node IP address and port
      var serverHashUrl = 'http://127.0.0.1:3000/generate-hash';
      requestHash(serverHashUrl);
    </script>
  </body>
</html>
```

Save this HTML file as `index.html` and then view it in your browser window.

## Conclusion

THEOplayer partnered with Wowza Streaming Engine to fully integrate their SecureToken version 2 module.

In summary, to integrate Wowza Streaming Engine SecureToken version 2 module, in THEOplayer, you have to implement a client/server side solution using custom code.

## Resources

* [Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)

* [Getting Started with Wowza Streaming Engine](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/)

* [Protect your streams using SecureToken in Wowza Streaming Engine](https://www.wowza.com/docs/how-to-protect-streaming-using-securetoken-in-wowza-streaming-engine)

---

# Deliver Low-Latency HLS live streams using Wowza Streaming Engine and THEOplayer

Wowza Streaming Engine™ media server software version 4.7.8 and later together with THEOplayer version 2.65 and later can deliver Low-Latency HLS (LL-HLS) live streams.

Low-Latency HLS streams conform to [Apple’s preliminary protocol extension to the HLS spec](https://developer.apple.com/documentation/http_live_streaming/protocol_extension_for_low-latency_hls_preliminary_specification?language=objc).

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | In Beta     | In Beta | In Beta  | In Beta        | N/A            |

## How to set up THEOplayer with Wowza Streaming Engine For LL-HLS

### Prerequisites

There are three prerequisites in order to continue with this guide:

1. In order to generate LL-HLS streams, you must first get a SSL certificate to secure your port and configure the port for HTTPS playback. LL-HLS playback does not work without an SSL secured port. For information on how to do this, refer to [How to Get an SSL Certificate from Wowza's Streamlock Service](https://www.wowza.com/docs/how-to-get-ssl-certificates-from-the-streamlock-service).

2. This guide expects that you have a THEOplayer license. If you are not using THEOplayer yet, you can start your free trial [here](https://portal.theoplayer.com/). In addition, you will need a specify the **LL-HLS** feature flag when generating your SDK. Be sure to have THEOplayer version 2.65 or higher.

3. This guide expects that you are a Wowza Streaming Engine client and that you are integrated with their streaming infrastructure. Information on Wowza Streaming Engine can be found [here](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/). Be sure to have Wowza Streaming Engine media server software version 4.7.8 or higher.

**Please Note:** Wowza occasionally update their documentation, which can be accessed [here](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine).

### Configure a live application to deliver LL-HLS streams

You can use the default **live** application that installs with Wowza Streaming Engine or create and use a new **Live** or **Live HTTP Origin** application. Use the **Live** application type for sending streams from Wowza Streaming Engine to clients or Wowza Streaming Engine edges. Use the **Live HTTP Origin** application type to connect to a CDN edge, such as the Fastly CDN, that can pull streams from the Wowza Streaming Engine origin application.

The following steps use the default **live** application to enable LL-HLS live streaming by editing the **Application.xml** and **VHost.xml** configuration files.

You can use the default live application that installs with Wowza Streaming Engine or create and use a new Live or Live HTTP Origin application. Use the Live application type for sending streams from Wowza Streaming Engine to clients or Wowza Streaming Engine edges. Use the Live HTTP Origin application type to connect to a CDN edge, such as the Fastly CDN, that can pull streams from the Wowza Streaming Engine origin application.

The following steps use the default **live** application to enable LL-HLS live streaming by editing the **Application.xml** and **VHost.xml** configuration files.

**Please Note:** If you're trying to use the CMAF packetizer to deliver LL-HLS and HLS or MPEG-DASH streams, you must use two separate live applications: one configured specifically for LL-HLS and another for CMAF-packetized HLS and MPEG-DASH.

#### Enable LL-HLS in Wowza Streaming Engine XML

The following steps enable transmuxing for CMAF packetization for LL-HLS delivery.

1. Navigate to **\[install-dir]/conf/live** or **\[install-dir]/conf/\[custom live application]** and open the **Application.xml** file in a text editor.
2. Add **cmafstreamingpacketizer** to the **LiveStreamPacketizers** property. You can add it to the prepopulated comma-separated list, or it can be the only packetizer specified. The XML looks like this:

```xml
<Streams>
    ...
    <LiveStreamPacketizers>cmafstreamingpacketizer</LiveStreamPacketizers>
    ...
</Streams>
```

**Please Note:** If you enable **cupertinostreamingpacketizer** and **cmafstreamingpacketizer**, Wowza Streaming Engine generates both MPEG-TS segments (using **cupertinostreamingpacketizer**) and fMP4 segments (using **cmafstreamingpacketizer**).

3. Add the **cmafLLEnableLowLatency** property to the **LiveStreamPacketizer** container element and set it to true.

```xml
<LiveStreamPacketizer>
    <Properties>
        <Property>
            <Name>cmafLLEnableLowLatency</Name>
            <Value>true</Value>
            <Type>Boolean</Type>
        </Property>
    </Properties>
</LiveStreamPacketizer>
```

4. For the **HTTPStreamers** property, make sure HLS (**cupertinostreaming**) is specified. The XML looks like this:

```xml
<HTTPStreamers>cupertinostreaming</HTTPStreamers>
```

5. Go to **\[install-dir]/conf/** and open the **VHost.xml** file in a text editor.

6. Add the `AllowHttp2` property to the `<SSLConfig>` container element in the `<HostPort>` you configured for SSL/TLS and set it to true.

```xml
<SSLConfig>
    ...
    <AllowHttp2>true</AllowHttp2>
    ...
</SSLConfig>
```

7. Save your changes.

Your live application is now configured to deliver LL-HLS streams.

#### Configure optional low latency partial segment properties and media playlist property

Configuring the following properties is optional as Wowza Streaming Engine will use the property's default value for any of the properties that you do not configure. You can configure the optional LL-HLS properties by editing the **Application.xml** file for your LL-HLS live stream application. For information about configuring custom (optional) properties, see [Add custom properties](https://www.wowza.com/docs/add-a-custom-property#add-custom-properties).

##### Low latency CMAF property reference

You can configure any of these optional **LiveStreamPacketizer** properties for the LL-HLS segments and video and audio partial segments (chunks) in the **Application/LiveStreamPacketizer/Properties** container element.

**Please Note:** If partial segments are too small, servers can become overloaded with frequent media playlist requests and cause playback to be less reliable.

| Name                                                                                                                                                          | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **cmafLLChunkingScheme**                                                                                                                                      | String  | Specifies the chunking scheme for low latency CMAF-packetized streams. Valid values are **byFrame** or **byDuration**. The default is **byDuration**. If the value is **byDuration**, packetization is configured using the **cmafLLChunkDurationTargetAudio** and **cmafLLChunkDurationTargetVideo** properties. If the value is **byFrame**, packetization is configured using the **cmafLLChunkFrameCountTargetAudio** and **cmafLLChunkFrameCountTargetVideo** properties. |
| **cmafLLChunkDurationTargetAudio**                                                                                                                            | Integer | Specifies, in milliseconds, the target duration of each low latency CMAF **audio** chunk. The default is **1000** and is recommended. The duration cannot exceed the [cmafSegmentDurationTarget](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine#cmafsegmentdurationtarget) value. This property is only available if **cmafLLChunkingScheme** is **byDuration**.                                                           |
| **cmafLLChunkDurationTargetVideo**                                                                                                                            | Integer | Specifies, in milliseconds, the target duration of each low latency CMAF **video** chunk. The default is **1000** and is recommended. The duration cannot exceed the [cmafSegmentDurationTarget](https://www.wowza.com/docs/deliver-apple-low-latency-hls-live-streams-using-wowza-streaming-engine#cmafsegmentdurationtarget) value. This property is only available if **cmafLLChunkingScheme** is **byDuration**.                                                           |
| **cmafLLChunkFrameCountTargetAudio**                                                                                                                          | Integer | Specifies the target number of audio frames to include in each low latency CMAF audio chunk. The default is **47** and is recommended. This property is only enabled if **cmafLLChunkingScheme** is **byFrame**.                                                                                                                                                                                                                                                               |
| **cmafLLChunkFrameCountTargetAudio**                                                                                                                          | Integer | Specifies the target number of audio frames to include in each low latency CMAF audio chunk. The default is **30** and is recommended. This property is only enabled if **cmafLLChunkingScheme** is **byFrame**.                                                                                                                                                                                                                                                               |
| **[cmafSegmentDurationTarget](https://www.wowza.com/docs/configure-cmaf-packetization-in-wowza-streaming-engine#cmaf-live-packetization-property-reference)** | Integer | Specifies, in milliseconds, the duration of the fMP4 segments in the stream. The default is **6000** (6 seconds) and is recommended. This property is configurable from the **CMAFStreamingPacketizer** properties section in Wowza Streaming Engine Manager.                                                                                                                                                                                                                  |

##### Advanced LL-HLS property reference

For advanced tuning, you can configure the following optional **HTTPStreamer** property in the **Application/HTTPStreamer/Properties** container element.

| Name                                    | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cupertinoPartHoldBack (4.8.0 and later) | Double | Specifies, in floating-point seconds, the server-recommended minimum distance from the live edge at which clients should begin to play or seek in a LL-HLS stream (the PART-HOLD-BACK attribute in media playlists). If you do not configure this property, Wowza Streaming Engine uses the default value, which is recommended. The default value is calculated as three times the maximum value of PART-TARGET out of all of a stream's variant media playlists. **Please Note:** PART-TARGET is an attribute of the EXT-X-PART-INF tag in media playlists and is based on the target values set with the **cmafLLChunkDurationTargetVideo** and **cmafLLChunkDurationTargetAudio** properties or the **cmafLLChunkFrameCountTargetVideo** and **cmafLLChunkFrameCountTargetAudio** properties. Wowza Streaming Engine will adjust the PART-HOLD-BACK value to be equal to the maximum value of PART-TARGET (across all variant media playlists) if you set this property to less than a partial segment duration. |

##### Transcoding considerations for LL-HLS

To bypass encoding streams with Transcoder, source streams should meet the following encoding recommendations. Otherwise, transcoding is recommended. Although a small amount of latency is introduced with transcoding, if your source stream does not meet the encoding recommendations, transcoding will ultimately improve reliability of LL-HLS streaming.

###### Encoding recommendations

* CMAF-supported codecs (required)

| Video          | Audio                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - H.264, H.265 | - AAC, AAC-LC, HE-AAC (AAC+ or aacPlus),<br />- HE-AACv2 (enhanced AAC+, aacPlus v2) - Dolby Digital 5.1 Surround Sound (AC-3) and Dolby Digital Plus (Enhanced AC-3 or E-AC-3) |

* GOP size: 1 or 2 seconds
* Closed GOPs
* H.264 and H.265 byte streams contain metadata about the GOP structure
* Constant frame rate video

A stream configured for transcoding and LL-HLS delivery cannot use **Passthrough** for the **Video Codec** of a stream rendition but not other renditions of the same stream. If you use **Passthrough** to pass a video source through to output without making any changes for any **Video Codec** in a stream's renditions, all of the video codecs must be set to **Passthrough**.

Stream name groups (NGRP) are not supported with LL-HLS. To group multiple stream renditions for LL-HLS, you need to create a SMIL file in accordance with CMAF HLS. See [Set up adaptive bitrate CMAF streaming](https://www.wowza.com/docs/create-adaptive-bitrate-cmaf-streams-using-wowza-streaming-engine#set-up-adaptive-bitrate-cmaf-streaming) for how to do this.

##### Scale LL-HLS with a CDN

Optionally, with your own CDN account, you can scale LL-HLS delivery by connecting a Wowza Streaming Engine **Live HTTP Origin** application to a CDN edge that can pull streams from the Wowza Streaming Engine origin application, such as the Fastly CDN.

To connect the **Live HTTP Origin** application to your CDN, provide the IP address or hostname of the Wowza Streaming Engine origin server in your CDN configuration. Also in your CDN configuration, enable connecting to the origin server over SSL/TLS using the port you configured for SSL/TLS in the Wowza Streaming Engine origin (default port 443).

##### Test stream playback

After your live application is configured to deliver an LL-HLS stream, complete the stream setup by connecting a source encoder or IP camera to Wowza Streaming Engine and publishing the live source stream to the server. When the camera or encoder is connected and the live stream is active, test LL-HLS playback using a supported test player.

To test LL-HLS live streams when only **cmafstreamingpacketizer** is enabled, specify the stream playback URL using one of the following formats:

**Single bitrate** https\://\[address]/\[application]/\[application-instance]/\[stream-name]/playlist.m3u8

If **cmafstreamingpacketizer** and **cupertinostreamingpacketizer** are enabled, specify the stream playback URL using one of the following formats:

**Single bitrate** https\://\[address]/\[application]/\[application-instance]/\[stream-name]/playlist\_sfm4s.m3u8

Where:

**\[address]** is the IP address or domain and port (default port 443) **\[application]** is the application name **\[application-instance]** is the name of the application instance (if omitted, defaults to ***definst***) **\[stream-name]** is the stream name So, for example, if only **cmafstreamingpacketizer** is enabled, the playlist URL for an adaptive bitrate LL-HLS stream that uses the address **example.com**, the default **live** application, and the default stream name **myStream** is:

<https://example.com/live/smil:myStream.smil/playlist.m3u8>

If **cmafstreamingpacketizer** and **cupertinostreamingpacketizer** are both enabled, the adaptive bitrate LL-HLS playlist URL for the same example is:

<https://example.com/live/smil:myStream.smil/playlist_sfm4s.m3u8>

and the playback URL for the Cupertino HLS stream is either:

<https://example.com/live/smil:myStream.smil/playlist.m3u8>

or

<https://example.com/live/smil:myStream.smil/playlist_sfts.m3u8>

where **\_sfts** indicates that the media playlist contains .ts segments.

### Configure THEOplayer to play your LL-HLS stream

##### Web SDK

1. Setup a basic HTML file and include the THEOplayer library. You can check: [How to get started with THEOplayer Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md).
2. Specify the LL-HLS stream generated above, as the `src` parameter in your source configuration
3. Set the flag `lowLatency` parameter to TRUE, in your source configuration

```html
<script>
  // LL-HLS
  player.source = {
    sources: [
      {
        src: 'https://5d6e17f1ca731.streamlock.net/LowLatencyBBB/myStream/playlist.m3u8', // set the LL-HLS source
        type: 'application/x-mpegurl', // set the type to HLS
        lowLatency: true,
      },
    ],
  };
</script>
```

## Conclusion

THEOplayer is partnered with Wowza Streaming Engine to fully implement low-latency HLS (LL-HLS) streaming playback.

## Resources

* [Getting Started on Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)

* [Getting Started with Wowza Streaming Engine](https://www.wowza.com/docs/wowza-streaming-engine-product-articles/)

---

# Introduction

This section provides some examples to help with the most common use cases:

## [📄️How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-enable-disable-audio-tracks.md)

[This article describes how you can use the MediaTrack API to enable or disable audio tracks.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-enable-disable-audio-tracks.md)

## [📄️How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-audio-tracks.md)

[This article describes how you can use the API to detect audio tracks.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-audio-tracks.md)

## [📄️How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-select-video-track-quality.md)

[This article describes how you can use the API to select a video track quality. If you select a specific quality, you overrule the ABR algorithm.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-select-video-track-quality.md)

## [📄️How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-qualities.md)

[This article describes how you can use the API to detect video track qualities.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-qualities.md)

## [📄️How to start with a specific quality?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-start-with-specific-quality.md)

[This question is typically asked because developers want their HLS or MPEG-DASH stream to start with a specific rendition of the manifest. They want to implement this use-case to speed up the time-to-first frame, or to serve a better quality to the customer, or to serve a different quality on different platforms.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-start-with-specific-quality.md)

## [📄️How to reduce data usage on mobile devices](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-reduce-data-usage-on-mobile-devices.md)

[Customers that use THEOplayer in mobile web which leverage THEOplayer's preloading capabilities (preload = "auto"), or provide very high qualities, sometimes receive complaints about data usage.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-reduce-data-usage-on-mobile-devices.md)

## [📄️How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-quality-changes.md)

[This article describes how you can use the API to detect video track quality changes.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-quality-changes.md)

## [📄️How to programmatically detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-audio-track-changes.md)

[This article describes how you can use the THEOplayer API to detect audio track quality changes.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-audio-track-changes.md)

---

# How to programmatically enable or disable audio tracks

This article describes how you can use the MediaTrack API to enable or disable audio tracks.

The AudioTrack API, which is a sub-API of the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrack), can be used to implement this functionality. Implementing this functionality is a common use-case for developers who want to build their own UI to toggle audio languages on and off.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            | Yes      |

## Using the AudioTrack API to enable different tracks

As mentioned above, you can use the AudioTrack API to enable or disable an audio track. Once you've programmatically selected a track, you can use its `enabled` property (or method) and set it to `true` or `false`.

### Code examples

The code examples below show how to implement toggling audio tracks. It's advised to disable audio tracks which you don't want to play, in order to avoid issues with overlapping audio.

##### Web SDK

```js
// disable all audio tracks
player.audioTracks.forEach(function (track) {
  track.enabled = false;
});
// enable a specific audio track
player.audioTracks[indexOfRequestedAudioTrack].enabled = true;
```

##### Android (TV) SDK

```java
// disable all audio tracks
for (int i = 0; i < theoplayer.getPlayer().getAudioTracks().length(); i++) {
    theoplayer.getPlayer().getAudioTracks().getItem(i).setEnabled(false);
}
// enable a specific audio track
theoplayer.getPlayer().getAudioTracks().getItem(i).setEnabled(true);
```

##### iOS (/tvOS) SDK

```swift
// disable all audio tracks
for i in 0..<self.player.audioTracks.count {
    var audio = self.player.audioTracks.get(i)
    audio.enabled = true
}
// enable a specific audio track
var desiredAudio = self.player.audioTracks[indexOfRequestedAudioTrack]
desiredAudio.enabled = true
```

##### Roku SDK

Enabling audio tracks:

To set a preferred audio track you can write a function like "setAudioLanguage". This function accepts "language" as a string parameter. It then searches for a specified language in the audio tracks and enables the track if it has a proper language.

```brightscript
function setAudioLanguage(language as String)
  audioTracks = m.player.audioTracks
  for i = audioTracks.count() - 1 to 0 step -1
    if audioTracks[i].language = language then
      audioTracks[i].enabled = true
    else
      audioTracks[i].enabled = false
    end if
  end for
  'required because roku deep-copied roAssociativeArray through fields (pass-by-value)
  'read more: https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow
  m.player.audioTracks = audioTracks
end function
```

## Remarks

The following remarks can help:

* A related article on building a Chromeless UI is located at [How to build a Chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md). This article can help understand why this type of usage of the API can be necessary.

## Resources

The following resources provide more information:

* [MediaTrack API Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrack)
* <https://developer.mozilla.org/en-US/docs/Web/API/AudioTrack/enabled>: the `enabled` property from the AudioTrack interface as documented by MDN.

---

# How to programmatically detect audio tracks

This article describes how you can use the API to detect audio tracks.

The AudioTrack API, which is a sub-API of the MediaTrack API, can be used to implement this functionality. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available audio languages.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            | Yes      |

## Code examples

The code examples below how to implement the detection of audio tracks across SDK.

##### Web SDK

The Web SDK leverages the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrack).

```js
function handleAddTrackEvent(addTrackEvent) {
  var audioTrack = addTrackEvent.track;
}
player.audioTracks.addEventListener('addtrack', handleAddTrackEvent);
```

##### Android (TV) SDK

The Android SDK leverages the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrackList).

```java
EventListener<AddTrackEvent> handleAddTrackEvent= new EventListener<AddTrackEvent>() {
    @Override
    public void handleEvent(AddTrackEvent addTrackEvent) {
        MediaTrack audioTrack = addTrackEvent.getTrack();
    }
};
tpv.getPlayer().getAudioTracks().addEventListener(AudioTrackListEventTypes.ADDTRACK, handleAddTrackEvent);
```

##### iOS (/tvOS) SDK

The iOS SDK leverages the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/MediaTrackList).

```swift
func handleAddTrackEvent(addTrackEvent : AddTrackEvent) {
    var audioTrack = addTrackEvent .track
}
self.theoplayer.audioTracks.addEventListener(type: AudioTrackListEventTypes.ADD_TRACK, listener: handleAddTrackEvent)
```

##### Roku SDK

Snippet below allows you to detect added audio tracks. In this example, we have used the `addedaudiotrack` event to propagate information about audio tracks. Basically, all we have to do is to add an event listener.

```brightscript
function Init()
  ...
  m.THEOplayer.callFunc("addEventListener", "addedaudiotrack", "onAudioTracksChanged")
  ...
end function

function onAudioTracksChanged()
  audioTracks = m.player.audioTracks
  ? "Audio tracks changed."
  ? audioTracks
end function
```

## Remarks

* A related article on building a Chromeless UI is located at [How to build a Chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md).

## Related articles

* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-qualities.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-quality-changes.md)
* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-enable-disable-audio-tracks.md)
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-select-video-track-quality.md)

---

# How to programmatically select a video track quality

This article describes how you can use the API to select a video track quality. If you select a specific quality, you overrule the ABR algorithm.

The VideoTrack API, which is a sub-API of the MediaTrack API, can be used to implement this functionality. Implementing this functionality is a common use-case for developers who want to build their own UI to toggle a specific video quality.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |

## Code examples

The code examples below show how to implement selecting video track qualities across SDKs.

##### Web SDK

The Web SDK leverages the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrack).

```js
// enable a specific video track quality
player.videoTracks[0].targetQuality = player.videoTracks[0].qualities[indexOfRequestedVideoTrackQuality];

// do ABR on a set of qualities
player.videoTracks[0].targetQuality = [
  player.videoTracks[0].qualities[indexOfRequestedVideoTrackQuality1],
  player.videoTracks[0].qualities[indexOfRequestedVideoTrackQuality2],
];

// set to default ABR algorithm
player.videoTracks[0].targetQuality = null;
```

##### Android (TV) SDK

The Android SDK leverages the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrackList).

```java
// enable a specific video track quality
theoplayer.getPlayer().getVideoTracks().getItem(0).setTargetQuality(theoplayer.getPlayer().getVideoTracks().getItem(0).getQualities().getItem(indexOfRequestedVideoTrackQuality));

// do ABR on a set of qualities
ArrayList<VideoQuality> selectedVideoQualities = new ArrayList<>();
selectedVideoQualities.add(theoplayer.getPlayer().getVideoTracks().getItem(0).getQualities().getItem(0));
selectedVideoQualities.add(theoplayer.getPlayer().getVideoTracks().getItem(0).getQualities().getItem(1));
theoplayer.getPlayer().getVideoTracks().getItem(0).setTargetQualities(selectedVideoQualities); // ABR algorithm only executed to qualities belonging to selectedVideoQualities

// set to default ABR algorithm
theoplayer.getPlayer().getVideoTracks().getItem(0).setTargetQualities(Collections.emptyList());
```

##### iOS (/tvOS) SDK

For HESP streams:

```swift
let videoTrack = player.videoTracks[0]
videoTrack.targetQualities = [videoTrack.qualities[indexOfRequestedVideoTrackQuality]]
// or
videoTrack.targetQualities = [videoTrack.qualities[0], videoTrack.qualities[1]]
```

For HLS streams:

The iOS SDK leverages the [ABR API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/ABRConfiguration). The underlying AVFoundation stack, which THEOplayer has to use, brings along the technical limitation that you cannot select a specific video quality. Instead, you can set a maximum resolution or bitrate.

```swift
// set preferred peak bitrate
self.theoplayer.abr.preferredPeakBitRate = 200000

// self.theoplayer.abr.preferredPeakBitRate = nil // removes any bitrate limitation

// preferredMaximumResolution supported starting from iOS 11 and above
// self.theoplayer.abr.preferredMaximumResolution = CGSize(width: 1280, height: 720)
// self.theoplayer.abr.preferredMaximumResolution = CGSize.zero // removes any resolution limitation
```

## Remarks

* A related article on building a Chromeless UI is located at [How to build a Chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md).

## Related articles

* [How to programmatically detect video track qualities](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-qualities.md)
* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-audio-tracks.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-quality-changes.md)
* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-enable-disable-audio-tracks.md)

---

# How to programmatically detect video track qualities

This article describes how you can use the API to detect video track qualities.

The VideoTrack API, which is a sub-API of the MediaTrack API, can be used to implement this functionality. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available video track qualities.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |

## Code examples

The code examples below how to implement the detection of video track qualities across SDK.

##### Web SDK

The Web SDK leverages the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrack).

```js
function handleAddTrackEvent(addTrackEvent) {
  var videoTrackQualities = addTrackEvent.track.qualities;
}
player.videoTracks.addEventListener('addtrack', handleAddTrackEvent);
```

##### Android (TV) SDK

The Android SDK leverages the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrackList).

```java
EventListener<AddTrackEvent> handleAddTrackEvent = new EventListener<AddTrackEvent>() {
    @Override
    public void handleEvent(AddTrackEvent addTrackEvent) {
        QualityList videoTrackQualities = addTrackEvent.getTrack().getQualities();
    }
};
tpv.getPlayer().getVideoTracks().addEventListener(VideoTrackListEventTypes.ADDTRACK, handleAddTrackEvent);
```

##### iOS (/tvOS) SDK

```swift
player.videoTracks.addEventListener(type: VideoTrackListEventTypes.ADD_TRACK, listener: { addTrackEvent in
    guard let videoTrack = addTrackEvent.track as? VideoTrack else { return }
    for i in 0..<videoTrack.qualities.count {
        let quality = videoTrack.qualities[i]
        var msg = "Quality added: bandwidth = \(quality.bandwidth)"
        if let videoQuality = quality as? VideoQuality {
            msg.append(", width = \(videoQuality.width), height = \(videoQuality.height)")
        }
        print(msg)
    }
})
```

## Remarks

* A related article on building a Chromeless UI is located at [How to build a Chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md).

## Related articles

* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-audio-tracks.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-quality-changes.md)
* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-enable-disable-audio-tracks.md)
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-select-video-track-quality.md)

---

# How to start with a specific quality?

This question is typically asked because developers want their HLS or MPEG-DASH stream to start with a specific rendition of the manifest. They want to implement this use-case to speed up the time-to-first frame, or to serve a better quality to the customer, or to serve a different quality on different platforms.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | No      | No       | Yes            | N/A            |

## Code examples

##### Web SDK

```js
var player = new THEOplayer.Player(element, playerConfig);
player.videoTracks.addEventListener('addtrack', function (e0) {
  player.videoTracks[0].targetQuality = player.videoTracks[0].qualities[0]; // start with a specific quality
  player.addEventListener('progress', attachABRResetLogic);
});

function attachABRResetLogic() {
  if (player.buffered.length > 0) {
    // switch to normal ABR when THEOplayer buffered beyond 10 seconds
    if (player.buffered.end(player.buffered.length - 1) > 10) {
      player.videoTracks[0].targetQuality = null;
      player.removeEventListener('progress', attachABRResetLogic);
    }
  }
}

player.source = {
  sources: [
    {
      src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
    },
  ],
};
```

Use the `targetQuality` property to pass on an array of qualities. THEOplayer will only be able to render qualities belonging to this array through its ABR algorithm. Viewers can still select the quality through the quality selector.

When the `addtrack` event is dispatched, THEOplayer has not yet started buffered, so you can adjust the `targetQuality`. The `targetQuality` property allows you to specify a set of qualities that THEOplayer can use for ABR selection. THEOplayer will have to select the set quality if only one quality is provided. You reset the ABR selection by setting `targetQuality` to null.

##### Android SDK

```java
private Player theoplayer;
private TimeRanges buffered;

theoplayer.getVideoTracks().addEventListener(VideoTrackListEventTypes.ADDTRACK, new EventListener<AddTrackEvent>() {
    @Override
    public void handleEvent(AddTrackEvent addTrackEvent) {
        theoplayer.getVideoTracks().getItem(0).setTargetQuality(theoplayer.getVideoTracks().getItem(0).getQualities().getItem(0));
        theoplayer.addEventListener(PlayerEventTypes.PROGRESS, new EventListener<ProgressEvent>() {
            @Override
            public void handleEvent(ProgressEvent progressEvent) {
                attachABRResetLogic();
            }
        });
    }
});
private void attachABRResetLogic() {
    theoplayer.requestBuffered(result -> buffered = result);
    if (buffered.length() > 0){
        //Switch to normal ABR when THEOplayer buffered beyond 10 seconds
        if (buffered.getEnd(buffered.length() - 1) > 10) {
            theoplayer.getVideoTracks().getItem(0).setTargetQuality(null);
            theoplayer.removeEventListener(PlayerEventTypes.PROGRESS, new EventListener<ProgressEvent>() {
                @Override
                public void handleEvent(ProgressEvent progressEvent) {
                    attachABRResetLogic();
                }
            });
        }
    }
}
```

## Remarks

* This is not possible on iOS (and with DRM streams in MacOS Safari) due to the fact that playback control on the Apple HLS-playback pipeline is very limited.

## Resources

* [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrack)

---

# How to reduce data usage on mobile devices

Customers that use THEOplayer in mobile web which leverage THEOplayer's preloading capabilities (`preload = "auto"`), or provide very high qualities, sometimes receive complaints about data usage.

You can combat this by leveraging the [ABR API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/ABRConfiguration) and the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrack).

## Step-by-step guide

### 1. Set the ABR targetBuffer property to lower number of seconds

You can set the `player.abr.targetBuffer` property, which allows you to configure the amount of seconds to buffer ahead of the current playback position. The standard buffer time is 20 seconds. Setting a lower number (e.g.: 6 seconds) allows you to download less information in front of the playhead position. This value is also employed when preloading content.

#### Web SDK

The snippet below sets the targetBuffer to 6 seconds.

```js
player.abr.targetBuffer = 6;
```

If necessary add a mobile check like this:

```js
if (THEOplayer.videojs.browser.IS_ANDROID || THEOplayer.videojs.browser.IS_IOS || ... ) {
    player.abr.targetBuffer = 6;
}
```

This snippet leverages THEOplayer's Video.js component.

#### Android SDK

The snippet below sets the targetBuffer to 6 seconds.

```java
theoplayer.getPlayer().getAbr().setTargetBuffer(6);
```

#### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

The iOS SDK does not allow you to change the targetBuffer. The iOS SDK's ABR API only allows you to change the ABRStrategyType.

### 2. Manage preloading

Preloading is a powerful feature when trying to reduce the Join Time. It is more effective in some situations than others and managing it correctly will help you reduce the data usage:

* preloading a live stream may entail appending in the buffer information that will never be played, if the user waits enough time before clicking "Play"
* in those situations when a user is not yet likely to be playing a stream (e.g.: the player is not yet in view), preloading may also mean downloading information that the user will not consume.

So, based on your use case, you might decide whether to enable preloading. The following snippets showcase how to do so.

#### Web SDK

```js
player.preload = 'auto'; // "metadata" is also a valid value
```

#### Android SDK

```java
theoplayer.getPlayer().setPreload(PreloadType.AUTO);
```

#### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

```swift
theoplayer.setPreload(.auto)
```

### 3. Choose the renditions considered for ABR

On mobile devices, THEOplayer by default takes into account the player size for ABR: this lets it avoid selecting renditions too big to be appreciated on the current device, thus avoiding wasting data. As of THEOplayer 5.7, it is also possible to configure the SourceAbrConfiguration property `restrictToPlayerSize` which also replicates this behavior on laptop/desktop browsers.

Leveraging the `targetQuality` property of the MediaTrack API, you can refine the rendition choice further and indicate yourself to the player which qualities should be considered for ABR. For example, you could configure that THEOplayer should only do ABR on the lowest 3 qualities of a stream containing 5.

For further information about both strategies, please check the documentation linked below.

## Conclusion

There are several actions that can be taken to drastically reduce data usage on mobile devices, both in the player and at other levels. As far as the player is concerned, by leveraging its API as described you can filter different use cases and handle several aspects related to media download for each use case. This enables you to manage the precise behavior in each case and optimize data usage.

## Related articles

* [How to start with a specific quality?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-start-with-specific-quality.md)
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-select-video-track-quality.md)
* [Web SDK API reference: restrictToPlayerSize](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SourceAbrConfiguration#restrictToPlayerSize)
* [Preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/preloading.md)

---

# How to programmatically detect video track quality changes

This article describes how you can use the API to detect video track quality changes.

The VideoTrack API, which is a sub-API of the MediaTrack API, can be used to implement this functionality. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available video track qualities.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |

## Code examples

The code examples below how to implement the detection of video track qualities across SDK.

##### Web SDK

The Web SDK leverages the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrack).

```js
// detect video tracks being added to the player
player.videoTracks.addEventListener('addtrack', function (e0) {
  // detect quality changes of a track
  e0.track.addEventListener('activequalitychanged', function (e1) {
    console.log('activequalitychanged event detected!', e1);
  });
});
```

##### Android (TV) SDK

The Android SDK leverages the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrackList).

```java
EventListener<AddTrackEvent> handleAddTrackEvent = new EventListener<AddTrackEvent>() {
    EventListener<ActiveQualityChangedEvent> handleActiveQualityChangedEvent = new EventListener<ActiveQualityChangedEvent>() {
        @Override
        public void handleEvent(ActiveQualityChangedEvent activeQualityChangedEvent) {
            System.out.println("activequalitychanged event detected! " + activeQualityChangedEvent.getQuality().toString());
        }
    };
    @Override
    public void handleEvent(AddTrackEvent addTrackEvent) {
        addTrackEvent.getTrack().addEventListener(VideoTrackEventTypes.ACTIVEQUALITYCHANGEDEVENT, handleActiveQualityChangedEvent);
    }
};
tpv.getPlayer().getVideoTracks().addEventListener(VideoTrackListEventTypes.ADDTRACK, handleAddTrackEvent);
```

##### iOS (/tvOS) SDK

```swift
player.videoTracks.addEventListener(type: VideoTrackListEventTypes.ADD_TRACK, listener: { addTrackEvent in
    guard let videoTrack = addTrackEvent.track as? VideoTrack else { return }
    videoTrack.addEventListener(type: MediaTrackEventTypes.ACTIVE_QUALITY_CHANGED, listener: { qualityChangeEvent in
        let quality = qualityChangeEvent.quality
        var msg = "Quality changed: bandwidth = \(quality.bandwidth)"
        if let videoQuality = quality as? VideoQuality {
            msg.append(", width = \(videoQuality.width), height = \(videoQuality.height)")
        }
        print(msg)
    })
})
```

## Remarks

* A related article on building a Chromeless UI is located at [How to build a Chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md).

## Related articles

* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-audio-tracks.md)
* [How to programmatically detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-quality-changes.md)
* [How to programmatically enable or disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-enable-disable-audio-tracks.md)
* [How to programmatically select a video track quality](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-select-video-track-quality.md)

---

# How to programmatically detect audio track changes

This article describes how you can use the THEOplayer API to detect audio track quality changes. An audio track "change" is triggered by enabling (or disabling) an audio track.

The AudioTrack API provides this functionality. More specifically, as a developer, you'll subscribe to the `change` event in the AudioTrack API.

Implementing this functionality is a common use-case for developers who want to build their own UI, and annotate the audio track that is currently active.

## SDKs

THEOplayer allows you to track audio track changes on the following SDKs.

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |          |

## Implementation

The AudioTrack API is available across all of our base SDKs. As described in the introduction, to detect text track changes, you want to detect the `change` event in the `AudioTrack` API.

* [Web SDK](#web-sdk)
* [Android SDK](#android-sdk)
* [iOS SDK](#iostvos-sdk-and-legacy-iostvos-sdk-412x)
* [Roku SDK](#roku-sdk)

### Web SDK

The implementation of the Web SDK applies to all web-based platforms, including Tizen and webOS.

The Web SDK exposes the AudioTrack API through [`player.audioTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#audiotracks). This `audioTracks` property is a [`MediaTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrackList) that inherits from the [`TrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackList). This `TrackList` dispatches the events from the [`TrackListEventMap`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackListEventMap). This `TrackListEventMap` contains the [`change`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackListEventMap#change) event, as well as the `addtrack` and `removetrack` event.

The code below allows you to detect text track changes.

```js
player.audioTracks.addEventListener('change', function (event) {
  const track = event.track;
  console.log(track, track.label, track.language, track.enabled);
});
```

The properties of a media `track` (e.g. `enabled`, `language`) are described in [the `MediaTrack` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrack).

### Android SDK

The implementation of the Android SDK applies to all Android-based platforms, including Android TV and Fire TV.

The Android SDK exposes the AudioTrack API through [`player.getAudioTracks()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#getAudioTracks--). This `getAudioTracks()` method returns a [`MediaTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrackList) that inherits from the [`TrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/TrackList). This `TrackList` dispatches the events from the [`AudioTrackListEventTypes`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/mediatrack/audio/list/AudioTrackListEventTypes). The `AudioTrackListEventTypes` contains the [`TRACKLISTCHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/mediatrack/audio/list/AudioTrackListEventTypes#TRACKLISTCHANGE) event, as well as the `ADDTRACK` and `REMOVETRACK` event.

The code below allows you to detect audio track changes.

```java
player.getAudioTracks().addEventListener(AudioTrackListEventTypes.TRACKLISTCHANGE, trackListChangeEvent -> {
    MediaTrack track = trackListChangeEvent.getTrack();
    System.out.println(track.getLabel() + ", " + track.getLanguage() + ", " + track.isEnabled());
});
```

The properties of a media `track` (e.g. `enabled`, `language`) are described in the [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/mediatrack/MediaTrack) and [`Track`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/Track) API references.

### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

The implementation of the iOS SDK applies to all iOS-based platforms, including iPadOS and tvOS.

The iOS SDK exposes the AudioTrack API through [`player.audioTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C11audioTracksAA14AudioTrackList_pvp). This `audioTracks` property is a [`MediaTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/MediaTrackList). This `MediaTrackList` dispatches the events from the [`AudioTrackListEventTypes`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/AudioTrackListEventTypes). The `AudioTrackListEventTypes` contains the [`CHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/AudioTrackListEventTypes#/s:13THEOplayerSDK24AudioTrackListEventTypesV6CHANGEAA0F4TypeCyAA0d6ChangeF0CGvpZ) event, as well as the `ADD_TRACK` and `REMOVE_TRACK` event.

The code below allows you to detect audio track changes.

```swift
player?.audioTracks.addEventListener(type: AudioTrackListEventTypes.CHANGE, listener: { (event) in
    let track : AudioTrack = event.track as! AudioTrack
    print(track.label, track.language, track.enabled)
})
```

The properties of a media `track` (e.g. `enabled`, `language`) are described in the [`MediaTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/MediaTrack) and [`Track`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/Track) API references.

### Roku SDK

*This subsection is in maintenance. Reach out to our team if you need help.*

# Related articles

Are you reading this article because you're interested in audio tracks? Continue reading below.

* [How to programmatically detect audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-audio-tracks.md)
* [How to enable and disable audio tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-enable-disable-audio-tracks.md)

Are you reading this article because you're implementing a custom UI? Then you'll find the following articles interesting:

* [How to build a Chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md)
* [How to detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-quality-changes.md)
* [How to detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-detect-text-track-changes.md)

---

# Introduction

In this section, you can find guides on how to use many of the player features not addressed in other sections of this documentation.

## [📄️Related Content](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/related-content.md)

[The article in this section describes how to implement common use-cases related to the Related Content feature. This feature adds a component to the UI which enables viewers to navigate to related content. Developers can configure the related content using the exposed Related API.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/related-content.md)

## [📄️Social Sharing](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/social-sharing.md)

[This article describes how to implement common use cases related to Social Sharing feature.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/social-sharing.md)

## [📄️Up Next](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/up-next.md)

[This article describes how to implement common use cases related to the Up Next feature - for example how to use the API.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/up-next.md)

## [📄️VR](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/vr.md)

[This article describes how to implement common use cases related to VR / 360 - for example how to use the API.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/vr.md)

## [📄️Web Audio](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/webaudio.md)

[THEOplayer provides a Web Audio API, which allows you to do some quite nifty stuff with the player's audio output. If you are unfamiliar with the ideas behind Web Audio API, Mozilla has an excellent intro to the basic ideas you need to know about here. This guide will help you set up a demo just like the one we have in our Demo Zone.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/webaudio.md)

## [📄️Clipping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/clipping.md)

[THEOplayer supports playing only a selected part of a video-on-demand stream, rather than playing it from start to finish. This can be used for example to watch a single game-changing event from a sports match, highlight an important part of a long video presentation, or skip straight to the best part of a song's video clip.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/clipping.md)

## [📄️Picture-in-Picture](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/picture-in-picture.md)

[This guide explains what Picture-in-Picture (PiP) is, describes how to implement it and links relevant resources.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/picture-in-picture.md)

## [📄️Using hlsDateRange property](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/using-hlsdatarange-property.md)

[This article explains how to enable the DateRange feature, so that a text track and cues are created.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/using-hlsdatarange-property.md)

## [📄️Preloading](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/preloading.md)

[This article contains a description of the possible preloading settings and will show you how to use them on your player. This is possible on Web, Android and iOS SDKs. The aim of preloading is to improve user experience by loading parts of the video before the Play button is hit when the user is likely to play the video.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/preloading.md)

## [📄️Saving the progress of a caching task in iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/saving-cachingtask-progress-ios.md)

[This guide explains how to save the progress of an ongoing caching task and what the limitations of the iOS platform are.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/saving-cachingtask-progress-ios.md)

## [🗃Context menu](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/context-menu/introduction.md)

[3 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/context-menu/introduction.md)

## [⚠️Error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/error/introduction.md)

[3 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/error/introduction.md)

---

# Related Content

The article in this section describes how to implement common use-cases related to the Related Content feature. This feature adds a component to the UI which enables viewers to navigate to related content. Developers can configure the related content using the exposed Related API.

![Related Content](/pr-932/assets/images/related-content-3e4e890814aa918323d0bf9fee9fb216.png "Related Content")

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | No          | Yes     | No       | No             | N/A            |

The Related Content API is a UI feature. It's currently unavailable on the Android (TV) SDK because the underlying THEOplayer CSS and JavaScript modules aren't activated. This means that you also can't enable it on the Android (TV) SDK by following the guide located at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

## Code examples

##### Web SDK

The Related Content API was first released on THEOplayer's Web SDK.

* Reference API: [Related-Content API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/RelatedContent)
* Online demo: <https://demo.theoplayer.com/related-content>

```js
player.related.sources = [
  {
    image: '//cdn.theoplayer.com/video/vr/poster.jpg',
    title: 'Experience true 360/VR in THEOplayer',
    duration: '2:14',
    link: '//demo.theoplayer.com/vr-and-360',
  },
  {
    image: '//cdn2.hubspot.net/hubfs/2163521/Demo_zone/CaminandesLlamaDramaPoster.jpg',
    title: '4K Streaming with THEOplayer',
    duration: '1:30',
    link: '//demo.theoplayer.com/4k',
  },
  {
    image: '//cdn.theoplayer.com/video/sintel/poster.jpg',
    title: 'Optimally present your content with chapter markers',
    duration: '1:30',
    link: '//demo.theoplayer.com/chapters',
  },
  {
    image: '//localhost/server/azure.jpg',
    title: 'Keep THEOplayer visible with picture-in-picture',
    duration: '1:30',
    link: '//demo.theoplayer.com/chapters',
  },
  {
    image: '//cdn.theoplayer.com/video/big_buck_bunny/poster.jpg',
    title: 'THEOplayer: Advertisements Tester (VAST, VPAID, VMAP)',
    duration: '9:57',
    link: '//demo.theoplayer.com/chapters',
  },
  {
    image: '//cdn2.hubspot.net/hubfs/2163521/Demo_zone/tears_of_steel_poster.jpg',
    title: 'CEA Closed Captions and Subtitles With THEOplayer',
    duration: '12:14',
    link: '//demo.theoplayer.com/closed-captions-subtitles',
  },
  {
    title: 'Go Big Screen With THEOplayer and Chromecast',
    link: '//demo.theoplayer.com/chromecast',
    duration: '9:57',
    image: '//cdn.theoplayer.com/video/big_buck_bunny/poster-alt1.jpg',
  },
  {
    title: 'Effortless casting with THEOplayer and AirPlay',
    link: '//demo.theoplayer.com/airplay',
    duration: '9:57',
    image: '//cdn.theoplayer.com/video/big_buck_bunny/poster-alt2.jpg',
  },
  {
    title: 'DRM and AES-128 content protection with THEOplayer',
    link: '//demo.theoplayer.com/drm-aes-128-encryption',
    duration: 'LIVE',
    image: '//cdn.theoplayer.com/video/big_buck_bunny/poster-alt3.jpg',
  },
];

player.addEventListener('ended', function () {
  if (!player.related.showing) {
    setTimeout(function () {
      player.related.show();
    }, 1000);
  }
});
```

##### Android (TV) SDK

This API is currently not available on the Android (TV) SDK.

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

The Related Content API is available on the iOS SDK, but not on the tvOS SDK. This feature can be used as below:

```swift
//Prerequisite: You would need THEOplayer iOS SDK enabled with Related Content feature.

//create a variable to declare related content sources to the player.
var relatedContent = self.theoplayer?.related

//Create an array variable with your related content sources.
var relatedSources = [RelatedContentSource]()
                relatedSources.append(RelatedContentSource(image: "https://cdn.theoplayer.com/video/vr/poster.jpg", source: sampleSource1, title: "xxx"))

                relatedSources.append(RelatedContentSource(image: "https://cdn.theoplayer.com/video/sintel/poster.jpg", source: sampleSource2, title: "xxx"))

                relatedSources.append(RelatedContentSource(image: "https://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg", source: sampleSource3, title: "xxx"))

                relatedSources.append(RelatedContentSource(image: "https://cdn2.hubspot.net/hubfs/2163521/Demo_zone/tears_of_steel_poster.jpg", source: sampleSource4, title: "xxx"))

                relatedSources.append(RelatedContentSource(image: "https://cdn.theoplayer.com/video/vr/poster.jpg", source: sampleSource5, title: "xxx"))

                relatedSources.append(RelatedContentSource(image: "https://cdn.theoplayer.com/video/vr/poster.jpg", source: sampleSource6, title: "xxx"))

//Add the relatedSources array to the created relatedContent variable.
relatedContent?.sources = relatedSources

// Example of Source to the player defined in above relatedSources
var sampleSource1: SourceDescription {
  let src = "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8"
  let stream = "application/x-mpegurl"
    return SourceDescription(
            source: TypedSource(
                src: src,
                type: stream

            ))
    }
```

* Reference DEMO APP: [iOS Related Content Demo APP](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Related-Content)
* Reference API: [iOS Related Content API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/RelatedContent)

## Important Note

The Related Content API is limited to show a maximum of 15 tiles only. By default, it is set to show only 6 even if more than 6 are added to the player source. To show case more than 6 sources, below CSS code needs to be added to make the `<div>` scrollable. To add external CSS files to your iOS Project, refer to the related articles.

```css
.theo-related-grid {
  height: 100% !important;
  overflow-y: scroll !important;
}

.theo-related-grid-tile {
  display: block !important;
}
```

## Related articles

* [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)

---

# Social Sharing

This article describes how to implement common use cases related to Social Sharing feature.

The Social Sharing feature adds a component to the UI which enables the viewers to share the page across media, for example through Twitter and Facebook.

The Social Sharing feature exposes the Social API. This API allows developers to configure the URLs and (social) channels.

![Social Sharing](/pr-932/assets/images/social-sharing-92115ada8662968068768f40ccf41832.png "Social Sharing")

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | No          | No      | No       | No             | N/A            |

The Social Sharing API is a UI feature. It's currently unavailable on all SDKs except the Web SDK because the underlying THEOplayer CSS and JavaScript modules aren't activated. This means that you also can't enable it using the guide located at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

## Code examples

##### Web SDK

The Social Sharing API is currently only available on the Web SDK.

* Reference API: [Social Sharing API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SocialSharing)
* Online demo: [Social Sharing Demo](https://demo.theoplayer.com/social-sharing)

```js
player.social.url = 'https://demo.theoplayer.com/social-sharing';
player.social.items = [
  {
    label: 'Facebook',
    icon: 'https://facebookbrand.com/wp-content/themes/fb-branding/prj-fb-branding/assets/images/fb-art.png',
    src: 'http://www.facebook.com/sharer/sharer.php?u=<URL>',
  },
  {
    label: 'Twitter',
    icon: 'https://s-media-cache-ak0.pinimg.com/originals/f3/6f/51/f36f511b261596a2debe85d844bb1b87.png',
    src: 'http://twitter.com/intent/tweet?url=<URL>',
  },
  {
    label: 'Reddit',
    icon: 'https://vignette3.wikia.nocookie.net/hayday/images/1/10/Reddit.png/revision/latest?cb=20160713122603',
    src: 'http://www.reddit.com/submit?url=<URL>',
  },
  {
    label: 'Direct link',
    src: 'http://demo.theoplayer.com/social-sharing',
  },
  {
    label: 'Embed',
    text: '<iframe width="640" height="360" src="http://demo.theoplayer.com/social-sharing" frameborder="0" allowfullscreen>\n</iframe>',
  },
];
```

##### Android (TV) SDK

This API is currently not available on the Android (TV) SDK.

##### iOS (/tvOS) SDK

This API is currently not available on the iOS (/tvOS) SDK.

## Related articles

* [Why does the Network API not work on iOS devices?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-does-network-api-not-work-on-ios-devices.md)

---

# Up Next

This article describes how to implement common use cases related to the Up Next feature - for example how to use the API.

The Up Next feature adds a component to the UI which enables the viewers to navigate to the upcoming asset, but also automatically loads this asset. This can be useful if you want to increase the engagement and consumption of your users.

The Up Next feature exposes the Up Next API. This API allows developers to configure the upcoming asset and its loading settings.

![Up Next](/pr-932/assets/images/up-next-b95f9436365130312d8f0070857eceaa.png "Up Next")

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | No          | No      | No       | No             | N/A            |

## How to use the Up Next API

The Up Next API is a UI feature and automatically loads upcoming content. Since it loads new web pages (and not just changes the video source), it is not relevant for other environments than web.

## Code Examples

This example explains how you do a basic implementation of the Up Next API.

#### Web SDK

The Up Next API is currently only available on the Web SDK.

* Reference API: [Up Next API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/Player#upnext)
* Online demo: [Up Next Demo](https://www.theoplayer.com/theoplayer-demo-up-next)

The snippet below demonstrates how you could configure the Up Next API.

```js
player.upnext.source = {
  image: '//cdn.theoplayer.com/video/vr/poster.jpg',
  title: '360/VR in THEOplayer',
  duration: '2:14',
  link: '//demo.theoplayer.com/vr-and-360',
};
player.upnext.bar.offset = 106;
```

#### Android SDK

This API is currently not available on the Android (TV) SDK.

#### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

This API is currently not available on the iOS (/tvOS) SDK.

## Sample Application

The demo below illustrates the Up Next API in production.

* Demo: <https://www.theoplayer.com/theoplayer-demo-up-next>

## Remarks

The Up Next API is currently unavailable on all SDKs except the Web SDK, because the underlying THEOplayer CSS and JavaScript modules aren't activated. This means that you also can't enable it using the guide located at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

## Resources

The following resources provide more information:

* [Up Next API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/Player#upnext)

---

# VR

This article describes how to implement common use cases related to VR / 360 - for example how to use the API.

The VR feature enables video to be rendered in a VR / 360 - experience. The input should be a video source in an equirectangular format, and the output is a container where viewers can navigate around the scene.

The VR feature exposes the VR API. This API allows developers to change the pitch, direction and more.

## 360 / VR

360-degree video is a type of video where every angle from a single viewpoint is recorded and can played back. It offers a great sense of immersion for panoramic imagery or simulation purposes.

THEOplayer allows you to render these videos in your browser or on your mobile device, with a full set of API controls to control the viewing direction.

Next to the spherical or 360° video playback, THEOplayer also offers integration with VR devices through stereoscopic view, dubbed "stereo mode".

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | No\*        | No\*    | No       | No             | No             |

\* VR is currently not supported in the native Android and iOS SDKs. Please reach out to us for VR support on the native SDKs.

## Configuration

### Initialization

#### Web SDK

The Web SDK uses the [WebXR API](https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API) for virtual reality playback. For platforms that do not natively support WebXR, you can add the [WebXR polyfill](https://github.com/immersive-web/webxr-polyfill) to your web page.

> **Bug in official polyfill**
>
> The official polyfill has a bug in its rendering, see [issue 167](https://github.com/immersive-web/webxr-polyfill/issues/167). Our team has already [proposed and submitted a fix](https://github.com/immersive-web/webxr-polyfill/pull/168), but this fix has not yet been published in a new release of the polyfill.
>
> In the meantime, you can use a patched build from our CDN. We highly recommend you to download and host this build on your own web server, since it will no longer be available once the official polyfill has been fixed.

Add the polyfill to your page:

```html
<script src="//cdn.theoplayer.com/webxr/webxr-polyfill-patched.js"></script>
```

And enable it:

```js
const POLYFILL_CONFIG = {
  allowCardboardOnDesktop: true,
};
new WebXRPolyfill(POLYFILL_CONFIG);
```

To indicate that your stream contains 360° content, pass a valid `VRConfiguration` as `vr` property when setting `player.source`.

For the full list of properties and events related to 360° video and VR, go to our [API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VR) page.

```js
var element = document.querySelector('.theoplayer');
var player = new THEOplayer.Player(element, {
  fluid: true,
});

player.vr.useDeviceMotionControls = true;

player.source = {
  sources: {
    type: 'application/x-mpegurl',
    src: 'http://example.com/example-stream.m3u8',
  },
  vr: {
    360: true,
  },
};
```

### Manipulating the viewing direction within a 360 video

Below you can find an example querying the VR viewing direction and one setting the viewing direction.

#### Web SDK

```js
/* reading the current position */
var currentViewingDirection = player.vr.direction; // e.g. {pitch: 0, yaw: 0, roll: 0}

/* setting the position */
player.vr.direction = { pitch: 0, yaw: 180, roll: 0 };

/* example of how you can update only one direction property */
var currentViewingDirection = player.vr.direction; /* e.g. {pitch: 0, yaw: 30, roll: 0} */
currentViewingDirection.pitch = 180; /* {pitch: 180, yaw:30, roll: 0} */
player.vr.direction = currentViewingDirection;
```

### Setting stereoMode

#### Web SDK

The snippet below enables stereo mode by setting the `stereoMode` variable to `horizontal`/`vertical`.

```js
player.source = {
  sources: [
    {
      src: 'http://example.com/example-stream.m3u8',
      type: 'application/x-mpegurl',
    },
  ],
  vr: {
    360: true,
    stereoMode: 'horizontal', // or 'vertical'
  },
};
```

### Listening to VR related events

The following code sample listens to `stereochange` and `directionchange` events thrown by THEOplayer and stores the new values in a variable.

#### Web SDK

```js
player.vr.addEventlistener('stereochange', () => {
  const isStereoEnabled = player.vr.stereo; // (boolean)
  // do something with it
});

player.vr.addEventlistener('directionchange', () => {
  const { yaw, roll, pitch } = player.vr.direction; // (object)
  // do something with it
});
```

## Request Permissions

Since iOS 13, access to device orientation and motion data is disabled by default. You will need to include code to request the necessary permission, triggered by a user action.

You can do this by using the following function to handle a user interaction triggered event

```js
function requestPermissions() {
  DeviceMotionEvent.requestPermission()
    .then((response) => {
      if (response == 'granted') {
        window.addEventListener('devicemotion', (e) => {
          console.log('Device motion permissions granted');
        });
      }
    })
    .catch(console.error);
  DeviceOrientationEvent.requestPermission()
    .then((response) => {
      if (response == 'granted') {
        window.addEventListener('deviceorientation', (e) => {
          console.log('Device orient permissions granted');
        });
      }
    })
    .catch(console.error);
}
```

## Sample Application

The following demo illustrates the VR API in production for Web SDK: <https://www.theoplayer.com/theoplayer-demo-virtual-reality-360-degree-view>

## Remarks

When trying to use the `StereoMode` functionality, the device must have the automatic rotation feature enabled.

---

# Web Audio

THEOplayer provides a [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API), which allows you to do some quite nifty stuff with the player's audio output. If you are unfamiliar with the ideas behind Web Audio API, Mozilla has an excellent intro to the basic ideas you need to know about [here](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API). This guide will help you set up a demo just like the one we have in our [Demo Zone](https://demo.theoplayer.com/web-audio-api).

To use this API, be sure to have the `webaudio` feature included in your THEOplayer SDK.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | No          | No      | No       | No             | No\*           |

(\*) can be investigated upon request

## How to use the Web Audio API

The first thing you need is a valid THEOplayer set-up. If you have no experience with setting up our player, we have an excellent [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md). In the following sections, we will assume that you have just created a THEOplayer instance and bound it to the variable 'player'.

## Code Examples

This example explains how you do a basic implementation of the Web Audio API.

##### Web SDK

**A very basic Web Audio graph**

```js
// The very first step in working with Web Audio is to create an AudioContext. This can be achieved as follows:
var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();

// Once you have an AudioContext, you can create an AudioNode which contains the player's audio output:
var sourceNode = player.audio.createAudioSourceNode(audioCtx);

// If we stop now, the result is that the player's audio will be piped into the graph, but will not be connected to any outputs,
// resulting in no sound output from your speakers/headphones.
// The next step to get it working again would be:
sourceNode.connect(audioCtx.destination);

//Which will result in the audio being output again.
```

**Playing with the audio gain**

Of course, this is not a very useful use of the Web Audio API, since essentially we are doing nothing with the audio. A first thing we could do is play with the gain, i.e. manipulate the player volume by using the Web Audio API.

```js
var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
var sourceNode = player.audio.createAudioSourceNode(audioCtx);
var gainNode = audioCtx.createGain();
sourceNode.connect(gainNode);
gainNode.connect(audioCtx.destination);
```

This sets up a gain filter on top of the player audio output, which we can manipulate using the gainNode.gain.value property. An example would be that we could set up a callback which monitors mouse movement:

```js
var updatePage = function (e) {
  gainNode.gain.value = (screen.height - e.screenY) / screen.height;
};

document.onmousemove = updatePage;
```

The callback will be executed every time the mouse position is updated. The result will be that the gain will be adjusted to be equal to the ratio of the distance of the mouse pointer position from the bottom of the screen (in pixels) and the screen height. So the farther you move the mouse pointer down, the quieter the output of the video will become, and the opposite effect when you move the mouse pointer up.

**Playing with stereo panning**

Similarly, we can play with the stereo panning of the player audio output. This can be achieved by playing with the pan.value property of the StereoPanner node.

```js
var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
var sourceNode = player.audio.createAudioSourceNode(audioCtx);
var pannerNode = audioCtx.createStereoPanner();
sourceNode.connect(pannerNode);
pannerNode.connect(audioCtx.destination);

var updatePage = function (e) {
  pannerNode.pan.value = (2 * e.screenX) / screen.width - 1;
};

document.onmousemove = updatePage;
```

The result is that moving the pointer left and right changes the stereo panning of the player audio, with balanced audio at the exact middle of the screen, pan all the way to the left when the pointer's on the left edge, and pan all the way right when the pointer's on the right edge.

**Double audio trouble**

We can also do both things at the same time. The way Web Audio works allows us to pipe the output of one node as input for another node (in most cases). This way, we can combine the two tricks we were doing before into one trick: modifying the volume by moving the mouse pointer up and down, and modifying the panning by moving the mouse left and right. This is achieved by the following code:

```js
var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
var sourceNode = player.audio.createAudioSourceNode(audioCtx);
var gainNode = audioCtx.createGain();
var pannerNode = audioCtx.createStereoPanner();
sourceNode.connect(pannerNode);
pannerNode.connect(gainNode);
gainNode.connect(audioCtx.destination);

var updatePage = function (e) {
  gainNode.gain.value = (screen.height - e.screenY) / screen.height;
  pannerNode.pan.value = (2 * e.screenX) / screen.width - 1;
};

document.onmousemove = updatePage;
```

**Bringing it all together**

The next step we can take is to create a simple demo where we manipulate the audio of two players simultaneously. Assume that we have two players set up, bound to variables player1 and player2. Then we can set up exactly the same audio pipeline for both players, and reroute their audio to a single output.

```js
var sourceNode1 = player1.audio.createAudioSourceNode(audioCtx);
var gainNode1 = audioCtx.createGain();
var pannerNode1 = audioCtx.createStereoPanner();
sourceNode1.connect(pannerNode1);
pannerNode1.connect(gainNode1);
gainNode1.connect(audioCtx.destination);

var sourceNode2 = player2.audio.createAudioSourceNode(audioCtx);
var gainNode2 = audioCtx.createGain();
var pannerNode2 = audioCtx.createStereoPanner();
sourceNode2.connect(pannerNode2);
pannerNode2.connect(gainNode2);
gainNode2.connect(audioCtx.destination);
```

**Inverting the behavior**

And at this point, we can do some more complex tricks. We can actually do the same thing as we did in the previous section, except that we can do the inverse for the second player's audio. That is, we can make moving the mouse pointer up decrease the volume for the second player, and we can invert the panning as well. This can be achieved with the following callback:

```js
var updatePage = function (e) {
  gainNode1.gain.value = (screen.height - e.screenY) / screen.height;
  pannerNode1.pan.value = (2 * e.screenX) / screen.width - 1;
  gainNode2.gain.value = e.screenY / screen.height;
  pannerNode2.pan.value = 1 - (2 * e.screenX) / screen.width;
};

document.onmousemove = updatePage;
```

##### Android SDK

This API is currently not available on the Android (TV) SDK.

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

This API is currently not available on the iOS (/tvOS) SDK.

## Sample Applications

The demo below illustrates the Web Audio API in production.

* Demo: <https://demo.theoplayer.com/web-audio-api>

## Remarks

The following remarks can help:

* The web Audio API is currently unavailable on all SDKs except the Web SDK.

* If your use case would require this feature to work on the Chromecast SDK, let us know and we’ll look into customizing a receiver in order to enable Web Audio on it.

## Resources

The following resources provide more information:

* [Basic Guide to Web Audio API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/basic-guide-web-audio-api.md)
* [MDN - Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)

---

# Clipping

THEOplayer supports playing only a selected part of a video-on-demand stream, rather than playing it from start to finish. This can be used for example to watch a single game-changing event from a sports match, highlight an important part of a long video presentation, or skip straight to the best part of a song's video clip.

## SDKs

| Web SDK | Android SDK                  | iOS SDK                      | tvOS SDK                     | Android TV SDK               | Chromecast SDK |
| ------- | ---------------------------- | ---------------------------- | ---------------------------- | ---------------------------- | -------------- |
| Yes     | Through JavaScript injection | Through JavaScript injection | Through JavaScript injection | Through JavaScript injection | No\*           |

## How to use the Clip API

The Clip API helps you configure a clip within your content. This allows you to only show a certain part of a video.

The start and end of the clipping window can be controlled through the Clip API:

* `startTime` and `endTime`, expressed in seconds

These properties are optional, and you don't need to specify both `startTime` and `endTime`. For example, you can set just `startTime = 30` to have the video start at 30 seconds and play the rest of the video normally.

## Code Examples

##### Web SDK

The following example shows a video clipped to start at 30 seconds and end at 60 seconds.

```js
player.source = {
    sources : [{
        src : '//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8', // sets source
        type : 'application/x-mpegurl' // sets correct type for current source (HLS)
    }],
    ...
    };

// In this example, the clipping is applied in an event listener to make sure it doesn't get called before the source is set
player.addEventListener("durationchange", function() {
        player.clip.startTime = 30;
        player.clip.endTime = 60;
});
```

##### Legacy Android SDK (4.12.X)

This is currently possible through JavaScript injection in your Android project. Find out more about this in the article [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

##### Legacy iOS/tvOS SDK (4.12.x)

This is currently possible through JavaScript injection in your iOS project. Find out more about this in the article [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

## Remarks

* The event listener in the provided code sample is not strictly necessary, but it ensures that the clipping is applied after the source is set. If your source has not been set or is being set but the process is not complete, clipping will not have any effect.

## Resources

* [Clip API Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Clip)
* [Blog article](https://www.theoplayer.com/blog/frame-accurate-clipping-in-hls)
* [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)

---

# Picture-in-Picture

This guide explains what Picture-in-Picture (PiP) is, describes how to implement it and links relevant resources.

The Picture-in-Picture feature allows developers to create a floating player. This is commonly used to let the video remain playing on screen even if:

* The user scrolls to another section of the page (causing the original player to no longer be visible).
* The user sends the application to the background.
* The user opens a new page within the same application.

## SDKs

The below table makes a comparison of the available THEOplayer APIs specifically targeting in or out of app PiP use cases. This table does not represent the possibilities on the platforms with THEOplayer.

| Type            | Web SDK | Android SDK | Android TV SDK | iOS SDK | tvOS SDK | Roku SDK | Fire TV SDK | Chromecast SDK |
| --------------- | ------- | ----------- | -------------- | ------- | -------- | -------- | ----------- | -------------- |
| **in-app**1     | Yes     | No3         | No3            | Yes     | No       | No       | No3         | N/A            |
| **out-of-app**2 | No      | Yes         | Yes            | Yes     | Yes      | No       | Yes         | N/A            |

1 While using in-app picture-in-picture, the visibility of the PiP window is contained to the inside of the app. In other words, it will go to background/foreground with the application.

2 While using out-of-app picture-in-picture, the visibility of the PiP windows is not contained to the inside of the app. It can remain visible while the user navigates to other views, pages or apps.

3 On Android/Fire TV SDK, there is no API to explicitly only allow in-app PiP. The existing [PiP API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/pip/package-summary) activates both in and out of app PiP.

## How to use Picture-in-Picture

Picture-in-Picture is an interesting option on both desktop and mobile to keep showing the video while the user navigates to different parts of the content. PiP in THEOplayer presents several possibilities: this section shows how to enable, configure and observe the Picture-in-Picture option for all available SDKs. A distinction is made between in-app and out-of-app Picture-in-picture, where in the latter the PiP-window can also remain visible if the application is sent to background or another view is presented.

## Code Examples

### Enable Picture-In-Picture mode

##### Web SDK

In this SDK, PiP is enabled by default if the player configuration contains any PiP configuration (see below image). For this reason, there is no need to use any specific snippet to enable it. Note that in this SDK out-of-app Picture is (currently) not supported.

![Picture-in-Picture](/pr-932/assets/images/picture-in-picture-778462f302e24a4b44a176d0fa345cd1.png "Picture-in-Picture")

The PiP configuration for this SDK includes 3 properties:

* `position`: (optional, possible values: "top-left", "top-right", "bottom-left", "bottom-right")<br />The corner in which the player should be shown while in PiP mode. Defaults to the bottom right corner.

* `visibility`: (optional, a number from 0 to 1)<br />The maximum percentage of the original player position that should be visible to enable PiP automatically. If not configured, PiP can only be turned on by setting [presentationMode](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/PresentationMode) to "picture-in-picture".

* `retainPresentationModeOnSourceChange`: (optional, possible values: true or false)<br />If set to true, the previous [presentationMode](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/PresentationMode) is retained even as the source changes. It is set to false by default.

```js
var playerConfig = {
  /* ... */
  pip: {
    visibility: 0.7,
    position: 'bottom-left',
    retainPresentationModeOnSourceChange: true,
  },
};
```

##### Android / Fire TV SDK

If you want to use Picture-In-Picture in your application you can instantiate the player with a PiPConfiguration, to be passed in the THEOplayerConfig. When passing a PipConfiguration, the Android SDK will **always** make use of out-of-app PiP.

Note that to make use of out-of-app PiP the minimum required Android version is Oreo (API level 26).

```kotlin
val playerConfig = THEOplayerConfig.Builder()
    .pipConfiguration(PipConfiguration.Builder().build())
    .build()

val tpv = THEOplayerView(context, playerConfig)
```

Once the Picture-In-Picture mode is enabled, the player's *pip* property can be accessed.

To enable PiP mode with the required PiP type, you can utilize the following steps:

1. **Access the PiP Manager:** Begin by accessing the PiP manager associated with your `THEOplayerView`. This manager reference is available through the `theoPlayerView`.

2. **Invoke `enterPiP()`:** Call the `enterPiP(PiPType.ACTIVITY)` method on the PiP manager. By doing so, you initiate PiP mode using the `ACTIVITY` PiP type.

Here's the implementation:

```kotlin
theoPlayerView.piPManager?.enterPiP(PiPType.ACTIVITY)
```

THEOplayer supports three PiP types:

* **ACTIVITY** This mode generates a separate Android activity that functions as the PiP window.

* **DIALOG** In this mode, a dialog window is utilized as the PiP window. The video content is displayed within the dialog.

* **CUSTOM** Unlike the predefined PiP types, `CUSTOM` empowers you as the developer to design and implement your own PiP window. You have the flexibility to tailor the PiP experience to your app's specific requirements. For details on implementing a custom PiP window, explore this [Android documentation](https://developer.android.com/develop/ui/views/picture-in-picture).

##### iOS / tvOS SDK

If you want to use Picture-In-Picture in your application you can instantiate the player with a PiPConfiguration, to be passed in the THEOplayerConfiguration. Using this PiPConfiguration you can configure whether the player should retain its presentation mode upon source-change. You can also choose whether to make use of out-of-app PiP (=`nativePictureInPicture`). Note that to make use of out-of-app PiP the minimum required iOS version is 14.0.

```swift
/* Configure whether presentation mode should be retained on source changes and whether to use native PiP */
let pipConfig = PiPConfiguration(retainPresentationModeOnSourceChange: true, nativePictureInPicture: true)
let playerConfig = THEOplayerConfiguration(... , pip: pipConfig)
var theoplayer = THEOplayer(configuration: playerConfig)
```

Once the Picture-In-Picture mode is enabled, the player's *pip* property can be accessed.

While using **in-app** PiP you can use the *configure(movable:defaultCorner:)* method of the player's *pip* property to configure the picture-in-picture.

You can configure:

* whether the PiP view is movable or not (default to true);

* the default corner of the PiP view (default to bottom right);

```swift
theoplayer.pip!.configure(movable: false, defaultCorner: .bottomLeft)
```

Notes:

* `configure` is only available when using in-app PiP.
* tvOS only supports in-app PiP, which is **enabled by default** if the OS version supports it (minimum tvOS 14.0).
* iPadOS 14.0 (and above) also supports in-app PiP.

### Observe events in Picture-In-Picture

##### Android SDK

For the Android SDK it is possible to listen for a `PlayerEventTypes.PRESENTATIONMODECHANGE` event or verify the presentationMode of the player in case you need to find out what the presentation mode is at a given moment or detect a change.

```kotlin
// Assuming you have an instance of the player called 'theoplayer'
theoplayer.addEventListener(PlayerEventTypes.PRESENTATIONMODECHANGE) { event ->
    val currentMode = event.presentationMode
    if (currentMode == PresentationMode.PICTURE_IN_PICTURE) {
        // Currently in PiP
    }
}

// The listener above will be triggered by one of:
theoPlayerView.piPManager?.enterPiP(PiPType.ACTIVITY)
theoPlayerView.piPManager?.exitPiP()
```

###### Returning from PiP Mode: Playback Behavior

###### 1. **ACTIVITY PiPType:**

When your app uses the `ACTIVITY` PiP type and the user closes the PiP window, the playback and its restoration follows these steps:

* **Playback Pausing:** Upon returning from PiP mode, playback is automatically paused, provided that `theoPlayerView.settings.setAllowBackgroundPlayback(false)` is set to false (which is the default setting).

* **Resuming Playback:** To resume playback, check whether your app's activity is in the foreground. If it is, call the `play()` method on the player instance.

Here's a code snippet demonstrating how to resume playback after exiting PiP mode:

```kotlin
theoPlayer.addEventListener(PlayerEventTypes.PRESENTATIONMODECHANGE) {
    if (it.presentationMode == PresentationMode.INLINE) {
        // Playback pauses after closing PiP window
        if (lifecycle.currentState == Lifecycle.State.STARTED) {
            theoPlayerView.player.play()
        }
    }
}
```

###### 2. **DIALOG PiPType:**

For the `DIALOG` PiP type, in order to correctly exit PiP window you should override `onPictureInPictureModeChanged` and call `piPManager.exitPiP()`.

```kotlin
override fun onPictureInPictureModeChanged(
    isInPictureInPictureMode: Boolean,
    newConfig: Configuration
) {
    super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)

    if (!isInPictureInPictureMode) {
        theoPlayerView.piPManager?.exitPiP()
    }
}
```

This example ensures that playback pauses if an Activity that holds THEOplayer is in the background and background playback is not allowed, providing a smoother transition for users returning from PiP mode.

###### 3. **CUSTOM PiPType:**

For the `CUSTOM` PiP type, you are responsible for implementing your own PiP window and handling the necessary tasks for entering and exiting PiP mode.

Managing playback after returning from PiP mode is in your hands as a developer. You can reference the provided code snippet for the `ACTIVITY` type as a starting point and adapt it to match your app's unique design and logic.

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

###### in-app Picture in Picture

Using the notification center you can listen to the *PictureInPictureMoved* notification. This notification will be pushed every time the picture-in-picture view moves to a different corner.

In the callback, you can retrieve the previous and the new corner in the userInfo dictionary respectively with the *PictureInPictureOldCornerUserInfoKey* and the *PictureInPictureNewCornerUserInfoKey* keys.

```swift
NotificationCenter.default.addObserver(self, selector: #selector(onPiPMoved), name: Notification.Name.PictureInPictureMoved, object: nil)

@objc func onPiPMoved(notif: Notification) {
    let userInfo = notif.userInfo as! [String: Any]
    let oldCorner : PictureInPictureCorner = userInfo[PictureInPictureOldCornerUserInfoKey]! as! PictureInPictureCorner
    let newCorner : PictureInPictureCorner = userInfo[PictureInPictureNewCornerUserInfoKey]! as! PictureInPictureCorner
    print("PiP has moved from \(oldCorner) to \(newCorner)")
}
```

###### out-of-app Picture in Picture

By using your own implementation of the [AVPictureinpictureControllerDelegate](https://developer.apple.com/documentation/avkit/avpictureinpicturecontrollerdelegate) you are able to listen to a number of events. These contain, but are not limited to, when the player will enter/exit PiP, has entered/exited PiP, ... To achieve this you just have to set your implementation of the delegate as the one of the [PictureInPictureController](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/PictureInPicture).

```swift
class CustomPiPDelegate: NSObject, AVPictureInPictureControllerDelegate {
    func pictureInPictureControllerDidStartPictureInPicture(_ pictureInPictureController: AVPictureInPictureController) {
        // Custom action when picture in picture started
    }
    // ... Others here.
}

let customDelegate = CustomPiPDelegate()
var THEOPiP = theoplayer?.pip
if #available(iOS 14.0, *) {
    THEOPiP?.nativePictureInPictureDelegate = customDelegate
} else {
    // Fallback on earlier versions
}
```

## Sample applications

### Web SDK

A demo of this feature can be found at

* <https://demo.theoplayer.com/picture-in-picture>

To see PiP in action, start the video and scroll down on the page.

### Android SDK

A sample app for Picture-In-Picture could be found here:

* <https://github.com/THEOplayer/samples-android-sdk/tree/master/pip-handling>

## Remarks

The following remarks can help:

* PiP is a presentation mode of the player. As such, you can listen for a *presentationmodechange* event or verify the presentationMode of the player in case you need to find out what the presentation mode is at a given moment or detect a change.

* More details of the `PresentationMode` types can be found here: [Web PresentationMode API Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/PresentationMode)

* This feature is not completely the same on all SDKs, as the options may vary.

* On the Web SDK, support for native picture in picture (i.e, where the player is draggable) is experimental and whilst support is widely adopted, the feature is most notably not supported by FireFox.

## Known Limitations

* iOS: VR360 is not supported in combination with PiP.
* iOS: Only SSAI is supported, no CSAI (both are supported for Android)
* iOS: No support for sideloaded textTracks.
* Android TV: A limitation from the Android Framework - When the player is showing a native Google IMA advertising while being in Picture-in-Picture mode and the user triggers something which moves the PiP window (such as opening the keyboard) then the view showing the advertisement might be misaligned.

## Resources

The following resources provide more information:

##### Web SDK

* [PipConfiguration API Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PiPConfiguration)
* [PlayerConfiguration API Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerConfiguration)

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

* [PipConfiguration API Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/PiPConfiguration)
* [PictureInPicture API Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/PictureInPicture)

##### Android SDK

* [PipConfiguration API Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/pip/PipConfiguration.Builder)
* [PiPManager API Reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/pip/PiPManager)

---

# Using hlsDateRange property

This article explains how to enable the DateRange feature, so that a text track and cues are created.

The EXT-X-DATERANGE tag associates a Date Range (i.e., a range of time defined by a starting and ending date) with a set of attribute/value pairs

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | N/A      | Yes            | N/A            |

## Instructions

`#EXT-X-DATERANGE` is a way of providing timed metadata in an HLS manifest. It is used to define date range metadata in a media playlist. A possible use case is defining timed metadata for interstitial regions such as advertisements, but can be used to define any timed metadata needed by your stream.

`#EXT-X-DATERANGE` is supported in THEOplayer as of 2.61.0. However, the feature is not enabled by default. To enable it, add *hlsDateRange* to the player configuration and set it to true. You can also choose (instead) to enable/disable the feature per source by adding the same option to a source in your source description.

##### Web SDK

```js
//in playerConfiguration
var element = document.querySelector('.theoplayer-container');

var player = new THEOplayer.Player(element, {
  libraryLocation: libraryLocation,
  license: 'your-license-here',
  hlsDateRange: true,
});

//in the source description
player.source = {
  hlsDateRange: true,
  sources: {
    src: 'Example-Stream.m3u8',
    type: 'application/x-mpegurl',
  },
};
```

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
//in playerConfiguration
func setupTheoPlayer() {
    var frame: CGRect = UIScreen.main.bounds
    frame.size.height = 350
    let stylePath1 = Bundle.main.path(forResource:"style1", ofType: "css")!
    let scriptPath = Bundle.main.path(forResource:"script1", ofType: "js")!
    //Add here at the end of playerConfig
    let playerConfig = THEOplayerConfiguration(defaultCSS: true, cssPaths:[stylePath1, stylePath2], jsPaths: [scriptPath], googleIMA: true, hlsDateRange: true)
    self.theoplayer = THEOplayer(configuration: playerConfig)
    self.theoplayer.frame = frame
    self.theoplayer.addAsSubview(of: playerView)
}

//in the source description
SourceDescription(
    source: TypedSource(
    src: src,
    type: stream,
    hlsDateRange: true
)
```

##### Android SDK

```java
//in playerConfiguration
THEOplayerConfig playerConfig = new THEOplayerConfig.Builder()
        .ui(new UIConfiguration.Builder().language("nl").build())
        .hlsDateRange(true)
        .build();
THEOplayerView tpv = new THEOplayerView(this, playerConfig);
```

The TextTrack API is used to retrieve the timed metadata. A MetadataTextTrack will provide cues which contain the timed metadata and will dispatch an event when started and ended.

## Using and interacting with date-range variables

##### Web SDK

```js
function handleTimedMetadata(player, onTimeMetadataEnter, onTimeMetadataExit) {
  console.log('function handleTimedMetadata is starting! yeeee');
  const onTrackAdded = (event) => {
    const track = event.track;
    console.log('track', track.kind, track.cues);
    if (track.kind !== 'metadata') {
      return;
    }
    track.mode = 'hidden'; // By default, tracks are disabled and do not expose cues
    track.addEventListener('addcue', onCueAdded);
    track.addEventListener('removecue', onCueRemoved);
  };
  const onTrackRemoved = (event) => {
    const track = event.track;
    if (track.kind !== 'metadata') {
      return;
    }
    track.removeEventListener('addcue', onCueAdded);
    track.removeEventListener('removecue', onCueRemoved);
  };
  const onCueAdded = (event) => {
    const cue = event.cue;
    console.log('cueadded', cue);
    cue.addEventListener('enter', onTimeMetadataEnter);
    cue.addEventListener('exit', onTimeMetadataExit);
  };
  const onCueRemoved = (event) => {
    const cue = event.cue;
    cue.removeEventListener('enter', onTimeMetadataEnter);
    cue.removeEventListener('exit', onTimeMetadataExit);
  };
  player.textTracks.addEventListener('addtrack', onTrackAdded);
  player.textTracks.addEventListener('removetrack', onTrackRemoved);
}
handleTimedMetadata(
  player,
  (event) => console.log('Do something with timed metadata starting', event),
  (event) => console.log('Do something with metadata ending', event)
);
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x) and Android

To be added

## Resources

HLS spec. : <https://tools.ietf.org/html/draft-pantos-hls-rfc8216bis-04#section-4.4.2.7>

---

# Preloading

This article contains a description of the possible preloading settings and will show you how to use them on your player. This is possible on Web, Android and iOS SDKs. The aim of preloading is to improve user experience by loading parts of the video before the Play button is hit when the user is likely to play the video.

At the bottom, you will be able to find interesting Resources on this topic.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | N/A            |

## How to use preloading

Choosing to preload your video content will reduce the start-up time of your videos. It will also make some data regarding the current source (video duration, timeline thumbnails, etc.) available before the user initiates playback. On the other hand, when the video is less likely to be played, or when it is less beneficial (live video; autoplay) you can configure the player to not preload it and save bandwidth. Here is how.

### Preloading settings

| Value    | Description                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| none     | Do not preload anything. After setting the source, the player will not load the manifest nor any media files until the play method is invoked on the player.                                                                                                                                                                                                                                   |
| metadata | Preload the metadata of the video. After setting the source, the player will automatically load the manifest file and will wait for loading media files until the play method is invoked on the player. For static videos (e.g. MP4 files), this translates to preloading data from the start of the video in order to acquire e.g. the video's width and height and the initial video frames. |
| auto     | Preload enough data to allow for smooth initial playback. After setting the source, the player will load both the manifest files and enough media files until a sufficient playback buffer has been obtained.                                                                                                                                                                                  |

## Code examples

##### Web SDK

In this example, we are preloading metadata only.

```js
player.preload = 'metadata';
```

##### Android SDK

To activate preload, you need to import the player preloadType:

```java
import com.theoplayer.android.api.player.PreloadType;
```

You can then choose the option you prefer:

```java
   tpv = new THEOplayerView(this);
   ...
   tpv.getPlayer().setPreload(PreloadType.METADATA, callbackHandler);
```

Here, `callbackHandler` is a method to establish which actions are to be taken when preloading has been successfully completed.

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

To use preloading

```swift
self.theoplayer?.setPreload(.metadata)
```

## Sample Applications

The demo below illustrates the Preload API in production.

* Demo: <https://demo.theoplayer.com/preloading-vod>

## Remarks

* THEOplayer will always prefer downloading data for the currently playing video over downloading data for a preloading video. Only when the currently playing video has enough data to play to the end of the video, will the player start preloading other videos.
* When preloading the first segment(s) (preload `auto`), the first frame of the video will be shown under the Big Play Button, if there is no poster.

## Resources

* [What are the benefits of preloading?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/what-are-the-benefits-of-preloading.md)
* [API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/PreloadType)
* [HTML5 specification](https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-preload)
* [API reference: Cache API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Cache)

---

# Saving the progress of a caching task in iOS

This guide explains how to save the progress of an ongoing caching task and what the limitations of the iOS platform are.

The THEOplayer iOS SDK provides the capability to pause an ongoing task. Doing so will store the file state of the partially downloaded stream to disk, and allow the task to be resumed even after the application runtime has been terminated. Note: See [CachingTask](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/CachingTask) for the `pause()` method.

## Code Examples

The code example below demonstrates how to save the progress of ongoing caching tasks upon app termination from the app delegate.

```swift
import THEOplayerSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
	...
    ...

    func applicationWillTerminate(_ application: UIApplication) {
        for task in THEOplayer.cache.tasks {
            if task.status == .loading {
                task.pause()
            }
        }
    }

    ...
    ...
```

Alternatively, Apple's [NotificationCenter](https://developer.apple.com/documentation/foundation/notificationcenter) provides an observer to receive app termination events:

```swift
import THEOplayerSDK

NotificationCenter.default.addObserver(self, selector: #selector(willTerminate), name: UIApplication.willTerminateNotification, object: nil)

...
...

@objc func willTerminate() {
    for task in THEOplayer.cache.tasks {
        if task.status == .loading {
            task.pause()
        }
    }
}
```

## Limitations

The THEOplayer iOS SDK allows the caching task to continue while running in the background, however, control in the background thread is limited and the termination signal falls short as noted in this [article](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623111-applicationwillterminate).

---

# Introduction

This section gives you the answer to the following questions:

* [How to disable the right click?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/context-menu/how-to-disable-right-click.md)
* [How to change the context menu?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/context-menu/how-to-change-context-menu.md)

---

# How can we disable the right click?

There are 2 ways of disabling the right click menu on the player.

1. Disable the context menu feature while you are building your SDK

By default, the `contextmenu` is included between the basic features of Web SDK. If you build your SDK with this feature disabled, your player will not have the context menu.

2. Add a CSS rule on your page

If you do not want to re-build your player, you can simply add the following CSS rule after calling your THEOplayer `ui.css`. You can add this rule in either: a) in a style element (see below) or b) in an external style.

See example:

```html
<link rel="stylesheet" type="text/css" href="/path/to/ui.css" />

<style>
  .theo-context-menu {
    display: none;
  }
</style>
```

---

# How to change the context menu

This question is typically asked by developers who want to change the logo in the context menu, change the default text or add some items.

The snippet below does exactly that.

```js
function customizeContextMenu(container) {
  var contextMenu = container.querySelector('.theo-context-menu');

  // change context menu text
  var contextMenuFirstItem = contextMenu.querySelector('.theo-context-version');
  contextMenuFirstItem.innerText = 'Brand X';

  // change mini logo
  var contextLogo = contextMenu.querySelector('.theo-0logo');
  contextLogo.style.backgroundImage = "url('https://image.freepik.com/free-icon/line-logo_318-102660.jpg')";
  contextLogo.style.backgroundSize = 'cover';
  contextLogo.querySelector('svg').style.visibility = 'hidden';

  // add a line
  var contextMenuSecondItem = document.createElement('li');
  contextMenuSecondItem.innerText = '24/07/2018';
  contextMenu.appendChild(contextMenuSecondItem);
}

var element = document.querySelector('.video-container');
var player = new THEOplayer.Player(element, playerConfig);
customizeContextMenu(element);
```

It's important to note that `customizeContextMenu` is immediately called after initializing a THEOplayer instance.

Another common question is to remove the context menu altogether. The context menu can be disabled as it is one of the feature flags you can toggle. You can manage your THEOplayer configuration via [THEOportal](https://portal.theoplayer.com/login)

To verify whether this feature is enabled you can execute the query below.

```js
var contextMenuEnabled = THEOplayer.features.indexOf('contextmenu') > -1;
```

---

# Introduction

We live in an imperfect world, and sometimes things go wrong. A viewer might not be able to watch a video stream for a variety of reasons. Some example reasons are:

* The video stream is unavailable,
* The video stream is not supported on the selected browser,
* The THEOplayer license is incorrectly configured.

**When an issue occurs, an error should be triggered**.

When a fatal playback issue occurs, THEOplayer overlays an error message on top of the video player. This error message indicates to the viewer that playback is unsuccessful. Additionally, THEOplayer exposes information about the error through the THEOplayer API.

The THEOplayer API allows you to detect errors. As a developer, you can use an event handler to catch (and handle) `error` events. This feature (i.e. being able to intercept errors and act on it) may be mandatory to you to achieve a use-case:

* You want to log the error on an analytics stacks,
* You want to replace the default error message of THEOplayer with your own error message,
* ...

THEOplayer associates error codes with errors to categorize types of issues. As a developer, these error codes may help you to log an error on an analytics stack, or may help you to generate a custom error message towards your viewer.

## Related resources

The following resources help you to understand error handling in THEOplayer.

* [How to do error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/error/how-to-do-error-handling.md): this article explains how you use event listeners to intercept the `error` event.
* [Error codes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/error/error-codes.md): this article explains what error codes are, and why they are useful

---

# How to do error handling

As a developer, you could be interested in error handling for any of the following reasons:

* You want to render human-friendly error messages inside the video player. Reading this error message,

  * the user can either remediate the issue by themselves (e.g. by refreshing the page, by checking again in some time, ...),
  * or contact a support service with this error code.

* You want to send error-data to an analytics service. (And this service helps you to identify frequent issues.)

* You want to self-remediate the issue. For example, if a stream is unavailable, they want to retry to load the stream, or load a different stream.

* ...

THEOplayer exposes different types of errors, and they can be accessed and intercepted in different ways.

## SDKs

Error handling is available across platforms and SDKs.

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |

## Intercepting errors

Developers can programmatically interact with errors in two ways:

1. Through an event listener, and attaching an event handler to this listener
2. Through a getter, which holds data when an error has occurred.

### Event Listener

Developers can subscribe to events and attach a callback function. This callback function implements the error handling.

This section describes how to use event handlers for the "top-level", "generic", "player" `error` event. This is the [`error`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#error) event which is dispatched through the `Player` interface. This event is fatal and prevents playback. (There are also `error` events, for example the [`error`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/ChromecastEventMap#error) event which is dispatched through the `Chromecast` interface. You handle these `error` events in the same fashion.)

#### Web

```js
player.addEventListener('error', function (errorEvent) {
  console.log(errorEvent);
});
```

#### Android

```java
theoPlayerView.getPlayer().addEventListener(PlayerEventTypes.ERROR, new EventListener<ErrorEvent>() {
    @Override
    public void handleEvent(ErrorEvent errorEvent) {
        System.out.println(errorEvent.getErrorObject());
    }
});
```

#### iOS

```swift
let listener = self.theoplayer?.addEventListener(type: PlayerEventTypes.ERROR, listener: { error in print(error.error)})
```

### Getter

Developers can query an occurred "generic player error" through the `errorObject` property of its related interface. For example, if the `error` event of the top-level `Player` interface would be dispatched for the Web SDK, then you can access the `errorObject` property of this interface.

```js
player.addEventListener('error', function (errorEvent) {
  // console.log(errorEvent);
  console.log(player.errorObject);
});
```

Note that other types of errors are not available through this approach.

## Types of errors

"[Which error related events does the player expose](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/which-error-related-events-does-player-expose.md)" lists which types of errors there are. Note that generally speaking only the "generic error event" is fatal. Other events, like the "Chromecast error event" and the "ad error event", are considered non-fatal because some type of playback can style continue.

"[Error codes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/error/error-codes.md)" lists which error codes are available for the "generic error event".

## Remarks

* We encourage developers to use event listeners to handle errors.
  * The data in this event can be processed (e.g. stringified) and transferred (e.g. sent to an analytics service).
* You could render your own error messages inside the video player.
  * The article at <http://demo.theoplayer.com/using-custom-error-messages> offers some help on this for the Web SDK.

---

# Error codes

THEOplayer has different types of error events. One of those error events is the "generic player error event". This error event indicates a fatal error, and can be intercepted through the `Player` interface.

This error event exposes an "error code" to explain the occurred error. An error code may be more interesting to track than a verbose error messages For example, if you are logging errors through an analytics service, it could be useful to filter them by their error code.

An error code is a number (e.g. 2001), and it belongs to a category. The format of an error code is "\[category]\[sub-code]". For example, error "2001" belong to category 2, and has sub-code 001.

Refer to "[How to do error handling](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/error/how-to-do-error-handling.md)" to learn how to detect the "generic player error event".

## SDKs

The "generic player error event" is available across platforms and SDKs.

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |

## Categories

Each error code belongs to an error category. At the time of writing, there are 11 categories.

1. Configuration error: the integrator misconfigured the player.
2. License error: the player license is no longer valid, incorrect or not provided.
3. Source invalid: the source is not valid, or cannot be played on the current platform.
4. Manifest load error: the manifest cannot be loaded or parsed.
5. Media not supported: the media cannot be played on the current platform.
6. Network error: the network timed out, or is not available.
7. Content protection error: anything DRM related. Key system is not supported, invalid license, license expired, key missing, output restricted...
8. Subtitle load error: the subtitles cannot be loaded or parsed...
9. VR not supported: VR is not available on the current platform, VR presentation cannot be switched
10. Ad blocker detected: an ad has been blocked (or the third party CSAI library was not loaded)
11. Fullscreen error: switching to fullscreen is not possible (note: this may be the case when fullscreen was not triggered by user interaction)

You can programmatically request the list of available error categories through the THEOplayer API. For example, on the Web SDK, you can access this list through `THEOplayer.ErrorCategory`, as illustrated by the screenshot below.

![ErrorCategory](/pr-932/assets/images/error-code-ErrorCategory-6f53a43777395769d34029b30d5ecade.png "ErrorCategory")

You can also programmatically request the category of an error code through the THEOplayer API. For example, on the Web SDK, you can access this through `THEOplayer.ErrorCategory.fromCode(<errorCode>)`. (Meaning: `THEOplayer.ErrorCategory.fromCode(11000)` would return `11`.)

Relevant API references:

* Web SDK

  * [`ErrorCategory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/enums/ErrorCategory)
  * [`ErrorCategory.fromCode()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/functions/ErrorCategory-1.fromCode)

* Android SDK

  * [`ErrorCategory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/error/ErrorCategory)
  * [`ErrorCategory.fromCode()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/error/ErrorCategory#fromCode\(ErrorCode\))

* iOS SDK
  * [`ErrorCategory`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Enums/ErrorCategory)

## Codes

An error code is prefixed with its category. For example, code `11001` belongs to category `11`, and has sub-code 001. If the error is a generic sub-code for its category, then the sub-code will be `000`. In other words, error `11000` would be the "catch-all" for category `11`.

You can programmatically request the list of all available error codes through the THEOplayer API. For example, on the Web SDK, you can access this through `THEOplayer.ErrorCode`, as illustrated by the screenshot below.

![ErrorCode](/pr-932/assets/images/error-code-ErrorCode-198ffee2db62e071b0f3be03b5e2d95d.png "ErrorCode")

Relevant API references:

* Web SDK
  * [`ErrorCode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/enums/ErrorCode)
* Android SDK
  * [`ErrorCode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/error/ErrorCode)
* iOS SDK
  * `THEOErrorCode`

---

# Introduction

This article explains how to use the Network API.

On iOS browsers, the Network API can only be used to intercept and alter DRM-related requests and responses.

The technical documentation on the Network API can be found [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Network).

## SDKs

| Web SDK | Android SDK | Legacy iOS SDK (4.12.x) | tvOS SDK | Chromecast SDK |
| ------- | ----------- | ----------------------- | -------- | -------------- |
| Yes     | Yes         | Through JS injection    | No       | Yes            |

## Instructions

1. Add/use request interceptor
2. Add/use response interceptor

### 1. Add/use request interceptor

The request interceptor can, as the handle suggests, be used to intercept requests. The method is available under `player.network` and requires a request object. Within the request object, you can change headers, redirect a license request, etc. You can't change the response with this interceptor, because that's covered with the response interceptor below. In the example below, the request interceptor is used to redirect certain URL to another URL.

#### Code examples

##### Web SDK

```js
// Add a request interceptor
player.network.addRequestInterceptor((request) => {
  // The interceptor intercepts ALL requests and we only want to redirect one specific url
  if (request.url == 'https://link-to-specific-url') {
    // Redirect the request
    request.redirect({
      url: 'https://link-to-new-url',
      method: request.method, // Keep the methods the same
      headers: request.headers, // Keep the headers the same
      closed: request.closed,
      useCredentials: request.useCredentials,
      type: request.type,
      subType: request.subType,
      responseType: request.responseType,
      body: request.body,
    });
  }
});
```

##### Android SDK

Follow our [Android Network Interceptor](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/network/android-network-interceptor.md) page.

##### Legacy Android (TV) SDK (4.12.X)

Add the above JavaScript snippet to your legacy Android (TV) SDK project as demonstrated at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

##### Legacy iOS/tvOS SDK (4.12.x)

Add the above JavaScript snippet to your legacy iOS SDK project as demonstrated at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

### 2. Add/use response interceptor

The response interceptor is used to intercept/change responses. You can overwrite any response that the player receives. It is important to respond in the proper format (with JSON, base-64 body, ...)

Like the example above, this example will overwrite a response:

#### Code examples

##### Web SDK

```js
player.network.addResponseInterceptor((response) => {
  // If the response comes from a specific URL
  if (response.url == 'https://specific-url') {
    // Requests run async, therefore make sure to execute after the request is finished
    response.waitUntil((done) => {
      response.respondWith({
        closed: response.closed,
        headers: response.headers,
        request: response.request,
        respondWith: response.respondWith,
        status: 201, // Updated status code as example
        statusText: 'All cool bro', // Updated status text as example
        url: response.url,
        waitUntil: response.waitUntil,
        body: 'New body',
      });
      done();
    });
  }
});
```

##### Android SDK

Follow our [Android Network Interceptor](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/network/android-network-interceptor.md) page.

##### Legacy Android (TV) SDK (4.12.X)

Add the above JavaScript snippet to your legacy Android (TV) SDK project as demonstrated at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

##### Legacy iOS/tvOS SDK (4.12.x)

Add the above JavaScript snippet to your legacy iOS SDK project as demonstrated at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

## HTTP Errors

If the status code is set to a code between 200-299, the player responds with a successful response, in any other cases the player will respond with an HTTP error.

If the player originally responded with an HTTP error, the interceptor can change the response to a successful response and vice versa.

## Adding and Removing Event Listeners

The 'online' and 'offline' events can be added to the network as follows:

`player.network.addEventListener('online', handleOnlineEvent);`

Events can be removed similarly, as follows:

`player.network.removeEventListener('online', handleOnlineEvent);`

## Related articles

* [Why does the Network API not work on iOS devices?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/why-does-network-api-not-work-on-ios-devices.md)

---

# Network Request/Response Interceptors

THEOplayer makes a number of network requests and receives responses while playing content video, these requests and responses can be intercepted to make a new or modified request or respond with a new response. The network object thus allows easy access to handle the network efficiently.

This guide explains how you set up THEOplayer to add and remove request/response interceptors. This document guides you through setting up a demo just like the one that's showcased in our [Demo Zone](https://www.theoplayer.com/demo-zone).

## Prerequisites

This guide expects that you have a THEOplayer license. If you aren't using THEOplayer yet, you can start by registering at THEOportal [here](https://portal.theoplayer.com) to get access to THEOplayer. Be sure to have THEOplayer version 2.21.0 or higher.

## Starting Template

The first thing you need is a valid THEOplayer set-up. If you have no experience with setting up our player, we have an excellent [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md).

To get THEOplayer to work, you only need to do three things:

1. Reference the THEOplayer JavaScript library (and optionally the default CSS styles).
2. Add a container which can hold your video player with HTML.
3. Create your player through JavaScript using our [API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/Player).

A basic HTML page with a working THEOplayer could look like the following:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Web SDK: Getting Started</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" type="text/css" href="/path/to/ui.css" />
  </head>
  <body>
    <div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>
    <script type="text/javascript" src="/path/to/THEOplayer.js"></script>
    <!-- ads THEOplayer library -->
    <script>
      var element = document.querySelector(".theoplayer-container")
      var player = new THEOplayer.Player(element, {
        libraryLocation: '/path/to/libraryLocation/',
        license: 'your_license_here'
      },

      player.source = {
        sources: [
          {
            src: "https://cdn.theoplayer.com/video/sintel/nosubs.m3u8",
            type: "application/x-mpegurl",
          },
        ],
      }
    </script>
  </body>
</html>
```

The two snippets below are the references to the JS and CSS library.

```html
<link rel="stylesheet" type="text/css" href="/path/to/ui.css" />
```

```html
<script type="text/javascript" src="/path/to/THEOplayer.js"></script>
```

The following snippet is your HTML container.

```html
<div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>
```

This snippet initializes your player, including an HLS source.

```html
<script>
  var element = document.querySelector('.theoplayer-container');
  var player = new THEOplayer.Player(element);
  player.source = {
    sources: [
      {
        src: 'https://cdn.theoplayer.com/video/sintel/nosubs.m3u8',
        type: 'application/x-mpegurl',
      },
    ],
  };
</script>
```

## Adding and removing Request Interceptors

Starting from the basic template above, you need to add a `RequestInterceptor` on the network object's addRequestInterceptor method. By adding a request interceptor, the original request made by HTTP can be modified so that specific properties of the original request can be altered to contain the necessary information, before it is sent to the server. The interceptors are added in a stack and the last interceptor to be added is the first one to intercept the original request.

A request interceptor can modify the request with the [`redirect`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/InterceptableRequest#redirect) or [`respondWith`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/InterceptableRequest#respondWith) method.

```js
var interceptor = function (request) {
  if (request.type === 'manifest') {
    request.redirect({
      url: 'https://cdn.theoplayer.com/video/elephants-dream/448/chunklist_w370587926_b688000_vo_slen_t64TWFpbg==.m3u8',
      method: 'GET',
      headers: {
        'Content-Type': 'application/x-mpegurl',
      },
    });
  }
};
```

The code sample above intercepts manifest requests made by the player and redirects them to the provided request URL.

If the properties of the given `RequestInit` object are missing, the API uses the properties values from the original request.

A response to the request can be added in an interceptor as follows:

```js
var interceptor = function (request) {
  if (request.type === 'manifest') {
    request.respondWith({
      body: '#EXTM3U\n#EXTINF:6,\nhttps://cdn.theoplayer.com/video/elephants-dream/448/media_w370587926_b688000_vo_slen_t64TWFpbg==_0.ts\n#EXT-X-ENDLIST',
      status: 200,
      statusText: 'OK',
    });
  }
};
```

The code sample above intercepts manifest requests made by the player and responds with a manifest containing a single segment.

The above defined interceptors can be added to the player as follows:

```js
player.network.addRequestInterceptor(interceptor);
```

Interceptors can be removed similarly, as follows:

```js
player.network.removeRequestInterceptor(interceptor);
```

## Adding and removing Response Interceptors

A `ResponseInterceptor` responds with the given response for the original request.

A `ResponseInterceptor` can be added on the network object's addResponseInterceptor method. By adding a response interceptor, the original response can be modified so that specific properties of the original response can be altered to contain the necessary information, before the server responds. The interceptors are added in a stack and the last interceptor to be added is the first one to intercept the original response.

A ResponseInterceptor can modify the response with the [`respondWith`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/InterceptableResponse#respondWith) method.

```js
var interceptor = function (response) {
  response.respondWith({
    body: '#EXTM3U\n#EXTINF:6,\nhttps://cdn.theoplayer.com/video/elephants-dream/448/media_w370587926_b688000_vo_slen_t64TWFpbg==_0.ts\n#EXT-X-ENDLIST',
    status: 200,
    statusText: 'OK',
  });
};
```

The code sample above intercepts manifest responses received by the player and responds with a manifest containing a single segment. The `respondWith` method accepts a [`ResponseInit`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/ResponseInit) object as its argument.

The above defined interceptor can be added to the player as follows:

```js
player.network.addResponseInterceptor(interceptor);
```

Interceptors can be removed similarly, as follows:

```js
player.network.removeResponseInterceptor(interceptor);
```

## Adding a waitUntil in Request and Response Interceptors

The `waitUntil` method can be used to execute synchronous and asynchronous processes before the `request` or the `response` can be closed. A waitUntil method can throw an error if, for a single Interceptor, a request or a response was already closed.

The waitUntil method can receive one of the following as its argument :

* A Done callback
* A function which returns a promise
* A PromiseLike

#### Done callback

When using a done callback, the waitUntil method needs to wait until the method finishes executing before the request or the response can be closed by calling the done callback. Failing to call this callback may result in the request or the response never being delivered.

The waitUntil method can be defined with a `done` callback as follows

```js
var interceptor = function (request) {
  request.waitUntil(function (done) {
    setTimeout(function () {
      request.redirect({
        url: 'https://cdn.theoplayer.com/video/elephants-dream/448/chunklist_w370587926_b688000_vo_slen_t64TWFpbg==.m3u8',
        method: 'GET',
        headers: modifyRequestHeaders(request.headers),
      });
      done();
    }, 100);
  });
};
```

The code sample above waits for 100 milliseconds before it redirects to another URL and then the done call is executed which means that the request can now be closed.

#### Function returns a promise

When the waitUntil method receives a function that returns a promise, the promise needs to resolve before the request or the response can be closed.

The waitUntil method that receives a function that returns a promise can be defined as follows

```js
var interceptor = function (request) {
  request.waitUntil(function () {
    return delay(100).then(function () {
      request.redirect({
        url: 'https://cdn.theoplayer.com/video/elephants-dream/448/chunklist_w370587926_b688000_vo_slen_t64TWFpbg==.m3u8',
        method: 'GET',
        headers: modifyRequestHeaders(request.headers),
      });
    });
  });
};
```

The code sample above waits for 100 milliseconds before it redirects to another URL after which the request can be closed.

#### PromiseLike

When using a `PromiseLike`, the waitUntil method needs to wait until the provided promise argument resolves before the request or the response can be closed.

The waitUntil method can be defined with a `PromiseLike` as follows

```js
var interceptor = function (request) {
  var promise = delay(100).then(function () {
    request.redirect({
      url: 'https://cdn.theoplayer.com/video/elephants-dream/448/chunklist_w370587926_b688000_vo_slen_t64TWFpbg==.m3u8',
      method: 'GET',
      headers: modifyRequestHeaders(request.headers),
    });
  });
  request.waitUntil(promise);
};
```

The code sample above waits until the modifyRequestHeaders promise is resolved and then the redirect method is executed which means that the request can now be closed.

## HTTP Errors

If the status code is set to a code between 200-299, the player responds with a successful response, in any other cases the player will respond with an HTTP error.

If the player originally responded with an HTTP error, the interceptor can change the response to a successful response and vice versa.

## Adding and Removing Event Listeners

The 'online' and 'offline' events can be added to the network as follows:

```js
player.network.addEventListener('online', handleOnlineEvent);
```

Events can be removed similarly, as follows:

```js
player.network.removeEventListener('online', handleOnlineEvent);
```

---

# Android Network Request/Response Interceptor

THEOplayer Android SDK makes a number of network requests and receives responses while playing video. These requests and responses can be intercepted to make a new or modified request or respond with a new response.

The Network API thus allows easy access to handle the network efficiently.

This guide explains how you set up THEOplayer Android SDK to add and remove request/response interceptors.

## Prerequisites

* This guide expects that you have a THEOplayer license. If you aren't using THEOplayer yet, you can start by registering at THEOportal [here](https://portal.theoplayer.com) to get access to THEOplayer.

* You need to be using at least THEOplayer Android SDK version 5.11.0.

## Set up THEOplayer in your app

To set up THEOplayer Android SDK in your app follow the steps in our [Getting started on Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/android/getting-started.md) guide.

## Adding and removing an interceptor

The THEOplayer Android SDK provides the `HTTPInterceptor` interface which contains 2 methods (`onRequest`, `onResponse`) where each can be optionally implemented based on the use-case.

* `suspend fun onRequest(request: InterceptableHTTPRequest)`: Intercepts an HTTP request before opening the connection.
* `suspend fun onResponse(response: InterceptableHTTPResponse)`: Intercepts an HTTP response before consuming the response body.

To start intercepting HTTP requests, add the interceptor to our Network API:

```kotlin
theoPlayerView.player.network.addHTTPInterceptor(httpInterceptor)
```

To stop intercepting HTTP requests, remove the interceptor from our Network API:

```kotlin
theoPlayerView.player.network.removeHTTPInterceptor(httpInterceptor)
```

## Intercepting a request

The `suspend fun onRequest(request: InterceptableHTTPRequest)` provides a `request` parameter that can be used to read/write properties or to interrupt the request providing a direct response.

In the below snippet, we show some common use-cases.

```kotlin
override suspend fun onRequest(request: InterceptableHTTPRequest) {
    // Read request properties
    Log.d("Interceptor", "onRequest - url: ${request.url}")

    // Add/override request headers
    request.headers["newKey"] = "newValue"

    // Replace properties
    request.method = "GET|POST|.."
    request.url = URL("new_url")
    request.headers = HashMap()

    // Replace POST/PUT request body
    request.body = "new post body".toByteArray()

    // Perform another async computation
    delay(1000) // simulating an async call

    // Interrupt the request and respond with a CompleteHTTPResponse
    request.respondWith(
        CompleteHTTPResponse(
            request,
            request.url,
            request.headers,
            200,
            "OK",
            "new post body".toByteArray()
        )
    )
}
```

## Intercepting a response

The `suspend fun onResponse(response: InterceptableHTTPResponse)` provides a `response` parameter that can be used to read and write properties from the received response.

In the below snippet we show some common use-cases.

```kotlin
override suspend fun onResponse(response: InterceptableHTTPResponse) {
    // Read response properties
    Log.d("Interceptor", "onResponse - headers: ${response.headers}")

    // Add/override response headers
    response.headers["newKey"] = "newValue"

    // Replace properties
    response.url = URL("new_url")
    response.headers = HashMap()
    response.status = 200
    response.statusText = "OK"

    // Get the chunks of the response body as they are read from the HTTP connection
    response.onChunk { chunk: ByteArray ->
        Log.d("Interceptor", "onResponse - onChunk: ${chunk.size}")
        delay(100)
        chunk
    }

    // Read the complete response body
    response.onBody { body: ByteArray ->
        Log.d("Interceptor", "onResponse - onBody: ${body.size}")

        // Read response body
        val string = body.decodeToString()
        val json = JSONObject(string)

        // Perform another async computation
        delay(1000) // simulating an async call

        // Replace response body
        "new response body".toByteArray()
    }
}
```

---

# iOS HLS Media Playlist Interceptor

THEOplayer iOS SDK makes a number of network requests and receives responses while playing video. These requests and responses can be intercepted to make a new or modified request, or respond with a new response to the HLS playlist requests.

This guide explains how you set up THEOplayer iOS SDK to add and remove request/response interceptors.

We will use a simple UIKit UIViewController for this guide.

## Set up THEOplayer

```swift
class ViewController: UIViewController {
    private var player: THEOplayer?

    override func viewDidLoad() {
        super.viewDidLoad()
        let player = THEOplayer()
        self.player = player
        player.frame = view.bounds
        player.addAsSubview(of: self.view)
        player.network.addMediaPlaylistInterceptor(self)
    }
}
```

## Intercepting the requests and/or responses

Use the `type` parameter on each method below to filter for HLS playlist types i.e. master, video, subtitles, etc... The rest of the usage is explained in comments in the code snippet below.

```swift
extension ViewController: MediaPlaylistInterceptor {
    // For modifications that you would make to the request, ie. add custom headers, query parameters, etc...
    func shouldInterceptPlaylistRequest(type: THEOplayerSDK.HlsPlaylistType) -> Bool { true }

    // For modifications that you would make to the response, ie. edit the m3u8 file content, vtt file content etc...
    func shouldInterceptPlaylistResponse(type: THEOplayerSDK.HlsPlaylistType) -> Bool { true }

    // Will be called if shouldInterceptPlaylistRequest returns true
    func didInterceptPlaylistRequest(type: THEOplayerSDK.HlsPlaylistType, request: URLRequest) async throws -> URLRequest {
        var modifiedRequest = request
        // modify
        // ...
        //...
        return modifiedRequest
    }

    // Will be called if shouldInterceptPlaylistResponse returns true
    func didInterceptPlaylistResponse(type: THEOplayerSDK.HlsPlaylistType, url: URL, response: URLResponse, data: Data) async throws -> Data {
        var modifiedResponseData = ""
        // customize the data string that you would like to return, should be a valid HLS playlist file
        // ...
        // ...
        let customDataResponse = modifiedResponseData.data(using: .utf8)
        return customDataResponse ?? data // `customDataResponse` is empty so playback will fail in this demo; return `data` to play
    }

    // Handle failure.
    func failedToPerformURLRequest(request: URLRequest, response: URLResponse) {}
}
```

## DRM request interception

The `MediaPlaylistInterceptor` API does not intercept DRM requests. To intercept FairPlay DRM requests, take a look at the following solution: <https://github.com/THEOplayer/samples-drm-integration/blob/master/ios/README.md>

---

# Introduction

The Player API is the top-level API. This API exposes:

* basic functions to manipulate video playback, such as start and pause;
* properties to check states and values, such as the playhead position;
* events to track changes.

The list below overviews how-to articles related to the Player API.

* [How do you know when a stream or an advertisement is playing?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/how-do-you-know-when-a-stream-or-ad-is-playing.md)
* [How to measure time-to-first-frame](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/how-to-measure-time-to-first-frame.md)
* [How can we track the first play(ing) event?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/how-can-we-track-the-first-playing-event.md)
* [How to track player states](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/how-to-track-player-states.md)

## Events

As a developer, you can programmatically attach event listeners to different APIs. Event listeners are often used to [implement a custom UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md) or to [implement a custom analytics integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/custom-analytics-integration.md).

The THEOplayer API exposes many events across different interfaces, as can be seen in the graphic below. Furthermore, most events exist in all SDKs (Web, iOS-based, Android-based and Roku).

![THEOplayer API Interfaces and Events](/pr-932/assets/images/analytics-events-185d6ab52b556af08d8300b545ae5876.png "THEOplayer API Interfaces and Events")

The table below gives an overview of a subset of the available events per interface in the THEOplayer Web SDK.

| Interface                                                                                                                                    | Event                                                                                                                                                            | Description                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| [Player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap)                          | [canplay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#canplay)                                     | Fired when the player can resume playback of the media data.                                                                                  |
| Player                                                                                                                                       | [canplaythrough](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#canplaythrough)                       | Fired when the player can resume playback of the media data and buffering is unlikely.                                                        |
| Player                                                                                                                                       | [contentprotectionerror](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#contentprotectionerror)       | Fired when an error related to content protection occurs.                                                                                     |
| Player                                                                                                                                       | [contentprotectionsuccess](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#contentprotectionsuccess)   | Fired when the key is usable for decryption.                                                                                                  |
| Player                                                                                                                                       | [currentsourcechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#currentsourcechange)             | Fired when the current source, which is chosen from ChromelessPlayer.source.sources, changes.                                                 |
| Player                                                                                                                                       | [destroy](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#destroy)                                     | Fired when the the player is destroyed.                                                                                                       |
| Player                                                                                                                                       | [dimensionchange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#dimensionchange)                     | Fired when the dimensions of the HTML element changes.                                                                                        |
| Player                                                                                                                                       | [durationchange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#durationchange)                       | Fired when ChromelessPlayer.duration changes.                                                                                                 |
| Player                                                                                                                                       | [emptied](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#emptied)                                     | Fired when the player's source is cleared.                                                                                                    |
| Player                                                                                                                                       | [encrypted](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#encrypted)                                 | Fired when the player encounters key system initialization data in the media data.                                                            |
| Player                                                                                                                                       | [ended](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#ended)                                         | Fired when playback has stopped because the end of the media resource was reached.                                                            |
| Player                                                                                                                                       | [error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#error)                                         | Fired when an error occurs.                                                                                                                   |
| Player                                                                                                                                       | [loadeddata](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#loadeddata)                               | Fired when the player can render the media data at the current playback position for the first time.                                          |
| Player                                                                                                                                       | [loadedmetadata](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#loadedmetadata)                       | Fired when the player determines the duration and dimensions of the media resource.                                                           |
| Player                                                                                                                                       | [loadstart](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#loadstart)                                 | Fired when the player starts loading the manifest.                                                                                            |
| Player                                                                                                                                       | [manifestupdate](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#manifestupdate)                       | Fired when the manifest is updated.                                                                                                           |
| Player                                                                                                                                       | [pause](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#pause)                                         | Fired when ChromelessPlayer.paused changes to true.                                                                                           |
| Player                                                                                                                                       | [play](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#play)                                           | Fired when ChromelessPlayer.paused changes to false.                                                                                          |
| Player                                                                                                                                       | [playing](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#playing)                                     | Fired when playback is ready to start after having been paused or delayed due to lack of media data.                                          |
| Player                                                                                                                                       | [progress](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#progress)                                   | Fired when the player loaded media data.                                                                                                      |
| Player                                                                                                                                       | [ratechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#ratechange)                               | Fired when ChromelessPlayer.playbackRate changes.                                                                                             |
| Player                                                                                                                                       | [readystatechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#readystatechange)                   | Fired when ChromelessPlayer.readyState changes.                                                                                               |
| Player                                                                                                                                       | [representationchange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#representationchange)           | Fired when the current representation changes.                                                                                                |
| Player                                                                                                                                       | [resize](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#resize)                                       | Fired when either ChromelessPlayer.videoWidth or ChromelessPlayer.videoHeight changes.                                                        |
| Player                                                                                                                                       | [seeked](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#seeked)                                       | Fired when ChromelessPlayer.seeking changes to false after the current playback position was changed.                                         |
| Player                                                                                                                                       | [seeking](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#seeking)                                     | Fired when ChromelessPlayer.seeking changes to true, and the player has started seeking to a new position.                                    |
| Player                                                                                                                                       | [segmentnotfound](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#segmentnotfound)                     | Fired when a segment can not be found.                                                                                                        |
| Player                                                                                                                                       | [sourcechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#sourcechange)                           | Fired when ChromelessPlayer.source changes.                                                                                                   |
| Player                                                                                                                                       | [timeupdate](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#timeupdate)                               | Fired when the current playback position changed as part of normal playback or in an especially interesting way, for example discontinuously. |
| Player                                                                                                                                       | [volumechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#volumechange)                           | Fired when ChromelessPlayer.volume changes.                                                                                                   |
| Player                                                                                                                                       | [waiting](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#waiting)                                     | Fired when playback has stopped because the next frame is not available, but the player expects that frame to become available in due course. |
| Player                                                                                                                                       | [currentTime](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#currenttime)                              | The current playback position of the media, in seconds.                                                                                       |
| Player                                                                                                                                       | [currentProgramDateTime](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#currentprogramdatetime)        | The current playback position of the media, as a timestamp.                                                                                   |
| Player                                                                                                                                       | [muted](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#muted)                                          | Whether audio is muted.                                                                                                                       |
| Player                                                                                                                                       | [...](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer)                                                  | ...                                                                                                                                           |
| [Ads (Client-Side)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap)                  | [adbegin](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#adbegin)                                        | Fired when an ad begins.                                                                                                                      |
| Ads (Client-Side)                                                                                                                            | [adbreakbegin](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#adbreakbegin)                              | Fired when an ad break begins.                                                                                                                |
| Ads (Client-Side)                                                                                                                            | [adbreakchange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#adbreakchange)                            | Fired when an ad break changes.                                                                                                               |
| Ads (Client-Side)                                                                                                                            | [adbreakend](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#adbreakend)                                  | Fired when an ad break ends.                                                                                                                  |
| Ads (Client-Side)                                                                                                                            | [adbuffering](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#adbuffering)                                | Fired when the ad has stalled playback to buffer.                                                                                             |
| Ads (Client-Side)                                                                                                                            | [addad](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#addad)                                            | Fired when an ad is added.                                                                                                                    |
| Ads (Client-Side)                                                                                                                            | [addadbreak](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#addadbreak)                                  | Fired when an ad break is added.                                                                                                              |
| Ads (Client-Side)                                                                                                                            | [adend](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#adend)                                            | Fired when an ad ends.                                                                                                                        |
| Ads (Client-Side)                                                                                                                            | [aderror](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#aderror)                                        | Fired when an ad errors.                                                                                                                      |
| Ads (Client-Side)                                                                                                                            | [adfirstquartile](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#adfirstquartile)                        | Fired when an ad reaches the first quartile.                                                                                                  |
| Ads (Client-Side)                                                                                                                            | [adimpression](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#adimpression)                              | Fired when an ad counts as an impression.                                                                                                     |
| Ads (Client-Side)                                                                                                                            | [adloaded](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#adloaded)                                      | Fired when an ad is loaded.                                                                                                                   |
| Ads (Client-Side)                                                                                                                            | [admetadata](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#admetadata)                                  | Fired when an ads list is loaded.                                                                                                             |
| Ads (Client-Side)                                                                                                                            | [admidpoint](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#admidpoint)                                  | Fired when an ad reaches the mid point.                                                                                                       |
| Ads (Client-Side)                                                                                                                            | [adskip](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#adskip)                                          | Fired when an ad is skipped.                                                                                                                  |
| Ads (Client-Side)                                                                                                                            | [adthirdquartile](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#adthirdquartile)                        | Fired when an ad reaches the third quartile.                                                                                                  |
| Ads (Client-Side)                                                                                                                            | [removeadbreak](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#removeadbreak)                            | Fired when an ad break is removed.                                                                                                            |
| Ads (Client-Side)                                                                                                                            | [updatead](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#updatead)                                      | Fired when an ad is updated.                                                                                                                  |
| Ads (Client-Side)                                                                                                                            | [updateadbreak](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/AdsEventMap#updateadbreak)                            | Fired when an AdBreak is updated.                                                                                                             |
| [Vendor Cast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VendorCastEventMap)                 | [statechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VendorCastEventMap#statechange)                         | Fired when the state changes.                                                                                                                 |
| [Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/ChromecastEventMap)                  | [error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/ChromecastEventMap#error)                                     | Fired when an error occurs while casting or trying to cast.                                                                                   |
| [Track List](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackListEventMap)                   | [addtrack](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackListEventMap#addtrack)                                | Fired when a track is added.                                                                                                                  |
| Track List                                                                                                                                   | [change](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackListEventMap#change)                                    | Fired when a track is activated or deactivated.                                                                                               |
| Track List                                                                                                                                   | [removetrack](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackListEventMap#removetrack)                          | Fired when a track is removed.                                                                                                                |
| [Track](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackEventMap)                            | [change](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackEventMap#change)                                        | Fired when a media track's enabled or a text track's changes.                                                                                 |
| Track                                                                                                                                        | [update](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackEventMap#update)                                        | Fired when the track updates.                                                                                                                 |
| [Media Track](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrackEventMap)                 | [activequalitychanged](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrackEventMap#activequalitychanged)       | Fired when the media track's active quality changes.                                                                                          |
| Media Track                                                                                                                                  | [qualityunavailable](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrackEventMap#qualityunavailable)           | Fired when a quality of the track becomes unavailable.                                                                                        |
| Media Track                                                                                                                                  | [targetqualitychanged](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/MediaTrackEventMap#targetqualitychanged)       | Fired when the media track's target quality changes.                                                                                          |
| [Text Track](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackEventMap)                   | [addcue](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackEventMap#addcue)                                    | Fired when a cue is added to the track.                                                                                                       |
| Text Track                                                                                                                                   | [cuechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackEventMap#cuechange)                              | Fired when a cue of the track changes.                                                                                                        |
| Text Track                                                                                                                                   | [entercue](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackEventMap#entercue)                                | Fired when a cue of the track enters.                                                                                                         |
| Text Track                                                                                                                                   | [error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackEventMap#error)                                      | Fired when an error occurred while loading or parsing the track.                                                                              |
| Text Track                                                                                                                                   | [exitcue](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackEventMap#exitcue)                                  | Fired when a cue of the track exits.                                                                                                          |
| Text Track                                                                                                                                   | [readystatechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackEventMap#readystatechange)                | Fired when the text track's changes.                                                                                                          |
| Text Track                                                                                                                                   | [removecue](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackEventMap#removecue)                              | Fired when a cue of the track is removed.                                                                                                     |
| Text Track                                                                                                                                   | [typechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackEventMap#typechange)                            | Fired when the text track's changes.                                                                                                          |
| [Text Track Cue](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackCueEventMap)            | [enter](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackCueEventMap#enter)                                   | Fired when the cue is entered.                                                                                                                |
| Text Track Cue                                                                                                                               | [exit](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackCueEventMap#exit)                                     | Fired when the cue is exited.                                                                                                                 |
| Text Track Cue                                                                                                                               | [update](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackCueEventMap#update)                                 | Fired when the cue is updated.                                                                                                                |
| [Presentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PresentationEventMap)              | [error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PresentationEventMap#error)                                   | Fired when an error occurs.                                                                                                                   |
| Presentation                                                                                                                                 | [presentationmodechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PresentationEventMap#presentationmodechange) | Fired when the presentation mode changes.                                                                                                     |
| [VR](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VREventMap)                                  | [directionchange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VREventMap#directionchange)                         | Fired when the VR.direction changes.                                                                                                          |
| VR                                                                                                                                           | [error](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VREventMap#error)                                             | Fired when an error occurs.                                                                                                                   |
| VR                                                                                                                                           | [statechange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VREventMap#statechange)                                 | Fired when the VR.state changes.                                                                                                              |
| VR                                                                                                                                           | [stereochange](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/VREventMap#stereochange)                               | Fired when the VR.stereo changes.                                                                                                             |
| [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkEventMap)                          | [assetinforesponse](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkEventMap#assetinforesponse)                 | Fired when an asset info response is received.                                                                                                |
| Uplynk                                                                                                                                       | [pingerror](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkEventMap#pingerror)                                 | Fired when an error or invalid response is received from the Ping API.                                                                        |
| Uplynk                                                                                                                                       | [pingresponse](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkEventMap#pingresponse)                           | Fired when a Ping response is received.                                                                                                       |
| Uplynk                                                                                                                                       | [preplayresponse](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkEventMap#preplayresponse)                     | Fired when a Preplay response is received.                                                                                                    |
| Uplynk                                                                                                                                       | [ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Uplynk#ads)                                                     | The Uplynk SSAI API.                                                                                                                          |
| Uplynk                                                                                                                                       | [assets](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Uplynk#assets)                                               | List of Uplynk assets.                                                                                                                        |
| [Uplynk Ad Break List](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdBreakListEventMap) | [addadbreak](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdBreakListEventMap#addadbreak)                    | Fired when the ad break is added.                                                                                                             |
| Uplynk Ad Break List                                                                                                                         | [removeadbreak](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdBreakListEventMap#removeadbreak)              | Fired when the ad break is removed.                                                                                                           |
| [Uplynk Ad Break](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdBreakEventMap)          | [adbreakbegin](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdBreakEventMap#adbreakbegin)                    | Fired when the ad break begins.                                                                                                               |
| Uplynk Ad Break                                                                                                                              | [adbreakend](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdBreakEventMap#adbreakend)                        | Fired when the ad break ends.                                                                                                                 |
| Uplynk Ad Break                                                                                                                              | [adbreakskip](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdBreakEventMap#adbreakskip)                      | Fired when the ad break is skipped.                                                                                                           |
| Uplynk Ad Break                                                                                                                              | [updateadbreak](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdBreakEventMap#updateadbreak)                  | Fired when the ad break is updated.                                                                                                           |
| [Uplynk Ad](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdEventMap)                     | [adbegin](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdEventMap#adbegin)                                   | Fired when an ad begins.                                                                                                                      |
| Uplynk Ad                                                                                                                                    | [adcomplete](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdEventMap#adcomplete)                             | Fired when the ad is completed.                                                                                                               |
| Uplynk Ad                                                                                                                                    | [adend](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdEventMap#adend)                                       | Fired when the ad ends.                                                                                                                       |
| Uplynk Ad                                                                                                                                    | [adfirstquartile](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdEventMap#adfirstquartile)                   | Fired when the ad reaches the first quartile.                                                                                                 |
| Uplynk Ad                                                                                                                                    | [admidpoint](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdEventMap#admidpoint)                             | Fired when the ad reaches the mid point.                                                                                                      |
| Uplynk Ad                                                                                                                                    | [adthirdquartile](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UplynkAdEventMap#adthirdquartile)                   | Fired when the ad reaches the third quartile.                                                                                                 |

Our APIs are continuously evolving, and so is our list of events. Refer to our API references of our SDKs to go through the latest sets of events:

* [Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web)
* [iOS SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios)
* [Android SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android)

---

# How do you know when a stream or an advertisement is playing?

This short how-to guide explains how to determine programmatically when the player is playing and whether it is playing a stream or a client-side advertisement. This may be useful if you need to determine different behavior (or UI) relating to the 2 mentioned options.

The question above is related to the following questions:

* How do you know when a video plays?
* How do I know whether the `playing` event is triggered for an advertisement, or for the main content/stream?

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | N/A            |

## How to detect an ad playing

There are certainly different ways to do so: it is enough to have a look at your player; or at the Network tab of your dev tools; or even directly at the manifest. Usually, the UI also has telltale signs. But there are many cases in which you may want to determine this programmatically, for example if you are to apply a different UI to your player depending on this factor.

### Code examples

You can use the `playing` event to know when content (or an ad) starts playing. Its event handler is the correct scope to check whether an advertisement is playing through the [`player.ads.playing`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Ads#playing) property.

Let's see some code examples for the various SDKs.

##### Web SDK

```js
function playingEventHandler(event) {
  var adIsPlaying = player.ads.playing;
  console.log('PLAYING', adIsPlaying ? 'Advertisement' : 'Content', event);
}
player.addEventListener('playing', playingEventHandler);
```

##### Android SDK

```java
final EventListener<PlayingEvent> playingEventHandler = new EventListener<PlayingEvent>() {
    @Override
    public void handleEvent(PlayingEvent playingEvent) {

        boolean adIsPlaying = tpv.getPlayer().getAds().isPlaying();
        System.out.println("PLAYING " + (adIsPlaying ? "Advertisement" : "Content"));
    }
};
tpv.getPlayer().addEventListener(PlayerEventTypes.PLAYING, playingEventHandler);
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

```swift
self.eventListener = self.theoplayer.addEventListener(type: PlayerEventTypes.PLAYING) { [weak self] event in
                                      self.theoplayer?.ads.requestPlaying() { (result, _) in
                                      print("player.ads.playing = ", result!)
                                      }
                              }
```

## Remarks

* This approach helps you detect when client-side ads are playing, but it will not work for server-side ads.

* Please refer to [How can we track the first play(ing) event?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/how-can-we-track-the-first-playing-event.md) to read more about capturing the first `playing` event.

## Resources

* [Reference API - Ads.playing property](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Ads#playing)
* [Reference API - playing property](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#playing)

---

# How to measure time-to-first-frame?

The question above is related to the following questions:

* How do I measure my start-up time?

To measure the time-to-first-frame, you need to measure the time difference between the `play` event and the `playing` event.

##### Web SDK

```js
var playEventRegisteredAt;
function playingEventHandler(event) {
  player.removeEventListener('playing', playingEventHandler);
  var timeToFirstFrame = Date.now() - playEventRegisteredAt;
  console.log('Time-to-first-frame:', timeToFirstFrame);
}
function playEventHandler(event) {
  player.removeEventListener('play', playEventHandler);
  playEventRegisteredAt = Date.now();
}
player.addEventListener('playing', playingEventHandler);
player.addEventListener('play', playEventHandler);
```

##### Android SDK

```java
long playEventRegisteredAt = 0; // global variable
...
EventListener<PlayingEvent> playingEventHandler = new EventListener<PlayingEvent>() {
    @Override
    public void handleEvent(PlayingEvent playingEvent) {
        tpv.getPlayer().removeEventListener(PlayerEventTypes.PLAYING, this);
        long timeToFirstFrame = System.currentTimeMillis() - playEventRegisteredAt;
        System.out.println("Time-to-first-frame: " + timeToFirstFrame);
    }
};
EventListener<PlayEvent> playEventHandler = new EventListener<PlayEvent>() {
    @Override
    public void handleEvent(PlayEvent playgEvent) {
        tpv.getPlayer().removeEventListener(PlayerEventTypes.PLAY, this);
        playEventRegisteredAt = System.currentTimeMillis();
    }
};
tpv.getPlayer().addEventListener(PlayerEventTypes.PLAYING, playingEventHandler);
tpv.getPlayer().addEventListener(PlayerEventTypes.PLAY, playEventHandler);
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

```swift
var playEventRegisteredAt: Date!
...
playingeventlistener = theoplayer.addEventListener(type:
PlayerEventTypes.PLAYING, listener: playingEventHandler)

playeventlistener = theoplayer.addEventListener(type:
PlayerEventTypes.PLAY, listener: playEventHandler)

func playingEventHandler (event : PlayingEvent) {
        theoplayer.removeEventListener(type: PlayerEventTypes.PLAY,  listener: playingeventlistener);

        let components = NSCalendar.current.dateComponents([.second], from: playEventRegisteredAt, to: Date())

        let timeToFirstFrame = components.second

        print("Time-to-first-frame:", timeToFirstFrame!,"second(s)");
}

func playEventHandler(event :PlayEvent) {
        theoplayer.removeEventListener(type: PlayerEventTypes.PLAY,  listener: playeventlistener)
        playEventRegisteredAt = Date()
}
```

##### Roku SDK

To measure the time to the first frame, we will use [roTimespan](https://developer.roku.com/en-gb/docs/references/brightscript/interfaces/iftimespan.md). Starting measurement will take place just before setting the source of the player and finishing measurement will occur in "playing" event callback.

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="TestScene" extends="Scene">
    <interface>
        <function name="callbackOnEventPlayerPlay"/>
        <function name="callbackOnEventPlayerPlaying"/>
    </interface>

    <script type = "text/brightscript" >

        <![CDATA[

        function Init()
            m.player = m.top.findNode("TestPlayer")
            m.player.configuration = {
              "license": "" ' put the THEOplayer license between apostrophes
            }
            m.player.listener = m.top
            m.player.callFunc("addEventListener", m.player.Event.play, "callbackOnEventPlayerPlay")
            m.player.callFunc("addEventListener", m.player.Event.playing, "callbackOnEventPlayerPlaying")
            m._ts = CreateObject("roTimespan")

            setSource()
            m.player.setFocus(true)
            m.player.callFunc("play")
        end function

        function setSource()
            sourceDescription = {
                "sources": [
                    {
                        "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
                        "type": "application/x-mpegURL"
                    }
                ]
            }
            m.player.source = sourceDescription
            m.player.source.Live = false
            m.player.source.LiveBoundsPauseBehavior = "pause"
        end function

        function callbackOnEventPlayerPlay(eventData)
            ? "Event <play>: "; eventData
            m._ts.Mark()
        end function

        function callbackOnEventPlayerPlaying(eventData)
            ? "Event <playing>: "; eventData
            ? "Time-to-first-frame: "; m._ts.TotalMilliseconds()
        end function

        ]]>

    </script>

    <children>
	    <THEOsdk:THEOplayer id="TestPlayer"/>
    </children>
</component>
```

---

# How can we track the first play(ing) event?

The question above is commonly asked to assist with the use-cases where the first [`play`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#play) event thrown by THEOplayer for a specific stream needs to be detected. Similar questions are:

* The developer wants to know when a new stream plays for the first time.
* The developer wants to forward a `firstplay` event to an analytics backend.
* The developer has heard of a `firstplay` event, and is interested if THEOplayer provides it.

Although we don't explicitly expose a `firstplay` event, you can implement it yourself, allowing you more control over its logic.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | N/A            | Yes      |

## Code examples

The snippets below demonstrate an example implementation of firstplaying.

If the user pauses the stream, and resumes the video player, the event isn't re-thrown. If the user switches to another video, the `firstplaying` event will be thrown once again. You can also swap out the `playing` event for a `play` event, or any other event for that matter.

##### Web SDK

```js
function firstplaying(event) {
  player.removeEventListener('playing', firstplaying);
  console.log('first play event!', event);
}
player.addEventListener('sourcechange', function () {
  console.log('A new SourceDescription has been set.');
  player.removeEventListener('playing', firstplaying);
  player.addEventListener('playing', firstplaying);
});
// OR
// player.addEventListener('loadedmetadata', function() {
//    console.log("A new stream has been detected.");
//    player.removeEventListener('playing', firstplaying);
//    player.addEventListener('playing', firstplaying);
// });
```

##### Android SDK

```java
final EventListener<PlayingEvent> firstplaying = new EventListener<PlayingEvent>() {
    @Override
    public void handleEvent(PlayingEvent playingEvent) {
        tpv.getPlayer().removeEventListener(PlayerEventTypes.PLAYING, this);
        System.out.println("First playing event!");
    }
};

tpv.getPlayer().addEventListener(PlayerEventTypes.LOADEDMETADATA, new EventListener<LoadedMetadataEvent>() {
    @Override
    public void handleEvent(LoadedMetadataEvent loadedMetadataEvent) {
        System.out.println("A new stream has been detected.");
        tpv.getPlayer().removeEventListener(PlayerEventTypes.PLAYING, firstplaying);
        tpv.getPlayer().addEventListener(PlayerEventTypes.PLAYING, firstplaying);
    }
});
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

//work in progress

##### Roku SDK

To track only the first `playing` event we will add a "playing" event and a callback function. We will remove this event listener to make sure that the event callback will only be executed once.

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="TestScene" extends="Scene">
    <interface>
        <function name="callbackOnEventPlayerFirstPlaying"/>
        <function name="callbackOnEventPlayerSourcechange"/>
    </interface>

    <script type = "text/brightscript" >

        <![CDATA[

        function Init()
            m.player = m.top.findNode("TestPlayer")
            m.player.configuration = {
              "license": "" ' put the THEOplayer license between apostrophes
            }
            m.player.listener = m.top
            m.player.callFunc("addEventListener", m.player.Event.sourcechange, "callbackOnEventPlayerSourcechange")

            setSource()
            m.player.setFocus(true)
            m.player.callFunc("play")
        end function

        function setSource()
            sourceDescription = {
                "sources": [
                    {
                        "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
                        "type": "application/x-mpegURL"
                    }
                ]
            }
            m.player.source = sourceDescription
            m.player.source.Live = false
            m.player.source.LiveBoundsPauseBehavior = "pause"
        end function

        function callbackOnEventPlayerSourcechange(eventData)
            ? "Event <sourcechange>: "; eventData
            m.player.callFunc("removeEventListener", m.player.Event.playing, "callbackOnEventPlayerFirstPlaying")
            m.player.callFunc("addEventListener", m.player.Event.playing, "callbackOnEventPlayerFirstPlaying")
        end function

        function callbackOnEventPlayerFirstPlaying(eventData)
            m.player.callFunc("removeEventListener", m.player.Event.playing, "callbackOnEventPlayerFirstPlaying")
            ? "Event <firstplaying>: "; eventData
        end function

        ]]>

    </script>

    <children>
	    <THEOsdk:THEOplayer id="TestPlayer"/>
    </children>
</component>
```

## Resources

* [Reference API - play event](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#play):

---

# How to track player states

A video player has states. As a developer, you should understand these states, as each state grants you access to different data, and might imply a re-render of your UI. For example, if your video player is in the "Paused" state, you want to show a play-button instead of a pause-button.

The objective of this guide is to define some video player states, and how to track the transition between states.

Although there's no official list of video player states, we'll define 11 states for learning purposes. These 11 states are visualized in the state diagram below.

![Video Player States](/pr-932/assets/images/player-video-player-states-4f4f37f92d4b03a2c750ce7fe03d0a5a.png "Video Player States")

The table below provides the definitions of these 11 states.

| State                            | Description                                                                                                                                                                                                                                                                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A: Empty                         | A state where the player is created, but has no information or data retained on the source which is to be played. The player is idle and not undertaking any interaction with the system.                                                                                                                                                         |
| B: Initialized                   | A state where the player knows the source which is to be played, but no media data is loaded. The player is idle and not undertaking any interaction with the system.                                                                                                                                                                             |
| C: Playing - HAVE\_NOTHING       | A state where the player wants to start playing a source, but has no media data available. The player is actively loading media data in order to initiate playback.                                                                                                                                                                               |
| D: Paused - HAVE\_NOTHING        | A state where the player wants to fill its buffer without playing, but has no media data available. The player is actively loading media data in order to fill its buffer.                                                                                                                                                                        |
| E: Playing - HAVE\_METADATA      | A state where the player wants to start playing a source, but only metadata is available and the entire buffer is still empty. The player knows which tracks and qualities are available. The player is actively loading media data in order to initiate playback.                                                                                |
| F: Paused - HAVE\_METADATA       | A state where the player wants to fill its buffer without playing, but only metadata is available and the entire buffer is still empty. The player knows which tracks and qualities are available. The player is actively loading media data in order to fill its buffer.                                                                         |
| G: Playing - HAVE\_CURRENT\_DATA | A state where the player wants to start playing a source and has media data in its buffer for the current timestamp, but this data is insufficient to start playback and guarantee a smooth viewer experience. The player is actively loading media data in order to initiate playback.                                                           |
| H: Paused - HAVE\_CURRENT\_DATA  | A state where the player wants to fill its buffer without playing and has media data in the buffer for the current timestamp, but this data is insufficient to start playback and guarantee a smooth viewer experience. The player is actively loading media data in order to fill its buffer.                                                    |
| I: Playing                       | A state where the player is actively rendering out media data. The current timestamp is progressing at the speed of the current playback rate and media buffer data is being consumed and loaded in parallel. timeupdate events will be dispatched regularly during playback and progress events will be dispatched as additional data is loaded. |
| J: Paused                        | A state where the player has sufficient media data in its buffer in order to guarantee a smooth viewer experience when playback is started, but it is in a paused state. The player is not consuming any media data, but might be loading additional media data to grow its buffer in the background.                                             |
| K: Error                         | A state where the player has observed a fatal, non recoverable error. The player cannot continue playback and needs to be initialized again in order to restart playback. A player can get into this state from any state other than the Empty-state.                                                                                             |

The table below explains what triggers each of the 26 transitions between states, and what video player events are related.

| Transition | Triggers                                                                                                   | Events                                                                                                                                                    |
| ---------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1          | `new THEOplayer.Player`                                                                                    |                                                                                                                                                           |
| 2          | `player.source = X`                                                                                        | `sourcechange`, `currentsourcechange`                                                                                                                     |
| 3          | `player.play()`                                                                                            | `play`, `loadstart`                                                                                                                                       |
| 4          | `player.load()`                                                                                            | `loadstart`                                                                                                                                               |
| 5          | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 6          | `player.play()`                                                                                            | `play`                                                                                                                                                    |
| 7          | The stream manifest being loaded                                                                           | `readystatechange`, `loadedmetadata`, `durationchange`                                                                                                    |
| 8          | The stream manifest being loaded                                                                           | `readystatechange`, `loadedmetadata`, `durationchange`                                                                                                    |
| 9          | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 10         | `player.play()`                                                                                            | `play`                                                                                                                                                    |
| 11         | Stream media data is loaded                                                                                | `readystatechange`, `loadeddata`, `progress`, `canplay`                                                                                                   |
| 12         | Stream media data is loaded                                                                                | `readystatechange`, `loadeddata`, `progress`, `canplay`                                                                                                   |
| 13         | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 14         | `player.play()`                                                                                            | `play`                                                                                                                                                    |
| 15         | Sufficient media data is loaded to start playback fluently.                                                | `progress`, `canplaythrough`, `readystatechange`, `playing`<br />*A `seeked` event can be dispatched if the entrance of this state was caused by a seek.* |
| 16         | Sufficient media data is loaded to start playback fluently.                                                | `canplaythrough`, `readystatechange`<br />*A `seeked` event can be dispatched if the entrance of this state was caused by a seek.*                        |
| 17         | `player.pause()`                                                                                           | `pause`                                                                                                                                                   |
| 18         | `player.play()`                                                                                            | `play`, `playing`                                                                                                                                         |
| 19         | `player.currentTime = X` and there is some media data at the target time, but not enough to play fluently. | `seeking`, `readystatechange`                                                                                                                             |
| 20         | The player buffer is not being filled enough, causing a stall.                                             | `waiting`, `readystatechange`                                                                                                                             |
| 21         | `player.currentTime = X` and there is no media data at the target time.                                    | `seeking`, `readystatechange`                                                                                                                             |
| 22         | Playback has ended.                                                                                        | `ended`, `readystatechange`                                                                                                                               |
| 23         | `player.currentTime = X` and there is some media data at the target time, but not enough to play fluently. | `seeking`, `readystatechange`                                                                                                                             |
| 24         | `player.currentTime = X` and there is no media data at the target time.                                    | `seeking`, `readystatechange`                                                                                                                             |
| 25         | An error occurred.                                                                                         | `error`                                                                                                                                                   |
| 26         | `player.source = null`                                                                                     | `emptied`                                                                                                                                                 |

### Implementation

The following code samples demonstrate how you track some of the 18 events related to the state transitions across different SDKs.

* `sourcechange`
* `currentsourcechange`
* `play`
* `loadstart`
* `pause`
* `readystatechange`
* `loadedmetadata`
* `durationchange`
* `loadeddata`
* `progress`
* `canplay`
* `canplaythrough`
* `playing`
* `waiting`
* `seeking`
* `ended`
* `error`
* `emptied`

All 18 events are dispatched by the `Player` interface.

* Web SDK: [interface](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer) and [events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap)
* Android SDK: [interface](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player) and [events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/player/PlayerEventTypes)
* iOS SDK: [interface](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer) and [events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/PlayerEventTypes)
* Roku SDK

#### Web SDK

The snippet below demonstrates how you can track some of the related events through the THEOplayer Web SDK. All other events can be tracked similarly. You can find the event names in [the `PlayerEventMap` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap). This approach is valid for all web-based platforms, including Tizen and webOS.

```javascript
player.addEventListener('sourcechange', (event) => {
  console.log(event);
});
// ...
player.addEventListener('ended', (event) => {
  console.log(event);
});
```

#### Android SDK

The snippet below demonstrates how you can track some of the related events through the THEOplayer Android SDK. All other events can be tracked similarly. You can find the event names in [the `PlayerEventTypes` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/player/PlayerEventTypes). This approach is valid for all Android-based platforms, including Android TV and Fire TV.

```java
player.addEventListener(PlayerEventTypes.SOURCECHANGE, event -> {
    System.out.println(event);
});
// ...
player.addEventListener(PlayerEventTypes.ENDED, event -> {
    System.out.println(event);
});
```

#### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

The snippet below demonstrates how you can track some of the related events through the THEOplayer iOS SDK. All other events can be tracked similarly. You can find the event names in [the `PlayerEventTypes` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/PlayerEventTypes). This approach is valid for all iOS-based platforms, including iPadOS and tvOS.

```swift
player?.addEventListener(type: PlayerEventTypes.SOURCE_CHANGE, listener: { (event) in
    print(event)
})
// ...
player?.addEventListener(type: PlayerEventTypes.ENDED, listener: { (event) in
    print(event)
})
```

#### Roku SDK

*This subsection is in maintenance. Reach out to our team if you require help.*

---

# Introduction

The articles in this section describe how to implement common use-cases related to text tracks, subtitles, closed captions and metadata. These use-cases can range from programmatically detecting new metadata, to side-loading subtitles.

The `textTrackRendering` feature flag, included by default makes THEOplayer capable of supporting

* subtitle and closed caption formats like WebVTT, CEA-608, DVB Subs and TTML;
* metadata formats like ID3, emsg, EventStream and `EXT-X-DATERANGE`.

The `textTrackRendering` feature exposes the TextTracks API. This API allows developers to programmatically switch between text tracks, detect events related to text tracks (e.g. new active cue) and more.

## Related articles

* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-dynamically-change-the-visible-captions.md)
* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-programmatically-detect-text-tracks.md)
* [How to programmatically detect text track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-detect-text-track-changes.md)
* [How to programmatically enable or disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-programmatically-disable-text-tracks.md)
* [How to detect active text track cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-detect-active-text-track-cues.md)
* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-insert-subtitles.md)
* [How to implement preview thumbnails in THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-implement-preview-thumbnails.md)
* [How to track ID3 cues/tags](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-track-id3-cues-tags.md)

---

# How to dynamically change the visible captions?

When working with the captions / text-track options, you can dynamically change the currently selected language (or set a default language) using following methods.

This method assumes that you are using text-tracks that are loaded with the manifest. If you add the text-track separately, you can just use this API: [TextTrackDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackDescription)

## Step-by-step guide

### 1. Create a new function inside the browser

##### Web SDK

```js
function setLanguage(player, language) {
  // Disable all text tracks that are currently active
  player.textTracks
    .filter(function (x) {
      if (x.mode !== 'disabled') {
        return x;
      }
    })
    .forEach(function (x) {
      x.mode = 'disabled';
    });
  // Enable the text track for a specific language. Note: Here we are searching the label. You can also do x.language for the ISO 3 letter language code.
  player.textTracks.filter(function (x) {
    if (x.label == language) {
      return x;
    }
  })[0].mode = 'showing';
}
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

```swift
private func setLanguage(player: THEOplayer, language: String) {
    let list: TextTrackList = player.textTracks
    for i in 0..<list.count {
        var textTrack: TextTrack = list[i]
        if textTrack.label == language {
            textTrack.mode = .showing
        }
    }
}
```

##### Roku SDK

In the following example we are iterating through all available text tracks. Once we found a track with a desired language, we simply set the mode to "showing". After that, we have to simply assign textTracks object to a proper THEOplayer attribute. This is all you have to do to make a desired text track visible. Of course, we can modify a visible text track during the video playback.

```brightscript

function setCaptionsLanguage(language as String)
  textTracks = m.player.textTracks
  for i = textTracks.count() - 1 to 0 step -1
    if textTracks[i].kind = "captions" and textTracks[i].language = language then
      if m.fullScreen then
        textTracks[i].mode = "showing"
      else
        textTracks[i].mode = "hidden"
      end if
    else
      textTracks[i].mode = "disabled"
    end if
  end for
  'assignment of new roAssociativeArray is required because roku deep-copied roAssociativeArray through fields (pass-by-value)
  'read more : <https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow>
  m.player.textTracks = textTracks
end function
```

### 2. Call the function using the language label (or 3-letter-language code if you change x.label to x.language)

## Related articles

* [How to dynamically change the visible captions?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-dynamically-change-the-visible-captions.md)
* [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)
* [Web SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md)
* [Android Legacy (4.12.x) SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/android/getting-started)
* [Chromecast Receiver SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/chromecast/getting-started.md)

---

# How to programmatically detect text tracks

This article describes how you can use the API to detect text tracks, which can be subtitles, closed captions or metadata.

The TextTrack API can be used to implement this functionality. Implementing this functionality is a common use-case for developers who want to build their own UI to visualize the available text languages.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            | Yes      |

## Code examples

The code examples below showcase how to implement the detection of audio tracks across SDKs.

##### Web SDK

The Web SDK leverages the [TextTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrack).

```js
function handleAddTrackEvent(addTrackEvent) {
  var textTrack = addTrackEvent.track;
}
player.textTracks.addEventListener('addtrack', handleAddTrackEvent);
```

##### Android (TV) SDK

The Android SDK leverages the [TextTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrackList).

```java
EventListener<AddTrackEvent> handleAudioTrackAdd = new EventListener<AddTrackEvent>() {
    @Override
    public void handleEvent(AddTrackEvent addTrackEvent) {
        TextTrack textTrack = addTrackEvent.getTrack();
    }
};
tpv.getPlayer().getTextTracks().addEventListener(TextTrackListEventTypes.ADDTRACK, handleAudioTrackAdd);
```

##### iOS (/tvOS) SDK

The iOS SDK leverages the [MediaTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/MediaTrackList).

```swift
func handleAddTrackEvent(addTrackEvent : AddTrackEvent) {
    var textTrack = addTrackEvent.track
}
self.theoplayer.textTracks.addEventListener(type: TextTrackListEventTypes.ADD_TRACK, listener: handleAddTrackEvent)
```

##### Roku SDK

To obtain an exact moment of recognizing text track we may use an “addedtexttrack” event. This will allow to programmatically detect all text tracks which are loaded with the stream.

```brightscript
function Init(){
  ...
  m.THEOplayer.callFunc("addEventListener", "addedtexttrack", "onEventTextTracksChanged")
  ...
end function

function onEventTextTracksChanged()
  textTracks= m.player.textTracks
  ? "Text tracks changed."
  ? textTracks
end function
```

## Remarks

* A related article on building a Chromeless UI is located at [How to build a Chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md).

---

# How to programmatically enable or disable text tracks

This article describes how you can use the API to enable or disable subtitles, closed captions or metadata.

The TextTracks API can be used to implement this functionality. Implementing this functionality is a common use-case for developers who want to build their own UI to toggle subtitles.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            | Yes      |

## Code examples

The code examples below how to implement toggling subtitles across SDK. It's advised to disable the text tracks you don't want to display, in order to avoid issues with overlapping text.

##### Web SDK

```js
// disable all text tracks
player.textTracks.forEach(function (track) {
  track.mode = 'disabled';
});
// enable a specific text track
player.textTracks[indexOfRequestedTextTrack].mode = 'showing';
```

##### Android (TV) SDK

```java
// disable all text tracks
for (int i = 0; i < tpv.getPlayer().getTextTracks().length(); i++) {
    theoplayer.getPlayer().getTextTracks().getItem(i).setMode(TextTrackMode.DISABLED);
}
// enable a specific text track
theoplayer.getPlayer().getTextTracks().getItem(indexOfRequestedTextTrack).setMode(TextTrackMode.SHOWING);
```

##### iOS (/tvOS) SDK

```swift
// disable all text tracks
for i in 0..<self.player.textTracks.count {
    var track = self.player.textTracks.get(i)
    track.mode = TextTrackMode.disabled
}
// enable a specific text track
var track = self.player.textTracks.get(indexOfRequestedTextTrack)
track.mode = TextTrackMode.showing
```

##### Roku SDK

To disable all text tracks we have to iterate through all text tracks and set the field mode to "disabled" for each of the text tracks.

It should be emphasized that in BrightScript and SceneGraph we are obligated to assign a whole new associative array to the interface field in order to change the associative array exposed through interface. As the attempts to change fields of an associative array or elements of array will bring no effect.

```brightscript
'disable all tracks
textTracks = m.player.textTracks
for i = textTracks.count() - 1 to 0 step -1
  textTracks[i].mode = "disabled"
end for
'assigment of new roAssociativeArray is required because roku deep-copied roAssociativeArray through fields (pass-by-value)
'read more : <https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow>
m.player.textTracks = textTracks

'disable specific track
textTracks =  m.player.textTracks
textTracks[indexOfRequestedTextTrack].mode = "disabled"
'assigment of new roAssociativeArray is required because roku deep-copied roAssociativeArray through fields (pass-by-value)
'read more : <https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow>
m.player.textTracks = textTracks
```

## Remarks

* A related article on building a Chromeless UI is located at [How to build a Chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md).

---

# How to insert subtitles?

You may be asking this question if you need captions or subtitles on your video. The sourceDescription property *textTracks* can be used to add an array of side-loaded text tracks to the player. All valid tracks will be available for playback as long as the player’s source is not set again. In the following guide, you will find several related topics and some code samples for different SDKs.

The *textTracks* property and objects can also be used for other purposes, e.g.: for including preview thumbnails and chapters. Please see linked documentation and article to find out more.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     |          |                |                |

## Related questions

* Can I activate captions in THEOplayer? How?
* Can I load subtitles in several languages, for the user to choose?
* Can I add styles to my subtitles

## Code examples

##### Web SDK

Each text track should be described as a [TextTrackDescription](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackDescription).

```js
player.source = {
  sources: [
    {
      src: '//path/to/your-manifest.m3u8', // sets source
      type: 'application/x-mpegurl', // sets type - find other values at https://support.theoplayer.com/hc/en-us/articles/214350425-SourceDescription-API#TypedSource
    },
  ],
  textTracks: [
    {
      default: true, //optional
      kind: 'subtitles', //optional - find other values at https://support.theoplayer.com/hc/en-us/articles/214350425#TextTrackDescription
      label: 'English subs', //optional - this will appear in your UI
      src: 'path/to/your-subs-track1.vtt',
      srclang: 'en',
    },
  ],
};
```

##### Android SDK

```java
public static final SourceDescription SOURCE_WITH_SUBS =
        new SourceDescription.Builder("//path/to/your-manifest.m3u8")
            .textTracks(
                new TextTrackDescription.Builder("path/to/your-subs-track1.vtt")
                    .isDefault(true)
                    .kind(TextTrackKind.SUBTITLES)
                    .srclang("en")
                    .label("en")
                    .build()
            ).build()
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

```swift
var sampleSource: SourceDescription {
        let src = "https://your.m3u8"
        let stream = "application/x-mpegurl"
        let textTrack1 = TextTrackDescription(src: "https://your.webvtt", srclang: "English", isDefault: true, kind: .subtitles, label:"English", format: .WebVTT)
        let textTrack2 = TextTrackDescription(src: "https://your.webvtt", srclang: "Arabic", isDefault: false, kind: .subtitles, label:"Arabic", format: .WebVTT)

        return SourceDescription(
            source: TypedSource(
                src: src,
                type: stream
            ),
            textTracks: [textTrack1,textTrack2]
        )
    }

Then set the source to the player by:

self.theoplayer.source = sampleSource
```

## Subtitle styling

To style your subtitles look into the player source property `textTrackStyle`.

---

# How to implement preview thumbnails in THEOplayer

This article describes how to enable preview thumbnails. In THEOplayer this is done with the TextTrack API.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         |         |          |                |                |

A demo/example of the preview thumbnails on the THEOplayer Web SDK can be found at <http://demo.theoplayer.com/preview-thumbnails>

## Code examples

The thumbnails are loaded as a separate text track, by setting it as a sideloaded textTrack in the SourceDescription:

##### Web SDK

```js
player.source = {
  sources: {
    type: 'application/x-mpegurl',
    src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8',
  },
  textTracks: [
    {
      default: true,
      src: 'https://cdn.theoplayer.com/dash/theoplayer/thumbnails/big_buck_bunny_thumbnails.vtt',
      label: 'thumbnails',
      kind: 'metadata',
    },
  ],
};
```

##### Android SDK

You can add/edit your SourceDescription as follows.

```java
public static final SourceDescription BBB_WITH_THUMBNAILS =
    new SourceDescription.Builder("https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8")
        .textTracks(new TextTrackDescription.Builder("https://cdn.theoplayer.com/dash/theoplayer/thumbnails/big_buck_bunny_thumbnails.vtt")
            .isDefault(true)
            .kind(TextTrackKind.METADATA)
            .srclang("en")
            .label("thumbnails")
            .build()
    ).build();
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

You can edit or add the SourceDescription below.

```swift
player.source = SourceDescription(
    source: TypedSource(
        src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8",
        type: "application/x-mpegurl"
    ),
    textTracks: [TextTrackDescription(
        src: "https://cdn.theoplayer.com/dash/theoplayer/thumbnails/big_buck_bunny_thumbnails.vtt",
        srclang: "en",
        isDefault: true,
        kind: TextTrackKind.metadata,
        label: "thumbnails")
    ]
)
```

---

# How to track ID3 cues / tags?

The question above is commonly asked by the developers who want to introduce a certain behavior depending on the metadata contained by the ID3 cues. For example, the developer wants:

* to schedule advertisements dynamically by using information passed on by the ID3 metadata.
* to overlay certain text on top of the player (e.g. the score of a football match).
* ...

[ID3](https://en.wikipedia.org/wiki/ID3) is a type of metadata which can be inserted in HTTP livestreams. Once an ID3 cue is inserted, it'll be added to a THEOplayer [TextTrack](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrack). The demo at <https://demo.theoplayer.com/audio-id3-metadata> demonstrates a usage of ID3 metadata. Just before the song changes, an `enter` event will be dispatched, the song information (title, album, etc.) is contained within this `enter` event, and can be used to update the UI.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | N/A            |

## Tracking ID3

This guide will show a couple of examples of tracking ID3 cues / tags, including:

* how to listen for timed metadata events
* how to track the *enter* event

## Code examples

### Listening for timed metadata events

Below you can find an example of how timed metadata events can be captured when using THEOplayer.

##### Web SDK

```js
var player = theoplayer.player(0);
player.textTracks.addEventListener('addtrack', function (addTrackEvent) {
  var track = addTrackEvent.track;
  // assert track.kind === "metadata"

  track.addEventListener('cuechange', function (cueChangeEvent) {
    // here you can access the cue and other properties of the track and display the metadata to the outside
  });
});
```

##### Android SDK

```java
EventListener<CueChangeEvent> cueChangeListener = (CueChangeEvent event) -> {
    event.getTextTrack().getCues();
};

EventListener<AddTrackEvent> handleTrackCreation = (AddTrackEvent event) -> {
    event.getTrack().addEventListener(TextTrackEventTypes.CUECHANGE, cueChangeListener);
};

this.tpv.getPlayer().getTextTracks().addEventListener(TextTrackListEventTypes.ADDTRACK, handleTrackCreation);
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

```swift
let cueChangeListener = { (event: CueChangeEvent) in
    // do something with the cue
}

let handleTrackCreation = { (event: AddTrackEvent) in
    if let textTrack = event.track as? TextTrack {
        _ = textTrack.addEventListener(type: TextTrackEventTypes.CUE_CHANGE, listener: cueChangeListener)
    }
}

_ = player.textTracks.addEventListener(type: TextTrackListEventTypes.ADD_TRACK, listener: handleTrackCreation)
```

### Track the enter event

The snippet below explains how you correctly track the `enter` event, which is part of the [TextTrack API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrack). The `enter` event maps to the moment in time when the ID3 cue is relevant.

> ⚠ **Migrating from version 3.x or lower**
>
> Previously, the `exit` event was used to signal when an ID3 cue becomes relevant. As of THEOplayer version 4.0, the `enter` event is used instead.

##### Web SDK

```js
function enterListener(e2) {
  // log enter event
  console.log(e2);
}
function handleTrackCreation(e0) {
  e0.track.cues.forEach(function (cue) {
    cue.addEventListener('enter', enterListener);
  });

  // detect cues being added to the track
  e0.track.addEventListener('addcue', function (e1) {
    // detect a cue being shown from a track
    e1.cue.addEventListener('enter', enterListener);
  });
}
player.textTracks.addEventListener('addtrack', handleTrackCreation);
```

##### Android SDK

```java
final EventListener<EnterCueEvent> enterListener = new EventListener<EnterCueEvent>() {
    @Override
    public void handleEvent(EnterCueEvent enterCueEvent) {
        System.out.println("enterCueEvent: " + enterCueEvent.getCue().getContent());

    }
};
EventListener<AddTrackEvent> handleTrackCreation = new EventListener<AddTrackEvent>() {
    @Override
    public void handleEvent(AddTrackEvent addTrackEvent) {
        addTrackEvent.getTrack().addEventListener(TextTrackEventTypes.ENTERCUE, enterListener);

    }
};
tpv.getPlayer().getTextTracks().addEventListener(TextTrackListEventTypes.ADDTRACK, handleTrackCreation);
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

```swift
let enterListener = { (event: EnterCueEvent) in
    // do something with the cue
}

let handleTrackCreation = { (event: AddTrackEvent) in
    if let textTrack = event.track as? TextTrack {
        _ = textTrack.addEventListener(type: TextTrackEventTypes.ENTER_CUE, listener: enterListener)
    }
}

_ = player.textTracks.addEventListener(type: TextTrackListEventTypes.ADD_TRACK, listener: handleTrackCreation)
```

## Sample application

The demo below illustrates the use of ID3 in production.

* Demo: <https://demo.theoplayer.com/audio-id3-metadata>

## Resources

* [Reference API - TextTrack](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrack)
* <http://id3.org/>: ID3.org Home
* <https://en.wikipedia.org/wiki/ID3>: Wikipedia - ID3
* <https://dev.w3.org/html5/html-sourcing-inband-tracks/>: External resource - Sourcing In-band Media Resource Tracks from Media Containers into HTML

---

# How to programmatically detect text track changes

This article describes how you can use the THEOplayer API to detect text track quality changes. A text track "change" is triggered by enabling (or disabling) a subtitle or closed captions track.

The TextTrack API provides this functionality. More specifically, as a developer, you'll subscribe to the `change` event in the TextTrack API.

Implementing this functionality is a common use-case for developers who want to build their own UI, and annotate the subtitle (or closed captions) track that is currently active.

## SDKs

THEOplayer allows you to track text track changes on the following SDKs.

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |          |

## Implementation

The TextTrack API is available across all of our base SDKs. As described in the introduction, to detect text track changes, you want to detect the `change` event in the `TextTrack` API.

* [Web SDK](#web-sdk)
* [Android SDK](#android-sdk)
* [iOS SDK](#iostvos-sdk-and-legacy-iostvos-sdk-412x)
* [Roku SDK](#roku-sdk)

### Web SDK

The implementation of the Web SDK applies to all web-based platforms, including Tizen and webOS.

The Web SDK exposes the TextTrack API through [`player.textTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#texttracks). This `textTracks` property is a [`TextTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTracksList) that inherits from the [`TrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackList). This `TrackList` dispatches the events from the [`TrackListEventMap`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackListEventMap). This `TrackListEventMap` contains the [`change`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackListEventMap#change) event, as well as the `addtrack` and `removetrack` event.

The code below allows you to detect text track changes.

```js
player.textTracks.addEventListener('change', function (event) {
  const track = event.track;
  const isEnabled = track.mode == 'showing';
  console.log(track, track.label, track.kind, track.type, isEnabled);
});
```

The properties of a text `track` (e.g. `mode`, `kind`) are described in [the `TextTrack` API reference](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrack).

### Android SDK

The implementation of the Android SDK applies to all Android-based platforms, including Android TV and Fire TV.

The Android SDK exposes the TextTrack API through [`player.getTextTracks()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#getTextTracks). This `getTextTracks()` method returns a [`TextTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrackList) that inherits from the [`TrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/TrackList). This `TrackList` dispatches the events from the [`TextTrackListEventTypes`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/texttrack/list/TextTrackListEventTypes). The `TextTrackListEventTypes` contains the [`TRACKLISTCHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/texttrack/list/TextTrackListEventTypes#TRACKLISTCHANGE) event, as well as the `ADDTRACK` and `REMOVETRACK` event.

The code below allows you to detect text track changes.

```java
player.getTextTracks().addEventListener(TextTrackListEventTypes.TRACKLISTCHANGE, trackListChangeEvent -> {
    TextTrack track = trackListChangeEvent.getTrack();
    boolean isEnabled = (track.getMode().getMode().equals("showing"));
    System.out.println(track.getLabel() + ", " + track.getKind() + ", " + track.getType().getType() + ", " + isEnabled);
});
```

The properties of a text `track` (e.g. `mode`, `kind`) are described in the [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrack) and [`Track`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/Track) API references.

### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

The implementation of the iOS SDK applies to all iOS-based platforms, including iPadOS and tvOS.

The iOS SDK exposes the TrackTrack API through [`player.textTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C10textTracksAA13TextTrackList_pvp). This `textTracks` property is a [`TextTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/TextTrackList). This `TextTrackList` dispatches the events from the [`TextTrackListEventTypes`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/TextTrackListEventTypes). The `TextTrackListEventTypes` contains the [`CHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/TextTrackListEventTypes#/s:13THEOplayerSDK23TextTrackListEventTypesV6CHANGEAA0F4TypeCyAA0d6ChangeF0CGvpZ) event, as well as the `ADD_TRACK` and `REMOVE_TRACK` event.

The code below allows you to detect text track changes.

```swift
player?.textTracks.addEventListener(type: TextTrackListEventTypes.CHANGE, listener: { (event) in
    let track : TextTrack = event.track as! TextTrack
    let isEnabled = (track.mode.rawValue == "showing")
    print(track.label, track.kind, track.type, isEnabled)
})
```

The properties of a text `track` (e.g. `mode`, `kind`) are described in the [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/TextTrack) and [`Track`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/Track) API references.

### Roku SDK

*This subsection is in maintenance. Reach out to our team if you need help.*

# Related articles

Are you reading this article because you're interested in subtitles and closed captions? Continue reading below.

* [How to programmatically detect text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-programmatically-detect-text-tracks.md)
* [How to dynamically change the visible captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-dynamically-change-the-visible-captions.md)
* [How to programmatically disable text tracks](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-programmatically-disable-text-tracks.md)
* [How to insert subtitles](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-insert-subtitles.md)

Refer to "[How to track id3 cues](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-track-id3-cues-tags.md)" if you're interested in timed metadata (id3, emsg, EventStream, EXT-X-DATERANGE, ...).

Are you reading this article because you're implementing a custom UI? Then you'll find the following articles interesting:

* [How to build a Chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md)
* [How to detect video track quality changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-quality-changes.md)
* [How to detect audio track changes](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-audio-track-changes.md)

---

# How to detect active text track cues

This article describes how you can use the THEOplayer API to detect the active text track cues.

The TextTrack API provides this functionality. More specifically, as a developer, you'll subscribe to the `enter` and `exit` events in the TextTrack API, or to the `cuechange` event.

Implementing this functionality can be a use-case for developers who want to build their own UI, and insert and style their subtitles with maximum freedom. Alternatively, you may require the access the active cues for analytics purposes, or to render it outside the video player.

Another common use-case is to detect the active text track cue of timed metadata. This article also discusses this use-case.

## SDKs

THEOplayer allows you to track text track changes on the following SDKs.

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- | -------- |
| Yes     | Yes         | Yes     | Yes      | Yes            | Yes            |          |

## Implementation for subtitles and closed captions

The TextTrack API is available across all of our 4 base SDKs. As described in the introduction, to detect which text track cues are active, you want to leverage the `enter` and `exit` events in the `TextTrack` API, or the `cuechange` event.

Note that this subsection focuses on detecting active cues for subtitles and closed captions. Go to the subsection on ["implementation for timed metadata"](#implementation-for-timed-metadata) if you rather want to track timed metadata like ID3, emsg, EXT-X-DATERANGE and EventStream.

* [Web SDK](#web-sdk)
* [Android SDK](#android-sdk)
* [iOS SDK](#iostvos-sdk-and-legacy-iostvos-sdk-412x)
* [Roku SDK](#roku-sdk)

### Web SDK

The implementation of the Web SDK applies to all web-based platforms, including Tizen and webOS.

The Web SDK exposes the TextTrack API through [`player.textTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#texttracks). This `textTracks` property is a [`TextTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTracksList) that inherits from the [`TrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackList). This `TrackList` dispatches the events from the [`TrackListEventMap`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackListEventMap). This `TrackListEventMap` contains the [`addtrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TrackListEventMap#change) event, as well as the `change` and `removetrack` event.

In the callback of your `addtrack` event, you want to track the [`addcue`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackEventMap#addcue) event through the [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrack) interface. Then, in the callback of your `addcue` event, you want to track the [`enter`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackCueEventMap#enter) and [`exit`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackCueEventMap#exit) events through the [`TextTrackCue`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackCue) interface. The `enter` event is dispatched when a cue becomes active and the `exit` event is dispatched when a cue becomes inactive. You can fetch the actual content in the callback of your `enter` event through its [`content`](https://docs.theoplayer.com/api-reference/web/theoplayer.texttrackcue.md#content) property.

Alternatively, in the callback of your `addtrack` event, you could track the [`cuechange`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/TextTrackEventMap#cuechange) event through the `TextTrack` interface. Then, in the callback of your `cuechange` event, you want to iterate over the active cues. For each active cue, you could also query its `content` property.

The code below allows you to detect the active text track cues.

```js
player.textTracks.addEventListener('addtrack', function (e1) {
  const track = e1.track;
  track.addEventListener('addcue', function (e2) {
    const cue = e2.cue;
    cue.addEventListener('enter', function (e3) {
      console.log(e3, e3.cue.content);
    });
    cue.addEventListener('exit', console.log);
  });
  track.addEventListener('cuechange', function (e2) {
    const cues = e2.track.activeCues;
    for (let i = 0; i < cues.length; i++) {
      console.log('cuechange active cue', i, cues[i]);
    }
  });
});
// ...
// player.source = ...
```

You want to invoke these event handlers before you configure your stream, because your video player might have already dispatched the event before you were able to subscribe to it.

### Android SDK

The implementation of the Android SDK applies to all Android-based platforms, including Android TV and Fire TV.

The Android SDK exposes the TextTrack API through [`player.getTextTracks()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#getTextTracks). This `getTextTracks()` method returns a [`TextTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrackList) that inherits from the [`TrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/TrackList). This `TrackList` dispatches the events from the [`TextTrackListEventTypes`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/texttrack/list/TextTrackListEventTypes). The `TextTrackListEventTypes` contains the [`ADDTRACK`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/texttrack/list/TextTrackListEventTypes#ADDTRACK) event, as well as the `TRACKLISTCHANGE` and `REMOVETRACK` event.

In the callback of your `ADDTRACK` event, you want to track the [`ADDCUE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/texttrack/TextTrackEventTypes#ADDCUE) event through the [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/texttrack/TextTrack) interface. Then, in the callback of your `ADDCUE` event, you want to track the [`ENTER`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/texttrack/texttrackcue/TextTrackCueEventTypes#ENTER) and [`EXIT`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/texttrack/texttrackcue/TextTrackCueEventTypes#EXIT) events through the [`TextTrackCue`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/texttrack/cue/TextTrackCue) interface. The `ENTER` event is dispatched when a cue becomes active and the `EXIT` event is dispatched when a cue becomes inactive. You can fetch the actual content in the callback of your `ENTER` event through its [`getContent()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/track/texttrack/cue/TextTrackCue#getContent--) method.

Alternatively, in the callback of your `ADDTRACK` event, you could track the [`CUECHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/track/texttrack/TextTrackEventTypes#CUECHANGE) event through the `TextTrack` interface. Then, in the callback of your `CUECHANGE` event, you want to iterate over the active cues. For each active cue, you could also query its `content` property.

The code below allows you to detect the active text track cues.

```java
player.getTextTracks().addEventListener(TextTrackListEventTypes.ADDTRACK, e1 -> {
    TextTrack track = e1.getTrack();
    track.addEventListener(TextTrackEventTypes.ADDCUE, e2 -> {
        TextTrackCue cue = e2.getCue();
        cue.addEventListener(TextTrackCueEventTypes.ENTER, e3 -> {
            System.out.println(e3 + " " + e3.getCue().getContent());
        });
        cue.addEventListener(TextTrackCueEventTypes.EXIT, e3 -> {
            System.out.println(e3);
        });
    });
    track.addEventListener(TextTrackEventTypes.CUECHANGE, e2 -> {
        TextTrackCueList cues = e2.getTextTrack().getActiveCues();
        for (int i = 0; i < cues.length(); i++) {
            System.out.println("cuechange active cue " + i + " " + cues.getItem(i));
        }
    });
});
// ...
// player.setSource(...)
```

You want to invoke these event handlers before you configure your stream, because your video player might have already dispatched the event before you were able to subscribe to it.

### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

The implementation of the iOS SDK applies to all iOS-based platforms, including iPadOS and tvOS.

The iOS SDK exposes the TrackTrack API through [`player.textTracks`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C10textTracksAA13TextTrackList_pvp). This `textTracks` property is a [`TextTrackList`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/TextTrackList). This `TextTrackList` dispatches the events from the [`TextTrackListEventTypes`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/TextTrackListEventTypes). The `TextTrackListEventTypes` contains the [`ADD_TRACK`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/TextTrackListEventTypes#/s:13THEOplayerSDK23TextTrackListEventTypesV9ADD_TRACKAA0F4TypeCyAA03AdddF0CGvpZ) event, as well as the `CHANGE` and `REMOVE_TRACK` event.

In the callback of your `ADD_TRACK` event, you want to track the [`ADD_CUE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/TextTrackEventTypes#/s:13THEOplayerSDK19TextTrackEventTypesV7ADD_CUEAA0E4TypeCyAA06AddCueE0CGvpZ) event through the [`TextTrack`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/TextTrack) interface. Then, in the callback of your `ADD_CUE` event, you want to track the [`ENTER`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/TextTrackCueEventTypes#/s:13THEOplayerSDK22TextTrackCueEventTypesV5ENTERAA0F4TypeCyAA0e5EnterF0CGvpZ) and [`EXIT`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/TextTrackCueEventTypes#/s:13THEOplayerSDK22TextTrackCueEventTypesV4EXITAA0F4TypeCyAA0e4ExitF0CGvpZ) events through the [`TextTrackCue`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/TextTrackCue) interface. The `ENTER` event is dispatched when a cue becomes active and the `EXIT` event is dispatched when a cue becomes inactive. You can fetch the actual content in the callback of your `ENTER` event through its [`content`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/TextTrackCue#/s:13THEOplayerSDK12TextTrackCueP7contentypSgvp) property.

Alternatively, in the callback of your `ADD_TRACK` event, you could track the [`CUE_CHANGE`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/TextTrackEventTypes#/s:13THEOplayerSDK19TextTrackEventTypesV10CUE_CHANGEAA0E4TypeCyAA09CueChangeE0CGvpZ) event through the `TextTrack` interface. Then, in the callback of your `CUE_CHANGE` event, you want to iterate over the active cues. For each active cue, you could also query its `content` property.

The code below allows you to detect the active text track cues.

```swift
player.textTracks.addEventListener(type: TextTrackListEventTypes.ADD_TRACK) { (e1) in
    var track : TextTrack = e1.track as! TextTrack
    track.addEventListener(type: TextTrackEventTypes.ADD_CUE) { (e2) in
        let cue = e2.cue
        cue.addEventListener(type: TextTrackCueEventTypes.ENTER) { (e3) in
            print(e3, e3.cue.content)
        }
        cue.addEventListener(type: TextTrackCueEventTypes.EXIT) { (e3) in
            print(e3)
        }
    }
    track.addEventListener(type: TextTrackEventTypes.CUE_CHANGE) { (e2) in
        let textTrack : TextTrack = e2.track as! TextTrack
        let cues = textTrack.activeCues
        cues.forEach { (cue) in
            print("cuechange active cue", cue)
        }
    }
}
// ...
// player.source = ...
```

You want to invoke these event handlers before you configure your stream, because your video player might have already dispatched the event before you were able to subscribe to it.

### Roku SDK

*This subsection is in maintenance. Reach out to our team if you need help.*

## Implementation for timed metadata

The implementation for timed metadata is identical to the one for subtitles and closed captions, except for three things.

1. You don't necessarily use the `enter` event. Some types of timed metadata, for example ID3 cues, only related to one specific moment, and those types only have an `exit` trigger.

2. You might need to set the `mode` of the relevant text track to `hidden`, as documented in ["How to programmatically enable or disable text tracks"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-programmatically-disable-text-tracks.md). Some types of timed metadata, for example EXT-X-DATERANGE and EventStream, are `disabled` by default. You should add a condition to your `addtrack` callback to decide whether you want to set your track to `hidden`.

3. You should set `hlsDateRange` to `true` if you want to detect EXT-X-DATERANGE tags in an HLS stream in your PlayerConfiguration or stream configuration. Refer to the [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerConfiguration#hlsDateRange), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/THEOplayerConfig.Builder#hlsDateRange\(boolean\)) or [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayerConfiguration) documentation for more info.

The article on ["how to track id3 cues / tags"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-track-id3-cues-tags.md) might be useful to learn more about detecting ID3 tags specifically.

---

# Introduction

THEOplayer has a default user interface (UI). The default UI is optimized for browsers, mobile devices and tablets. As a developer, you may A) use this UI as is, B) customize it, or C) create a brand-new Chromeless UI, as depicted in the screenshot below.

![THEOplayer UI overview](/pr-932/assets/images/ui-introduction-overview-03ba6a2cf9c5dafe7480f59155541b41.png "THEOplayer UI overview")

The default UI is responsive, so it looks different depending on your device, as visualized in the screenshot below.

![THEOplayer default UI](/pr-932/assets/images/ui-introduction-default-ui-60eb17b239311a93c4099657dcaf8651.png "THEOplayer default UI")

The default UI has all the basic controls you'd expect from a video player, ranging from a scrub bar to a fullscreen button.

Building a Chromeless UI means building a new UI from scratch using the THEOplayer API and custom application code. In other words: you are responsible for inserting your own controls (e.g. a play button), and connecting it with the THEOplayer API (e.g. `player.play()`).

Note that some features are dependent on our default UI, because they are built on top of our default UI. For example, the [Up Next](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/up-next.md) feature (and API) wouldn't work when you build a Chromeless UI.

## Customize the UI

The next sections tackle the following topics:

1. [Default UI versus Chromeless UI](#default-ui-versus-chromeless-ui)
2. [Modify default UI](#modify-default-ui)
3. [Implement Chromeless UI](#implement-chromeless-ui)

### Default UI versus Chromeless UI

It's possible that the envisioned design of your video player looks different from THEOplayer's default UI. When that happens, your team has to decide whether to A) customize THEOplayer's default UI, or B) implement a Chromeless UI.

The default UI has all the basic functionality you expect from a video player, but it might be missing some more exotic UI (or UX) features. Changing the colors of the default UI is relatively straightforward, as is hiding a default control item (e.g. the fullscreen button), as is inserting a new button in the default control bar. However, truly transforming the default UI, such as repositioning elements, using all new icons, and more complex operations, can be quite challenging.

Implementing a Chromeless UI gives you total control of your UI and UX. However, this requires an understanding of video and the THEOplayer API, and you might feel like you're reinventing the wheel.

So what to pick: modify the default UI or implement a Chromeless UI?

If the envisioned design looks "quite different" from the default UI, we encourage people to implement a Chromeless UI. Alternatively, if that isn't an option, we advise people to compromise, and to adapt their envisioned design to look "quite similar" to the default UI.

Our default UI is not optimized for big screen devices like Samsung Tizen, LG webOS and Android TV. If you're targeting those (and similar devices), you should consider implementing a Chromeless UI, as demonstrated on our [Tizen](https://github.com/THEOplayer/samples-tizen) and [webOS](https://github.com/THEOplayer/samples-webos) GitHub repositories.

Our default UI for Apple TV (i.e. tvOS SDK) is similar to the default Apple TV video player. You should consider a Chromeless UI for this platform should you want to divert from this design.

### Modify default UI

You can modify the default UI through JavaScript and CSS.

Changing the colors is quite easy. There's a GUI when building your Web SDK at <https://portal.theoplayer.com> to generate code (depicted in the screenshot below), or you can use a similar tool at <https://demo.theoplayer.com/ui-skinning>. More information on changing the colors is available at our article on [UI skinning](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/ui-skinning.md).

![UI editor on portal](/pr-932/assets/images/ui-introduction-portal-4705aec7c4a71c082932485a32599949.png "UI editor on portal")

The default UI is a fork of Video.js 5, so you may also use the Video.js 5 API to modify the UI, as demonstrated in some of our articles. This may - for example - simplify the process of [adding a new button](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-insert-a-button.md) to the default control bar.

Removing a button is a matter of identifying the appropriate CSS selector, and configuring `display: none!important`.

Overlaying text and images is a matter of overlaying a custom `<div>` (or native element) on top of the THEOplayer container.

#### iOS and Android SDK

As of THEOplayer version 5, the iOS and Android SDKs no longer ship a default UI. We recommend switching to our [Open Video UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/ui/android/open-video-ui.md) (for Android) or our [React Native UI](https://github.com/THEOplayer/react-native-theoplayer-ui) (for Android and iOS).

For THEOplayer version 4 and lower, the default UI is the same UI as our Web SDK. See [our version 4 documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/how-to-guides/ui/introduction#ios-and-android-sdk) for more information.

#### Related articles

Below are some articles related to modifying our default UI:

* [Is it possible to remove an element from the UI?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/is-it-possible-to-remove-an-element.md)
* [How to align the timeline in the middle](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-align-timeline-in-the-middle.md)
* [How to change the Big Play Button?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-change-big-play-button.md)
* [How to make the control bar always visible?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-make-control-keys-always-visible.md)
* [Is it possible to hide/disable the Google IMA UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/is-it-possible-to-hide-googla-ima.md)
* [How to insert a button](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-insert-a-button.md)
* [How to change the default UI language to other](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-change-default-UI-language-to-other.md)
* [Customize UI during ad playback](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/customize-ui-during-playback.md)
* [How to change how a video should be fit inside of a container](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-change-how-a-video-should-fit-inside-a-container.md)
* [How to make an audio-only player](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-make-audio-only-player.md)
* [Customizing the UI: vertical volume slider](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/customising-vertical-volume-slider.md)
* [UI Skinning](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/ui-skinning.md)

### Implement Chromeless UI

Building a Chromeless UI may be daunting at first, but it's rewarding. A Chromeless UI gives you full control over your UI and UX, but you must understand the flow of a video, its API and its events.

Refer to our article on [How to build a Chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md) for more information.

#### iOS and Android SDK

You can implement a Chromeless UI on iOS and Android completely on top of THEOplayer through the native technologies and programming languages. The THEOplayer API exposes all the events and properties that you need to implement a custom design.

---

# Is it possible to remove an element from the UI?

This question may be asked if you want to limit the options/controls that are showed in the UI.

There are three possible approaches to this:

1. Use the Chromeless version and build your own UI on top of it. This may be useful if you do not need to remove just one element, but want a radically different UI.
2. Hide the element through CSS
3. Remove it through JavaScript

In the following we will briefly explore the last two possibilities.

## SDKs

| Web SDK | Android SDK                      | iOS SDK                          | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | -------------------------------- | -------------------------------- | -------- | -------------- | -------------- |
| Yes     | Through CSS/JavaScript injection | Through CSS/JavaScript injection | N/A      | N/A            | N/A            |

## Code examples

For this example we will consider the Speed menu option (control bar > Settings > Speed) as the element to remove from the page. The following methods may of course be used for other elements.

##### Web SDK

**Hide the element with CSS**

We identify the element and hide it. Since In this specific case there is no id or class to identify this element specifically, we make use of its aria attribute. Of course, should it change, this line of code should be adapted accordingly.

```css
.theoplayer-skin li[aria-label='Open the video speed settings menu'] {
  display: none !important;
}
```

**Remove the element through JavaScript**

In alternative to CSS, it is also possible to achieve the same result with JavaScript, in the following way.

```js
function firstplay(event) {
  player.removeEventListener('playing', firstplay);
  var speed = document.querySelector('.theoplayer-skin li[aria-label="Open the video speed settings menu"]');
  speed.parentNode.removeChild(speed);
}
player.addEventListener('sourcechange', function () {
  player.removeEventListener('playing', firstplay);
  player.addEventListener('playing', firstplay);
});
```

##### Legacy Android SDK (4.12.x)

To achieve the same result on Android SDK, the same CSS need to be passed to your app.

**Step 1**

To learn how to inject CSS into your Android project, follow the guide [Android SDK Customization - Custom CSS and JavaScript files](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

**Step 2**

In the CSS or JavaScript file you created, add the code reported above in the Web SDK section.

##### Legacy iOS/tvOS SDK (4.12.x)

To achieve the same result on iOS SDK, the same CSS need to be passed to your app.

**Step 1**

To learn how to inject CSS into your iOS project, follow the guide [iOS SDK Customization - Custom CSS and JavaScript files](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

**Step 2**

In the CSS or JavaScript file you created, add the code reported above in the Web SDK section.

##### Roku SDK

What UI elements should be visible for Chromefull THEOplayer on Roku? Currently, Chromefull THEOplayer uses Roku native player and that one has e.g. a clock UI element while paused.

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="TestScene" extends="Scene">
    <interface>
    </interface>

    <script type = "text/brightscript" >

        <![CDATA[

        function Init()
            m.player = m.top.findNode("TestPlayer")
            m.player.configuration = {
              "license": "" ' put the THEOplayer license between apostrophes
            }
            ' remove the clock UI node
            m.player.getChildren(-1, 0)[0].getChildren(-1, 0)[1].removeChildIndex(11)

            setSource()
            m.player.setFocus(true)
            m.player.callFunc("play")
        end function

        function setSource()
            sourceDescription = {
                "sources": [
                    {
                        "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
                        "type": "application/x-mpegURL"
                    }
                ]
            }
            m.player.source = sourceDescription
            m.player.source.Live = false
            m.player.source.LiveBoundsPauseBehavior = "pause"
        end function

        ]]>

    </script>

    <children>
	    <THEOsdk:THEOplayer id="TestPlayer"/>
    </children>
</component>
```

---

# How to align the timeline in the middle

This question is asked when developers want to change the appearance of the current time digits and duration digits in the seekbar. For example, instead of having it aligned on the left of the control bar, they might want to have it in the middle.

Please note that this article isn't final.

![Align timeline middle](/pr-932/assets/images/align-timeline-middle-66bdd5275fa323e16204484e31301562.png "Align timeline middle")

## SDKs

| Web SDK | Android SDK                      | iOS SDK                          | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | -------------------------------- | -------------------------------- | -------- | -------------- | -------------- | -------- |
| Yes     | Through CSS/JavaScript injection | Through CSS/JavaScript injection | N/A      | N/A            | N/A            | N/A      |

## Approach #1

##### Web SDK

One approach is to create a new overlay. The code snippet below implements this strategy.

CSS

```css
.custom-timeline {
  display: none;
  bottom: 0;
  position: absolute;
  width: 100%;
  text-align: center;
  line-height: 36px;
  pointer-events: none;
}

.vjs-has-started .custom-timeline.show {
  display: block;
}

.vjs-time-control {
  display: none !important;
}

.theo-mobile .custom-timeline {
  display: none;
}

.vjs-fullscreen .custom-timeline {
  margin-bottom: 8px;
}
```

HTML and JS

```html
<div class="video-container video-js theoplayer-skin">
  <div class="custom-timeline"><span class="current-time">00:00:00</span> / <span class="duration"></span></div>
</div>
<script>
  var player = new THEOplayer.Player(element, playerConfig);
  ...
  function secondsToHms(d) {
      d = Number(d);
      var h = Math.floor(d / 3600);
      var m = Math.floor(d % 3600 / 60);
      var s = Math.floor(d % 3600 % 60);

      var hDisplay = h > 0 ? h + (h == 1 ? ":" : ":") : "00:";
      var mDisplay = m > 0 ? m + (m == 1 ? ":" : ":") : "00:";
      var sDisplay = s;
      return hDisplay + mDisplay + sDisplay;
  }

  player.addEventListener('timeupdate', function(e) {
      document.querySelector('.custom-timeline .current-time').innerText = secondsToHms(Math.floor(e.currentTime));
  })

  player.addEventListener('durationchange', function(e) {
      document.querySelector('.custom-timeline .duration').innerText = secondsToHms(Math.floor(e.duration));
      document.querySelector('.custom-timeline').classList.add('show');
  })
  ...
</script>
```

##### Android SDK

To achieve the same result on Android SDK, the same CSS need to be passed to your app.

**Step 1**

To learn how to inject CSS into your Android project, follow the guide [Android SDK Customization - Custom CSS and JavaScript files](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

**Step 2**

In the CSS and JavaScript files you created, add the code reported above in the Web SDK section.

##### Legacy iOS/tvOS SDK (4.12.x)

To achieve the same result on iOS SDK, the same CSS need to be passed to your app.

**Step 1**

To learn how to inject CSS into your iOS project, follow the guide [iOS SDK Customization - Custom CSS and JavaScript files](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

**Step 2**

In the CSS and JavaScript files you created, add the code reported above in the Web SDK section.

---

# How to change the Big Play Button?

The question above is typically asked by developers who want to increase/decrease the size, set a different image instead, or introduce on-hover behavior.

## SDKs

| Web SDK | Android SDK           | iOS SDK               | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | --------------------- | --------------------- | -------- | -------------- | -------------- | -------- |
| Yes     | Through CSS injection | Through CSS injection | N/A      | N/A            | N/A            | N/A      |

## Code example

The snippet below demonstrates how you could set another image instead of the default big play button. Additionally, the button becomes bigger when you hover it.

##### Web SDK

```css
/* Increase button size when hovering */
.theoplayer-skin .vjs-big-play-button:hover {
  background: none;
  -webkit-transition-duration: 0.2s;
  -moz-transition-duration: 0.2s;
  transition-duration: 0.2s;
  transform: translate(-50%, -50%) scale(1.2);
  transition: transform 0.2s;
}
/* Set other image */
.theoplayer-skin .vjs-big-play-button:before {
  content: '';
  background: url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+Cjxzdmcgd2lkdGg9IjcycHgiIGhlaWdodD0iNzJweCIgdmlld0JveD0iMCAwIDcyIDcyIiB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiPgogICAgPCEtLSBHZW5lcmF0b3I6IFNrZXRjaCA0My4yICgzOTA2OSkgLSBodHRwOi8vd3d3LmJvaGVtaWFuY29kaW5nLmNvbS9za2V0Y2ggLS0+CiAgICA8dGl0bGU+dmlkZW8gaWNvbiBjb3B5IDQ8L3RpdGxlPgogICAgPGRlc2M+Q3JlYXRlZCB3aXRoIFNrZXRjaC48L2Rlc2M+CiAgICA8ZGVmcz48L2RlZnM+CiAgICA8ZyBpZD0iSG9tZXBhZ2UiIHN0cm9rZT0ibm9uZSIgc3Ryb2tlLXdpZHRoPSIxIiBmaWxsPSJub25lIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPgogICAgICAgIDxnIGlkPSJIb21lcGFnZS1fZGVza3RvcCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoLTQ3MC4wMDAwMDAsIC0zMDEyLjAwMDAwMCkiPgogICAgICAgICAgICA8ZyBpZD0iZnd0diIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTIwLjAwMDAwMCwgMjc4OC4wMDAwMDApIj4KICAgICAgICAgICAgICAgIDxnIGlkPSJiaWctdmlkZW8iIHRyYW5zZm9ybT0idHJhbnNsYXRlKDAuMDAwMDAwLCA1MC4wMDAwMDApIj4KICAgICAgICAgICAgICAgICAgICA8ZyBpZD0idmlkZW8tMnB4IiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgzNTEuMDAwMDAwLCAxNzUuMDAwMDAwKSI+CiAgICAgICAgICAgICAgICAgICAgICAgIDxnIGlkPSJ2aWRlby1jb3B5IiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgzNS4wMDAwMDAsIDM1LjAwMDAwMCkgcm90YXRlKC0zNjAuMDAwMDAwKSB0cmFuc2xhdGUoLTM1LjAwMDAwMCwgLTM1LjAwMDAwMCkgIj4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxjaXJjbGUgaWQ9Ik92YWwtMiIgc3Ryb2tlPSIjRkZGRkZGIiBzdHJva2Utd2lkdGg9IjIiIGZpbGwtb3BhY2l0eT0iMC4xNSIgZmlsbD0iIzAwMDAwMCIgY3g9IjM1IiBjeT0iMzUiIHI9IjM1Ij48L2NpcmNsZT4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxwb2x5Z29uIGlkPSJUcmlhbmdsZSIgZmlsbD0iI0ZGRkZGRiIgcG9pbnRzPSIyNi45ODI4NTY5IDQ5Ljk1Mzc1MiAyNi45ODI4NTY5IDE5LjM0MjEwNTMgNDguNTQzNDU4OSAzMy45OTY5NDI5Ij48L3BvbHlnb24+CiAgICAgICAgICAgICAgICAgICAgICAgIDwvZz4KICAgICAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgIDwvZz4KICAgICAgICA8L2c+CiAgICA8L2c+Cjwvc3ZnPg==')
    no-repeat 0 0;
  /* background: url('http://i.stack.imgur.com/LT3WE.png') no-repeat 0 0; */ /* Use image instead */
  background-size: 100%;
  display: block;
}
/* Remove default THEOplayer image */
.theo-big-play-button-svg-container svg {
  display: none;
}
/* Remove default spotlight around button on focus */
.theoplayer-skin:hover .vjs-big-play-button:after,
.theoplayer-skin .vjs-big-play-button:focus:after {
  opacity: 0;
}
```

##### Legacy Android SDK (4.12.x)

To achieve the same result on Android SDK, the same CSS need to be passed to your app.

**Step 1**

To learn how to inject CSS into your Android project, follow the guide [Android SDK Customization - Custom CSS and JavaScript files](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

**Step 2**

In the CSS file you created, add the code reported above in the Web SDK section.

##### Legacy iOS/tvOS SDK (4.12.x)

To achieve the same result on iOS SDK, the same CSS need to be passed to your app.

**Step 1**

To learn how to inject CSS into your iOS project, follow the guide [iOS SDK Customization - Custom CSS and JavaScript files](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

**Step 2**

In the CSS file you created, add the code reported above in the Web SDK section.

The snippet above also removes some default behavior, such as the shadow-effect when hovering the big play button.

![Big Play Button](/pr-932/assets/images/big-play-button-7ba8ac3c1d83a855d6fb4f1035f4c466.png "Big Play Button")

---

# How to make the control bar always visible?

The question above is typically asked by developers who want to be able to see the control bar at all times without having to continuously move the cursor over it (or tap the screen).

## SDKs

| Web SDK | Android SDK           | iOS SDK               | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
| ------- | --------------------- | --------------------- | -------- | -------------- | -------------- | -------- |
| Yes     | Through CSS injection | Through CSS injection | N/A      | N/A            | N/A            | N/A      |

## Code examples

##### Web SDK

The following CSS line is aimed at overwriting the opacity transition and have the control bar always visible.

```css
.theo-secondary-color.vjs-control-bar {
  opacity: 1 !important;
}
```

##### Legacy Android SDK (4.12.x)

To achieve the same result on Android SDK, the same CSS need to be passed to your app.

**Step 1**

To learn how to inject CSS into your Android project, follow the guide [Android SDK Customization - Custom CSS and JavaScript files](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

**Step 2**

In the CSS file you created, add the code reported above in the Web SDK section.

##### Legacy iOS/tvOS SDK (4.12.x)

To achieve the same result on iOS SDK, the same CSS need to be passed to your app.

**Step 1**

To learn how to inject CSS into your iOS project, follow the guide [iOS SDK Customization - Custom CSS and JavaScript files](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios).

**Step 2**

In the CSS file you created, add the code reported above in the Web SDK section.

---

# Is it possible to hide/disable the Google IMA UI?

You may ask this question if you are trying to determine what controls are visible to the user during ads and want therefore to use your own UI elements.

Unfortunately Google IMA provides very limited control over the UI. The only thing that is possible to change/hide from THEOplayer is the countdown: to do so, you can configure as `*showCountdown: false*` in the AdsConfiguration ([related documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/Player)).

Using other methods, like CSS or JavaScript, to modify the Google IMA UI elements styles will also not work due to:

* the usual higher specificity of the *iframe* CSS
* the security restrictions on XSS.

---

# How to build a Chromeless UI

A Chromeless UI comes into play when your envisioned video player UI too different from the default [THEOplayer UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/introduction.md).

Building a Chromeless UI means building a brand-new video player UI from scratch. You achieve this by implementing your own custom UI components, and by associating those components with the appropriate THEOplayer API. The screenshot below visualizes such a Chromeless UI -- albeit not the most pretty one.

![Chromeless UI Layout](/pr-932/assets/images/chromeless-ui-7-4025542f4b233096015b9e6ecce5bcd5.png "Chromeless UI Layout")

A Chromeless UI gives you complete control over your full UI and UX, but it also means that you responsible for implementing your full UI and UX. Achieving this feat requires you to have an adequate grasp on the video player architecture and its underlying API.

The goal of this guide is to advance your understanding on how to connect the dots between custom components and the THEOplayer API. For example, this guide will explain to which THEOplayer APIs you could map your custom play button.

*Tip: go to our Chromeless UI samples for Web, [iOS](https://github.com/THEOplayer/samples-ios-sdk/tree/master/Custom-UI), [Android](https://github.com/THEOplayer/samples-android-sdk/tree/master/Custom-UI) and [Roku](https://github.com/THEOplayer/samples-roku-sdk/tree/master/basic-playback-app/components/ChromelessView) on GitHub if you want to go straight to completed code samples.*

You can create a Chromeless UI on all THEOplayer SDKs.

## Creating a Chromeless player instance

The article will often mention `player` variable. This `player` variable is a "Chromeless" instance created through the THEOplayer constructor.

#### Web SDK

The API reference on creating a Chromeless player instance for the THEOplayer Web SDK is located at [ChromelessPlayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#constructor).

When you're implementing a Chromeless UI, you don't need to include the THEOplayer CSS library (i.e. `ui.css`) mentioned in our [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md), nor do you need to specify some default CSS classed.

Additionally, instead of including `THEOplayer.js` as mentioned in our [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md), you'll include `THEOplayer.chromeless.js`, as demonstrated by the snippet below.

```html
<script type="text/javascript" src="/path/to/THEOplayer.chromeless.js"></script>
```

The snippet below demonstrates how you set up a Chromeless player instance through the THEOplayer Web SDK API.

```javascript
var element = document.querySelector('.theoplayer-container');
var player = new THEOplayer.ChromelessPlayer(element, {
  libraryLocation: '/path/to/your-theoplayer-folder/',
  license: 'your_license_string',
});
```

Notice how this snippet uses `ChromelessPlayer` instead of `Player`. The `element` variable refers to an existing DOM element. If we modified our template in the [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md) to be Chromeless, it would resemble the code below.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>THEOplayer Chromeless</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
  <body>
    <div class="theoplayer-container"></div>
    <script type="text/javascript" src="/path/to/THEOplayer.chromeless.js"></script>
    <script>
      var element = document.querySelector('.theoplayer-container');
      var player = new THEOplayer.ChromelessPlayer(element, {
        libraryLocation: '/path/to/your-theoplayer-folder/',
        license: 'your_license_string',
      });
      player.source = {
        sources: [
          {
            src: '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8',
            type: 'application/x-mpegurl',
          },
        ],
      };
    </script>
  </body>
</html>
```

Of course, you would still need to apply CSS to style your `theoplayer-container`, and give it a width and height.

##### Legacy Android SDK (4.12.x)

The API reference on creating a Chromeless player instance for the THEOplayer Android SDK is located at [THEOplayerView](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/THEOplayerView).

When creating an instance, you need to provide a [`THEOplayerConfig`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/THEOplayerConfig), and set `chromeless` to `true`. The snippet below demonstrates how to create a Chromeless instance.

```java
THEOplayerConfig config = new THEOplayerConfig.Builder()
        .chromeless(true)
        .license("your_license_string")
        .build();
THEOplayerView theoplayerView = new THEOplayerView(this, config);
Player player = theoplayerView.getPlayer();
```

If you are creating your `THEOplayerView` through XML, then you can specify `app:chromeless="true"` as implemented at <https://github.com/THEOplayer/samples-android-sdk/blob/master/Custom-UI/app/src/main/res/layout/activity_player.xml>.

#### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

The API reference on creating a Chromeless player instance for the THEOplayer iOS SDK is located at [THEOplayer](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer).

When creating an instance, you need to [`THEOplayerConfig`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayerConfiguration), and set `chromeless` to `true`. The snippet below demonstrates how to create a Chromeless instance.

```swift
let config = THEOplayerConfiguration(
    chromeless: true,
    pip: nil,
    license: "your_license_string"
)
let player = THEOplayer(configuration: config)
```

## Using a WebView in legacy Android/iOS SDKs (4.12.x)

As mentioned in our [introduction](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/introduction.md#ios-and-android-sdk), the legacy Android and iOS SDKs (4.12.x) use a WebView for their default UI. You may leverage this existing WebView to create a custom Chromeless UI for our Android and iOS SDK through a combination of JavaScript, CSS and HTML.

See [our version 4 documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/how-to-guides/ui/how-to-build-chromeless-ui#using-a-webview) for more information.

## Tracking transitions between states

Refer to the article on ["How to track player states"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/how-to-track-player-states.md) to advance your understanding on video player states. Understanding the video player lifecycle is a vital part of building a Chromeless UI.

![Video Player States](/pr-932/assets/images/player-video-player-states-4f4f37f92d4b03a2c750ce7fe03d0a5a.png "Video Player States")

This article explains how to track the start of a video and its end, but also how to detect buffering, errors and much more. You'll need to implement (some of) these transitions in your Chromeless UI in order to render the appropriate components.

## Mapping components

A video player UI can be dissected into different components (or controls). A component offers context, and it may also offer an action. The "play button" is an example of an action component, but the "current time text" (X in the screenshot below) is a context component.

As a developer, you should understand which controls are out there, and which video player APIs are relevant.

This section addresses the following components:

1. Play button
2. Pause button
3. Volume mute button
4. Volume change button
5. Current time text
6. Duration text
7. Scrub bar
8. Buffered blocks
9. Live button
10. Audio change component
11. Subtitle change component
12. Video quality change component
13. Fullscreen and inline button
14. Picture-in-picture button
15. Chromecast button
16. AirPlay button

Additionally, we'll discuss the following overlays:

1. Subtitle cues
2. Advertisement metadata

![Chromeless UI Layout](/pr-932/assets/images/chromeless-ui-layout-3642d810cba7de946ee7cb69b7ab238b.png "Chromeless UI Layout")

Instead of providing inline code on this article, we'll refer to other articles as much as possible, because linking the THEOplayer API to your custom components is an application of many of the existing how-to guides for a specific use-case.

If you know how to navigate our API references, you don't even need this section. The graphic below (originally referenced in ["custom analytics integration"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/analytics/custom-analytics-integration.md)) gives a basic overview of many of the relevant interfaces and events.

![THEOplayer API Interfaces and Events](/pr-932/assets/images/analytics-events-185d6ab52b556af08d8300b545ae5876.png "THEOplayer API Interfaces and Events")

### Play button

You should show your play button when you are in a paused state, as described in ["how to track player states"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/how-to-track-player-states.md). If a viewer clicks your play button, you should call the `play()` on your `player` instance as documented across our [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#play), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#play--) and [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/c:@M@THEOplayerSDK@objc\(cs\)THEOplayer\(im\)play) documentation.

### Pause button

You should show your pause button when you are in a playing state, as described in ["how to track player states"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/player/how-to-track-player-states.md). If a viewer clicks your pause button, you should call the `pause()` on your `player` instance as documented across our [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#pause), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#pause--) and [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/c:@M@THEOplayerSDK@objc\(cs\)THEOplayer\(im\)pause) documentation.

### Volume mute button

You can check whether your volume is muted through the `muted` property (or method) on your `player` instance as documented across our [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#muted), Android ([isMuted()](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#isMuted--) and [setMuted()](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#setMuted-boolean-)) and [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C5mutedSbvp) documentation. You should consider showing a different button depending on whether `muted` returns `true` or `false`. If a viewer clicks your mute button, you should set `muted` to `!muted`.

### Volume change button

You can get and set your volume level through the `volume` property (or method) on your `player` instance as documented across our [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#volume), Android ([getVolume()](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#getVolume--) and [setVolume()](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#setVolume-double-)) and [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C6volumeSfvp) documentation. You should consider showing a different button depending on the volume level.

Note that you cannot control the volume level on iOS- and Android-based SDKs as this is delegated to the hardware buttons. You can only toggle the muted state on these SDKs.

### Current time text

You can get the current time through the `currentTime` property (or method) on your `player` instance as documented across our [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#currentTime), Android ([requestCurrentTime()](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#requestCurrentTime-com.theoplayer.android.api.player.RequestCallback-) and [setCurrentTime()](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#setCurrentTime-double-)) and iOS ([requestCurrentTime()](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C18requestCurrentTime17completionHandleryySdSg_s5Error_pSgtc_tF) and [setCurrentTime()](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C14setCurrentTime_17completionHandlerySd_yypSg_s5Error_pSgtcSgtF)) documentation.

Note that `currentTime` returns a relative value in seconds. If you are dealing with live streams, you might want to use `currentProgramDateTime` instead, as this returns an absolute value like `"2022-04-01T13:37:42.666Z"`. This property (or method) is especially useful when implementing an [EPG](https://en.wikipedia.org/wiki/Electronic_program_guide) experience.

### Duration text

You can get the duration of a stream through the `duration` property (or method) on your `player` instance as documented across our [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#duration), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#getDuration--) and [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C8durationSdSgvp) documentation.

The `duration` will return the duration in seconds for VOD streams, and `Infinity` for live streams.

You can calculate the remaining duration by subtracting the `currentTime` from the `duration`.

### Scrub bar

Related to the subsection on "Current time text", you can seek to a different playhead position through the `currentTime` property (or `setCurrentTime()` method) on your `player` instance. Alternatively, for live streams, you may also use `currentProgramDateTime` to seek to absolute playhead positions.

You can only seek to a playhead position that is within any of the time ranges of your `seekable` property (or method) of your `player` instance as documented across our [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#seekable), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#requestSeekable-com.theoplayer.android.api.player.RequestCallback-) and [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C15requestSeekable17completionHandleryySayAA9TimeRangeCGSg_s5Error_pSgtc_tF) documentation. For example, on the Web SDK, this means that you'll stay between `player.seekable.start(0)` and `player.seekable.end(player.seekable.length-1)`.

You subscribe to the `timeupdate` event to periodically update your scrub bar bullet. This event is dispatched every \~200ms during playback. Refer to our [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#timeupdate), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/player/PlayerEventTypes#TIMEUPDATE) and [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/PlayerEventTypes#/s:13THEOplayerSDK16PlayerEventTypesV11TIME_UPDATEAA0D4TypeCyAA010TimeUpdateD0CGvpZ) documentation for more info on this event.

A `seek` event is dispatched when you set a new value for `currentTime` or `currentProgramDateTime`. A `seeked` event is dispatched when the seek was successful. Refer to our [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#seeking), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/player/PlayerEventTypes#SEEKING) and [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/PlayerEventTypes#/s:13THEOplayerSDK16PlayerEventTypesV7SEEKINGAA0D4TypeCyAA07SeekingD0CGvpZ) documentation for more info on these events. You should consider displaying a "stalling icon" between these two events.

#### Buffered blocks

You may also want to annotate parts of the scrub bar that have already been buffered. When the viewer seeks to a buffered block playback immediately starts.

You can track information on what's being buffered through the `progress` event. Refer to our [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#progress), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/event/player/PlayerEventTypes#PROGRESS) and [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Structs/PlayerEventTypes#/s:13THEOplayerSDK16PlayerEventTypesV8PROGRESSAA0D4TypeCyAA08ProgressD0CGvpZ) documentation for more info on this event. In the callback of the `progress` event, you will want to query the `buffered` property (or method) to iterate through the available buffered time ranges. The `buffered` property (or method) is described in our [Web](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#buffered), [Android](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#requestBuffered-com.theoplayer.android.api.player.RequestCallback-) and [iOS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C15requestBuffered17completionHandleryySayAA9TimeRangeCGSg_s5Error_pSgtc_tF) documentation.

### Live button

A stream is a live stream when your `duration` property (or method) returns `Infinity`. If you want to implement a button that takes you to the "most live point" when clicked, then you set `currentTime` to the maximum `seekable` `end` time. For example, on the Web SDK, you would call `player.currentTime = player.seekable.end(player.seekable.length-1)`.

### Audio change component

Refer to the article on ["how to detect audio tracks"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-audio-tracks.md) to know how to detect the available audio tracks. You'll need this article to know which audio tracks are part of your stream.

Refer to the article on ["how to enable and disable audio tracks"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-enable-disable-audio-tracks.md) to know how to enable or disable another audio track. You'll need this article to enable another audio track.

Refer to the article on ["how to detect audio track changes"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-audio-track-changes.md) to know how to detect when an audio track has been enabled or disabled. You'll need this article to correctly annotate your UI.

### Subtitle change component

Refer to the article on ["how to detect text tracks"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-programmatically-detect-text-tracks.md) to know how to detect the available text tracks. You'll need this article to know which subtitles and closed captions are part of your stream.

Refer to the article on ["how to enable and disable text tracks"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-programmatically-disable-text-tracks.md) to know how to enable or disable another text track.

Refer to the article on ["how to detect text track changes"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-detect-text-track-changes.md) to know how to detect when a text track has been enabled or disabled. You'll need this article to correctly annotate your UI.

### Video quality change component

Refer to the article on ["how to detect video track qualities"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-qualities.md) to know how to detect the available video track qualities. You'll need this article to know which video qualities are part of your stream.

Refer to the article on ["how to select video track quality"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-select-video-track-quality.md) to know how to enable another video track quality.

Refer to the article on ["how to detect video track quality changes"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/mediatrack/how-to-detect-video-track-quality-changes.md) to know how to detect when a specific video track quality has become active. You'll need this article to correctly annotate your UI.

### Fullscreen and inline button

Getting your video player in and out fullscreen requires some getting used to, and differs a bit across SDKs.

#### Web SDK

You cannot use our [`Presentation API`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Presentation) to switch between fullscreen, inline and picture-in-picture. Instead, you need to implement your own fullscreen handling.

One approach to achieve this is by using the `Fullscreen API` as described at <https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API>. Additionally, to deal with iOS browsers, you can leverage [`webkitEnterFullscreen()`](https://developer.apple.com/documentation/webkitjs/htmlvideoelement/1633500-webkitenterfullscreen), or resize your video player container to a 100% width and height.

#### Android SDK

You cannot use our ['FullscreenManager API\`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/fullscreen/FullScreenManager) to switch between fullscreen and inline. Instead, you need to implement your own fullscreen handling, as well as any associated orientation changes.

Refer to <https://developer.android.com/training/system-ui/immersive> for more information on implementing your own fullscreen handling.

#### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

You may use the [`presentationMode`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C16presentationModeAA012PresentationD0Ovp) property of the `player` instance, as demonstrated in the snippet below.

```swift
if (player.presentationMode == PresentationMode.fullscreen) {
    player.presentationMode = PresentationMode.inline
} else {
    player.presentationMode = PresentationMode.fullscreen
}
```

You may also use [`fullscreenOrientationCoupling`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Classes/THEOplayer#/s:13THEOplayerSDK0A0C29fullscreenOrientationCouplingSbvp) to automatically enter fullscreen when the viewer goes into landscape mode.

Forcing the video player to rotate into landscape when you hit the fullscreen button in portrait mode is something that you need to implement on top of THEOplayer. (For example through a combination of [`UIDevice`](https://developer.apple.com/documentation/uikit/uidevice) and [`UIInterfaceOrientation`](https://developer.apple.com/documentation/uikit/uiinterfaceorientation).)

Do note that when you leverage our `presentationMode` you must add your custom components as subviews of the `THEOplayerView`, because your components won't remain visible otherwise. In other words, you'll have to identify the appropriate subview X of the view Y to which you have (indirectly) added your `player` instance as a subview X. (You do this by querying the subviews of view Y.)

You may also implement fullscreen management on top of THEOplayer. This is worth considering if you want more control and flexibility.

### Picture-in-picture button

You should implement your Picture-in-Picture UI and UX independently of THEOplayer, regardless of whether you're considering "in-app" picture-in-picture or "out-of-app" picture-in-picture. The [THEOplayer Picture-in-Picture API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/picture-in-picture.md) is not available for Chromeless players.

To get the active video element on the THEOplayer Web SDK you may query `player.element.querySelectorAll('video[src]')[0]`.

Related resources:

* <https://developers.google.com/web/updates/2017/09/picture-in-picture>
* <https://developer.apple.com/documentation/webkitjs/adding_picture_in_picture_to_your_safari_media_controls>
* <https://developer.android.com/guide/topics/ui/picture-in-picture>
* <https://developer.apple.com/documentation/avkit/adopting_picture_in_picture_in_a_custom_player>

Note that it might not be possible to implement out-of-app Picture-in-Picture on the THEOplayer iOS SDK.

### Chromecast button

Refer to our [introduction on Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/introduction.md) to know how to track the availability of Chromecast, and how to start and stop a Chromecast session.

### AirPlay button

Refer to our [introduction on AirPlay](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/airplay/introduction.md) to know how to track the availability of AirPlay, and how to start and stop an AirPlay session.

### Subtitle cues

You may still leverage THEOplayer's default rendering of subtitles (and closed captions) in your Chromeless UI. This may require some extra styling though, depending on your SDK. For example, on the Web SDK, you may have to set a default `font-size` through CSS, as demonstrated in the snippet below.

```css
.theoplayer-texttracks * {
  font-size: 1em !important;
}
```

So what's the alternative? Instead of using THEOplayer's default rendering, you can programmatically detect when a subtitle (and closed captions) cue should appear and disappear, as explained in ["how to detect active text track cues"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-detect-active-text-track-cues.md). You could insert the cue when it should appear, and remove it when it should disappear. This alternative makes you fully responsible for the rendering and styling, and gives you total control over it.

### Advertisement metadata

When playing back advertisements, you might want to overlay a countdown, show a skip button after some seconds, insert ad markers in the scrub bar, and achieve other use cases.

If you use [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/google-ima.md) for client-side ad-insertion, then this integration might already take care of some default UI customization.

If you are using THEOplayer's [default ad integration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-set-up-vast-and-vmap.md) for client-side ad-insertion, then you need to [subscribe to the appropriate ad events](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-subscribe-to-ad-events.md), and apply your UI and UX in the callbacks of these events.

Similarly, if you're doing server-side ad-insertion, you also need to apply your UI and UX in the callbacks of your ad events.

## Sample code

The following subsections help you get started on our SDKs.

### Web SDK

The sample code at <https://jsfiddle.net/thijsl/1xbk9csq/1/> may help you get bootstrapped on our Web SDK. (Note that this sample code doesn't necessarily demonstrate best practices.)

### Android SDK

The GitHub project at <https://github.com/THEOplayer/samples-android-sdk/tree/master/Custom-UI> provides a basic implementation of a Chromeless UI on the Android SDK.

### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

The GitHub project at <https://github.com/THEOplayer/samples-ios-sdk/tree/master/Custom-UI> provides a basic implementation of a Chromeless UI on the iOS SDK.

### Roku SDK

The GitHub project at <https://github.com/THEOplayer/samples-roku-sdk/tree/master/basic-playback-app/components/ChromelessView> provides a basic implementation of a Chromeless UI on the Roku SDK.

## UX Enhancements

You can make your user-experience more appealing through various enhancements. For example, when the player is out of video data and is waiting for additional content you could show a 'loading' indication.

Below are some common UX enhancements to consider:

1. Loading spinner: provide an indication when no video data is available.
2. Poster: show a poster (thumbnail) before initial play-request, and when the video is complete.
3. Auto next: when approaching the end, render a clickable overlay that allows the viewer to navigate to the next stream. Automatically play this stream when the current stream ends.
4. Skip intro: render a clickable button to skip the (ongoing) intro.
5. Ad countdown: overlay the remaining time of the ongoing ad break.
6. Ad markers: indicate the position of ad breaks in the scrub bar.

## Error handling

A UI should also be capable of handling errors and informing the viewer. Refer to our [introduction on errors](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/miscellaneous/error/introduction.md) to further explore this topic.

## Roku SDK

This subsection gets you started on implementing a Chromeless UI on our Roku SDK.

* [Display Chromeless player](#display-chromeless-player)
* [Control bar and Buttons](#control-bar-play-pause-stop-buttons)
* [Switch Audio or Text Tracks](#control-bar-switch-audio-or-text-tracks)

This section will give you an overview on how custom controls can be integrated with THEOplayer API and also a brief introduction to BrightScript and SceneGraph. We will create play, pause, stop buttons, add audio and text tracks management menu and create a simple timeline.

### Display chromeless player

To display the video in chromeless THEOplayer we have to take a few steps:

Include and add the instance of THEOplayer.

```xml
  <THEOsdk:THEOplayer id="TestPlayer" controls="false"/>
```

Set the "controls" attribute to "false" to hide all default controls.

```brightscript
function Init()
    m.player = m.top.findNode("TestPlayer")
    m.player.configuration = {
      "license": "" ' put the THEOplayer license between apostrophes
    }
    ' we can go chromeless both via XML or Brightscript'
    ' m.player.controls = false
end function
```

To set the player source, you can create the following function and then just call it inside the "init" function.

```brightscript
function setSource()
    sourceDescription = {
        "sources": [
            {
                "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
                "type": "application/x-mpegURL"
            }
        ]
    }
    m.player.source = sourceDescription
    m.player.source.Live = false
    m.player.source.LiveBoundsPauseBehavior = "pause"
end function
```

To make sure that the player will be displayed in a proper position you can set a destination rectangle. In our example we will display the video in a rectangle (1600x800) positioned in the middle of the screen using the "setDestinationRectangle" THEOplayer method.

```brightscript
function setupPlayerPosition()
    uiRes = m.top.getScene().currentDesignResolution
    m.uiRes = uiRes
    playerRect = {
        width: 1600,
        height: 800,
        x: (m.uiRes.width - 1600) / 2,
        y: (m.uiRes.height - 800) / 2
    }
    m.player.callFunc("setDestinationRectangle", playerRect)
end function
```

When all is set up, all we have to do is to play the video using the "play" method.

```brightscript
m.player.callFunc("play")
```

**Notice: The "play" method call is mandatory, otherwise the video playback won’t start and users won’t be able to use remote controls.**

Below you can see the whole working example. The BrightScript code in this snippet is added inside the component xml file, but you can easily extract the logic part to separate ".brs" file by using "script" tag with a specified "uri" field.

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="TestScene" extends="Scene">
    <interface>

    </interface>

    <script type = "text/brightscript" >

        <![CDATA[

        function Init()
            m.player = m.top.findNode("TestPlayer")
            m.player.configuration = {
              "license": "" ' put the THEOplayer license between apostrophes
            }
            ' we can go chromeless both via XML or Brightscript'
            ' m.player.controls = false

            m.player.callFunc("setMaxVideoResolution", 1920, 1080)
            setupPlayerPosition()
            setSource()
            m.top.setFocus(true)
            m.player.callFunc("play")
        end function

        function setSource()
            sourceDescription = {
                "sources": [
                    {
                        "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
                        "type": "application/x-mpegURL"
                    }
                ]
            }
            m.player.source = sourceDescription
            m.player.source.Live = false
            m.player.source.LiveBoundsPauseBehavior = "pause"
        end function

        function setupPlayerPosition()
            uiRes = m.top.getScene().currentDesignResolution
            m.uiRes = uiRes
            playerRect = {
                width: 1600,
                height: 800,
                x: (m.uiRes.width - 1600) / 2,
                y: (m.uiRes.height - 800) / 2
            }
            m.player.callFunc("setDestinationRectangle", playerRect)
        end function

        ]]>

    </script>

    <children>
	    <THEOsdk:THEOplayer id="TestPlayer" controls="false"/>
    </children>
</component>
```

### Control bar Play, Pause, Stop buttons

To create a control bar with play, pause and stop buttons, generally we would need to create custom UI elements (buttons) and call the api methods when they are played. To accomplish that we have to take the following steps:

Let's start with creating the UI elements which are simply xml elements. We will add three buttons (play, pause and stop), along with timeline bar.

```xml
<Group id="playerOverlay">
	<Group id="GroupOptions">
		<Rectangle id="OptionsBackground" color="0x000000FF" height="47" width="10" opacity="0.5"/>
		<Rectangle id="TimelineBackground" height="3" width="0" opacity="0.3"/>
		<Rectangle id="TimelineProgress" height="3" width="0" color="0xFFC713FF"/>

		<ButtonGroup id="ButtonGroupOptions" layoutDirection="horiz">
			<Button id="ButtonPlay" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
				<Poster width="75" height="65" id="playIcon" uri="pkg:/images/play.png" translation="[20,15]" opacity="0.9"/>
			</Button>
			<Button id="ButtonPause" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
				<Poster width="75" height="65" id="pauseIcon" uri="pkg:/images/pause.png" translation="[20,15]" opacity="0.9"/>
			</Button>
			<Button id="ButtonStop" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
				<Poster id="stopIcon" uri="pkg:/images/stop.png" width="75" height="65" translation="[20,15]" opacity="0.9"/>
			</Button>
		</ButtonGroup>
	</Group>
</Group>
```

Next step would be adding callback on buttons press. To do so, we will use [roku native observe mechanism](https://developer.roku.com/en-gb/docs/developer-program/core-concepts/handling-application-events.md#handling-node-field-value-changes).

```brightscript
function Init()
	m.player = m.top.findNode("TestPlayer")
	m.player.configuration = {
      "license": "" ' put the THEOplayer license between apostrophes
    }
	m.buttonPlay = m.top.findNode("ButtonPlay")
	m.buttonPause = m.top.findNode("ButtonPause")
	m.buttonStop = m.top.findNode("ButtonStop")

	setupPlayerPosition()
	setupControlsPosition()
	setSource()

	m.buttonPlay.setFocus(true)

	m.buttonPlay.observeField("buttonSelected", "OnEventPlay")
	m.buttonPause.observeField("buttonSelected", "OnEventPause")
	m.buttonStop.observeField("buttonSelected", "OnEventStop")

end function

function OnEventPlay()

end function

function OnEventPause()

end function

function OnEventStop()

end function
```

The next step would be calling the THEOplayer api methods inside our callback. To do so, we will modify the callbacks:

```brightscript
function OnEventPlay()
	if m.player.source = Invalid
		setSource()
	end if
	m.player.callFunc("play")
end function

function OnEventPause()
	m.player.callFunc("pause")
end function

function OnEventStop()
	m.player.source = Invalid
end function
```

Last thing left to do is to make the timeline work. We will add an event listener to an event "timeUpdate". This listener will allow us to react to every time update, so we can draw the current progress in playing video.

```xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="TestScene" extends="Scene">
    <interface>

        <function name="callbackOnEventPlayerTimeupdate"/>

    </interface>

    <script type = "text/brightscript" >

        <![CDATA[

        function Init()
            m.player = m.top.findNode("TestPlayer")
            m.player.configuration = {
              "license": "" ' put the THEOplayer license between apostrophes
            }
            m.buttonPlay = m.top.findNode("ButtonPlay")
            m.buttonPause = m.top.findNode("ButtonPause")
            m.buttonStop = m.top.findNode("ButtonStop")

            m.player.callFunc("setMaxVideoResolution", 1920, 1080)
            setupPlayerPosition()
            setupControlsPosition()

            setSource()
            m.buttonPlay.setFocus(true)

            m.buttonPlay.observeField("buttonSelected", "OnEventPlay")
            m.buttonPause.observeField("buttonSelected", "OnEventPause")
            m.buttonStop.observeField("buttonSelected", "OnEventStop")

            m.player.listener = m.top
            m.player.callFunc("addEventListener", m.player.Event.c, "callbackOnEventPlayerTimeupdate")
        end function

        function setSource()
            sourceDescription = {
                "sources": [
                    {
                        "src": "http://cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8",
                        "type": "hls"
                    }
                ]
            }
            m.player.source = sourceDescription
            m.player.source.Live = false
            m.player.source.LiveBoundsPauseBehavior = "pause"
        end function

        function setupPlayerPosition()
            uiRes = m.top.getScene().currentDesignResolution
            m.uiRes = uiRes
            playerRect = {
                width: 1600,
                height: 800,
                x: (m.uiRes.width - 1600) / 2,
                y: (m.uiRes.height - 800) / 2
            }
            m.player.callFunc("setDestinationRectangle", playerRect)
        end function

        function setupControlsPosition()
            buttons = [m.buttonPlay, m.buttonPause, m.buttonStop]
            buttonsWidth = 0

            for each button in buttons
                ' get rid of focus footprint on the buttons
                button.removeChildIndex(1)

                ' -20 because of buttons ovelaping and scale
                buttonsWidth += button.minWidth - 20
            end for

            uiRes = m.top.getScene().currentDesignResolution
            playerRect = m.player.boundingRect()
            playerBottomX = playerRect.width + playerRect.x
            playerBottomY = playerRect.height + playerRect.y
            m.groupOptions = m.top.findNode("GroupOptions")
            m.buttonGroupOptions = m.top.findNode("ButtonGroupOptions")
            m.groupOptionsVisible = true
            buttonGroupOptionsRect = m.buttonGroupOptions.boundingRect()
            centerY = playerRect.y + playerRect.height - buttonGroupOptionsRect.height
            centerX = playerRect.x
            m.groupOptions.translation = [centerX, centerY]
            centerX = (playerRect.width - buttonsWidth / 2) / 2
            m.buttonGroupOptions.translation = [centerX, 3]

            m.optionsBackground = m.top.findNode("OptionsBackground")
            m.optionsBackground.width = playerRect.width
            m.timelineBackground = m.top.findNode("TimelineBackground")
            m.timelineBackground.width = playerRect.width

            m.timelineProgress = m.top.findNode("TimelineProgress")
            m.timelineProgress.width = 1
        end function

        function callbackOnEventPlayerTimeupdate(eventData)
            'update movie timeline bar
            if m.player.duration > 0 and m.player.currentTime < m.player.duration
                rect = m.player.boundingRect()
                m.timelineProgress.width = rect.width * ( m.player.currentTime / m.player.duration )
            end if
        end function

        function OnEventPlay()
            if m.player.source = Invalid
                setSource()
            end if

            m.player.callFunc("play")
        end function

        function OnEventPause()
            m.player.callFunc("pause")
        end function

        function OnEventStop()
            m.player.source = Invalid
        end function

        ]]>

    </script>

    <children>
	    <THEOsdk:THEOplayer id="TestPlayer" controls="false"/>

        <Group id="playerOverlay">
            <Group id="GroupOptions">
                <Rectangle id="OptionsBackground" color="0x000000FF" height="47" width="10" opacity="0.5"/>
                <Rectangle id="TimelineBackground" height="3" width="0" opacity="0.3"/>
                <Rectangle id="TimelineProgress" height="3" width="0" color="0xFFC713FF"/>

                <ButtonGroup id="ButtonGroupOptions" layoutDirection="horiz">
                    <Button id="ButtonPlay" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">

                        <Poster width="75" height="65" id="playIcon" uri="pkg:/images/play.png" translation="[20,15]" opacity="0.9"/>
                    </Button>
                    <Button id="ButtonPause" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">

                        <Poster width="75" height="65" id="pauseIcon" uri="pkg:/images/pause.png" translation="[20,15]" opacity="0.9"/>
                    </Button>
                    <Button id="ButtonStop" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">

                        <Poster id="stopIcon" uri="pkg:/images/stop.png" width="75" height="65" translation="[20,15]" opacity="0.9"/>
                    </Button>
                </ButtonGroup>

            </Group>
        </Group>
    </children>
</component>
```

### Control bar Switch audio or text tracks

Now, let’s add an audio or text track management menu. In this portion, we will use a fresh SceneGraph component (RadioButtonList). We will use other callbacks, API methods and attributes. The main steps which we have to take to accomplish the desired outcome are:

Create an empty RadioButtonList component:

```xml
<RadioButtonList
    id="ButtonGroupCategoryFirst"
    opacity="1"
    focusBitmapUri="pkg:/images/focusBG.png"
    focusedColor="0xFFFFFFFF"
    color="0xFFFFFFFF"
    itemSize="[300,65]"
    translation="[0,65]">
</RadioButtonList>
```

Add the content to our list. To do so, we will observe audio tracks and assign the audio tracks list to a previously created radio button list.

```brightscript
function onEventAudioTracksChanged()
    list = createObject("roSGNode","ContentNode")
    option = list.createChild("ContentNode")
    option.title = "default"
    option.description = "default"
    option.id = ""
    checkedItem = 0
    index = 1
    for each track in m.player.audioTracks
        option = list.createChild("ContentNode")
        option.title = track.label
        option.description = track.language
        option.id = track.id
        if track.enabled then
            checkedItem = index
        end if
        index +=1
    end for

    optionsCount = 0
    if Type(m.buttonGroupCategorySecond.content) <> "roInvalid" then
        optionsCount = m.buttonGroupCategorySecond.content.count()
    end if
    if list.count() <> optionsCount then
        m.buttonGroupCategorySecond.content = list
        m.buttonGroupCategorySecond.checkedItem = checkedItem
        setAudioMenuPosition()
    end if
end function
```

The next step would be managing a focus of the remote.

```brightscript
function OnKeyEvent(key, press) as Boolean
    handled = false
    showOptions()
    if press
        if key = "options"
        else if m.player.visible = true and key = "back"
            ' Settings Menu opened
            if m.settingsOptions.visible = true
                hideSettings()
                handled = true
            ' category 1 Menu opened
            else if m.categoryFirstOptions.visible = true then
                hideCategoryFirst()
                handled = true
            ' category 2 Menu opened
            else if m.categorySecondOptions.visible = true then
                hideCategorySecond()
                handled = true
            else
                m.player.source = Invalid
            end if
        else if key = "up"
            if m.settingsOptions.visible = true and m.buttonCategoryFirst.hasFocus() = true
                hideSettings()
                handled = true
            ' category 1 Menu opened
            ' else if m.categoryFirstOptions.visible = true and m.buttonGroupCategoryFirst.hasFocus() = true then
            '     hideCategoryFirst()
            '     handled = true
            ' category 2 Menu opened
            else if m.categorySecondOptions.visible = true and m.categorySecondButtonFirst.hasFocus() = true then
                hideCategorySecond()
                handled = true
            end if
        end if
    end if

    return handled
end function
```

In order to allow the user to change audio tracks, we have to prepare a function which will change audio track.

```brightscript
function setAudioTrack(label as String)
    audioTracks =  m.player.audioTracks
    for i =  audioTracks.count() - 1 to 0 step -1
        if audioTracks[i].label = label then
            audioTracks[i].enabled = true
        else
            audioTracks[i].enabled = false
        end if
    end for
    'required because roku deep-copied roAssociativeArray through fields (pass-by-value)
    'read more : <https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow>
    m.player.audioTracks = audioTracks
end function

function OnEventCategorySecondSelectedItem()
    if m.player.instance <> Invalid
        itemIndex = m.buttonGroupCategorySecond.checkedItem
        item = m.buttonGroupCategorySecond.content.getChild(itemIndex)
        setAudioTrack(item.title)
    end if
end function
```

To complete this functionality, we will add an observer to the radio button list and call the setAudioTrack function.

```brightscript
function OnEventCategoryFirstSelectedItem()
    if m.player.instance <> Invalid
        itemIndex = m.buttonGroupCategoryFirst.checkedItem
        item = m.buttonGroupCategoryFirst.content.getChild(itemIndex)
        setCaptionsLanguage(item.description)
    end if
end function
```

You can find the whole example below. This example contains two menus which allow users to manipulate audio and text tracks.

```xml
<?xml version="1.0" encoding="utf-8" ?>

<component name="TestScene" extends="Scene">

    <interface>

        <function name="callbackOnEventPlayerTimeupdate"/>

    </interface>

    <script type="text/brightscript">
        <![CDATA[

        function Init()
            SetupUI()
            SetupObservers()
            SetupEventListeners()
        end function

        function SetupUI()
            m.buttonPlay = m.top.findNode("ButtonPlay")
            m.buttonPause = m.top.findNode("ButtonPause")
            m.buttonStop = m.top.findNode("ButtonStop")
            m.buttonSettings = m.top.findNode("ButtonSettings")
            m.categoryFirstHeaderBackground = m.top.findNode("CategoryFirstHeaderBackground")
            m.settingsOptions = m.top.findNode("SettingsOptions")
            m.buttonCategoryFirst = m.top.findNode("ButtonCategoryFirst")
            m.buttonCategorySecond = m.top.findNode("ButtonCategorySecond")
            m.categoryFirstButtonFirst = m.top.findNode("CategoryFirstButtonFirst")
            m.categorySecondButtonFirst = m.top.findNode("CategorySecondButtonFirst")

            m.player = m.top.findNode("TestPlayer")
            m.player.configuration = {
              "license": "" ' put the THEOplayer license between apostrophes
            }
            SetupPlayerPosition()
            SetControlsPosition()

            setSource()
            m.buttonPlay.setFocus(true)
        end function

        function SetupObservers()
            m.player.observeField("audioTracks","onEventAudioTracksChanged")
            m.player.observeField("textTracks","onEventTextTracksChanged")

            m.buttonPlay.observeField("buttonSelected", "OnEventPlay")
            m.buttonPause.observeField("buttonSelected", "OnEventPause")
            m.buttonStop.observeField("buttonSelected", "OnEventStop")
            m.buttonSettings.observeField("buttonSelected", "OnEventSettings")

            m.buttonCategoryFirst.observeField("buttonSelected", "OnEventCategoryFirst")
            m.buttonGroupCategoryFirst.observeField("itemFocused", "OnEventCategoryFirstFocusedItem")
            m.buttonGroupCategoryFirst.observeField("checkedItem", "OnEventCategoryFirstSelectedItem")

            m.buttonCategorySecond.observeField("buttonSelected", "OnEventCategorySecond")
            m.buttonGroupCategorySecond.observeField("itemFocused", "OnEventCategorySecondFocusedItem")
            m.buttonGroupCategorySecond.observeField("checkedItem", "OnEventCategorySecondSelectedItem")
        end function

        function SetupEventListeners()
            m.player.listener = m.top
            m.player.callFunc("addEventListener", m.player.Event.timeupdate, "callbackOnEventPlayerTimeupdate")
        end function

        function SetupPlayerPosition()
            m.uiRes = m.top.getScene().currentDesignResolution
            m.timelineProgress = m.top.findNode("TimelineProgress")
            m.timelineProgress.width = 1
            'm.player.callFunc("setMaxVideoResolution", m.uiRes.width, m.uiRes.height)
            ' center video'
            'playerRect = {
            ''    width: m.uiRes.width,
            ''    height: m.uiRes.height,
            ''    x: 0,
            ''    y: 0
            ''}
            'm.player.callFunc("setDestinationRectangle", playerRect)
        end function

        function SetControlsPosition()
            buttons = [m.buttonPlay, m.buttonPause, m.buttonStop, m.buttonSettings]
            buttonsWidth = 0

            for each button in buttons
                ' get rid of focus footprint on the buttons
                button.removeChildIndex(1)

                ' -20 because of buttons ovelaping and scale
                buttonsWidth += button.minWidth - 20
            end for
            playerRect = m.player.boundingRect()
            playerBottomX = playerRect.width + playerRect.x
            playerBottomY = playerRect.height + playerRect.y
            m.groupOptions = m.top.findNode("GroupOptions")
            m.buttonGroupOptions = m.top.findNode("ButtonGroupOptions")
            m.groupOptionsVisible = true
            buttonGroupOptionsRect = m.buttonGroupOptions.boundingRect()
            centerY = playerRect.y + playerRect.height - buttonGroupOptionsRect.height
            centerX = playerRect.x
            m.groupOptions.translation = [centerX, centerY]
            centerX = (playerRect.width - buttonsWidth / 2) / 2
            m.buttonGroupOptions.translation = [centerX, 3]

            m.optionsBackground = m.top.findNode("OptionsBackground")
            m.optionsBackground.width = playerRect.width
            m.timelineBackground = m.top.findNode("TimelineBackground")
            m.timelineBackground.width = playerRect.width

            m.settingsOptions = m.top.findNode("SettingsOptions")
            m.buttonGroupSettings = m.top.findNode("ButtonGroupSettings")
            settingsRect = m.settingsOptions.boundingRect()
            buttonGroupSettingsRect = m.buttonGroupSettings.boundingRect()
            groupOptionsRect = m.groupOptions.boundingRect()
            centerX = playerBottomX - buttonGroupSettingsRect.x - settingsRect.width - 20
            centerY = playerBottomY - buttonGroupSettingsRect.y - settingsRect.height - 20
            m.settingsOptions.translation = [centerX, centerY ]


            m.categoryFirstOptions = m.top.findNode("CategoryFirstOptions")
            m.categoryFirstBackground = m.top.findNode("CategoryFirstBackground")
            m.buttonGroupCategoryFirst = m.top.findNode("ButtonGroupCategoryFirst")
            SetClosedCaptionsMenuPosition()

            m.categorySecondOptions = m.top.findNode("CategorySecondOptions")
            m.categorySecondBackground = m.top.findNode("CategorySecondBackground")
            m.buttonGroupCategorySecond = m.top.findNode("ButtonGroupCategorySecond")
            SetAudioMenuPosition()
        end function

        function SetClosedCaptionsMenuPosition()
            playerRect = m.player.boundingRect()
            playerBottomX = playerRect.width + playerRect.x
            playerBottomY = playerRect.height + playerRect.y
            categoryFirstRect = m.categoryFirstOptions.boundingRect()
            categoryFirstButtonGroupRect = m.buttonGroupCategoryFirst.boundingRect()
            centerX = playerBottomX - categoryFirstButtonGroupRect.x - categoryFirstRect.width - 20
            centerY = playerBottomY - categoryFirstButtonGroupRect.y - categoryFirstRect.height - m.categoryFirstHeaderBackground.height - 20
            m.categoryFirstOptions.translation = [centerX, centerY]
            m.categoryFirstBackground.height = categoryFirstRect.height + 30 ' added 30 because radio group shows separator
            if playerRect.x = 0 or playerRect.y = 0 or playerRect.width = m.uiRes.width or playerRect.height = m.uiRes.height then
                m.fullScreen = true
                if m.player.textTracks.count() > 0
                    m.buttonCategoryFirst.textColor = "0xFFFFFFFF"
                    m.buttonCategoryFirst.focusedTextColor = "0xFFFFFFFF"
                else
                    m.buttonCategoryFirst.textColor = "0x666666FF"
                    m.buttonCategoryFirst.focusedTextColor = "0x666666FF"
                end if
            else
                m.fullScreen = false
                m.buttonCategoryFirst.textColor = "0x666666FF"
                m.buttonCategoryFirst.focusedTextColor = "0x666666FF"
            end if
        end function

        function SetAudioMenuPosition()
            playerRect = m.player.boundingRect()
            playerBottomX = playerRect.width + playerRect.x
            playerBottomY = playerRect.height + playerRect.y
            categorySecondOptionsRect = m.categorySecondOptions.boundingRect()
            categorySecondButtonGroupRect = m.buttonGroupCategorySecond.boundingRect()
            centerX = playerBottomX - categorySecondButtonGroupRect.x - categorySecondOptionsRect.width - 20
            centerY = playerBottomY - categorySecondButtonGroupRect.y - categorySecondOptionsRect.height - 20
            m.categorySecondOptions.translation = [centerX, centerY]
            m.categorySecondBackground.height = categorySecondOptionsRect.height
            isNode = Type(m.buttonGroupCategorySecond.content) = "roSGNode"
            if isNode then
                m.buttonCategorySecond.textColor = "0xFFFFFFFF"
                m.buttonCategorySecond.focusedTextColor = "0xFFFFFFFF"
            else
                m.buttonCategorySecond.textColor = "0x666666FF"
                m.buttonCategorySecond.focusedTextColor = "0x666666FF"
            end if
        end function

        function callbackOnEventPlayerTimeupdate(eventData)
            ? "Event <timeupdate>: "; eventData

            'update movie timeline bar
            if m.player.duration > 0 and m.player.currentTime < m.player.duration
                rect = m.player.boundingRect()
                m.timelineProgress.width = rect.width * ( m.player.currentTime / m.player.duration )
            end if
        end function

        function setSource()
            sourceDescription = {
                "poster": ""
                "sources": [
                    {
                        "src": "http://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8",
                        "type": "application/x-mpegURL"
                    }
                ]
            }
            m.player.source = sourceDescription
            m.player.source.Live = m.live
            m.player.source.LiveBoundsPauseBehavior = "pause"
        end function

        function OnEventPlay()
            if m.player.source = Invalid
                setSource()
            end if

            m.player.callFunc("play")
        end function

        function hideOptions()
            if m.groupOptionsVisible = true
                m.groupOptionsVisible = false
                hideCategoryFirst()
                hideCategorySecond()
                hideSettings()
            end if
        end function

        function showOptions()
            if m.groupOptionsVisible = false
                m.groupOptionsVisible = true
            end if
        end function

        function showCategoryFirst()
            hideSettings()
            m.categoryFirstOptions.visible = true
            m.buttonGroupCategoryFirst.setFocus(true)
        end function

        function hideCategoryFirst()
            if  m.categoryFirstOptions.visible = true
                m.categoryFirstOptions.visible = false
                showSettings()
            end if
        end function

        function showCategorySecond()
            hideSettings()
            m.categoryFirstOptions.visible = true
            m.categorySecondButtonFirst.setFocus(true)
        end function

        function hideCategorySecond()
            if m.categorySecondOptions.visible = true
                m.categorySecondOptions.visible = false
                showSettings()
            end if
        end function

        function showSettings()
            m.settingsOptions.visible = true
            m.buttonCategoryFirst.setFocus(true)
        end function

        function hideSettings()
            if m.settingsOptions.visible = true
                m.settingsOptions.visible = false
                m.buttonSettings.setFocus(true)
            end if
        end function

        function OnEventPause()
            m.player.callFunc("pause")
        end function

        function OnEventStop()
            m.player.source = Invalid
        end function

        function OnEventCategoryFirst()
            isNode = Type(m.buttonGroupCategoryFirst.content) = "roSGNode"
            if isNode and m.fullScreen
                m.settingsOptions.visible = false
                m.categoryFirstOptions.visible = true
                m.buttonGroupCategoryFirst.setFocus(true)
            end if
        end function

        function OnEventCategorySecond()
            isNode = Type(m.buttonGroupCategorySecond.content) = "roSGNode"
            if isNode
                m.settingsOptions.visible = false
                m.categorySecondOptions.visible = true
                m.buttonGroupCategorySecond.setFocus(true)
            end if
        end function

        function onEventAudioTracksChanged()
            list = createObject("roSGNode","ContentNode")
            option = list.createChild("ContentNode")
            option.title = "default"
            option.description = "default"
            option.id = ""
            checkedItem = 0
            index = 1
            for each track in m.player.audioTracks
                option = list.createChild("ContentNode")
                option.title = track.label
                option.description = track.language
                option.id = track.id
                if track.enabled then
                    checkedItem = index
                end if
                index +=1
            end for

            optionsCount = 0
            if Type(m.buttonGroupCategorySecond.content) <> "roInvalid" then
                optionsCount = m.buttonGroupCategorySecond.content.count()
            end if
            if list.count() <> optionsCount then
                m.buttonGroupCategorySecond.content = list
                m.buttonGroupCategorySecond.checkedItem = checkedItem
                setAudioMenuPosition()
            end if
        end function

        function onEventTextTracksChanged()
            list = createObject("roSGNode","ContentNode")
            option = list.createChild("ContentNode")
            option.title = "default"
            option.description = "default"
            option.id = ""
            checkedItem = 0
            index = 1
            for each track in m.player.textTracks
                if track.kind = "captions"
                    option = list.createChild("ContentNode")
                    option.title = track.label
                    option.description = track.language
                    option.id = track.id
                    if track.mode = "showing" then
                        checkedItem = index
                    end if
                    index +=1
                end if
            end for

            optionsCount = 0
            if Type(m.buttonGroupCategoryFirst.content) <> "roInvalid" then
                optionsCount = m.buttonGroupCategoryFirst.content.count()
            end if
            if list.count() <> optionsCount then
                m.buttonGroupCategoryFirst.content = list
                m.buttonGroupCategoryFirst.checkedItem = checkedItem
                setClosedCaptionsMenuPosition()
            end if
        end function

        function OnEventSettings()
            if m.settingsOptions.visible = false
                m.settingsOptions.visible = true
                m.buttonCategoryFirst.setFocus(true)
            else
                m.settingsOptions.visible = false
            end if
        end function

        function OnEventCategoryFirstFocusedItem()
            showOptions()
        end function

        function setCaptionsLanguage(language as String)
            textTracks =  m.player.textTracks
            for i =  textTracks.count() - 1 to 0 step -1
                if textTracks[i].kind = "captions" and textTracks[i].language = language then
                    if m.fullScreen then
                        textTracks[i].mode = "showing"
                    else
                        textTracks[i].mode = "hidden"
                    end if
                else
                    textTracks[i].mode = "disabled"
                end if
            end for
            'assigment of new roAssociativeArray is required because roku deep-copied roAssociativeArray through fields (pass-by-value)
            'read more : <https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow>
            m.player.textTracks = textTracks
        end function

        function OnEventCategoryFirstSelectedItem()
            if m.player.instance <> Invalid
                itemIndex = m.buttonGroupCategoryFirst.checkedItem
                item = m.buttonGroupCategoryFirst.content.getChild(itemIndex)
                setCaptionsLanguage(item.description)
            end if
        end function

        function OnEventCategorySecondFocusedItem()
            showOptions()
        end function

        function setAudioTrack(label as String)
            audioTracks =  m.player.audioTracks
            for i =  audioTracks.count() - 1 to 0 step -1
                if audioTracks[i].label = label then
                    audioTracks[i].enabled = true
                else
                    audioTracks[i].enabled = false
                end if
            end for
            'required because roku deep-copied roAssociativeArray through fields (pass-by-value)
            'read more : <https://developer.roku.com/en-gb/docs/developer-program/performance-guide/optimization-techniques.md#OptimizationTechniques-DataFlow>
            m.player.audioTracks = audioTracks
        end function

        function OnEventCategorySecondSelectedItem()
            if m.player.instance <> Invalid
                itemIndex = m.buttonGroupCategorySecond.checkedItem
                item = m.buttonGroupCategorySecond.content.getChild(itemIndex)
                setAudioTrack(item.title)
            end if
        end function

        function OnKeyEvent(key, press) as Boolean
            handled = false
            showOptions()
            if press
                if key = "options"
                else if m.player.visible = true and key = "back"
                    ' Settings Menu opened
                    if m.settingsOptions.visible = true
                        hideSettings()
                        handled = true
                    ' category 1 Menu opened
                    else if m.categoryFirstOptions.visible = true then
                        hideCategoryFirst()
                        handled = true
                    ' category 2 Menu opened
                    else if m.categorySecondOptions.visible = true then
                        hideCategorySecond()
                        handled = true
                    else
                        m.player.source = Invalid
                    end if
                else if key = "up"
                    if m.settingsOptions.visible = true and m.buttonCategoryFirst.hasFocus() = true
                        hideSettings()
                        handled = true
                    ' category 1 Menu opened
                    ' else if m.categoryFirstOptions.visible = true and m.buttonGroupCategoryFirst.hasFocus() = true then
                    '     hideCategoryFirst()
                    '     handled = true
                    ' category 2 Menu opened
                    else if m.categorySecondOptions.visible = true and m.categorySecondButtonFirst.hasFocus() = true then
                        hideCategorySecond()
                        handled = true
                    end if
                end if
            end if

            return handled
        end function

        ]]>
    </script>
    <children>
	    <THEOsdk:THEOplayer id="TestPlayer" controls="false"/>

        <Group id="playerOverlay">
            <Group id="GroupOptions">
                <Rectangle id="OptionsBackground" color="0x000000FF" height="47" width="10" opacity="0.5"/>
                <Rectangle id="TimelineBackground" height="3" width="0" opacity="0.3"/>
                <Rectangle id="TimelineProgress" height="3" width="0" color="0xFFC713FF"/>

                <ButtonGroup id="ButtonGroupOptions" layoutDirection="horiz">
                    <Button id="ButtonPlay" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
                        <Poster width="75" height="65" id="playIcon" uri="pkg:/images/play.png" translation="[20,15]" opacity="0.9"/>
                    </Button>
                    <Button id="ButtonPause" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
                        <Poster width="75" height="65" id="pauseIcon" uri="pkg:/images/pause.png" translation="[20,15]" opacity="0.9"/>
                    </Button>
                    <Button id="ButtonStop" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
                        <Poster id="stopIcon" uri="pkg:/images/stop.png" width="75" height="65" translation="[20,15]" opacity="0.9"/>
                    </Button>
                    <Button id="ButtonSettings" iconUri="" focusBitmapUri="pkg:/images/focusBG.png" focusedIconUri="" maxWidth="115" minWidth="115" height="95" opacity="0.9" scale="[0.5,0.5]">
                        <Poster id="settingsIcon" uri="pkg:/images/settings.png" width="75" height="65" translation="[20,15]" opacity="0.9"/>
                    </Button>
                </ButtonGroup>

            </Group>

            <Group id="SettingsOptions" visible="false">
                <Rectangle id="SettingsBackground" color="0x000000FF" width="500" height="215" translation="[-15,0]" opacity="0.5"/>
                <Rectangle id="SettingsHeaderBackground" color="0xFFC713FF" width="500" height="65" translation="[-15,0]">
                    <Label text="Settings" height="65" width="470" horizAlign="center" vertAlign="center" font="font:SmallestBoldSystemFont"/>
                </Rectangle>

                <ButtonGroup id="ButtonGroupSettings" layoutDirection="vert" vertAlignment="top" translation="[0,65]" opacity="1">
                    <Button
                        id="ButtonCategoryFirst"
                        iconUri=""
                        focusedIconUri=""
                        focusBitmapUri="pkg:/images/focusBG.png"
                        maxWidth="470"
                        minWidth="470"
                        height="65"
                        opacity="0.9"
                        text="Captions"
                        focusedTextColor="0xFFFFFFFF"
                        textFont="font:SmallestBoldSystemFont"
                        focusedTextFont="font:SmallestBoldSystemFont"></Button>
                    <Button
                        id="ButtonCategorySecond"
                        iconUri=""
                        focusedIconUri=""
                        focusBitmapUri="pkg:/images/focusBG.png"
                        maxWidth="470"
                        minWidth="470"
                        height="65"
                        opacity="0.9"
                        text="Audio Tracks"
                        focusedTextColor="0xFFFFFFFF"
                        textFont="font:SmallestBoldSystemFont"
                        focusedTextFont="font:SmallestBoldSystemFont"></Button>
                </ButtonGroup>
            </Group>

            <Group id="CategoryFirstOptions" visible="false">
                <Rectangle id="CategoryFirstBackground" color="0x000000FF" width="300" height="0" opacity="0.5"/>
                <Rectangle id="CategoryFirstHeaderBackground" color="0xFFC713FF" width="300" height="65">
                    <Label text="Captions" height="65" width="300" horizAlign="center" vertAlign="center" font="font:SmallestBoldSystemFont"/>
                </Rectangle>

                <RadioButtonList
                    id="ButtonGroupCategoryFirst"
                    opacity="1"
                    focusBitmapUri="pkg:/images/focusBG.png"
                    focusedColor="0xFFFFFFFF"
                    color="0xFFFFFFFF"
                    itemSize="[300,65]"
                    translation="[0,65]">
                </RadioButtonList>
            </Group>
            <Group id="CategorySecondOptions" visible="false">
                <Rectangle id="CategorySecondBackground" color="0x000000FF" width="300" height="0" opacity="0.5"/>
                <Rectangle id="CategorySecondHeaderBackground" color="0xFFC713FF" width="300" height="65">
                    <Label text="Audio Tracks" height="65" width="300" vertAlign="center" horizAlign="center" font="font:SmallestBoldSystemFont"/>
                </Rectangle>

                <RadioButtonList
                    id="ButtonGroupCategorySecond"
                    opacity="1"
                    focusBitmapUri="pkg:/images/focusBG.png"
                    focusedColor="0xFFFFFFFF"
                    color="0xFFFFFFFF"
                    itemSize="[300,65]"
                    translation="[0,65]">
                </RadioButtonList>
            </Group>
        </Group>
    </children>
</component>
```

---

# How to insert a button

This article provides information on how developers can add custom buttons to THEOplayer's **default UI**.

THEOplayer's default UI is based on VideoJS. A WebView is used on the legacy Android and iOS SDKs (4.12.x). HTML, CSS and JavaScript is used to insert a button.

When using the legacy Android or iOS SDKs (4.12.x), THEOplayer exposes a system to include JavaScript and CSS files (as described at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)). This system allows developers to reuse their code-logic.

## Code example

This code example adds 2 time-jump buttons to the control bar. A button to go back 10 seconds in time should be positioned to the left of the play-button, and a button to go forward 10 seconds in time should be positioned to the right of the play-button.

### Web SDK

The buttons use the [Font Awesome](http://fontawesome.io/) icon set. This means that we first need to include the Font Awesome CSS stylesheet.

```html
<link rel="stylesheet" type="text/css" href="http://cdn.theoplayer.com/demos/font-awesome/css/font-awesome.min.css" />
```

The code below inserts two buttons in the control bar, lets viewers jump in time when it is clicked, and adds a tooltip to the button.

```js
// setting up the rewind button by setting up a video-js component
var Button = THEOplayer.videojs.getComponent('Button');
var RewindButton = THEOplayer.videojs.extend(Button, {
  constructor: function () {
    Button.apply(this, arguments);
    /* initialize your button */
    // this.el() = created DOM-element

    // add tooltip
    var tooltipSpan = document.createElement('span');
    tooltipSpan.className = 'theo-button-tooltip vjs-hidden';
    tooltipSpan.innerText = 'Go back 10 seconds';
    function toggleTooltip() {
      tooltipSpan.classList.toggle('vjs-hidden');
    }
    this.el().addEventListener('mouseover', toggleTooltip);
    this.el().addEventListener('mouseout', toggleTooltip);
    this.el().appendChild(tooltipSpan);
  },
  handleClick: () => {
    player.currentTime -= 10;
  },
  buildCSSClass: function () {
    return 'fa fa-step-backward vjs-button'; // insert all class names here
  },
});
THEOplayer.videojs.registerComponent('RewindButton', RewindButton);
player.ui.getChild('controlBar').addChild('RewindButton', {});

// setting up the forward button by setting up a video-js component
var Button = THEOplayer.videojs.getComponent('Button');
var ForwardButton = THEOplayer.videojs.extend(Button, {
  constructor: function () {
    Button.apply(this, arguments);
    /* initialize your button */
    // this.el() = created DOM-element

    // add tooltip
    var tooltipSpan = document.createElement('span');
    tooltipSpan.className = 'theo-button-tooltip vjs-hidden';
    tooltipSpan.innerText = 'Go forward 10 seconds';
    function toggleTooltip() {
      tooltipSpan.classList.toggle('vjs-hidden');
    }
    this.el().addEventListener('mouseover', toggleTooltip);
    this.el().addEventListener('mouseout', toggleTooltip);
    this.el().appendChild(tooltipSpan);
  },
  handleClick: () => {
    player.currentTime += 10;
  },
  buildCSSClass: function () {
    return 'fa fa-step-forward vjs-button'; // insert all class names here
  },
});
THEOplayer.videojs.registerComponent('ForwardButton', ForwardButton);
player.ui.getChild('controlBar').addChild('ForwardButton', {});
```

You could add `vjs-control` to the return-string of `buildCSSClass` to make the button more similar to the default buttons.

Finally, you can adjust the position of the custom buttons with the order attribute, and force the cursor to use a pointer.

```css
.fa-step-backward {
  order: -101; /* to the left of the play/pause-button */
  cursor: pointer;
}
.fa-step-forward {
  order: -100; /* to the right of the play/pause-button */
  cursor: pointer;
}
```

### Android SDK

Since JavaScript injection is not available on the native Android SDK, you can add a button in a native way to the platform and use THEOplayer APIs for its function.

### iOS SDK

Since JavaScript injection is not available on the native iOS SDK, you can add a button in a native way to the platform and use THEOplayer APIs for its function.

### Legacy Android SDK (4.12.x)

See [our version 4 documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/how-to-guides/ui/how-to-insert-a-button#android-sdk) for more information.

### Legacy iOS SDK (4.12.x)

See [our version 4 documentation](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/how-to-guides/ui/how-to-insert-a-button#ios-sdk) for more information.

## Sample resources

The pages or projects below demonstrate implementations of similar use cases.

* Web SDK - Demo Page: <https://www.theoplayer.com/theoplayer-demo-adding-buttons-to-the-ui-with-custom-logic>
* Web SDK - Sample App: <https://github.com/THEOplayer/samples-html5-sdk/tree/master/reference-apps/ui-adding-buttons>

## Other resources

The samples below demonstrate how to implement a custom UI without injecting JavaScript into a WebView on mobile SDKs.

* Android SDK - Custom UI Sample: <https://github.com/THEOplayer/samples-android-sdk/tree/master/Custom-UI>
* iOS SDK - Custom UI Sample: <https://github.com/THEOplayer/samples-ios-sdk/tree/master/Custom-UI>

---

# How to change the default UI language to other

This article describes how to change the default UI language to other.

The UIConfiguration Object uses a property \_language \_&\* languages \*to change the default UI language i.e. English to any other language. This is an optional property of the player whereby if defined then the language code must have a matching language dictionary in the languages configuration.

When this configuration is set, the labels and tooltips in the UI will be replaced by their translated version from the language. If no translation is found for a label or tooltip, the original English version will be used instead.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     |          |                |                |

## Prerequisites

* THEOplayer valid license SDK for respective platform (Web, iOS & Android)
* Download the specific language JSONs to add into your project

**Language JSON Links**

Arabic : <http://cdn.theoplayer.com/demos/theoplayer/lang/ar.js>

Bashkir: <http://cdn.theoplayer.com/demos/theoplayer/lang/ba.js>

Bulgarian: <http://cdn.theoplayer.com/demos/theoplayer/lang/bg.js>

Catalan: <http://cdn.theoplayer.com/demos/theoplayer/lang/ca.js>

Czech: <http://cdn.theoplayer.com/demos/theoplayer/lang/cs.js>

Danish: <http://cdn.theoplayer.com/demos/theoplayer/lang/da.js>

German: <http://cdn.theoplayer.com/demos/theoplayer/lang/de.js>

Greek: <http://cdn.theoplayer.com/demos/theoplayer/lang/el.js>

Spanish: <http://cdn.theoplayer.com/demos/theoplayer/lang/es.js>

Persian: <http://cdn.theoplayer.com/demos/theoplayer/lang/fa.js>

Finnish: <http://cdn.theoplayer.com/demos/theoplayer/lang/fi.js>

French: <http://cdn.theoplayer.com/demos/theoplayer/lang/fr.js>

Croatian: <http://cdn.theoplayer.com/demos/theoplayer/lang/hr.js>

Hungarian: <http://cdn.theoplayer.com/demos/theoplayer/lang/hu.js>

Italian: <http://cdn.theoplayer.com/demos/theoplayer/lang/it.js>

Japanese: <http://cdn.theoplayer.com/demos/theoplayer/lang/ja.js>

Korean: <http://cdn.theoplayer.com/demos/theoplayer/lang/ko.js>

Dutch: <http://cdn.theoplayer.com/demos/theoplayer/lang/nl.js>

Polish: <http://cdn.theoplayer.com/demos/theoplayer/lang/pl.js>

Portuguese: <http://cdn.theoplayer.com/demos/theoplayer/lang/pt-BR.js>

Russian: <http://cdn.theoplayer.com/demos/theoplayer/lang/ru.js>

Serbian: <http://cdn.theoplayer.com/demos/theoplayer/lang/sr.js>

Swedish: <http://cdn.theoplayer.com/demos/theoplayer/lang/sv.js>

Turkish: <http://cdn.theoplayer.com/demos/theoplayer/lang/tr.js>

Ukrainian: <http://cdn.theoplayer.com/demos/theoplayer/lang/uk.js>

Vietnamese: <http://cdn.theoplayer.com/demos/theoplayer/lang/vi.js>

Chinese: <http://cdn.theoplayer.com/demos/theoplayer/lang/zh-CN.js> | <http://cdn.theoplayer.com/demos/theoplayer/lang/zh-TW.js>

## Code examples

##### Web SDK

Each language should be described as a [UIConfiguration](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/UIConfiguration)

```js
player = new THEOplayer.Player(playerElement, {
  libraryLocation: 'path/to/theoplayer/',
  license: 'your-license-here',
  ui: {
    language: 'esp',
    languages: {
      esp: {
        Play: 'Reproducir',
        Pause: 'Pausa',
        'Current Time': 'Tiempo actual',
        'Duration Time': 'Duración',
        'Remaining Time': 'Tiempo restante',
      },
    },
  },
});
```

##### Legacy Android SDK (4.12.x)

In the implementation for Android SDK, the addition of language needs to be done in 2 following Steps:

1. An Additional separate JavaScript file needs to be added to your Android project. You can follow the instructions presented in this article: [How to add/customize the Android THEOplayer SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)

2. After a JavaScript file is added to your project, Please add the specific language to the JS file

Sample Code to Add new language

```java
//add this code to pre.js file
THEOplayer.videojs.addLanguage("nl",{
    "Play": "Afspelen",
    "Pause": "Pauze",
    "Current Time": "Huidige tijd",
    "Duration Time": "Looptijd",
    "Remaining Time": "Resterende tijd",
    "Stream Type": "Streamtype",
    "LIVE": "LIVE",
    "Loaded": "Geladen",
    "Progress": "Status",
    "Fullscreen": "Volledig scherm",
    "Non-Fullscreen": "Geen volledig scherm",
    "Mute": "Geluid uit",
    "Unmute": "Geluid aan",
    "Settings": "Instellingen",
    "Quality": "Kwaliteit",
    "Speed": "Snelheid",
    "Normal": "Normaal",
    "AUTOMATIC": "AUTOMATISCH",
    "Automatic": "Automatisch",
    "Playback Rate": "Weergavesnelheid"
});
```

3. Create a new player configuration with declared new UIConfiguration:

Sample Code to create a new player config

```java
//declare the variable for THEOplayerView
THEOplayerView theoPlayerView;

//Create a new player config in onCreate(Bundle savedInstanceState):
THEOplayerConfig playerConfig = new THEOplayerConfig.Builder()
                .jsPathsPre("pre.js")
                .ui(new UIConfiguration.Builder().language("nl").build())
                .build();
theoPlayerView = new THEOplayerView(this, playerConfig);
```

##### Legacy iOS/tvOS SDK (4.12.x)

In the implementation for iOS SDK, the addition of language needs to be done in 2 following Steps:

1. An Additional separate JavaScript file needs to be added to your Android project. You can follow the instructions presented in this article: [How to add/customize the iOS THEOplayer SDK](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)

2. After a JavaScript file is added to your project, Please add the specific language to the JS file

Sample code to add new language

```swift
//add this code to pre.js file
THEOplayer.videojs.addLanguage("nl",{
    "Play": "Afspelen",
    "Pause": "Pauze",
    "Current Time": "Huidige tijd",
    "Duration Time": "Looptijd",
    "Remaining Time": "Resterende tijd",
    "Stream Type": "Streamtype",
    "LIVE": "LIVE",
    "Loaded": "Geladen",
    "Progress": "Status",
    "Fullscreen": "Volledig scherm",
    "Non-Fullscreen": "Geen volledig scherm",
    "Mute": "Geluid uit",
    "Unmute": "Geluid aan",
    "Settings": "Instellingen",
    "Quality": "Kwaliteit",
    "Speed": "Snelheid",
    "Normal": "Normaal",
    "AUTOMATIC": "AUTOMATISCH",
    "Automatic": "Automatisch",
    "Playback Rate": "Weergavesnelheid"
});
```

3. Create a new player configuration with declared new UIConfiguration:

Sample Code to create a new player config

```swift
//declare the variable for THEOplayerView
var theoplayer: THEOplayer!

//Create a new player config in ViewDidLoad()
let jsPath = Bundle.main.path(forResource:"pre", ofType: "js")!
let playerConfig = THEOplayerConfiguration(defaultCSS: true, jsPathsPre: [jsPath], ui: UIConfiguration(language: "nl"))
self.theoplayer = THEOplayer(configuration: playerConfig)
```

## Reference Material

A Sample project to demonstrate the above use-case:

1. Include THEOplayer Android SDK before compiling the entire project.

   Download Here: <http://cdn.theoplayer.com/demos/theoplayer/apps/lang/android-sdk-starter-project-master.zip>

2. Include THEOplayer iOS SDK before compiling the entire project.

   Download Here: <http://cdn.theoplayer.com/demos/theoplayer/apps/lang/ios-sdk-starter-project-master.zip>

---

# Customize UI during ad playback

This how-to guide describes how to customize the look and feel of the player when an advertisement is playing. We will be leveraging mainly some event listeners and CSS. In the section *Resources*, at the bottom of the page, you will also find links to the reference API and to a related how-to guide that explains when and how the texts displayed during ad playback (if any) may be changed.

## SDKs

| Web SDK | Android SDK                      | iOS SDK                          | tvOS SDK | Android TV SDK                   | Chromecast SDK |
| ------- | -------------------------------- | -------------------------------- | -------- | -------------------------------- | -------------- |
| Yes     | Through CSS/JavaScript injection | Through CSS/JavaScript injection | No       | Through CSS/JavaScript injection | N/A            |

## How to customize the ad playback UI

You may want to alter the UI during ad playback, for example in order to hide some elements, to show some new elements or to change the aspect of existing ones. In the following, we will see some example related to this.

### Detecting ad playback

There are two general approaches to detect advertisement playback:

1. A responsive approach using a **CSS rule**.
2. A programmatic approach using **events**.

##### Web SDK

Whenever you create a THEOplayer instance, you need to provide a DOM-element which will be the container of the player (for more information regarding this, see Resources). This container gains the `.theo-ad-playing` class whenever an advertisement is playing. Through CSS, you could use this class to enforce certain behavior. For example, you could hide the fullscreen button if an ad is playing.

```css
.theo-ad-playing .vjs-fullscreen-control {
  display: none !important;
}
```

##### Android SDK

The Web SDK code should be included in your Android (TV) project. The article at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios) explains how you can add CSS and JavaScript files to your project. The sample project at [How to insert a button](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-insert-a-button.md) demonstrates this.

##### Legacy iOS/tvOS SDK (4.12.x)

The Web SDK code should be included in your iOS project. The article at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios) explains how you can add CSS and JavaScript files to your project. The sample project at [How to insert a button](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-insert-a-button.md) demonstrates this.

### Events

The [Ads API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Ads) exposes, among others, the following events:

* `adbegin`: dispatched when an ad starts
* `adend`: dispatched when an ad ends
* `adbreakbegin`: dispatched when an ad break (or ad slot) starts
* `adbreakend`: dispatched when an ad break ends

##### Web SDK

The snippet below demonstrates how you could detect the start of an adbreak through a JavaScript event listener.

```js
player.ads.addEventListener('adbreakbegin', console.log);
```

These events can be used to trigger a certain behavior programmatically.

##### Android SDK

// work in progress

##### Legacy iOS/tvOS SDK (4.12.x)

// work in progress

### Displaying an advertisement label

##### Web SDK

The snippet below demonstrates how to add a label to the control bar during ad playback using CSS and JavaScript.

CSS

```css
.theo-ad-playing .theo-advert-label {
  display: block !important;
}

.theo-ad-playing .vjs-fullscreen-control {
  display: none !important;
}
```

JavaScript

```js
var button = THEOplayer.videojs.getComponent('Button');
var myButton = THEOplayer.videojs.extend(button, {
  constructor: function () {
    button.apply(this, arguments);
    this.el().innerHTML = 'Ad';
  },
  handleClick: function () {
    elementContainer.classList.toggle('hidden');
  },
  buildCSSClass: function () {
    return 'theo-advert-label';
  },
});
THEOplayer.videojs.registerComponent('AdvertLabelButton', myButton);
player.ui.getChild('controlBar').addChild('AdvertLabelButton', {});
```

##### Android SDK

// work in progress

##### Legacy iOS/tvOS SDK (4.12.x)

// work in progress

### Adding a custom countdown

##### Web SDK

The snippet below demonstrates how to add a countdown timer using primarily JavaScript.

CSS

```css
.theo-ad-countdown {
  position: absolute;
  top: 50%;
  left: 50%;
  font-size: 5em;
}
```

JavaScript

```js
function updateTime() {
  var countdown = document.querySelector('.theo-ad-countdown');
  if (countdown) {
    countdown.innerHTML = Math.round(player.duration - player.currentTime);
  }
}

player.ads.addEventListener('adbegin', function (e) {
  var countdown = document.createElement('div');
  countdown.className = 'theo-ad-countdown';
  countdown.innerHTML = player.duration;
  element.appendChild(countdown);

  player.addEventListener('timeupdate', updateTime);
});

player.ads.addEventListener('adend', function (e) {
  var countdown = document.querySelector('.theo-ad-countdown');
  if (countdown) {
    player.removeEventListener('timeupdate', updateTime);
    element.removeChild(countdown);
  }
});
```

##### Android SDK

// work in progress

##### Legacy iOS/tvOS SDK (4.12.x)

// work in progress

---

# How to change how a video should be fit inside a container

This question is asked by developers who want to alter how a video should be sized inside the video's frame. By default, a video player respects the aspect ratio the video.

* For example, due to size of the container/frame, black pillars appear on the sides of the container. Instead, you want your video to cover these black pillars, even though this
* Cuts out content outside the box.
* Or deforms the content, and causing misalignment with the aspect-ratio.

## SDKs

| Web SDK | Android SDK | iOS SDK                                     | tvOS SDK | Android TV SDK |
| ------- | ----------- | ------------------------------------------- | -------- | -------------- |
| Yes     | Yes         | Unverified through CSS/JavaScript injection | No       | Yes            |

## Code example

The snippets below help you understand how you could attempt to implement this use case.

### Web SDK

The CSS [`object-fit`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) property serves this use-case.

```css
.theoplayer-skin video {
  object-fit: contain; /* default */
  /* object-fit: cover; // content outside of the container, hence some content might be missing from the container */
  /* object-fit: fill; // all content inside of the container, but the content might be deformed to be fitted inside of it */
}

/*
// if you are doing object-fit: cover, and you don't want to show the content outside of the container, then do:
.theoplayer-skin {
    overflow-y: hidden;
}
// additionally, the object-position CSS property can help position the content, e.g.
.theoplayer-skin video {
    object-position: top;
}
*/
```

Alternatively, if you cannot use CSS for some reason, you could try to achieve the same through JavaScript.

```javascript
const videos = document.querySelectorAll('.theoplayer-skin video');
for (let i = 0; i < videos.length; i++) {
  videos[i].style.objectFit = 'cover';
}
```

##### Legacy Android SDK (4.12.x)

For SDK version **3.6.1** and above, you can use the API described at [Player#setAspectRatio(AspectRatio)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/Player#setAspectRatio\(AspectRatio\)) to set the [AspectRatio](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/android/com/theoplayer/android/api/player/AspectRatio) values.

The snippet below demonstrates how you could use this API:

```java
theoPlayerView.getPlayer().setAspectRatio(AspectRatio.FIT);
```

If you are using one of `minApi21`, `androidTV` or `fireTV` SDK with version below 3.6.1, the Web SDK code above should be included in your Android (TV) project .

The article at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios) explains how you can add CSS and JavaScript files to your project. The sample project at [How to insert a button](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-insert-a-button.md) demonstrates this.

### iOS (tvOS) SDK

You can use the API described at [THEOplayerFullscreen](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/ios/Protocols/Fullscreen_Objc#/c:@M@THEOplayerSDK@objc\(pl\)THEOplayerFullscreen\(im\)setAspectRatioWithAspectRatio:) to set the [video gravity](https://developer.apple.com/documentation/avfoundation/avplayerlayer/1388915-videogravity) values.

The snippet below demonstrates how you could use this API:

```swift
theoplayer.fullscreen.setAspectRatio(aspectRatio: AspectRatio.fill)
```

---

# How to make an audio-only player

This article will tell you how to manipulate THEOplayer (Web) to make an audio-only interface, using only CSS and JavaScript. This applies also to mobile SDKs, where CSS and javascript can be injected (see *Resources*).

Going from this ![Audio Only](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAf0AAAEhCAYAAAB1MHncAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAABKvSURBVHhe7d1vsF1VeQdgtWAEiWBAI/9CgoGQSIgGQsQQIhhgpqWdYFstMIrTCmNrFREwQztatKWFgtggcVI6dkBQalOlKBQLUwZoh8GRts60tS0znZYPOvClpbRjP+7y3nafu3Py3su95+x9/qw8Z+bJZH5nnb3WXufDunuftdd6VeXl5eXl5eV1QLxe9fIr/gEAypeGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQ2AKrVh+UHXxtmXV9ZefUN35a2urh3ZtrL53zzurf3ngnOqFR8+rXnry/OrHT10wI/4fWbwXZaJsfCY+G8eIY2V1AFMtDYEpcObaQ2cG6Qc+//bquQe3Vf/z1IWtimPGsaOOqCtrAzBV0hCYUBdtOWLmijyu0LOBut/zf35e9YO9Z1dP37W5emzPGdUju0+fEf+PLN6LMtln+0WdUXe0IWsbMPHSEJgg61YuqW69avW8A/2z92+t9t68obrhylXV+95zVLX+xCXVkte+Jj1eJsrGZ+KzcYw4VhwzqytEW6JN0bbseMBESkNgAsQVddxezwbduDq/78b11RU7jq5WveXg9PNtiGNHHVHXXHcEoo2u/mEqpCEwRjGRLm6/9w+uLz6xvfrKZ0+tdpyzLP3cKETd0YZoS3/7os3R9uxzwERIQ2AMtpx22Mws+v7B9Jl7z6o+cclxi7pd37VoS7Qp2tbf3jiHOJfsc8BYpSEwQjGA7t55yn6DZ1w5x2/s2WcmSbQxuzMR5zRJf6gAeQiMyGUXvnm/CXoxq34aBvt+0eZoe/Nc4tziHLPywMilITAC8fhbc4CMiXJxyzwrO03iHPon/cW5ZmWBkUpDoEOx0E2sgtccFGNy3JFLy7kVHucS59Q8xzhni/zAWKUh0JEPXbR8ZgnceiCMK+LIsrIliHNrXvXHuZd8vjDh0hDowGc+vLI3+IVYGa/LZ+wnRZxjnGvz3KMvsrJAp9IQaNmua07eZ9C747o1abmSxTk3+yD6JCsHdCYNgRb1T9i77gMr0nIHgjj3Zl+Y4AcjlYZAS/oHfL9n/9/v/M0+MfDDyKQh0IL+W/rT+Ox9V6Ivmn3jVj+MRBoCQ+qftGfA31//wG9yH3QuDYEh9N++dkt/bvoKRioNgQHF4jPN5/AP5El7C9Wc3Bd9ZwEf6EwaAgNqrrR3ID6WN6jm43zRh1kZYGhpCAygOVM/FqPJygzq3I1L07wkzQV8zOiHTqQhsEixk1w9YMWys22utPfag19d/e1Xz6q+/7V3VXuuX1td+nJdhx9a3pa10WfNJXvtzgetS0NgEWLP+Ob2uG1PRtu64bDqv/9ydp5A+NF3zq3uv2XDzI52xx51UPq5adSc2Bd9aj9+aFUaAouwe+cpvYEqdpbLygzjql84rnf8zA8ffnd129UnVetWLkk/P22au/NF32ZlgIGkIbBAW047rDdAxa3pLrbHvfPX913Vby7//vj26vevX1ttXjfds9+jD5u3+aOPs3LAoqUhsEAP7drYG5ziVntWZlhP/sGmXh0Ldc/nTq22b3pDerxpEH1Zn0v0cVYGWLQ0BBbg4m3LegPT03dtTsu04flHzu3Vs1jf/N0N1Y5zlqXHnXTRp/V5RF9nZYBFSUNgAR7bc0ZvUOpqmd1TVy3p1TGMvTedVp31ttendUyq5jK90ddZGWBR0hB4BRdtOWIkA9L7t++7Pv0wXnpye3XLx1dXS6focb/mH1bR51kZYMHSEHgFD3z+7b3BqMvNdHZ+cN/959vw91/fUn3kvcek9U2a5tV+9HlWBliwNATmEY/G1QPRM/eelZZpy+5PzS5P27YHf+8dUzHZL/q4bnMpjyXCmKQhMI9br1rdG4S6mrFf+9Zts3cUunLHy39YTPICP82Z/NH3WRlgQdIQmEe9+t6LT2zvfMW4v/nq7FVul+KcPnnZ8Wkbxi36OPq6bmdWBliQNATm0JzA18Xqe/1eeHR2kZpRiDsLZ6w5JG3LODVX6TOhDwaWhsAcmjvpdf38e8yyr+sapfhDIyYQZm0al+jrun124IOBpSEwh/rWfiwTm73fprjirge6cZi0q/56aV63+GFgaQgkzlx7aG9AvO/G9WmZNrX5jP6gJumqP/q8bld8F1kZYF5pCCSuv/yE3qBzxY6j0zJt6uIZ/UFNwlV/9HndnvgusjLAvNIQSDQX5Fn1loPTMm26+WOzjwZOgnFf9Uef122xUA8MJA2BxHMPbpsZcJ69f2v6ftu+cPVJvUFuksSAe8rxr03b3LXo+2hDfBfZ+8C80hDos2L5Qb1Bb+/NG9IybYtFc+o6J01MpvvAT745bXeXou/rNsR3kpUB5pSGQJ/mNro3XLkqLdO25uOBk+q2q09K296V6Pu6btvtwqKlIdCnOYmvyw12mu76jbf16pxkj+4+vdo0otn0zQ14TOaDRUtDoE/zqnv9iaPZ9OWrvzm7Ct2k+9F3zh3Jzn3R93WdFumBRUtDoM9Duzb2Bpuu19uv7b3ptF6d02LP9Wur13XYP9H3dV3xnWRlgDmlIdDne/e8c2agGcVKfLU/vbX7Hfa68FdfPrPauuGw9JzaUK/MF99J9j4wpzQE+tTL7/5g79np+114aNc79hlMp8nzj5xb/eLPvCU9r2HFdxB1WI4XFi0NgT71bndP37U5fb8LMUGuOZBOo9/+6FvTcxtGfAdx7PhOsveBOaUh0OelJ8+fGWge23NG+n4XHr9z0z4D6LT62m+1u09BfAdx3PhOsveBOaUh0OfHT10wM9A88vLVd/Z+Fx790vRf6dfid/5jjvyJ9DwXK76DOGZ8J9n7wJzSEOgzjkH/z26ffWJg2v3Fy1fnRy1tZ1a/QR8GloZAn3Hc3v9WY4OfaXb7tSen5zcot/dhYGkI9BnHRL4/aawzP60+/v5j03Mbhol8MLA0BPqM45G9P7px/T4D6DT5x2+cXf302W9Mz2tYHtmDgaUh0Gcci/N85bPTswxv0903vG1m7/vsnNpgcR4YWBoCfcaxDO8ffnpdr85p8Hdf31Jd/lPL03Npi2V4YShpCPQZx4Y7sY59Xeek+9LOU6ojW5qdPx8b7sBQ0hDoM46tdb943ZpenZPqu3dvrn7uvCPT9nfB1rowlDQE+ly8bVlvsLnhylVpmbbddvVJvTon0S1Xra6WHPzqtO1dib6v64/vJCsDzCkNgT4rlh/UG2z23rwhLdO2mz62ulfnJImVAi/cfETa5q5F39ftiO8kKwPMKQ2BxHMPbpsZbJ69f2v6fts+8+GVvQFuEsQjcp+89Pi0raMSfR9tie8iex+YVxoCiQcaK+R1+Uha7aM/f2yvvnHbvfOU6tijxntlHX1etye+i6wMMK80BBLNyXxX7Dg6LdOmSy54U6++cXn49o3VBZsPT9s3atHndbtM4oOBpCGQOHPtob1B574b290uNnPBmYf36hu1f/rG1upj72t/Cd1hRJ/X7YvvIisDzCsNgTnUy/GOYmW+jScf0hvkRmnXNSdXb3pDO9vgtqleic/yuzCwNATm0FykZ8c53T4yFr+h13WNwre/8I7qvI1L07aMW/R13U6L8sDA0hCYw0VbjugNPrE2flamLc0lZ7v0xJ2bqssufHPahknR3IcgvoOsDPCK0hCYR32L/8Untne+Dv9/PL69N9i17a/vPav65Z89Jq13kkQfR19Hm93ah6GkITCPW6+aXTTnE5ccl5Zpy7/9/9oAbfrnb26tdn5wRXXQa/I6J030cd326PusDLAgaQjMY93K2U1fnnn5ajkr05bvf+1dvbqG9cOH313d+CsnVm98/Wh2CWxL9HF9DtH3WRlgQdIQeAXNhXq63IDn8Ts39eoZ1H8+sb26/dqTq7ce3f2CQm1rbrBjQR4YWhoCr6A5oe+xPWekZdoQK+HV9SzWfz15fvXlT6+rTl9zSHrsaRB9W5+PCXwwtDQEFqA5IHV1tf+R9x7Tq2Ohnn/kvOqL166pNqx+XXrMadG8yu/yDys4gKQhsADN7XafvmtzWmZY79n0hl4dr+Rfv72t+p1ffWt14gj2BRiF6NP63GyjC61IQ2CBHtq1sTcwdTGT/4TGlr5z+Yc/3lJ9+pdWVkcuna4JevNpztiPPs7KAIuWhsACbTntsN7gFMvEdjHwfv++fAb/d+/eXF196fHVkoNfnX5uWkUf1kvuhujjrBywaGkILEJzsl0Xq/R967bZJwViP/k7rlszsxlPVrYEzdX3om+zMsBA0hBYhFgxrl6lL3zoouVpuUHd8ak11b2fO7V6//buHg2cFNF3dT9Gn3a94iEcYNIQWKRYu74erOLW9KoWJ9MtPfTAGPiiz5q39Sd9PwCYQmkIDKC5A98ju09PyzC36LO6/+ykB51IQ2BA37vnnb2BK357z8qwv+irut+iD7MywNDSEBjQmWsPrV568vzeAHbdB1ak5ZgVfVT3V/Rd9GFWDhhaGgJDaE5GC21P7CuJvoKRSkNgSJ/58Mp9BrMuN+WZVs1ldkP0WVYOaE0aAi3Ydc3J+wxqBv5Z/QN+9FVWDmhVGgItac7oD25f739L30x9GJk0BFrUP/AfyJP7mpP2ggEfRioNgZb13+o/EB/naz6WF9zSh5FLQ6AD/ZP7YjGaNlfum1Rxjs2Fd4JJezAWaQh0JH7Pbj7HH8vOlvw7f5xbc2ndOHfzGmBs0hDoUCw+01y5L8TOciXthx/n0twtL8Q5W3gHxioNgRHon+AXV8SfuOS4tOw0iXNoXt0HE/ZgIqQhMCKxk1xzW97w9F2bp/KZ/mhztL15LnFudsuDiZGGwAjFnvG7d56yz2AZHttzxlQM/tHGaGt/++Oc7IcPEyUNgTHYctph1UO7Nu43eD5z71kzt8wnaQCNtkSbom397Y1ziHPJPgeMVRoCY3TxtmXplfOLT2yfmRy345xl6edGIeqONkRb+tsXbY62Z58DJkIaAhPgoi1HVA98/u37Da4hJsrdd+P66oodR3f6rH8cO+qIuvon59WijdHW7PPARElDYIKsW7mkuvWq1ftN+Gt69v6t1d6bN1Q3XLlq5jf29ScuWdTPAVE2PhOfjWPEseKYWV0h2hJtirZlxwMmUhoCEyquqOPxt/n+AGiKq/Mf7D17ZlZ93H6PlfFC/D+yeG+uK/h+UWfU7aoeplYaAlMgFrq5/vITZm6vP/fgtnSgHkYcM44ddVhUB4qQhsAUWrH8oJmJdDFIxxV5zKKPVfDiCv2FR8+bWQL3x09dMCP+H1m8F2WibHwmPhvHiGNldQBTLQ0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE8aAgDlSUMAoDxpCACUJw0BgPKkIQBQnjQEAMqThgBAedIQAChPGgIA5UlDAKA8aQgAlCcNAYDypCEAUJ40BADKk4YAQHnSEAAoTxoCAOVJQwCgPGkIAJQnDQGA8qQhAFCeNAQAypOGAEB50hAAKE3l5eXl5eXldQC8qup/AZqSq1BORoY4AAAAAElFTkSuQmCC "Audio Only")

to this

![Audio Only](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAf8AAAA0CAYAAACEqTF9AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAN2SURBVHhe7d0xSxx5HMdhCWIhiI2FBGLjO0hpZy0ptMlbSJvG0sLORoiCvQgWqQwWwglJFQvroIJgDsRCBEW0UNH8c785R1Z3PDDZXXPzf77woOvODCHNZzeOpiv9s66uLgAgA0X3xR8A8iH+AJAZ8QeAzIg/AGRG/AEgM+IPAJkRfwDIjPgDQGZ+Of4jIyMAwB+iqtWPEX8AqIGqVj9G/AGgBqpa/RjxB4AaqGr1Y345/gDA/5P4A0BmxB8AMiP+AJAZ8QeAzIg/AGRG/AEgM+IPAJkRfwDIjPgDQGayjP/w8HDx8fvf39OnT5/SwMBA0zEAUFdtif+rV6+e/HuGO2V2draIfnx+dnZW/AX8+PEjra6uNh0LAHUUa3n8JyYmiguvrKyk7u7uymOeQ4Q/tr+/XzyemppKl5eXxddiHz9+bDoHAOom1rb4x87Pz9Pbt28rj+ukMvyxMv6hp6cn/bW+fvtMSu/fv793HgDUTayt8S+3sbGR+vr6Ko9vt8bwx8r4Ly0tFfGPz/f29ornbm5uUn9//73zAaBOYh2Jf+zq6ipNTk5WntNKnz9/TicnJ3cerox/fM//6Ogo9fb2Fjf9Rfhjc3NzTdcEgLqIdSz+5XZ3d+/uuG+HiPt/rTH+senp6eJx+e5/Z2fn3vUAoE5iHY9/LN5lz8/PV57/u54a/2/fvhWP44a/WPxrQOP1AKBOYs8S/9iXL18qz/9dT41/+U5/cXGxeHx8fHzvegBQJ7GOx//09DS9efOm8txWeGr8P3z4UDyOFwGx+LZE4/UAoE5iHYt//DKd5eXl9OLFi8rzWmV7e7v4tkLp4Rrjf3FxkQYHB4u7/uOGxFj8FMDDawJAXcQ6Ev+Dg4P0+vXryuPbbW1t7fZP8e/K+K+vr6ehoaHi868bX2+fTXdfA4A6irU1/tfX12lmZqbyuE5qfAFQxr/U+HsAFhYW7j0HAHUTa1v84y76ly9fVh7zHMoXAGX8x8fH0+HhYfG12ObmZtM5AFA3sZbHP4L/7t27yueeW7wAeHjDXyxu9vuT/h8CAGiXWMvj/6cbGxsrPsaP9G1tbaXR0dGmYwCgrrKMf8k7fQBylHX8ASBH4g8AmRF/AMiM+ANAZsQfADIj/gCQGfEHgMyIPwBkRvwBIDN38TczM7N8Jv5mZmaZTfzNzMyyWko/AakVHpXdu7n/AAAAAElFTkSuQmCC "Audio Only")

## SDKs

| Web SDK | Android SDK                                       | iOS SDK                                           | tvOS SDK | Android TV SDK                                    | Chromecast SDK |
| ------- | ------------------------------------------------- | ------------------------------------------------- | -------- | ------------------------------------------------- | -------------- |
| Yes     | Unverified / Through CSS and JavaScript injection | Unverified / Through CSS and JavaScript injection | No       | Unverified / Through CSS and JavaScript injection | N/A            |

## Making the audio player from the video player

This section explains how to alter the default video player UI into the UI shown in the picture below, thus transforming a default THEOplayer instance in an audio player. This can, of course, be further customized to your liking to adapt to the rest of your implementation.

![Audio Only](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAArMAAAAvCAYAAADw3EIKAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAggSURBVHhe7d1vqE3bGsfxkySRlCgpSiQlJSnaipRckRdESrwREfGGdpGQ8sILvBBSnEjyJ+3rb+meQuocUXLLn0S4CeeG/Cnb9X/c8RvHWGfsuZ+19tx7O2ePre9TH9YzxzPHWnOXeow15tw/OYIgCIIgCILopPGTD/0BAAAAdApp+NwuAgAAAHKUhs/tIgAAACBHafjcLgIAAABylIbP7SIAAAAgR2n43C4CAAAAcpSGz+0iAAAAIEdp+NwuAgAAAHKUhs/tIgAAACBHafjcLir632//ALJw8+bNNqmrqwMAABmyes9a0vC5XVRkNRVAR7Aa1TKsfzwAAKDjWb1nLWn43C4qspoKoCNYjWoZ1j8eAADQ8azes5Y0fG4XFVlNBdARrEa1DOsfDwAA6HhW71lLGj63iwAAAIAcpeFzuwgAAADIURo+t4sAAACAHKXhc7sIAAAAyFEaPreLAAAAgByl4XO7CAAAAMhRGj63iwAAAIAcpeFzuwgAAADIURo+t4sAAACAHKXhc7sIAAAAyFEaPreLfiR9+/Z1PXr0cCtXrnRPnz51CxcuNOsAAACQvzR8bheVNXXqVLdjx46KiRMnVsZGjRrVZGzBggVNzv079OvXz71588bNnDnTrV279ttlO/fixYvw2a1zAAAAkK80fG4XlXXu3LlvU/0R+/btq4ylzaPi+r+vNzn3rxYbWYWa2UGDBrkbN26EXPHx48dwzDq3tbp06WIel1pjUXvPTw0ZMiSsRltjRd26dTOPt/Y9i9p7PgAAQDVp+NwuKivXZjZtZBVqZuPYlClT3IcPH8Lx58+fu65duzY5tzU2bNjg3r59G+Z69uyZGz58eDiuOX/97dfQMH/58sVdv37dDR06tNn5avquXLniPn/+HOouX75c+TyLFi1yjx49CnO/fPnSzZkzp9n5llevXrn6+npzLLVq1aowd+/evSvHql1P0bVr18JnjvSeOl7regAAAL6HNHxuF5WVYzNbbGQVambnzp3rli1bFmpmz579bcS506dPN5ujjLq6Ovf161e3Z88eN3bsWPf7f393T548CWP6OaiRnTx5cthuoWZPjV1xjsOHD7tPnz65MWPGhC0amm/37t1u2LBh4bUaw8GDB7uGfzaE5tBqiFNakdV5PXv2NMdFzevFixe/Xf2fzWyt6ylqfNfozp49GxpsmTZtWjhe7XqK5wMAALRVGj63i8rKoZlVE6ZmMVITWYx0z+z69evDeSdOnAi5VmmLc5Zx5MgR9/79+0q+ZMmSMJ++ut+8eXN4vzimVVqteOr1vXv33KVLl8Jrffbp06eH17169QoNq+Zds2ZNmGvgwIFhTHMqtm/fHvJqtLKq1WZrLFq9erVrbGwM+5gVsZmtdT3z5s0LP1et1Hbv3j0c138IVJOu3la7njgOAADQXmn43C4qK4dmVo1qS5E2s2rkdJ5WTWNoJbE4b0vUoOqr+JhrNVOhldi0rn///uFrd9Urb2hocLt27WpSo9XLd+/eBdrzOnr06DDXjBkzwnic+/jx403OK9J2hpMnT5pjkZpRbQfQDXCK2MzWup5Jkya5W7duuQEDBoTGVqFV1xhbt26tnCfF60nHAAAA2iMNn9tFZXXGZlYxcuTIcG5syBYvXtxs3pZcvXrVPX78uJKraVOoSY7HtDqpJydo9VfbH+LxIn09r0ZSn2fjxo3h2OvXr8PX+UePHq1smzh27Fizc1N6H62YWmNFxWa2zPWItmpo9VdbC7RyfPfu3dC0pjXW9QAAAHwPafjcLiqrszaz48aNC+dqxVSxfPnyZvO2RNeefqU/YcKEMFefPn1Crr/jtgettMa6Wu7cuROaWL3W1/VqCNUo/uuXX0Jju2nTpmbnRFpJ1df61pil2My2dD3V6HMq4ipyKr0eAACA7yENn9tFZXXGZjbukY1foyvGjx/fbN6W6Kt03ewUc82vlUi91g1YamT1XrUa2TNnzjT5mZ06dSo0pFrR3bJlS9gSoOO6sUsxa9asSm3Rvp9/dvfv3zfHLMVmttb1pNatW1fZ8yt6frBCN61Vu56YAwAAtFcaPreLysqhmdXX3WqYorh1II20md2/f384b+/evSHX6mxbnouqZ9QqtEdVK71qXrUSqbHz58+HMd2QNX/+/ECfQWM6tmLFivD64MGD4f1145QeGaYbsB4+fBgeZ6XGUlsMdAOWtgDoBrJaj7l6+J+HrXpyQLGZrXU9I0aMcIcOHQq18T8P+nnq6Qp6fFhcfa12PfE9AQAA2isNn9tFZeXQzBbpZq7iEw3UgKmh3LlzZ6VGja8i3pjVFgcOHAhzKLSvVauTOh7nTkOfSWPaQ3v79u3wWiuwDx48CA246LgaR41t27atsg1CWwysr/EjNeN6z+LNZ7Wo2VToM8Rj1a5n6dKl4VicX816vEZdV3wGbq3rAQAA+B7S8LldVFaOzawUG9q4Kiq6Iz/eUKX9qC3tCW2JtgK09PzXlugzpE1lpCa1zNyq0xMHrLHWKns9es9qjWq16wEAAGivNHxuF5WVazMraUOrZlZNmh6LFbch6O+27JUFAABAx0nD53ZRWXqk1YULFyr0W7bimJrJdCz+soK/U2xo1cymzbX2o7blCQYAAADoWGn43C76kehpAvrFBfX19eGGJP3CAt1UZdUCAAAgb2n43C76EWmPp1hjAAAA6BzS8LldBAAAAOQoDZ/bRQAAAECO0vC5XQQAAADkKA2f20UAAABAjtLwuV0EAAAA5CgNn9tFAAAAQI7+DOf+D9Obw/667MRKAAAAAElFTkSuQmCC "Audio Only")

The alteration involves 8 steps:

1. Add a new class to 2 HTML elements in the player (JavaScript)
2. Hide unnecessary buttons from the control bar (CSS)
3. Hide content that might appear above the control bar (CSS)
4. Decrease the player's height (CSS)
5. Ensure the control bar is always visible (CSS)
6. Rescale the loading spinner (CSS)
7. Change appearance for when the stream is not yet loaded (CSS)
8. (Optional) Add the audioOnly flag (JavaScript)

In the following, you can find a description and a code example for each step.

## Code examples

##### Web SDK

### 1 - Add a new class to 2 HTML elements in the player

To comfortably provide the required CSS during the next steps, we add CSS classes to two HTML elements, respectively:

1. 'audioplayer' to the player element (select it using the 'vjs-fluid' class)
2. 'audiocontrol' to the controls element (select it using the 'vjs-control-bar' class)

```js
function transformPlayer(forAudio) {
  var player = document.querySelector('.vjs-fluid');
  var controlbar = document.querySelector('.vjs-control-bar');
  if (forAudio) {
    player.classList.add('audioplayer');
    controlbar.classList.add('audiocontrol');
  } else {
    player.classList.remove('audioplayer');
    controlbar.classList.remove('audiocontrol');
  }
}
```

### 2 - Hide unnecessary buttons from the control bar

There are a bunch of buttons in the control bar that might not be relevant for an audio-only stream. Hence, we hide the following buttons using CSS:

* Subtitles button
* Quality label
* Audio menu
* Settings menu
* Fullscreen control
* Cast button

```css
.audiocontrol .vjs-icon-subtitles,
.audiocontrol .theo-quality-label,
.audiocontrol .vjs-icon-audio,
.audiocontrol .vjs-icon-cog,
.audiocontrol .vjs-fullscreen-control,
.audiocontrol .theo-cast-button,
.audioplayer video {
  display: none !important;
}
```

### 3 - Hide content that might appear above the control bar

Now we need to make sure no content appears above our controls. Again, we use CSS to hide elements:

* Poster image
* Video
* Metadata (like song info)

```css
.audiocontrol .theoplayer-poster,
.audiocontrol .song-info,
.audioplayer video {
  display: none !important;
}
```

### 4- Decrease the player's height

Next up, decreasing the player height to 50px.

```css
.audioplayer {
  padding: 0 !important;
  height: 50px !important;
}
```

### 5 Ensure the control bar is always visible

By default, the control bar fades away to ensure better user experience for the video viewer. The following snippet ensures that the controls stay always visible.

```css
.audiocontrol.vjs-control-bar {
  visibility: visible !important;
  opacity: 1 !important;
  display: flex !important;
}
```

### 6 - Rescale the loading spinner

An optional step is to scale the loading icon that spins when the player stalls.

```css
.audioplayer .vjs-loading-spinner {
  transform: scale(0.3) !important;
}
```

### 7 - Change appearance for when the stream is not yet loaded

We're almost there. We just need to remove the giant play-button that shows when the video hasn't started yet.

```css
:not(.vjs-has-started).audioplayer .vjs-big-play-button {
  display: none !important;
}
```

Should we stop here, the audio player would show 0:00 / 0:00 as time information, since the stream is not yet loaded. This looks a bit clumsy, so we can hide it until the stream has started.

```css
:not(.vjs-has-started).audioplayer .vjs-current-time,
:not(.vjs-has-started).audioplayer .vjs-time-divider,
:not(.vjs-has-started).audioplayer .vjs-duration {
  display: none !important;
}

.vjs-has-started .vjs-current-time,
.vjs-has-started .vjs-time-divider,
.vjs-has-started .vjs-duration {
  display: flex !important;
}
```

Note: if you preload the source (see *Resources*), hiding the time information before the player starts playing may not be needed, as the duration will be already available.

### 8 - (Optional) Add the audioOnly flag

Finally, we recommend you to set the audioOnly flag to true in the player configuration. In that case, the player will use an audio element instead of a video element for media playback. This is only supported for HLS streams for now. Otherwise, the player uses a video element instead. This plays without any issue on most platforms, however we have noticed that Firefox doesn’t handle video elements with height and width 0 well.

```js
const player = new THEOplayer.Player(element, {
  audioOnly: true,
});
```

### Result

You should end up with a player that looks like this:

![Audio Only](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAq4AAAAxCAYAAAAbUCu5AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAefSURBVHhe7d1tiE1rH8fxO0kiKVFSlEhKSlI0ipQckRdESrwREfGGFAkpL7zACyHFiSQPaW6PpaOQckRpTnlIxNwJ54Q8lHE8X+f8/rdr32vW/u+918zuPnONvv/6ZO//tdbae01N/VzrWmv+9XcFAAAAoBNwmwAAAEBq3CYAAACQGrcJAAAApMZtAgAAAKlxmwAAAEBq3CYAAACQGrdZ5s9ffwKScPv27XZpaGgAAAAJ8rJnBW6zjBcggI7ghdIivF8UAADQ8bzsWYHbLOMFCKAjeKG0CO8XBQAAdDwve1bgNst4AQLoCF4oLcL7RQEAAB3Py54VuE0AAAAgNW4TAAAASI3bBAAAAFLjNgEAAIDUuE0AAAAgNW4TAAAASI3bBAAAAFLjNgEAAIDUuE0AAAAgNW4TAAAASI3b/KH07ds39OjRI6xcuTI8e/YsLFy40N0OAAAASXObhU2dOjXs3LmzZOLEiaWxUaNGtRpbsGBBq33/Cf369Qtv374NM2fODOvWrQuxXr58ad/d2wcAAABJcpuFnT9//nsU/G/t37+/NJYNiqqm35pa7fv/FkOrSsF10KBB4datW/Ze9enTJ+t5+7ZVly5d3L5UG4vq3T9ryJAhNsvsjeV169bN7bf1M/Pq3R8AAMDhNgtLNbhmQ6tKwTWOTZkyJXz8+NH6L168CF27dm21b1ts3LgxvHv3zo71/PnzMHz4cOvrmFd/vWrh+OvXr6GpqSkMHTq0bH8FvOvXr4cvX77YdteuXSt9n0WLFoXHjx/bsV+9ehXmzJlTtr/n9evXYc2aNe5Y1qpVq+zYvXv3LvUqnU/ezZs37TtH+kz1q50PAABAndxmYSkG13xoVSm4zp07Nyxbtsy2mT179veREM6cOVN2jCIaGhrCt2/fwt69e8PYsWPD73/8Hp4+fWpj+jkotE6ePNmWTCjYKcTlj3HkyJHw+fPnMGbMGFtmoePt2bMnDBs2zF4rBA4ePDg0/rvRgqAXfrM006r9evbs6Y6Lgurly5e/n/3/gmu188lred8Szp07Z2Fapk2bZv1K55PfHwAAoB3cZmEpBFcFLgXDSIExX9k1rhs2bLD9Tp48ae81+5o/ZhFHjx4NHz58KL1fsmSJHU+X37ds2WKfF8c0+6qZTL1+8OBBuHLlir3Wd58+fbq97tWrl4VTHXft2rV2rIEDB9qYjqnasWOHva9EM6aaRfbGotWrV4eWlhZbd6yKwbXa+cybN89+rpqB7d69u/UV/rVNdla20vnEcQAAgDq4zcJSCK4KpbUqG1wV2rSfZkNjaYYwf9xaFEZ1OT2+1yylSjOs2e369+9vl861vd43NjaG3bt3t9pGs5Lv3783WqM6evRoO9aMGTNsPB77xIkTrfbL05KEU6dOuWORgqcu6evmNFUMrtXOZ9KkSeHOnTthwIABFmJVmk2NtW3bttJ+kj+f7BgAAEA7uc3COmNwVY0cOdL2jeFr8eLFZcet5caNG+HJkyel9wpoKgXi2NOso55goFldLWGI/TxdYldo1PfZtGmT9d68eWOX5I8dO1Za+nD8+PGyfbP0OZoJ9cby8sG1yPmIlltoVlfLAzQjfP/+fQuo2W288wEAAKiT2yysswbXcePG2b6aCVUtX7687Li16Nyzl+UnTJhgx+rTp4+9179x6YJmUON21dy7d88Cq17rkrvCn0LhLxcuWIjdvHlz2T6RZkh1ad4b8+SDa63zqUTfUxVnh7Oy5wMAAFAnt1lYZwyucU1rvBSuGj9+fNlxa9HlcN2IFN/r+Jph1GvdHKXQqs+qFlrPnj3b6md2+vRpC5+aqd26datd1ldfN12pZs2aVdo2b//PP4eHDx+6Y558cK12Plnr168vrdEVPZ9XpRvKKp1PfA8AAFAHt1lYCsFVl6wVjqJ4+T9b2eB64MAB22/fvn32XrOu7XnuqJ4Bq9KaUs3gKqhqhlFjFy9etDHdLDV//nyj76Ax9VasWGGvDx06ZJ+vm5r0mC7dHNXc3GyPkFKI1DIB3Ryly/i6uavao6Wa/9Pcpjv488G12vmMGDEiHD582LaN/1HQz1NPOdAju+KsaqXziZ8JAABQB7dZWArBNU83WuWfLKCwpfC4a9eu0jYKuap401R7HDx40I6h0jpUzTqqH4+dLX0njWnN6927d+21ZlYfPXpkYVvUV0jU2Pbt20tLGbRMwLsUHyl46zPzN4ZVo2Cp0neIvUrns3TpUuvF4yuYx3PUecVnzFY7HwAAgDq5zcJSDK6SD69xtlN0Z3y82UnrR2ut4axFl/NrPV+1Fn2HbICMFEiLHFvb6c5/b6ytip6PPrNSKK10PgAAAHVwm4WlGlwlG14VXBXI9CiquJRA/7ZnbSsAAAA6hNssTI+RunTpUon+OlUcU3DMjsUH//+TYnhVcM0Gaa0fbc+TBAAAANBh3OYPRXf1648A6O/362YhPfxfNzx52wIAACBZbvOHpDWZ4o0BAAAgeW4TAAAASI3bBAAAAFLjNgEAAIDUuE0AAAAgNW4TAAAASI3bBAAAAFLjNgEAAIDUuE0AAAAgNW4TAAAASMv3P91PURRFURRFUUkXwZWiKIqiKIrqBBXCX2Lvh9WhXJHWAAAAAElFTkSuQmCC "Audio Only")

You can further modify the audio player that you have at this point to better fit in your implementation.

##### Legacy Android SDK (4.12.x)

The Web SDK code should be included in your Android (TV) project. The article at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios)explains how you can add CSS and JavaScript files to your project.

##### Legacy iOS/tvOS SDK (4.12.x)

The Web SDK code should be included in your iOS project. The article at [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios) explains how you can add CSS and JavaScript files to your project.

## Sample application

The demo below illustrates the transformation from video player to audio player.

* Demo: <http://cdn.theoplayer.com/demos/nus/audio-only.html>

## Resources

* [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios): How-to guide

---

# Customizing the UI: vertical volume slider

This article provides information regarding the implementation of a vertical volume slider instead of the default horizontal one.

**Please note that the following page is meant as a general example and need in all cases to be further personalized. The aim is to show you the process of implementing a vertical volume slider.**

**In other words, this is a first step in a work in progress as it does not yet account for color and aspect customization, as well as for a series of other small details.**

There is currently no ready-made option in THEOplayer for changing the orientation of the volume slider with a simple parameter. However, good results can be achieved with a [custom button](https://www.theoplayer.com/theoplayer-demo-adding-buttons-to-the-ui-with-custom-logic).

Notes about the current example:

* it has been successfully tested on major browsers (Chrome, Firefox, Safari) but no complete investigation has been performed. In Edge the slider still does not appear correctly and needs some more CSS tinkering.
* it has been successfully tested in several conditions (fullscreen and inline presentation mode and on different resolutions). However, it still needs testing in your specific implementation and use case.
* The aspect of the current volume slider differs depending on the browser: we encourage you to replace it with your favorite one and customize it
* The volume icon changes when the player is muted, but otherwise do not reflect volume increases/decreases.
* When the player is muted, the slider and the aria values do not go to 0 yet

---

# UI Skinning

THEOplayer allows you to style the player to your own needs. This guide will give an in-depth explanation of which colors can be changed and which parts of the player are affected. First it will explain how to change the skin of your player using 6 custom CSS classes. Afterwards, an overview follows explaining which parts of the players are affected by each class. If you don't already have an up-and-running version of THEOplayer, take a look at our [getting started guide](https://support.theoplayer.com/hc/en-us/articles/115001933305-Getting-Started-with-THEOplayer-2-X).

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | No       | No             | No             |

## CSS properties to override

THEOplayer provides multiple colors you can change to create your desired look-and-feel. These colors can be changed easily by including a custom CSS file which overrides some classes. An example of such a file is given below. There is also a demo page available where you can interactively change these colors and immediately see the effect [here](https://demo.theoplayer.com/ui-skinning). **NOTE:** The vjs-selected is needed to change the color of selected items in the menus.

```html
<style>
  .theo-primary-color,
  .vjs-selected {
    color: #ffc50f !important;
  }

  .theo-primary-background {
    color: #000000 !important;
    background-color: #ffc50f !important;
  }

  .theo-secondary-color {
    color: #ffffff !important;
  }

  .theo-secondary-background {
    color: #000000 !important;
    background-color: #ffffff !important;
  }

  .theo-tertiary-color {
    color: #000000 !important;
  }

  .theo-tertiary-background {
    color: #ffffff !important;
    background-color: #000000 !important;
  }
</style>
```

## Affected Components

This section discusses which parts of the components are affected by each CSS class.

When the player is added to the page, the only visible control is the **big-play-button**. The color of this component is equal to the *theoplayer-primary-color.*

When the big-play-button is clicked, the player starts playing the video. Two components are visible now: the **control-bar** and the **sharing button**.

The background color of the\*\* control bar\*\* can be styled using *theoplayer-tertiary-color*.

The **control bar** exists of: **control-bar-icons**, the **progress bar** and **menu**s.

* The color of the control bar icons can be set using `theoplayer-secondary-color`.

* The color of the progress bar can be set using `theoplayer-primary-color`.

* The color and background color of the header of the menu can be set using `theoplayer-primary-background`.

* The color and background color of the content of the menu can be set using `theoplayer-tertiary-background`.

* The color of the selected text of the menu can be set using `theoplayer-primary-color`.

## Summary

After this tutorial, you should be able to style your THEOplayer to your own needs. All CSS properties and the components they affect were discussed. A brief summary of these properties is given below:

| Color                | Affected components                             |
| -------------------- | ----------------------------------------------- |
| Primary color        | Big play button, progress bar, menu text        |
| Primary background   | Menu header                                     |
| Secondary color      | Control bar icons (including time and tooltips) |
| Secondary background | Social sharing close button                     |
| Tertiary color       | Control bar background                          |
| Tertiary background  | Menu content background                         |

## Mobile

Our mobile player uses the same class naming as our web version, so this is applicable to mobile as well. The CSS changes are to be gathered in a custom .CSS file, added to your project and then loaded into the PlayerConfiguration. More information on [How to add CSS or JavaScript files to an Android/iOS project](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/faq/how-to-add-css-or-javascript-files-to-android-ios) .

##### Legacy iOS/tvOS SDK (4.12.x)

```swift
let cssPath = Bundle.main.path(forResource: "style", ofType: "css")!
let theoConfig = THEOplayerConfiguration(cssPaths: [cssPath])
let theoplayer = THEOplayer(with: //frame, configuration: theoConfig)
```

##### Legacy Android SDK (4.12.x)

You can do this either by XML:

```java
<com.theoplayer.android.api.THEOplayerView
    android:id="@+id/theo_player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:defaultCss="true"
    app:cssPaths="path/to/style1.css"/>
```

Or directly in the player config in Java:

```java
THEOplayerConfig playerConfig = new THEOplayerConfig.Builder()
        .chromeless(false)
        .defaultCss(true)
        .cssPaths("path/to/style1.css","path/to/style2.css") // Path is relative to the location of the assets directory
        .build();
THEOplayerView tpv = new THEOplayerView(this, playerConfig);
```

It is also possible to change certain parts of the UI by editing the xml resources directly. E.g. colors.xml:

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="colorPrimary">#E361FF</color>
    <color name="colorPrimaryDark">#00574B</color>
    <color name="colorAccent">#D81B60</color>
</resources>
```

---

# How to detect the visibility of the default control bar

This question is typically asked by developers that want to insert a custom element that should

1. disappear when the default control bar disappears,
2. appear when the default control bar appears.

This article discusses three approaches that allow you to detect whether the control bar is visible.

1. [Using a Chromeless UI](#using-a-chromeless-ui)
2. [Using a MutationObserver](#using-a-mutationobserver)
3. [Using CSS](#using-css)

## Using a Chromeless UI

Instead of making the default THEOplayer UI fit your use cases, it might make sense to opt for a [Chromeless UI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ui/how-to-build-chromeless-ui.md). When you use a Chromeless UI, you have full control over the UI and UX, and you are not restricted to the complexities of our default UI.

## Using a MutationObserver

You can use a [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) to detect the visibility of the control bar.

Generally speaking, the default control bar is visible when the following scenario is true for your THEOplayer container's [`classList`](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList):

1. The `vjs-user-active` class is listed in the `classList`;
2. Or if the `vjs-paused` class is listed in the `classList`;
3. And the `vjs-has-started` class is listed in the `classList`.

The control bar is visible in the screenshot below because `vjs-paused` and `vjs-has-started` are classes of the THEOplayer container, as highlighted with the yellow rectangles.

![](/pr-932/assets/images/ui-control-bar-visibile-8e0fc2133328b496d115b9798f356b5c.png)

If we map that to JavaScript code:

```javascript
const theoplayerContainer = document.querySelector('.video-js');
const controlBarVisible =
  (theoplayerContainer.classList.contains('vjs-user-active') || theoplayerContainer.classList.contains('vjs-paused')) &&
  theoplayerContainer.classList.contains('vjs-has-started');
```

This approach is also valid for our default UI on the iOS and Android SDK, because their default UI can be customized through the same JavaScript (and CSS) as explained at

1. [iOS SDK Customization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/ios/ios-sdk-customization) for the iOS SDK
2. [Android Legacy (4.12.x) SDK Customization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/android/android-sdk-customization) for the Android SDK

It should be noted that this approach does not take the opacity of the control bar into account. The default control bar UI has a "fade in" and "fade out" effect. If you want to take this into account, you can capture its opacity through JavaScript when you have a reference to your control bar DOM element. The snippet below illustrates how you could poll the opacity every 100ms.

```javascript
setInterval(function () {
  const controlBar = document.querySelectorAll('.vjs-control-bar')[1];
  const controlBarOpacity = getComputedStyle(controlBar).opacity;
  console.log('control bar opacity', controlBarOpacity);
}, 100);
```

The next sub-sections discusses this approach in more detail per SDK.

### SDKs

| Web SDK | iOS SDK                                   | Android SDK                                 | tvOS SDK | Android TV SDK                              | Roku SDK | Chromecast SDK |
| ------- | ----------------------------------------- | ------------------------------------------- | -------- | ------------------------------------------- | -------- | -------------- |
| Yes     | Verified through CSS/JavaScript injection | Unverified through CSS/JavaScript injection | No       | Unverified through CSS/JavaScript injection | N/A      | N/A            |

#### Web SDK

The snippet below demonstrates how use the previously specified `controlBarVisible` variable in combination with a `MutationObserver`.

```javascript
const theoplayerContainer = document.querySelector('.video-js');
var controlBarObserver = new MutationObserver(function (event) {
  for (let i = 0; i < event.length; i++) {
    const el = event[i].target;
    const controlBarVisible =
      (el.classList.contains('vjs-user-active') || el.classList.contains('vjs-paused')) && el.classList.contains('vjs-has-started');
    const message = {
      controlBarVisible: controlBarVisible,
    };
    console.log(message);
  }
});
controlBarObserver.observe(theoplayerContainer, {
  attributes: true,
  attributeFilter: ['class'],
  childList: false,
  characterData: false,
});
```

You can try out this snippet at <https://detect-visibility-default-control-bar--thijslowette.repl.co/>, and verify the `{"controlBarVisible": true}` (or `{"controlBarVisible": false}`) logs in the developer console.

#### Legacy iOS/tvOS SDK (4.12.x)

You can leverage the approach of the Web SDK in your iOS project.

Firstly, you'll need to set up your project to support communication between your native code and JavaScript. This flow is described at [iOS SDK Customization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/ios/ios-sdk-customization).

This means that your JavaScript code could resemble the snippet below:

```javascript
const theoplayerContainer = document.querySelector('.video-js');
var controlBarObserver = new MutationObserver(function (event) {
  for (let i = 0; i < event.length; i++) {
    const el = event[i].target;
    const controlBarVisible =
      (el.classList.contains('vjs-user-active') || el.classList.contains('vjs-paused')) && el.classList.contains('vjs-has-started');
    const message = {
      controlBarVisible: controlBarVisible,
    };
    console.log(message);
    window.webkit.messageHandlers.myMessageName.postMessage(message);
  }
});
controlBarObserver.observe(theoplayerContainer, {
  attributes: true,
  attributeFilter: ['class'],
  childList: false,
  characterData: false,
});
```

Notice that we've only added the line below which posts message to your native code:

```javascript
window.webkit.messageHandlers.myMessageName.postMessage(message);
```

Next, you need to be able to intercept this message in your native code, as demonstrated by the snippet below.

```swift
func onMessageReceived(message : [String:Any]) {
    print(message)
    let isControlsVisible : Int = message["isControlsVisible"] as! Int
    if (isControlsVisible == 1) {
        print("controls are visible")
    } else {
        print("controls are not visible")
    }
}
theoplayer.addJavascriptMessageListener(name: "myMessageName", listener: onMessageReceived)
```

You can now use this `onMessageReceived` callback to detect the visibility in your iOS project through native code.

##### Legacy Android SDK (4.12.x)

Adopt the above iOS approach to Android. The communication between native Android and JavaScript is documented at [Android Legacy (4.12.x) SDK Customization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/android/android-sdk-customization).

## Using CSS

If you insert your custom elements through JavaScript, you can use CSS queries to align the visibility of your custom controls with the default control bar.

The snippet at <https://detect-visibility-default-control-bar--thijslowette.repl.co/> has a text ("Hello World!") that's only visible when the control bar is visible. We also leverage the `vjs-has-started`, `vjs-paused` and `vjs-user-active` classes mentioned in the previous approach.

---

# How to disable click to pause

When you use the default UI of THEOplayer you can pause (and resume) the video by clicking anywhere on the video (except in the control bar). You can confirm this behavior at <https://optiview.dolby.com/resources/demos/test-stream/>.

You might be interested in disabling this behavior because your functional requirements don't allow you to pause the video.

You can disable this default UX behavior through CSS on both the Web SDK, iOS SDK and Android SDK. The next section will focus on the Web SDK specifically. We'll also discuss some related APIs. To achieve the same on the iOS SDK you can implement the Web SDK approach through [iOS SDK customization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/ios/ios-sdk-customization). To achieve the same on the Android Legacy (4.12.x) SDK you can implement the Web SDK approach through [Android Legacy (4.12.x) SDK customization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v4/getting-started/sdks/android/android-sdk-customization).

## SDKs

| Web SDK | iOS SDK                                              | Android SDK                                          | tvOS SDK | Android TV SDK | Roku SDK | Chromecast SDK |
| ------- | ---------------------------------------------------- | ---------------------------------------------------- | -------- | -------------- | -------- | -------------- |
| Yes     | Yes, but unverified through CSS/JavaScript injection | Yes, but unverified through CSS/JavaScript injection | N/A      | N/A            | N/A      | N/A            |

### Web SDK

The following CSS snippet disables pause to click by no longer catching the pointer event.

```css
.video-js .vjs-tech {
  pointer-events: none;
}
```

The following JavaScript snippet automatically resumes a video when someone tries to pause it by leveraging the [`pause`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/PlayerEventMap#pause) event and the [`play()`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/classes/ChromelessPlayer#play) method.

```javascript
player.addEventListener('pause', () => {
  player.play();
});
```

The following CSS snippet hides the play and pause button.

```css
.video-js .vjs-play-control {
  display: none;
}
```

Interested in autoplay behavior? You might find ["How to combat autoplay policies"](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/how-to-combat-autoplay-policies.md) an interesting read.

---

# Introduction

This article explains how to configure the license at runtime.

A THEOplayer license is required to use the THEOplayer library for the desired domains. The licensing schema was previously based on the built-in license from the SDK build. THEOplayer now allows to update the license without rebuilding or re-integrating the player SDK.

This guide builds upon the basic player setup, make sure you read our [getting-started guides](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/introduction.md).

## SDKs

| Web SDK | Android SDK | iOS SDK | Android TV SDK | tvOS SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------------- | -------- | -------------- |
| Yes     | Yes         | Yes     | Yes            | Yes      | Yes            |

## Web and Chromecast SDK

THEOplayer is extended to allow configuring the license at runtime by just passing the license when a player is configured.

#### Passing the license through the PlayerConfiguration

This can be done in two ways:

* Pass a license string for the player by setting it on the `license` property:

```js
var player = new THEOplayer.Player(element, {
  // instantiates video player
  libraryLocation: '/path/to/your-theoplayer-folder/',
  license: 'your_license',
});
```

* Pass a valid URL that can be used to fetch the license for the player by setting it on the `licenseUrl` property:

```js
var player = new THEOplayer.Player(element, {
  // instantiates video player
  libraryLocation: '/path/to/your-theoplayer-folder/',
  licenseUrl: 'your_license_url',
});
```

If the player is configured with either `license` or `licenseUrl`, the player will first validate the `license` string. If license is either undefined or expired, the player will attempt to request the `licenseUrl` instead, if no `licenseUrl` is defined, then a default license Url will be used. If neither of these options is provided, the player will default to the built-in license in the SDK.

If no valid license can be found, the player will throw a license error.

## iOS and tvOS SDK

When building an iOS application, a player license can be defined in one of the following ways:

#### Passing the license through the PlayerConfiguration

Include the license parameter in the player configuration either by passing the license as a string or a license URL as shown below

```swift
// passing license as a string
let playerConfig = THEOplayerConfiguration(license: "your_license_here")
var theoplayer = THEOplayer(configuration: playerConfig)
```

```swift
// passing license as a URL
let playerConfig = THEOplayerConfiguration(licenseUrl: "your_licenseUrl_here")
var theoplayer = THEOplayer(configuration: playerConfig)
```

#### Passing the license through the Info.plist

Define the same `license` or a `licenseUrl` as a new key in the `Info.plist` file.

Our iOS SDK allows configuring the license via Info.plist keys, which could be either `THEOplayerLicense` or `THEOplayerLicenseUrl`.

* `THEOplayerLicense` must be a license string
* `THEOplayerLicenseUrl` must be a valid URL to a license server

The license defined in the player configuration has higher precedence than the license provided in the `Info.plist`. If neither of these are defined, then the built-in license will be used.

## Android SDK

When building an Android application, a player license can be defined in one of the following ways:

#### Passing the license through the PlayerConfiguration

Include the license parameter in the player configuration either by passing the license as a string or a license URL as described below

```java
// passing license as a string
public static THEOplayerConfig.Builder getTHEOplayerConfigBuilder() {
return new THEOplayerConfig.Builder()
    .license("your_license_here");
}
```

```java
// passing license as a URL
public static THEOplayerConfig.Builder getTHEOplayerConfigBuilder() {
return new THEOplayerConfig.Builder()
    .licenseUrl("your_licenseUrl_here");
}
```

#### Passing the license through the manifest

Define the same `license` or a `licenseUrl` as a new key in the app's manifest.

Our Android SDK allows configuring the license via metadata keys, which could be either `THEOPLAYER_LICENSE` or `THEOPLAYER_LICENSE_URL`.

* `THEOPLAYER_LICENSE` must be a license string
* `THEOPLAYER_LICENSE_URL` must be a valid URL to a license server

The license defined in the player configuration has higher precedence than the license provided in the app's manifest. If neither of these are defined, then the built-in license will be used.

## FAQ

### Why do I have to configure a license?

In order to provide THEOplayer insights if a stream can be played, it needs to have access to an active license. You can choose to either configure this license, or configure a URL where this license can be retrieved. If you are using an old SDK, it is also possible to have a license configured by default in the THEOplayer library itself. We recommend everyone to configure an active license or a license URL.

### How do I avoid introducing any dependencies on THEOplayer servers?

There are two important aspects which can introduce a dependency on THEOplayer servers:

##### 1. Loading a THEOplayer SDK from the THEOplayer CDN

This issue is only relevant for the THEOplayer HTML5 / Tizen / webOS SDK. In order to avoid this dependency, we recommend to self-host your THEOplayer SDK. The easiest approach is to load the player through NPM, or download the player SDK as a zip-file from the developer portal. More information on how to self-host your player can be found [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/self-hosting-theoplayer.md).

##### 2. Loading a THEOplayer license from the THEOplayer license system

In order to avoid this dependency, it is important to always keep your license up to date, either by configuring an updated license or by configuring your own license URL. When your THEOplayer license expires, a new player instance will actively check against THEOplayer’s license system if there is an updated license available. This system should however only serve as a fallback for applications which cannot be updated.

### Should I pass a license string or a license URL?

We recommend our customers to use the license string whenever possible.

In special cases it is possible to use the license URL instead. Use-cases include contractual or legal (f.i privacy) requirements. For more information, please contact <support@theoplayer.com>.

If the player is configured both with a license string and license URL, it will first try to validate the license string. If the license string is either not configured or expired, the player will attempt to request the license URL instead. If no license URL is defined, then a default license URL will be used. If neither is defined, the player will default to the built-in license in the SDK. If no valid license can be found, the player will throw a license error.

### Should I update my application upon license renewal?

Yes. After renewing your license, you should make sure to include the new THEOplayer license in your next app update.

### What happens if I don’t timely update the license in my application?

The player will attempt to update the license up to 72 hours before expiration. For this, the player will request a new license either from the configured license URL or as a fallback (when there is no license URL configured) from `validate.theoplayer.com`. Either way, if the request is successful, the player will store the license locally. We highly recommend you to self-host the license using the license URL in the player configuration.

For self-hosting, the license file with the latest license string for your application should be hosted. The full URL to this file should then be configured as the license URL in the player configuration.

### Will I still be able to play offline content with my THEOplayer SDK if my license expires?

When your license expires, THEOplayer will attempt to load an updated license. If an updated license is available, offline playback will still function. If no valid license is available, and no license server can be reached (due to the client being offline), the player will throw an error and stop playback. For this reason, it is important to always keep your license up to date.

### What should I do to protect my license?

The THEOplayer license you get from THEOportal is already an obfuscated string. If you want to protect your license, you need to make sure to configure your [page and source domains](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/faq/page-and-source-domains.md) to guarantee that your license string cannot be used anywhere other than the specified pages and/or with those source domains.

---

# What are the Uplynk challenges

The purpose of this article is to group common challenges application developers might encounter when using [Uplynk](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/introduction.md) (formerly known as Verizon Media, Edgecast or Edgio) as the back-end.

1. [Why does Chromecast or AirPlay not work?](#why-does-chromecast-or-airplay-not-work)
2. [Why aren't all video qualities showing up?](#why-arent-all-video-qualities-showing-up)
3. [What should I know before tokenizing my stream?](#what-should-i-know-before-tokenizing-my-stream)

## Why does Chromecast or AirPlay not work?

If you've [correctly enabled Chromecast](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/cast/chromecast/enable-chromecast-on-the-sender.md) or AirPlay, but you are not getting any playback on your Chromecast or AirPlay device, then a likely cause is your [tokenization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/preplay.md#using-tokens) approach.

1/ When you tokenize a URL, you are also specifying an expiration date. It is possible that your expiration date has passed when you initiate the casting session. Your stream will no longer be valid when this is the case, and result in unsuccessful casting.

The solution? Use an expiration date that is valid for a longer time.

2/ An Uplynk token will be attached to one IP address when it's invoked for the first time (i.e. request to the Preplay URL with the token as a query parameter). This could cause problems when either your sender device (i.e. iOS app, Android app, browser) or receiver device (i.e. Chromecast device) uses an iPv6 address, because those addresses are unique. (Meaning: the token could be invalid for your IPv6 receiver device because it was already attached to your different IPv4 sender device.)

The solution?

1. You can disable IP address checking by adding `pp2ip=0` to your token (and Preplay parameters).
2. You can implement a [custom Chromecast receiver app](https://github.com/THEOplayer/samples-google-cast-v3-receiver) that generates its own unique token. (This however doesn't address the issue on AirPlay, and also gives rise to challenges related to building a custom Chromecast app.)
3. You can disable tokenization (if it's not a requirement).

## Why aren't all video qualities showing up?

If you notice that THEOplayer doesn't expose all your Uplynk MPEG-DASH video qualities, then the likely culprit is not aggregating the different `AdaptationSet`s as part of Uplynk's multi-key approach.

The solution?

Add `singlevideolicense=1` to your Preplay parameters and/or token. Doing so will group all qualities to one `AdaptationSet` with one key.

## What should I know before tokenizing my stream?

Refer to [Preplay - tokenization](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/preplay.md#using-tokens).

---

# Knowledge base

Want to know more about topics in the video industry? We have a small list of articles to provide you some basic knowledge.

## [💰Advertisements](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/introduction.md)

[3 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/introduction.md)

## [🔐Content protection](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/content-protection/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/content-protection/introduction.md)

## [▶️Playback](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/introduction.md)

[7 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/introduction.md)

## [🎥Streaming](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/streaming/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/streaming/introduction.md)

## [🔗CORS](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/cors/introduction.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/cors/introduction.md)

## [🏷️Metadata](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/metadata/introduction.md)

[1 item](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/metadata/introduction.md)

---

# Advertisements

This section allows you to learn everything about advertisements!

## [📄️Advertising User Guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/user-guide.md)

[THEOplayer allows you to configure different aspects of its advertising environment. By following this guide you will learn about:](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/user-guide.md)

## [📄️Server Side Ad Insertion](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/server-side-ad-insertion.md)

[If you are a content distributor, you know how difficult it is to properly monetize content. While content acquisition can be expensive, more and more users are looking for ways to access premium content for free.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/server-side-ad-insertion.md)

## [📄️Support matrix](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/support-matrix.md)

[THEOplayer currently supports two ad implementations:](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/support-matrix.md)

---

# Advertising User Guide

THEOplayer allows you to configure different aspects of its advertising environment. By following this guide you will learn about:

* The advertisement feature in THEOplayer, with a focus on a few key concepts

* The ad integrations in THEOplayer

* Ad configuration and ad block detection

* Related resources, including

  * How-to guides related to specific integrations
  * The reference API
  * Other ad-related how-to guides, information pages, blog articles, etc.

How to configure ads, code snippets and specific support and use for the various integrations are found on the guides dedicated to the specific integrations.

## Feature Overview

### An overview of THEOplayer's Advertisement tools

THEOplayer offers an array of features that allow you to take total control over your online video content advertisement environment.

To facilitate integration between content providers and ad servers, we implement the IAB Video Suite, a set of technical specifications that are widely used by many participants in the online video advertisement industry. More specifically, we implement the following IAB specifications: *Digital Video Ad Serving Template* (**VAST**), *Digital Video Multiple Ad Playlist* (**VMAP**) and *Digital Video Player-Ad Interface Definition* (**VPAID**). You will have to get acquainted with these specifications if you want to optimize your advertisement revenue.

On top of the IAB suite, THEOplayer comes with additional tools to improve advertisement efficiency, like **Adblock Detection**.

#### Digital Video Ad Serving Template (VAST)

The Digital Video Ad Serving Template (VAST) specification is a description for video ads that standardizes communication requirements between video players and ad server. It gives instructions to the video player on how ads should be handled and displayed. It can define how and how long the ad should be displayed, if and when it can be skipped and how to give tracking information to the ad servers. VAST also specifies ad pods. These are groups of advertisements which should be played back-to-back.

THEOplayer offers support for the delivery of video ads with VAST 4.0. Support is available for linear ads (pre-rolls, mid-rolls, post-rolls and ad breaks), non-linear ads (overlay banners) and companion banners, all of which are discussed in the next section.

#### Digital Video Multiple Ad Playlist (VMAP)

With Digital Video Multiple Ad Playlist (VMAP), video content owners can exercise control over the ad inventory displayed with their content when they cannot control the video player, to capitalize on advertising while maintaining the integrity of their program content. VMAP enables the content owner to define the ad breaks within their content, including the timing for each break, how many breaks are available, what type of ads and how many are allowed in each break. It is important to note however that VMAP was mainly designed with Video on demand (VOD) in mind.

#### Digital Video Player-Ad Interface Definition (VPAID)

VPAID establishes a common communication protocol between video players and ad units that allows a single “executable ad” (one that requires software logic to be executed as part of ad playback) to be displayed in-stream with the publisher’s video content. It allows the ad and the player to expect and rely upon a common set of functionalities. The significance is that advertisers using VPAID ads can provide rich ad experiences for viewers and collect ad playback and interaction details that are just as rich as the ad experience. With the adoption of VPAID, advertisers have more control over the display experience in their video campaigns. VPAID ads can easily be integrated on top of VAST manifests.

#### Adblock detection

Ad blockers or filters (such as the AdBlock plugin for browsers) remove or alter ads on webpages such that they become less obtrusive for the user. They can be a big threat to websites that get their revenue from video advertisements as they prevent an ad from being played. THEOplayer has built-in features that can detect ad blockers and act accordingly.

### An overview of THEOplayer's different ad types

THEOplayer has support for **Linear**, **Non-linear** and **Companion** VAST and VPAID ads, as well as for VMAP ads.

THEOplayer currently supports several ad playback implementations:

**Client-side ad insertion (CSAI)**

1. THEOplayer (default)
2. Google IMA
3. SpotX
4. FreeWheel

**Server-side ad insertion (SSAI)**

1. Google DAI
2. Yospace
3. Verizon Media
4. MediaTailor

Below you can find the support matrix for different types of ads:

|            | VAST | VMAP | VPAID |
| ---------- | ---- | ---- | ----- |
| THEOplayer | Yes  | Yes  | No    |
| Google IMA | Yes  | Yes  | Yes   |
| SpotX      | Yes  | Yes  | Yes   |
| FreeWheel  | Yes  | No   | Yes   |
| Google DAI | No   | No   | No    |
| Yospace    | Yes  | Yes  | No    |

#### Linear Ads

Linear ads are video ads that play before, during or after the content video. THEOplayer allows you to specify an optional offset to make a linear ad play at a given time during or after the video. Linear ads can be further configured by specifying how long the ad must be watched before the user can skip it. Linear ads can be interactive (VPAID) or can simply have a click-through that directs users to a webpage on a different screen.

#### Non-linear Ads (overlays)

Non-linear ads are shown on top of the video as an overlay during playback. The user can interact with these ads by clicking them, which will, for example, redirect them to a page with more information about the product being advertised. Non-linear ads can also be closed by users.

#### Companion Ads

Companion banners are ads surrounding the video player that, in comparison with linear and non-linear ads, do not directly interfere with a user’s viewing experience. THEOplayer allows you to choose where the companion ads should be displayed on your website so it better integrates with the layout of the page.

## Ad Integrations

Advertisements are described through the AdDescription object in the API. Beside defining a source, you can also define the integration property.

### Client-Side Ad Insertion (CSAI)

Client-Side Ad Insertion (CSAI) is the traditional method of inserting advertisements into an online video. Through this method, advertisements and video are served separately and integrated into the video player on the client side: this approach pauses your content, loads a video advertisement, and then resumes your video when the ad is finished. The benefit of CSAI is that it is easy to implement and integrate. As it has direct contact with the ad server, it also allows advertisers to better track metrics. On the client side, the video player is responsible for loading all necessary files (e.g. VAST, videos, banners), managing the timing of when the advertisements should be played, interrupting playback when needed and ensuring that switching content and error handling works smoothly.

THEOplayer provides several integrations to achieve CSAI, including its own integration:

#### THEOplayer

The THEOplayer ad system is selected with the value 'theo'. As this ad system is the default one, you do not have to indicate this preference, and you can omit the integration property altogether. More information can be found at:

* [Ads Reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Ad)

* [How to set up VAST and VMAP ads](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/how-to-set-up-vast-and-vmap.md): this how-to guide contains information regarding this integration, including how to use this integration, requirements (if any) and code samples.

#### Google IMA

Set the `integration` property to `'google-ima'` to use the Google IMA integration. More information can be found at:

* [Reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/IMAAdDescription)
* [Google IMA](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/google-ima.md): this how-to guide contains information regarding this integration, including how to use this integration, requirements (if any) and code samples.

#### SpotX

Set the `integration property` to `'spotx'` to configure SpotX ads. More information can be found at:

* [Reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/SpotXAdDescription)
* [SpotX](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/spotx.md): this how-to guide contains more information regarding this integration, including how to use this integration, requirements (if any) and code samples.

#### FreeWheel

Set the `integration` property to `'freewheel'` to configure FreeWheel ads. Please note that, in this case, the adSource properties are different from those for other ad integrations (e.g.: theo integration). More information can be found at:

* [Reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/FreeWheelAdDescription)
* [FreeWheel](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/freewheel.md): this how-to guide contains more information regarding this integration, including how to use this integration, requirements (if any) and code samples.

### Server Side Ad Insertion (SSAI)

With Server-Side Ad Insertion (SSAI), advertising content is injected into a video stream: the broadcaster indicates when advertisements may be inserted by providing cues (hints) in the stream. The content is then forwarded to an ad insertion server, which replaces the dummy content with actual advertisements. That way, the advertisements are part of the stream. This creates an experience much like traditional broadcasting. SSAI opens the door to many possibilities. For example, inserted advertisement content can be personalized down to a single-user level, for improved advertisement efficiency. As a client can no longer make the distinction between content and advertisement video chunks, their download calls cannot be blocked by ad blockers. This increases advertisement revenue compared to traditional client-side ads.

THEOplayer pre-integrates with first-class Server-Side Ad Insertion(SSAI) providers, including Google DAI and Yospace.

#### Google Dynamic Ad Insertion (DAI)

To use the Google DAI integration you have to set the `integration` key to `'google-dai'`.

* [Reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/GoogleDAIConfiguration)

#### Yospace

To use the Yospace integration you have to set the `integration` key to `'yospace'`.

* [Reference API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Yospace)
* [Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/yospace.md): this how-to guide contains more information regarding this integration, including how to use this integration, requirements (if any) and code samples.

#### Verizon Media

To use the Verizon Media integration you have to set the `integration` key to `'verizon-media'`.

You can refer to [our section on Verizon Media](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/ads.md) to learn more about SSAI with Verizon Media.

#### MediaTailor

To use the MediaTailor integration you have to set the `integration` key to `'mediatailor'`.

You can refer to [our MediaTailor guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/mediatailor.md) to learn more about SSAI with MediaTailor.

## Ad Configuration

### Basic Ad Configuration

As we discussed in [An overview of THEOplayer's Advertisement tools](#overview-advertisement-tools), VAST gives instructions to the video player on how ads should be handled and displayed. This guide does not go into the details of how to create a VAST file. We only refer to the VAST specification, a good starting point if you want to learn the skill.

Here, we will discuss how you can add existing VAST ads to THEOplayer - examples for all the features explained in this section can be found in the how-to guides linked below.

#### Adding and configuring VAST ads

The player supports VAST by specifying a URL parameter to the VAST description in the player configuration. The player will automatically load this advertisement description and act accordingly.

| Attribute | Description                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------- |
| `sources` | This mandatory parameter allows you to specify the location of the VAST advertisement XML file. |

**Specifying an offset for your ad**

You can specify an optional offset parameter that indicates at what time the ad should be displayed before, during or after the video. This parameter works for linear as well as non-linear and companion ads and has the following specification:

* `timeOffset`: This optional parameter allows you to determine the placement of the specified ad. Five different formats are allowed:

  * **seconds**: a numeric value representing the number of seconds into the video the ad should play.
  * **time**: in the format `hh:mm:ss.mmm` (`.mmm` is optional), for example `'00:35:30.000'`.
  * **percentage**: in the format `n%`, where n is a value from 0-100, for example `50%`.
  * **start/end**: The value `'start'` signifies that the video is a pre-roll and should be played before the actual video can be watched. The value `'end'` signifies that the video is a post-roll and should be played after the original video.

If you are using a VMAP ad, this property should not be used, as the VMAP format specifies its own time offset for breaks. Using this property with VMAP may cause no ad breaks or incorrect placement of ad breaks.

**Configuring your ad to be skippable**

You can allow an ad to be skipped by adding a skip parameter in the configuration. The skip parameter describes how long - in seconds - the ad must be watched before the user can skip it. The parameter is optional: if you do not define one, THEOplayer will use the information specified by the VAST file itself.

*NOTE: ad-skipping is currently not supported on some iOS devices for google IMA.*

| Attribute    | Description                                                                                                                                                                                                                      |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `skipOffset` | This optional parameter allows you to override the amount of seconds a viewer must watch the advertisement before it can be skipped. A negative value of -1 disables ad-skipping (even if the VAST file specifies a skip delay). |

**Choosing where to place companion ads**

THEOplayer allows you to render companion ads where you want. This way, you can optimally integrate ads with the layout of your page. When a companion ad is in the VAST/VMAP/VPAID, you can detect them through an event listener. These elements can be added to the page where they fit best.

#### Control the ads shown alongside your content with VMAP

The VMAP protocol enriches the VAST data with the timing of the advertisements. Again, we will not explain how you should create VMAP files, you can read more on that in the [VMAP specification](https://www.iab.com/guidelines/digital-video-multiple-ad-playlist-vmap-1-0-1/). Configuration of the skipOffset delay can be done similarly as in the VAST configuration, discussed in [Adding and configuring VAST ads](#adding-configuring-vast-ads). The following table summarizes the possibilities and effects of each option.

| Attribute    | Description                                                                                                                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sources`    | This parameter specifies the location of the VMAP advertisement XML file.                                                                                                                                                            |
| `skipOffset` | This optional parameter allows overriding the number of seconds a viewer must watch a pre-roll ad before it can be skipped. A negative value of -1 disables ad-skipping. This will affect all linear ads specified in the VMAP file. |

#### Adding and configuring interactive VPAID ads

Our player provides VPAID 2.0 support via our Google IMA integration. This version of the specification is designed to further facilitate VPAID integration with VAST. This means that you can embed rich VPAID ads in your VAST manifests and add those manifests to our player, as we have shown in [Adding and configuring VAST ads](#adding-configuring-vast-ads).

### Advanced Ad Configuration

#### Dynamic Ad Scheduling

In [Basic Ad Configuration](#basic-ad-config), we learned how to statically add ads to THEOplayer on startup by specifying them in the configuration object. However, several interesting use cases exist that require on the fly ad injection, for example when VAST files should be added by a script provided by an external ad server.

To dynamically add advertisements, you should use the [`player.ads.schedule(AdDescription)`](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Ads#schedule) function which will add the given ad file as if it were specified in the initial configuration. The AdDescription - which you will pass as a parameter to the function - is the same object as previously discussed in [Basic Ad Configuration](#basic-ad-config).

NOTE: Please note that when adding a pre-roll when the original video is already playing (for example because of autoplay), the pre-roll cannot start playing. An advertisement with an offset of '0%' will always be able to play.

## Ad Block Detection

THEOplayer offers the option to block the player when an adblocker is detected. This can be achieved by setting blockOnAdBlock in the configuration.ads object to true. The player will display a message saying it has detected an ad blocker and that the user will need to turn it off in order to watch the video. A more in-depth code-example can be found at <https://demo.theoplayer.com/adblock-detection>.

The default message that is shown when ad-block is detected is depicted below.

![Adblock detection](/pr-932/assets/images/adblock-detected-8348d073be3013c7944848c140c8a7ef.png)

## Demos and sample applications

* [Google DAI Demo Page](https://www.theoplayer.com/theoplayer-demo-google-dai)
* [SSAI Demo Page](https://demo.theoplayer.com/ssai)
* [THEOplayer: Advertisements Tester (VAST, VPAID, VMAP)](https://www.theoplayer.com/theoplayer-demo-advertisement-tester-vpaid-vast-vmap)
* [Adblock detection](https://demo.theoplayer.com/adblock-detection)

---

# Server Side Ad Insertion

If you are a content distributor, you know how difficult it is to properly monetize content. While content acquisition can be expensive, more and more users are looking for ways to access premium content for free.

When content creators and providers offer easy access to content with advertisements, users will often go one step further and install an ad-blocker which cancels out any client-side advertising. As a result the monetization of the content is offset and providers will no longer be able to cover costs.

Luckily, the design of adaptive streaming protocols allows for a solution.

## Server-Side Ad Insertion

An HLS or MPEG-DASH stream consists of a long chain of separate segments. Server-Side Ad Insertion (SSAI) is a simple concept wherein advertising content is injected into this stream of segments. This creates an experience much like traditional broadcasting, with the additional benefit that the injected advertising content can be personalized down to a single-user level. As a client can no longer make the distinction between content and advertisement download call, these calls cannot be blocked by ad blockers.

A fully-fledged SSAI system will also contain obfuscation and transcoding services that together will make your content more secure and more stable in playback. As a result, SSAI creates a solution very much like a traditional broadcasting experience. Additionally, a number of modern information and advertisement technologies is leveraged to further increase its efficiency in monetizing content.

### Dynamic Ad Insertion

While often used as an interchangeable term for Server-Side Ad Injection, Dynamic Ad Insertion (DAI) actually refers to the ability to dynamically customize the advertising content that is stitched into the stream. While people around the world could be watching the same sports event, it makes very little sense to show each viewer the same advertisement. Targeted ads are much more powerful and Dynamic Ad Insertion allows you to do exactly that.

On top of that, Dynamic Ad Insertion allows you to update advertisements. If someone's looking at a live show from four years ago, advertising a four-year-old promotion on cat food at your favorite supermarket chain would not be very effective.

### Live vs Video on demand

When we look at live and video on demand, leveraging the full power of SSAI requires us to look at the differences between the use cases.

Starting from a video on demand stream without advertisements, SSAI can easily stitch in relevant advertisements for the user that requested the video stream. Since it is a video on demand, the length of the manifest can change to accommodate any ad that is injected.

Using SSAI in live streams poses a slightly more difficult use case, in the sense that simply injecting an ad in between segments in a live stream would lengthen the manifest. As a result, for a live stream to be used with SSAI, ad breaks will need to be defined, so that the server knows where it is supposed to stitch in the ads. On top of that the length of ads and ad breaks will need to be matched, whereas for a VOD this is not necessary.

The final use case to look at is a recorded live stream that is made available as a video on demand. At first glance it might look like the ad injection process would be the same as the previous use case. However, matching the ad and ad break length is not a hard requirement, as the length of the manifest is not as strict in the VOD use case.

### THEOplayer and SSAI

There are a number of solutions in the market that provide SSAI and DAI services. As a market leader in video playback, THEOplayer has chosen to integrate with a number of different partners in the market of SSAI and DAI. These integrations provide a world-class solution with modern advertisement mechanics that allow you to monetize your content successfully.

---

# Support matrix

THEOplayer currently supports two ad implementations:

* an in-house advertisement implementation
* an implementation of Google IMA which is [DFP certified](https://support.google.com/admanager/answer/186110?hl=en)

A more in-depth advertisement guide can be found [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/advertisement/user-guide.md)

| Ad Standard             | Type                 | Supported through |
| ----------------------- | -------------------- | ----------------- |
| **VAST 2.0**            | Linear               | 1.2               |
|                         | Non-linear (Overlay) | 1.2               |
|                         | Companion            | 1.2               |
|                         | Wrapper              | 1.2               |
| **VAST 3.0**            | Linear               | 1.2               |
|                         | Non-linear (Overlay) | 1.2               |
|                         | Companion            | 1.2               |
|                         | Wrapper              | 1.2               |
|                         | Ad Pod               | 1.2               |
|                         | Skippable linear     | 1.2               |
| **VAST 4.0**            | Linear               | 1.2               |
|                         | Non-linear (Overlay) | 1.2               |
|                         | Companion            | 1.2               |
|                         | Wrapper              | 1.2               |
|                         | Ad Pod               | 1.2               |
|                         | Skippable linear     | 1.2               |
| **VPAID 2.0 (HTML+JS)** | Linear               | 2                 |
|                         | Non-linear (Overlay) | 2                 |
|                         | Companion            | N/A               |
|                         | Wrapper              | N/A               |
|                         | Ad Pod               | N/A               |
|                         | Skippable linear     | 2                 |
| **VMAP 1.0.1**          |                      | 2                 |

*Notes:*

* Support for VPAID 1.0 (Flash) was dropped by Google IMA in May 2018.
* THEOplayer also supports [SpotX](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/spotx.md).

---

# Content protection

Get ready to learn everything about content protection.

## [📄️Digital Rights Management (DRM) Systems](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/content-protection/drm-systems.md)

[Intellectual property theft has a huge economic impact. The digital media sector is one of its biggest victims with annual losses running into billions of dollars.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/content-protection/drm-systems.md)

## [📄️AES-128 Encryption](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/content-protection/aes-128-encryption.md)

[The Apple HTTP Live Streaming (HLS) specification uses AES-128 encryption to provide content protection. The Advanced Encryption Standard (AES) is a specification for the encryption of electronic data established by the U.S. National Institute of Standards and Technology. In case of HLS with AES-128, individual media segments get encrypted with a 16-octet key. Most modern streaming servers have simple configuration options for enabling AES-128 on HLS streams.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/content-protection/aes-128-encryption.md)

---

# Digital Rights Management (DRM) Systems

Intellectual property theft has a huge economic impact. The digital media sector is one of its biggest victims with annual losses running into billions of dollars.

Due to its nature and distribution, digital media is one of the most difficult intellectual properties to secure. This is especially the case when it comes to securing digital media without impacting the user experience.

In the online streaming market, security is achieved through Digital Rights Management (DRM) Systems. These technologies use a combination of Access Control schemes and encryption to make content transparently available to authorized users, while restricting access for everyone else.

## How does it work?

DRM in HTML5 streaming is achieved by encrypting content with AES-128 Encryption. Subsequently, decryption keys are distributed through a DRM specific licensing server. Which DRM system needs to be used depends on the device and browser that is being used.

The major advantage of DRM systems over standard AES-128 Encryption as it is available in HLS streaming is the ability to pass encrypted content to the browser. For more information on AES-128 Encryption in HLS, you can read our article [here](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/content-protection/aes-128-encryption.md).

## MPEG-DASH vs. HLS

HLS was one of the first and is currently most widely used HTML5 adaptive streaming protocol. The specifications for HLS are proprietary to Apple, but are published on the IETF website as the [Pantos HTTP Live Streaming Specification](https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis). The protocol is regularly updated and enhanced by Apple at a steady pace of a new update every six months.

MPEG-DASH on the other hand is backed by an industry forum with a large number of members in the online streaming market.

As you can see from the infographic above, when using a DRM system, encrypted content is passed to the browser. To be able to play the content, the browser needs to have access to a Content Decryption Module (CDM) that can handle the DRM system's security policies.

Currently, each device and browser combination provides support for just one DRM technology. Apple's FairPlay is the DRM technology to use on Apple's Safari browser and in iOS apps, while Microsoft PlayReady is available on Edge and Internet Explorer and Google's Widevine DRM is available in Firefox and Chromium based browsers such as Google Chrome, Opera and Vivaldi.

| Operating System      | Browser              | DRM Content Protection           |
| --------------------- | -------------------- | -------------------------------- |
| **Windows**           | Edge                 | MPEG-DASH + PlayReady (in HTML5) |
|                       | Internet Explorer 11 | MPEG-DASH + PlayReady (in HTML5) |
|                       | Chrome               | MPEG-DASH + Widevine (in HTML5)  |
|                       | Firefox              | MPEG-DASH + Widevine (in HTML5)  |
|                       | Opera                | MPEG-DASH + Widevine (in HTML5)  |
|                       | Vivaldi              | MPEG-DASH + Widevine (in HTML5)  |
| **OS X**              | Safari               | HLS + FairPlay (in HTML5)        |
|                       | Chrome               | MPEG-DASH + Widevine (in HTML5)  |
|                       | Firefox              | MPEG-DASH + Widevine (in HTML5)  |
|                       | Opera                | MPEG-DASH + Widevine (in HTML5)  |
|                       | Vivaldi              | MPEG-DASH + Widevine (in HTML5)  |
| **Linux**             | Chrome               | MPEG-DASH + Widevine (in HTML5)  |
|                       | Firefox              | MPEG-DASH + Widevine (in HTML5)  |
|                       | Opera                | MPEG-DASH + Widevine (in HTML5)  |
| **Android**           | Chrome for Android   | MPEG-DASH + Widevine (in HTML5)  |
| **Windows Phone 8.1** | Internet Explorer    | MPEG-DASH + PlayReady (in HTML5) |

## Common Encryption

This divided landscape of DRM technologies, browsers and platforms could potentially mean that a content provider needs a lot of resources available to provide full streaming support for all these platforms.

This is however not the case in practice. The MPEG Common Encryption standards defines metadata specific for the container formats in which content can be transported. That way, the player and browser know exactly which encryption schemes were used and how specific parts of the stream were encrypted. As long as the different DRM schemes adhere to these specifications, they can be used in combination with the same stream. This allows to reduce the resources required for the streaming provider. In the end, this currently comes down to setting up an HLS stream with FairPlay and an MPEG-DASH stream with PlayReady and Widevine.

## Licensing Servers

A crucial element in the DRM workflow is the DRM licensing server. These servers control the access that users have to your content. Providing various features to fine-tune license types (subscriptions, rentals, purchases, ...) or create user profiles with fine-grained access control (e.g.: premium customers with access to content in higher quality).

This creates two drawbacks at the moment.

* To be able to support your entire viewer base, most content providers will have to use more than one licensing server.
* Available features between different DRMs and licensing servers differs, making management of the user base more complex.

## Multi-DRM Solutions

Leveraging Common Encryption and providing support for all common DRM systems on the market, multi-DRM solutions allow a content provider to reach their entire user base with a single point-of-access for their management backend. Multi-DRM solutions make it very easy to protect content with studio-approved DRM.

THEOplayer has proven integrations with a number of vendors in the multi-DRM market, as well as Widevine, PlayReady and FairPlay individually.

---

# AES-128 Encryption

The Apple [HTTP Live Streaming (HLS)](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/streaming/http-live-streaming.md) specification uses AES-128 encryption to provide content protection. The Advanced Encryption Standard (AES) is a specification for the encryption of electronic data established by the U.S. National Institute of Standards and Technology. In case of HLS with AES-128, individual media segments get encrypted with a 16-octet key. Most modern streaming servers have simple configuration options for enabling AES-128 on HLS streams.

## Content Protection in THEOplayer

THEOplayer supports decryption and playback of HLS streams with AES-128 content protection out of the box, without extra configuration in the player. In order to play AES-128 content protected streams, the decryption key and an optional initialization vector have to be provided in the manifest. When configured correctly, THEOplayer allows playback of AES-128 content protected streams on all supported devices in real time. It allows for the usage of a single key, or a rotating key.

In order to make sure THEOplayer can decrypt the stream, make sure the following information is correct in the manifest:

* If a decryption key is specified, it is relevant for all following media segments. This allows you to specify a key for each segment or one for the whole manifest
* The decryption key can be hosted externally (by referencing the key URL) or embedded in the manifest file (by key value)

## Cross Origin Resource Sharing (CORS)

Make sure CORS is enabled both on the **media segments** that have to be downloaded, decrypted and played as well as the **decryption key** if referenced externally in the manifest file.

## Examples

### THEOplayer example

There’s a demo of THEOplayer playing an AES-128 Content Protected stream at <https://demo.theoplayer.com/drm-aes-protection-128-encryption>.

### Video on Demand stream with multiple encryption keys

An example manifest of a 44-second long VOD stream protected with AES-128 content protection - each media segment has its own key.

```text
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-ALLOWCACHE:1
#EXT-X-KEY:METHOD=AES-128,URI="segment-00000.key"
#EXTINF:4.458667,
segment-00000.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00001.key"
#EXTINF:4.010000,
segment-00001.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00002.key"
#EXTINF:4.468667,
segment-00002.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00003.key"
#EXTINF:3.893000,
segment-00003.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00004.key"
#EXTINF:4.007333,
segment-00004.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00005.key"
#EXTINF:3.292667,
segment-00005.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00006.key"
#EXTINF:4.011667,
segment-00006.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00007.key"
#EXTINF:4.001000,
segment-00007.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00008.key"
#EXTINF:4.011667,
segment-00008.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00009.key"
#EXTINF:4.001000,
segment-00009.ts.enc
#EXT-X-KEY:METHOD=AES-128,URI="segment-00010.key"
#EXTINF:4.011667,
segment-00010.ts.enc
#EXT-X-TARGETDURATION:5
#EXT-X-ENDLIST
```

---

# Playback

This section will update you about the world of playback.

## [📄️What are chapter markers?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/what-are-chapter-markers.md)

[Dividing a video into separate parts helps your audience navigate through your content. While hovering the seek bar, THEOplayer's chapter markers and titles will help your users identify different parts of your content more easily. It also allows them to revisit their favorite parts of your videos.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/what-are-chapter-markers.md)

## [📄️What are the benefits of preview thumbnails?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/what-are-the-benefits-of-preview-thumbnails.md)

[Preview thumbnails improve the user experience by allowing the user to scan the video for specific content. They also have a business impact determined by the bandwidth optimization connected to users that can decide and quickly jump to the content they are interested in.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/what-are-the-benefits-of-preview-thumbnails.md)

## [📄️Frame Accurate Seeking](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/frame-accurate-seeking.md)

[This guide will explain how you can achieve frame-accurate seeking with THEOplayer. It will explain how to calculate the current frame of your player, how to seek to a specific frame and known limitations with this approach.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/frame-accurate-seeking.md)

## [📄️Program Date Time](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/program-date-time.md)

[THEOplayer has support for associating media segments with an absolute date and time. This can be useful when you want to synchronize video playback with displaying other relevant information about the video stream.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/program-date-time.md)

## [📄️Basic guide to Web Audio API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/basic-guide-web-audio-api.md)

[THEOplayer provides a Web Audio API, which allows you to do some quite nifty stuff with the player's audio output. If you are unfamiliar with the ideas behind Web Audio API, Mozilla has an excellent intro to the basic ideas you need to know about here. This guide will help you set up a demo just like the one we have in our Demo Zone.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/basic-guide-web-audio-api.md)

## [📄️Video Clipping](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/video-clipping.md)

[THEOplayer supports playing only a selected part of a video-on-demand stream, rather than playing it from start to finish. This can be used for example to watch a single game-changing event from a sports match, highlight an important part of a long video presentation, or skip straight to the best part of a song's video clip.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/video-clipping.md)

## [💬Subtitles and closed captions](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/subtitles-and-closed-captions/introduction.md)

[2 items](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/subtitles-and-closed-captions/introduction.md)

---

# What are chapter markers?

Dividing a video into separate parts helps your audience navigate through your content. While hovering the seek bar, THEOplayer's chapter markers and titles will help your users identify different parts of your content more easily. It also allows them to revisit their favorite parts of your videos.

Chapter markers are cue points that allow you to divide your video content into segments called chapters. Chapters are used to convey metadata (e.g.: a title for each video segment) and to help the viewer seek to the desired portion of the video. Segmenting a long video is, therefore, a way to provide additional navigation to your content, improving the user experience.

Chapter markers are rendered on the timeline to visualize different segments of a video. Browsing chapters is possible by scanning through the chapter titles that are rendered on the UI while the user hovers the seek bar.

THEOplayer supports loading of chapter markers in WebVTT, SRT and other text track formats.

For the following example, we will focus on chapter markers in WebVTT format. WebVTT is a plain text format, part of the HTML5 standard, that's also used for providing subtitles and closed captions. These WebVTT files are quite straightforward and contain the chapter titles for specific time ranges in the video.

A sample WebVTT file could look like the following:

```text
WEBVTT

1
00:00:00.000 --> 00:01:42.000
Opening credits

2
00:01:42.000 --> 00:04:44.000
A dangerous quest

3
00:04:44.000 --> 00:05:50.000
The attack
```

## Resources

The following resources provide more information:

* [How-to guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/subtitles-and-closed-captions/chapter-markers.md)
* [Demo page](https://demo.theoplayer.com/chapters)

---

# What are the benefits of preview thumbnails?

Preview thumbnails improve the user experience by allowing the user to scan the video for specific content. They also have a business impact determined by the bandwidth optimization connected to users that can decide and quickly jump to the content they are interested in.

Appearing when hovering over the seek bar, preview thumbnails show a quick snapshot of the video content in a tooltip.

The most straightforward advantage of thumbnails is that they allow your viewers to scan the video for content, in case they are interested in a specific portion instead of the whole video, and then seek back or forward to the desired point.

Thumbnails have also a second advantage: it might benefit your bandwidth usage. As your viewers will more easily find the content they are looking for by seeking through your video, less content needs to be buffered. Although the advantage is limited to a bandwidth optimization of only a few percentages, with growing consumption every percentage saved on bandwidth results in significant cost savings.

## Resources

* [How to guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-implement-preview-thumbnails.md)
* [Demo page](https://demo.theoplayer.com/preview-thumbnails)
* [Blog post by THEO](https://www.theoplayer.com/blog/in-stream-thumbnail-support-dvr-dash-streams)

---

# Frame Accurate Seeking

This guide will explain how you can achieve frame-accurate seeking with THEOplayer. It will explain how to calculate the current frame of your player, how to seek to a specific frame and known limitations with this approach.

## Calculate current frame

The current frame of the player can be calculated given the current time of the player, the time at which the first frame is located and the framerate. A possible implementation could be:

```js
function getCurrentFrame(player) {
  var activeQuality = player.videoTracks[0].activeQuality;
  return Math.round((player.currentTime - activeQuality.firstFrame) * activeQuality.frameRate - 0.5);
}
```

NOTE: This implementation depends on the first frame and frameRate of the active video quality. This information is not available until start of playback. When an active quality is chosen, an `activequalitychanged` event will be dispatched. The active quality is then accessible but might not have initialized values for the framerate and firstframe properties. When these properties are updated, an `update` event will be dispatched on the active quality. Using these two events, you can determine from when frame accurate seeking is possible.

## Seek to specific frame

Given a certain frame number, it is possible to seek to this frame specifically. To obtain this behavior, the time that corresponds with the frame should be calculated. A possible implementation could be:

```js
function seekToFrame(player, targetFrame) {
  var activeQuality = player.videoTracks[0].activeQuality;
  var time = (targetFrame + 0.5) / activeQuality.frameRate + activeQuality.firstFrame;
  player.currentTime = time;
}
```

## Example

The previous sections can be combined to obtain a wide variety of use cases. Suppose you desire to seek to 100 frames after the current one, this can easily be obtained with the following snippet:

```js
seekToFrame(player, getCurrentFrame(player) + 100);
```

## Known limitations

The approach mentioned above is easy and straightforward, however it does have some limitations.

* The first frame will be 0 if you start playback in the middle of a stream. This can change later if you seek back to the start of the stream. Leading to small inaccuracies.
* If an HLS stream contains discontinuities, the frame rate might not be 100% accurate.
* Some MPEG-DASH streams manifests don't contain the frame rate. In this case frame accurate seeking is not possible.
* For MPEG-DASH streams, the first frame is always reported as 0. If the first frame does not start at 0, then this approach won't work.

---

# Program Date Time

THEOplayer has support for associating media segments with an absolute date and time. This can be useful when you want to synchronize video playback with displaying other relevant information about the video stream.

THEOplayer enables this feature by making use of the `EXT-X-PROGRAM-DATE-TIME` information that gets embedded in the HLS manifest file.

## API and usage

Once the `EXT-X-PROGRAM-DATE-TIME` information is set in the HLS manifest, reading and setting the current program date time information on a THEOplayer instance is fairly straight forward. Start by [obtaining a reference to the THEOplayer instance](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md):

```js
THEOplayer.players[identifier];
```

On this THEOplayer instance, the following API attributes are available for controlling the current program data time:

| Attribute                | Description                                                                                                                                                                                                             |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currentProgramDateTime` | Sets or returns the current program date time reference. This message is calculated from the PROGRAM-DATE-TIME tag. Setting the property will seek to the playback position to the new program date time. (Date object) |

The value of the currentProgramDateTime gets updated with each `timeupdate` event thrown by the THEOplayer instance.

---

# Basic guide to Web Audio API

THEOplayer provides a [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API), which allows you to do some quite nifty stuff with the player's audio output. If you are unfamiliar with the ideas behind Web Audio API, Mozilla has an excellent intro to the basic ideas you need to know about [here](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API). This guide will help you set up a demo just like the one we have in our [Demo Zone](https://demo.theoplayer.com/web-audio-api).

This guide expects that you have a THEOplayer license. Be sure to have THEOplayer version 2.19.4 or higher.

## Getting started with THEOplayer

The first thing you need is a valid THEOplayer set-up. If you have no experience with setting up our player, we have an excellent [getting started guide](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/getting-started/sdks/web/getting-started.md). In the following sections, we will assume that you have just created a THEOplayer instance and bound it to the variable 'player'.

## A very basic Web Audio graph

The very first step in working with Web Audio is to create an AudioContext. This can be achieved as follows:

```js
var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
```

Once you have an AudioContext, you can create an AudioNode which contains the player's audio output:

```js
var sourceNode = player.audio.createAudioSourceNode(audioCtx);
```

If we stop now, the result is that the player's audio will be piped into the graph, but will not be connected to any outputs, resulting in no sound output from your speakers/headphones. The next step to get it working again would be:

```js
sourceNode.connect(audioCtx.destination);
```

Which will result in the audio being output again.

## Playing with the audio gain

Of course, this is not a very useful use of the Web Audio API, since essentially we are doing nothing with the audio. A first thing we could do is play with the gain, i.e. manipulate the player volume by using the Web Audio API.

```js
var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
var sourceNode = player.audio.createAudioSourceNode(audioCtx);
var gainNode = audioCtx.createGain();
sourceNode.connect(gainNode);
gainNode.connect(audioCtx.destination);
```

This sets up a gain filter on top of the player audio output, which we can manipulate using the gainNode.gain.value property. An example would be that we could set up a callback which monitors mouse movement:

```js
var updatePage = function (e) {
  gainNode.gain.value = (screen.height - e.screenY) / screen.height;
};

document.onmousemove = updatePage;
```

The callback will be executed every time the mouse position is updated. The result will be that the gain will be adjusted to be equal to the ratio of the distance of the mouse pointer position from the bottom of the screen (in pixels) and the screen height. So the farther you move the mouse pointer down, the quieter the output of the video will become, and the opposite effect when you move the mouse pointer up.

Playing with stereo panning

Similarly, we can play with the stereo panning of the player audio output. This can be achieved by playing with the pan.value property of the StereoPanner node.

```js
var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
var sourceNode = player.audio.createAudioSourceNode(audioCtx);
var pannerNode = audioCtx.createStereoPanner();
sourceNode.connect(pannerNode);
pannerNode.connect(audioCtx.destination);

var updatePage = function (e) {
  pannerNode.pan.value = (2 * e.screenX) / screen.width - 1;
};

document.onmousemove = updatePage;
```

The result is that moving the pointer left and right changes the stereo panning of the player audio, with balanced audio at the exact middle of the screen, pan all the way to the left when the pointer's on the left edge, and pan all the way right when the pointer's on the right edge.

## Double audio trouble

We can also do both things at the same time. The way Web Audio works allows us to pipe the output of one node as input for another node (in most cases). This way, we can combine the two tricks we were doing before into one trick: modifying the volume by moving the mouse pointer up and down, and modifying the panning by moving the mouse left and right. This is achieved by the following code:

```js
var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();
var sourceNode = player.audio.createAudioSourceNode(audioCtx);
var gainNode = audioCtx.createGain();
var pannerNode = audioCtx.createStereoPanner();
sourceNode.connect(pannerNode);
pannerNode.connect(gainNode);
gainNode.connect(audioCtx.destination);

var updatePage = function (e) {
  gainNode.gain.value = (screen.height - e.screenY) / screen.height;
  pannerNode.pan.value = (2 * e.screenX) / screen.width - 1;
};

document.onmousemove = updatePage;
```

## Bringing it all together

The next step we can take is to create a simple demo where we manipulate the audio of two players simultaneously. Assume that we have two players set up, bound to variables player1 and player2. Then we can set up exactly the same audio pipeline for both players, and reroute their audio to a single output.

```js
var sourceNode1 = player1.audio.createAudioSourceNode(audioCtx);
var gainNode1 = audioCtx.createGain();
var pannerNode1 = audioCtx.createStereoPanner();
sourceNode1.connect(pannerNode1);
pannerNode1.connect(gainNode1);
gainNode1.connect(audioCtx.destination);

var sourceNode2 = player2.audio.createAudioSourceNode(audioCtx);
var gainNode2 = audioCtx.createGain();
var pannerNode2 = audioCtx.createStereoPanner();
sourceNode2.connect(pannerNode2);
pannerNode2.connect(gainNode2);
gainNode2.connect(audioCtx.destination);
```

And at this point, we can do some more complex tricks. We can actually do the same thing as we did in the previous section, except that we can do the inverse for the second player's audio. That is, we can make moving the mouse pointer up decrease the volume for the second player, and we can invert the panning as well. This can be achieved with the following callback:

```js
var updatePage = function (e) {
  gainNode1.gain.value = (screen.height - e.screenY) / screen.height;
  pannerNode1.pan.value = (2 * e.screenX) / screen.width - 1;
  gainNode2.gain.value = e.screenY / screen.height;
  pannerNode2.pan.value = 1 - (2 * e.screenX) / screen.width;
};

document.onmousemove = updatePage;
```

Try it out!

---

# Video Clipping

THEOplayer supports playing only a selected part of a video-on-demand stream, rather than playing it from start to finish. This can be used for example to watch a single game-changing event from a sports match, highlight an important part of a long video presentation, or skip straight to the best part of a song's video clip.

## API

The start and end of the clipping window can be controlled through the [Clip API](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/interfaces/Clip):

* `startTime` and `endTime`, expressed in seconds

These properties are optional, and you don't need to specify both `startTime` and `endTime`. For example, you can set just `startTime = 30` to have the video start at 30 seconds and play the rest of the video normally.

## Basic setup

The following example shows a video clipped to start at 30 seconds and end at 60 seconds.

```js
var player = ...;
player.source = {
    sources : [{
     src : '//cdn.theoplayer.com/video/star_wars_episode_vii-the_force_awakens_official_comic-con_2015_reel_(2015)/index.m3u8', // sets HLS source
     type : 'application/x-mpegurl' // sets type to HLS
    }],
  poster: '//cdn.theoplayer.com/video/big_buck_bunny/poster.jpg'
    };

player.clip.startTime = 30;
player.clip.endTime = 60;
```

---

# Introduction

THEOplayer supports rendering of subtitles and closed captions in both live and VOD content via the WebVTT format. You can supply subtitles and closed captions to THEOplayer in WebVTT format either externally via the `<track>` element or embedded inside the HLS stream.

## Embedded WebVTTs in the HLS playlist

Apart from specifying the WebVTT file in the track element, THEOplayer has support for WebVTT captions and subtitles embedded in the HLS m3u8 manifest file.

## Examples

### Sideloading WebVTT

[This page](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-insert-subtitles.md) explains how you can insert WebVTT files.

### HTTP Live Streaming Manifest with embedded WebVTT subtitles

The following is a root HLS manifest with English, French, Spanish and Japanese subtitles. THEOplayer will handle and parse the required subtitles and synchronize them with the stream.

```text
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="English",DEFAULT=YES,AUTOSELECT=YES,FORCED=NO,LANGUAGE="en",CHARACTERISTICS="public.accessibility.transcribes-spoken-dialog, public.accessibility.describes-music-and-sound",URI="subtitles/eng/prog_index.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="Français",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="fr",CHARACTERISTICS="public.accessibility.transcribes-spoken-dialog, public.accessibility.describes-music-and-sound",URI="subtitles/fra/prog_index.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="Español",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="es",CHARACTERISTICS="public.accessibility.transcribes-spoken-dialog, public.accessibility.describes-music-and-sound",URI="subtitles/spa/prog_index.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="日本語",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="ja",CHARACTERISTICS="public.accessibility.transcribes-spoken-dialog, public.accessibility.describes-music-and-sound",URI="subtitles/jpn/prog_index.m3u8"
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=1860000,RESOLUTION=960x540,CODECS="avc1.42c01f,mp4a.40.2",SUBTITLES="subs"
gear1/prog_index.m3u8
```

## Demo

A demo on closed captions and subtitles can be found at <https://demo.theoplayer.com/closed-captions-subtitles>.

---

# Chapter markers

This guide explains to you how to set up THEOplayer to display chapter markers as a way of navigating videos. For more information regarding chapter markers, see Resources at the bottom of this page.

## SDKs

| Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK |
| ------- | ----------- | ------- | -------- | -------------- | -------------- |
| Yes     | Yes         | Yes     | N/A      | N/A            | N/A            |

## How to use the Up Next API

The Up Next API is a UI feature and shows video chapters when hovering the timeline.

### Prerequisites

This guide expects that you have a THEOplayer license. If you aren't using THEOplayer yet, you can start your free trial [here](https://portal.theoplayer.com). Be sure to have THEOplayer version 2.11 or higher.

### Adding a chapter markers track

In order to add chapter markers, you need to add a TextTrackDescription to your source that specifies a sideloaded text track of kind 'chapters'. THEOplayer supports loading of chapter markers in WebVTT, SRT and other text track formats.

To see an example of chapter markers in WebVTT formats, check out the article [What are chapter markers?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/what-are-chapter-markers.md).

### Code samples

The following code samples show how you can load THEOplayer with a video and sideloaded chapters track:

##### Web SDK

This example shows how to use chapters on your video. In this example, the source contains one `TextTrack` object, including a WebVTT file with video chapters.

```js
player.source = {
    ...
    textTracks : [{
        kind : 'chapters',
        src : 'https://cdn.theoplayer.com/video/sintel/chapters.vtt',
        srclang : 'en'
    }]
};
```

##### Android SDK

The following example shows how to use chapters on your video. In this example, the source contains one `TextTrack` object, including a WebVTT file with video chapters.

```java
sourceDescription(
    typedSource("https://cdn.theoplayer.com/video/sintel/nosubs.m3u8")
        .build()
)
.textTracks(
    new TextTrackDescription(
        src: "https://cdn.theoplayer.com/video/sintel/chapters.vtt",
        isDefault: true,
        TextTrackKind.CHAPTERS,
        srclang: "en",
        label: "Chapters")
)
```

##### iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

A `TextTrackDescription` object has the following constructor:

```swift
TextTrackDescription(src: String,
                     srclang: String,
                     isDefault: Bool?,
                     kind: TextTrackKind?,
                     label: String?,
                     format: TextTrackFormat?)
```

The following example shows how to use chapters on your video. In this example, the source contains one `TextTrack` object, including a WebVTT file with video chapters.

Example code:

```swift
var textTrackDescription = TextTrackDescription(src: "https://cdn.theoplayer.com/video/sintel/chapters.vtt",
                                                srclang: "en",
                                                kind: .chapters)
}

var sourceDescription = SourceDescription(source: TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8",
                                                              type: "application/x-mpegurl"),
                                          textTracks: [textTrackDescription])
)
```

## Sample application

This demo illustrates the use of chapter markers in production: <https://demo.theoplayer.com/chapters>.

---

# Streaming

Always wanted to know more about streaming? This is your chance!

## [📄️HTTP Live Streaming](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/streaming/http-live-streaming.md)

[HTTP Live Streaming (also known as HLS) is a protocol implemented by Apple for streaming of audio and/or video content over HTTP. HLS has become over the last years a de facto standard for streaming content online. The main reasons for this are:](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/streaming/http-live-streaming.md)

## [📄️What are the recommended stream settings?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/streaming/what-are-the-recommended-stream-settings.md)

[There are many options to encode your streams. These encoding are often related to the content you are streaming. For example, fast motion movies like sporting events might require higher frame rates and more bandwidth compared to video of static landscape webcams.](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/streaming/what-are-the-recommended-stream-settings.md)

---

# HTTP Live Streaming

HTTP Live Streaming (also known as HLS) is a protocol implemented by Apple for streaming of audio and/or video content over HTTP. HLS has become over the last years a de facto standard for streaming content online. The main reasons for this are:

* Adaptive streaming: HLS is able to dynamically adjust playback quality to match the device and network conditions such as the available speed of wired or wireless networks. This method of adaptive streaming allows the protocol to deliver better viewer experiences.
* Support for live, video-on-demand (VOD) and time-shifted (DVR) streaming.
* HTTP transactions: Because HLS only makes use of standard HTTP requests it is capable of traversing any firewall or proxy server that let through standard HTTP traffic. This also allows content to be delivered via widely available CDNs.

The HLS protocol also specifies a standard encryption mechanism with AES-128 for content protection, offers support for subtitles and closed captions, advertisements, ...

## THEOplayer and HLS: HTML5 vs. Flash

HTTP Live Streaming is currently the only protocol capable of streaming to Apples iPhone and iPad devices. However, besides Safari on Mac, most other browsers do not directly support playback of the HLS protocol. Other solutions for playback of HLS require primarily the installation of external browser plug-ins such as Flash, Silverlight or QuickTime.

With THEOplayer it is possible to stream live, VOD or DVR content with HLS directly to HTML5 platforms without the need to have any plug-ins or apps installed. THEOplayer offers support for HLS on almost all modern devices and browsers. This includes desktop devices running Windows, Linux and OS X, but also mobile devices running Android or Windows Phone.

## Supported platforms and browsers

THEOplayer offers support for HTTP Live Streaming on the following HTML5 platforms and browsers without the need to have any apps or plug-ins such as Flash, Silverlight or QuickTime installed:

| Platform              | Browser                |
| --------------------- | ---------------------- |
| **Windows**           | Internet Explorer (\*) |
|                       | Edge                   |
|                       | Chrome                 |
|                       | Firefox                |
|                       | Opera                  |
|                       | Vivaldi                |
| **OS X**              | Safari                 |
|                       | Chrome                 |
|                       | Firefox (\*\*)         |
|                       | Opera                  |
|                       | Vivaldi                |
| **Linux**             | Chrome                 |
|                       | Firefox (\*\*\*)       |
|                       | Opera                  |
| **Android**           | Chrome for Android     |
|                       | Firefox for Android    |
|                       | Opera                  |
| **iOS**               | Safari                 |
|                       | Chrome for iOS         |
|                       | Opera Mini             |
|                       | Opera Coast            |
| **Windows Phone 8.1** | Internet Explorer      |

(\*) = Version 10+

(\*\*) = As of Firefox 35+

(\*\*\*) = Requires gstreamer H.264 plug-in to be installed

---

# What are the recommended stream settings?

There are many options to encode your streams. These encoding are often related to the content you are streaming. For example, fast motion movies like sporting events might require higher frame rates and more bandwidth compared to video of static landscape webcams.

The video and audio codecs which are recommended are:

* Video: H.264 in Baseline Profile, Main Profile or High Profile. We advise against the usage of B-frames as this requires the entire chunk to be available before playback can start. It is important to take into account not all platforms will be able to play back the High profile. When setting up encoding profiles, keep in mind the platforms you intend to support.

* Audio: AAC-LC or HE-AAC. It is however important to use the same codec for all audio tracks. Using the same sampling frequency and bitrate is not required, but deviating from this might result in audible changes between streams. Also, when using HE-AAC it is highly recommended stating this in the stream's CODEC-attribute.

In regard to packaging, both raw-audio files (.aac, .mp3, ...) and MPEG Transport Streams can be used. For video, it is recommended to add a full IDR frame (keyframe) at the start of each video chunk.

The following configurations for adaptive streams have proven to work well on most content. Keep in mind some content can be displayed better when tweaking these parameters:

| # | Resolution | Video settings | Video bitrate | Frame rate | Audio settings | Audio bitrate | Audio sample rate |
| - | ---------- | -------------- | ------------- | ---------- | -------------- | ------------- | ----------------- |
| 1 | 480x270    | Baseline 3.0   | 500k          | 25 fps     | HE-AAC         | 128k          | 44.1kHz           |
| 2 | 640x360    | Baseline 3.0   | 900k          | 25 fps     | HE-AAC         | 128k          | 44.1kHz           |
| 3 | 960x540    | Baseline 3.1   | 1800k         | 25 fps     | HE-AAC         | 128k          | 44.1kHz           |
| 4 | 1280x720   | Main 3.1       | 4500k         | 25 fps     | HE-AAC         | 128k          | 44.1kHz           |
| 5 | 1920x1080  | High 4.0       | 8500k         | 25 fps     | HE-AAC         | 128k          | 44.1kHz           |

For manifest generation, we always advice to add at least the CODECS and RESOLUTION as they will speed up the adaptive bitrate capabilities of the player.

As a reference, Apple also provides a list of recommendations in regard to HLS: [TN2224](https://developer.apple.com/library/ios/technotes/tn2224/_index.html#//apple_ref/doc/uid/DTS40009745-CH1-SETTINGSFILES)

---

# Cross Origin Resource Sharing (CORS)

Cross-origin resource sharing (CORS) is a content protection mechanism that allows resources (manifests, video files or encryption keys) on server to be requested from a webpage on a different domain, subdomain or port than the one on from which the resources originated.

Such "cross-origin" requests would otherwise be forbidden by web browsers, per the same-origin security policy. CORS defines a way in which the browser and the server can interact and determine whether the browser is allowed to make these cross-origin request.

THEOplayer makes use of CORS for downloading manifests, video files and encryption keys from the streaming infrastructure. If CORS headers are not present on these server(s), THEOplayer assumes that it is not allowed to play the provided link. Make sure CORS headers are being served along with your resources in order to ensure smooth playback by THEOplayer.

## Content Delivery Network Support

From our experience and collaborations, the following CDNs have support for honoring or even adding CORS headers to requests they handle. If you are aware of a CDN that has support for CORS and is not on the list, make sure to contact us.

| Name       | Support |
| ---------- | ------- |
| Akamai     | Yes     |
| Anevia     | Yes     |
| Bitgravity | Yes     |
| Edgio      | Yes     |
| Highwinds  | Yes     |
| Internap   | Yes     |
| Level 3    | Yes     |
| Limelight  | Yes     |

## Enabling CORS on Wowza Media Server

Open the relevant (VOD, Live, ...) Wowza Application.xml configuration files.<br />Go to the `HTTPStreamer / Properties` container.<br />Add or make sure it contains:

```xml
<HTTPStreamer>
    <Properties>
        <Property>
            <Name>cupertinoUserHTTPHeaders</Name>
            <Value>Access-Control-Allow-Origin: *</Value>
        </Property>
    </Properties>
</HTTPStreamer>
```

This ensures that requested HLS files have the required CORS headers for domain \*. When in doubt, restart your Wowza Media Server instance to make sure the new configuration has been loaded.

## Enabling CORS on Adobe Flash Media Server

For Adobe Flash Media Server, CORS can be enabled by editing the .htaccess file that ships along with the installation. Add or make sure the file contains:

```xml
<IfModule mod_headers.c>
    Header set Access-Control-Allow-Origin *
</IfModule>
```

This ensures that requested HLS files have the required CORS header for domain \*. When in doubt, restart your Adobe Flash Media Server instance to make sure the new configuration has been loaded.

## Other Resources

Enabling CORS depends on the backend technology and on the used CDN. More information about CORS and how to enable it on a range of backend server technology can be found at <http://enable-cors.org/>

---

# Timed Metadata

*Timed metadata* describes a subset of a stream through data (bytes, text, image, ...), a start time and/or a stop time. For example, if you're watching a 60 seconds video, and if I would declare that an advertisement is playing in this video between 00:30 and 00:45, then I am declaring timed metadata because I'm referring to a subset of this video.

Timed metadata shouldn't be confused with *general metadata*. General metadata describes data related to your entire video content, like the title of the video, its total duration and its PG-rating. In this article we use timed metadata and metadata interchangeably, and consider general metadata out-of-scope.

![Metadata Flow](/pr-932/assets/images/metadata-flow-e0209c23fa4699e2528b581ecd591be1.png "Metadata Flow")

This article provides information on the different types of timed metadata and how you can leverage it in an application. The story is told in the reverse order: first we'll consider some use-cases (e.g. highlights), next we'll talk about the role of a video player versus the application, and finally we'll list the types of metadata (e.g. ID3) you can insert.

## Using Metadata

When using timed metadata, you are trying to achieve a [use-case](#use-cases) through a [technical implementation](#technical-implementation). In an ideal world, your video player provides an [out-of-the-box solution](#out-of-the-box-solutions) for your use-case, and you don't need to write and maintain a lot of code.

### Use-Cases

Timed metadata enables all kinds of use-cases in the field across various domains.

**Markers**

A popular use-case is to associate some data (text, image, ...) with a specific moment in time to mark a highlight.

![Metadata Markers](/pr-932/assets/images/metadata-goals-de17fe35188d311939191999ab0e74ca.png "Metadata Markers")

For example, in the screenshot above, we're leveraging metadata to highlight where a goal has been scored. If you click on the goal icon, you'll be taken to this moment in time in the video. You could of course expand this feature, and hovering the goal icon would toggle a tooltip which tells you who scored and what the new score is.

**Advertising**

Timed metadata can help you define the start and end of an advertisement. This information can be used to enhance the UI and UX. For example, at <https://cdn.theoplayer.com/demos/verizon-media/index.html>, the application leverages metadata to render markers in the scrub bar and to count down to the end of the ad break, and on top of that, if you try to seek over an ad break, the cursor snaps back to the ad break.

![Metadata Advertising](/pr-932/assets/images/metadata-advertising-15104844ee4b00b1cb4b5c40d44602b7.png "Metadata Advertising")

You can also leverage timed metadata "behind the scenes". For example, the timed metadata might contain info on the creative ID of the advertisement, and the URLs of its event trackers. An application could then use this information to communicate with an ad server or analytics server.

**Actions**

Timed metadata could also be used to initiate events and actions. For example, perhaps you want to overlay some text or image when you are at position 00:40. Or perhaps you want to disable seeking through the scrub bar for a defined period of time.

![Metadata Actions](/pr-932/assets/images/metadata-actions-01db1cadbab3af30116042c4a68cd07e.png "Metadata Actions")

The screenshot showcases a demo where a relevant hyperlink is being overlaid on top of the video within a specific time period. This hyperlink (and its start and stop time) was indicated through timed metadata.

**Other**

You can get very creative with timed metadata.

* You can use it to schedule client-side advertisements.
* You can use it to make certain areas of your video frame clickable at certain times, and clicking it will bring you to a web shop.
* ...

If you have a use-case where a certain behavior can be associated with a certain moment in time, you can probably tackle it through timed metadata.

### Technical Implementation

To programmatically extract your metadata and implement your use-case, you will always need to write custom application logic to some degree.

* You still need to write the custom code which calls the video player API.
* You might use a combination of external metadata and specification-compliant metadata, which requires you to write custom logic to tie things together.
* You probably want to tweak the UI and UX, so you'd also write some custom application code for that.

On top of this, you might need to leverage a video player API to extract your metadata, if you pass along your metadata in such a way it adheres to a certain streaming specification. More about this in the following sections.

### Out-of-the-box Solutions

To implement the use-cases listed above, applications developers have to write and maintain application code.

Sometimes, pre-integrations offered by the video player can take away some responsibilities of the application developer. For example, THEOplayer has a pre-integration with Verizon Media which allows developers to easily configure whether viewers can see ad break markers, whether viewers can skip over ad breaks, and much more.

At other times, there might be a recommended workflow and pre-integrated feature to achieve your use-case. For example, you can use [Chapter Markers](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/subtitles-and-closed-captions/chapter-markers.md) to highlight different chapters in a video.

THEOplayer also acts as the main contributor to [Enriched Media Streaming Solutions](https://www.theoplayer.com/emss) (EMSS). EMSS describes a standardized way to insert metadata and how a video player should handle and visualize this metadata. It might be interesting for you to [reach out to THEOplayer](https://servicedesk.theoplayer.com/) and ask if your use-case is supported by EMSS out-of-the-box.

## Extracting Metadata

Depending on how you insert the metadata, you have to use your video player API to extract the metadata, and/or write custom application logic.

* You use a **video player API** if you've inserted metadata which adheres to a streaming-related specification supported by the selected video player. For example, if you're using ID3 tags to pass along your metadata, you will use the designated video player API, if your video player supports the extraction of ID3 metadata.
* You write **custom application logic** if you're storing your metadata externally (e.g. on a CMS) or if you're using a metadata format which is not supported by your video player. It might be possible that you're using a video player which is pre-integrated with an external database, so you could perhaps still leverage your video player. (e.g. THEOplayer and Verizon Media.)

When you use THEOplayer as your video player API, you can use the `TextTracks API` to extract certain types of timed metadata like ID3, emsg, EXT-X-DATERANGE and EventStream, and APIs like `player.currentProgramDateTime` to determine the absolute date and time should you want to compare that with an external CMS.

## Inserting Metadata

Before we can unlock our use-cases, we need to create and insert our timed metadata. How you'll do this depends on your back-end set-up. (e.g. [Azure Media Services](https://docs.microsoft.com/en-us/azure/media-services/media-services-specifications-live-timed-metadata#2-timed-metadata-ingest) versus [Verizon Media Platform](https://docs.vdms.com/video/index.html#Develop/Live-Slicer-API.htm#timedmeta).)

Let's talk about the different types of timed metadata.

* [Segment Metadata](#segment-metadata)
* [Manifest Metadata](#manifest-metadata)
* [External Metadata](#external-metadata)
* [Timeline Metadata](#timeline-metadata)

It depends on your use-case and back-end which type you should pick, and which [considerations](#considerations) you should make. Perhaps your back-end doesn't allow you to insert any stream metadata (i.e. segment and manifest metadata), or perhaps you cannot use an external CMS.

### Segment Metadata

Segment metadata is contained within a segment. The industry also refers to segment metadata as in-band media timed events. There are two popular types of segment metadata:

1. ID3 is mostly contained .ts segments. This type of segment (`.ts`) is commonly used in HLS. ID3 can also occur in MPEG-DASH through a carriage over emsg.
2. emsg is mostly contained in CMAF media segments (e.g. `.mp4`). This type of segment is commonly used in MPEG-DASH, and in HLS when your HLS stream is using fragmented MP4 segments instead of .ts segments.

### Manifest Metadata

Manifest metadata is contained in the manifest of your streaming protocol. The industry also refers to manifest metadata as out-band media timed events. There are two popular types of manifest metadata:

1. EXT-X-DATERANGE is contained in the HLS (e.g. `.m3u8`) manifest.
2. EventStream is contained in the MPEG-DASH (e.g. `.mpd`) manifest.

### External Metadata

You can also store metadata externally, for example in a remote database or in a file.

**Database**

You can store metadata in an external database, for example by using a content management system (CMS). In this CMS, you will probably associate an IDs with asset, and associate certain types of data with these IDs.

Furthermore, your database should offer an API to your application, in order for your application developer to successfully query your database through an asset ID.

**File**

You can store metadata in files. For example, you could leverage [Chapter Markers](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/knowledge-base/playback/subtitles-and-closed-captions/chapter-markers.md) and thus use `.vtt` files. That being said, you would still need to know which asset should load which `.vtt` file, thus creating the need for an underlying CMS.

### Timeline Metadata

Your video player might be able to determine *timeline metadata* through your segments or manifests. Knowing your playhead position, video duration and/or absolute date may be necessary for you to implement your use-case.

For example, your HLS manifest might contain the `#PROGRAM-DATE-TIME` tag which defines the absolute date and time. This property allows your video player to calculate and expose the absolute date and time, which you can then leverage in your use-case.

Check with your back-end (vendor) whether if they expose the manifest metadata required for video players to calculate the absolute date and time. For HLS, this goes through the `#PROGRAM-DATE-TIME` tag. For MPEG-DASH, this goes through the `availabilityTimeOffset` attribute, and additionally through the `suggestedPresentationDelay` attribute.

### Considerations

We've listed some remarks below which could influence your decision in selecting a specific type of metadata.

* Manifest metadata can be useful because your video player will know about the metadata without requiring your video player to download individual segments. This is useful in use-cases where you want to mark highlights.
* Generating manifest metadata might increase the time it takes to load your manifest, either because the file size increases, or because of additional computations.
* Segment metadata must be downloaded by the video player before it can be extracted. What if the segment is skipped?
* Manifests and segments are not ideal suitors to carry large chunks of data. Perhaps you should put images elsewhere if you can load them on-demand?
* Not all back-end systems support all types of manifests metadata or segment metadata. You might not be able to implement your use-case on specific platforms. For example, what if your back-end does support EXT-X-DATERANGE through HLS, but not EventStream through MPEG-DASH? What if you initially didn't need to use MPEG-DASH, but suddenly (e.g. through new DRM requirements) have to us MPEG-DASH?
* Not all back-end systems (e.g. CMS) provide APIs which can be queried by an application.

## THEOplayer and Timed Metadata

THEOplayer is able to extract all applicable types of timed metadata across all supported platforms:

* EventStream through the `TextTracks` API.
* EXT-X-DATERANGE through the `TextTracks` API.
* ID3 through the `TextTracks` API.
* emsg through the `TextTracks` API.
* Timeline metadata through the `player.currentTime` and `player.currentProgramDateTime` API.

THEOplayer offers a number of pre-integrations to facilitate the implementation of relevant SSAI use-cases. Reach out to THEOplayer if your vendor is missing from the list below, because the list is incomplete.

* [Google DAI](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/google-dai.md)
* [Yospace](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/ads/yospace.md)
* [Verizon Media](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/web/uplynk/introduction.md)

THEOplayer offers features which might implement your desired use-case out-of-the-box:

* [Chapter Markers](https://demo.theoplayer.com/chapters)
* [Preview Thumbnails](https://demo.theoplayer.com/preview-thumbnails)

## Resources

* THEOplayer

  * [How to track ID3 cues/tags?](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/how-to-guides/texttrack/how-to-track-id3-cues-tags.md)
  * [TextTrack Types](https://docs-preview.optiview.dolby.com/pr-932/theoplayer/v10/api-reference/web/types/TextTrackType)
  * [ID3 Audio Player Demo](https://demo.theoplayer.com/audio-id3-metadata)

* External

  * [Requirements for Media Timed Events by the Media and Entertainment Interest Group](https://www.w3.org/TR/media-timed-events/)
  * [EXT-X-DATERANGE in the HLS specification](https://tools.ietf.org/html/draft-pantos-hls-rfc8216bis-07#section-4.4.5.1)
  * [Apple on ID3 in HLS](https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/HTTP_Live_Streaming_Metadata_Spec/Introduction/Introduction.html)
  * [MPEG-DASH Guidelines](https://dashif.org/guidelines/)

---