@mux/mux-react-native-player 0.1.0

package/src/MuxVideoView.tsx

@@ -0,0 +1,412 @@
+import * as React from 'react';
+import { Dimensions, Modal, Platform, StyleSheet, View } from 'react-native';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+const IOS_LANDSCAPE_SAFE_INSET = 50;
+
+import { MuxVideoPlayer } from './MuxVideoPlayer';
+import { MuxVideoControls } from './MuxVideoControls';
+import NativeMuxVideoView from './NativeMuxVideoView';
+import {
+  lockOrientationLandscape,
+  unlockOrientation,
+} from './screenOrientation';
+import type {
+  MuxNativeViewRef,
+  MuxVideoChapter,
+  MuxVideoKeyMoment,
+  MuxVideoSource,
+  MuxVideoSummary,
+  MuxVideoViewProps,
+} from './types';
+
+export type MuxVideoViewRef = {
+  play: () => Promise<void>;
+  pause: () => Promise<void>;
+  replay: () => Promise<void>;
+  seekBy: (seconds: number) => Promise<void>;
+  seekTo: (seconds: number) => Promise<void>;
+  setMuted: (muted: boolean) => Promise<void>;
+  setVolume: (volume: number) => Promise<void>;
+  setLoop: (loop: boolean) => Promise<void>;
+  setPlaybackRate: (rate: number) => Promise<void>;
+  setCaptionTrack: (trackId: string | null) => Promise<void>;
+  release: () => Promise<void>;
+  enterFullscreen: () => void;
+  exitFullscreen: () => void;
+};
+
+export const MuxVideoView = React.forwardRef<MuxVideoViewRef, MuxVideoViewProps>(
+  (
+    {
+      player,
+      controls,
+      controlsTheme,
+      robots,
+      nativeControls = true,
+      contentFit = 'contain',
+      allowsFullscreen = true,
+      allowsPictureInPicture = false,
+      timeUpdateEventInterval = 0.5,
+      startupBufferDuration,
+      onStatusChange,
+      onPlayingChange,
+      onTimeUpdate,
+      onSourceLoad,
+      onSourceError,
+      onFullscreenChange,
+      ...viewProps
+    },
+    ref
+  ) => {
+    const nativeRef = React.useRef<MuxNativeViewRef>(null);
+    const [fullscreen, setFullscreen] = React.useState(false);
+    const [fullscreenReady, setFullscreenReady] = React.useState(false);
+    const enteredViaRotationRef = React.useRef(false);
+    const suppressRotationEntryRef = React.useRef(false);
+    const pendingExitRef = React.useRef(false);
+    const [generatedSummary, setGeneratedSummary] = React.useState<MuxVideoSummary>();
+    const [generatedChapters, setGeneratedChapters] = React.useState<MuxVideoChapter[]>();
+    const [generatedKeyMoments, setGeneratedKeyMoments] = React.useState<MuxVideoKeyMoment[]>();
+    const snapshot = React.useSyncExternalStore(
+      player._subscribe,
+      player._getSnapshot,
+      player._getSnapshot
+    );
+
+    const enterFullscreen = React.useCallback(() => {
+      player._markResumePoint();
+      enteredViaRotationRef.current = false;
+      suppressRotationEntryRef.current = false;
+      pendingExitRef.current = false;
+      const { width, height } = Dimensions.get('window');
+      setFullscreenReady(width > height);
+      setFullscreen(true);
+    }, [player]);
+    const beginExit = React.useCallback(() => {
+      player._markResumePoint();
+      enteredViaRotationRef.current = false;
+      suppressRotationEntryRef.current = true;
+      setFullscreenReady(false);
+      const { width, height } = Dimensions.get('window');
+      if (width <= height) {
+        pendingExitRef.current = false;
+        setFullscreen(false);
+        return;
+      }
+      pendingExitRef.current = true;
+      void unlockOrientation();
+      setTimeout(() => {
+        if (pendingExitRef.current) {
+          pendingExitRef.current = false;
+          setFullscreen(false);
+        }
+      }, 600);
+    }, [player]);
+    const exitFullscreen = React.useCallback(() => {
+      beginExit();
+    }, [beginExit]);
+    const toggleFullscreen = React.useCallback(() => {
+      if (fullscreen) {
+        beginExit();
+        return;
+      }
+      player._markResumePoint();
+      enteredViaRotationRef.current = false;
+      suppressRotationEntryRef.current = false;
+      pendingExitRef.current = false;
+      const { width, height } = Dimensions.get('window');
+      setFullscreenReady(width > height);
+      setFullscreen(true);
+    }, [beginExit, fullscreen, player]);
+
+    React.useEffect(() => {
+      if (!allowsFullscreen) {
+        return;
+      }
+      const subscription = Dimensions.addEventListener('change', ({ window }) => {
+        const isLandscape = window.width > window.height;
+        if (!isLandscape) {
+          suppressRotationEntryRef.current = false;
+          if (pendingExitRef.current) {
+            pendingExitRef.current = false;
+            setFullscreenReady(false);
+            setFullscreen(false);
+            return;
+          }
+        } else if (pendingExitRef.current) {
+          pendingExitRef.current = false;
+        }
+        setFullscreenReady(isLandscape);
+        setFullscreen(prev => {
+          if (isLandscape && !prev) {
+            if (suppressRotationEntryRef.current) {
+              return prev;
+            }
+            enteredViaRotationRef.current = true;
+            player._markResumePoint();
+            return true;
+          }
+          if (!isLandscape && prev && enteredViaRotationRef.current) {
+            enteredViaRotationRef.current = false;
+            player._markResumePoint();
+            return false;
+          }
+          return prev;
+        });
+      });
+      return () => subscription.remove();
+    }, [allowsFullscreen, player]);
+
+    React.useImperativeHandle(
+      ref,
+      () => ({
+        play: () => player.play(),
+        pause: () => player.pause(),
+        replay: () => player.replay(),
+        seekBy: seconds => player.seekBy(seconds),
+        seekTo: seconds => player.seekTo(seconds),
+        setMuted: muted => player.setMuted(muted),
+        setVolume: volume => player.setVolume(volume),
+        setLoop: loop => player.setLoop(loop),
+        setPlaybackRate: rate => player.setPlaybackRate(rate),
+        setCaptionTrack: trackId => player.setCaptionTrack(trackId),
+        release: () => player.release(),
+        enterFullscreen,
+        exitFullscreen,
+      }),
+      [player, enterFullscreen, exitFullscreen]
+    );
+
+    React.useEffect(() => {
+      player._attachNativeRef(nativeRef.current);
+      return () => {
+        player._attachNativeRef(null);
+      };
+    }, [player, fullscreen]);
+
+    React.useEffect(() => {
+      onFullscreenChange?.(fullscreen);
+      if (!fullscreen) {
+        return;
+      }
+      const entryViaRotation = enteredViaRotationRef.current;
+      if (!entryViaRotation) {
+        void lockOrientationLandscape();
+      }
+      return () => {
+        if (!entryViaRotation) {
+          void unlockOrientation();
+        }
+      };
+    }, [fullscreen, onFullscreenChange]);
+
+    const controlsMode = controls ?? (nativeControls ? 'native' : 'none');
+    const showCustomControls = controlsMode === 'custom';
+    const showNativeControls = controlsMode === 'native';
+    const controlsRobots = React.useMemo(
+      () =>
+        robots && robots.assetId == null && snapshot.source?.assetId
+          ? { ...robots, assetId: snapshot.source.assetId }
+          : robots,
+      [robots, snapshot.source?.assetId]
+    );
+    const robotsAssetId = controlsRobots?.assetId;
+
+    React.useEffect(() => {
+      setGeneratedSummary(undefined);
+      setGeneratedChapters(undefined);
+      setGeneratedKeyMoments(undefined);
+    }, [robotsAssetId]);
+
+    const sharedNativeProps = {
+      startupBufferDuration,
+      source: snapshot.source,
+      playWhenReady: snapshot.shouldPlay,
+      muted: snapshot.muted,
+      volume: snapshot.volume,
+      loop: snapshot.loop,
+      playbackRate: snapshot.playbackRate,
+      contentFit,
+      allowsFullscreen,
+      allowsPictureInPicture,
+      timeUpdateEventInterval,
+      onStatusChange: (event: { nativeEvent: any }) => {
+        player._handleStatusChange(event.nativeEvent);
+        onStatusChange?.(event.nativeEvent);
+      },
+      onPlayingChange: (event: { nativeEvent: any }) => {
+        onPlayingChange?.(event.nativeEvent);
+      },
+      onTimeUpdate: (event: { nativeEvent: any }) => {
+        player._handleTimeUpdate(event.nativeEvent);
+        onTimeUpdate?.(event.nativeEvent);
+      },
+      onSourceLoad: (event: { nativeEvent: any }) => {
+        player._handleSourceLoad(event.nativeEvent);
+        onSourceLoad?.(event.nativeEvent);
+      },
+      onSourceError: (event: { nativeEvent: any }) => {
+        player._handleSourceError(event.nativeEvent);
+        onSourceError?.(event.nativeEvent);
+      },
+    } as const;
+
+    if (showNativeControls) {
+      return (
+        <NativeMuxVideoView
+          {...viewProps}
+          {...sharedNativeProps}
+          ref={nativeRef}
+          nativeControls
+        />
+      );
+    }
+
+    const renderManagedBody = (
+      containerStyle: StyleProp<ViewStyle>,
+      controlsInset: { left: number; right: number } = { left: 0, right: 0 }
+    ) => (
+      <View style={containerStyle}>
+        <NativeMuxVideoView
+          {...sharedNativeProps}
+          ref={nativeRef}
+          nativeControls={false}
+          style={StyleSheet.absoluteFill}
+        />
+        {showCustomControls ? (
+          <View
+            pointerEvents="box-none"
+            style={{
+              position: 'absolute',
+              top: 0,
+              bottom: 0,
+              left: controlsInset.left,
+              right: controlsInset.right,
+            }}
+          >
+            <MuxVideoControls
+              player={player}
+              status={snapshot.status}
+              shouldPlay={snapshot.shouldPlay}
+              theme={controlsTheme}
+              robots={controlsRobots}
+              allowsFullscreen={allowsFullscreen}
+              isFullscreen={fullscreen}
+              onToggleFullscreen={allowsFullscreen ? toggleFullscreen : undefined}
+              generatedSummary={generatedSummary}
+              generatedChapters={generatedChapters}
+              generatedKeyMoments={generatedKeyMoments}
+              onGeneratedSummaryChange={setGeneratedSummary}
+              onGeneratedChaptersChange={setGeneratedChapters}
+              onGeneratedKeyMomentsChange={setGeneratedKeyMoments}
+            />
+          </View>
+        ) : null}
+      </View>
+    );
+
+    const inlineContainerStyle: StyleProp<ViewStyle> = [
+      styles.customControlsContainer,
+      viewProps.style,
+    ];
+
+    if (!fullscreen) {
+      return renderManagedBody(inlineContainerStyle);
+    }
+
+    const fullscreenControlsInset =
+      Platform.OS === 'ios' && fullscreenReady
+        ? { left: IOS_LANDSCAPE_SAFE_INSET, right: IOS_LANDSCAPE_SAFE_INSET }
+        : { left: 0, right: 0 };
+
+    return (
+      <>
+        <View
+          {...viewProps}
+          style={[inlineContainerStyle, styles.placeholderInline]}
+          pointerEvents="none"
+        />
+        <Modal
+          animationType="fade"
+          visible
+          supportedOrientations={[
+            'portrait',
+            'landscape',
+            'landscape-left',
+            'landscape-right',
+          ]}
+          statusBarTranslucent
+          presentationStyle="overFullScreen"
+          transparent
+          onRequestClose={exitFullscreen}
+        >
+          <View style={styles.fullscreenContainer}>
+            {renderManagedBody(StyleSheet.absoluteFill, fullscreenControlsInset)}
+            {!fullscreenReady ? (
+              <View
+                pointerEvents="none"
+                style={[StyleSheet.absoluteFill, styles.fullscreenCover]}
+              />
+            ) : null}
+          </View>
+        </Modal>
+      </>
+    );
+  }
+);
+
+MuxVideoView.displayName = 'MuxVideoView';
+
+export function useMuxVideoPlayer(
+  source?: MuxVideoSource,
+  setup?: (player: MuxVideoPlayer) => void
+): MuxVideoPlayer {
+  const playerRef = React.useRef<MuxVideoPlayer | null>(null);
+  const sourceKey = source == null ? undefined : JSON.stringify(source);
+
+  if (playerRef.current == null) {
+    playerRef.current = new MuxVideoPlayer(source);
+  }
+
+  React.useEffect(() => {
+    if (source != null) {
+      playerRef.current?.replace(source);
+    }
+  }, [sourceKey]);
+
+  React.useEffect(() => {
+    if (playerRef.current && setup) {
+      setup(playerRef.current);
+    }
+  }, [setup]);
+
+  React.useEffect(() => {
+    const player = playerRef.current;
+    return () => {
+      player?.release().catch(() => {
+        // React cleanup may run after the native view has already detached.
+      });
+    };
+  }, []);
+
+  return playerRef.current;
+}
+
+const styles = StyleSheet.create({
+  customControlsContainer: {
+    backgroundColor: 'transparent',
+    overflow: 'hidden',
+    position: 'relative',
+  },
+  placeholderInline: {
+    backgroundColor: 'transparent',
+  },
+  fullscreenContainer: {
+    backgroundColor: '#000',
+    flex: 1,
+  },
+  fullscreenCover: {
+    backgroundColor: '#000',
+  },
+});

