react-native-theoplayer 9.3.0 → 9.5.0

package/src/api/track/TextTrack.ts

@@ -1,6 +1,20 @@
 import type { Track } from './Track';
 import type { TextTrackCue } from './TextTrackCue';
 
+/**
+ * The content type of a text track, represented by a value from the following list:
+ * <br/> - `'srt'`: The track contains SRT (SubRip Text) content.
+ * <br/> - `'ttml'`: The track contains TTML (Timed Text Markup Language) content.
+ * <br/> - `'webvtt'`: The track contains WebVTT (Web Video Text Tracks) content.
+ * <br/> - `'emsg'`: The track contains emsg (Event Message) content.
+ * <br/> - `'eventstream'`: The track contains Event Stream content.
+ * <br/> - `'id3'`: The track contains ID3 content.
+ * <br/> - `'cea608'`: The track contains CEA608 content.
+ * <br/> - `'daterange'`: The track contains HLS EXT-X-DATERANGE content.
+ *
+ * @category Media and Text Tracks
+ * @public
+ */
 export enum TextTrackType {
   cea608 = 'cea608',
   id3 = 'id3',
@@ -12,6 +26,17 @@ export enum TextTrackType {
   emsg = 'emsg',
 }
 
+/**
+ * The kind of the text track, represented by a value from the following list:
+ * <br/> - `'subtitles'`: The track contains subtitles.
+ * <br/> - `'captions'`: The track contains closed captions, a translation of dialogue and sound effects.
+ * <br/> - `'descriptions'`: The track contains descriptions, a textual description of the video.
+ * <br/> - `'chapters'`: The track contains chapter titles.
+ * <br/> - `'metadata'`: The track contains metadata. This track will not serve display purposes.
+ *
+ * @category Media and Text Tracks
+ * @public
+ */
 export enum TextTrackKind {
   captions = 'captions',
   chapters = 'chapters',
@@ -21,12 +46,32 @@ export enum TextTrackKind {
   thumbnails = 'thumbnails',
 }
 
+/**
+ * The mode of the text track, represented by a value from the following list:
+ * <br/> - `'disabled'`: The track is disabled.
+ * <br/> - `'hidden'`: The track is hidden.
+ * <br/> - `'showing'`: The track is showing.
+ *
+ * @remarks
+ * <br/> - A disabled track is not displayed and exposes no active cues, nor fires cue events.
+ * <br/> - A hidden track is not displayed but exposes active cues and fires cue events.
+ * <br/> - A showing track is displayed, exposes active cues and fires cue events.
+ *
+ * @category Media and Text Tracks
+ * @public
+ */
 export enum TextTrackMode {
   disabled = 'disabled',
   showing = 'showing',
   hidden = 'hidden',
 }
 
+/**
+ * Represents a text track of a media resource.
+ *
+ * @category Media and Text Tracks
+ * @public
+ */
 export interface TextTrack extends Track {
   /**
    * The kind of the text track, represented by a value from the following list:
@@ -101,7 +146,11 @@ export interface TextTrack extends Track {
 
 /**
  * Retain renderable tracks.
+ *
  * https://html.spec.whatwg.org/multipage/embedded-content.html#text-track-showing
+ *
+ * @category Media and Text Tracks
+ * @internal
  */
 export function filterRenderableTracks(textTracks: TextTrack[] | undefined): TextTrack[] | undefined {
   return textTracks && textTracks.filter((textTrack) => textTrack.kind === 'subtitles' || textTrack.kind === 'captions');
@@ -109,6 +158,9 @@ export function filterRenderableTracks(textTracks: TextTrack[] | undefined): Tex
 
 /**
  * Retain first thumbnail track encountered in the textTracks list.
+ *
+ * @category Media and Text Tracks
+ * @internal
  */
 export function filterThumbnailTracks(textTracks: TextTrack[] | undefined): TextTrack | undefined {
   return textTracks && textTracks.find(isThumbnailTrack);
@@ -116,27 +168,53 @@ export function filterThumbnailTracks(textTracks: TextTrack[] | undefined): Text
 
 /**
  * Query whether a track is a valid thumbnail track.
+ *
+ * @category Media and Text Tracks
+ * @internal
  */
 export function isThumbnailTrack(textTrack: TextTrack | undefined): boolean {
   return !!textTrack && (textTrack.kind === 'thumbnails' || (textTrack.kind === 'metadata' && textTrack.label === 'thumbnails'));
 }
-
+/**
+ * Query whether a track is a given cue.
+ *
+ * @category Media and Text Tracks
+ * @internal
+ */
 export function hasTextTrackCue(textTrack: TextTrack, cue: TextTrackCue): boolean {
   return !!(textTrack.cues && cue && textTrack.cues.find((c) => cue.uid === c.uid));
 }
 
+/**
+ * Removes a cue from a text track.
+ *
+ * @category Media and Text Tracks
+ * @internal
+ */
 export function removeTextTrackCue(textTrack?: TextTrack, cue?: TextTrackCue) {
   if (textTrack && textTrack.cues && cue && hasTextTrackCue(textTrack, cue)) {
     textTrack.cues = textTrack.cues.filter((c) => c.uid !== cue.uid);
   }
 }
 
+/**
+ * Adds a cue to a text track.
+ *
+ * @category Media and Text Tracks
+ * @internal
+ */
 export function addTextTrackCue(textTrack?: TextTrack, cue?: TextTrackCue) {
   if (textTrack && textTrack.cues && cue && !hasTextTrackCue(textTrack, cue)) {
     textTrack.cues.push(cue);
   }
 }
 
+/**
+ * Returns a cue from a text track by uid.
+ *
+ * @category Media and Text Tracks
+ * @internal
+ */
 export function findTextTrackByUid(textTracks: TextTrack[], uid: number): TextTrack | undefined {
   return textTracks.find((t) => t.uid === uid);
 }

package/src/api/track/TextTrackCue.ts

@@ -1,6 +1,7 @@
 /**
  * Represents a cue of a text track.
  *
+ * @category Media and Text Tracks
  * @public
  */
 export interface TextTrackCue {

package/src/api/track/TextTrackStyle.ts

@@ -1,6 +1,7 @@
 /**
  * The text track style API.
  *
+ * @category Media and Text Tracks
  * @public
  */
 export interface TextTrackStyle {
@@ -15,7 +16,7 @@ export interface TextTrackStyle {
    * @example
    * <br/> - `red` will set the color of the text to red.
    * <br/> - `#ff0000` will set the color of the text to red.
-   * <br/> - Available on Web only: `rgba(255,0,0,0.5)` will set the color of the text to red, with 50% opacity.
+   * <br/> - Available for Web only: `rgba(255,0,0,0.5)` will set the color of the text to red, with 50% opacity.
    */
   fontColor: string | undefined;
 
@@ -36,21 +37,22 @@ export interface TextTrackStyle {
    * @example
    * <br/> - `red` will set the background color of the text track to red.
    * <br/> - `#ff0000` will set the background color of the text track to red.
-   * <br/> - Available on Web only: `rgba(255,0,0,0.5)` will set the background color of the text track to red, with 50% opacity.
+   * <br/> - Available for Web only: `rgba(255,0,0,0.5)` will set the background color of the text track to red, with 50% opacity.
    */
   backgroundColor: string | undefined;
 
   /**
    * The window color for the text track.
    *
+   * @platform web,android
+   *
    * @remarks
    * <br/> - This targets the area covering the full width of the text track.
-   * <br/> - Available on Web and Android only.
    *
    * @example
    * <br/> - `red` will set the background color of the window of the text track to red.
    * <br/> - `#ff0000` will set the background color of the window of the text track to red.
-   * <br/> - Available on Web only: `rgba(255,0,0,0.5)` will set the background color of the window of the text track to red, with 50% opacity.
+   * <br/> - Available for Web only: `rgba(255,0,0,0.5)` will set the background color of the window of the text track to red, with 50% opacity.
    */
   windowColor: string | undefined;
 
@@ -60,15 +62,14 @@ export interface TextTrackStyle {
    * <br/> - `'dropshadow'`
    * <br/> - `'raised'`
    * <br/> - `'depressed'`
-   * <br/> - `'uniform`
+   * <br/> - `'uniform'`
    */
   edgeStyle: EdgeStyle | undefined;
 
   /**
    * The edge color for the text track.
    *
-   * @remarks
-   * <br/> - Available on Android only.
+   * @platform android
    */
   edgeColor: string | undefined;
 
@@ -83,9 +84,10 @@ export interface TextTrackStyle {
   /**
    * The bottom margin of the area where subtitles are being rendered.
    *
+   * @platform web,android
+   *
    * @remarks
    * <br/> - The margin is in number of pixels.
-   * <br/> - Available on Web only.
    */
   marginBottom: number | undefined;
   /**
@@ -98,10 +100,11 @@ export interface TextTrackStyle {
   /**
    * The right margin  of the area where subtitles are being rendered.
    *
+   * @platform web,android
+   *
    * @remarks
    * <br/> - The margin is in number of pixels.
    * <br/> - Useful for pushing the subtitles left, so they don't overlap with the UI.
-   * <br/> - Available on Web only.
    */
   marginRight: number | undefined;
 }
@@ -114,6 +117,7 @@ export interface TextTrackStyle {
  * <br/> - `'depressed'`
  * <br/> - `'uniform'`
  *
+ * @category Media and Text Tracks
  * @public
  */
 export enum EdgeStyle {

package/src/api/track/Track.ts

@@ -4,6 +4,7 @@
  * @remarks
  * <br/> - A specific track type (e.g. {@link TextTrack}) will always be used.
  *
+ * @category Media and Text Tracks
  * @public
  */
 export interface Track {
@@ -46,18 +47,42 @@ export interface Track {
   readonly language: string;
 }
 
+/**
+ * Checks whether a track list contains a given track.
+ *
+ * @category Media and Text Tracks
+ * @internal
+ */
 export function hasTrack<TTrack extends Track>(trackList: TTrack[], track: TTrack): boolean {
   return !!(trackList && track && trackList.find((t) => t.uid === track.uid));
 }
 
+/**
+ * Removes a track from a track list.
+ *
+ * @category Media and Text Tracks
+ * @internal
+ */
 export function removeTrack<TTrack extends Track>(trackList: TTrack[], track: TTrack): TTrack[] {
   return trackList && track ? trackList.filter((t) => t.uid !== track.uid) : trackList;
 }
 
+/**
+ * Adds a track to a track list.
+ *
+ * @category Media and Text Tracks
+ * @internal
+ */
 export function addTrack<TTrack extends Track>(trackList: TTrack[], track: TTrack): TTrack[] {
   return trackList && track && !hasTrack(trackList, track) ? sortTracks([...trackList, track]) : trackList;
 }
 
+/**
+ * Sort a track list based on the track's uids, which is how they are listed in the manifest.
+ *
+ * @category Media and Text Tracks
+ * @internal
+ */
 export function sortTracks<TTrack extends Track>(trackList?: TTrack[]): TTrack[] {
   return trackList?.sort((t1: TTrack, t2: TTrack) => t1.uid - t2.uid) || [];
 }

package/src/api/ui/UIConfiguration.ts

@@ -1,6 +1,7 @@
 /**
  * Describes the UI related configuration of the player.
  *
+ * @category UI
  * @public
  */
 export interface UIConfiguration {

package/src/internal/adapter/DefaultNativePlayerState.ts

@@ -25,6 +25,7 @@ export class DefaultNativePlayerState extends DefaultTextTrackState implements N
   seeking = false;
   volume = 1;
   currentTime = 0;
+  currentProgramDateTime: number | undefined = undefined;
   duration = NaN;
   playbackRate = 1;
   preload: PreloadType = 'none';

package/src/internal/adapter/THEOplayerAdapter.ts

@@ -108,6 +108,7 @@ export class THEOplayerAdapter extends DefaultEventDispatcher<PlayerEventMap> im
 
   private onTimeupdate = (event: TimeUpdateEvent) => {
     this._state.currentTime = event.currentTime;
+    this._state.currentProgramDateTime = event.currentProgramDateTime;
   };
 
   private onResize = (event: ResizeEvent) => {
@@ -267,6 +268,10 @@ export class THEOplayerAdapter extends DefaultEventDispatcher<PlayerEventMap> im
     NativePlayerModule.setCurrentTime(this._view.nativeHandle, seekTime);
   }
 
+  get currentProgramDateTime(): number | undefined {
+    return this._state.currentProgramDateTime;
+  }
+
   get duration(): number {
     return this._state.duration;
   }

package/src/internal/adapter/THEOplayerWebAdapter.ts

@@ -327,6 +327,10 @@ export class THEOplayerWebAdapter extends DefaultEventDispatcher<PlayerEventMap>
     }
   }
 
+  get currentProgramDateTime(): number | undefined {
+    return this._player?.currentProgramDateTime?.getTime();
+  }
+
   get aspectRatio(): AspectRatio {
     return AspectRatio.FIT;
   }

package/src/internal/cache/MediaCache.ts

@@ -150,4 +150,10 @@ export class NativeMediaCache extends DefaultEventDispatcher<CacheEventMap> impl
   }
 }
 
+/**
+ * The media cache API.
+ *
+ * @category Caching
+ * @public
+ */
 export const MediaCache: MediaCacheAPI = new NativeMediaCache();

package/src/internal/drm/ContentProtectionRegistry.ts

@@ -172,4 +172,10 @@ export class NativeContentProtectionRegistry implements ContentProtectionAPI {
   };
 }
 
+/**
+ * The registry for adding custom content protection (DRM) integrations.
+ *
+ * @category Content Protection
+ * @public
+ */
 export const ContentProtectionRegistry: ContentProtectionAPI = new NativeContentProtectionRegistry();

package/src/manifest.json

@@ -1 +1 @@
-{"version":"9.3.0","buildDate":"2025-06-02T11:43:22.126Z"}
+{"version":"9.5.0","buildDate":"2025-06-20T10:02:00.763Z"}

package/src/plugins/expo/Common.ts

@@ -0,0 +1,20 @@
+export type Extension = 'ima' | 'dai' | 'cast' | 'theoads' | 'millicast' | 'sideloaded-texttracks';
+
+export interface THEOplayerPluginAndroidProps {
+  extensions?: Extension[];
+}
+
+export interface THEOplayerPluginIOSProps {
+  extensions?: Extension[];
+}
+
+export interface THEOplayerPluginProps {
+  // Top-level extensions
+  extensions?: Extension[];
+
+  // Per-platform extensions, specific for Android
+  android?: THEOplayerPluginAndroidProps;
+
+  // Per-platform extensions, specific for iOS
+  ios?: THEOplayerPluginIOSProps;
+}

package/src/plugins/expo/withCustomPod.ts

@@ -0,0 +1,28 @@
+import { withDangerousMod } from '@expo/config-plugins';
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Add a custom pod-line to Podfile.
+ */
+function addPodToPodfile(contents: string, podLine: string) {
+  const lines = contents.split('\n');
+  const targetIndex = lines.findIndex((line: string) => line.trim().startsWith("target '")) + 1;
+  if (targetIndex > 0 && !lines.includes(podLine)) {
+    lines.splice(targetIndex, 0, podLine);
+  }
+  return lines.join('\n');
+}
+
+export const withCustomPod = (config: any, podLine: string) => {
+  return withDangerousMod(config, [
+    'ios',
+    async (config) => {
+      const podfilePath = path.join(config.modRequest.projectRoot, 'ios', 'Podfile');
+      const contents = fs.readFileSync(podfilePath, 'utf8');
+      const newContents = addPodToPodfile(contents, podLine);
+      fs.writeFileSync(podfilePath, newContents);
+      return config;
+    },
+  ]);
+};

package/src/plugins/expo/withTHEOplayer.ts

@@ -0,0 +1,11 @@
+import { ConfigPlugin } from '@expo/config-plugins';
+import { withTHEOplayerAndroid } from './withTHEOplayerAndroid';
+import { withTHEOplayerIOS } from './withTHEOplayerIOS';
+
+const withTHEOplayerWrapper: ConfigPlugin = (config, props: any) => {
+  config = withTHEOplayerAndroid(config, props);
+  config = withTHEOplayerIOS(config, props);
+  return config;
+};
+
+export default withTHEOplayerWrapper;

package/src/plugins/expo/withTHEOplayerAndroid.ts

@@ -0,0 +1,53 @@
+import { ConfigPlugin, withProjectBuildGradle, withGradleProperties } from '@expo/config-plugins';
+import { PropertiesItem } from '@expo/config-plugins/build/android/Properties';
+import { THEOplayerPluginProps, Extension } from './Common';
+
+function mapAndroidExtensionKey(ext: Extension): string | undefined {
+  switch (ext) {
+    case 'ima':
+      return 'THEOplayer_extensionGoogleIMA';
+    case 'dai':
+      return 'THEOplayer_extensionGoogleDAI';
+    case 'cast':
+      return 'THEOplayer_extensionCast';
+    case 'theoads':
+      return 'THEOplayer_extensionTHEOads';
+    case 'millicast':
+      return 'THEOplayer_extensionMillicast';
+    default:
+      return undefined;
+  }
+}
+
+const applyAndroidExtensions: ConfigPlugin<THEOplayerPluginProps['extensions']> = (config, extensions) => {
+  return withGradleProperties(config, (config) => {
+    extensions?.forEach((ext) => {
+      const key = mapAndroidExtensionKey(ext);
+      if (key) {
+        const prop: PropertiesItem = { type: 'property', key, value: 'true' };
+        config.modResults.push(prop);
+      }
+    });
+    return config;
+  });
+};
+
+export const withTHEOplayerAndroid: ConfigPlugin<THEOplayerPluginProps> = (config, props = {}) => {
+  const { extensions, android } = props;
+
+  // Apply Android extensions
+  config = applyAndroidExtensions(config, android?.extensions ?? extensions);
+
+  // Add THEOplayer and local Maven repos to the project's repositories
+  return withProjectBuildGradle(config, (config) => {
+    const localMaven = 'maven { url("$rootDir/../node_modules/react-native-theoplayer/android/local") }';
+    const THEOplayerMaven = 'maven { url("https://maven.theoplayer.com/releases") }';
+
+    config.modResults.contents = config.modResults.contents.replace(
+      /allprojects\s*\{\s*repositories\s*\{/,
+      `$&\n\t\t${localMaven}\n\t\t${THEOplayerMaven}`,
+    );
+
+    return config;
+  });
+};

package/src/plugins/expo/withTHEOplayerIOS.ts

@@ -0,0 +1,44 @@
+import { ConfigPlugin } from '@expo/config-plugins';
+import { Extension, THEOplayerPluginProps } from './Common';
+import { withCustomPod } from './withCustomPod';
+
+const CAST_POD_LINE = `  pod 'react-native-google-cast', :git => 'https://github.com/Danesz/react-native-google-cast.git', branch: 'feature/guestmode_apple_silicon'`;
+
+function mapIOSExtensionKey(ext: Extension): string | undefined {
+  switch (ext) {
+    case 'ima':
+      return 'GOOGLE_IMA';
+    case 'cast':
+      return 'CHROMECAST';
+    case 'theoads':
+      return 'THEO_ADS';
+    case 'millicast':
+      return 'MILLICAST';
+    case 'sideloaded-texttracks':
+      return 'SIDELOADED_TEXTTRACKS';
+    default:
+      return undefined;
+  }
+}
+
+const applyIOSExtensions: ConfigPlugin<THEOplayerPluginProps['extensions']> = (config, extensions) => {
+  const iosFeatures = extensions?.map(mapIOSExtensionKey)?.filter((f): f is string => !!f);
+
+  if (iosFeatures?.length ?? 0 > 0) {
+    const featureList = iosFeatures?.join(',');
+    console.log(`Setting THEO_FEATURES="${featureList}"`);
+    process.env.THEO_FEATURES = featureList;
+  }
+
+  // Align react-native-google-cast dependency
+  if (extensions?.includes('cast')) {
+    config = withCustomPod(config, CAST_POD_LINE);
+  }
+
+  return config;
+};
+
+export const withTHEOplayerIOS: ConfigPlugin<THEOplayerPluginProps> = (config, props = {}) => {
+  const { extensions, ios } = props;
+  return applyIOSExtensions(config, ios?.extensions ?? extensions);
+};