bitmovin-player-react-native 0.3.1 → 0.5.0

package/src/events.ts

@@ -1,4 +1,13 @@
+import {
+  Ad,
+  AdBreak,
+  AdConfig,
+  AdItem,
+  AdQuartile,
+  AdSourceType,
+} from './advertising';
 import { SubtitleTrack } from './subtitleTrack';
+import { VideoQuality } from './media';
 
 /**
  * Base event type for all events.
@@ -158,6 +167,16 @@ export interface SeekEvent extends Event {
  */
 export interface SeekedEvent extends Event {}
 
+/**
+ * Emitted when the player begins to stall and to buffer due to an empty buffer.
+ */
+export interface StallStartedEvent extends Event {}
+
+/**
+ * Emitted when the player ends stalling, due to enough data in the buffer.
+ */
+export interface StallEndedEvent extends Event {}
+
 /**
  * Emitted when the current playback time has changed.
  */
@@ -243,3 +262,239 @@ export interface SubtitleChangedEvent extends Event {
    */
   newSubtitleTrack: SubtitleTrack;
 }
+
+/**
+ * Emitted when the player enters Picture in Picture mode.
+ *
+ * @platform iOS, Android
+ */
+export interface PictureInPictureEnterEvent extends Event {}
+
+/**
+ * Emitted when the player exits Picture in Picture mode.
+ *
+ * @platform iOS, Android
+ */
+export interface PictureInPictureExitEvent extends Event {}
+
+/**
+ * Emitted when the player has finished entering Picture in Picture mode on iOS.
+ *
+ * @platform iOS
+ */
+export interface PictureInPictureEnteredEvent extends Event {}
+
+/**
+ * Emitted when the player has finished exiting Picture in Picture mode on iOS.
+ *
+ * @platform iOS
+ */
+export interface PictureInPictureExitedEvent extends Event {}
+
+/**
+ * Emitted when the fullscreen functionality has been enabled.
+ *
+ * @platform iOS, Android
+ */
+export interface FullscreenEnabledEvent extends Event {}
+
+/**
+ * Emitted when the fullscreen functionality has been disabled.
+ *
+ * @platform iOS, Android
+ */
+export interface FullscreenDisabledEvent extends Event {}
+
+/**
+ * Emitted when the player enters fullscreen mode.
+ *
+ * @platform iOS, Android
+ */
+export interface FullscreenEnterEvent extends Event {}
+
+/**
+ * Emitted when the player exits fullscreen mode.
+ *
+ * @platform iOS, Android
+ */
+export interface FullscreenExitEvent extends Event {}
+
+/**
+ * Emitted when the availability of the Picture in Picture mode changed on Android.
+ *
+ * @platform Android
+ */
+export interface PictureInPictureAvailabilityChangedEvent extends Event {
+  /**
+   * Whether Picture in Picture is available.
+   */
+  isPictureInPictureAvailable: boolean;
+}
+
+/**
+ * Emitted when an ad break has started.
+ */
+export interface AdBreakStartedEvent extends Event {
+  /**
+   * The `AdBreak` that has started.
+   */
+  adBreak?: AdBreak;
+}
+
+/**
+ * Emitted when an ad break has finished.
+ */
+export interface AdBreakFinishedEvent extends Event {
+  /**
+   * The `AdBreak` that has finished.
+   */
+  adBreak?: AdBreak;
+}
+
+/**
+ * Emitted when the playback of an ad has started.
+ */
+export interface AdStartedEvent extends Event {
+  /**
+   * The `Ad` this event is related to.
+   */
+  ad?: Ad;
+  /**
+   * The target URL to open once the user clicks on the ad.
+   */
+  clickThroughUrl?: string;
+  /**
+   * The `AdSourceType` of the started `Ad`.
+   */
+  clientType?: AdSourceType;
+  /**
+   * The duration of the ad in seconds.
+   */
+  duration: number;
+  /**
+   * The index of the ad in the queue.
+   */
+  indexInQueue: number;
+  /**
+   * The position of the corresponding `Ad`.
+   */
+  position?: string;
+  /**
+   * The skip offset of the ad in seconds.
+   */
+  skipOffset: number;
+  /**
+   * The content time at which the `Ad` is played.
+   */
+  timeOffset: number;
+}
+
+/**
+ * Emitted when an ad has finished playback.
+ */
+export interface AdFinishedEvent extends Event {
+  /**
+   * The `Ad` that finished playback.
+   */
+  ad?: Ad;
+}
+
+/**
+ * Emitted when an error with the ad playback occurs.
+ */
+export interface AdErrorEvent extends ErrorEvent {
+  /**
+   * The `AdConfig` for which the ad error occurred.
+   */
+  adConfig?: AdConfig;
+  /**
+   * The `AdItem` for which the ad error occurred.
+   */
+  adItem?: AdItem;
+}
+
+/**
+ * Emitted when an ad was clicked.
+ */
+export interface AdClickedEvent extends Event {
+  /**
+   * The click through url of the ad.
+   */
+  clickThroughUrl?: string;
+}
+
+/**
+ * Emitted when an ad was skipped.
+ */
+export interface AdSkippedEvent extends Event {
+  /**
+   * The `Ad` that was skipped.
+   */
+  ad?: Ad;
+}
+
+/**
+ * Emitted when the playback of an ad has progressed over a quartile boundary.
+ */
+export interface AdQuartileEvent extends Event {
+  /**
+   * The `AdQuartile` boundary that playback has progressed over.
+   */
+  quartile: AdQuartile;
+}
+
+/**
+ * Emitted when an ad manifest was successfully downloaded, parsed and added into the ad break schedule.
+ */
+export interface AdScheduledEvent extends Event {
+  /**
+   * The total number of scheduled ads.
+   */
+  numberOfAds: number;
+}
+
+/**
+ * Emitted when the download of an ad manifest is started.
+ */
+export interface AdManifestLoadEvent extends Event {
+  /**
+   * The `AdBreak` this event is related to.
+   */
+  adBreak?: AdBreak;
+  /**
+   * The `AdConfig` of the loaded ad manifest.
+   */
+  adConfig?: AdConfig;
+}
+
+/**
+ * Emitted when an ad manifest was successfully loaded.
+ */
+export interface AdManifestLoadedEvent extends Event {
+  /**
+   * The `AdBreak` this event is related to.
+   */
+  adBreak?: AdBreak;
+  /**
+   * The `AdConfig` of the loaded ad manifest.
+   */
+  adConfig?: AdConfig;
+  /**
+   * How long it took for the ad tag to be downloaded in milliseconds.
+   */
+  downloadTime: number;
+}
+
+/**
+ * Emitted when the current video playback quality has changed.
+ */
+export interface VideoPlaybackQualityChangedEvent extends Event {
+  /**
+   * The new quality
+   */
+  newVideoQuality: VideoQuality;
+  /**
+   * The previous quality
+   */
+  oldVideoQuality: VideoQuality;
+}

