react-native-alpha-video 0.0.0-stage → 1.0.0

package/react-native/src/AlphaVideoView.tsx

@@ -0,0 +1,329 @@
+/**
+ * The player view, split out from the package barrel.
+ *
+ * Separate from `index.tsx` so that anything built ON the player can import it without the barrel
+ * importing that code back. A cycle through the entry point happens to work while every reference
+ * is inside a render, which makes it a trap rather than a design.
+ */
+
+import React, { useRef, forwardRef, useImperativeHandle, useMemo, useEffect } from 'react';
+import {
+  Platform,
+  ViewProps,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
+import NativeAlphaVideoView, { Commands, type Decoder } from './AlphaVideoViewNativeComponent';
+import { WebPlayer } from './WebPlayer';
+import type { ByteSource } from 'alpha-video-web';
+
+export type { Decoder, ByteSource };
+
+/**
+ * The web engine (default `'auto'`): `'browser'` (`<video>`), `'webcodecs'`, `'webcodecs-hw'`,
+ * `'webcodecs-sw'` or `'software'` (WebAssembly). `'auto'` tries them in that order and uses the
+ * first that shows the alpha; a forced engine never falls back.
+ */
+export type WebDecoder = 'auto' | 'browser' | 'webcodecs' | 'webcodecs-hw' | 'webcodecs-sw' | 'software';
+
+/**
+ * Source types for WebM video
+ */
+export interface AlphaVideoSource {
+  /**
+   * https:// (read by range as it plays), file://, an absolute path, asset://relative/path
+   * (app bundle / APK assets; the site root on web), content:// (Android), or
+   * Image.resolveAssetSource(require(...)).uri. With `dataSource`, any URI that source reads.
+   */
+  uri: string;
+  /** Names the stored copy, for URLs that change while the file doesn't (presigned URLs); same as the `cacheKey` prop */
+  cacheKey?: string;
+  /** Sent with every request for the URL, e.g. Authorization; given to a `dataSource` too */
+  headers?: Record<string, string>;
+  /**
+   * iOS and Android: read the file through the data source the app registered under this name
+   * (`AlphaVideoDataSources.register` on Android, `AlphaVideoDataSources.register(_:name:)`
+   * on iOS) instead of the built-in fetcher.
+   */
+  dataSource?: string;
+}
+
+/**
+ * Web only: the file itself (a Blob or File), or a byte source that reads it by offset
+ * (`{ size, read(offset, length, signal) }`, the app's own fetcher or decryption). Keep the same
+ * object between renders: a new one loads again. On iOS and Android use `source.dataSource`.
+ */
+export type AlphaVideoWebSource = Blob | ByteSource;
+
+/** True for `{ uri, ... }`, false for a web-only Blob or byte source. */
+export function isUriSource(source: AlphaVideoSource | AlphaVideoWebSource | null | undefined): source is AlphaVideoSource {
+  return source != null && typeof (source as AlphaVideoSource).uri === 'string';
+}
+
+/**
+ * Where a URL's bytes are kept between plays, read back by range: `'disk'` (the cache folder;
+ * OPFS, else IndexedDB, on the web), `'memory'` (for the app's lifetime) or `'none'`. `'auto'`,
+ * the default, is `'disk'` for URLs and `'none'` for a `dataSource` and local files.
+ */
+export type AlphaVideoStorage = 'auto' | 'disk' | 'memory' | 'none';
+
+/**
+ * Props for the AlphaVideoView component
+ */
+/**
+ * Playback mode for the WebM player.
+ */
+export type PlaybackMode = 'preload' | 'stream' | 'streamAndPreload';
+
+export interface AlphaVideoLoadEvent {
+  totalFrames: number;
+  width: number;
+  height: number;
+  /**
+   * The engine and decoders playing the file: `'software (libvpx)'`, `'software (dav1d)'` (AV1),
+   * `'mediacodec-hw (c2.qti.vp9.decoder)'`, `'mediacodec-sw (...)'`, `'mediacodec (hardware, software)'`
+   * for one of each. On the web: `'browser'`, `'webcodecs (vp09.00.41.08)'` (with the alpha track's
+   * codec when it differs), `'software (vp9)'`, `'software (vp9, 4+2 threads)'` or `'software (dav1d)'`.
+   */
+  decoder: string;
+}
+
+export interface AlphaVideoViewProps extends ViewProps {
+  /** Video source URL or path; on the web also a Blob or byte source ({@link AlphaVideoWebSource}) */
+  source: AlphaVideoSource | AlphaVideoWebSource;
+  /** Auto-play video when loaded (default: true) */
+  autoPlay?: boolean;
+  /** Loop video playback (default: true) */
+  loop?: boolean;
+  /** Pause video playback (default: false) */
+  paused?: boolean;
+  /** Playback speed multiplier (default: 1.0) */
+  playbackSpeed?: number;
+  /**
+   * Names the stored copy instead of the URL, for URLs that change while the file doesn't
+   * (presigned URLs). `source.cacheKey` wins over it.
+   */
+  cacheKey?: string;
+
+  /** See {@link AlphaVideoStorage}. */
+  storage?: AlphaVideoStorage;
+
+  /**
+   * Cap on the bytes this player stores across every clip, evicting the least recently played
+   * (default 512 MB).
+   */
+  maxStorageBytes?: number;
+  
+  /**
+   * Playback mode for the player.
+   * - 'stream' (default): Decode frames on-demand with a sliding window cache.
+   * - 'preload': Decode all frames upfront before playback starts.
+   * - 'streamAndPreload': Start playing immediately while decoding in background.
+   *
+   * Applies to the software decoders only: a file MediaCodec plays on Android (see `decoder`) decodes as it is read.
+   */
+  mode?: PlaybackMode;
+
+  /**
+   * Android: the decoder for files with colour and alpha as separate VP8/VP9/AV1 bitstreams
+   * (default `'auto'`; see {@link Decoder}). `onLoad` reports the one used. iOS always uses
+   * the C++ core; the web has `webDecoder`.
+   */
+  decoder?: Decoder;
+
+  /** Web: the engine (default `'auto'`; see {@link WebDecoder}). `onLoad` reports the one used. */
+  webDecoder?: WebDecoder;
+  
+  /**
+   * @deprecated Use `mode` instead.
+   * Enable streaming mode for low RAM usage.
+   * When true: decode on-demand with sliding window cache (good for long videos like YouTube)
+   * When false: preload all frames to RAM (good for short loops like glow effects)
+   * When omitted, `mode` (default 'stream') applies.
+   */
+  stream?: boolean;
+  
+  /**
+   * Number of frames decoded ahead of the shown one when streaming. Stream mode keeps only
+   * these, so this is also its memory: more absorbs slow decodes, fewer uses less memory.
+   * Default: 8 frames (about 0.27 seconds at 30fps)
+   * Only used when mode='stream'
+   */
+  streamPrefetchAhead?: number;
+  
+  /**
+   * Enable global decode queue for non-stream mode.
+   * When true (default): decoding is serialized across all players, preventing CPU saturation
+   * When false: each player decodes independently (can freeze with many)
+   * Has no effect when mode='stream'.
+   */
+  useDecodeQueue?: boolean;
+  
+  /**
+   * Enable verbose per-frame logging for debugging.
+   * When true: logs every frame queue, release, and render event.
+   * When false (default): only logs lifecycle events and periodic performance stats.
+   */
+  verbose?: boolean;
+  
+  /** Container style */
+  style?: StyleProp<ViewStyle>;
+  /** Callback when video loads */
+  onLoad?: (event: AlphaVideoLoadEvent) => void;
+  /**
+   * Callback when error occurs. On the web, `code` tells the errors apart: `'LOAD_FAILED'`,
+   * `'UNSUPPORTED_FILE'`, `'NO_ALPHA_PATH'`, `'DECODER_UNSUPPORTED'`, `'DECODE_FAILED'`, `'WEBGL_UNSUPPORTED'`
+   * or `'NEEDS_SERVICE_WORKER'`.
+   * On iOS and Android, `'NO_DECODER'` is a file needing a codec left out of the build (see the
+   * app's `package.json` `"react-native-alpha-video": { "codecs": [...] }`); other errors have none.
+   */
+  onError?: (event: { error: string; code?: string }) => void;
+  /** Callback when video ends */
+  onEnd?: (event: {}) => void;
+}
+
+/**
+ * Methods exposed by the AlphaVideoView ref
+ */
+export interface AlphaVideoViewRef {
+  play: () => void;
+  pause: () => void;
+  stop: () => void;
+  /** Shows that frame (clamped to the clip) and keeps playing or stays paused. */
+  seekToFrame: (frame: number) => void;
+  /** Seeks to the frame showing at that time, in seconds. */
+  seekToTime: (seconds: number) => void;
+}
+
+// Native component for iOS and Android, from the codegen spec: a Fabric component on the new
+// architecture, a view manager on the old one.
+const NativeAlphaVideoViewOrNull = Platform.OS !== 'web' ? NativeAlphaVideoView : null;
+
+/** `mode` wins over the deprecated `stream`. */
+function resolveMode(mode: PlaybackMode | undefined, stream: boolean | undefined): PlaybackMode | undefined {
+  if (mode) return mode;
+  if (stream == null) return undefined;
+  return stream ? 'stream' : 'preload';
+}
+
+/**
+ * Native implementation for iOS and Android
+ */
+const NativePlayer = forwardRef<AlphaVideoViewRef, AlphaVideoViewProps>(
+  (props, ref) => {
+    const nativeRef = useRef<React.ElementRef<typeof NativeAlphaVideoView>>(null);
+
+    const withView = (command: (view: React.ElementRef<typeof NativeAlphaVideoView>) => void) => {
+      if (nativeRef.current) command(nativeRef.current);
+    };
+
+    useImperativeHandle(ref, () => ({
+      play: () => withView(view => Commands.play(view)),
+      pause: () => withView(view => Commands.pause(view)),
+      stop: () => withView(view => Commands.stop(view)),
+      seekToFrame: (frame: number) => withView(view => Commands.seekToFrame(view, frame)),
+      seekToTime: (seconds: number) => withView(view => Commands.seekToTime(view, seconds)),
+    }));
+
+    const uriSource = isUriSource(props.source) ? props.source : undefined;
+    const { uri, headers, dataSource } = uriSource ?? {};
+    const headersKey = headers ? JSON.stringify(headers) : '';
+    // Rebuilt only when a value changes, so a new source object each render doesn't reload
+    const nativeSource = useMemo(
+      () => ({
+        uri,
+        headers: headers ? ([] as string[]).concat(...Object.entries(headers)) : undefined,
+        dataSource,
+      }),
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [uri, headersKey, dataSource],
+    );
+
+    const webOnlySource = props.source != null && !uriSource;
+    useEffect(() => {
+      if (webOnlySource) {
+        props.onError?.({ error: 'A Blob or byte source plays only on the web; on iOS and Android, use source.dataSource' });
+      }
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [webOnlySource, props.source]);
+
+    if (!NativeAlphaVideoViewOrNull) {
+      return null;
+    }
+
+    // Wrap native event handlers to extract nativeEvent data
+    const handleNativeLoad = props.onLoad 
+      ? (event: { nativeEvent: AlphaVideoLoadEvent }) => {
+          props.onLoad?.(event.nativeEvent);
+        }
+      : undefined;
+
+    const handleNativeError = props.onError
+      ? (event: { nativeEvent: { error: string; code?: string } }) => {
+          // The new architecture's event struct sends an absent code as ''
+          const { error, code } = event.nativeEvent;
+          props.onError?.(code ? { error, code } : { error });
+        }
+      : undefined;
+
+    const handleNativeEnd = props.onEnd
+      ? (event: { nativeEvent: {} }) => {
+          props.onEnd?.(event.nativeEvent);
+        }
+      : undefined;
+
+    return (
+      <NativeAlphaVideoViewOrNull
+        ref={nativeRef}
+        source={nativeSource}
+        autoPlay={props.autoPlay}
+        loop={props.loop}
+        paused={props.paused}
+        playbackSpeed={props.playbackSpeed}
+        cacheKey={uriSource?.cacheKey || props.cacheKey}
+        storage={props.storage}
+        maxStorageBytes={props.maxStorageBytes}
+        mode={resolveMode(props.mode, props.stream)}
+        decoder={props.decoder}
+        streamPrefetchAhead={props.streamPrefetchAhead}
+        useDecodeQueue={props.useDecodeQueue}
+        verbose={props.verbose}
+        style={props.style}
+        onLoad={handleNativeLoad}
+        onError={handleNativeError}
+        onEnd={handleNativeEnd}
+      />
+    );
+  }
+);
+
+NativePlayer.displayName = 'NativePlayer';
+
+/**
+ * AlphaVideoView - Cross-platform WebM VP8/VP9/AV1 video player with alpha transparency support
+ * 
+ * Uses native C++ implementation with Metal (iOS) and OpenGL ES (Android) for optimal performance.
+ * On the web, alpha-video-web: `<video>` where the browser keeps the alpha, otherwise WebCodecs or
+ * WebAssembly decoding drawn in WebGL2.
+ * 
+ * @example
+ * ```tsx
+ * <AlphaVideoView
+ *   source={{ uri: 'https://example.com/video.webm' }}
+ *   autoPlay={true}
+ *   loop={true}
+ *   style={{ width: 300, height: 300 }}
+ * />
+ * ```
+ */
+export const AlphaVideoView = forwardRef<AlphaVideoViewRef, AlphaVideoViewProps>(
+  (props, ref) => {
+    if (Platform.OS === 'web') {
+      return <WebPlayer ref={ref} {...props} />;
+    }
+
+    return <NativePlayer ref={ref} {...props} />;
+  }
+);
+
+AlphaVideoView.displayName = 'AlphaVideoView';

package/react-native/src/AlphaVideoViewNativeComponent.ts

@@ -0,0 +1,132 @@
+import type * as React from 'react';
+import type { HostComponent, ViewProps } from 'react-native';
+import type {
+  DirectEventHandler,
+  Double,
+  Int32,
+  WithDefault,
+} from 'react-native/Libraries/Types/CodegenTypes';
+import codegenNativeCommands from 'react-native/Libraries/Utilities/codegenNativeCommands';
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+
+/**
+ * Playback mode for the WebM player.
+ * 
+ * - `'stream'` (default): Decode frames on-demand with a sliding window cache.
+ *   Best for long videos or memory-constrained devices. Frames are evicted
+ *   from cache, so looping requires re-decoding.
+ * 
+ * - `'preload'`: Decode all frames upfront before playback starts.
+ *   Best for short loops. Zero CPU during playback, instant looping.
+ * 
+ * - `'streamAndPreload'`: Start playing immediately while decoding in background.
+ *   After first pass completes, all frames are cached for instant looping.
+ *   Best of both worlds: fast start + smooth loops.
+ */
+export type PlaybackMode = 'preload' | 'stream' | 'streamAndPreload';
+
+/**
+ * Decoder for files with colour and alpha as separate VP8/VP9/AV1 bitstreams (two tracks, or a
+ * standard alpha WebM's BlockAdditional). Android only; iOS always uses the C++ core and web the browser.
+ *
+ * - `'auto'` (default): MediaCodec hardware decoders that list every track's profile, else
+ *   MediaCodec's software decoders, else the C++ core.
+ * - `'mediacodec'`: per track, a hardware decoder if one lists the profile and has an instance
+ *   free, else a software one.
+ * - `'mediacodec-hw'` / `'mediacodec-sw'`: hardware / software decoders only, for both tracks.
+ * - `'software'`: the C++ core, with the codecs built in (libvpx for VP8 and 8-bit VP9, dav1d for 8- to
+ *   12-bit AV1).
+ *
+ * A forced engine never falls back: a file it can't play calls `onError`. One that needs a codec
+ * left out of the build reports the code `'NO_DECODER'`.
+ */
+export type Decoder = 'auto' | 'mediacodec' | 'mediacodec-hw' | 'mediacodec-sw' | 'software';
+
+type LoadEvent = Readonly<{
+  totalFrames: Int32;
+  width: Int32;
+  height: Int32;
+  /** The engine and decoders playing the file, e.g. `'mediacodec-hw (c2.qti.vp9.decoder)'`. */
+  decoder: string;
+}>;
+
+type ErrorEvent = Readonly<{
+  error: string;
+  /** `'NO_DECODER'` when the file needs a software decoder that isn't built in */
+  code?: string;
+}>;
+
+/** Android only: every frame is decoded (preload and streamAndPreload modes). */
+type PreloadCompleteEvent = Readonly<{
+  totalFrames: Int32;
+  timeMs: Double;
+}>;
+
+export interface NativeProps extends ViewProps {
+  source?: Readonly<{
+    uri?: string;
+    /** Request headers as name, value, name, value... (codegen has no string maps) */
+    headers?: ReadonlyArray<string>;
+    /** A data source registered in native code under this name */
+    dataSource?: string;
+  }>;
+  autoPlay?: WithDefault<boolean, true>;
+  loop?: WithDefault<boolean, true>;
+  paused?: WithDefault<boolean, false>;
+  playbackSpeed?: WithDefault<Double, 1.0>;
+  /** What the store keeps the source under, instead of its URL */
+  cacheKey?: string;
+  /** Where a URL's or data source's bytes are kept between plays */
+  storage?: WithDefault<'auto' | 'disk' | 'memory' | 'none', 'auto'>;
+  /** The store's cap in bytes; 0 for the default (512 MB) */
+  maxStorageBytes?: WithDefault<Double, 0>;
+
+  /** See {@link PlaybackMode}. */
+  mode?: WithDefault<'preload' | 'stream' | 'streamAndPreload', 'stream'>;
+
+  /** See {@link Decoder}. */
+  decoder?: WithDefault<'auto' | 'mediacodec' | 'mediacodec-hw' | 'mediacodec-sw' | 'software', 'auto'>;
+
+  /**
+   * Number of frames decoded ahead of the shown one when streaming; stream mode keeps only these.
+   * Default: 8 frames (about 0.27 seconds at 30fps)
+   * Only used when mode='stream'
+   */
+  streamPrefetchAhead?: WithDefault<Int32, 8>;
+
+  /**
+   * Enable global decode queue for non-stream mode.
+   * When true (default): decoding is serialized across all players, preventing CPU saturation
+   * When false: each player decodes independently (can freeze with many)
+   * Has no effect when mode='stream'.
+   */
+  useDecodeQueue?: WithDefault<boolean, true>;
+
+  /**
+   * Enable verbose per-frame logging for debugging.
+   * When true: logs every frame queue, release, and render event.
+   * When false (default): only logs lifecycle events and periodic performance stats.
+   */
+  verbose?: WithDefault<boolean, false>;
+
+  onLoad?: DirectEventHandler<LoadEvent>;
+  onError?: DirectEventHandler<ErrorEvent>;
+  onEnd?: DirectEventHandler<Readonly<{}>>;
+  onPreloadComplete?: DirectEventHandler<PreloadCompleteEvent>;
+}
+
+type NativeComponentType = HostComponent<NativeProps>;
+
+interface NativeCommands {
+  play: (viewRef: React.ElementRef<NativeComponentType>) => void;
+  pause: (viewRef: React.ElementRef<NativeComponentType>) => void;
+  stop: (viewRef: React.ElementRef<NativeComponentType>) => void;
+  seekToFrame: (viewRef: React.ElementRef<NativeComponentType>, frame: Int32) => void;
+  seekToTime: (viewRef: React.ElementRef<NativeComponentType>, seconds: Double) => void;
+}
+
+export const Commands: NativeCommands = codegenNativeCommands<NativeCommands>({
+  supportedCommands: ['play', 'pause', 'stop', 'seekToFrame', 'seekToTime'],
+});
+
+export default codegenNativeComponent<NativeProps>('RNAlphaVideoView') as NativeComponentType;

package/react-native/src/AlphaVideoViewNativeComponent.web.ts

@@ -0,0 +1,5 @@
+// The web player is a <video> element. This stub keeps the native spec's imports out of web bundles.
+const noCommands = {};
+// React Native's Babel codegen plugin rejects `export const Commands` unless it is codegenNativeCommands.
+export { noCommands as Commands };
+export default null;

package/react-native/src/NativeAlphaVideoModule.ts

@@ -0,0 +1,22 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/** The decoder utilities. Android only: iOS has no native module, so `get` returns null there. */
+export interface Spec extends TurboModule {
+  getDecoderInfo(): Promise<string>;
+  getMaxDecoderInstances(mimeType: string): Promise<number>;
+  getActiveDecoderCount(): Promise<number>;
+  getDecoderStatus(): Promise<{
+    maxVp9Instances: number;
+    maxAv1Instances: number;
+    vp9HardwareAvailable: boolean;
+    av1HardwareAvailable: boolean;
+    activeDecoders: number;
+    availableVp9Slots: number;
+    maxDualStreamPlayers: number;
+    canCreateMore: boolean;
+    softwareDecoders: string[];
+  }>;
+}
+
+export default TurboModuleRegistry.get<Spec>('RNAlphaVideo');

package/react-native/src/NativeAlphaVideoModule.web.ts

@@ -0,0 +1,2 @@
+// No native module on the web.
+export default null;

package/react-native/src/WebPlayer.tsx

@@ -0,0 +1,7 @@
+// iOS and Android bundles get this instead of WebPlayer.web.tsx, so they never include alpha-video-web.
+import { forwardRef } from 'react';
+import type { AlphaVideoViewProps, AlphaVideoViewRef } from './AlphaVideoView';
+
+export const WebPlayer = forwardRef<AlphaVideoViewRef, AlphaVideoViewProps>(() => null);
+
+WebPlayer.displayName = 'WebPlayer';

package/react-native/src/WebPlayer.web.tsx

@@ -0,0 +1,60 @@
+/**
+ * The web player: alpha-video-web, which shows the alpha in every browser. It plays in `<video>`
+ * where the browser keeps WebM alpha, otherwise through WebCodecs or WebAssembly decoding drawn
+ * in WebGL2, loading those engines only when a file needs them.
+ */
+
+import React, { forwardRef } from 'react';
+import { View, StyleSheet } from 'react-native';
+import { AlphaVideo } from 'alpha-video-web/react';
+import { isUriSource, type AlphaVideoViewProps, type AlphaVideoViewRef } from './AlphaVideoView';
+
+/** asset://path names the app's bundled media; on the web it is served from the site root. */
+function toWebUrl(uri: string): string {
+  return uri.startsWith('asset://') ? '/' + uri.slice('asset://'.length).replace(/^\/+/, '') : uri;
+}
+
+export const WebPlayer = forwardRef<AlphaVideoViewRef, AlphaVideoViewProps>((props, ref) => {
+  const { source, autoPlay = true, loop = true, paused = false, playbackSpeed = 1, webDecoder = 'auto', cacheKey } = props;
+  const { storage, maxStorageBytes } = props;
+  const { style, onLoad, onError, onEnd } = props;
+  // Streamed by range from http(s) URLs and kept in the browser's storage (OPFS, else IndexedDB)
+  // by the canvas engines; <video> uses the HTTP cache. A Blob or byte source plays as it is.
+  const uriSource = isUriSource(source) ? source : undefined;
+  const src = isUriSource(source) ? (source.uri ? toWebUrl(source.uri) : undefined) : source;
+
+  return (
+    <View style={[styles.container, style]}>
+      {src ? (
+        <AlphaVideo
+          ref={ref}
+          src={src}
+          autoPlay={autoPlay}
+          loop={loop}
+          paused={paused}
+          playbackSpeed={playbackSpeed}
+          decoder={webDecoder}
+          headers={uriSource?.headers}
+          cacheKey={uriSource?.cacheKey || cacheKey}
+          storage={storage === 'disk' ? 'auto' : storage}
+          maxStorageBytes={maxStorageBytes}
+          style={fill}
+          onLoad={({ totalFrames, width, height, decoder }) => onLoad?.({ totalFrames, width, height, decoder })}
+          onError={(error) => onError?.({ error: error.message, code: error.code })}
+          onEnd={() => onEnd?.({})}
+        />
+      ) : null}
+    </View>
+  );
+});
+
+WebPlayer.displayName = 'WebPlayer';
+
+const styles = StyleSheet.create({
+  container: {
+    overflow: 'hidden',
+  },
+});
+
+// A DOM style: AlphaVideo renders a <div>
+const fill: React.CSSProperties = { width: '100%', height: '100%' };