react-native-theoplayer 1.0.0 → 1.1.0

package/src/api/THEOplayerView.ts

@@ -0,0 +1,221 @@
+import type { SourceDescription } from './source/SourceDescription';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type {
+  DurationChangeEvent,
+  ErrorEvent,
+  LoadedMetadataEvent,
+  ReadyStateChangeEvent,
+  TimeUpdateEvent,
+  ProgressEvent,
+  SegmentNotFoundEvent,
+} from './event/PlayerEvent';
+import type { TextTrackEvent, TextTrackListEvent } from './event/TrackEvent';
+import type { HostComponent } from 'react-native';
+import type { PlayerConfiguration } from './config/PlayerConfiguration';
+
+export interface THEOplayerViewProps {
+  /**
+   * The player configuration with THEOplayer license.
+   */
+  config?: PlayerConfiguration;
+
+  /**
+   * A source description that determines the current media resource.
+   */
+  source: SourceDescription;
+
+  /**
+   * Used to set the player's paused state.
+   *
+   * @remarks
+   * <br/> - If paused is initially set to `true`, play-out will start once the source is set.
+   */
+  paused?: boolean;
+
+  /**
+   * Used to set the playback rate of the media.
+   *
+   * @example
+   * <br/> - `playbackRate = 0.70` will slow down the playback rate of the media by 30%.
+   * <br/> - `playbackRate = 1.25` will speed up the playback rate of the media by 25%.
+   *
+   * @remarks
+   * <br/> - Playback rate is represented by a number where `1` is default playback speed.
+   * <br/> - Playback rate must be a positive number.
+   * <br/> - It is recommended that you limit the range to between 0.5 and 4.
+   */
+  playbackRate?: number;
+
+  /**
+   * Used to set the volume of the audio.
+   *
+   * @remarks
+   * <br/> - Volume is represented by a floating point number between `0.0` and `1.0`.
+   */
+  volume?: number;
+
+  /**
+   * Determines whether audio is muted.
+   */
+  muted?: boolean;
+
+  /**
+   * Determines whether the player is currently playing in fullscreen.
+   */
+  fullscreen?: boolean;
+
+  /**
+   * Used to set the current selected text track by passing its `uid`, or `null` to select none.
+   */
+  selectedTextTrack?: number | null;
+
+  /**
+   * Used to set the current selected video track by passing its `uid`, or `null` to select none.
+   */
+  selectedVideoTrack?: number | null;
+
+  /**
+   * Used to set the current selected audio track by passing its `uid`, or `null` to select none.
+   */
+  selectedAudioTrack?: number | null;
+
+  /**
+   * The style applied to the player view.
+   */
+  style?: StyleProp<ViewStyle>;
+
+  /**
+   * Invoked before the player goes to fullscreen.
+   */
+  onFullscreenPlayerWillPresent?: () => void;
+
+  /**
+   * Invoked after the player went to fullscreen.
+   */
+  onFullscreenPlayerDidPresent?: () => void;
+
+  /**
+   * Invoked before the player returns from fullscreen.
+   */
+  onFullscreenPlayerWillDismiss?: () => void;
+
+  /**
+   * Invoked after the player returned from fullscreen.
+   */
+  onFullscreenPlayerDidDismiss?: () => void;
+
+  /**
+   * Invoked when the player's buffering state has changed.
+   *
+   * @remarks
+   * <br/> - The `isBuffering` value is typically coupled to showing/hiding a loading indicator.
+   *
+   * @param isBuffering A value that indicates whether the player is buffering.
+   */
+  onBufferingStateChange?: (isBuffering: boolean) => void;
+
+  /**
+   * Invoked when the player receives a new source description.
+   */
+  onSourceChange?: () => void;
+
+  /**
+   * Invoked when the player starts loading the manifest.
+   */
+  onLoadStart?: () => void;
+
+  /**
+   * Invoked when the player has determined the duration and dimensions of the
+   * media resource, and the text and media tracks are ready.
+   */
+  onLoadedMetadata?: (event: LoadedMetadataEvent) => void;
+
+  /**
+   * Invoked when the player can render the media data at the current playback position for the first time.
+   */
+  onLoadedData?: () => void;
+
+  /**
+   * Invoked when the player's readyState has changed.
+   */
+  onReadyStateChange?: (event: ReadyStateChangeEvent) => void;
+
+  /**
+   * Invoked when an error occurs.
+   */
+  onError?: (event: ErrorEvent) => void;
+
+  /**
+   * Invoked each time the player has loaded media data.
+   */
+  onProgress?: (event: ProgressEvent) => void;
+
+  /**
+   * Invoked when the player's internal paused state changes to `false`.
+   */
+  onPlay?: () => void;
+
+  /**
+   * Invoked when playback is ready to start after having been paused or delayed due to
+   * lack of media data.
+   */
+  onPlaying?: () => void;
+
+  /**
+   * Invoked when the player's internal paused state changes to `true`.
+   */
+  onPause?: () => void;
+
+  /**
+   * Invoked when a seek operation starts and the player is seeking a new position.
+   */
+  onSeeking?: () => void;
+
+  /**
+   * Invoked when a seek operation completed and the current playback position has changed
+   */
+  onSeeked?: () => void;
+
+  /**
+   * Invoked when playback has stopped because the end of the media was reached or because
+   * no further data is available.
+   */
+  onEnded?: () => void;
+
+  /**
+   * Invoked when the current playback position changed.
+   */
+  onTimeUpdate?: (event: TimeUpdateEvent) => void;
+
+  /**
+   * Invoked when the player's duration attribute has been updated.
+   */
+  onDurationChange?: (event: DurationChangeEvent) => void;
+
+  /**
+   * Invoked when a segment can not be found.
+   *
+   * @remarks
+   * <br/> - Only dispatched on DASH streams.
+   */
+  onSegmentNotFound?: (event: SegmentNotFoundEvent) => void;
+
+  /**
+   * Invoked when a text track list event occurs.
+   */
+  onTextTrackListEvent?: (event: TextTrackListEvent) => void;
+
+  /**
+   * Invoked when a text track event occurs.
+   */
+  onTextTrackEvent?: (event: TextTrackEvent) => void;
+}
+
+export interface THEOplayerViewComponent extends HostComponent<THEOplayerViewProps> {
+  /**
+   * Seek to a new position.
+   *
+   * @param seekTime - new time, in milliseconds.
+   */
+  seek: (seekTime: number) => void;
+}

