From f2a5de1bc31ea2aaa8ba321e6e87a95358b81175 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Thu, 28 Mar 2024 12:09:48 +0100 Subject: [PATCH 01/17] Clean up --- doc/creating-minimal-app.md | 2 -- doc/fullscreen.md | 2 -- 2 files changed, 4 deletions(-) diff --git a/doc/creating-minimal-app.md b/doc/creating-minimal-app.md index e3b9249b3..f960ebd30 100644 --- a/doc/creating-minimal-app.md +++ b/doc/creating-minimal-app.md @@ -53,7 +53,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,7 +87,6 @@ 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/) diff --git a/doc/fullscreen.md b/doc/fullscreen.md index 1b033e4b1..b4529c814 100644 --- a/doc/fullscreen.md +++ b/doc/fullscreen.md @@ -89,7 +89,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 +117,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. From 4809e5d5d7f6eec288c046f7949c9829b788270c Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Thu, 28 Mar 2024 13:07:35 +0100 Subject: [PATCH 02/17] Fix heading levels --- doc/abr.md | 12 ++++++------ doc/ads.md | 22 +++++++++++----------- doc/audio-control.md | 10 +++++----- doc/background.md | 12 ++++++------ doc/cast.md | 28 ++++++++++++++-------------- doc/creating-minimal-app.md | 20 ++++++++++---------- doc/drm.md | 14 +++++++------- doc/example-app.md | 4 ++-- doc/fullscreen.md | 16 ++++++++-------- doc/limitations.md | 4 ++-- doc/media_caching.md | 26 +++++++++++++------------- doc/migrating_v2.md | 8 ++++---- doc/pip.md | 24 ++++++++++++------------ doc/texttracks.md | 22 +++++++++++----------- doc/theoplayerview-component.md | 24 ++++++++++++------------ 15 files changed, 123 insertions(+), 123 deletions(-) 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..e4b017135 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) @@ -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. @@ -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 f960ebd30..d56a1835a 100644 --- a/doc/creating-minimal-app.md +++ b/doc/creating-minimal-app.md @@ -1,11 +1,11 @@ -## Creating a minimal demo app +# 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 +## 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) @@ -13,7 +13,7 @@ A user interface is added using the `@theoplayer/react-native-ui` package. - [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. @@ -94,7 +94,7 @@ or request a [free trial license](https://www.theoplayer.com/free-trial-theoplay ![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 @@ -137,7 +137,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: @@ -182,7 +182,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 @@ -196,7 +196,7 @@ 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 @@ -205,7 +205,7 @@ In addition, the project relies on webpack to create the bundle that is loaded i We refer to the [example application](example-app.md) and its [code](../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 @@ -213,7 +213,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. @@ -224,7 +224,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..4aacc4eab 100644 --- a/doc/example-app.md +++ b/doc/example-app.md @@ -1,4 +1,4 @@ -## Example Application +# 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 @@ -15,7 +15,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: diff --git a/doc/fullscreen.md b/doc/fullscreen.md index b4529c814..29e0d0597 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,7 +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 +## Table of Contents - [Presenting a fullscreen video player](#presenting-a-fullscreen-video-player) - [A separate player screen](#1-a-separate-player-screen) @@ -19,7 +19,7 @@ offer versatile applications beyond fullscreen display. - [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 +35,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 +44,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 +66,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 +79,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. @@ -129,7 +129,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/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 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 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..951410c73 100644 --- a/doc/texttracks.md +++ b/doc/texttracks.md @@ -1,9 +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 +## Table of Contents - [Types of text tracks](#types-of-text-tracks) - [Side-loaded text tracks](#side-loaded-text-tracks) @@ -12,7 +12,7 @@ Some of its key functionalities include text track selection, styling, and liste - [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 +26,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 +52,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 +65,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 +107,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 +120,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 +156,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 +176,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..c7bafaa81 100644 --- a/doc/theoplayerview-component.md +++ b/doc/theoplayerview-component.md @@ -1,4 +1,4 @@ -## The `THEOplayerView` Component +# 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,7 +12,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 +## Table of Contents - [Properties](#properties) - [Configuration](#configuration) @@ -23,7 +23,7 @@ bridges that map each THEO SDK API to the THEOplayerView component. - [Preview thumbnails](#preview-thumbnails) - [Buffering state changes](#buffering-state-changes) -### Properties +## Properties The `THEOplayerView` component supports the following list of properties. @@ -34,7 +34,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 +61,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 +92,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 +102,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 +126,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. From a19b8f66be8a74760bac42d52383fcb66080ded2 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Thu, 28 Mar 2024 14:50:08 +0100 Subject: [PATCH 03/17] Copy README to getting-started --- doc/getting-started.md | 110 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 doc/getting-started.md diff --git a/doc/getting-started.md b/doc/getting-started.md new file mode 100644 index 000000000..b4cca70a0 --- /dev/null +++ b/doc/getting-started.md @@ -0,0 +1,110 @@ +# React Native THEOplayer + +![](./doc/logo-react-native.png) ![](./doc/logo-theo.png) + +## License + +This projects falls under the license as defined in https://github.com/THEOplayer/license-and-disclaimer. + +## Table of Contents + +1. [Overview](#overview) +2. [Prerequisites](#prerequisites) +3. [How to use these guides](#how-to-use-these-guides) +4. [Features](#features) +5. [Available connectors](#available-connectors) +6. [Getting Started](#getting-started) + +## Overview + +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 use your existing THEOplayer SDK license or request a +[free trial account](https://www.theoplayer.com/free-trial-theoplayer?hsLang=en-us). + +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. + + + +## 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) | + +## Getting Started + +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. + +- [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) +- [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/) From 473dc70cea6d4fd71220e8ee9d4455073f614529 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Thu, 28 Mar 2024 14:56:46 +0100 Subject: [PATCH 04/17] Fix sidebar positions --- doc/creating-minimal-app.md | 4 ++++ doc/example-app.md | 4 ++++ doc/getting-started.md | 4 ++++ doc/theoplayerview-component.md | 4 ++++ 4 files changed, 16 insertions(+) diff --git a/doc/creating-minimal-app.md b/doc/creating-minimal-app.md index d56a1835a..117cb2d53 100644 --- a/doc/creating-minimal-app.md +++ b/doc/creating-minimal-app.md @@ -1,3 +1,7 @@ +--- +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`, diff --git a/doc/example-app.md b/doc/example-app.md index 4aacc4eab..1f4db0c26 100644 --- a/doc/example-app.md +++ b/doc/example-app.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 3 +--- + # Example Application The example application on our `react-native-theoplayer` diff --git a/doc/getting-started.md b/doc/getting-started.md index b4cca70a0..c7ad19f99 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 0 +--- + # React Native THEOplayer ![](./doc/logo-react-native.png) ![](./doc/logo-theo.png) diff --git a/doc/theoplayerview-component.md b/doc/theoplayerview-component.md index c7bafaa81..8db0928da 100644 --- a/doc/theoplayerview-component.md +++ b/doc/theoplayerview-component.md @@ -1,3 +1,7 @@ +--- +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 From 8a0e5537e35dbb88de68aeafba9445d229f4953c Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Thu, 28 Mar 2024 14:59:33 +0100 Subject: [PATCH 05/17] Fix sign up link --- README.md | 3 +-- doc/getting-started.md | 6 +++--- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index fd96ce401..8cb819818 100644 --- a/README.md +++ b/README.md @@ -39,8 +39,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), diff --git a/doc/getting-started.md b/doc/getting-started.md index c7ad19f99..04285fe92 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -42,9 +42,9 @@ For each platform, a dependency to the corresponding THEOplayer SDK is included - 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 use your existing THEOplayer SDK license or request a -[free trial account](https://www.theoplayer.com/free-trial-theoplayer?hsLang=en-us). +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), From 3e60d97aee463b647ca60de011b4569485ae46d7 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Thu, 28 Mar 2024 14:59:48 +0100 Subject: [PATCH 06/17] Rework getting started guide --- doc/getting-started.md | 79 +++++++++++++++++++----------------------- 1 file changed, 35 insertions(+), 44 deletions(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 04285fe92..44e6f5f3a 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -2,24 +2,7 @@ sidebar_position: 0 --- -# React Native THEOplayer - -![](./doc/logo-react-native.png) ![](./doc/logo-theo.png) - -## License - -This projects falls under the license as defined in https://github.com/THEOplayer/license-and-disclaimer. - -## Table of Contents - -1. [Overview](#overview) -2. [Prerequisites](#prerequisites) -3. [How to use these guides](#how-to-use-these-guides) -4. [Features](#features) -5. [Available connectors](#available-connectors) -6. [Getting Started](#getting-started) - -## Overview +# Getting started with React Native THEOplayer The `react-native-theoplayer` package provides a `THEOplayerView` component supporting video playback on the following platforms: @@ -36,6 +19,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 @@ -63,7 +47,7 @@ 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. - +![Features](features.svg) ## Available connectors @@ -71,7 +55,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) | @@ -83,32 +67,39 @@ 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. - -- [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) -- [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/) +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 + +[API Reference](https://theoplayer.github.io/react-native-theoplayer/api/) From 7282269b93f12f61ca0d86bb5ddf4e9d9659741e Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Tue, 2 Apr 2024 14:20:30 +0200 Subject: [PATCH 07/17] Remove manual ToCs --- doc/creating-minimal-app.md | 8 -------- doc/fullscreen.md | 9 --------- doc/texttracks.md | 9 --------- doc/theoplayerview-component.md | 11 ----------- 4 files changed, 37 deletions(-) diff --git a/doc/creating-minimal-app.md b/doc/creating-minimal-app.md index 117cb2d53..41480e690 100644 --- a/doc/creating-minimal-app.md +++ b/doc/creating-minimal-app.md @@ -9,14 +9,6 @@ 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 In the following steps we will be using `npm` as the Node.js package manager. diff --git a/doc/fullscreen.md b/doc/fullscreen.md index 29e0d0597..a7e96f2f2 100644 --- a/doc/fullscreen.md +++ b/doc/fullscreen.md @@ -10,15 +10,6 @@ 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 A native iOS or Android video player that transitions into fullscreen typically creates another activity diff --git a/doc/texttracks.md b/doc/texttracks.md index 951410c73..b83973874 100644 --- a/doc/texttracks.md +++ b/doc/texttracks.md @@ -3,15 +3,6 @@ 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 In this document we will differentiate between the following kinds of text tracks: diff --git a/doc/theoplayerview-component.md b/doc/theoplayerview-component.md index 8db0928da..7982f46f1 100644 --- a/doc/theoplayerview-component.md +++ b/doc/theoplayerview-component.md @@ -16,17 +16,6 @@ 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 The `THEOplayerView` component supports the following list of properties. From 5985c492f3a3caa745115091e18904168c2c7d96 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Tue, 2 Apr 2024 15:36:14 +0200 Subject: [PATCH 08/17] Fix links --- doc/ads.md | 4 ++-- doc/creating-minimal-app.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/ads.md b/doc/ads.md index e4b017135..df41f74ed 100644 --- a/doc/ads.md +++ b/doc/ads.md @@ -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 @@ -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 diff --git a/doc/creating-minimal-app.md b/doc/creating-minimal-app.md index 41480e690..7f04a8484 100644 --- a/doc/creating-minimal-app.md +++ b/doc/creating-minimal-app.md @@ -199,7 +199,7 @@ Deploying a web app requires a little more work. The example uses [react-native- 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 From 21f6700894df536c1d0247d633c973f1d75191c6 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Tue, 2 Apr 2024 16:02:46 +0200 Subject: [PATCH 09/17] Update link to API reference --- doc/getting-started.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 44e6f5f3a..7f444fd93 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -102,4 +102,5 @@ This section gives an overview of features, limitations and known issues: ## API Reference -[API Reference](https://theoplayer.github.io/react-native-theoplayer/api/) +See the [API Reference](https://theoplayer.github.io/react-native-theoplayer/api/) for detailed documentation +about all available components and functions. From 3707ec0e787ecb87ad9f5202cb0009d4b49b796d Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Tue, 2 Apr 2024 16:04:43 +0200 Subject: [PATCH 10/17] Align readme with getting started --- README.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 8cb819818..aa2701a5d 100644 --- a/README.md +++ b/README.md @@ -78,21 +78,25 @@ 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. +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 + +## 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) @@ -106,4 +110,8 @@ and discussed in the next section. Finally, an overview of features, limitations - [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/) + +## API Reference + +See the [API Reference](https://theoplayer.github.io/react-native-theoplayer/api/) for detailed documentation +about all available components and functions. From a7e5d13c42e6bba950d8498907c8eff020d351fc Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Tue, 2 Apr 2024 16:05:03 +0200 Subject: [PATCH 11/17] Fix indentation --- README.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index aa2701a5d..aa2afdfe6 100644 --- a/README.md +++ b/README.md @@ -97,19 +97,19 @@ and discussed in the next section. 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) +- [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 From a9341a4c199d396471ddbdf7bb0b678122d45fc9 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Tue, 2 Apr 2024 16:27:04 +0200 Subject: [PATCH 12/17] Replace underscores with dashes in file names --- CHANGELOG.md | 6 +++--- README.md | 4 ++-- doc/getting-started.md | 4 ++-- doc/{media_caching.md => media-caching.md} | 0 doc/{migrating_v2.md => migrating-v2.md} | 0 5 files changed, 7 insertions(+), 7 deletions(-) rename doc/{media_caching.md => media-caching.md} (100%) rename doc/{migrating_v2.md => migrating-v2.md} (100%) 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 aa2afdfe6..e18130ed4 100644 --- a/README.md +++ b/README.md @@ -105,8 +105,8 @@ This section gives an overview of features, limitations and known issues: - [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) +- [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) diff --git a/doc/getting-started.md b/doc/getting-started.md index 7f444fd93..bc20620f7 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -94,8 +94,8 @@ This section gives an overview of features, limitations and known issues: - [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) +- [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) diff --git a/doc/media_caching.md b/doc/media-caching.md similarity index 100% rename from doc/media_caching.md rename to doc/media-caching.md diff --git a/doc/migrating_v2.md b/doc/migrating-v2.md similarity index 100% rename from doc/migrating_v2.md rename to doc/migrating-v2.md From c30e0234f08993ffd8bee4c6fac84953a1a151a5 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Tue, 2 Apr 2024 16:30:50 +0200 Subject: [PATCH 13/17] Remove links for free trial licenses --- doc/creating-minimal-app.md | 3 +-- doc/example-app.md | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/creating-minimal-app.md b/doc/creating-minimal-app.md index 7f04a8484..0fb8230ad 100644 --- a/doc/creating-minimal-app.md +++ b/doc/creating-minimal-app.md @@ -85,8 +85,7 @@ 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/) -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) diff --git a/doc/example-app.md b/doc/example-app.md index 1f4db0c26..ebe2d5ec5 100644 --- a/doc/example-app.md +++ b/doc/example-app.md @@ -41,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: From aaf1f3073867b21cef5dbed876083d0df448a2a8 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Tue, 2 Apr 2024 17:42:26 +0200 Subject: [PATCH 14/17] Replace features.svg with a regular Markdown table --- README.md | 15 ++++- doc/features.svg | 130 ----------------------------------------- doc/getting-started.md | 15 ++++- 3 files changed, 28 insertions(+), 132 deletions(-) delete mode 100644 doc/features.svg diff --git a/README.md b/README.md index e18130ed4..0a618fe67 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,20 @@ 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. - +| 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 | ## Available connectors 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/getting-started.md b/doc/getting-started.md index bc20620f7..cbeeff446 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -47,7 +47,20 @@ 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. -![Features](features.svg) +| 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 | ## Available connectors From 9da33dbb35f180c02ad7ef0cf47dd92f1ad01718 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Tue, 2 Apr 2024 17:42:39 +0200 Subject: [PATCH 15/17] Tiny tweaks --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0a618fe67..c5bc40138 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 @@ -79,7 +80,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) | From be9cc078156dc16539cdc0f1d5dfc79601b10e74 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Tue, 2 Apr 2024 17:45:02 +0200 Subject: [PATCH 16/17] Update GitHub links to point to develop --- README.md | 2 +- doc/example-app.md | 2 +- doc/getting-started.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c5bc40138..e200d05b0 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,7 @@ functionality. Currently, the following connectors are available: 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), +[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) diff --git a/doc/example-app.md b/doc/example-app.md index ebe2d5ec5..61dc93b6d 100644 --- a/doc/example-app.md +++ b/doc/example-app.md @@ -5,7 +5,7 @@ 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), diff --git a/doc/getting-started.md b/doc/getting-started.md index cbeeff446..e57b484c0 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -85,7 +85,7 @@ functionality. Currently, the following connectors are available: 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), +[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) From a85b70f0f329021627b934987ba7e12a1ea54b87 Mon Sep 17 00:00:00 2001 From: Mattias Buelens Date: Wed, 3 Apr 2024 10:37:25 +0200 Subject: [PATCH 17/17] Use plain HTML tables --- README.md | 80 ++++++++++++++++++++++++++++++++++-------- doc/getting-started.md | 80 ++++++++++++++++++++++++++++++++++-------- 2 files changed, 132 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index e200d05b0..be8963a53 100644 --- a/README.md +++ b/README.md @@ -59,20 +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. -| 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 | +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
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 diff --git a/doc/getting-started.md b/doc/getting-started.md index e57b484c0..3e6fe411f 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -47,20 +47,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. -| 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 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
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