@bendyline/squisq-video-react 2.0.2 → 2.1.0

package/src/__tests__/workerEncoder.test.ts

@@ -1,143 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { createWorkerEncoder } from '../workerEncoder.js';
-import type { MainToWorkerMessage, WorkerToMainMessage } from '../workers/workerTypes.js';
-
-class FakeWorker {
-  static instances: FakeWorker[] = [];
-
-  onmessage: ((event: MessageEvent<WorkerToMainMessage>) => void) | null = null;
-  onerror: ((event: ErrorEvent) => void) | null = null;
-  readonly posted: MainToWorkerMessage[] = [];
-  readonly terminate = vi.fn();
-
-  constructor() {
-    FakeWorker.instances.push(this);
-  }
-
-  postMessage(message: MainToWorkerMessage): void {
-    this.posted.push(message);
-  }
-
-  emit(message: WorkerToMainMessage): void {
-    this.onmessage?.({ data: message } as MessageEvent<WorkerToMainMessage>);
-  }
-}
-
-function createEncoder() {
-  return createWorkerEncoder({ width: 640, height: 360, fps: 30, quality: 'normal' });
-}
-
-function bitmap(): ImageBitmap {
-  return { close: vi.fn() } as unknown as ImageBitmap;
-}
-
-describe('createWorkerEncoder', () => {
-  beforeEach(() => {
-    FakeWorker.instances = [];
-    vi.stubGlobal('Worker', FakeWorker);
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-  });
-
-  it('rejects invalid configs before allocating a worker', () => {
-    expect(() =>
-      createWorkerEncoder({ width: 640, height: 360, fps: 0, quality: 'normal' }),
-    ).toThrow('Video FPS');
-    expect(FakeWorker.instances).toHaveLength(0);
-  });
-
-  it('keeps frame backpressure until the worker acknowledges the frame', async () => {
-    const encoder = createEncoder();
-    const worker = FakeWorker.instances[0];
-    worker.emit({ type: 'capabilities', backend: 'webcodecs' });
-    await expect(encoder.ready).resolves.toBe('webcodecs');
-
-    let completed = false;
-    const pending = encoder.encodeFrame(bitmap(), 7).then(() => {
-      completed = true;
-    });
-
-    await Promise.resolve();
-    expect(completed).toBe(false);
-    expect(worker.posted[worker.posted.length - 1]).toMatchObject({ type: 'frame', frameIndex: 7 });
-
-    worker.emit({ type: 'frame-complete', frameIndex: 7 });
-    await pending;
-    expect(completed).toBe(true);
-  });
-
-  it('threads self-hosted ffmpeg core URLs through worker initialization', () => {
-    createWorkerEncoder({
-      width: 640,
-      height: 360,
-      fps: 30,
-      quality: 'normal',
-      ffmpegWasm: {
-        coreURL: '/vendor/ffmpeg-core.js',
-        wasmURL: '/vendor/ffmpeg-core.wasm',
-      },
-    });
-
-    expect(FakeWorker.instances[0].posted[0]).toMatchObject({
-      type: 'init',
-      ffmpegWasm: {
-        coreURL: '/vendor/ffmpeg-core.js',
-        wasmURL: '/vendor/ffmpeg-core.wasm',
-      },
-    });
-  });
-
-  it('does not finalize until every submitted frame has completed', async () => {
-    const encoder = createEncoder();
-    const worker = FakeWorker.instances[0];
-    worker.emit({ type: 'capabilities', backend: 'ffmpeg-wasm' });
-    await encoder.ready;
-
-    const frame = encoder.encodeFrame(bitmap(), 3);
-    const finalized = encoder.finalize();
-    await Promise.resolve();
-    expect(worker.posted.some((message) => message.type === 'finalize')).toBe(false);
-
-    worker.emit({ type: 'frame-complete', frameIndex: 3 });
-    await frame;
-    await Promise.resolve();
-    expect(worker.posted[worker.posted.length - 1]).toEqual({ type: 'finalize' });
-
-    const result = new ArrayBuffer(4);
-    worker.emit({ type: 'complete', data: result, size: result.byteLength });
-    await expect(finalized).resolves.toBe(result);
-    expect(worker.terminate).toHaveBeenCalledOnce();
-  });
-
-  it('rejects readiness when closed during initialization', async () => {
-    const encoder = createEncoder();
-    const worker = FakeWorker.instances[0];
-    const readiness = expect(encoder.ready).rejects.toThrow('Encoder closed');
-
-    encoder.close();
-
-    await readiness;
-    expect(worker.posted[worker.posted.length - 1]).toEqual({ type: 'cancel' });
-    expect(worker.terminate).toHaveBeenCalledOnce();
-  });
-
-  it('rejects an in-flight finalization when closed', async () => {
-    const encoder = createEncoder();
-    const worker = FakeWorker.instances[0];
-    worker.emit({ type: 'capabilities', backend: 'webcodecs' });
-    await encoder.ready;
-
-    const finalized = encoder.finalize();
-    await Promise.resolve();
-    expect(worker.posted[worker.posted.length - 1]).toEqual({ type: 'finalize' });
-
-    encoder.close();
-
-    await expect(finalized).rejects.toThrow('Encoder closed');
-    expect(worker.posted[worker.posted.length - 1]).toEqual({ type: 'cancel' });
-    expect(worker.terminate).toHaveBeenCalledOnce();
-  });
-});