package/src/api/barrel.ts

@@ -0,0 +1,7 @@
+export * from './error/barrel';
+export * from './event/barrel';
+export * from './source/barrel';
+export * from './timeranges/barrel';
+export * from './track/barrel';
+export * from './config/barrel';
+export * from './THEOplayerView';

package/src/api/config/PlayerConfiguration.ts

@@ -0,0 +1,16 @@
+export interface PlayerConfiguration {
+  /**
+   * The license for the player
+   */
+  readonly license?: string;
+
+  /**
+   * The url to fetch the license for the player
+   */
+  readonly licenseUrl?: string;
+
+  /**
+   * Sets whether the native player is chromeless (without UI).
+   */
+  readonly chromeless?: boolean;
+}

package/src/api/config/barrel.ts

@@ -0,0 +1 @@
+export * from './PlayerConfiguration';

package/src/api/error/PlayerError.ts

@@ -0,0 +1,4 @@
+export interface PlayerError {
+  readonly errorCode: string;
+  readonly errorMessage: string;
+}

package/src/api/error/barrel.ts

@@ -0,0 +1 @@
+export * from './PlayerError';

package/src/api/event/PlayerEvent.ts

@@ -0,0 +1,66 @@
+import type { MediaTrack, PlayerError, TextTrack } from 'react-native-theoplayer';
+import type { TimeRange } from '../timeranges/TimeRange';
+
+export interface ErrorEvent {
+  error: PlayerError;
+}
+
+export interface LoadedMetadataEvent {
+  textTracks: TextTrack[];
+  audioTracks: MediaTrack[];
+  videoTracks: MediaTrack[];
+  duration: number;
+  selectedTextTrack: number | undefined;
+  selectedVideoTrack: number | undefined;
+  selectedAudioTrack: number | undefined;
+}
+
+export interface TimeUpdateEvent {
+  /**
+   * The player's current time, in msecs.
+   */
+  readonly currentTime: number;
+
+  /**
+   * The player's current program date time, in msecs.
+   */
+  readonly currentProgramDateTime?: number;
+}
+
+export interface DurationChangeEvent {
+  /**
+   * The player's new duration, in msecs.
+   */
+  readonly duration: number;
+}
+
+export interface ReadyStateChangeEvent {
+  /**
+   * The player's new ready state.
+   */
+  readonly readyState: number;
+}
+
+export interface ProgressEvent {
+  /**
+   * The ranges of the media resource that are seekable by the player.
+   */
+  readonly seekable: TimeRange[];
+}
+
+export interface SegmentNotFoundEvent {
+  /**
+   * Start time of the segment.
+   */
+  readonly segmentStartTime: number;
+
+  /**
+   * Descriptive error message.
+   */
+  readonly error: string;
+
+  /**
+   * Number of times the segment was retried.
+   */
+  readonly retryCount: number;
+}

