@stepincto/expo-video 1.0.0

package/src/VideoPlayerEvents.types.ts

@@ -0,0 +1,313 @@
+import {
+  PlayerError,
+  SubtitleTrack,
+  VideoPlayerStatus,
+  VideoSource,
+  VideoTrack,
+  AudioTrack,
+} from './VideoPlayer.types';
+
+/**
+ * Handlers for events which can be emitted by the player.
+ */
+export type VideoPlayerEvents = {
+  /**
+   * Handler for an event emitted when the status of the player changes.
+   */
+  statusChange(payload: StatusChangeEventPayload): void;
+
+  /**
+   * Handler for an event emitted when the player starts or stops playback.
+   */
+  playingChange(payload: PlayingChangeEventPayload): void;
+
+  /**
+   * Handler for an event emitted when the `playbackRate` property of the player changes.
+   */
+  playbackRateChange(payload: PlaybackRateChangeEventPayload): void;
+
+  /**
+   * Handler for an event emitted when the `volume` of `muted` property of the player changes.
+   */
+  volumeChange(payload: VolumeChangeEventPayload): void;
+
+  /**
+   * Handler for an event emitted when the `muted` property of the player changes
+   */
+  mutedChange(payload: MutedChangeEventPayload): void;
+
+  /**
+   * Handler for an event emitted when the player plays to the end of the current source.
+   */
+  playToEnd(): void;
+
+  /**
+   * Handler for an event emitted in a given interval specified by the `timeUpdateEventInterval`.
+   */
+  timeUpdate(payload: TimeUpdateEventPayload): void;
+
+  /**
+   * Handler for an event emitted when the current media source of the player changes.
+   */
+  sourceChange(payload: SourceChangeEventPayload): void;
+
+  /**
+   * Handler for an event emitted when the available subtitle tracks change.
+   */
+  availableSubtitleTracksChange(payload: AvailableSubtitleTracksChangeEventPayload): void;
+
+  /**
+   * Handler for an event emitted when the current subtitle track changes.
+   */
+  subtitleTrackChange(payload: SubtitleTrackChangeEventPayload): void;
+
+  /**
+   * Handler for an event emitted when the available audio tracks change.
+   */
+  availableAudioTracksChange(payload: AvailableAudioTracksChangeEventPayload): void;
+
+  /**
+   * Handler for an event emitted when the current audio track changes.
+   */
+  audioTrackChange(payload: AudioTrackChangeEventPayload): void;
+
+  /**
+   * Handler for an event emitted when the current video track changes.
+   */
+  videoTrackChange(payload: VideoTrackChangeEventPayload): void;
+
+  /**
+   * Handler for an event emitted when the player has finished loading metadata for the current video source.
+   * This event is emitted when the player has finished metadata for a [`VideoSource`](#videosource), but it doesn't mean that there is enough data buffered to start the playback.
+   */
+  sourceLoad(payload: SourceLoadEventPayload): void;
+};
+
+/**
+ * Data delivered with the [`statusChange`](#videoplayerevents) event.
+ */
+export type StatusChangeEventPayload = {
+  /**
+   * New status of the player.
+   */
+  status: VideoPlayerStatus;
+
+  /**
+   * Previous status of the player.
+   */
+  oldStatus?: VideoPlayerStatus;
+
+  /**
+   * Error object containing information about the error that occurred.
+   */
+  error?: PlayerError;
+};
+
+/**
+ * Data delivered with the [`playingChange`](#videoplayerevents) event.
+ */
+export type PlayingChangeEventPayload = {
+  /**
+   * Boolean value whether the player is currently playing.
+   */
+  isPlaying: boolean;
+
+  /**
+   * Previous value of the `isPlaying` property.
+   */
+  oldIsPlaying?: boolean;
+};
+
+/**
+ * Data delivered with the [`playbackRateChange`](#videoplayerevents) event.
+ */
+export type PlaybackRateChangeEventPayload = {
+  /**
+   * Float value indicating the current playback speed of the player.
+   */
+  playbackRate: number;
+
+  /**
+   * Previous value of the `playbackRate` property.
+   */
+  oldPlaybackRate?: number;
+};
+
+/**
+ * Data delivered with the [`volumeChange`](#videoplayerevents) event.
+ */
+export type VolumeChangeEventPayload = {
+  /**
+   * Float value indicating the current volume of the player.
+   */
+  volume: number;
+
+  /**
+   * Previous value of the `volume` property.
+   */
+  oldVolume?: number;
+};
+
+/**
+ * Data delivered with the [`mutedChange`](#videoplayerevents) event.
+ */
+export type MutedChangeEventPayload = {
+  /**
+   * Boolean value whether the player is currently muted.
+   */
+  muted: boolean;
+
+  /**
+   * Previous value of the `isMuted` property.
+   */
+  oldMuted?: boolean;
+};
+
+/**
+ * Data delivered with the [`sourceChange`](#videoplayerevents) event.
+ */
+export type SourceChangeEventPayload = {
+  /**
+   * New source of the player.
+   */
+  source: VideoSource;
+
+  /**
+   * Previous source of the player.
+   */
+  oldSource?: VideoSource;
+};
+
+/**
+ * Data delivered with the [`timeUpdate`](#videoplayerevents) event, contains information about the current playback progress.
+ */
+export type TimeUpdateEventPayload = {
+  /**
+   * Float value indicating the current playback time in seconds. Same as the [`currentTime`](#currenttime) property.
+   */
+  currentTime: number;
+
+  /**
+   * The exact timestamp when the currently displayed video frame was sent from the server,
+   * based on the `EXT-X-PROGRAM-DATE-TIME` tag in the livestream metadata.
+   * Same as the [`currentLiveTimestamp`](#currentlivetimestamp) property.
+   * @platform android
+   * @platform ios
+   */
+  currentLiveTimestamp: number | null;
+
+  /**
+   * Float value indicating the latency of the live stream in seconds.
+   * Same as the [`currentOffsetFromLive`](#currentoffsetfromlive) property.
+   * @platform android
+   * @platform ios
+   */
+  currentOffsetFromLive: number | null;
+
+  /**
+   * Float value indicating how far the player has buffered the video in seconds.
+   * Same as the [`bufferedPosition`](#bufferedPosition) property.
+   * @platform android
+   * @platform ios
+   */
+  bufferedPosition: number;
+};
+
+export type SubtitleTrackChangeEventPayload = {
+  /**
+   * New subtitle track of the player.
+   */
+  subtitleTrack: SubtitleTrack | null;
+
+  /**
+   * Previous subtitle track of the player.
+   */
+  oldSubtitleTrack?: SubtitleTrack | null;
+};
+
+/**
+ * Data delivered with the [`videoTrackChange`](#videoplayerevents) event, contains information about the video track which is currently being played.
+ */
+export type VideoTrackChangeEventPayload = {
+  /**
+   * New video track of the player.
+   */
+  videoTrack: VideoTrack | null;
+
+  /**
+   * Previous video track of the player.
+   */
+  oldVideoTrack?: VideoTrack | null;
+};
+
+/**
+ * TODO @behenate: For SDK53 mark as deprecated in favor of SourceLoadEventPayload
+ * @hidden
+ */
+export type AvailableSubtitleTracksChangeEventPayload = {
+  /**
+   * Array of available subtitle tracks.
+   */
+  availableSubtitleTracks: SubtitleTrack[];
+
+  /**
+   * Previous array of available subtitle tracks.
+   */
+  oldAvailableSubtitleTracks?: SubtitleTrack[];
+};
+
+/**
+ * Data delivered with the [`sourceLoad`](#videoplayerevents) event, contains information about the video source that has finished loading.
+ */
+export type SourceLoadEventPayload = {
+  /**
+   * The video source that has been loaded.
+   */
+  videoSource: VideoSource | null;
+
+  /**
+   * Duration of the video source in seconds.
+   */
+  duration: number;
+
+  /**
+   * Video tracks available for the loaded video source.
+   *
+   * > On iOS, when using a HLS source, make sure that the uri contains `.m3u8` extension or that the [`contentType`](#contenttype) property of the [`VideoSource`](#videosource) has been set to `'hls'`. Otherwise, the video tracks will not be available.
+   */
+  availableVideoTracks: VideoTrack[];
+
+  /**
+   * Subtitle tracks available for the loaded video source.
+   */
+  availableSubtitleTracks: SubtitleTrack[];
+
+  /**
+   * Audio tracks available for the loaded video source.
+   */
+  availableAudioTracks: AudioTrack[];
+};
+
+type AudioTrackChangeEventPayload = {
+  /**
+   * New audio track of the player.
+   */
+  audioTrack: AudioTrack | null;
+
+  /**
+   * Previous audio track of the player.
+   */
+  oldAudioTrack?: AudioTrack | null;
+};
+
+type AvailableAudioTracksChangeEventPayload = {
+  /**
+   * Array of available audio tracks.
+   */
+  availableAudioTracks: AudioTrack[];
+
+  /**
+   * Previous array of available audio tracks.
+   */
+  oldAvailableAudioTracks?: AudioTrack[];
+};

