spactureai-mobile-player 1.0.30

package/src/core/types/Events.ts

@@ -0,0 +1,283 @@
+import type { VideoPlayerSource } from '../../spec/nitro/VideoPlayerSource.nitro';
+import type { TextTrack } from './TextTrack';
+import type { VideoRuntimeError } from './VideoError';
+import type { VideoOrientation } from './VideoOrientation';
+import type { VideoPlayerStatus } from './VideoPlayerStatus';
+
+export interface VideoPlayerEvents {
+  /**
+   * Called when the audio becomes noisy.
+   * @platform Android
+   */
+  onAudioBecomingNoisy: () => void;
+  /**
+   * Called when the audio focus changes.
+   * @param hasAudioFocus Whether the audio has focus.
+   * @platform Android
+   */
+  onAudioFocusChange: (hasAudioFocus: boolean) => void;
+  /**
+   * Called when the bandwidth of the video changes.
+   */
+  onBandwidthUpdate: (data: BandwidthData) => void;
+  /**
+   * Called when the video is buffering.
+   * @param buffering Whether the video is buffering.
+   */
+  onBuffer: (buffering: boolean) => void;
+  /**
+   * Called when the video view's controls visibility changes.
+   * @param visible Whether the video view's controls are visible.
+   */
+  onControlsVisibleChange: (visible: boolean) => void;
+  /**
+   * Called when the video ends.
+   */
+  onEnd: () => void;
+  /**
+   * Called when the external playback state changes.
+   * @param externalPlaybackActive Whether the external playback is active.
+   * @platform iOS
+   */
+  onExternalPlaybackChange: (externalPlaybackActive: boolean) => void;
+  /**
+   * Called when the video is loaded.
+   * @note onLoadStart -> initialize the player -> onLoad
+   */
+  onLoad: (data: onLoadData) => void;
+  /**
+   * Called when the video starts loading.
+   * @note onLoadStart -> initialize the player -> onLoad
+   */
+  onLoadStart: (data: onLoadStartData) => void;
+  /**
+   * Called when the player playback state changes.
+   */
+  onPlaybackStateChange: (data: onPlaybackStateChangeData) => void;
+  /**
+   * Called when the player playback rate changes.
+   */
+  onPlaybackRateChange: (rate: number) => void;
+  /**
+   * Called when the player progress changes.
+   */
+  onProgress: (data: onProgressData) => void;
+  /**
+   * Called when the video is ready to display.
+   */
+  onReadyToDisplay: () => void;
+  /**
+   * Called when the player seeks.
+   */
+  onSeek: (seekTime: number) => void;
+  /**
+   * Called when player receives timed metadata.
+   */
+  onTimedMetadata: (metadata: TimedMetadata) => void;
+  /**
+   * Called when the text track (currently displayed subtitle) data changes.
+   */
+  onTextTrackDataChanged: (texts: string[]) => void;
+  /**
+   * Called when the selected text track changes.
+   * @param track - The newly selected text track, or null if no track is selected
+   */
+  onTrackChange: (track: TextTrack | null) => void;
+  /**
+   * Called when the volume of the player changes.
+   */
+  onVolumeChange: (data: onVolumeChangeData) => void;
+  /**
+   * Called when the player status changes.
+   */
+  onStatusChange: (status: VideoPlayerStatus) => void;
+}
+
+export interface JSVideoPlayerEvents {
+  onError: (error: VideoRuntimeError) => void;
+}
+
+export type AllPlayerEvents = VideoPlayerEvents & JSVideoPlayerEvents;
+
+export interface VideoViewEvents {
+  /**
+   * Called when the video view's picture in picture state changes.
+   * @param isInPictureInPicture Whether the video view is in picture in picture mode.
+   */
+  onPictureInPictureChange: (isInPictureInPicture: boolean) => void;
+  /**
+   * Called when the video view's fullscreen state changes.
+   * @param fullscreen Whether the video view is in fullscreen mode.
+   */
+  onFullscreenChange: (fullscreen: boolean) => void;
+  /**
+   * Called when the video view will enter fullscreen mode.
+   */
+  willEnterFullscreen: () => void;
+  /**
+   * Called when the video view will exit fullscreen mode.
+   */
+  willExitFullscreen: () => void;
+  /**
+   * Called when the video view will enter picture in picture mode.
+   */
+  willEnterPictureInPicture: () => void;
+  /**
+   * Called when the video view will exit picture in picture mode.
+   */
+  willExitPictureInPicture: () => void;
+}
+
+export interface BandwidthData {
+  /**
+   * The bitrate of the video in bits per second.
+   */
+  bitrate: number;
+  /**
+   * The width of the video in pixels.
+   * @platform android
+   */
+  width?: number;
+  /**
+   * The height of the video in pixels.
+   * @platform Android
+   */
+  height?: number;
+}
+
+export interface onLoadData {
+  /**
+   * The current time of the video in seconds.
+   */
+  currentTime: number;
+  /**
+   * The duration of the video in seconds.
+   * @note NaN if the duration is unknown.
+   */
+  duration: number;
+  /**
+   * The height of the video in pixels.
+   */
+  height: number;
+  /**
+   * The width of the video in pixels.
+   */
+  width: number;
+  /**
+   * The orientation of the video.
+   */
+  orientation: VideoOrientation;
+}
+
+export type SourceType = 'local' | 'network';
+
+export interface onLoadStartData {
+  /**
+   * The type of the source.
+   * @note `local` for local files, `network` for network sources.
+   */
+  sourceType: SourceType;
+  /**
+   * The source of the video.
+   */
+  source: VideoPlayerSource;
+}
+
+export interface onPlaybackStateChangeData {
+  /**
+   * Whether the video is playing.
+   */
+  isPlaying: boolean;
+  /**
+   * Whether the video is buffering.
+   */
+  isBuffering: boolean;
+}
+
+export interface onProgressData {
+  /**
+   * The current time of the video in seconds.
+   */
+  currentTime: number;
+  /**
+   * The duration of the video in seconds.
+   * @note NaN if the duration is unknown (e.g., live streams).
+   */
+  duration: number;
+  /**
+   * The time that player is able to play with only buffer.
+   */
+  bufferDuration: number;
+}
+
+export type TimedMetadataObject = {
+  value: string;
+  identifier: string;
+};
+
+export interface TimedMetadata {
+  /**
+   * The timed metadata of the video.
+   */
+  metadata: Array<TimedMetadataObject>;
+}
+
+export interface onVolumeChangeData {
+  /**
+   * The volume of the player (0.0 = 0%, 1.0 = 100%).
+   */
+  volume: number;
+  /**
+   * Whether the player is muted.
+   */
+  muted: boolean;
+}
+
+type CheckAllAndOnly<T, A extends readonly (keyof T)[]> =
+  // Missing keys?
+  Exclude<keyof T, A[number]> extends never
+    ? // Extra keys?
+      Exclude<A[number], keyof T> extends never
+      ? A
+      : ['Extra keys', Exclude<A[number], keyof T>]
+    : ['Missing keys', Exclude<keyof T, A[number]>];
+
+function allKeysOf<T>() {
+  return <A extends readonly (keyof T)[]>(...arr: A): CheckAllAndOnly<T, A> => {
+    return arr as CheckAllAndOnly<T, A>;
+  };
+}
+
+export const ALL_PLAYER_EVENTS: (keyof AllPlayerEvents)[] =
+  allKeysOf<AllPlayerEvents>()(
+    'onAudioBecomingNoisy',
+    'onAudioFocusChange',
+    'onBandwidthUpdate',
+    'onBuffer',
+    'onControlsVisibleChange',
+    'onEnd',
+    'onError',
+    'onExternalPlaybackChange',
+    'onLoad',
+    'onLoadStart',
+    'onPlaybackStateChange',
+    'onPlaybackRateChange',
+    'onProgress',
+    'onReadyToDisplay',
+    'onSeek',
+    'onTimedMetadata',
+    'onTextTrackDataChanged',
+    'onTrackChange',
+    'onVolumeChange',
+    'onStatusChange'
+  );
+
+export const ALL_VIEW_EVENTS: (keyof VideoViewEvents)[] =
+  allKeysOf<VideoViewEvents>()(
+    'onPictureInPictureChange',
+    'onFullscreenChange',
+    'willEnterFullscreen',
+    'willExitFullscreen',
+    'willEnterPictureInPicture',
+    'willExitPictureInPicture'
+  );