package/src/api/event/TrackEvent.ts

@@ -0,0 +1,55 @@
+import type { TextTrack } from '../track/TextTrack';
+import type { TextTrackCue } from '../track/TextTrackCue';
+
+export enum TrackListEventType {
+  /**
+   * Dispatched when track has been added to the track list.
+   */
+  AddTrack,
+
+  /**
+   * Dispatched when track has been removed from the track list.
+   */
+  RemoveTrack,
+}
+
+export interface TextTrackListEvent {
+  /**
+   * The type of text track list event.
+   */
+  readonly type: TrackListEventType;
+
+  /**
+   * The relevant text track.
+   */
+  readonly track: TextTrack;
+}
+
+export enum TextTrackEventType {
+  /**
+   * Dispatched when cue has been added to the text track.
+   */
+  AddCue,
+
+  /**
+   * Dispatched when cue has been removed from the text track.
+   */
+  RemoveCue,
+}
+
+export interface TextTrackEvent {
+  /**
+   * The type of text track event.
+   */
+  readonly type: TextTrackEventType;
+
+  /**
+   * The text track's uid to which this cue belongs.
+   */
+  readonly trackUid: number;
+
+  /**
+   * The text track's cue.
+   */
+  readonly cue: TextTrackCue;
+}

package/src/api/event/barrel.ts

@@ -0,0 +1,2 @@
+export * from './PlayerEvent';
+export * from './TrackEvent';

package/src/api/source/SourceDescription.ts