package/src/audioTrack.ts

@@ -1,332 +0,0 @@
-/**
- * audioTrack — In-browser audio rendering + AAC encoding for MP4 export.
- *
- * Replaces the CLI's ffmpeg `adelay`/`atrim`/`amix` graph with browser-native
- * primitives:
- *
- *  - {@link supportsWebCodecsAac} probes whether the browser can encode AAC
- *    (WebCodecs `AudioEncoder`).
- *  - {@link renderAudioTimeline} mixes an {@link AudioTimelineClip} list into a
- *    single `AudioBuffer` using an `OfflineAudioContext` (decode → schedule →
- *    render).
- *  - {@link encodeAacTrack} feeds that buffer through a WebCodecs
- *    `AudioEncoder` and hands the chunks to an mp4-muxer audio track (tier 1).
- *  - {@link audioBufferToWav} + {@link muxAudioWithFfmpegWasm} cover the
- *    ffmpeg.wasm fallback (tier 2).
- *  - {@link selectAudioTier} is the pure capability→tier decision shared with
- *    `useVideoExport` (and unit-tested at the module boundary).
- */
-
-import {
-  ffmpegAudioMuxArgs,
-  type AudioTimelineClip,
-  type FfmpegWasmLoadConfig,
-} from '@bendyline/squisq-video';
-
-/** Sample rate the export renders + encodes audio at. */
-export const EXPORT_AUDIO_SAMPLE_RATE = 48_000;
-/** Channel count the export renders + encodes audio at (stereo). */
-export const EXPORT_AUDIO_CHANNELS = 2;
-
-/** Tier-3 reason used when AAC encoding is impossible and no ffmpeg fallback. */
-export const REASON_NO_AAC_NO_SAB =
-  'This browser cannot encode AAC audio (WebCodecs AudioEncoder unavailable) ' +
-  'and the ffmpeg.wasm fallback requires cross-origin isolation (SharedArrayBuffer).';
-
-// ── Capability probe ───────────────────────────────────────────────
-
-/**
- * Whether the browser can encode AAC (`mp4a.40.2`) via WebCodecs.
- * Returns false when `AudioEncoder` is undefined (e.g. Node/jsdom, Safari,
- * older Chromium) or the config is unsupported.
- */
-export async function supportsWebCodecsAac(
-  sampleRate: number = EXPORT_AUDIO_SAMPLE_RATE,
-  channels: number = EXPORT_AUDIO_CHANNELS,
-): Promise<boolean> {
-  if (typeof AudioEncoder === 'undefined') return false;
-  try {
-    const support = await AudioEncoder.isConfigSupported({
-      codec: 'mp4a.40.2',
-      sampleRate,
-      numberOfChannels: channels,
-      bitrate: 128_000,
-    });
-    return support.supported === true;
-  } catch {
-    return false;
-  }
-}
-
-// ── Tier selection (pure) ──────────────────────────────────────────
-
-export interface AudioTierInputs {
-  /** Whether the doc has any audio timeline clips to include at all. */
-  hasClips: boolean;
-  /** Whether WebCodecs AAC encoding is available. */
-  aacSupported: boolean;
-  /** Whether `SharedArrayBuffer` (ffmpeg.wasm path) is available. */
-  sharedArrayBufferAvailable: boolean;
-  /** Whether the main-thread WebCodecs H.264 encoder is in use (tier-1 host). */
-  canUseMainThreadWebCodecs: boolean;
-}
-
-export interface AudioTierDecision {
-  /**
-   * 1 → inline AAC into the video muxer.
-   * 2 → finalize video-only then ffmpeg.wasm mux pass.
-   * 3 → video-only (no audio).
-   */
-  tier: 1 | 2 | 3;
-  /**
-   * Reason audio will be absent, when tier 3. `null` means "there was simply
-   * no audio to include" (not a failure). Non-null for a genuine capability
-   * shortfall. Always `null` for tiers 1 and 2 (the attempt is expected to
-   * succeed; the caller downgrades with a fresh reason on runtime failure).
-   */
-  reason: string | null;
-}
-
-/**
- * Decide which audio tier to run from capability booleans. Pure — the single
- * source of truth for tier selection, shared with `useVideoExport`.
- */
-export function selectAudioTier(inputs: AudioTierInputs): AudioTierDecision {
-  if (!inputs.hasClips) {
-    return { tier: 3, reason: null };
-  }
-  if (inputs.aacSupported && inputs.canUseMainThreadWebCodecs) {
-    return { tier: 1, reason: null };
-  }
-  if (inputs.sharedArrayBufferAvailable) {
-    return { tier: 2, reason: null };
-  }
-  return { tier: 3, reason: REASON_NO_AAC_NO_SAB };
-}
-
-// ── OfflineAudioContext rendering ──────────────────────────────────
-
-type OfflineCtor = new (
-  numberOfChannels: number,
-  length: number,
-  sampleRate: number,
-) => OfflineAudioContext;
-
-function resolveOfflineAudioContext(): OfflineCtor {
-  const g = globalThis as unknown as {
-    OfflineAudioContext?: OfflineCtor;
-    webkitOfflineAudioContext?: OfflineCtor;
-  };
-  const ctor = g.OfflineAudioContext ?? g.webkitOfflineAudioContext;
-  if (!ctor) {
-    throw new Error('OfflineAudioContext is not available in this environment.');
-  }
-  return ctor;
-}
-
-/**
- * Mix a list of timeline clips into one `AudioBuffer`.
- *
- * Decodes each unique source once, then schedules an `AudioBufferSourceNode`
- * per clip at its `startSec` with the trim window (`offset = sourceInSec`,
- * `duration = durationSec`). Undecodable sources are skipped rather than
- * failing the whole render.
- */
-export async function renderAudioTimeline(
-  clips: AudioTimelineClip[],
-  buffers: Map<string, ArrayBuffer>,
-  totalDurationSec: number,
-  sampleRate: number = EXPORT_AUDIO_SAMPLE_RATE,
-): Promise<AudioBuffer> {
-  const Ctor = resolveOfflineAudioContext();
-  const channels = EXPORT_AUDIO_CHANNELS;
-  const length = Math.max(1, Math.ceil(totalDurationSec * sampleRate));
-  const ctx = new Ctor(channels, length, sampleRate);
-
-  // Decode each unique source once. decodeAudioData detaches the buffer, so
-  // hand it a copy to keep the caller's ArrayBuffer reusable.
-  const decoded = new Map<string, AudioBuffer>();
-  for (const [src, data] of buffers) {
-    try {
-      decoded.set(src, await ctx.decodeAudioData(data.slice(0)));
-    } catch {
-      // Skip undecodable sources; the clip is simply omitted.
-    }
-  }
-
-  for (const clip of clips) {
-    const buffer = decoded.get(clip.src);
-    if (!buffer) continue;
-    const node = ctx.createBufferSource();
-    node.buffer = buffer;
-    node.connect(ctx.destination);
-    const when = Math.max(0, clip.startSec);
-    const offset = Math.max(0, clip.sourceInSec);
-    const duration = Math.max(0, clip.durationSec);
-    node.start(when, offset, duration);
-  }
-
-  return ctx.startRendering();
-}
-
-// ── WebCodecs AAC encode (tier 1) ──────────────────────────────────
-
-/** Minimal muxer surface {@link encodeAacTrack} needs. */
-export interface AudioChunkSink {
-  addAudioChunk(chunk: EncodedAudioChunk, meta?: EncodedAudioChunkMetadata): void;
-}
-
-/**
- * Encode an `AudioBuffer` to AAC via WebCodecs and feed the chunks to `sink`.
- * Resolves once every chunk has been flushed to the muxer. Throws only if the
- * `AudioEncoder` errors — the caller wraps this so audio failure never aborts
- * the video export.
- */
-export async function encodeAacTrack(
-  audioBuffer: AudioBuffer,
-  sink: AudioChunkSink,
-  bitrate: number,
-): Promise<void> {
-  if (typeof AudioEncoder === 'undefined' || typeof AudioData === 'undefined') {
-    throw new Error('WebCodecs AudioEncoder is not available.');
-  }
-
-  const sampleRate = audioBuffer.sampleRate;
-  const channels = audioBuffer.numberOfChannels;
-
-  let encodeError: Error | null = null;
-  const encoder = new AudioEncoder({
-    output: (chunk, meta) => sink.addAudioChunk(chunk, meta ?? undefined),
-    error: (err) => {
-      encodeError = err instanceof Error ? err : new Error(String(err));
-    },
-  });
-
-  encoder.configure({ codec: 'mp4a.40.2', sampleRate, numberOfChannels: channels, bitrate });
-
-  const FRAME = 1024; // samples per AudioData chunk
-  const total = audioBuffer.length;
-  const channelData: Float32Array[] = [];
-  for (let ch = 0; ch < channels; ch++) {
-    channelData.push(audioBuffer.getChannelData(ch));
-  }
-
-  for (let offset = 0; offset < total; offset += FRAME) {
-    if (encodeError) break;
-    const count = Math.min(FRAME, total - offset);
-    // Planar layout: all of channel 0, then all of channel 1, …
-    const planar = new Float32Array(count * channels);
-    for (let ch = 0; ch < channels; ch++) {
-      planar.set(channelData[ch].subarray(offset, offset + count), ch * count);
-    }
-    const timestamp = Math.round((offset / sampleRate) * 1_000_000);
-    const audioData = new AudioData({
-      format: 'f32-planar',
-      sampleRate,
-      numberOfFrames: count,
-      numberOfChannels: channels,
-      timestamp,
-      data: planar,
-    });
-    encoder.encode(audioData);
-    audioData.close();
-  }
-
-  await encoder.flush();
-  encoder.close();
-  if (encodeError) throw encodeError;
-}
-
-// ── WAV serialization (tier 2 input) ───────────────────────────────
-
-/**
- * Serialize an `AudioBuffer` to a 16-bit PCM WAV byte array. Used to hand the
- * rendered audio to the ffmpeg.wasm fallback for muxing.
- */
-export function audioBufferToWav(buffer: AudioBuffer): Uint8Array {
-  const channels = buffer.numberOfChannels;
-  const sampleRate = buffer.sampleRate;
-  const frames = buffer.length;
-  const bytesPerSample = 2;
-  const blockAlign = channels * bytesPerSample;
-  const dataSize = frames * blockAlign;
-  const out = new ArrayBuffer(44 + dataSize);
-  const view = new DataView(out);
-
-  const writeStr = (offset: number, str: string) => {
-    for (let i = 0; i < str.length; i++) view.setUint8(offset + i, str.charCodeAt(i));
-  };
-
-  writeStr(0, 'RIFF');
-  view.setUint32(4, 36 + dataSize, true);
-  writeStr(8, 'WAVE');
-  writeStr(12, 'fmt ');
-  view.setUint32(16, 16, true); // PCM chunk size
-  view.setUint16(20, 1, true); // PCM format
-  view.setUint16(22, channels, true);
-  view.setUint32(24, sampleRate, true);
-  view.setUint32(28, sampleRate * blockAlign, true); // byte rate
-  view.setUint16(32, blockAlign, true);
-  view.setUint16(34, bytesPerSample * 8, true);
-  writeStr(36, 'data');
-  view.setUint32(40, dataSize, true);
-
-  const channelData: Float32Array[] = [];
-  for (let ch = 0; ch < channels; ch++) channelData.push(buffer.getChannelData(ch));
-
-  let pos = 44;
-  for (let i = 0; i < frames; i++) {
-    for (let ch = 0; ch < channels; ch++) {
-      let sample = channelData[ch][i];
-      sample = Math.max(-1, Math.min(1, sample));
-      view.setInt16(pos, sample < 0 ? sample * 0x8000 : sample * 0x7fff, true);
-      pos += 2;
-    }
-  }
-
-  return new Uint8Array(out);
-}
-
-// ── ffmpeg.wasm mux fallback (tier 2) ──────────────────────────────
-
-/**
- * Mux a pre-encoded video-only MP4 with a WAV audio track in a single
- * ffmpeg.wasm pass (`-c:v copy -c:a aac -af apad -shortest`). Requires
- * `SharedArrayBuffer` (cross-origin isolation). Returns the muxed MP4 bytes.
- */
-export async function muxAudioWithFfmpegWasm(
-  videoMp4: Uint8Array,
-  wav: Uint8Array,
-  audioBitrate: number,
-  loadConfig?: FfmpegWasmLoadConfig,
-): Promise<Uint8Array> {
-  const { FFmpeg } = await import('@ffmpeg/ffmpeg');
-  const ffmpeg = new FFmpeg();
-  try {
-    await ffmpeg.load({
-      ...loadConfig,
-      classWorkerURL:
-        loadConfig?.classWorkerURL ??
-        new URL('./workers/ffmpeg.class-worker.js', import.meta.url).href,
-    });
-    await ffmpeg.writeFile('video.mp4', videoMp4);
-    await ffmpeg.writeFile('audio.wav', wav);
-    const exitCode = await ffmpeg.exec([
-      '-i',
-      'video.mp4',
-      '-i',
-      'audio.wav',
-      '-c:v',
-      'copy',
-      ...ffmpegAudioMuxArgs(audioBitrate),
-      'out.mp4',
-    ]);
-    if (exitCode !== 0) {
-      throw new Error(`ffmpeg.wasm audio mux failed with exit code ${exitCode}`);
-    }
-    const data = await ffmpeg.readFile('out.mp4');
-    return data instanceof Uint8Array ? data : new TextEncoder().encode(data as string);
-  } finally {
-    ffmpeg.terminate();
-  }
-}

