bitmovin-player-react-native 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Bitmovin Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+# Bitmovin Player React Native
+
+Official React Native bindings for Bitmovin's mobile Player SDKs.
+
+[![npm](https://img.shields.io/npm/v/bitmovin-player-react-native)](https://www.npmjs.com/package/bitmovin-player-react-native)
+![Supports Android and iOS](https://img.shields.io/badge/platforms-android%20%7C%20ios-lightgrey.svg)
+[![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.
+
+- [Installation](#installation)
+  - [Add package dependency](#add-package-dependency)
+  - [Setup iOS Player SDK](#setup-ios-player-sdk)
+  - [Setup Android Player SDK](#setup-android-player-sdk)
+- [Getting Started](#getting-started)
+  - [Setting up a license key](#setting-up-a-license-key)
+  - [Accessing native `Player` instances](#accessing-native-player-instances)
+  - [Listening to events](#listening-to-events)
+- [Contributing](#contributing)
+
+## Installation
+
+Since Bitmovin's native SDKs are distributed through custom [Cocoapods](https://github.com/bitmovin/cocoapod-specs) and [Maven](https://artifacts.bitmovin.com/ui/native/public-releases) repositories, the installation cannot be managed by React Native's Autolink and requires some extra steps. Please refer to the installation instructions for each platform below. For more information on integrating the native SDKs, refer to the [Getting Started guides](https://bitmovin.com/docs/getting-started).
+
+### Add package dependency
+
+This library is available as an [NPM package](https://www.npmjs.com/package/bitmovin-player-react-native) and may be added as a dependency to your project using any node-based package manager, e.g.
+
+> npm
+
+```sh
+npm install bitmovin-player-react-native --save
+```
+
+> yarn
+
+```sh
+yarn add bitmovin-player-react-native
+```
+
+### Setup iOS Player SDK
+
+If you ran `pod install` after installing the node package and received an error similar to the one below, it is because Bitmovin's custom cocoapods repository has not been added to the `Podfile` and the [`iOS Player SDK`](https://github.com/bitmovin/bitmovin-player-ios-samples) could not be resolved:
+
+```
+[!] Unable to find a specification for `BitmovinPlayer (= 3.xx.x)` depended upon by `RNBitmovinPlayer`
+
+You have either:
+ * out-of-date source repos which you can update with `pod repo update` or with `pod install --repo-update`.
+ * mistyped the name or version.
+ * not added the source repo that hosts the Podspec to your Podfile.
+```
+
+To fix above error, open your `ios/Podfile` and set up Bitmovin's pods source url:
+
+```ruby
+require_relative '../node_modules/react-native/scripts/react_native_pods'
+require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'
+
+# Bitmovin pods source url
+source 'https://github.com/bitmovin/cocoapod-specs.git'
+
+# iOS version should be 12 or greater.
+# If you are running RN 0.69 you should be fine already.
+platform :ios, '12.4'
+install! 'cocoapods', :deterministic_uuids => false
+
+target 'MyApp' do
+  config = use_native_modules!
+
+  # Rest of Podfile...
+```
+
+Now run `pod install` again (try with `--repo-update` if the error persists) - the error should now be resolved.
+
+### Setup Android Player SDK
+
+The Android setup also needs an extra step in order to correctly resolve the [Android Player SDK](https://github.com/bitmovin/bitmovin-player-android-samples) native dependency.
+
+Just make sure to add Bitmovin's artifacts repository to the `allprojects.repositories` section of your `android/build.gradle`:
+
+```groovy
+allprojects {
+    repositories {
+        maven { url("$rootDir/../node_modules/react-native/android") }
+        maven { url("$rootDir/../node_modules/jsc-android/dist") }
+        mavenCentral {
+            content {
+                excludeGroup "com.facebook.react"
+            }
+        }
+        google()
+        maven { url 'https://www.jitpack.io' }
+        // Add Bitmovin's artifacts repository url
+        maven { url 'https://artifacts.bitmovin.com/artifactory/public-releases' }
+    }
+}
+```
+
+## Getting Started
+
+The following is the simplest working component one can create using this library:
+
+```typescript
+import React, { useEffect, useCallback } from 'react';
+import { View, Platform, StyleSheet } from 'react-native';
+import {
+  usePlayer,
+  SourceType,
+  PlayerView,
+} from 'bitmovin-player-react-native';
+
+export default function PlayerSample() {
+  // The `usePlayer` hook creates or references a certain native `Player`
+  // instance from within any component.
+  const player = usePlayer({
+    // The only required parameter is the license key but it can be omitted from code upon correct
+    // Info.plist/AndroidManifest.xml configuration.
+    //
+    // Head to `Setting up a license key` for more information.
+    licenseKey: '<ENTER-YOUR-LICENSE-KEY>',
+  });
+
+  useEffect(() => {
+    // Load a streamable video source during component's initialization.
+    player.load({
+      // Select url and type dependeding on the running platform.
+      url:
+        Platform.OS === 'ios'
+          ? // HLS for iOS
+            'https://bitmovin-a.akamaihd.net/content/MI201109210084_1/m3u8s/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.m3u8'
+          : // Dash for Android
+            'https://bitmovin-a.akamaihd.net/content/MI201109210084_1/mpds/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.mpd',
+      type: Platform.OS === 'ios' ? SourceType.HLS : SourceType.DASH,
+      // Optionally set a title that will appear at player's top-left corner.
+      title: 'Art of Motion',
+      // Optionally load a poster image over the player.
+      poster:
+        'https://bitmovin-a.akamaihd.net/content/MI201109210084_1/poster.jpg',
+      // Optionally set whether poster image will persist over player.
+      // Useful for audio-only streams. Default to false.
+      isPosterPersistent: false,
+    });
+  }, [player]);
+
+  // onReady is called when the player has downloaded initial
+  // video and audio and is ready to start playback.
+  const onReady = useCallback(
+    (event) => {
+      // Start playback
+      player.play();
+      // Print event timestamp
+      console.log(event.timestamp);
+    },
+    [player]
+  );
+
+  // Make sure to pass the `player` prop in `PlayerView`.
+  return (
+    <View style={styles.flex1}>
+      <PlayerView style={styles.flex1} player={player} onReady={onReady} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  flex1: {
+    flex: 1,
+  },
+});
+```
+
+If you're interested in a complete running example, head to [`example/`](https://github.com/bitmovin/bitmovin-player-react-native/tree/main/example).
+
+### Setting up a license key
+
+First of all, create a license key on the [Dashboard](https://bitmovin.com/dashboard) and then make sure to associate your iOS app bundle id with it (see more [here](https://bitmovin.com/docs/player/getting-started/ios#step-3-configure-your-player-license)).
+
+Then your license key can be either set from code or by configuring `Info.plist` and `AndroidManifest.xml`.
+
+#### Configuring through code
+
+```typescript
+// Simply pass the `licenseKey` property to `PlayerConfig` when instantiating a player.
+
+// With hooks
+import { usePlayer } from 'bitmovin-player-react-native';
+const player = usePlayer({
+  licenseKey: '<ENTER-YOUR-LICENSE-KEY>',
+});
+
+// Without hooks
+import { Player } from 'bitmovin-player-react-native';
+const player = new Player({
+  // Make sure to use React.createRef if instantiating inside a component.
+  licenseKey: '<ENTER-YOUR-LICENSE-KEY>',
+});
+```
+
+#### Configuring `Info.plist`
+
+Add the following lines to the `<dict>` section of your `ios/Info.plist`:
+
+```xml
+<key>BitmovinPlayerLicenseKey</key>
+<string>ENTER-YOUR-LICENSE-KEY</string>
+```
+
+#### Configuring `AndroidManifest.xml`
+
+Add the following line to the `<application>` section of your `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<meta-data android:name="BITMOVIN_PLAYER_LICENSE_KEY" android:value="ENTER-YOUR-LICENSE-KEY" />
+```
+
+### Accessing native `Player` instances
+
+When you instantiate a player with `usePlayer` or `new Player()` from javascript, you're actually either creating a new `Player` instance in the native side (see [SDKs docs](https://bitmovin.com/docs/player/sdks) for more info) or referencing an existing one.
+
+So it means that a player with the same `nativeId` in two different parts of the code is referencing the same in-memory instance internally.
+
+**Example**
+
+Both components in the example below are referencing the same native `Player` indexed as `my-player`. And even though each `<PlayerView />` creates a different `View` internally, the `Player` instance (which is a separate thing) remains the same. It just gets attached to a different view.
+
+```typescript
+// Using `usePlayer`
+export const CompA = () => {
+  // Same `player` as in `CompB`.
+  const player = usePlayer({
+    nativeId: 'my-player',
+  });
+  return <PlayerView player={player} />;
+};
+
+// Using `new Player()`
+export const CompB = () => {
+  // Same `player` as in `CompA`.
+  const player = useRef(
+    new Player({
+      nativeId: 'my-player',
+    })
+  );
+  return <PlayerView player={player.current} />;
+};
+```
+
+### Listening to events
+
+Both player and source events can be registered from `PlayerView`, but not all of them. For a complete list of the events currently available, checkout [`EventProps`](https://github.com/bitmovin/bitmovin-player-react-native/blob/main/src/components/PlayerView/events.ts#L29) and [`events.ts`](https://github.com/bitmovin/bitmovin-player-react-native/blob/main/src/events.ts).
+
+To register an event callback, just pass its name prefixed with `on` as a `PlayerView` prop:
+
+```typescript
+return (
+  <PlayerView
+    onReady={onReady}
+    onMuted={onMuted}
+    onPaused={onPaused}
+    onPlayerActive={onPlayerActive}
+    onSourceLoaded={onSourceLoaded}
+    onPlayerError={onPlayerError}
+    onSourceError={onSourceError}
+    onPlaybackFinished={onPlaybackFinished}
+    {...}
+  />
+);
+```
+
+## Contributing
+
+See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

package/RNBitmovinPlayer.podspec

@@ -0,0 +1,23 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "RNBitmovinPlayer"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => "12.0" }
+  s.source       = {
+    :git => "https://github.com/bitmovin/player-react-native-bridge.git",
+    :tag => "#{s.version}"
+  }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+
+  s.dependency "React-Core"
+  s.dependency "BitmovinPlayer", "3.23.0"
+end

package/android/build.gradle

@@ -0,0 +1,55 @@
+buildscript {
+    ext {
+        kotlinVersion = '1.7.0'
+        androidToolsVersion = '7.0.4'
+    }
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath "com.android.tools.build:gradle:$androidToolsVersion"
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+repositories {
+    mavenLocal()
+    maven {
+        // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm
+        url "$rootDir/../node_modules/react-native/android"
+    }
+    google()
+    mavenCentral()
+}
+
+android {
+    compileSdk 31
+    defaultConfig {
+        minSdkVersion 21
+        targetSdkVersion 31
+        versionCode 1
+        versionName '1.0'
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+    lintOptions {
+        disable 'GradleCompatible'
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+}
+
+dependencies {
+    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlinVersion"
+    implementation 'com.bitmovin.player:player:3.20.0'
+    implementation 'com.facebook.react:react-native:+'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,4 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+          package="com.bitmovin.player.reactnative">
+
+</manifest>

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

@@ -0,0 +1,279 @@
+package com.bitmovin.player.reactnative
+
+import com.bitmovin.player.api.Player
+import com.bitmovin.player.reactnative.converter.JsonConverter
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.module.annotations.ReactModule;
+import com.facebook.react.uimanager.UIManagerModule
+import java.util.UUID
+
+@ReactModule(name = PlayerModule.name)
+class PlayerModule(private val context: ReactApplicationContext) : ReactContextBaseJavaModule(context) {
+    /**
+     * In-memory mapping of `id` <-> `Player`.
+     */
+    private var registry: MutableMap<String, Player> = mutableMapOf()
+
+    /**
+     * Exported module name to JS.
+     */
+    companion object {
+        const val name = "PlayerModule"
+    }
+    override fun getName() = PlayerModule.name
+
+    /**
+     * Fetch the `Player` instance with id equal to `playerId` inside this module's `registry`.
+     * @param playerId Target player to look inside registry.
+     */
+    fun getPlayer(playerId: String?): Player? {
+        if (playerId == null) {
+            return null
+        }
+        return registry[playerId]
+    }
+
+    /**
+     * Synchronously generate a random UUID for `Player`s native id when no `nativeId` is provided
+     * by the user.
+     * @return Random UUID RFC 4122 version 4.
+     */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun generateUUIDv4(): String = UUID.randomUUID().toString()
+
+    /**
+     * Create a new `Player` instance for the given `config` if no one exists already.
+     * @param config Player configuration options sent from JS.
+     */
+    @ReactMethod
+    fun initWithConfig(playerId: String, config: ReadableMap?) {
+        uiManager()?.addUIBlock {
+            if (!registry.containsKey(playerId)) {
+                JsonConverter.toPlayerConfig(config)?.let {
+                    registry[playerId] = Player.create(context, it)
+                }
+            }
+        }
+    }
+
+    /**
+     * Load the source of the given `playerId` with `config` options from JS.
+     * @param playerId Target player.
+     * @param config Source configuration options from JS.
+     */
+    @ReactMethod
+    fun loadSource(playerId: String, config: ReadableMap?) {
+        uiManager()?.addUIBlock {
+            JsonConverter.toSourceConfig(config)?.let {
+                registry[playerId]?.load(it)
+            }
+        }
+    }
+
+    /**
+     * Call `.unload()` on `playerId`'s player.
+     * @param playerId Target player Id.
+     */
+    @ReactMethod
+    fun unload(playerId: String) {
+        uiManager()?.addUIBlock {
+            registry[playerId]?.unload()
+        }
+    }
+
+    /**
+     * Call `.play()` on `playerId`'s player.
+     * @param playerId Target player Id.
+     */
+    @ReactMethod
+    fun play(playerId: String) {
+        uiManager()?.addUIBlock {
+            registry[playerId]?.play()
+        }
+    }
+
+    /**
+     * Call `.pause()` on `playerId`'s player.
+     * @param playerId Target player Id.
+     */
+    @ReactMethod
+    fun pause(playerId: String) {
+        uiManager()?.addUIBlock {
+            registry[playerId]?.pause()
+        }
+    }
+
+    /**
+     * Call `.seek(time:)` on `playerId`'s player.
+     * @param playerId Target player Id.
+     * @param time Seek time in seconds.
+     */
+    @ReactMethod
+    fun seek(playerId: String, time: Double) {
+        uiManager()?.addUIBlock {
+            registry[playerId]?.seek(time)
+        }
+    }
+
+    /**
+     * Call `.mute()` on `playerId`'s player.
+     * @param playerId Target player Id.
+     */
+    @ReactMethod
+    fun mute(playerId: String) {
+        uiManager()?.addUIBlock {
+            registry[playerId]?.mute()
+        }
+    }
+
+    /**
+     * Call `.unmute()` on `playerId`'s player.
+     * @param playerId Target player Id.
+     */
+    @ReactMethod
+    fun unmute(playerId: String) {
+        uiManager()?.addUIBlock {
+            registry[playerId]?.unmute()
+        }
+    }
+
+    /**
+     * Call `.destroy()` on `playerId`'s player.
+     * @param playerId Target player Id.
+     */
+    @ReactMethod
+    fun destroy(playerId: String) {
+        uiManager()?.addUIBlock {
+            registry[playerId]?.destroy()
+        }
+    }
+
+    /**
+     * Call `.setVolume(volume:)` on `playerId`'s player.
+     * @param playerId Target player Id.
+     * @param volume Volume level integer between 0 to 100.
+     */
+    @ReactMethod
+    fun setVolume(playerId: String, volume: Int) {
+        uiManager()?.addUIBlock {
+            registry[playerId]?.volume = volume
+        }
+    }
+
+    /**
+     * Resolve `playerId`'s current volume.
+     * @param playerId Target player Id.
+     * @param promise JS promise object.
+     */
+    @ReactMethod
+    fun getVolume(playerId: String, promise: Promise) {
+        uiManager()?.addUIBlock {
+            promise.resolve(registry[playerId]?.volume)
+        }
+    }
+
+    /**
+     * Resolve the source of `playerId`'s player.
+     * @param playerId Target player Id.
+     * @param promise JS promise object.
+     */
+    @ReactMethod
+    fun source(playerId: String, promise: Promise) {
+        uiManager()?.addUIBlock {
+            promise.resolve(JsonConverter.fromSource(registry[playerId]?.source))
+        }
+    }
+
+    /**
+     * Resolve `playerId`'s current playback time.
+     * @param playerId Target player Id.
+     * @param promise JS promise object.
+     */
+    @ReactMethod
+    fun currentTime(playerId: String, mode: String?, promise: Promise) {
+        uiManager()?.addUIBlock {
+            var timeOffset: Double = 0.0
+            if (mode != null) {
+                timeOffset = if (mode == "relative") {
+                    registry[playerId]?.playbackTimeOffsetToRelativeTime ?: 0.0
+                } else {
+                    registry[playerId]?.playbackTimeOffsetToAbsoluteTime ?: 0.0
+                }
+            }
+            val currentTime = registry[playerId]?.currentTime
+            if (currentTime != null) {
+                promise.resolve(currentTime + timeOffset)
+            }
+        }
+    }
+
+    /**
+     * Resolve `playerId`'s current source duration.
+     * @param playerId Target player Id.
+     * @param promise JS promise object.
+     */
+    @ReactMethod
+    fun duration(playerId: String, promise: Promise) {
+        uiManager()?.addUIBlock {
+            promise.resolve(registry[playerId]?.duration)
+        }
+    }
+
+    /**
+     * Resolve `playerId`'s current muted state.
+     * @param playerId Target player Id.
+     * @param promise JS promise object.
+     */
+    @ReactMethod
+    fun isMuted(playerId: String, promise: Promise) {
+        uiManager()?.addUIBlock {
+            promise.resolve(registry[playerId]?.isMuted)
+        }
+    }
+
+    /**
+     * Resolve `playerId`'s current playing state.
+     * @param playerId Target player Id.
+     * @param promise JS promise object.
+     */
+    @ReactMethod
+    fun isPlaying(playerId: String, promise: Promise) {
+        uiManager()?.addUIBlock {
+            promise.resolve(registry[playerId]?.isPlaying)
+        }
+    }
+
+    /**
+     * Resolve `playerId`'s current paused state.
+     * @param playerId Target player Id.
+     * @param promise JS promise object.
+     */
+    @ReactMethod
+    fun isPaused(playerId: String, promise: Promise) {
+        uiManager()?.addUIBlock {
+            promise.resolve(registry[playerId]?.isPaused)
+        }
+    }
+
+    /**
+     * Resolve `playerId`'s current live state.
+     * @param playerId Target player Id.
+     * @param promise JS promise object.
+     */
+    @ReactMethod
+    fun isLive(playerId: String, promise: Promise) {
+        uiManager()?.addUIBlock {
+            promise.resolve(registry[playerId]?.isLive)
+        }
+    }
+
+    /**
+     * Helper function that returns the initialized `UIManager` instance.
+     */
+    private fun uiManager(): UIManagerModule? =
+        context.getNativeModule(UIManagerModule::class.java)
+}