package/src/VideoThumbnail.ts

@@ -0,0 +1,31 @@
+import { SharedRef } from 'expo';
+
+import NativeVideoModule from './NativeVideoModule';
+
+/**
+ * Represents a video thumbnail that references a native image.
+ * Instances of this class can be passed as a source to the `Image` component from `expo-image`.
+ * @platform android
+ * @platform ios
+ */
+export declare class VideoThumbnail extends SharedRef<'image'> {
+  /**
+   * Width of the created thumbnail.
+   */
+  width: number;
+  /**
+   * Height of the created thumbnail.
+   */
+  height: number;
+  /**
+   * The time in seconds at which the thumbnail was to be created.
+   */
+  requestedTime: number;
+  /**
+   * The time in seconds at which the thumbnail was actually generated.
+   * @platform ios
+   */
+  actualTime: number;
+}
+
+export default NativeVideoModule.VideoThumbnail;

package/src/VideoView.tsx

@@ -0,0 +1,86 @@
+import { ReactNode, PureComponent, createRef } from 'react';
+
+import NativeVideoModule from './NativeVideoModule';
+import NativeVideoView, { NativeTextureVideoView } from './NativeVideoView';
+import type { VideoPlayer } from './VideoPlayer.types';
+import type { VideoViewProps } from './VideoView.types';
+
+/**
+ * Returns whether the current device supports Picture in Picture (PiP) mode.
+ *
+ * > **Note:** All major web browsers support Picture in Picture (PiP) mode except Firefox.
+ * > For more information, see [MDN web docs](https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API#browser_compatibility).
+ * @returns A `boolean` which is `true` if the device supports PiP mode, and `false` otherwise.
+ * @platform android
+ * @platform ios
+ * @platform web
+ */
+export function isPictureInPictureSupported(): boolean {
+  return NativeVideoModule.isPictureInPictureSupported();
+}
+
+export class VideoView extends PureComponent<VideoViewProps> {
+  nativeRef = createRef<any>();
+
+  /**
+   * Enters fullscreen mode.
+   */
+  async enterFullscreen(): Promise<void> {
+    return await this.nativeRef.current?.enterFullscreen();
+  }
+
+  /**
+   * Exits fullscreen mode.
+   */
+  async exitFullscreen(): Promise<void> {
+    return await this.nativeRef.current?.exitFullscreen();
+  }
+
+  /**
+   * Enters Picture in Picture (PiP) mode. Throws an exception if the device does not support PiP.
+   * > **Note:** Only one player can be in Picture in Picture (PiP) mode at a time.
+   *
+   * > **Note:** The `supportsPictureInPicture` property of the [config plugin](#configuration-in-app-config)
+   * > has to be configured for the PiP to work.
+   * @platform android
+   * @platform ios
+   * @platform web
+   */
+  async startPictureInPicture(): Promise<void> {
+    return await this.nativeRef.current?.startPictureInPicture();
+  }
+
+  /**
+   * Exits Picture in Picture (PiP) mode.
+   * @platform android
+   * @platform ios
+   * @platform web
+   */
+  async stopPictureInPicture(): Promise<void> {
+    return await this.nativeRef.current?.stopPictureInPicture();
+  }
+
+  render(): ReactNode {
+    const { player, ...props } = this.props;
+    const playerId = getPlayerId(player);
+
+    if (NativeTextureVideoView && this.props.surfaceType === 'textureView') {
+      return <NativeTextureVideoView {...props} player={playerId} ref={this.nativeRef} />;
+    }
+    return <NativeVideoView {...props} player={playerId} ref={this.nativeRef} />;
+  }
+}
+
+// Temporary solution to pass the shared object ID instead of the player object.
+// We can't really pass it as an object in the old architecture.
+// Technically we can in the new architecture, but it's not possible yet.
+function getPlayerId(player: number | VideoPlayer): number | null {
+  if (player instanceof NativeVideoModule.VideoPlayer) {
+    // @ts-expect-error
+    return player.__expo_shared_object_id__;
+  }
+  if (typeof player === 'number') {
+    return player;
+  }
+  return null;
+}