@@ -0,0 +1,292 @@
+/**
+ * Represents a media resource.
+ *
+ * @remarks
+ * <br/> - Can be a string value representing the URL of a media resource, a {@link TypedSource}.
+ *
+ * @public
+ */
+import type { DashPlaybackConfiguration } from './dash/DashPlaybackConfiguration';
+import type { DRMConfiguration } from './drm/DRMConfiguration';
+import type { HlsPlaybackConfiguration } from './hls/HlsPlaybackConfiguration';
+import type { AdDescription } from './ads/Ads';
+
+export type Source = TypedSource;
+
+/**
+ * A media resource or list of media resources.
+ *
+ * @remarks
+ * <br/> - The order of sources when using a list determines their priority when attempting playback.
+ *
+ * @public
+ */
+export type Sources = Source | Source[];
+
+/**
+ * The cross-origin setting of a source, represented by a value from the following list:
+ * <br/> - `'anonymous'`: CORS requests will have the credentials flag set to 'same-origin'.
+ * <br/> - `'use-credentials'`: CORS requests will have the credentials flag set to 'include'.
+ * <br/> - `''`: Setting the empty string is the same as `'anonymous'`
+ *
+ * @remarks
+ * <br/> - See {@link https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes | The crossorigin attribute: Requesting CORS access to content}
+ *
+ * @public
+ */
+export type CrossOriginSetting = '' | 'anonymous' | 'use-credentials';
+
+/**
+ * Describes the configuration of a player's source.
+ *
+ * @public
+ */
+export interface SourceConfiguration {
+  /**
+   * List of {@link AdDescription}s to be queued for playback.
+   */
+  ads?: AdDescription[];
+
+  /**
+   * Content protection configuration.
+   */
+  contentProtection?: DRMConfiguration;
+
+  /**
+   * The poster of the media source.
+   *
+   * @remarks
+   * <br/> - An empty string (`''`) clears the current poster.
+   * <br/> - This poster has priority over {@link ChromelessPlayer.poster}.
+   */
+  poster?: string;
+
+  /**
+   * List of text tracks to be side-loaded with the media source.
+   *
+   * @remarks
+   * <br/> - A source change will reset side-loaded text tracks.
+   */
+  textTracks?: TextTrackDescription[];
+
+  /**
+   * The URL of a time server used by the player to synchronise the time in DASH sources.
+   *
+   * @remarks
+   * <br/> - The time server should return time in ISO-8601 format.
+   * <br/> - Overrides the time server provided the DASH manifest's `<UTCTiming>`.
+   * <br/> - All sources will use the time server. Alternatively, for one source use {@link BaseSource.timeServer}.
+   */
+  timeServer?: string;
+}
+
+/**
+ * Describes the configuration of a player's source.
+ *
+ * @public
+ */
+export interface SourceDescription extends SourceConfiguration {
+  /**
+   * One or more media resources for playback.
+   *
+   * @remarks
+   * <br/> - Multiple media sources should be used to increase platform compatibility. See examples below for important use cases.
+   * <br/> - The player will try each source in the provided order.
+   *
+   * @example
+   * In this example, the player will first try to play the DASH source.
+   * This might fail if the browser does not support the {@link https://www.widevine.com/ | Widevine} or {@link https://www.microsoft.com/playready/ | PlayReady} CDM, for example on Safari.
+   * In that case, the player will try to play the HLS source instead.
+   *
+   * ```
+   * [{
+   *   src: 'dash-source-with-drm.mpd'
+   *   contentProtection: {
+   *     widevine: {
+   *       licenseAcquisitionURL: 'https://license.company.com/wv'
+   *     },
+   *     playready: {
+   *       licenseAcquisitionURL: 'https://license.company.com/pr'
+   *     }
+   *   }
+   * },{
+   *   src: 'hls-source-with-drm.m3u8',
+   *   contentProtection: {
+   *     fairplay: {
+   *       certificateURL: 'https://license.company.com/fp'
+   *     }
+   *   }
+   * }]
+   * ```
+   *
+   * @example
+   * In this example, the player will first try to play the DASH source.
+   * This might fail if the browser does not support the {@link https://developer.mozilla.org/en-US/docs/Web/API/Media_Source_Extensions_API | Media Source Extensions API}.
+   * In that case, the player will try to play the MP4 source instead, though without features such as adaptive bitrate switching.
+   *
+   * ```
+   * [{
+   *   src: 'source.mpd'
+   * },{
+   *   src: 'source.mp4'
+   * }]
+   * ```
+   */
+  sources?: Sources;
+}
+
+/**
+ * Describes the configuration of a side-loaded text track.
+ *
+ * @public
+ */
+export interface TextTrackDescription {
+  /**
+   * Whether the text track should be enabled by default.
+   *
+   * @remarks
+   * <br/> - Only one text track per {@link TextTrack.kind} may be marked as default.
+   *
+   * @defaultValue `false`
+   */
+  default?: boolean;
+
+  /**
+   * The kind of the text track, represented by a value from the following list:
+   * <br/> - `'subtitles'`: The track provides subtitles, used to display subtitles in a video.
+   * <br/> - `'captions'`: The track provides a translation of dialogue and sound effects (suitable for users with a hearing impairment).
+   * <br/> - `'descriptions'`: The track provides a textual description of the video (suitable for users with a vision impairment).
+   * <br/> - `'chapters'`: The track provides chapter titles (suitable for navigating the media resource).
+   * <br/> - `'metadata'`: The track provides content used by scripts and is not visible for users.
+   *
+   * @remarks
+   * <br/> -  If an unrecognized value is provided, the player will interpret it as `'metadata'`.
+   *
+   * @defaultValue `'subtitles'`
+   */
+  kind?: string;
+
+  /**
+   * The format of the track, represented by a value from the following list:
+   * <br/> - `'srt'`
+   * <br/> - `'ttml'`
+   * <br/> - `'webvtt'`
+   * <br/> - `'emsg'`
+   * <br/> - `'eventstream'`
+   * <br/> - `'id3'`
+   * <br/> - `'cea608'`
+   * <br/> - `'daterange'`
+   *
+   * @defaultValue `''`
+   */
+  format?: string;
+
+  /**
+   * The source URL of the text track.
+   */
+  src: string;
+
+  /**
+   * The language of the text track.
+   */
+  srclang?: string;
+
+  /**
+   * A label for the text track.
+   *
+   * @remarks
+   * <br/> - This will be used as an identifier on the player API and in the UI.
+   */
+  label?: string;
+
+  /**
+   * The identifier of this text track.
+   *
+   * @internal
+   */
+  // Note: This works for HLS, but not for DASH.
+  id?: string;
+}
+
+/**
+ * Represents the common properties of a media resource.
+ *
+ * @public
+ */
+export interface BaseSource {
+  /**
+   * The URL of a time server used by the player to synchronise the time in DASH sources.
+   *
+   * @remarks
+   * <br/> - Available since v2.47.0.
+   * <br/> - The time server should return time in ISO-8601 format.
+   * <br/> - Overrides the time server provided the DASH manifest's `<UTCTiming>`.
+   * <br/> - Only this source will use the time server. Alternatively, for all source use {@link SourceConfiguration.timeServer}.
+   */
+  timeServer?: string;
+
+  /**
+   * Whether the source should be played in the low-latency-mode of the player.
+   *
+   * @defaultValue `false`
+   *
+   * @remarks
+   * <br/> - This setting must be `true` when using Low-Latency CMAF with ABR.
+   * <br/> - Available since v2.62.0.
+   */
+  lowLatency?: boolean;
+
+  /**
+   * The configuration for controlling playback of an MPEG-DASH stream.
+   *
+   * @remarks
+   * <br/> - Available since v2.79.0.
+   * <br/> - Ignored for non-DASH streams.
+   */
+  dash?: DashPlaybackConfiguration;
+
+  /**
+   * The configuration for controlling playback of an HLS stream.
+   *
+   * @remarks
+   * <br/> - Available since v2.82.0.
+   * <br/> - Ignored for non-HLS streams.
+   */
+  hls?: HlsPlaybackConfiguration;
+}
+
+/**
+ * Represents a media resource characterized by a URL to the resource and optionally information about the resource.
+ *
+ * @public
+ */
+export interface TypedSource extends BaseSource {
+  /**
+   * The source URL of the media resource.
+   *
+   * @remarks
+   * <br/> - Required if the `ssai` property is absent.
+   * <br/> - Available since v2.4.0.
+   */
+  src?: string;
+
+  /**
+   * The content type (MIME type) of the media resource, represented by a value from the following list:
+   * <br/> - `'application/dash+xml'`: The media resource is an MPEG-DASH stream.
+   * <br/> - `'application/x-mpegURL'` or `'application/vnd.apple.mpegurl'`: The media resource is an HLS stream.
+   * <br/> - `'video/mp4'`, `'video/webm'` and other formats: The media resource should use native HTML5 playback if supported by the browser.
+   * <br/> - `'application/vnd.theo.hesp+json'`: The media resource is an HESP stream.
+   *
+   * @remarks
+   * <br/> - Available since v2.4.0.
+   */
+  type?: string;
+
+  /**
+   * The content protection parameters for the media resource.
+   *
+   * @remarks
+   * <br/> - Available since v2.15.0.
+   */
+  contentProtection?: DRMConfiguration;
+}