package/src/core/types/IgnoreSilentSwitchMode.ts

@@ -0,0 +1 @@
+export type IgnoreSilentSwitchMode = 'auto' | 'ignore' | 'obey';

package/src/core/types/MixAudioMode.ts

@@ -0,0 +1 @@
+export type MixAudioMode = 'mixWithOthers' | 'doNotMix' | 'duckOthers' | 'auto';

package/src/core/types/ResizeMode.ts

@@ -0,0 +1,9 @@
+/**
+ * Video resize modes that determine how video content is resized to fit the view
+ *
+ * - 'contain': Scale the video uniformly (maintain aspect ratio) so that it fits entirely within the view
+ * - 'cover': Scale the video uniformly (maintain aspect ratio) so that it fills the entire view (may crop)
+ * - 'stretch': Scale the video to fill the entire view without maintaining aspect ratio
+ * - 'none': Do not resize the video - it will fallback to default behavior (contain)
+ */
+export type ResizeMode = 'contain' | 'cover' | 'stretch' | 'none';

package/src/core/types/TextTrack.ts

@@ -0,0 +1,22 @@
+export interface TextTrack {
+  /**
+   * Unique identifier for the text track
+   */
+  id: string;
+
+  /**
+   * Display label for the text track
+   */
+  label: string;
+
+  /**
+   * Language code (ISO 639-1 or ISO 639-2)
+   * @example "en", "es", "fr"
+   */
+  language?: string;
+
+  /**
+   * Whether this track is currently selected
+   */
+  selected: boolean;
+}

