diff --git a/CHANGELOG.md b/CHANGELOG.md index b72d90d02..b590c5b66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -492,7 +492,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Added -- Added `onPlayerReady` callback on `THEOplayerView` to pass a `THEOplayer` instance once it is ready for access. More info on the [migration documentation](./doc/migrating_v2.md) page. +- Added `onPlayerReady` callback on `THEOplayerView` to pass a `THEOplayer` instance once it is ready for access. More info on the [migration documentation](./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. @@ -513,8 +513,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Changed -- Moved all player properties such as `paused`, `muted` and `volume`, from `THEOplayerView` component to `THEOplayer` instance. More info on the [migration documentation](./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](./doc/migrating_v2.md) page. +- Moved all player properties such as `paused`, `muted` and `volume`, from `THEOplayerView` component to `THEOplayer` instance. More info on the [migration documentation](./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](./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. diff --git a/README.md b/README.md index fd96ce401..be8963a53 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ It also gives a description of the properties of the `THEOplayerView` component, 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 @@ -39,8 +40,7 @@ For each platform, a dependency to the corresponding THEOplayer SDK is included - 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 use your existing THEOplayer SDK license or request a -[free trial account](https://www.theoplayer.com/free-trial-theoplayer?hsLang=en-us). +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), @@ -59,7 +59,72 @@ Depending on the platform on which the application is deployed, a different set If a feature missing, additional help is needed, or you need to extend the package, please reach out to us for support. - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureAndroid, Android TV, Fire TVWebiOS, tvOS
StreamingMPEG-DASH (fmp4, CMAF), HLS (TS, CMAF), Progressive MP4, MP3HLS (TS, CMAF), Progressive MP4, MP3
Content ProtectionWidevineWidevine, PlayReady, FairplayFairplay
DRM ConnectorsBuyDRM, EZDRM, Anvato, Titanium, Axinom, Irdeto, VuDRM, Comcast, Verimatrix, Azure, …
Analytics ConnectorsAdobe, Agama, Comscore, Conviva, Mux, Nielsen, Youbora
Subtitles & Closed CaptionsCEA-608/708, SRT, TTML, WebVTT
MetadataEvent stream, emsg, ID3, EXT-X-DATERANGE, EXT-X-PROGRAM-DATE-TIME
Advertising IntegrationGoogle IMA, Google DAI
Cast IntegrationChromecastChromecast, Airplay
Presentation ModeInline, Picture-in-Picture, Fullscreen
Audio Control ManagementAudio focus & Audio-Becoming-Noisy mgmt(Audio control management by platform)
Advanced APIsBackground playback,
Media Session,
Media Cache (offline playback)		Background playback,
NowPlaying,
Media Cache (iOS only)
User Interface
@theoplayer/react-native-ui		Basic playback, media & text track selection, progress bar, live & vod, preview thumbnails, customisable & extensible
## Available connectors @@ -67,7 +132,7 @@ The `react-native-theoplayer` package can be combined with any number of connect functionality. Currently, the following connectors are available: | Package name | Purpose | Registry | -|---------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`@theoplayer/react-native-analytics-adobe`](https://github.com/THEOplayer/react-native-theoplayer-analytics) | Adobe analytics connector | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-analytics-adobe)](https://www.npmjs.com/package/@theoplayer/react-native-analytics-adobe) | | [`@theoplayer/react-native-analytics-agama`](https://github.com/THEOplayer/react-native-theoplayer-analytics) | Agama analytics connector | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-analytics-agama)](https://www.npmjs.com/package/@theoplayer/react-native-analytics-agama) | | [`@theoplayer/react-native-analytics-comscore`](https://github.com/THEOplayer/react-native-theoplayer-analytics) | Comscore analytics connector | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-analytics-comscore)](https://www.npmjs.com/package/@theoplayer/react-native-analytics-comscore) | @@ -79,32 +144,40 @@ functionality. Currently, the following connectors are available: | [`@theoplayer/react-native-ui`](https://github.com/THEOplayer/react-native-theoplayer-ui) | React Native user interface | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-ui)](https://www.npmjs.com/package/@theoplayer/react-native-ui) | | [`@theoplayer/react-native-connector-template`](https://github.com/THEOplayer/react-native-theoplayer-connector-template) | A template for
`react-native-theoplayer` connectors. | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-connector-template)](https://www.npmjs.com/package/@theoplayer/react-native-connector-template) | -## Getting Started +## 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/master/example), -and discussed in the next section. Finally, an overview of features, limitations and known issues is listed. +[git repository](https://github.com/THEOplayer/react-native-theoplayer/tree/develop/example), +and discussed in the next section. - [Creating a minimal demo app](./doc/creating-minimal-app.md) - - [Getting started on Android](./doc/creating-minimal-app.md#getting-started-on-android) - - [Getting started on iOS](./doc/creating-minimal-app.md#getting-started-on-ios-and-tvos) - - [Getting started on Web](./doc/creating-minimal-app.md#getting-started-on-web) + - [Getting started on Android](./doc/creating-minimal-app.md#getting-started-on-android) + - [Getting started on iOS](./doc/creating-minimal-app.md#getting-started-on-ios-and-tvos) + - [Getting started on Web](./doc/creating-minimal-app.md#getting-started-on-web) - [The THEOplayerView component](./doc/theoplayerview-component.md) - [The example application](./doc/example-app.md) -- Knowledge Base - - [Adaptive Bitrate (ABR)](./doc/abr.md) - - [Advertisements](./doc/ads.md) - - [Audio Control Management](./doc/audio-control.md) - - [Background playback and notifications](./doc/background.md) - - [Casting with Chromecast and Airplay](./doc/cast.md) - - [Custom iOS framework](./doc/custom-ios-framework.md) - - [Digital Rights Management (DRM)](./doc/drm.md) - - [Fullscreen presentation](./doc/fullscreen.md) - - [Media Caching](./doc/media_caching.md) - - [Migrating to `react-native-theoplayer` v2.x](./doc/migrating_v2.md) - - [Picture-in-Picture (PiP)](./doc/pip.md) - - [Subtitles, Closed Captions and Metadata tracks](./doc/texttracks.md) - - [Limitations and known issues](./doc/limitations.md) -- [API Reference](https://theoplayer.github.io/react-native-theoplayer/api/) + +## Knowledge Base + +This section gives an overview of features, limitations and known issues: + +- [Adaptive Bitrate (ABR)](./doc/abr.md) +- [Advertisements](./doc/ads.md) +- [Audio Control Management](./doc/audio-control.md) +- [Background playback and notifications](./doc/background.md) +- [Casting with Chromecast and Airplay](./doc/cast.md) +- [Custom iOS framework](./doc/custom-ios-framework.md) +- [Digital Rights Management (DRM)](./doc/drm.md) +- [Fullscreen presentation](./doc/fullscreen.md) +- [Media Caching](./doc/media-caching.md) +- [Migrating to `react-native-theoplayer` v2.x](./doc/migrating-v2.md) +- [Picture-in-Picture (PiP)](./doc/pip.md) +- [Subtitles, Closed Captions and Metadata tracks](./doc/texttracks.md) +- [Limitations and known issues](./doc/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. diff --git a/doc/abr.md b/doc/abr.md index c3f848fc2..5354704a1 100644 --- a/doc/abr.md +++ b/doc/abr.md @@ -1,6 +1,6 @@ -## Adaptive Bitrate (ABR) +# Adaptive Bitrate (ABR) -### Overview +## 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 @@ -14,7 +14,7 @@ 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 +## ABR Configuration The [ABR Configuration](../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. @@ -54,7 +54,7 @@ const strategyConfig: ABRStrategyConfiguration = { player.abr.strategy = strategyConfig; ``` -### Setting Target Video Quality +## 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. @@ -67,7 +67,7 @@ const selectedVideoQuality: number | number[] | undefined = [33, 34, 35] player.targetVideoQuality = selectedVideoQuality; ``` -### Subscribing to track events +## 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: @@ -77,7 +77,7 @@ when the track list is modified, or when a track's current quality changes: | `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 +### 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 diff --git a/doc/ads.md b/doc/ads.md index 7b2d25d76..df41f74ed 100644 --- a/doc/ads.md +++ b/doc/ads.md @@ -1,6 +1,6 @@ -## Advertisements +# Advertisements -### Overview +## Overview A good starting point to get acquainted with THEOplayer's advertising features is THEOplayer's [Knowledge Base](https://docs.theoplayer.com/knowledge-base/01-advertisement/01-user-guide.md). @@ -18,9 +18,9 @@ Additional functionality, such as scheduling ads at runtime, is provided by the The final section describes how to subscribe and add custom logic to [ad events](#subscribing-to-ad-events). -### Getting started with Google IMA +## Getting started with Google IMA -#### Configuration +### Configuration First enable Google IMA support, which requires a different approach on each platform. @@ -40,13 +40,13 @@ THEOplayer_extensionGoogleIMA = true
iOS/tvOS -##### 1.x versions: Custom THEOplayer build +#### 1.x versions: Custom THEOplayer build To enable GoogleIMA on react-native-theoplayer 1.x versions, a dependency to the THEOplayer SDK that includes the Google IMA library needs to be added. See [Custom iOS framework](./custom-ios-framework.md) for more details. -##### 2.x versions: Add feature flag to config +#### 2.x versions: Add feature flag to config To enable Google IMA on react-native-theoplayer 2.x versions, you can add the "GOOGLE_IMA" [feature flag](./creating-minimal-app.md#getting-started-on-ios-and-tvos) to react-native-theoplayer.json (or theoplayer-config.json) @@ -57,7 +57,7 @@ To enable Google IMA on react-native-theoplayer 2.x versions, you can add the "G 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](../example/web/public/index.html): +in the example app's [index.html](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/example/web/public/index.html): ```html @@ -69,7 +69,7 @@ in the example app's [index.html](../example/web/public/index.html):
-#### Source description +### 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: @@ -96,7 +96,7 @@ const imaSource = { The API's [`AdSource`](../src/api/source/ads/Ads.ts) description provides additional information on the configurable properties. -### Getting started with Google DAI +## Getting started with Google DAI First enable Google DAI support, which requires a different approach on each platform. @@ -126,7 +126,7 @@ To enable Google DAI for iOS, a dependency to the THEOplayer SDK that includes t 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](../example/web/public/index.html): +in the example app's [index.html](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/example/web/public/index.html): ```html @@ -138,7 +138,7 @@ in the example app's [index.html](../example/web/public/index.html): -#### Source description +### Source description Providing a Google DAI source description to the player requires providing an `ssai` object and specifying `"google-dai"` as integration type: @@ -159,7 +159,7 @@ const daiSource = { A full description of the available source properties can be found in the [API](../src/api/source/ads/ssai/GoogleDAIConfiguration.ts) definition. -### Using the Ads API +## Using the Ads API [THEOplayer](../src/api/player/THEOplayer.ts) provides an [AdsAPI](../src/api/ads/AdsAPI.ts) that enables additional features @@ -201,7 +201,7 @@ const streamTimeForContentTime = (contentTime: number): Promise | undefi }; ``` -### Subscribing to ad events +## Subscribing to ad events [THEOplayer](../src/api/player/THEOplayer.ts) allows you to subscribe to ad events: diff --git a/doc/audio-control.md b/doc/audio-control.md index d58d80dca..e6cf9c560 100644 --- a/doc/audio-control.md +++ b/doc/audio-control.md @@ -1,6 +1,6 @@ -## Audio Control Management on Android +# Audio Control Management on Android -### Overview +## 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 @@ -13,7 +13,7 @@ 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 +## 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. @@ -21,7 +21,7 @@ request upon the start of playback and responds to the loss of audio focus by pa 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" +### 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 @@ -37,7 +37,7 @@ In summary: | `AUDIOFOCUS_GAIN` | Resume play-out | -### Audio Becoming Noisy +## 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. diff --git a/doc/background.md b/doc/background.md index 279d22ead..0361bcffb 100644 --- a/doc/background.md +++ b/doc/background.md @@ -1,12 +1,12 @@ -## Background Playback and Notifications +# Background Playback and Notifications -### Overview +## 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 +## 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 @@ -19,7 +19,7 @@ properties, or whether an ad is playing or not. player.backgroundAudioConfiguration = { enabled: true }; ``` -#### Android +### 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. @@ -28,7 +28,7 @@ It is possible to disable the service at build time by setting the build config 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 +## 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 @@ -81,7 +81,7 @@ As a result, the following setup will result in the same lockscreen info being d |-----------------------------------------------------|:-------------------------------------------:|:---:| | Android | iOS | Web | -#### Configuration +### Configuration The `mediaControl` property of `PlayerConfiguration` hosts properties that affect the notifications, media sessions and controls on each platform. Currently, it only contains a property `mediaSessionEnabled` diff --git a/doc/cast.md b/doc/cast.md index 28c43479c..aefa30fa5 100644 --- a/doc/cast.md +++ b/doc/cast.md @@ -1,6 +1,6 @@ -## Casting with Chromecast and Airplay +# Casting with Chromecast and Airplay -### Overview +## Overview The basics of both Chromecast and Airplay are well-described in THEOplayer's [Knowledge Base](https://docs.theoplayer.com/how-to-guides/03-cast/01-chromecast/00-introduction.md). @@ -9,16 +9,16 @@ 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 +## Chromecast -#### Setup +### 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 `` component that can be added to the app's UI, as demonstrated in -the [example app](example-app.md). +the [example app](example-app.md). ```tsx iOS -##### Add feature flag to config +#### Add feature flag to config To enable Chromecast on react-native-theoplayer 2.x versions and higher, you can add the "CHROMECAST" [feature flag](./creating-minimal-app.md#getting-started-on-ios-and-tvos) to react-native-theoplayer.json (or theoplayer-config.json) -##### iOS Configuration +#### 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. @@ -81,7 +81,7 @@ network. ``` -##### Combining with react-native-google-cast +#### 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 @@ -123,7 +123,7 @@ The web page hosting the player just needs to load the Google cast sender module -#### THEOplayerView configuration +### 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 @@ -150,7 +150,7 @@ 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 +### Cast strategy The `strategy` property indicates the *join strategy* that will be used when starting/joining sessions: @@ -181,7 +181,7 @@ useEffect(() => { The [example app](./example-app.md) uses strategy `auto` so the player will automatically send its source description when a session is created. -#### Providing metadata +### 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`. @@ -208,7 +208,7 @@ to the receiver. Common fields include `poster`, `title`, `subtitle`, `album` an |---------------------------------| | Casting a stream with metadata. | -### Airplay +## Airplay For iOS and Web Safari, also Airplay is 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 @@ -225,11 +225,11 @@ player.cast.airplay?.state().then((airplayCastState) => { }) ``` -### Cast API +## Cast API The `THEOplayerView` provides the [THEOplayer API](../src/api/player/THEOplayer.ts) using the `onPlayerReady` callback, where you can access the [CastAPI](../src/api/event/CastEvent.ts) to control or start cast sessions, either Chromecast or Airplay. -### Subscribing to Cast Events +## Subscribing to Cast Events The `THEOplayerView` provides the [THEOplayer API](../src/api/player/THEOplayer.ts) using the `onPlayerReady` callback, where you can subscribe to cast events: diff --git a/doc/creating-minimal-app.md b/doc/creating-minimal-app.md index e3b9249b3..0fb8230ad 100644 --- a/doc/creating-minimal-app.md +++ b/doc/creating-minimal-app.md @@ -1,19 +1,15 @@ -## Creating a minimal demo app +--- +sidebar_position: 1 +--- + +# 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. -### 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-and-tvos) -- [Getting started on Web](#getting-started-on-web) -- [Building and running the app](#building-and-running-the-app) -- [Adding a user interface](#adding-a-user-interface) - -### Setting up a new project +## Setting up a new project In the following steps we will be using `npm` as the Node.js package manager. @@ -53,7 +49,6 @@ $ npm i react-native-theoplayer --legacy-peer-deps Finally, replace the `App.tsx` with this minimal code: -{% raw %} ```tsx import React from 'react'; import {Platform, View} from 'react-native'; @@ -88,15 +83,13 @@ const App = () => { export default App; ``` -{% endraw %} 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/) -or request a [free trial license](https://www.theoplayer.com/free-trial-theoplayer?hsLang=en-us). +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](./license_portal.png) -### Getting started on Android +## 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 @@ -139,7 +132,7 @@ For optimal performance, make sure to build your app in release mode, and optio 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 +## Getting started on iOS and tvOS To define which extra THEOplayer integrations need to be loaded for additional features (currently: IMA ads and/or chromecast) a config file needs to be added to you application folder: @@ -184,7 +177,7 @@ Run pod install in your app's ios folder pod install ``` -### When working with a 4.x tvOS THEOplayer SDK +## When working with a 4.x tvOS THEOplayer SDK When using a 4.x SDK, you need an additional change for tvOS, since the tvOS SDK needs to be prepared before it can be used in a RN context. First, include TheoplayerSDK into your project's AppDelegate: ```swift #if TARGET_OS_TV @@ -198,16 +191,16 @@ Next, prepare the THEOplayer right after the creation of the rootViewController #endif ``` -### Getting started on Web +## 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](example-app.md) and its [code](../example/web/) for a full demonstration. +We refer to the [example application](example-app.md) and its [code](https://github.com/THEOplayer/react-native-theoplayer/blob/develop/example/web/) for a full demonstration. -#### libraryConfiguration +### libraryConfiguration When passing the `PlayerConfiguration` object while creating the player, the [`libraryConfiguration`](https://docs.theoplayer.com/api-reference/web/theoplayer.playerconfiguration.md#librarylocation) parameter specifies @@ -215,7 +208,7 @@ where the THEOplayer web worker files are located. The worker files are dynamica 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 +## 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. @@ -226,7 +219,7 @@ $ npm run ios $ npm run web ``` -### Adding a user interface +## 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`. diff --git a/doc/drm.md b/doc/drm.md index f96ef2354..6cf570a61 100644 --- a/doc/drm.md +++ b/doc/drm.md @@ -1,12 +1,12 @@ -## Digital Rights Management (DRM) +# Digital Rights Management (DRM) -### Overview +## 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://docs.theoplayer.com/knowledge-base/02-content-protection/00-introduction.md). -### Configuration +## 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 @@ -36,9 +36,9 @@ const onReady = (player: THEOplayer) => { ``` -### Content Protection Integrations +## Content Protection Integrations -#### Pre-integrations +### Pre-integrations THEOplayer is [pre-integrated](https://docs.theoplayer.com/how-to-guides/04-drm/00-introduction.md#pre-integrations) with a number of commercial multi-DRM vendors, which means support for these vendors is already included @@ -47,7 +47,7 @@ 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 +### 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 @@ -55,7 +55,7 @@ to the implementation for the Web SDK, and is explained in detail on our repository. This repository also contains a number of examples for well-known multi-DRM vendors. -#### Registering a custom protection integration +### Registering a custom protection integration Once the custom DRM integrations is created, it needs to be registered up-front as follows: diff --git a/doc/example-app.md b/doc/example-app.md index 8fbc2caee..61dc93b6d 100644 --- a/doc/example-app.md +++ b/doc/example-app.md @@ -1,7 +1,11 @@ -## Example Application +--- +sidebar_position: 3 +--- + +# Example Application The example application on our `react-native-theoplayer` -[git repository](https://github.com/THEOplayer/react-native-theoplayer/tree/master/example) demonstrates how the use the +[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), @@ -15,7 +19,7 @@ visit [our React Native UI project](https://github.com/THEOplayer/react-native-t |-------------------------------------------------------------------------------|--------------------------------------------------------|--------------------------------------------------| | The `DefaultTHEOplayerUi` in action. | Choosing a demo source from a custom UI component. | Preview thumbnails. | -### Building the example application +## Building the example application Clone the repository and install the dependencies for the `react-native-theoplayer` package: @@ -37,8 +41,7 @@ For iOS and tvOS, also make sure to install pod dependencies $ (cd example/ios && pod install) ``` -Make sure to configure your [THEOplayer license](https://portal.theoplayer.com/), -or [free trial license](https://www.theoplayer.com/free-trial-theoplayer?hsLang=en-us), in +Make sure to configure your [THEOplayer license](https://portal.theoplayer.com/) in the [app config](../example/src/App.tsx). Finally, after making sure the necessary development tools are installed, build & deploy the example: diff --git a/doc/features.svg b/doc/features.svg deleted file mode 100644 index 424f683b8..000000000 --- a/doc/features.svg +++ /dev/null @@ -1,130 +0,0 @@ - - -
- - -
-
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, PlayReady, Fairplay
-
Fairplay
-
- -
-
DRM Connectors
-
BuyDRM, EZDRM, Anvato, Titanium, Axinom, Irdeto, VuDRM, Comcast, Verimatrix, Azure, …
-
- -
-
Analytics Connectors
-
Adobe, Agama, Comscore, Conviva, Mux, Nielsen, Youbora
-
- -
-
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
-
- -
-
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,
- Media Session,
- Media Cache (offline playback) -
-
- Background playback,
- NowPlaying,
- Media Cache (iOS only)
-
- -
-
User Interface
@theoplayer/react-native-ui
-
Basic playback, media & text track selection, progress bar, live & vod, preview thumbnails, customisable & extensible
-
-
- - diff --git a/doc/fullscreen.md b/doc/fullscreen.md index 1b033e4b1..a7e96f2f2 100644 --- a/doc/fullscreen.md +++ b/doc/fullscreen.md @@ -1,4 +1,4 @@ -## A Fullscreen Video Player Component +# A Fullscreen Video Player Component Presenting a fullscreen video player poses challenges due to the need to seamlessly transition between the regular view and fullscreen mode, while maintaining playback continuity. @@ -10,16 +10,7 @@ new screen to present the player, and a second that transitions to fullscreen fr We will also discuss the related concept of "React Portals", which, when paired with a video player component, offer versatile applications beyond fullscreen display. -### Table of Contents - -- [Presenting a fullscreen video player](#presenting-a-fullscreen-video-player) - - [A separate player screen](#1-a-separate-player-screen) - - [An inline video player](#2-an-inline-video-player) -- [Portals](#portals) -- [Using Portals to transition from an inline player to a floating](#using-portals-to-transition-to-an-in-app-mini-player) -- [Closing remarks](#closing-remarks) - -### Presenting a fullscreen video player +## 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 @@ -35,7 +26,7 @@ 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 +### 1. A separate player screen Navigate to a _separate player screen_ that contains only the video player presented in an immersive mode. @@ -44,7 +35,7 @@ transitioning to another screen means recreating (remounting) the player, causin 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 +### 2. An inline video player Make the current _inline video player_ component stretch itself while covering all elements in the current screen. @@ -66,7 +57,7 @@ player.presentationMode = PresentationMode.fullscreen; When the player transitions back to inline mode, the view hierarchy will be restored. -### Portals +## Portals 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 @@ -79,7 +70,7 @@ A typical use case is when the child component needs to "break out" of its conta 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 +## 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. @@ -89,7 +80,6 @@ use [a package](https://www.npmjs.com/package/@alexzunik/rn-native-portals-rebor _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. -{% raw %} ```tsx export default function App() { const [isMiniPlayer, setMiniPlayer] = useState(false); @@ -118,7 +108,6 @@ export default function App() { ); } ``` -{% endraw %} 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. @@ -131,7 +120,7 @@ will also be re-parented to the miniPlayer container at the bottom of the screen |----------------------------------------|------------------------------------| | A mini-player using Portals on Android | A mini-player using Portals on iOS | -### Closing remarks +## Closing remarks Variants of the approach discussed above put the `PortalDestination` on a dedicated route in a [`NavigationContainer`](https://reactnavigation.org/docs/navigation-container/). This is diff --git a/doc/getting-started.md b/doc/getting-started.md new file mode 100644 index 000000000..3e6fe411f --- /dev/null +++ b/doc/getting-started.md @@ -0,0 +1,171 @@ +--- +sidebar_position: 0 +--- + +# 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureAndroid, Android TV, Fire TVWebiOS, tvOS
StreamingMPEG-DASH (fmp4, CMAF), HLS (TS, CMAF), Progressive MP4, MP3HLS (TS, CMAF), Progressive MP4, MP3
Content ProtectionWidevineWidevine, PlayReady, FairplayFairplay
DRM ConnectorsBuyDRM, EZDRM, Anvato, Titanium, Axinom, Irdeto, VuDRM, Comcast, Verimatrix, Azure, …
Analytics ConnectorsAdobe, Agama, Comscore, Conviva, Mux, Nielsen, Youbora
Subtitles & Closed CaptionsCEA-608/708, SRT, TTML, WebVTT
MetadataEvent stream, emsg, ID3, EXT-X-DATERANGE, EXT-X-PROGRAM-DATE-TIME
Advertising IntegrationGoogle IMA, Google DAI
Cast IntegrationChromecastChromecast, Airplay
Presentation ModeInline, Picture-in-Picture, Fullscreen
Audio Control ManagementAudio focus & Audio-Becoming-Noisy mgmt(Audio control management by platform)
Advanced APIsBackground playback,
Media Session,
Media Cache (offline playback)		Background playback,
NowPlaying,
Media Cache (iOS only)
User Interface
@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: + +| Package name | Purpose | Registry | +| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`@theoplayer/react-native-analytics-adobe`](https://github.com/THEOplayer/react-native-theoplayer-analytics) | Adobe analytics connector | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-analytics-adobe)](https://www.npmjs.com/package/@theoplayer/react-native-analytics-adobe) | +| [`@theoplayer/react-native-analytics-agama`](https://github.com/THEOplayer/react-native-theoplayer-analytics) | Agama analytics connector | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-analytics-agama)](https://www.npmjs.com/package/@theoplayer/react-native-analytics-agama) | +| [`@theoplayer/react-native-analytics-comscore`](https://github.com/THEOplayer/react-native-theoplayer-analytics) | Comscore analytics connector | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-analytics-comscore)](https://www.npmjs.com/package/@theoplayer/react-native-analytics-comscore) | +| [`@theoplayer/react-native-analytics-conviva`](https://github.com/THEOplayer/react-native-theoplayer-analytics) | Conviva analytics connector | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-analytics-conviva)](https://www.npmjs.com/package/@theoplayer/react-native-analytics-conviva) | +| [`@theoplayer/react-native-analytics-mux`](https://github.com/THEOplayer/react-native-theoplayer-analytics) | Mux analytics connector | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-analytics-mux)](https://www.npmjs.com/package/@theoplayer/react-native-analytics-mux) | +| [`@theoplayer/react-native-analytics-nielsen`](https://github.com/THEOplayer/react-native-theoplayer-analytics) | Nielsen analytics connector | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-analytics-nielsen)](https://www.npmjs.com/package/@theoplayer/react-native-analytics-nielsen) | +| [`@theoplayer/react-native-analytics-youbora`](https://github.com/THEOplayer/react-native-theoplayer-analytics) | Youbora analytics connector | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-analytics-youbora)](https://www.npmjs.com/package/@theoplayer/react-native-analytics-youbora) | +| [`@theoplayer/react-native-drm`](https://github.com/THEOplayer/react-native-theoplayer-drm) | Content protection (DRM) connectors | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-drm)](https://www.npmjs.com/package/@theoplayer/react-native-drm) | +| [`@theoplayer/react-native-ui`](https://github.com/THEOplayer/react-native-theoplayer-ui) | React Native user interface | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-ui)](https://www.npmjs.com/package/@theoplayer/react-native-ui) | +| [`@theoplayer/react-native-connector-template`](https://github.com/THEOplayer/react-native-theoplayer-connector-template) | A template for
`react-native-theoplayer` connectors. | [![npm](https://img.shields.io/npm/v/@theoplayer/react-native-connector-template)](https://www.npmjs.com/package/@theoplayer/react-native-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](creating-minimal-app.md) + - [Getting started on Android](creating-minimal-app.md#getting-started-on-android) + - [Getting started on iOS](creating-minimal-app.md#getting-started-on-ios-and-tvos) + - [Getting started on Web](creating-minimal-app.md#getting-started-on-web) +- [The THEOplayerView component](theoplayerview-component.md) +- [The example application](example-app.md) + +## Knowledge Base + +This section gives an overview of features, limitations and known issues: + +- [Adaptive Bitrate (ABR)](abr.md) +- [Advertisements](ads.md) +- [Audio Control Management](audio-control.md) +- [Background playback and notifications](background.md) +- [Casting with Chromecast and Airplay](cast.md) +- [Custom iOS framework](custom-ios-framework.md) +- [Digital Rights Management (DRM)](drm.md) +- [Fullscreen presentation](fullscreen.md) +- [Media Caching](media-caching.md) +- [Migrating to `react-native-theoplayer` v2.x](migrating-v2.md) +- [Picture-in-Picture (PiP)](pip.md) +- [Subtitles, Closed Captions and Metadata tracks](texttracks.md) +- [Limitations and known issues](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. diff --git a/doc/limitations.md b/doc/limitations.md index 10dee911a..97e8aabb6 100644 --- a/doc/limitations.md +++ b/doc/limitations.md @@ -1,8 +1,8 @@ -## Limitations and Known Issues +# Limitations and Known Issues This sections lists any limitations and known issues in the current package version. -### Custom-built THEOplayer SDKs +## Custom-built THEOplayer SDKs Dependencies to the underlying THEOplayer SDKs are currently configured in the `react-native-theoplayer` package using various dependency managers: diff --git a/doc/media_caching.md b/doc/media-caching.md similarity index 94% rename from doc/media_caching.md rename to doc/media-caching.md index be4496b8b..3c9740145 100644 --- a/doc/media_caching.md +++ b/doc/media-caching.md @@ -1,6 +1,6 @@ -## Media Cache +# Media Cache -### Overview +## 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, @@ -21,7 +21,7 @@ This page is structured as follows: - [Using React hooks](#using-react-hooks) - [Known Limitations](#known-limitations) -#### Caching Workflow +### 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. @@ -30,7 +30,7 @@ Caching a media asset encompasses the following stages: - 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 +## 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 @@ -68,7 +68,7 @@ const parameters = { const task = await MediaCache.createTask(source, parameters); ``` -### Controlling the CachingTask +## Controlling the CachingTask Once the `CachingTask` is created, it enters the `idle` state. To initiate the download process: ```typescript @@ -82,11 +82,11 @@ task.pause(); task.remove(); ``` -### Listening for Cache events +## Listening for Cache events Both `MediaCache` and `CachingTask` instances dispatch events to notify about changes and status updates. -#### MediaCache events +### MediaCache events The `MediaCache` dispatches the following events: @@ -105,7 +105,7 @@ MediaCache.addEventListener(CacheEventType.addtask, (event: AddCachingTaskEvent) ); ``` -#### CachingTask events +### CachingTask events Each individual `CachingTask` also dispatches events to advertise changes in `progress` or `status`. @@ -122,12 +122,12 @@ task.addEventListener(CachingTaskEventType.progress, () => { }); ``` -### Using React hooks +## Using React hooks For convenience, React hooks are available to simplify handling caching tasks without the need to subscribe or unsubscribe to listeners. -#### useCachingTaskList +### useCachingTaskList This hooks listens for updates in the `MediaCache.tasks` list, and returns the updated list. @@ -140,7 +140,7 @@ function TaskListView(props: {debug: boolean}) { } ``` -#### useCachingTaskProgress and useCachingTaskStatus +### useCachingTaskProgress and useCachingTaskStatus These hooks listen for updates in both progress and status of a `CachingTask`. @@ -156,7 +156,7 @@ function CachingTaskView(props: {task: CachingTask, debug: boolean}) { } ``` -### The Example App +## 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 @@ -165,4 +165,4 @@ source, and show a list of the currently available caching tasks. | ![main](./media_caching_1.png) | ![main](./media_caching_2.png) | |--------------------------------|--------------------------------| -### Known Limitations +## Known Limitations diff --git a/doc/migrating_v2.md b/doc/migrating-v2.md similarity index 97% rename from doc/migrating_v2.md rename to doc/migrating-v2.md index 20b24d9d6..bbf3a35da 100644 --- a/doc/migrating_v2.md +++ b/doc/migrating-v2.md @@ -1,4 +1,4 @@ -## Migrating to `react-native-theoplayer` v2.x +# Migrating to `react-native-theoplayer` v2.x The v2 release of `react-native-theoplayer` comes with a number of breaking API changes. The `THEOplayerView` component is now split into two separate objects, @@ -8,7 +8,7 @@ In addition, events are being dispatched to subscribed listeners instead of thro In this section we will highlight the differences between the old and new approach in order to allow a smooth transition. -### Player Creation +## Player Creation The `THEOplayerView` component is created and mounted as before. @@ -60,7 +60,7 @@ const App = () => { -### Listening to Player Events +## Listening to Player Events As of v2.x, the event callbacks have been removed from `THEOplayerView` and replaced by a subscription approach. @@ -131,7 +131,7 @@ const App = () => { -### AdsAPI and CastAPI +## AdsAPI and CastAPI The existing ads and casting API's work the same as before. Instead of requesting an API from the view's reference, it can now be requested directly from the player instance. diff --git a/doc/pip.md b/doc/pip.md index eaf7ba8f7..cee1c9f39 100644 --- a/doc/pip.md +++ b/doc/pip.md @@ -1,6 +1,6 @@ -## Picture-in-Picture (PiP) +# Picture-in-Picture (PiP) -### Overview +## 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. @@ -12,9 +12,9 @@ Transitioning the player to a PiP window can be done in two ways: This page describes how to configure PiP with react-native-theoplayer. -### Configuration +## Configuration -#### Transitioning to PiP automatically +### 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 @@ -25,7 +25,7 @@ behaviour depending on the active media asset. player.pipConfiguration = { startsAutomatically: true } ``` -#### Using presentationMode +### Using presentationMode The picture-in-picture presentation mode can also be triggered explicitly using the `THEOplayer` API: @@ -35,7 +35,7 @@ The picture-in-picture presentation mode can also be triggered explicitly using player.presentationMode = PresentationMode.pip; ``` -#### Listening for presentationMode changes +### 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 @@ -52,14 +52,14 @@ player.addEventListener( Additional configuration is necessary depending on the platform the app runs on. -### Android +## 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 +### 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 @@ -96,7 +96,7 @@ override fun onPictureInPictureModeChanged( } ``` -#### PiP controls +### 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 @@ -105,7 +105,7 @@ navigator buttons. | ![pip1](./pip_android_1.png) | ![pip2](./pip_android_2.png) | ![pip3](./pip_android_3.png) | |---------------------------------------------------|:----------------------------------------------------------:|:-----------------------------:| -#### User interface +### User interface As mentioned before, when choosing `picture-in-picture` presentation mode on Android the whole activity moves to the PiP window, including the @@ -114,14 +114,14 @@ on Android in PiP mode, as opposed to iOS and web where the video view is separa 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 +## iOS No extra configuration is necessary to support picture-in-picture on iOS. In contrast to Android, only the video view will move to the floating PiP window. The react-native UI can remain visible and provide playback control. -### Web +## Web On web the behavior is similar to iOS, where PiP can be started manually from the UI. It will open up a floating PiP window displaying the video element. diff --git a/doc/texttracks.md b/doc/texttracks.md index d18a5ee60..b83973874 100644 --- a/doc/texttracks.md +++ b/doc/texttracks.md @@ -1,18 +1,9 @@ -## Subtitles, Closed Captions and Metadata tracks +# 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. -### Table of Contents - -- [Types of text tracks](#types-of-text-tracks) -- [Side-loaded text tracks](#side-loaded-text-tracks) -- [Listening to text track events](#listening-to-text-track-events) -- [Enabling a text track](#enabling-a-text-track) -- [Preview thumbnails](#preview-thumbnails) -- [Styling subtitles and closed captions](#styling-subtitles-and-closed-captions) - -### Types of text tracks +## Types of text tracks In this document we will differentiate between the following kinds of text tracks: @@ -26,7 +17,7 @@ In addition, a distinction can be made between how a text track is delivered to - **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 +## 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: @@ -52,7 +43,7 @@ player.source = { } ``` -#### iOS/tvOS +### 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. @@ -65,7 +56,7 @@ feature to the `react-native-theoplayer.json` (or `theoplayer-config.json`) file } ``` -### Listening to text track events +## 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, @@ -107,7 +98,7 @@ player.addEventListener(PlayerEventType.TEXT_TRACK, (event: TextTrackEvent) => { }) ``` -### Enabling a text track +## 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. @@ -120,7 +111,7 @@ 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. -### Preview thumbnails +## 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. @@ -156,12 +147,12 @@ thumbnail viewer the interprets thumbnail cues and displays them above the progr [//]: # ( TODO: insert picture from react-native-theoplayer-ui) [//]: # (# ![]()) -### Styling subtitles and closed captions +## 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 +### Style properties | Property | Purpose | Value | Support | |-------------------|-------------------------------------------------------------------|-----------------------------------------------------------------------------------------|:-------------------------------------------------------------------| @@ -176,7 +167,7 @@ which enables the customization of subtitles and closed captions' appearance. We | `marginBottom` | The bottom margin of the area where subtitles are being rendered. | A positive numeric value specifying the number of pixels. | Web only. | | `marginRight` | The right margin of the area where subtitles are being rendered. | A positive numeric value specifying the number of pixels. | Web only. | -#### Examples +### Examples diff --git a/doc/theoplayerview-component.md b/doc/theoplayerview-component.md index 796f9f023..7982f46f1 100644 --- a/doc/theoplayerview-component.md +++ b/doc/theoplayerview-component.md @@ -1,4 +1,8 @@ -## The `THEOplayerView` Component +--- +sidebar_position: 2 +--- + +# 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. @@ -12,18 +16,7 @@ its [THEOplayerViewProps interface](../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. -### Table of Contents - -- [Properties](#properties) -- [Configuration](#configuration) -- [Chromeless vs. Chromefull](#chromeless-vs-chromefull) -- [Setting a source](#setting-a-source) -- [Seeking to a position in a stream](#seeking-to-a-position-in-a-stream) -- [Text tracks and media tracks](#text-tracks-and-media-tracks) -- [Preview thumbnails](#preview-thumbnails) -- [Buffering state changes](#buffering-state-changes) - -### Properties +## Properties The `THEOplayerView` component supports the following list of properties. @@ -34,7 +27,7 @@ The `THEOplayerView` component supports the following list of properties. | `onPlayerReady` | A callback that provides the [THEOplayer API](../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 +## Configuration The `THEOplayerView` component accepts a `config` property that contains basic player configuration. @@ -61,23 +54,23 @@ const license = Platform.select( 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 +### Adaptive Bitrate (ABR) configuration On Android and Web platforms, you can control the ABR configuration using `player.abr` on the [THEOplayer API](../src/api/player/THEOplayer.ts). We refer to the [Adaptive Bitrate (ABR)](abr.md) page for detailed information, including examples. -#### Chromeless vs. Chromefull +### 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 +### 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 +## Setting a source You can set a source using the `source` property on the [THEOplayer API](../src/api/player/THEOplayer.ts). The type definition of `SourceDescription` maps to the type used in @@ -92,7 +85,7 @@ player.source = { } ``` -### Seeking to a position in a stream +## 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](../src/api/player/THEOplayer.ts). @@ -102,7 +95,7 @@ Timestamps are measured in milliseconds. player.currentTime = 20_000; // msec ``` -### Text tracks and media tracks +## 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](../src/api/player/THEOplayer.ts). @@ -126,14 +119,14 @@ The `PlayerEventType.MEDIA_TRACK_LIST` event can be used to dynamically listen t 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 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](./example-app.md) demonstrate. The example also contains an implementation of a thumbnail viewer. -### Buffering state changes +## 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.