package/src/index.ts

@@ -1,3 +1,6 @@
+export * from './advertising';
+export * from './analytics';
+export * from './audioSession';
 export * from './components';
 export * from './drm';
 export * from './events';
@@ -5,3 +8,4 @@ export * from './hooks';
 export * from './player';
 export * from './source';
 export * from './subtitleTrack';
+export * from './styleConfig';

package/src/media.ts

@@ -0,0 +1,33 @@
+/**
+ * Quality definition of a video representation.
+ */
+export interface VideoQuality {
+  /**
+   * The id of the media quality.
+   */
+  id: string;
+  /**
+   * The label of the media quality that should be exposed to the user.
+   */
+  label?: string;
+  /**
+   * The bitrate of the media quality.
+   */
+  bitrate?: number;
+  /**
+   * The codec of the media quality.
+   */
+  codec?: string;
+  /**
+   * The frame rate of the video quality. If the frame rate is not known or not applicable a value of -1 will be returned.
+   */
+  frameRate?: number;
+  /**
+   * The height of the video quality.
+   */
+  height?: number;
+  /**
+   * The width of the video quality.
+   */
+  width?: number;
+}

package/src/player.ts

@@ -1,7 +1,10 @@
 import { NativeModules, Platform } from 'react-native';
+import { AdItem, AdvertisingConfig } from './advertising';
+import { AnalyticsCollector, AnalyticsConfig } from './analytics';
 import NativeInstance, { NativeInstanceConfig } from './nativeInstance';
 import { Source, SourceConfig } from './source';
 import { SubtitleTrack } from './subtitleTrack';
+import { StyleConfig } from './styleConfig';
 import { TweaksConfig } from './tweaksConfig';
 
 const PlayerModule = NativeModules.PlayerModule;