package/src/NativeMuxVideoView.ts

@@ -0,0 +1,15 @@
+import {
+  requireNativeViewManager,
+  requireOptionalNativeModule,
+} from 'expo-modules-core';
+import * as React from 'react';
+
+import type { MuxNativeViewRef, NativeMuxVideoViewProps } from './types';
+
+requireOptionalNativeModule('MuxReactNativePlayer');
+
+const NativeMuxVideoView = requireNativeViewManager('MuxReactNativePlayer') as React.ComponentType<
+  NativeMuxVideoViewProps & React.RefAttributes<MuxNativeViewRef>
+>;
+
+export default NativeMuxVideoView;

package/src/index.ts

@@ -0,0 +1,32 @@
+export { createMuxVideoPlayer, MuxVideoPlayer } from './MuxVideoPlayer';
+export { MuxVideoView, useMuxVideoPlayer } from './MuxVideoView';
+export { muxResolutionSupport, normalizeMuxVideoSource } from './normalizeSource';
+export type {
+  MuxContentFit,
+  MuxVideoControls,
+  MuxVideoControlsTheme,
+  MuxCustomData,
+  MuxMaxResolution,
+  MuxMinResolution,
+  MuxNativeViewRef,
+  MuxPlaybackStatus,
+  MuxPlayerStatus,
+  MuxPlayingChangeEvent,
+  MuxRenditionOrder,
+  MuxSourceErrorEvent,
+  MuxSourceLoadEvent,
+  MuxStatusChangeEvent,
+  MuxTimeUpdateEvent,
+  MuxVideoChapter,
+  MuxVideoCaptionTrack,
+  MuxVideoClipping,
+  MuxVideoMetadata,
+  MuxVideoKeyMoment,
+  MuxVideoRobotsConfig,
+  MuxVideoRobotsContext,
+  MuxVideoSource,
+  MuxVideoSourceObject,
+  MuxVideoSummary,
+  MuxVideoViewProps,
+} from './types';
+export type { MuxVideoViewRef } from './MuxVideoView';