package/src/core/types/Utils.ts

@@ -0,0 +1 @@
+export type NoAutocomplete<T> = T & never;

package/src/core/types/VideoConfig.ts

@@ -0,0 +1,150 @@
+import type { BufferConfig } from './BufferConfig';
+import type { DrmParams } from './DrmParams';
+
+export type VideoSource = number | string;
+
+export type VideoConfig = {
+  /**
+   * The uri of the video.
+   * @example
+   * ```ts
+   * uri: 'https://example.com/video.mp4'
+   * // or
+   * uri: require('./assets/video.mp4')
+   * ```
+   */
+  uri: VideoSource;
+  /**
+   * The headers to be sent with the request.
+   */
+  headers?: Record<string, string>;
+  /**
+   * The DRM parameters to be used.
+   */
+  drm?: DrmParams;
+  /**
+   * The player buffer configuration.
+   */
+  bufferConfig?: BufferConfig;
+  /**
+   * The custom metadata to be associated with the video.
+   * This metadata can be used by the native player to show information about the video.
+   */
+  metadata?: CustomVideoMetadata;
+  /**
+   * The external subtitles to be used.
+   * @note on iOS, only WebVTT (.vtt) subtitles are supported (for HLS streams and MP4 files).
+   * @note on iOS, `label` can be overridden by player and there is no way to get around it.
+   * @example
+   * ```ts
+   * externalSubtitles: [
+   *   {
+   *     uri: 'https://example.com/subtitles_en.vtt',
+   *     label: 'English',
+   *     type: 'vtt',
+   *     language: 'en'
+   *   },
+   *   {
+   *     uri: 'https://example.com/subtitles_es.vtt',
+   *     label: 'Español',
+   *     type: 'vtt',
+   *     language: 'es'
+   *   }
+   * ]
+   * ```
+   */
+  externalSubtitles?: ExternalSubtitle[];
+  /**
+   * when the player is created, this flag will determine if native player should be initialized immediately.
+   * If set to true, the player will be initialized as soon as player is created
+   * If set to false, the player will need be initialized manually later
+   * @default true
+   */
+  initializeOnCreation?: boolean;
+};
+
+// @internal
+export interface NativeVideoConfig extends VideoConfig {
+  // The uri should be resolved to string before creating the source
+  uri: string;
+  externalSubtitles?: NativeExternalSubtitle[];
+  drm?: NativeDrmParams;
+}
+
+/**
+ * The type of the subtitle.
+ * - `vtt` - WebVTT
+ * - `srt` - SubRip
+ * - `ssa` - SubStation Alpha
+ * - `ass` - Advanced SubStation Alpha
+ * - `auto` - Auto detect the subtitle type from the file extension
+ *
+ * @note `auto` is not available when uri have no extension.
+ */
+export type SubtitleType = 'vtt' | 'srt' | 'ssa' | 'ass' | 'auto';
+
+interface ExternalSubtitleWithInferredType {
+  /**
+   * The uri of the subtitle.
+   * @note the uri must end with the subtitle type.
+   */
+  uri: `${string}.${SubtitleType}`;
+  /**
+   * The label for the subtitle.
+   */
+  label: string;
+  /**
+   * The type of the subtitle.
+   */
+  type?: SubtitleType;
+  /**
+   * The language code for the subtitle (ISO 639-1 or ISO 639-2).
+   * @example 'en', 'es', 'fr', 'de', 'zh-CN'
+   * @default 'und' (undefined)
+   */
+  language?: string;
+}
+
+interface ExternalSubtitleWithCustomType {
+  /**
+   * The uri of the subtitle.
+   */
+  uri: string;
+  /**
+   * The label for the subtitle.
+   */
+  label: string;
+  /**
+   * The type of the subtitle.
+   */
+  type: Omit<SubtitleType, 'auto'>;
+  /**
+   * The language code for the subtitle (ISO 639-1 or ISO 639-2).
+   * @example 'en', 'es', 'fr', 'de', 'zh-CN'
+   * @default 'und' (undefined)
+   */
+  language?: string;
+}
+
+export type ExternalSubtitle =
+  | ExternalSubtitleWithInferredType
+  | ExternalSubtitleWithCustomType;
+
+interface NativeExternalSubtitle {
+  uri: string;
+  label: string;
+  type: SubtitleType;
+  language: string;
+}
+
+interface NativeDrmParams extends DrmParams {
+  type?: string;
+}
+
+interface CustomVideoMetadata {
+  title?: string;
+  subtitle?: string;
+  description?: string;
+  artist?: string;
+  imageUri?: string;
+}

