@bendyline/squisq-video-react 1.2.0 → 1.2.2

package/src/VideoExportButton.tsx

@@ -10,18 +10,28 @@ import { createPortal } from 'react-dom';
 import type { Doc } from '@bendyline/squisq/schemas';
 import type { MediaProvider } from '@bendyline/squisq/schemas';
 import { VideoExportModal } from './VideoExportModal.js';
+import type { VideoExportConfig } from './hooks/useVideoExport.js';
 
 export interface VideoExportButtonProps {
   /** The document to export */
   doc: Doc;
-  /** Player IIFE bundle source */
-  playerScript: string;
+  /**
+   * Player IIFE bundle source. Unused by the browser export path (frames
+   * are captured from a live in-page DocPlayer); only forwarded for
+   * CLI/Playwright-style pipelines that render standalone HTML.
+   */
+  playerScript?: string;
   /** Optional media provider for resolving images/audio */
   mediaProvider?: MediaProvider;
   /** Pre-collected images map */
   images?: Map<string, ArrayBuffer>;
   /** Pre-collected audio map */
   audio?: Map<string, ArrayBuffer>;
+  /**
+   * Seeds the modal's initial export settings and is merged as a base into the
+   * config passed to the export hook. Forwarded to {@link VideoExportModal}.
+   */
+  defaultConfig?: Partial<VideoExportConfig>;
   /** Button label (default: "Export Video") */
   label?: string;
   /** Additional inline styles for the button */
@@ -36,6 +46,7 @@ export function VideoExportButton({
   mediaProvider,
   images,
   audio,
+  defaultConfig,
   label = 'Export Video',
   style,
   disabled,
@@ -59,6 +70,7 @@ export function VideoExportButton({
             mediaProvider={mediaProvider}
             images={images}
             audio={audio}
+            defaultConfig={defaultConfig}
             onClose={handleClose}
           />,
           document.body,

package/src/VideoExportModal.tsx

@@ -19,14 +19,26 @@ import { useVideoExport, type VideoExportConfig } from './hooks/useVideoExport.j
 export interface VideoExportModalProps {
   /** The document to export */
   doc: Doc;
-  /** Player IIFE bundle source */
-  playerScript: string;
+  /**
+   * Player IIFE bundle source. Unused by the browser export path (frames
+   * are captured from a live in-page DocPlayer); only forwarded for
+   * CLI/Playwright-style pipelines that render standalone HTML.
+   */
+  playerScript?: string;
   /** Optional media provider for resolving images/audio */
   mediaProvider?: MediaProvider;
   /** Pre-collected images map (alternative to mediaProvider) */
   images?: Map<string, ArrayBuffer>;
   /** Pre-collected audio map */
   audio?: Map<string, ArrayBuffer>;
+  /**
+   * Seeds the modal's initial quality/fps/orientation/captionMode selections
+   * and is merged (as a base) into the config passed to the export hook, so a
+   * host can share one config shape with `useVideoExport`. The individual
+   * `images`/`audio`/`mediaProvider`/`playerScript` props still take
+   * precedence over any matching key here.
+   */
+  defaultConfig?: Partial<VideoExportConfig>;
   /** Called when the modal should close */
   onClose: () => void;
 }
@@ -139,12 +151,15 @@ export function VideoExportModal({
   mediaProvider,
   images,
   audio,
+  defaultConfig,
   onClose,
 }: VideoExportModalProps) {
-  const [quality, setQuality] = useState<VideoQuality>('normal');
-  const [fps, setFps] = useState(24);
-  const [orientation, setOrientation] = useState<VideoOrientation>('landscape');
-  const [captionMode, setCaptionMode] = useState<CaptionMode>('off');
+  const [quality, setQuality] = useState<VideoQuality>(defaultConfig?.quality ?? 'normal');
+  const [fps, setFps] = useState(defaultConfig?.fps ?? 24);
+  const [orientation, setOrientation] = useState<VideoOrientation>(
+    defaultConfig?.orientation ?? 'landscape',
+  );
+  const [captionMode, setCaptionMode] = useState<CaptionMode>(defaultConfig?.captionMode ?? 'off');
 
   const exportHook = useVideoExport();
   const {
@@ -153,6 +168,8 @@ export function VideoExportModal({
     backend,
     downloadUrl,
     fileSize,
+    audioIncluded,
+    audioSkippedReason,
     error,
     elapsed,
     estimatedRemaining,
@@ -163,6 +180,8 @@ export function VideoExportModal({
 
   const handleExport = useCallback(async () => {
     const config: VideoExportConfig = {
+      // defaultConfig is the base; explicit props/selections win over it.
+      ...defaultConfig,
       quality,
       fps,
       orientation,
@@ -170,7 +189,8 @@ export function VideoExportModal({
       images,
       audio,
       mediaProvider,
-      playerScript,
+      // Only thread the bundle through when the host actually supplied one.
+      ...(playerScript !== undefined ? { playerScript } : {}),
     };
     await startExport(doc, config);
   }, [
@@ -183,6 +203,7 @@ export function VideoExportModal({
     audio,
     mediaProvider,
     playerScript,
+    defaultConfig,
     startExport,
   ]);
 
@@ -318,6 +339,15 @@ export function VideoExportModal({
             <p style={{ fontSize: 13, color: '#5a4a2a', margin: '0 0 4px 0' }}>
               File size: {(fileSize / (1024 * 1024)).toFixed(1)} MB
             </p>
+            {audioIncluded ? (
+              <p style={{ fontSize: 12, color: '#2d6a10', margin: '0 0 4px 0' }}>
+                Audio included ✓
+              </p>
+            ) : (
+              <p style={{ fontSize: 12, color: '#8a7a5a', margin: '0 0 4px 0' }}>
+                Video only{audioSkippedReason ? ` — ${audioSkippedReason}` : ''}
+              </p>
+            )}
             {backend && (
               <p style={{ fontSize: 12, color: '#8a7a5a', margin: '0 0 12px 0' }}>
                 Encoded with WebCodecs (H.264)

package/src/__tests__/audioTrack.test.ts

@@ -0,0 +1,108 @@
+/**
+ * audioTrack — tier selection + capability probe.
+ *
+ * The tier decision is the boundary `useVideoExport` delegates to, so testing
+ * `selectAudioTier` directly exercises the exact logic the hook runs (jsdom
+ * lacks real WebCodecs / OfflineAudioContext, so the end-to-end encode path
+ * can only be exercised in a browser). `supportsWebCodecsAac` is verified to
+ * degrade to `false` when `AudioEncoder` is undefined (jsdom's state).
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  selectAudioTier,
+  supportsWebCodecsAac,
+  REASON_NO_AAC_NO_SAB,
+  audioBufferToWav,
+} from '../audioTrack.js';
+
+describe('selectAudioTier', () => {
+  it('tier 1 when AAC is supported on the main-thread WebCodecs encoder', () => {
+    expect(
+      selectAudioTier({
+        hasClips: true,
+        aacSupported: true,
+        sharedArrayBufferAvailable: true,
+        canUseMainThreadWebCodecs: true,
+      }),
+    ).toEqual({ tier: 1, reason: null });
+  });
+
+  it('tier 2 when AAC is unsupported but SharedArrayBuffer (ffmpeg.wasm) is available', () => {
+    expect(
+      selectAudioTier({
+        hasClips: true,
+        aacSupported: false,
+        sharedArrayBufferAvailable: true,
+        canUseMainThreadWebCodecs: false,
+      }),
+    ).toEqual({ tier: 2, reason: null });
+  });
+
+  it('tier 2 when AAC is supported but the main-thread encoder is not in use', () => {
+    // AAC exists but the video is going through the worker/ffmpeg path — the
+    // inline muxer isn't available, so fall back to the ffmpeg mux pass.
+    expect(
+      selectAudioTier({
+        hasClips: true,
+        aacSupported: true,
+        sharedArrayBufferAvailable: true,
+        canUseMainThreadWebCodecs: false,
+      }),
+    ).toEqual({ tier: 2, reason: null });
+  });
+
+  it('tier 3 with a reason when neither AAC nor SharedArrayBuffer is available', () => {
+    expect(
+      selectAudioTier({
+        hasClips: true,
+        aacSupported: false,
+        sharedArrayBufferAvailable: false,
+        canUseMainThreadWebCodecs: false,
+      }),
+    ).toEqual({ tier: 3, reason: REASON_NO_AAC_NO_SAB });
+  });
+
+  it('tier 3 with a null reason when there is no audio to include', () => {
+    expect(
+      selectAudioTier({
+        hasClips: false,
+        aacSupported: true,
+        sharedArrayBufferAvailable: true,
+        canUseMainThreadWebCodecs: true,
+      }),
+    ).toEqual({ tier: 3, reason: null });
+  });
+});
+
+describe('supportsWebCodecsAac', () => {
+  it('returns false when AudioEncoder is undefined (jsdom/Node)', async () => {
+    expect(typeof AudioEncoder).toBe('undefined');
+    await expect(supportsWebCodecsAac()).resolves.toBe(false);
+  });
+});
+
+describe('audioBufferToWav', () => {
+  it('serializes a minimal AudioBuffer-shaped value to a RIFF/WAVE header', () => {
+    // Hand-rolled AudioBuffer stand-in (jsdom has no AudioBuffer). Only the
+    // fields audioBufferToWav reads are provided.
+    const frames = 4;
+    const left = new Float32Array([0, 0.5, -0.5, 1]);
+    const right = new Float32Array([0, -1, 0.25, -0.25]);
+    const fake = {
+      numberOfChannels: 2,
+      sampleRate: 48_000,
+      length: frames,
+      getChannelData: (ch: number) => (ch === 0 ? left : right),
+    } as unknown as AudioBuffer;
+
+    const wav = audioBufferToWav(fake);
+    const ascii = (i: number, n: number) =>
+      String.fromCharCode(...Array.from(wav.subarray(i, i + n)));
+    expect(ascii(0, 4)).toBe('RIFF');
+    expect(ascii(8, 4)).toBe('WAVE');
+    expect(ascii(36, 4)).toBe('data');
+    // 44-byte header + 2 channels * 2 bytes * 4 frames = 60 bytes.
+    expect(wav.byteLength).toBe(44 + frames * 2 * 2);
+  });
+});

package/src/__tests__/mp4MuxAudio.test.ts

@@ -0,0 +1,72 @@
+/**
+ * mp4Mux audio track — verifies the additive AAC track wiring.
+ *
+ * mp4-muxer runs in Node, so we can add a raw audio sample and assert the
+ * finalized MP4 actually carries an `mp4a` sample-description box (i.e. the
+ * audio track made it into the container). We also assert the video-only
+ * configuration produces no such box, guarding the "byte-identical when no
+ * audio" contract.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { createMp4Muxer, type Mp4MuxerHandle } from '../mp4Mux.js';
+
+/** Add one stub AVC keyframe so the always-present video track can finalize. */
+function addStubVideoSample(muxer: Mp4MuxerHandle): void {
+  const avcDescription = new Uint8Array([
+    0x01, 0x64, 0x00, 0x28, 0xff, 0xe1, 0x00, 0x04, 0x67, 0x64, 0x00, 0x28, 0x01, 0x00, 0x04, 0x68,
+    0xee, 0x3c, 0x80,
+  ]);
+  muxer.addVideoChunkRaw(new Uint8Array([0x00, 0x00, 0x00, 0x02, 0x09, 0x10]), 'key', 0, 33_333, {
+    decoderConfig: { codec: 'avc1.640028', description: avcDescription },
+  });
+}
+
+/** Find the ASCII 4CC `needle` anywhere in the MP4 bytes. */
+function containsFourCC(buffer: ArrayBuffer, needle: string): boolean {
+  const bytes = new Uint8Array(buffer);
+  const pat = Array.from(needle, (c) => c.charCodeAt(0));
+  outer: for (let i = 0; i + pat.length <= bytes.length; i++) {
+    for (let j = 0; j < pat.length; j++) {
+      if (bytes[i + j] !== pat[j]) continue outer;
+    }
+    return true;
+  }
+  return false;
+}
+
+describe('createMp4Muxer audio track', () => {
+  it('writes an mp4a sample entry when an audio track is configured', () => {
+    const muxer = createMp4Muxer({
+      width: 320,
+      height: 240,
+      fps: 30,
+      audio: { numberOfChannels: 2, sampleRate: 48_000 },
+    });
+
+    expect(muxer.hasAudioTrack).toBe(true);
+
+    // The video track needs at least one sample to finalize. Feed a raw AVC
+    // sample with a stub decoderConfig (bytes don't need to be a valid stream
+    // for the container-level box check).
+    addStubVideoSample(muxer);
+
+    // Feed one raw AAC sample (contents don't matter for the container check).
+    const sample = new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]);
+    // timestamp/duration are in microseconds.
+    muxer.addAudioChunkRaw(sample, 'key', 0, 1_000_000);
+
+    const mp4 = muxer.finalize();
+    expect(mp4.byteLength).toBeGreaterThan(0);
+    // The AAC audio sample entry box is named 'mp4a'.
+    expect(containsFourCC(mp4, 'mp4a')).toBe(true);
+  });
+
+  it('produces no audio track (no mp4a box) when audio is omitted', () => {
+    const muxer = createMp4Muxer({ width: 320, height: 240, fps: 30 });
+    expect(muxer.hasAudioTrack).toBe(false);
+    addStubVideoSample(muxer);
+    const mp4 = muxer.finalize();
+    expect(containsFourCC(mp4, 'mp4a')).toBe(false);
+  });
+});

package/src/__tests__/videoExportProps.test.tsx

@@ -0,0 +1,73 @@
+/**
+ * Prop-surface tests for the video export components.
+ *
+ * `playerScript` is unused on the browser export path (frames are captured
+ * from a live in-page DocPlayer), so both VideoExportButton and
+ * VideoExportModal must accept being rendered without it.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, renderHook } from '@testing-library/react';
+import { VideoExportButton } from '../VideoExportButton';
+import { VideoExportModal } from '../VideoExportModal';
+import { useVideoExport } from '../hooks/useVideoExport';
+import type { Doc } from '@bendyline/squisq/schemas';
+
+function minimalDoc(): Doc {
+  return {
+    articleId: 'export-test',
+    duration: 5,
+    blocks: [{ id: 'b1', startTime: 0, duration: 5, audioSegment: 0, layers: [] }],
+    audio: { segments: [] },
+  };
+}
+
+describe('VideoExportButton', () => {
+  it('renders without a playerScript prop', () => {
+    const { getByRole } = render(<VideoExportButton doc={minimalDoc()} />);
+    expect(getByRole('button', { name: 'Export Video' })).toBeTruthy();
+  });
+
+  it('accepts a defaultConfig prop', () => {
+    const { getByRole } = render(
+      <VideoExportButton doc={minimalDoc()} defaultConfig={{ quality: 'high', fps: 30 }} />,
+    );
+    expect(getByRole('button', { name: 'Export Video' })).toBeTruthy();
+  });
+});
+
+describe('VideoExportModal', () => {
+  it('renders the configure state without a playerScript prop', () => {
+    const { container } = render(<VideoExportModal doc={minimalDoc()} onClose={() => {}} />);
+    expect(container.textContent).toContain('Export Video');
+  });
+
+  it('seeds the initial selections from defaultConfig', () => {
+    const { container } = render(
+      <VideoExportModal
+        doc={minimalDoc()}
+        defaultConfig={{
+          quality: 'high',
+          fps: 30,
+          orientation: 'portrait',
+          captionMode: 'standard',
+        }}
+        onClose={() => {}}
+      />,
+    );
+    const selects = Array.from(container.querySelectorAll('select')) as HTMLSelectElement[];
+    // Order in the configure form: Quality, Frame Rate, Orientation, Captions.
+    expect(selects[0].value).toBe('high');
+    expect(selects[1].value).toBe('30');
+    expect(selects[2].value).toBe('portrait');
+    expect(selects[3].value).toBe('standard');
+  });
+});
+
+describe('useVideoExport result shape', () => {
+  it('exposes the additive audio result fields, defaulted for idle', () => {
+    const { result } = renderHook(() => useVideoExport());
+    expect(result.current.audioIncluded).toBe(false);
+    expect(result.current.audioSkippedReason).toBeNull();
+  });
+});