spactureai-mobile-player 1.0.30

package/src/core/VideoPlayerEvents.ts

@@ -0,0 +1,146 @@
+import type {
+  ListenerSubscription,
+  VideoPlayerEventEmitter,
+} from '../spec/nitro/VideoPlayerEventEmitter.nitro';
+import {
+  ALL_PLAYER_EVENTS,
+  type JSVideoPlayerEvents,
+  type AllPlayerEvents as PlayerEvents,
+} from './types/Events';
+
+export class VideoPlayerEvents {
+  protected eventEmitter: VideoPlayerEventEmitter;
+  protected jsEventListeners: Partial<
+    Record<keyof JSVideoPlayerEvents, Set<(...params: any[]) => void>>
+  > = {};
+
+  protected readonly supportedEvents: (keyof PlayerEvents)[] =
+    ALL_PLAYER_EVENTS;
+
+  constructor(eventEmitter: VideoPlayerEventEmitter) {
+    this.eventEmitter = eventEmitter;
+  }
+
+  protected triggerJSEvent<Event extends keyof JSVideoPlayerEvents>(
+    event: Event,
+    ...params: Parameters<JSVideoPlayerEvents[Event]>
+  ): boolean {
+    if (!this.jsEventListeners[event]) return false;
+    this.jsEventListeners[event]?.forEach((fn) => fn(...params));
+    return true;
+  }
+
+  /**
+   * Adds a listener for a player event.
+   * @throw Error if the event is not supported.
+   * @param event - The event to add a listener for.
+   * @param callback - The callback to call when the event is triggered.
+   * @returns A subscription object that can be used to remove the listener.
+   */
+  addEventListener<Event extends keyof PlayerEvents>(
+    event: Event,
+    callback: PlayerEvents[Event]
+  ): ListenerSubscription {
+    switch (event) {
+      // ----------------- JS Events -----------------
+      case 'onError':
+        this.jsEventListeners.onError ??= new Set();
+        this.jsEventListeners.onError.add(
+          callback as JSVideoPlayerEvents['onError']
+        );
+        return {
+          remove: () =>
+            this.jsEventListeners.onError?.delete(
+              callback as JSVideoPlayerEvents['onError']
+            ),
+        };
+      // ----------------- Native Events -----------------
+      case 'onAudioBecomingNoisy':
+        return this.eventEmitter.addOnAudioBecomingNoisyListener(
+          callback as PlayerEvents['onAudioBecomingNoisy']
+        );
+      case 'onAudioFocusChange':
+        return this.eventEmitter.addOnAudioFocusChangeListener(
+          callback as PlayerEvents['onAudioFocusChange']
+        );
+      case 'onBandwidthUpdate':
+        return this.eventEmitter.addOnBandwidthUpdateListener(
+          callback as PlayerEvents['onBandwidthUpdate']
+        );
+      case 'onBuffer':
+        return this.eventEmitter.addOnBufferListener(
+          callback as PlayerEvents['onBuffer']
+        );
+      case 'onControlsVisibleChange':
+        return this.eventEmitter.addOnControlsVisibleChangeListener(
+          callback as PlayerEvents['onControlsVisibleChange']
+        );
+      case 'onEnd':
+        return this.eventEmitter.addOnEndListener(
+          callback as PlayerEvents['onEnd']
+        );
+      case 'onExternalPlaybackChange':
+        return this.eventEmitter.addOnExternalPlaybackChangeListener(
+          callback as PlayerEvents['onExternalPlaybackChange']
+        );
+      case 'onLoad':
+        return this.eventEmitter.addOnLoadListener(
+          callback as PlayerEvents['onLoad']
+        );
+      case 'onLoadStart':
+        return this.eventEmitter.addOnLoadStartListener(
+          callback as PlayerEvents['onLoadStart']
+        );
+      case 'onPlaybackStateChange':
+        return this.eventEmitter.addOnPlaybackStateChangeListener(
+          callback as PlayerEvents['onPlaybackStateChange']
+        );
+      case 'onPlaybackRateChange':
+        return this.eventEmitter.addOnPlaybackRateChangeListener(
+          callback as PlayerEvents['onPlaybackRateChange']
+        );
+      case 'onProgress':
+        return this.eventEmitter.addOnProgressListener(
+          callback as PlayerEvents['onProgress']
+        );
+      case 'onReadyToDisplay':
+        return this.eventEmitter.addOnReadyToDisplayListener(
+          callback as PlayerEvents['onReadyToDisplay']
+        );
+      case 'onSeek':
+        return this.eventEmitter.addOnSeekListener(
+          callback as PlayerEvents['onSeek']
+        );
+      case 'onTimedMetadata':
+        return this.eventEmitter.addOnTimedMetadataListener(
+          callback as PlayerEvents['onTimedMetadata']
+        );
+      case 'onTextTrackDataChanged':
+        return this.eventEmitter.addOnTextTrackDataChangedListener(
+          callback as PlayerEvents['onTextTrackDataChanged']
+        );
+      case 'onTrackChange':
+        return this.eventEmitter.addOnTrackChangeListener(
+          callback as PlayerEvents['onTrackChange']
+        );
+      case 'onVolumeChange':
+        return this.eventEmitter.addOnVolumeChangeListener(
+          callback as PlayerEvents['onVolumeChange']
+        );
+      case 'onStatusChange':
+        return this.eventEmitter.addOnStatusChangeListener(
+          callback as PlayerEvents['onStatusChange']
+        );
+      default:
+        throw new Error(`[Unified Player] Unsupported event: ${event}`);
+    }
+  }
+
+  /**
+   * Clears all events from the event emitter.
+   */
+  clearAllEvents() {
+    this.jsEventListeners = {};
+    this.eventEmitter.clearAllListeners();
+  }
+}