@@ -33,10 +36,22 @@ export interface PlayerConfig extends NativeInstanceConfig {
    * Configures playback behaviour. A default PlaybackConfig is set initially.
    */
   playbackConfig?: PlaybackConfig;
+  /**
+   * Configures the visual presentation and behaviour of the player UI. A default StyleConfig is set initially.
+   */
+  styleConfig?: StyleConfig;
+  /**
+   * Configures advertising functionality. A default AdvertisingConfig is set initially.
+   */
+  advertisingConfig?: AdvertisingConfig;
   /**
    * Configures experimental features. A default TweaksConfig is set initially.
    */
   tweaksConfig?: TweaksConfig;
+  /**
+   * Configures analytics functionality.
+   */
+  analyticsConfig?: AnalyticsConfig;
 }
 
 /**
@@ -103,7 +118,7 @@ export interface PlaybackConfig {
    */
   isBackgroundPlaybackEnabled?: boolean;
   /**
-   * Whether the picture-in-picture mode option is enabled for iOS or not. Default is `false`.
+   * Whether the Picture in Picture mode option is enabled or not. Default is `false`.
    *  @example
    * ```
    * const player = new Player({
@@ -130,6 +145,10 @@ export class Player extends NativeInstance<PlayerConfig> {
    * Currently active source, or `null` if none is active.
    */
   source?: Source;
+  /**
+   * Analytics collector currently attached to this player instance.
+   */
+  analyticsCollector?: AnalyticsCollector;
   /**
    * Whether the native `Player` object has been created.
    */