package/src/core/types/VideoError.ts

@@ -0,0 +1,174 @@
+export type LibraryError =
+  | 'library/deallocated'
+  | 'library/application-context-not-found';
+
+export type PlayerError =
+  | 'player/released'
+  | 'player/not-initialized'
+  | 'player/asset-not-initialized'
+  | 'player/invalid-source';
+
+export type SourceError =
+  | 'source/invalid-uri'
+  | 'source/missing-read-file-permission'
+  | 'source/file-does-not-exist'
+  | 'source/failed-to-initialize-asset'
+  | 'source/unsupported-content-type';
+
+export type VideoViewError =
+  | 'view/not-found'
+  | 'view/deallocated'
+  | 'view/picture-in-picture-not-supported';
+
+export type UnknownError = 'unknown/unknown';
+
+export type VideoErrorCode =
+  | LibraryError
+  | PlayerError
+  | SourceError
+  | VideoViewError
+  | UnknownError;
+
+export class VideoError<TCode extends VideoErrorCode> extends Error {
+  private readonly _code: TCode;
+  private readonly _message: string;
+  private readonly _stack?: string;
+
+  public get code(): TCode {
+    return this._code;
+  }
+  public get message(): string {
+    return this._message;
+  }
+
+  public get stack(): string | undefined {
+    return this._stack;
+  }
+
+  /**
+   * @internal
+   */
+  constructor(code: TCode, message: string, stack?: string) {
+    super(`[${code}]: ${message}`);
+    super.name = `[Unified Player] ${code}`;
+    super.message = message;
+    super.stack = stack;
+    this._code = code;
+    this._message = message;
+    this._stack = stack;
+  }
+
+  public toString(): string {
+    let string = `[${this.code}]: ${this.message}`;
+    return string;
+  }
+}
+
+export class VideoComponentError extends VideoError<VideoViewError> {}
+
+export class VideoRuntimeError extends VideoError<
+  LibraryError | PlayerError | SourceError | UnknownError
+> {}
+
+/**
+ * Check if the message contains code and message
+ */
+const getCodeAndMessage = (
+  message: string
+): { code: string; message: string } | null => {
+  // (...){%@(match[1])::(match[2]);@%}(...)
+  const regex = /\{%@([^:]+)::([^@]+)@%\}/;
+  const match = message.match(regex);
+
+  if (
+    match &&
+    match.length === 3 &&
+    typeof match[1] === 'string' &&
+    typeof match[2] === 'string'
+  ) {
+    return {
+      code: match[1],
+      message: match[2],
+    };
+  }
+  return null;
+};
+
+/**
+ * Check if the error has a stack property
+ * If it does, it will try to parse the error message in the stack trace
+ * and replace it with the proper code and message
+ */
+const maybeFixErrorStack = (error: object) => {
+  if ('stack' in error && typeof error.stack === 'string') {
+    const stack = error.stack;
+
+    // (...){%@(match[1])::(match[2]);@%}(...)
+    const regex = /\{%@([^:]+)::([^@]+)@%\}/;
+    const match = stack.match(regex);
+
+    if (
+      match &&
+      match.length === 3 &&
+      typeof match[1] === 'string' &&
+      typeof match[2] === 'string'
+    ) {
+      error.stack = error.stack.replace(regex, `[${match[1]}]: ${match[2]}`);
+    }
+  }
+};
+
+const isVideoError = (
+  error: unknown
+): error is { code: string; message: string } =>
+  typeof error === 'object' &&
+  error != null &&
+  // @ts-expect-error error is still unknown
+  typeof error.message === 'string' &&
+  // @ts-expect-error error is still unknown
+  getCodeAndMessage(error.message) != null;
+
+const hasStack = (error: unknown): error is { stack: string } =>
+  typeof error === 'object' &&
+  error != null &&
+  'stack' in error &&
+  typeof error.stack === 'string';
+
+/**
+ * Tries to parse an error coming from native to a typed JS video error.
+ * @param {VideoError} nativeError The native error instance. This is a JSON in the legacy native module architecture.
+ * @returns A {@linkcode VideoRuntimeError} or {@linkcode VideoComponentError}, or the `nativeError` itself if it's not parsable
+ * @method
+ */
+export const tryParseNativeVideoError = <T>(
+  nativeError: T
+): (VideoRuntimeError | VideoComponentError) | T => {
+  if (isVideoError(nativeError)) {
+    const result = getCodeAndMessage(nativeError.message);
+
+    if (result == null) {
+      return nativeError;
+    }
+
+    const { code, message } = result;
+
+    maybeFixErrorStack(nativeError);
+
+    if (code.startsWith('view')) {
+      return new VideoComponentError(
+        code as VideoViewError,
+        message,
+        hasStack(nativeError) ? nativeError.stack : undefined
+      );
+    }
+
+    return new VideoRuntimeError(
+      // @ts-expect-error the code is string, we narrow it down to TS union.
+      code,
+      message,
+      hasStack(nativeError) ? nativeError.stack : undefined
+    );
+  }
+
+  return nativeError;
+};

