bitmovin-player-react-native 0.1.0 → 0.2.0

package/README.md

@@ -7,7 +7,7 @@ Official React Native bindings for Bitmovin's mobile Player SDKs.
 [![MIT License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
 [![Bitmovin Community](https://img.shields.io/discourse/users?label=community&server=https%3A%2F%2Fcommunity.bitmovin.com)](https://community.bitmovin.com/?utm_source=github&utm_medium=bitmovin-player-react-native&utm_campaign=dev-community)
 
-> :warning: **Beta Version**: The library is under active development. The current Beta release supports basic playback of unprotected video assets.
+> :warning: **Beta Version**: The library is under active development.
 
 - [Installation](#installation)
   - [Add package dependency](#add-package-dependency)
@@ -17,6 +17,8 @@ Official React Native bindings for Bitmovin's mobile Player SDKs.
   - [Setting up a license key](#setting-up-a-license-key)
   - [Accessing native `Player` instances](#accessing-native-player-instances)
   - [Listening to events](#listening-to-events)
+  - [Enabling DRM protection](#enabling-drm-protection)
+  - [Adding external subtitle tracks](#adding-subtitle-tracks)
 - [Contributing](#contributing)
 
 ## Installation
@@ -269,6 +271,166 @@ return (
 );
 ```
 
+### Enabling DRM protection
+
+> ⚠️ **Beta Version**: For now, only `FairPlay` is supported on iOS and
+> only `Widevine` is supported on Android. More DRM systems will be added in the future.
+
+Simple streaming of protected assets can be enabled with just a little configuration on `SourceConfig.drmConfig`:
+
+```typescript
+import { Platform } from 'react-native';
+import { SourceConfig, SourceType } from 'bitmovin-player-react-native';
+
+// Source configuration for protected assets.
+const drmSource: SourceConfig = {
+  // Protected stream URL.
+  url:
+    Platform.OS === 'ios'
+      ? 'https://fps.ezdrm.com/demo/video/ezdrm.m3u8' // iOS stream url
+      : 'https://bitmovin-a.akamaihd.net/content/art-of-motion_drm/mpds/11331.mpd', // Android stream url
+  // Stream type.
+  type: Platform.OS === 'ios' ? SourceType.HLS : SourceType.DASH,
+  // DRM setup.
+  // Each key in this object maps to a different DRM system config (`widevine` or `fairplay`).
+  drmConfig: {
+    // Widevine is the default and only DRM system supported on Android for now.
+    widevine: {
+      licenseUrl: 'https://cwip-shaka-proxy.appspot.com/no_auth',
+    },
+    // FairPlay is the default and only DRM system supported on iOS for now.
+    fairplay: {
+      licenseUrl:
+        'https://fps.ezdrm.com/api/licenses/09cc0377-6dd4-40cb-b09d-b582236e70fe',
+      certificateUrl: 'https://fps.ezdrm.com/demo/video/eleisure.cer',
+    },
+  },
+};
+```
+
+#### Prepare hooks
+
+In the native SDKs, some DRM properties like `message` and `license` can have their value transformed before use in order
+to enable some more complex use cases: such as extracting the `license` from a `JSON`, for example.
+
+In order to handle such transformations, it's possible to hook methods onto `SourceConfig.drmConfig` to proxy DRM values
+and potentially alter them:
+
+```typescript
+import { Platform } from 'react-native';
+import { SourceConfig, SourceType } from 'bitmovin-player-react-native';
+
+// Source configuration for protected assets.
+const drmSource: SourceConfig = {
+  // Protected stream URL.
+  url:
+    Platform.OS === 'ios'
+      ? 'https://fps.ezdrm.com/demo/video/ezdrm.m3u8' // iOS stream url
+      : 'https://bitmovin-a.akamaihd.net/content/art-of-motion_drm/mpds/11331.mpd', // Android stream url
+  // Stream type.
+  type: Platform.OS === 'ios' ? SourceType.HLS : SourceType.DASH,
+  // DRM setup.
+  drmConfig: {
+    // Widevine is the default and only DRM system supported on Android for now.
+    widevine: {
+      licenseUrl: 'https://cwip-shaka-proxy.appspot.com/no_auth',
+      // Data is passed as a base64 string and expects to return a base64 string.
+      prepareLicense: (license: string) => {
+        // Do something with the `license` value...
+        // And return processed data as base64 string.
+        return license; // base64 string
+      },
+    },
+    // FairPlay is the default and only DRM system supported on iOS for now.
+    fairplay: {
+      licenseUrl:
+        'https://fps.ezdrm.com/api/licenses/09cc0377-6dd4-40cb-b09d-b582236e70fe',
+      certificateUrl: 'https://fps.ezdrm.com/demo/video/eleisure.cer',
+      // Data is passed as a base64 string and expects to return a base64 string.
+      prepareLicense: (license: string) => {
+        // Do something with the `license` value...
+        // And return processed data as base64 string.
+        return license; // base64 string
+      },
+      // Data is passed as a base64 string and expects to return a base64 string.
+      prepareMessage: (message: string, assetId: string) => {
+        // Do something with the `assetId` and `message` values...
+        // And return processed data as base64 string.
+        return message; // base64 string
+      },
+    },
+  },
+};
+```
+
+The [`FairplayConfig`](https://github.com/bitmovin/bitmovin-player-react-native/blob/development/src/drm.ts#L10) interface provides a bunch of hooks that can be used to fetch and transform different DRM related data. Check out the [docs](https://github.com/bitmovin/bitmovin-player-react-native/blob/development/src/drm.ts#L10) for a complete list and detailed information on them.
+
+Also, don't forget to check out the [example](https://github.com/bitmovin/bitmovin-player-react-native/tree/development/example) app for a complete iOS/Android [DRM example](https://github.com/bitmovin/bitmovin-player-react-native/blob/development/example/src/screens/BasicDRMPlayback.tsx).
+
+### Adding external subtitle tracks
+
+Usually, subtitle tracks are provided in the manifest of your content (see [Enconding Manifests API](https://bitmovin.com/docs/encoding/api-reference/sections/manifests) for more information). And if they are provided this way, the player already recognizes them and show them in the subtitles selection menu without any further configuration.
+
+Otherwise, it's also possible to add external tracks via the subtitle API:
+
+```typescript
+import { Platform } from 'react-native';
+import {
+  SourceConfig,
+  SourceType,
+  SubtitleFormat,
+} from 'bitmovin-player-react-native';
+
+// Source config with an external subtitle track.
+const config: SourceConfig = {
+  url:
+    Platform.OS === 'ios'
+      ? 'https://bitmovin-a.akamaihd.net/content/sintel/hls/playlist.m3u8'
+      : 'https://bitmovin-a.akamaihd.net/content/sintel/sintel.mpd',
+  type: Platform.OS === 'ios' ? SourceType.HLS : SourceType.DASH,
+  poster: 'https://bitmovin-a.akamaihd.net/content/sintel/poster.png',
+  // External subtitle tracks list to be added to this source.
+  subtitleTracks: [
+    // You can select 'Custom English' in the subtitles menu.
+    {
+      // The URL of the subtitle file. Required.
+      url: 'https://bitdash-a.akamaihd.net/content/sintel/subtitles/subtitles_en.vtt',
+      // External file format.
+      // Supports `.vtt`, `.ttml` and `.cea` extensions.
+      //
+      // This option can be left empty since the player automatically recognizes the format
+      // from the provided url most of the time.
+      format: SubtitleFormat.VTT,
+      // Label for this track shown under the selection menu. Required.
+      label: 'Custom English',
+      // The IETF BCP 47 language tag associated with this track. Required.
+      language: 'en',
+      // The unique identifier used for this track.
+      // The default value for this options is a randomly generated UUID.
+      identifier: 'sub1',
+      // This track is considered the default if set to `true`.
+      // The default value for this option is `false`.
+      isDefault: false,
+      // If set to `true` it means that the player should automatically select and switch this
+      // subtitle according to the selected audio language. Forced subtitles do not appear in
+      // `Player.getAvailableSubtitles`.
+      //
+      // The default value for this option is `false`.
+      isForced: false,
+    },
+    // You may add even more tracks to the list...
+  ],
+};
+```
+
+The supported `PlayerView` events for subtitles are:
+
+- `onSubtitleAdded`
+- `onSubtitleRemoved`
+- `onSubtitleChanged`
+
+You might check out a complete subtitle example in the [`example/`](https://github.com/bitmovin/bitmovin-player-react-native/tree/development/example) app.
+
 ## Contributing
 
 See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

package/RNBitmovinPlayer.podspec

@@ -10,10 +10,10 @@ Pod::Spec.new do |s|
   s.license      = package["license"]
   s.authors      = package["author"]
 
-  s.platforms    = { :ios => "12.0" }
+  s.platforms    = { :ios => "12.4" }
   s.source       = {
-    :git => "https://github.com/bitmovin/player-react-native-bridge.git",
-    :tag => "#{s.version}"
+    :git => "https://github.com/bitmovin/bitmovin-player-react-native.git",
+    :tag => "v#{s.version}"
   }
 
   s.source_files = "ios/**/*.{h,m,mm,swift}"

package/android/src/main/java/com/bitmovin/player/reactnative/DrmModule.kt

@@ -0,0 +1,191 @@
+package com.bitmovin.player.reactnative
+
+import android.util.Base64
+import com.bitmovin.player.api.drm.PrepareLicenseCallback
+import com.bitmovin.player.api.drm.PrepareMessageCallback
+import com.bitmovin.player.api.drm.WidevineConfig
+import com.bitmovin.player.reactnative.converter.JsonConverter
+import com.facebook.react.bridge.*
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.UIManagerModule
+import java.util.concurrent.locks.Condition
+import java.util.concurrent.locks.ReentrantLock
+import kotlin.concurrent.withLock
+
+/**
+ * Represents some operation that transforms data as bytes.
+ */
+typealias PrepareCallback = (ByteArray) -> ByteArray
+
+@ReactModule(name = DrmModule.name)
+class DrmModule(private val context: ReactApplicationContext) : ReactContextBaseJavaModule(context) {
+    /**
+     * In-memory mapping from `nativeId`s to `WidevineConfig` instances.
+     */
+    private val drmConfigs: Registry<WidevineConfig> = mutableMapOf()
+
+    /**
+     * Module's local lock object used to sync calls between Kotlin and JS.
+     */
+    private val lock = ReentrantLock()
+
+    /**
+     * Mapping between an object's `nativeId` and the value that'll be returned by its `prepareMessage` callback.
+     */
+    private val preparedMessages: Registry<String> = mutableMapOf()
+
+    /**
+     *  Lock condition used to sync read/write operations on `preparedMessages`.
+     */
+    private val preparedMessagesCondition = lock.newCondition()
+
+    /**
+     * Mapping between an object's `nativeId` and the value that'll be returned by its `prepareLicense` callback.
+     */
+    private val preparedLicenses: Registry<String> = mutableMapOf()
+
+    /**
+     *  Lock condition used to sync read/write operations on `preparedMessages`.
+     */
+    private val preparedLicensesCondition = lock.newCondition()
+
+    /**
+     * JS exported module name.
+     */
+    companion object {
+        const val name = "DrmModule"
+    }
+    override fun getName() = DrmModule.name
+
+    /**
+     * Fetches the `WidevineConfig` instance associated with `nativeId` from internal drmConfigs.
+     * @param nativeId `WidevineConfig` instance ID.
+     * @return The associated `WidevineConfig` instance or `null`.
+     */
+    fun getConfig(nativeId: NativeId?): WidevineConfig? {
+        if (nativeId == null) {
+            return null
+        }
+        return drmConfigs[nativeId]
+    }
+
+    /**
+     * Creates a new `WidevineConfig` instance inside the internal drmConfigs using the provided `config` object.
+     * @param nativeId ID to associate with the `WidevineConfig` instance.
+     * @param config `DrmConfig` object received from JS.
+     */
+    @ReactMethod
+    fun initWithConfig(nativeId: NativeId, config: ReadableMap?) {
+        uiManager()?.addUIBlock {
+            if (!drmConfigs.containsKey(nativeId) && config != null) {
+                JsonConverter.toWidevineConfig(config)?.let {
+                    drmConfigs[nativeId] = it
+                    initPrepareMessage(nativeId, config)
+                    initPrepareLicense(nativeId, config)
+                }
+            }
+        }
+    }
+
+    /**
+     * Removes the `WidevineConfig` instance associated with `nativeId` from the internal drmConfigs.
+     * @param nativeId `WidevineConfig` to be disposed.
+     */
+    @ReactMethod
+    fun destroy(nativeId: NativeId) {
+        drmConfigs.remove(nativeId)
+    }
+
+    /**
+     * Function called from JS to store the computed `prepareMessage` return value for `nativeId`.
+     */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun setPreparedMessage(nativeId: NativeId, message: String) {
+        lock.withLock {
+            preparedMessages[nativeId] = message
+            preparedMessagesCondition.signal()
+        }
+    }
+
+    /**
+     * Function called from JS to store the computed `prepareLicense` return value for `nativeId`.
+     */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun setPreparedLicense(nativeId: NativeId, license: String) {
+        lock.withLock {
+            preparedLicenses[nativeId] = license
+            preparedLicensesCondition.signal()
+        }
+    }
+
+    /**
+     * Initialize the `prepareMessage` block in the `WidevineConfig` associated with `nativeId`.
+     * @param nativeId Instance ID.
+     * @param config `DrmConfig` config object sent from JS.
+     */
+    private fun initPrepareMessage(nativeId: NativeId, config: ReadableMap) {
+        val widevineConfig = drmConfigs[nativeId]
+        val widevineJson = config.getMap("widevine")
+        if (widevineConfig != null && widevineJson != null && widevineJson.hasKey("prepareMessage")) {
+            val prepareMessage = createPrepareCallback(
+                nativeId,
+                "onPrepareMessage",
+                preparedMessages,
+                preparedMessagesCondition
+            )
+            widevineConfig.prepareMessageCallback = PrepareMessageCallback {
+                prepareMessage(it)
+            }
+        }
+    }
+
+    /**
+     * Initialize the `prepareLicense` block in the `WidevineConfig` associated with `nativeId`.
+     * @param nativeId Instance ID.
+     * @param config `DrmConfig` config object sent from JS.
+     */
+    private fun initPrepareLicense(nativeId: NativeId, config: ReadableMap) {
+        val widevineConfig = drmConfigs[nativeId]
+        val widevineJson = config.getMap("widevine")
+        if (widevineConfig != null && widevineJson != null && widevineJson.hasKey("prepareLicense")) {
+            val prepareLicense = createPrepareCallback(
+                nativeId,
+                "onPrepareLicense",
+                preparedLicenses,
+                preparedLicensesCondition
+            )
+            widevineConfig.prepareLicenseCallback = PrepareLicenseCallback {
+                prepareLicense(it)
+            }
+        }
+    }
+
+    /**
+     * Creates the body of a preparation callback e.g. `prepareMessage`, `prepareLicense`, etc.
+     * @param nativeId Instance ID.
+     * @param method JS prepare callback name.
+     * @param registry Registry where JS preparation result will be stored.
+     * @return The preparation callback function.
+     */
+    private fun createPrepareCallback(
+        nativeId: NativeId,
+        method: String,
+        registry: Registry<String>,
+        registryCondition: Condition
+    ): PrepareCallback = {
+        val args = Arguments.createArray()
+        args.pushString(Base64.encodeToString(it, Base64.NO_WRAP))
+        context.catalystInstance.callFunction("DRM-${nativeId}", method, args as NativeArray)
+        lock.withLock {
+            registryCondition.await()
+            val result = registry[nativeId]
+            Base64.decode(result, Base64.NO_WRAP)
+        }
+    }
+
+    /**
+     * Helper function that returns the initialized `UIManager` instance.
+     */
+    private fun uiManager(): UIManagerModule? =
+        context.getNativeModule(UIManagerModule::class.java)
+}