@bendyline/squisq-video-react 2.0.2 → 2.2.0

package/src/mainThreadEncoder.ts

@@ -1,158 +0,0 @@
-/**
- * Main-thread WebCodecs encoder.
- *
- * Encodes video frames to MP4 using the WebCodecs API and mp4-muxer,
- * running directly on the main thread. This is simpler and avoids
- * worker module-resolution issues with bundlers. Since frame capture
- * via html2canvas (~100-200ms per frame) is the bottleneck — not
- * encoding (~1ms per frame with hardware-accelerated WebCodecs) —
- * worker offloading provides minimal benefit.
- *
- * Requirements: Chrome 94+ / Edge 94+ (WebCodecs support).
- */
-
-import { bitrateForQuality, validateVideoExportOptions } from '@bendyline/squisq-video';
-
-import { createMp4Muxer, type Mp4MuxerHandle } from './mp4Mux.js';
-
-export interface EncoderConfig {
-  width: number;
-  height: number;
-  fps: number;
-  quality: 'draft' | 'normal' | 'high';
-  /**
-   * When present, the underlying muxer is configured with an AAC audio track
-   * and {@link MainThreadEncoder.addAudioChunk} becomes usable. Absent → the
-   * encoder produces a video-only MP4 exactly as before.
-   */
-  audio?: {
-    numberOfChannels: number;
-    sampleRate: number;
-  };
-}
-
-export interface MainThreadEncoder {
-  /** Encode a single frame. The bitmap is closed after encoding. */
-  encodeFrame(bitmap: ImageBitmap, frameIndex: number): Promise<void>;
-  /**
-   * Hand an encoded audio chunk (from a WebCodecs `AudioEncoder`) to the muxer.
-   * Only valid when the encoder was created with an `audio` config; otherwise a
-   * no-op. Must be called before {@link finalize}.
-   */
-  addAudioChunk?(chunk: EncodedAudioChunk, meta?: EncodedAudioChunkMetadata): void;
-  /** Flush pending frames and finalize the MP4. Returns the MP4 ArrayBuffer. */
-  finalize(): Promise<ArrayBuffer>;
-  /** Close the encoder without producing output (e.g., on cancel). */
-  close(): void;
-}
-
-/**
- * Check whether the browser supports WebCodecs video encoding.
- */
-export function supportsWebCodecs(): boolean {
-  return typeof VideoEncoder !== 'undefined' && typeof VideoFrame !== 'undefined';
-}
-
-/**
- * Probe whether the WebCodecs encoder actually supports the H.264 profile
- * we use. The `VideoEncoder` global can exist while the specific codec is
- * unavailable — this is the case on Linux Chromium, which ships without
- * the proprietary H.264 encoder.
- */
-export async function supportsWebCodecsH264(config: EncoderConfig): Promise<boolean> {
-  if (!supportsWebCodecs()) return false;
-  try {
-    const support = await VideoEncoder.isConfigSupported({
-      codec: 'avc1.640028',
-      width: config.width,
-      height: config.height,
-      bitrate: bitrateForQuality(config.quality, config.width, config.height),
-      framerate: config.fps,
-    });
-    return support.supported === true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Create a main-thread WebCodecs encoder.
- *
- * Throws if WebCodecs is not available.
- */
-export function createEncoder(config: EncoderConfig): MainThreadEncoder {
-  validateVideoExportOptions(config);
-  if (!supportsWebCodecs()) {
-    throw new Error(
-      'WebCodecs is not available in this browser. ' +
-        'Video export requires Chrome 94+, Edge 94+, or another Chromium-based browser.',
-    );
-  }
-
-  const muxer: Mp4MuxerHandle = createMp4Muxer({
-    width: config.width,
-    height: config.height,
-    fps: config.fps,
-    ...(config.audio ? { audio: config.audio } : {}),
-  });
-
-  let closed = false;
-  const frameDuration = 1_000_000 / config.fps; // microseconds per frame
-
-  const encoder = new VideoEncoder({
-    output(chunk, meta) {
-      if (closed) return;
-      muxer.addVideoChunk(chunk, meta ?? undefined);
-    },
-    error(err) {
-      console.error('WebCodecs encoder error:', err.message);
-    },
-  });
-
-  encoder.configure({
-    // Deliberate profile split from the fallback worker (avc1.42001f, Baseline):
-    // this primary WebCodecs path targets H.264 High@4.0 for better quality up
-    // to 1080p; the wasm-fallback worker uses Baseline for max decoder compat.
-    codec: 'avc1.640028', // H.264 High profile, level 4.0 (supports up to 1080p)
-    width: config.width,
-    height: config.height,
-    bitrate: bitrateForQuality(config.quality, config.width, config.height),
-    framerate: config.fps,
-  });
-
-  return {
-    async encodeFrame(bitmap: ImageBitmap, frameIndex: number): Promise<void> {
-      if (closed) {
-        bitmap.close();
-        throw new Error('Encoder already closed');
-      }
-      const timestamp = Math.round(frameIndex * frameDuration);
-      const frame = new VideoFrame(bitmap, { timestamp });
-      const keyFrame = frameIndex % 30 === 0;
-      encoder.encode(frame, { keyFrame });
-      frame.close();
-      bitmap.close();
-    },
-
-    addAudioChunk(chunk: EncodedAudioChunk, meta?: EncodedAudioChunkMetadata) {
-      if (closed || !muxer.hasAudioTrack) return;
-      muxer.addAudioChunk(chunk, meta);
-    },
-
-    async finalize(): Promise<ArrayBuffer> {
-      if (closed) throw new Error('Encoder already closed');
-      await encoder.flush();
-      encoder.close();
-      closed = true;
-      return muxer.finalize();
-    },
-
-    close() {
-      if (closed) return;
-      closed = true;
-      if (encoder.state !== 'closed') {
-        encoder.close();
-      }
-    },
-  };
-}

package/src/mp4Mux.ts

@@ -1,123 +0,0 @@
-/**
- * mp4Mux — Thin wrapper around mp4-muxer for WebCodecs encoding.
- *
- * Creates a Muxer instance configured for H.264 video (and, optionally, an
- * AAC audio track), accumulates encoded chunks, and produces a final MP4
- * ArrayBuffer. When no `audio` option is supplied the muxer configuration is
- * byte-identical to the video-only path.
- */
-
-import { Muxer, ArrayBufferTarget } from 'mp4-muxer';
-
-export interface Mp4MuxerOptions {
-  width: number;
-  height: number;
-  fps: number;
-  /**
-   * When present, declares an AAC audio track alongside the video track.
-   * Feed encoded audio via {@link Mp4MuxerHandle.addAudioChunk} (from a
-   * WebCodecs `AudioEncoder`) or {@link Mp4MuxerHandle.addAudioChunkRaw}.
-   */
-  audio?: {
-    numberOfChannels: number;
-    sampleRate: number;
-  };
-}
-
-export interface Mp4MuxerHandle {
-  /** Add an encoded video chunk to the muxer. */
-  addVideoChunk(chunk: EncodedVideoChunk, meta?: EncodedVideoChunkMetadata): void;
-  /**
-   * Add a raw video sample (bytes + timing) without an `EncodedVideoChunk`.
-   * Useful where no `VideoEncoder` instance is available (e.g. Node tests).
-   */
-  addVideoChunkRaw(
-    data: Uint8Array,
-    type: 'key' | 'delta',
-    timestampMicros: number,
-    durationMicros: number,
-    meta?: EncodedVideoChunkMetadata,
-  ): void;
-  /** Add an encoded audio chunk (from a WebCodecs `AudioEncoder`). */
-  addAudioChunk(chunk: EncodedAudioChunk, meta?: EncodedAudioChunkMetadata): void;
-  /**
-   * Add a raw audio sample (bytes + timing) without an `EncodedAudioChunk`.
-   * Useful where no `AudioEncoder` instance is available (e.g. Node tests).
-   */
-  addAudioChunkRaw(
-    data: Uint8Array,
-    type: 'key' | 'delta',
-    timestampMicros: number,
-    durationMicros: number,
-    meta?: EncodedAudioChunkMetadata,
-  ): void;
-  /** Whether this muxer was created with an audio track. */
-  readonly hasAudioTrack: boolean;
-  /** Finalize and return the MP4 as an ArrayBuffer. */
-  finalize(): ArrayBuffer;
-}
-
-/**
- * Create an MP4 muxer configured for H.264 video, plus an optional AAC track.
- */
-export function createMp4Muxer(options: Mp4MuxerOptions): Mp4MuxerHandle {
-  const target = new ArrayBufferTarget();
-
-  const muxer = new Muxer({
-    target,
-    video: {
-      codec: 'avc',
-      width: options.width,
-      height: options.height,
-    },
-    // Only declare the audio track when requested so the video-only
-    // configuration stays byte-identical to the historical output.
-    ...(options.audio
-      ? {
-          audio: {
-            codec: 'aac' as const,
-            numberOfChannels: options.audio.numberOfChannels,
-            sampleRate: options.audio.sampleRate,
-          },
-        }
-      : {}),
-    fastStart: 'in-memory',
-  });
-
-  return {
-    hasAudioTrack: options.audio !== undefined,
-
-    addVideoChunk(chunk: EncodedVideoChunk, meta?: EncodedVideoChunkMetadata) {
-      muxer.addVideoChunk(chunk, meta);
-    },
-
-    addVideoChunkRaw(
-      data: Uint8Array,
-      type: 'key' | 'delta',
-      timestampMicros: number,
-      durationMicros: number,
-      meta?: EncodedVideoChunkMetadata,
-    ) {
-      muxer.addVideoChunkRaw(data, type, timestampMicros, durationMicros, meta);
-    },
-
-    addAudioChunk(chunk: EncodedAudioChunk, meta?: EncodedAudioChunkMetadata) {
-      muxer.addAudioChunk(chunk, meta);
-    },
-
-    addAudioChunkRaw(
-      data: Uint8Array,
-      type: 'key' | 'delta',
-      timestampMicros: number,
-      durationMicros: number,
-      meta?: EncodedAudioChunkMetadata,
-    ) {
-      muxer.addAudioChunkRaw(data, type, timestampMicros, durationMicros, meta);
-    },
-
-    finalize(): ArrayBuffer {
-      muxer.finalize();
-      return target.buffer;
-    },
-  };
-}

package/src/workerEncoder.ts

@@ -1,175 +0,0 @@
-/**
- * Worker-backed video encoder.
- *
- * Spawns `workers/encode.worker.ts` and exposes the same shape as
- * `MainThreadEncoder` so `useVideoExport` can treat both backends
- * uniformly. Used as a fallback when WebCodecs H.264 isn't supported
- * (typical on Linux Chromium): the worker auto-selects its ffmpeg.wasm
- * path in that case.
- */
-
-import type { MainThreadEncoder, EncoderConfig } from './mainThreadEncoder.js';
-import type { MainToWorkerMessage, WorkerToMainMessage } from './workers/workerTypes.js';
-import type { FfmpegWasmLoadConfig } from '@bendyline/squisq-video';
-import { validateVideoExportOptions } from '@bendyline/squisq-video';
-
-/** Resolves once the worker has reported which backend it picked. */
-export interface WorkerEncoder extends MainThreadEncoder {
-  /** Backend the worker selected ('webcodecs' or 'ffmpeg-wasm'). */
-  readonly ready: Promise<'webcodecs' | 'ffmpeg-wasm'>;
-}
-
-export function createWorkerEncoder(
-  config: EncoderConfig & { ffmpegWasm?: FfmpegWasmLoadConfig },
-): WorkerEncoder {
-  validateVideoExportOptions(config);
-
-  const worker = new Worker(new URL('./workers/encode.worker.js', import.meta.url), {
-    type: 'module',
-  });
-
-  let state: 'open' | 'finalizing' | 'closed' = 'open';
-  let fatalError: Error | null = null;
-  let finalizeResolve: ((buffer: ArrayBuffer) => void) | null = null;
-  let finalizeReject: ((err: Error) => void) | null = null;
-  let readyResolve: ((backend: 'webcodecs' | 'ffmpeg-wasm') => void) | null = null;
-  let readyReject: ((err: Error) => void) | null = null;
-  let readySettled = false;
-  const frameWaiters = new Map<
-    number,
-    { promise: Promise<void>; resolve: () => void; reject: (err: Error) => void }
-  >();
-
-  const ready = new Promise<'webcodecs' | 'ffmpeg-wasm'>((resolve, reject) => {
-    readyResolve = resolve;
-    readyReject = reject;
-  });
-
-  const frameDuration = 1_000_000 / config.fps; // microseconds per frame
-
-  function post(msg: MainToWorkerMessage, transfer?: Transferable[]) {
-    worker.postMessage(msg, transfer ?? []);
-  }
-
-  // Keep async lifecycle checks observable to TypeScript: event handlers can
-  // change state while finalize() is awaiting pending frame acknowledgements.
-  const currentState = () => state;
-
-  worker.onmessage = (event: MessageEvent<WorkerToMainMessage>) => {
-    const msg = event.data;
-    switch (msg.type) {
-      case 'capabilities':
-        readySettled = true;
-        readyResolve?.(msg.backend);
-        readyResolve = readyReject = null;
-        break;
-      case 'frame-complete': {
-        const waiter = frameWaiters.get(msg.frameIndex);
-        waiter?.resolve();
-        frameWaiters.delete(msg.frameIndex);
-        break;
-      }
-      case 'complete':
-        state = 'closed';
-        finalizeResolve?.(msg.data);
-        finalizeResolve = finalizeReject = null;
-        worker.terminate();
-        break;
-      case 'error': {
-        const err = new Error(msg.message);
-        fatalError = err;
-        state = 'closed';
-        readySettled = true;
-        readyReject?.(err);
-        finalizeReject?.(err);
-        for (const waiter of frameWaiters.values()) waiter.reject(err);
-        frameWaiters.clear();
-        readyResolve = readyReject = null;
-        finalizeResolve = finalizeReject = null;
-        worker.terminate();
-        break;
-      }
-      // 'progress' is informational; ignored at this layer
-    }
-  };
-
-  worker.onerror = (event) => {
-    const err = new Error(event.message || 'Worker error');
-    fatalError = err;
-    state = 'closed';
-    readySettled = true;
-    readyReject?.(err);
-    finalizeReject?.(err);
-    for (const waiter of frameWaiters.values()) waiter.reject(err);
-    frameWaiters.clear();
-    readyResolve = readyReject = null;
-    finalizeResolve = finalizeReject = null;
-    worker.terminate();
-  };
-
-  post({
-    type: 'init',
-    width: config.width,
-    height: config.height,
-    fps: config.fps,
-    quality: config.quality,
-    ...(config.ffmpegWasm ? { ffmpegWasm: config.ffmpegWasm } : {}),
-  });
-
-  return {
-    ready,
-
-    encodeFrame(bitmap: ImageBitmap, frameIndex: number): Promise<void> {
-      if (state !== 'open' || fatalError) {
-        bitmap.close();
-        return Promise.reject(fatalError ?? new Error('Encoder is not accepting frames'));
-      }
-      if (frameWaiters.has(frameIndex)) {
-        bitmap.close();
-        return Promise.reject(new Error(`Frame ${frameIndex} was submitted more than once`));
-      }
-      let resolveFrame!: () => void;
-      let rejectFrame!: (err: Error) => void;
-      const promise = new Promise<void>((resolve, reject) => {
-        resolveFrame = resolve;
-        rejectFrame = reject;
-      });
-      frameWaiters.set(frameIndex, { promise, resolve: resolveFrame, reject: rejectFrame });
-      const timestamp = Math.round(frameIndex * frameDuration);
-      post({ type: 'frame', bitmap, frameIndex, timestamp }, [bitmap]);
-      return promise;
-    },
-
-    async finalize(): Promise<ArrayBuffer> {
-      if (state !== 'open') throw new Error('Encoder already closed or finalizing');
-      if (fatalError) throw fatalError;
-      state = 'finalizing';
-      await Promise.all(Array.from(frameWaiters.values(), (waiter) => waiter.promise));
-      if (currentState() === 'closed') {
-        throw fatalError ?? new Error('Encoder closed during finalization');
-      }
-      return new Promise<ArrayBuffer>((resolve, reject) => {
-        finalizeResolve = resolve;
-        finalizeReject = reject;
-        post({ type: 'finalize' });
-      });
-    },
-
-    close() {
-      if (state === 'closed') return;
-      state = 'closed';
-      const err = new Error('Encoder closed');
-      if (!readySettled) {
-        readySettled = true;
-        readyReject?.(err);
-      }
-      finalizeReject?.(err);
-      for (const waiter of frameWaiters.values()) waiter.reject(err);
-      frameWaiters.clear();
-      readyResolve = readyReject = null;
-      finalizeResolve = finalizeReject = null;
-      post({ type: 'cancel' });
-      worker.terminate();
-    },
-  };
-}