package/src/core/hooks/useEvent.ts

@@ -0,0 +1,24 @@
+import { useEffect } from 'react';
+import { VideoPlayer } from '../VideoPlayer';
+import { type AllPlayerEvents } from '../types/Events';
+
+/**
+ * Attaches an event listener to a `VideoPlayer` instance for a specified event.
+ *
+ * @param player - The player to attach the event to
+ * @param event - The name of the event to attach the callback to
+ * @param callback - The callback for the event
+ */
+export const useEvent = <T extends keyof AllPlayerEvents>(
+  player: VideoPlayer,
+  event: T,
+  callback: AllPlayerEvents[T]
+) => {
+  useEffect(() => {
+    const subscription = player.addEventListener(event, callback);
+
+    return () => {
+      subscription.remove();
+    };
+  }, [player, event, callback]);
+};

package/src/core/hooks/useManagedInstance.ts

@@ -0,0 +1,96 @@
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type DependencyList,
+} from 'react';
+
+/**
+ * @internal
+ * A hook that helps to manage the lifecycle of a native instance in a React component.
+ * It allows instance to be recreated when dependencies change, but not when the component is hot reloaded.
+ *
+ * @param config.factory - The factory function that creates the instance.
+ * @param config.cleanup - The cleanup function that destroys the instance.
+ * @param config.dependenciesEqualFn - The function that compares the dependencies.
+ *
+ * @param dependencies - The dependencies array.
+ * @returns The managed instance.
+ */
+export const useManagedInstance = <T, D extends DependencyList[number]>(
+  config: {
+    factory: () => T;
+    cleanup: (object: T) => void;
+    dependenciesEqualFn?: (a: D, b?: D) => boolean;
+  },
+  dependencies: D[]
+): T => {
+  const { factory, cleanup, dependenciesEqualFn } = config;
+
+  const objectRef = useRef<T | null>(null);
+  const isFastRefresh = useRef(false);
+  const previousDependencies = useRef(dependencies);
+
+  // Wee need to force a "re-render" to recalculate the object
+  const [released, setReleased] = useState(false);
+
+  if (objectRef.current == null) {
+    objectRef.current = factory();
+  }
+
+  const object = useMemo(() => {
+    let newObject = objectRef.current;
+
+    const dependenciesChanged =
+      previousDependencies.current?.length === dependencies.length &&
+      dependencies.every(
+        (value, index) =>
+          dependenciesEqualFn?.(value, previousDependencies.current[index]) ??
+          value === previousDependencies.current[index]
+      );
+
+    if (!newObject || !dependenciesChanged || released) {
+      // Destroy the old object
+      if (objectRef.current) {
+        cleanup(objectRef.current);
+        objectRef.current = null;
+      }
+
+      // Create a new object
+      newObject = factory();
+      objectRef.current = newObject;
+      setReleased(false);
+
+      // Update the previous dependencies
+      previousDependencies.current = dependencies;
+    } else {
+      // If useMemo is re-evaluated, but dependencies are the same
+      // and object is still the same, we can assume that that
+      // the component is being hot reloaded
+      isFastRefresh.current = true;
+    }
+
+    return newObject;
+
+    // factory and cleanup are stable, so we don't need to re-evaluate
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [...dependencies, released]);
+
+  useEffect(() => {
+    isFastRefresh.current = false;
+
+    return () => {
+      if (!isFastRefresh.current && objectRef.current) {
+        cleanup(objectRef.current);
+        objectRef.current = null;
+        setReleased(true);
+      }
+    };
+
+    // factory and cleanup are stable, so we don't need to re-evaluate
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return object;
+};

package/src/core/hooks/useVideoPlayer.ts

@@ -0,0 +1,73 @@
+import { useRef } from 'react';
+import type { VideoPlayerSource } from '../../spec/nitro/VideoPlayerSource.nitro';
+import type { NoAutocomplete } from '../types/Utils';
+import type { VideoConfig, VideoSource } from '../types/VideoConfig';
+import { isVideoPlayerSource } from '../utils/sourceFactory';
+import { VideoPlayer } from '../VideoPlayer';
+import { useManagedInstance } from './useManagedInstance';
+
+const sourceEqual = <T extends VideoConfig | VideoSource | VideoPlayerSource>(
+  a: T,
+  b?: T
+) => {
+  if (isVideoPlayerSource(a) && isVideoPlayerSource(b)) {
+    return a.equals(b);
+  }
+
+  return JSON.stringify(a) === JSON.stringify(b);
+};
+
+/**
+ * Creates a `VideoPlayer` instance and manages its lifecycle.
+ *
+ * if `initializeOnCreation` is true (default), the `setup` function will be called when the player is started loading source.
+ * if `initializeOnCreation` is false, the `setup` function will be called when the player is created. changes made to player made before initializing will be overwritten when initializing.
+ *
+ * @param source - The source of the video to play
+ * @param setup - A function to setup the player
+ * @returns The `VideoPlayer` instance
+ */
+export const useVideoPlayer = (
+  source: VideoConfig | VideoSource | NoAutocomplete<VideoPlayerSource>,
+  setup?: (player: VideoPlayer) => void
+) => {
+  const setupCalled = useRef(false);
+
+  return useManagedInstance(
+    {
+      factory: () => {
+        const player = new VideoPlayer(source);
+
+        if (setup === undefined) {
+          return player;
+        }
+
+        if (player.source.config.initializeOnCreation !== false) {
+          // if source is small video, it can happen that onLoadStart is called before we set event from JS
+          // Thats why we adding event listener and calling setup once if player is loading or ready to play
+          // That way we ensure that setup is always called
+
+          const callSetupOnce = () => {
+            if (!setupCalled.current) {
+              setupCalled.current = true;
+              setup?.(player);
+            }
+          };
+
+          player.addEventListener('onLoadStart', callSetupOnce);
+          player.addEventListener('onStatusChange', callSetupOnce);
+        } else {
+          setup?.(player);
+        }
+
+        return player;
+      },
+      cleanup: (player) => {
+        player.__destroy();
+        setupCalled.current = false;
+      },
+      dependenciesEqualFn: sourceEqual,
+    },
+    [JSON.stringify(source)]
+  );
+};

package/src/core/types/BufferConfig.ts

@@ -0,0 +1,103 @@
+export interface LivePlaybackParams {
+  /**
+   * Minimum playback speed for catching up to target live offset.
+   * @platform android
+   */
+  minPlaybackSpeed?: number;
+  /**
+   * Maximum playback speed for catching up to target live offset.
+   * @platform android
+   */
+  maxPlaybackSpeed?: number;
+  /**
+   * Maximum allowed live offset. The player won’t exceed this limit.
+   * @platform android
+   */
+  maxOffsetMs?: number;
+  /**
+   * Minimum allowed live offset. The player won’t go below this limit.
+   * @platform android
+   */
+  minOffsetMs?: number;
+  /**
+   * Target live offset. The player will try to maintain this offset.
+   * @platform android, ios, visionOS, tvOS
+   */
+  targetOffsetMs?: number;
+}
+
+interface Resolution {
+  width: number;
+  height: number;
+}
+
+export interface BufferConfig {
+  /**
+   * Configuration for live playback.
+   */
+  livePlayback?: LivePlaybackParams;
+
+  // -------- Android specific options --------
+
+  /**
+   * Minimum duration (ms) the player will attempt to keep buffered.
+   * @default 5000
+   * @platform android
+   */
+  minBufferMs?: number;
+  /**
+   * Maximum duration (ms) the player will attempt to keep buffered.
+   * @default 10000
+   * @platform android
+   */
+  maxBufferMs?: number;
+  /**
+   * Duration (ms) of media that must be buffered for playback to start or resume following a user action such as a seek.
+   * @default 1000
+   * @platform android
+   */
+  bufferForPlaybackMs?: number;
+  /**
+   * Duration (ms) of media that must be buffered for playback to resume after a rebuffer.
+   * @default 2000
+   * @platform android
+   */
+  bufferForPlaybackAfterRebufferMs?: number;
+  /**
+   * Duration (ms) of media that must be buffered before it can be played from the back buffer.
+   * @platform android
+   */
+  backBufferDurationMs?: number;
+
+  // -------- iOS specific options --------
+
+  /**
+   * The preferred duration (ms) of media that the player will attempt to retain in the buffer.
+   * @platform ios, visionOS, tvOS
+   */
+  preferredForwardBufferDurationMs?: number;
+  /**
+   * The desired limit, in bits per second, of network bandwidth used for loading the current item.
+   *
+   * You can use {@linkcode preferredPeakBitRateForExpensiveNetworks} to set a different bit rate when on an expensive network (e.g. cellular).
+   * @platform ios, visionOS, tvOS
+   */
+  preferredPeakBitRate?: number;
+  /**
+   * The preferred maximum resolution of the video.
+   *
+   * You can use {@linkcode preferredMaximumResolutionForExpensiveNetworks} to set a different resolution when on an expensive network (e.g. cellular).
+   * @platform ios, visionOS, tvOS
+   */
+  preferredMaximumResolution?: Resolution;
+  /**
+   * The desired limit, in bits per second, of network bandwidth used for loading the current item when on an expensive network (e.g. cellular).
+   * @platform ios, visionOS, tvOS
+   */
+  preferredPeakBitRateForExpensiveNetworks?: number;
+  /**
+   * The preferred maximum resolution of the video when on an expensive network (e.g. cellular).
+   * @platform ios, visionOS, tvOS
+   */
+  preferredMaximumResolutionForExpensiveNetworks?: Resolution;
+}

package/src/core/types/DrmParams.ts

@@ -0,0 +1,65 @@
+/**
+ * Headers type specifically for DRM license requests
+ */
+
+export interface DrmParams {
+  /**
+   * The license URL for the DRM license request.
+   * @platform Android, iOS, visionOS
+   */
+  licenseUrl?: string;
+  /**
+   * The certificate URL for the DRM license request.
+   * @platform iOS, visionOS
+   */
+  certificateUrl?: string;
+  /**
+   * The content ID for the DRM license request.
+   * @platform iOS, visionOS
+   */
+  contentId?: string;
+  /**
+   * The type of DRM to use.
+   * @platform Android, iOS, visionOS
+   */
+  type?: DRMType;
+  /**
+   * The headers to send with the DRM license request.
+   * @platform Android, iOS, visionOS
+   */
+  licenseHeaders?: Record<string, string>;
+  /**
+   * Whether to allow multiple sessions for the DRM license request.
+   * @platform Android
+   */
+  multiSession?: boolean;
+  /**
+   * A function to get the license for the DRM license request.
+   * @platform iOS
+   */
+  getLicense?: (payload: OnGetLicensePayload) => Promise<string>;
+}
+
+interface OnGetLicensePayload {
+  /**
+   * The content ID for the DRM license request.
+   * This is typically a unique identifier for the content being played.
+   */
+  contentId: string;
+  /**
+   * The license URL for the DRM license request.
+   */
+  licenseUrl: string;
+  /**
+   * The key URL for the DRM license request.
+   * Typically starts with starting with skd:// or clearkey://
+   */
+  keyUrl: string;
+  /**
+   * The secure playback context (SPC) for the DRM license request.
+   * This is typically a base64-encoded string that contains information about the playback environment.
+   */
+  spc: string;
+}
+
+type DRMType = 'widevine' | 'fairplay' | (string & {});