package/src/gifTranscode.ts

@@ -1,75 +0,0 @@
-/**
- * Animated GIF finalization for the browser export path.
- *
- * The frame-capture pipeline already produces a compact, video-only MP4. For
- * the GIF MVP we use that MP4 as a bounded-memory intermediate, then run a
- * palette generation/application pass through ffmpeg.wasm.
- */
-
-import {
-  ffmpegGifOutputArgs,
-  type FfmpegWasmLoadConfig,
-  type GifOutputOptions,
-} from '@bendyline/squisq-video';
-
-/** Build the deterministic ffmpeg arguments used for MP4 -> animated GIF. */
-export function buildGifFfmpegArgs(options: GifOutputOptions): string[] {
-  return ['-y', '-i', 'video.mp4', ...ffmpegGifOutputArgs(options), 'out.gif'];
-}
-
-/**
- * Convert a video-only MP4 into a looping animated GIF with a generated
- * palette. The ffmpeg runtime is always terminated, including on failure.
- */
-export async function transcodeMp4ToGifWithFfmpegWasm(
-  videoMp4: Uint8Array,
-  options: GifOutputOptions,
-  loadConfig?: FfmpegWasmLoadConfig,
-  signal?: AbortSignal,
-): Promise<Uint8Array> {
-  if (videoMp4.byteLength === 0) {
-    throw new Error('Cannot create an animated GIF from an empty MP4.');
-  }
-  if (signal?.aborted) {
-    throw new DOMException('Animated GIF export was cancelled.', 'AbortError');
-  }
-
-  const args = buildGifFfmpegArgs(options);
-  const { FFmpeg } = await import('@ffmpeg/ffmpeg');
-  const ffmpeg = new FFmpeg();
-  let terminated = false;
-  const terminate = () => {
-    if (terminated) return;
-    terminated = true;
-    ffmpeg.terminate();
-  };
-  const handleAbort = () => terminate();
-  signal?.addEventListener('abort', handleAbort, { once: true });
-  try {
-    await ffmpeg.load({
-      ...loadConfig,
-      classWorkerURL:
-        loadConfig?.classWorkerURL ??
-        new URL('./workers/ffmpeg.class-worker.js', import.meta.url).href,
-    });
-    if (signal?.aborted) {
-      throw new DOMException('Animated GIF export was cancelled.', 'AbortError');
-    }
-    await ffmpeg.writeFile('video.mp4', videoMp4);
-    if (signal?.aborted) {
-      throw new DOMException('Animated GIF export was cancelled.', 'AbortError');
-    }
-    const exitCode = await ffmpeg.exec(args);
-    if (signal?.aborted) {
-      throw new DOMException('Animated GIF export was cancelled.', 'AbortError');
-    }
-    if (exitCode !== 0) {
-      throw new Error(`ffmpeg.wasm GIF transcode failed with exit code ${exitCode}`);
-    }
-    const data = await ffmpeg.readFile('out.gif');
-    return data instanceof Uint8Array ? data : new TextEncoder().encode(data as string);
-  } finally {
-    signal?.removeEventListener('abort', handleAbort);
-    terminate();
-  }
-}