@bendyline/squisq-video-react 1.2.0 → 1.2.1

package/src/mainThreadEncoder.ts

@@ -11,6 +11,8 @@
  * Requirements: Chrome 94+ / Edge 94+ (WebCodecs support).
  */
 
+import { bitrateForQuality } from '@bendyline/squisq-video';
+
 import { createMp4Muxer, type Mp4MuxerHandle } from './mp4Mux.js';
 
 export interface EncoderConfig {
@@ -18,11 +20,26 @@ export interface EncoderConfig {
   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): 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). */
@@ -58,19 +75,6 @@ export async function supportsWebCodecsH264(config: EncoderConfig): Promise<bool
   }
 }
 
-function bitrateForQuality(quality: string, width: number, height: number): number {
-  const pixels = width * height;
-  const baseBitrate = pixels * 4; // ~4 bits per pixel baseline
-  switch (quality) {
-    case 'draft':
-      return Math.round(baseBitrate * 0.5);
-    case 'high':
-      return Math.round(baseBitrate * 2);
-    default: // normal
-      return baseBitrate;
-  }
-}
-
 /**
  * Create a main-thread WebCodecs encoder.
  *
@@ -94,6 +98,7 @@ export function createEncoder(config: EncoderConfig): MainThreadEncoder {
     width: config.width,
     height: config.height,
     fps: config.fps,
+    ...(config.audio ? { audio: config.audio } : {}),
   });
 
   let closed = false;
@@ -110,6 +115,9 @@ export function createEncoder(config: EncoderConfig): MainThreadEncoder {
   });
 
   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,
@@ -131,6 +139,11 @@ export function createEncoder(config: EncoderConfig): MainThreadEncoder {
       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();

package/src/mp4Mux.ts

@@ -1,8 +1,10 @@
 /**
  * mp4Mux — Thin wrapper around mp4-muxer for WebCodecs encoding.
  *
- * Creates a Muxer instance configured for H.264 video, accumulates
- * encoded chunks, and produces a final MP4 ArrayBuffer.
+ * 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';
@@ -11,17 +13,52 @@ 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.
+ * Create an MP4 muxer configured for H.264 video, plus an optional AAC track.
  */
 export function createMp4Muxer(options: Mp4MuxerOptions): Mp4MuxerHandle {
   const target = new ArrayBufferTarget();
@@ -33,14 +70,51 @@ export function createMp4Muxer(options: Mp4MuxerOptions): Mp4MuxerHandle {
       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/workers/encode.worker.ts

@@ -16,8 +16,9 @@ import type {
   InitMessage,
   FrameMessage,
 } from './workerTypes.js';
+import { bitrateForQuality, ffmpegVideoQualityArgs } from '@bendyline/squisq-video';
+
 import { createMp4Muxer, type Mp4MuxerHandle } from '../mp4Mux.js';
-import { bitrateForQuality } from './encodeParams.js';
 
 // ── State ──────────────────────────────────────────────────────────
 
@@ -35,7 +36,6 @@ let ffmpegConfig: InitMessage | null = null;
 
 // Frame tracking
 let totalFramesReceived = 0;
-let _totalFramesEncoded = 0;
 
 // ── Helpers ────────────────────────────────────────────────────────
 
@@ -96,14 +96,15 @@ function initWebCodecs(config: InitMessage) {
     output(chunk, meta) {
       if (cancelled) return;
       muxer!.addVideoChunk(chunk, meta ?? undefined);
-      _totalFramesEncoded++;
     },
     error(err) {
       postError(`WebCodecs encoder error: ${err.message}`);
     },
   });
 
-  // Use H.264 Baseline for maximum compatibility
+  // Deliberate profile split from mainThreadEncoder (avc1.640028, High@4.0):
+  // this worker is the max-compatibility fallback path, so it uses H.264
+  // Baseline (avc1.42001f) — widest decoder support at a small quality cost.
   videoEncoder.configure({
     codec: 'avc1.42001f',
     width: config.width,
@@ -240,10 +241,7 @@ async function encodeFfmpegBatch() {
     'libx264',
     '-pix_fmt',
     'yuv420p',
-    '-preset',
-    config.quality === 'draft' ? 'ultrafast' : config.quality === 'high' ? 'slow' : 'medium',
-    '-crf',
-    config.quality === 'draft' ? '28' : config.quality === 'high' ? '18' : '23',
+    ...ffmpegVideoQualityArgs(config.quality),
     segmentName,
   ]);
 
@@ -334,7 +332,6 @@ self.onmessage = async (event: MessageEvent<MainToWorkerMessage>) => {
       case 'init': {
         cancelled = false;
         totalFramesReceived = 0;
-        _totalFramesEncoded = 0;
 
         if (await supportsWebCodecsH264(msg)) {
           backend = 'webcodecs';

package/dist/chunk-LZYWP4HB.js

@@ -1,28 +0,0 @@
-// src/mp4Mux.ts
-import { Muxer, ArrayBufferTarget } from "mp4-muxer";
-function createMp4Muxer(options) {
-  const target = new ArrayBufferTarget();
-  const muxer = new Muxer({
-    target,
-    video: {
-      codec: "avc",
-      width: options.width,
-      height: options.height
-    },
-    fastStart: "in-memory"
-  });
-  return {
-    addVideoChunk(chunk, meta) {
-      muxer.addVideoChunk(chunk, meta);
-    },
-    finalize() {
-      muxer.finalize();
-      return target.buffer;
-    }
-  };
-}
-
-export {
-  createMp4Muxer
-};
-//# sourceMappingURL=chunk-LZYWP4HB.js.map

package/dist/chunk-LZYWP4HB.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/mp4Mux.ts"],"sourcesContent":["/**\n * mp4Mux — Thin wrapper around mp4-muxer for WebCodecs encoding.\n *\n * Creates a Muxer instance configured for H.264 video, accumulates\n * encoded chunks, and produces a final MP4 ArrayBuffer.\n */\n\nimport { Muxer, ArrayBufferTarget } from 'mp4-muxer';\n\nexport interface Mp4MuxerOptions {\n  width: number;\n  height: number;\n  fps: number;\n}\n\nexport interface Mp4MuxerHandle {\n  /** Add an encoded video chunk to the muxer. */\n  addVideoChunk(chunk: EncodedVideoChunk, meta?: EncodedVideoChunkMetadata): void;\n  /** Finalize and return the MP4 as an ArrayBuffer. */\n  finalize(): ArrayBuffer;\n}\n\n/**\n * Create an MP4 muxer configured for H.264 video.\n */\nexport function createMp4Muxer(options: Mp4MuxerOptions): Mp4MuxerHandle {\n  const target = new ArrayBufferTarget();\n\n  const muxer = new Muxer({\n    target,\n    video: {\n      codec: 'avc',\n      width: options.width,\n      height: options.height,\n    },\n    fastStart: 'in-memory',\n  });\n\n  return {\n    addVideoChunk(chunk: EncodedVideoChunk, meta?: EncodedVideoChunkMetadata) {\n      muxer.addVideoChunk(chunk, meta);\n    },\n\n    finalize(): ArrayBuffer {\n      muxer.finalize();\n      return target.buffer;\n    },\n  };\n}\n"],"mappings":";AAOA,SAAS,OAAO,yBAAyB;AAkBlC,SAAS,eAAe,SAA0C;AACvE,QAAM,SAAS,IAAI,kBAAkB;AAErC,QAAM,QAAQ,IAAI,MAAM;AAAA,IACtB;AAAA,IACA,OAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO,QAAQ;AAAA,MACf,QAAQ,QAAQ;AAAA,IAClB;AAAA,IACA,WAAW;AAAA,EACb,CAAC;AAED,SAAO;AAAA,IACL,cAAc,OAA0B,MAAkC;AACxE,YAAM,cAAc,OAAO,IAAI;AAAA,IACjC;AAAA,IAEA,WAAwB;AACtB,YAAM,SAAS;AACf,aAAO,OAAO;AAAA,IAChB;AAAA,EACF;AACF;","names":[]}

package/src/__tests__/encodeParams.test.ts

@@ -1,33 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { bitrateForQuality } from '../workers/encodeParams.js';
-
-const W = 1920;
-const H = 1080;
-const base = W * H * 4;
-
-describe('bitrateForQuality', () => {
-  it('returns the ~4 bits-per-pixel baseline for normal quality', () => {
-    expect(bitrateForQuality('normal', W, H)).toBe(base);
-  });
-
-  it('falls back to the normal baseline for unknown quality values', () => {
-    expect(bitrateForQuality('whatever', W, H)).toBe(base);
-  });
-
-  it('halves the baseline for draft and doubles it for high', () => {
-    expect(bitrateForQuality('draft', W, H)).toBe(Math.round(base * 0.5));
-    expect(bitrateForQuality('high', W, H)).toBe(Math.round(base * 2));
-  });
-
-  it('orders bitrate draft < normal < high', () => {
-    const draft = bitrateForQuality('draft', W, H);
-    const normal = bitrateForQuality('normal', W, H);
-    const high = bitrateForQuality('high', W, H);
-    expect(draft).toBeLessThan(normal);
-    expect(normal).toBeLessThan(high);
-  });
-
-  it('scales with resolution', () => {
-    expect(bitrateForQuality('normal', 640, 480)).toBeLessThan(bitrateForQuality('normal', W, H));
-  });
-});

package/src/workers/encodeParams.ts

@@ -1,24 +0,0 @@
-/**
- * Pure encoding-parameter helpers used by the encode worker.
- *
- * Kept separate from `encode.worker.ts` so they can be unit-tested directly —
- * importing the worker module wires up `self.onmessage` and pulls in the
- * WebCodecs / ffmpeg.wasm backends, none of which exist in a plain test runner.
- */
-
-/**
- * Target H.264 bitrate (bits/sec) for a given quality at a given resolution.
- * Baseline is ~4 bits per pixel; `draft` halves it and `high` doubles it.
- */
-export function bitrateForQuality(quality: string, width: number, height: number): number {
-  const pixels = width * height;
-  const baseBitrate = pixels * 4; // ~4 bits per pixel baseline
-  switch (quality) {
-    case 'draft':
-      return Math.round(baseBitrate * 0.5);
-    case 'high':
-      return Math.round(baseBitrate * 2);
-    default: // normal
-      return baseBitrate;
-  }
-}