@@ -145,6 +164,12 @@ export class Player extends NativeInstance<PlayerConfig> {
   initialize = () => {
     if (!this.isInitialized) {
       PlayerModule.initWithConfig(this.nativeId, this.config);
+      const analyticsConfig = this.config?.analyticsConfig;
+      if (analyticsConfig) {
+        this.analyticsCollector = new AnalyticsCollector(analyticsConfig);
+        this.analyticsCollector?.initialize();
+        this.analyticsCollector?.attach(this.nativeId);
+      }
       this.isInitialized = true;
     }
   };
@@ -156,6 +181,7 @@ export class Player extends NativeInstance<PlayerConfig> {
     if (!this.isDestroyed) {
       PlayerModule.destroy(this.nativeId);
       this.source?.destroy();
+      this.analyticsCollector?.destroy();
       this.isDestroyed = true;
     }
   };
@@ -321,4 +347,34 @@ export class Player extends NativeInstance<PlayerConfig> {
   getAvailableSubtitles = async (): Promise<SubtitleTrack[]> => {
     return PlayerModule.getAvailableSubtitles(this.nativeId);
   };
+
+  /**
+   * Dynamically schedules the `adItem` for playback.
+   * Has no effect if there is no active playback session.
+   *
+   * @param adItem - Ad to be scheduled for playback.
+   *
+   * @platform iOS, Android
+   */
+  scheduleAd = (adItem: AdItem) => {
+    PlayerModule.scheduleAd(this.nativeId, adItem);
+  };
+
+  /**
+   * Skips the current ad.
+   * Has no effect if the current ad is not skippable or if no ad is being played back.
+   *
+   * @platform iOS, Android
+   */
+  skipAd = () => {
+    PlayerModule.skipAd(this.nativeId);
+  };
+
+  /**
+   * @returns `true` while an ad is being played back or when main content playback has been paused for ad playback.
+   * @platform iOS, Android
+   */
+  isAd = (): Promise<boolean> => {
+    return PlayerModule.isAd(this.nativeId);
+  };
 }

package/src/source.ts

@@ -78,6 +78,10 @@ export interface SourceConfig extends NativeInstanceConfig {
    * External subtitle tracks to be added into the player.
    */
   subtitleTracks?: SideLoadedSubtitleTrack[];
+  /**
+   * External thumbnails to be added into the player.
+   */
+  thumbnailTrack?: string;
 }
 
 /**

package/src/styleConfig.ts

@@ -0,0 +1,87 @@
+/**
+ * Contains config values which can be used to alter the visual presentation and behaviour of the player UI.
+ */
+export interface StyleConfig {
+  /**
+   * Sets if the UI should be enabled or not. Default value is true.
+   * @example
+   * ```
+   * const player = new Player({
+   *   styleConfig: {
+   *     isUiEnabled: false,
+   *   },
+   * });
+   * ```
+   */
+  isUiEnabled?: boolean;
+  /**
+   * Set the CSS file that will be used for the UI. The default CSS file will be completely replaced by the CSS file set with this property.
+   * @example
+   * ```
+   * const player = new Player({
+   *   styleConfig: {
+   *     playerUiCss: 'https://domain.tld/path/to/bitmovinplayer-ui.css',
+   *   },
+   * });
+   * ```
+   * @platform iOS, Android
+   */
+  playerUiCss?: string;
+  /**
+   * Set a CSS file which contains supplemental styles for the player UI. These styles will be added to the default CSS file or the CSS file set with StyleConfig#playerUiCss.
+   * @example
+   * ```
+   * const player = new Player({
+   *   styleConfig: {
+   *     supplementalPlayerUiCss: 'https://domain.tld/path/to/bitmovinplayer-supplemental-ui.css',
+   *   },
+   * });
+   * ```
+   * @platform iOS, Android
+   */
+  supplementalPlayerUiCss?: string;
+  /**
+   * Sets the JS file that will be used for the UI. The default JS file will be completely replaced by the JS file set with this property.
+   * @example
+   * ```
+   * const player = new Player({
+   *   styleConfig: {
+   *     playerUiJs: 'https://domain.tld/path/to/bitmovinplayer-ui.js',
+   *   },
+   * });
+   * ```
+   * @platform iOS, Android
+   */
+  playerUiJs?: string;
+  /**
+   * Determines how the video content is scaled or stretched within the parent container’s bounds.  Possible values are defined in ScalingMode.
+   * Default value is ScalingMode.fit.
+   * @example
+   * ```
+   * const player = new Player({
+   *   styleConfig: {
+   *     scalingMode: ScalingMode.Zoom,
+   *   },
+   * });
+   * ```
+   */
+  scalingMode?: ScalingMode;
+}
+
+/**
+ * Specifies how the video content is scaled or stretched.
+ */
+export enum ScalingMode {
+  /**
+   * Specifies that the player should preserve the video’s aspect ratio and fit the video within the container's bounds.
+   */
+  Fit = 'Fit',
+  /**
+   * Specifies that the video should be stretched to fill the container’s bounds. The aspect ratio may not be preserved.
+   */
+  Stretch = 'Stretch',
+  /**
+   * Specifies that the player should preserve the video’s aspect ratio and fill the container’s bounds.
+   */
+  Zoom = 'Zoom',
+}

package/src/ui/fullscreenhandler.ts

@@ -0,0 +1,19 @@
+/**
+ * Handles the UI state change when fullscreen should be entered or exited.
+ */
+export interface FullscreenHandler {
+  /**
+   * Indicates if the UI is currently in fullscreen mode
+   */
+  isFullscreenActive: boolean;
+
+  /**
+   * Is called by the `PlayerView` when the UI should enter fullscreen mode.
+   */
+  enterFullscreen(): void;
+
+  /**
+   * Is called by the `PlayerView` when the UI should exit fullscreen mode.
+   */
+  exitFullscreen(): void;
+}

package/src/ui/fullscreenhandlerbridge.ts

@@ -0,0 +1,59 @@
+import { NativeModules } from 'react-native';
+import BatchedBridge from 'react-native/Libraries/BatchedBridge/BatchedBridge';
+import { FullscreenHandler } from './fullscreenhandler';
+
+const Uuid = NativeModules.UuidModule;
+const FullscreenHandlerModule = NativeModules.FullscreenHandlerModule;
+
+/**
+ * Takes care of JS/Native communication for a FullscreenHandler.
+ */
+export class FullscreenHandlerBridge {
+  readonly nativeId: string;
+  fullscreenHandler?: FullscreenHandler;
+  isDestroyed: boolean;
+
+  constructor(nativeId?: string) {
+    this.nativeId = nativeId ?? Uuid.generate();
+    this.isDestroyed = false;
+    BatchedBridge.registerCallableModule(
+      `FullscreenBridge-${this.nativeId}`,
+      this
+    );
+    FullscreenHandlerModule.registerHandler(this.nativeId);
+  }
+
+  /**
+   * Destroys the native FullscreenHandler
+   */
+  destroy() {
+    if (!this.isDestroyed) {
+      FullscreenHandlerModule.destroy(this.nativeId);
+      this.isDestroyed = true;
+    }
+  }
+
+  // noinspection JSUnusedGlobalSymbols
+  /**
+   * Called by native code, when the UI should enter fullscreen.
+   */
+  enterFullscreen(): void {
+    this.fullscreenHandler?.enterFullscreen();
+    FullscreenHandlerModule.onFullscreenChanged(
+      this.nativeId,
+      this.fullscreenHandler?.isFullscreenActive ?? false
+    );
+  }
+
+  // noinspection JSUnusedGlobalSymbols
+  /**
+   * Called by native code, when the UI should exit fullscreen.
+   */
+  exitFullscreen(): void {
+    this.fullscreenHandler?.exitFullscreen();
+    FullscreenHandlerModule.onFullscreenChanged(
+      this.nativeId,
+      this.fullscreenHandler?.isFullscreenActive ?? false
+    );
+  }
+}