package/src/VideoView.types.ts

@@ -0,0 +1,165 @@
+import { ViewProps } from 'react-native';
+
+import type { VideoPlayer } from './VideoPlayer.types';
+
+/**
+ * Describes how a video should be scaled to fit in a container.
+ * - `contain`: The video maintains its aspect ratio and fits inside the container, with possible letterboxing/pillarboxing.
+ * - `cover`: The video maintains its aspect ratio and covers the entire container, potentially cropping some portions.
+ * - `fill`: The video stretches/squeezes to completely fill the container, potentially causing distortion.
+ */
+export type VideoContentFit = 'contain' | 'cover' | 'fill';
+
+/**
+ * Describes the type of the surface used to render the video.
+ * - `surfaceView`: Uses the `SurfaceView` to render the video. This value should be used in the majority of cases. Provides significantly lower power consumption, better performance, and more features.
+ * - `textureView`: Uses the `TextureView` to render the video. Should be used in cases where the SurfaceView is not supported or causes issues (for example, overlapping video views).
+ *
+ * You can learn more about surface types in the official [ExoPlayer documentation](https://developer.android.com/media/media3/ui/playerview#surfacetype).
+ * @platform android
+ */
+export type SurfaceType = 'textureView' | 'surfaceView';
+
+export interface VideoViewProps extends ViewProps {
+  /**
+   * A video player instance. Use [`useVideoPlayer()`](#usevideoplayersource-setup) hook to create one.
+   */
+  player: VideoPlayer;
+
+  /**
+   * Determines whether native controls should be displayed or not.
+   * @default true
+   */
+  nativeControls?: boolean;
+
+  /**
+   * Describes how the video should be scaled to fit in the container.
+   * Options are `'contain'`, `'cover'`, and `'fill'`.
+   * @default 'contain'
+   */
+  contentFit?: VideoContentFit;
+
+  /**
+   * Determines whether fullscreen mode is allowed or not.
+   * @default true
+   */
+  allowsFullscreen?: boolean;
+
+  /**
+   * Determines whether the timecodes should be displayed or not.
+   * @default true
+   * @platform ios
+   */
+  showsTimecodes?: boolean;
+
+  /**
+   * Determines whether the player allows the user to skip media content.
+   * @default false
+   * @platform android
+   * @platform ios
+   */
+  requiresLinearPlayback?: boolean;
+
+  /**
+   * Determines the type of the surface used to render the video.
+   * > This prop should not be changed at runtime.
+   * @default 'surfaceView'
+   * @platform android
+   */
+  surfaceType?: SurfaceType;
+
+  /**
+   * Determines the position offset of the video inside the container.
+   * @default { dx: 0, dy: 0 }
+   * @platform ios
+   */
+  contentPosition?: { dx?: number; dy?: number };
+
+  /**
+   * A callback to call after the video player enters Picture in Picture (PiP) mode.
+   * @platform android
+   * @platform ios
+   * @platform web
+   */
+  onPictureInPictureStart?: () => void;
+
+  /**
+   * A callback to call after the video player exits Picture in Picture (PiP) mode.
+   * @platform android
+   * @platform ios
+   * @platform web
+   */
+  onPictureInPictureStop?: () => void;
+
+  /**
+   * Determines whether the player allows Picture in Picture (PiP) mode.
+   * > **Note:** The `supportsPictureInPicture` property of the [config plugin](#configuration-in-app-config)
+   * > has to be configured for the PiP to work.
+   * @platform android
+   * @platform ios
+   * @platform web
+   */
+  allowsPictureInPicture?: boolean;
+
+  /**
+   * Determines whether a video should be played "inline", that is, within the element's playback area.
+   * @platform web
+   */
+  playsInline?: boolean;
+
+  /**
+   * Determines whether the player should start Picture in Picture (PiP) automatically when the app is in the background.
+   * > **Note:** Only one player can be in Picture in Picture (PiP) mode at a time.
+   *
+   * > **Note:** The `supportsPictureInPicture` property of the [config plugin](#configuration-in-app-config)
+   * > has to be configured for the PiP to work.
+   *
+   * @default false
+   * @platform android 12+
+   * @platform ios
+   */
+  startsPictureInPictureAutomatically?: boolean;
+
+  /**
+   * Specifies whether to perform video frame analysis (Live Text in videos).
+   * Check official [Apple documentation](https://developer.apple.com/documentation/avkit/avplayerviewcontroller/allowsvideoframeanalysis) for more details.
+   * @default true
+   * @platform ios 16.0+
+   */
+  allowsVideoFrameAnalysis?: boolean;
+
+  /**
+   * A callback to call after the video player enters fullscreen mode.
+   */
+  onFullscreenEnter?: () => void;
+
+  /**
+   * A callback to call after the video player exits fullscreen mode.
+   */
+  onFullscreenExit?: () => void;
+
+  /**
+   * A callback to call after the mounted `VideoPlayer` has rendered the first frame into the `VideoView`.
+   * This event can be used to hide any cover images that conceal the initial loading of the player.
+   * > **Note:** This event may also be called during playback when the current video track changes (for example when the player switches video quality).
+   */
+  onFirstFrameRender?: () => void;
+
+  /**
+   * Determines whether the player should use the default ExoPlayer shutter that covers the `VideoView` before the first video frame is rendered.
+   * Setting this property to `false` makes the Android behavior the same as iOS.
+   *
+   * @platform android
+   * @default false
+   */
+  useExoShutter?: boolean;
+
+  /**
+   * Determines the [cross origin policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) used by the underlying native view on web.
+   * If undefined, does not use CORS at all.
+   *
+   * @platform web
+   * @default undefined
+   */
+  crossOrigin?: 'anonymous' | 'use-credentials';
+}