package/src/normalizeSource.ts

@@ -0,0 +1,101 @@
+import type {
+  MuxCustomData,
+  MuxMaxResolution,
+  MuxMinResolution,
+  MuxVideoSource,
+  NormalizedMuxVideoSource,
+} from './types';
+
+const MIN_RESOLUTION_ORDER: MuxMinResolution[] = ['480p', '540p', '720p', '1080p', '1440p', '2160p'];
+const MAX_RESOLUTION_ORDER: MuxMaxResolution[] = ['720p', '1080p', '1440p', '2160p'];
+const CUSTOM_DATA_KEYS = Array.from({ length: 10 }, (_, index) => `customData${index + 1}`);
+
+export function normalizeMuxVideoSource(source: MuxVideoSource): NormalizedMuxVideoSource {
+  const input = typeof source === 'string' ? { playbackId: source } : source;
+  const playbackId = input.playbackId?.trim();
+
+  if (!playbackId) {
+    throw new Error('Mux video source requires a non-empty playbackId.');
+  }
+
+  if (input.drmToken && !input.playbackToken) {
+    throw new Error('Mux DRM playback requires both drmToken and playbackToken.');
+  }
+
+  validateResolutionWindow(input.minResolution, input.maxResolution);
+  validateClipping(input.clipping?.assetStartTime, input.clipping?.assetEndTime);
+
+  return {
+    ...input,
+    playbackId,
+    renditionOrder: input.renditionOrder ?? 'default',
+    metadata: input.metadata
+      ? {
+          ...input.metadata,
+          customData: normalizeCustomData(input.metadata.customData),
+        }
+      : undefined,
+  };
+}
+
+function validateResolutionWindow(minResolution?: MuxMinResolution, maxResolution?: MuxMaxResolution) {
+  if (!minResolution || !maxResolution) {
+    return;
+  }
+
+  const minPixels = Number(minResolution.replace('p', ''));
+  const maxPixels = Number(maxResolution.replace('p', ''));
+  if (minPixels > maxPixels) {
+    throw new Error(`Mux video source minResolution (${minResolution}) cannot exceed maxResolution (${maxResolution}).`);
+  }
+}
+
+function validateClipping(assetStartTime?: number, assetEndTime?: number) {
+  if (assetStartTime != null && (!Number.isFinite(assetStartTime) || assetStartTime < 0)) {
+    throw new Error('Mux video source clipping.assetStartTime must be a non-negative finite number.');
+  }
+
+  if (assetEndTime != null && (!Number.isFinite(assetEndTime) || assetEndTime < 0)) {
+    throw new Error('Mux video source clipping.assetEndTime must be a non-negative finite number.');
+  }
+
+  if (assetStartTime != null && assetEndTime != null && assetStartTime >= assetEndTime) {
+    throw new Error('Mux video source clipping.assetStartTime must be less than clipping.assetEndTime.');
+  }
+}
+
+function normalizeCustomData(customData?: MuxCustomData): MuxCustomData | undefined {
+  if (!customData) {
+    return undefined;
+  }
+
+  const out: Record<string, string> = {};
+  const directKeys = Object.keys(customData).filter(key => CUSTOM_DATA_KEYS.includes(key));
+
+  for (const key of directKeys) {
+    const value = customData[key];
+    if (typeof value === 'string') {
+      out[key] = value;
+    }
+  }
+
+  const remainingValues = Object.entries(customData)
+    .filter(([key, value]) => !CUSTOM_DATA_KEYS.includes(key) && typeof value === 'string')
+    .map(([, value]) => value as string);
+
+  for (const key of CUSTOM_DATA_KEYS) {
+    if (remainingValues.length === 0) {
+      break;
+    }
+    if (out[key] == null) {
+      out[key] = remainingValues.shift() as string;
+    }
+  }
+
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+export const muxResolutionSupport = {
+  min: MIN_RESOLUTION_ORDER,
+  max: MAX_RESOLUTION_ORDER,
+} as const;

package/src/screenOrientation.ts

@@ -0,0 +1,46 @@
+import { requireOptionalNativeModule } from 'expo-modules-core';
+
+type MuxReactNativePlayerModule = {
+  lockFullscreenLandscape?: () => Promise<void>;
+  unlockFullscreenOrientation?: () => Promise<void>;
+};
+
+let cached: MuxReactNativePlayerModule | null | undefined;
+
+function loadModule(): MuxReactNativePlayerModule | null {
+  if (cached !== undefined) {
+    return cached;
+  }
+  try {
+    cached = requireOptionalNativeModule(
+      'MuxReactNativePlayer'
+    ) as MuxReactNativePlayerModule | null;
+  } catch {
+    cached = null;
+  }
+  return cached;
+}
+
+export async function lockOrientationLandscape(): Promise<void> {
+  const mod = loadModule();
+  if (!mod) {
+    return;
+  }
+  try {
+    await mod.lockFullscreenLandscape?.();
+  } catch {
+    // Locking can fail on devices that don't support orientation changes.
+  }
+}
+
+export async function unlockOrientation(): Promise<void> {
+  const mod = loadModule();
+  if (!mod) {
+    return;
+  }
+  try {
+    await mod.unlockFullscreenOrientation?.();
+  } catch {
+    // ignore
+  }
+}