package/src/core/types/VideoInformation.ts

@@ -0,0 +1,45 @@
+import type { Int64 } from 'react-native-nitro-modules';
+import type { VideoOrientation } from './VideoOrientation';
+
+export interface VideoInformation {
+  /**
+   * The bitrate of the video in kbps.
+   */
+  bitrate: number;
+
+  /**
+   * The width of the video in pixels.
+   */
+  width: number;
+
+  /**
+   * The height of the video in pixels.
+   */
+  height: number;
+
+  /**
+   * The duration of the video in seconds.
+   */
+  duration: Int64;
+
+  /**
+   * The file size of the video in bytes.
+   */
+  fileSize: Int64;
+
+  /**
+   * Whether the video is HDR.
+   */
+  isHDR: boolean;
+
+  /**
+   * Whether the video is live
+   */
+  isLive: boolean;
+
+  /**
+   * The orientation of the video.
+   * see {@link VideoOrientation}
+   */
+  orientation: VideoOrientation;
+}

package/src/core/types/VideoOrientation.ts

@@ -0,0 +1,8 @@
+export type VideoOrientation =
+  | 'portrait'
+  | 'landscape'
+  | 'portrait-upside-down'
+  | 'landscape-left'
+  | 'landscape-right'
+  | 'square'
+  | 'unknown';