@bendyline/squisq-editor-react 1.4.0 → 1.5.1

package/src/recorder/formats.ts

@@ -0,0 +1,159 @@
+/**
+ * Format probing for MediaRecorder.
+ *
+ * Different browsers expose different container/codec combinations. Chrome
+ * and Firefox produce WebM (VP8/VP9 + Opus); Safari produces MP4 (H.264 +
+ * AAC). We probe at runtime via `MediaRecorder.isTypeSupported()` and pick
+ * the best supported option, falling back to whatever the browser hands
+ * back when no probe succeeds.
+ */
+
+/** What the recorded stream is intended to capture. */
+export type CaptureKind = 'audio' | 'video';
+
+/** A probed format choice — what to pass to `MediaRecorder` and where to write it. */
+export interface ResolvedFormat {
+  /** MIME type to pass to `new MediaRecorder(stream, { mimeType })`. Empty string means "let the browser pick". */
+  mimeType: string;
+  /** File extension to use when writing to the container, including the leading dot. */
+  extension: string;
+  /** Container directory inside the `ContentContainer` (no trailing slash). */
+  directory: 'audio' | 'video';
+}
+
+/**
+ * Preferred MIME types for audio-only recording, in priority order. The
+ * first one `MediaRecorder.isTypeSupported()` accepts wins.
+ *
+ * Opus in a WebM container is the modern default (Chrome, Firefox, Edge).
+ * MP4/AAC covers Safari. Bare strings are kept as a final fallback for
+ * older browsers that don't accept codec hints.
+ */
+const AUDIO_CANDIDATES = [
+  'audio/webm;codecs=opus',
+  'audio/webm',
+  'audio/mp4;codecs=mp4a.40.2',
+  'audio/mp4',
+  'audio/ogg;codecs=opus',
+];
+
+/**
+ * Preferred MIME types for video recording. VP9/Opus on top because it
+ * yields good quality at modest bitrate in Chrome/Firefox. VP8 follows for
+ * older Chromium. MP4/H.264 covers Safari.
+ */
+const VIDEO_CANDIDATES = [
+  'video/webm;codecs=vp9,opus',
+  'video/webm;codecs=vp8,opus',
+  'video/webm',
+  'video/mp4;codecs=avc1.42E01E,mp4a.40.2',
+  'video/mp4',
+];
+
+/**
+ * Map a chosen MIME type to a file extension. Best-effort — if we can't
+ * tell, default to `.bin` so the file is at least retrievable.
+ */
+function extensionForMime(mimeType: string): string {
+  const m = mimeType.toLowerCase();
+  if (m.startsWith('audio/webm')) return '.webm';
+  if (m.startsWith('audio/ogg')) return '.ogg';
+  if (m.startsWith('audio/mp4')) return '.m4a';
+  if (m.startsWith('audio/mpeg')) return '.mp3';
+  if (m.startsWith('audio/wav')) return '.wav';
+  if (m.startsWith('video/webm')) return '.webm';
+  if (m.startsWith('video/mp4')) return '.mp4';
+  return '.bin';
+}
+
+/**
+ * Probe `MediaRecorder.isTypeSupported()` and return the first supported
+ * MIME type from the candidate list. Returns `null` when the
+ * MediaRecorder API itself is unavailable or none of the candidates pass.
+ */
+function probeMimeType(candidates: readonly string[]): string | null {
+  if (typeof MediaRecorder === 'undefined') return null;
+  for (const candidate of candidates) {
+    try {
+      if (MediaRecorder.isTypeSupported(candidate)) return candidate;
+    } catch {
+      // isTypeSupported isn't supposed to throw, but Safari has historically
+      // misbehaved on unknown codec strings. Keep probing.
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the format the recorder will use for a given capture kind. If a
+ * `preferred` MIME type is supported, it wins; otherwise we fall through
+ * the priority list. When nothing matches (extremely old browser), we
+ * return an empty `mimeType` — `MediaRecorder` will pick a default and we
+ * tag the file with `.webm` as a best guess.
+ */
+export function resolveFormat(kind: CaptureKind, preferred?: string): ResolvedFormat {
+  const candidates = kind === 'audio' ? AUDIO_CANDIDATES : VIDEO_CANDIDATES;
+  const probed = (preferred && probeMimeType([preferred])) ?? probeMimeType(candidates) ?? '';
+  const directory = kind === 'audio' ? 'audio' : 'video';
+  const extension = probed ? extensionForMime(probed) : '.webm';
+  return { mimeType: probed, extension, directory };
+}
+
+/**
+ * `MediaRecorder` support probe. Returns false when running in a
+ * non-browser environment (e.g. SSR) or on a browser that doesn't
+ * implement the API at all.
+ */
+export function supportsMediaRecorder(): boolean {
+  return typeof MediaRecorder !== 'undefined';
+}
+
+/**
+ * `getUserMedia` support probe (for mic / camera capture).
+ */
+export function supportsUserMedia(): boolean {
+  return (
+    typeof navigator !== 'undefined' &&
+    typeof navigator.mediaDevices !== 'undefined' &&
+    typeof navigator.mediaDevices.getUserMedia === 'function'
+  );
+}
+
+/**
+ * `getDisplayMedia` support probe (for screen capture). Browsers may
+ * implement `mediaDevices` without `getDisplayMedia` (Firefox on Android
+ * being the long-standing example), so this is its own probe.
+ */
+export function supportsDisplayMedia(): boolean {
+  return (
+    typeof navigator !== 'undefined' &&
+    typeof navigator.mediaDevices !== 'undefined' &&
+    typeof navigator.mediaDevices.getDisplayMedia === 'function'
+  );
+}
+
+/**
+ * Build a default filename for a recording. `basename` is a hint
+ * (e.g. user-typed name); when omitted, a sortable timestamp is used so
+ * concurrent recordings don't collide.
+ */
+export function buildFilename(kind: CaptureKind, extension: string, basename?: string): string {
+  const safe = basename
+    ? basename
+        .trim()
+        .replace(/[\\/:*?"<>|]+/g, '-')
+        .replace(/\s+/g, '-')
+    : '';
+  if (safe) return `${safe}${extension}`;
+  const now = new Date();
+  const stamp =
+    now.getFullYear().toString().padStart(4, '0') +
+    (now.getMonth() + 1).toString().padStart(2, '0') +
+    now.getDate().toString().padStart(2, '0') +
+    '-' +
+    now.getHours().toString().padStart(2, '0') +
+    now.getMinutes().toString().padStart(2, '0') +
+    now.getSeconds().toString().padStart(2, '0');
+  const prefix = kind === 'audio' ? 'narration' : 'recording';
+  return `${prefix}-${stamp}${extension}`;
+}

package/src/recorder/hooks/useMediaRecorder.ts

@@ -0,0 +1,378 @@
+/**
+ * useMediaRecorder
+ *
+ * React wrapper around `MediaRecorder` that handles stream acquisition,
+ * the recorder lifecycle, and produces a single `Blob` on stop. Selects
+ * a browser-supported MIME type via {@link resolveFormat}.
+ *
+ * Mirrors the shape of `useVideoExport` in `@bendyline/squisq-video-react`
+ * (request → start → stop → blob), inverted for capture rather than
+ * export.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  resolveFormat,
+  supportsMediaRecorder,
+  type CaptureKind,
+  type ResolvedFormat,
+} from '../formats.js';
+import { requestMicStream } from '../sources/micStream.js';
+import { requestCameraStream } from '../sources/cameraStream.js';
+import { requestScreenStream, type ScreenStreamHandle } from '../sources/screenStream.js';
+
+/** Which capture source to use. `screen+mic` mixes the microphone into the screen stream. */
+export type RecorderSource = 'mic' | 'camera' | 'screen' | 'screen+mic';
+
+/** Discriminated state describing what the recorder is currently doing. */
+export type RecorderState =
+  | 'idle'
+  | 'requesting'
+  | 'ready'
+  | 'recording'
+  | 'stopping'
+  | 'stopped'
+  | 'error';
+
+export interface UseMediaRecorderOptions {
+  /** Which capture pipeline to use. */
+  source: RecorderSource;
+  /**
+   * Preferred MIME type override. When the browser supports it, this
+   * wins over the default candidate list. When unset (or unsupported),
+   * the hook probes a built-in priority list.
+   */
+  mimeType?: string;
+  /** Video track constraints for camera / screen sources. */
+  videoConstraints?: MediaTrackConstraints | boolean;
+  /** Audio track constraints for mic / camera / screen+mic sources. */
+  audioConstraints?: MediaTrackConstraints | boolean;
+  /**
+   * Bits-per-second hint passed to `MediaRecorder`. Most browsers cap to
+   * reasonable defaults internally; leaving this undefined is usually
+   * fine.
+   */
+  bitsPerSecond?: number;
+  /**
+   * Whether to attempt to capture system audio when `source === 'screen'`
+   * or `'screen+mic'`. Browser support is limited (desktop Chromium
+   * only); when unsupported the resulting stream simply omits it.
+   */
+  systemAudio?: boolean;
+}
+
+export interface UseMediaRecorderResult {
+  /** Current recorder state. */
+  state: RecorderState;
+  /** Live `MediaStream` after `request()` succeeds; useful for preview. */
+  stream: MediaStream | null;
+  /** Final `Blob` after `stop()` resolves, or `null` while recording. */
+  blob: Blob | null;
+  /** MIME type the recorder actually used (after `request()`). */
+  mimeType: string | null;
+  /** File extension matching `mimeType` (e.g. `.webm`). */
+  extension: string | null;
+  /** Suggested container directory (`'audio'` for mic, `'video'` for camera/screen). */
+  directory: 'audio' | 'video' | null;
+  /** Milliseconds elapsed since `start()` was called. Updates ~10× per second while recording. */
+  durationMs: number;
+  /** Most recent error, if any. */
+  error: Error | null;
+  /**
+   * Acquire the stream and prepare a `MediaRecorder`. After this resolves
+   * the hook is in `'ready'` state and a `<video>`/`<audio>` element can
+   * preview `stream`. Call `start()` to begin recording.
+   */
+  request: () => Promise<void>;
+  /** Start recording. Must be called from `'ready'`. */
+  start: () => void;
+  /**
+   * Stop recording and resolve with the resulting `Blob`. Safe to call
+   * from `'recording'`; a no-op from any other state (resolves with the
+   * existing `blob`, or `null`).
+   */
+  stop: () => Promise<Blob | null>;
+  /**
+   * Tear everything down — stops the recorder if running, releases all
+   * tracks, disposes the AudioContext mixer (if any), and returns to
+   * `'idle'`. Always safe to call.
+   */
+  cancel: () => void;
+  /** Reset state without releasing the stream. Useful for re-recording. */
+  reset: () => void;
+}
+
+/**
+ * Acquire the right stream for the chosen source. Returns the stream
+ * plus an optional `dispose` callback for sources that own auxiliary
+ * resources (e.g. the screen+mic AudioContext mixer).
+ */
+async function acquireStream(
+  opts: UseMediaRecorderOptions,
+): Promise<{ stream: MediaStream; dispose: () => void }> {
+  switch (opts.source) {
+    case 'mic': {
+      const audio = typeof opts.audioConstraints === 'object' ? opts.audioConstraints : undefined;
+      const stream = await requestMicStream(audio);
+      return { stream, dispose: () => {} };
+    }
+    case 'camera': {
+      const stream = await requestCameraStream({
+        video: opts.videoConstraints ?? true,
+        audio: opts.audioConstraints ?? true,
+      });
+      return { stream, dispose: () => {} };
+    }
+    case 'screen':
+    case 'screen+mic': {
+      const handle: ScreenStreamHandle = await requestScreenStream({
+        video: opts.videoConstraints ?? true,
+        systemAudio: opts.systemAudio ?? false,
+        includeMicrophone: opts.source === 'screen+mic',
+        microphoneConstraints:
+          typeof opts.audioConstraints === 'object' ? opts.audioConstraints : undefined,
+      });
+      return { stream: handle.stream, dispose: handle.dispose };
+    }
+  }
+}
+
+/** Whether the chosen source records video (vs. audio-only). */
+function captureKindFor(source: RecorderSource): CaptureKind {
+  return source === 'mic' ? 'audio' : 'video';
+}
+
+/**
+ * Returns the kind of capture that the given source produces. Exposed
+ * separately from {@link useMediaRecorder} so non-React callers
+ * (e.g. headless tests) can resolve a format up front.
+ */
+export function getCaptureKind(source: RecorderSource): CaptureKind {
+  return captureKindFor(source);
+}
+
+export function useMediaRecorder(options: UseMediaRecorderOptions): UseMediaRecorderResult {
+  const [state, setState] = useState<RecorderState>('idle');
+  const [stream, setStream] = useState<MediaStream | null>(null);
+  const [blob, setBlob] = useState<Blob | null>(null);
+  const [format, setFormat] = useState<ResolvedFormat | null>(null);
+  const [durationMs, setDurationMs] = useState(0);
+  const [error, setError] = useState<Error | null>(null);
+
+  const recorderRef = useRef<MediaRecorder | null>(null);
+  const chunksRef = useRef<Blob[]>([]);
+  const disposeStreamRef = useRef<(() => void) | null>(null);
+  const startTimestampRef = useRef<number | null>(null);
+  const tickerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const stopResolversRef = useRef<Array<(blob: Blob | null) => void>>([]);
+
+  // Stable copy of options for callbacks that read them late. Re-evaluated
+  // each render, but each callback closes over the ref so we don't have
+  // to recreate them on every options change.
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const clearTicker = useCallback(() => {
+    if (tickerRef.current !== null) {
+      clearInterval(tickerRef.current);
+      tickerRef.current = null;
+    }
+  }, []);
+
+  const releaseStream = useCallback(() => {
+    const s = recorderRef.current?.stream;
+    if (s) {
+      s.getTracks().forEach((t) => t.stop());
+    }
+    // Also stop whatever we last handed to setStream — it may differ
+    // from recorderRef.current.stream when stream/recorder lifecycles
+    // diverged (e.g. cancel before start).
+    setStream((current) => {
+      current?.getTracks().forEach((t) => t.stop());
+      return null;
+    });
+    disposeStreamRef.current?.();
+    disposeStreamRef.current = null;
+  }, []);
+
+  const reset = useCallback(() => {
+    setBlob(null);
+    setDurationMs(0);
+    setError(null);
+    chunksRef.current = [];
+    startTimestampRef.current = null;
+    clearTicker();
+    // If a stream is still live from a prior `request()`, hop back to
+    // `'ready'` so the UI can offer "record again" without the caller
+    // having to re-acquire permissions. Otherwise drop to `'idle'`.
+    const rec = recorderRef.current;
+    if (rec && rec.state === 'inactive' && rec.stream.active) {
+      setState('ready');
+    } else {
+      setState('idle');
+    }
+  }, [clearTicker]);
+
+  const cancel = useCallback(() => {
+    const rec = recorderRef.current;
+    if (rec && rec.state !== 'inactive') {
+      try {
+        rec.stop();
+      } catch {
+        // Ignore — we're tearing down anyway.
+      }
+    }
+    recorderRef.current = null;
+    releaseStream();
+    clearTicker();
+    chunksRef.current = [];
+    startTimestampRef.current = null;
+    // Any in-flight stop() promises won't get a blob.
+    stopResolversRef.current.splice(0).forEach((resolve) => resolve(null));
+    setBlob(null);
+    setDurationMs(0);
+    setError(null);
+    setState('idle');
+  }, [clearTicker, releaseStream]);
+
+  const request = useCallback(async () => {
+    if (!supportsMediaRecorder()) {
+      const err = new Error('MediaRecorder is not supported in this environment.');
+      setError(err);
+      setState('error');
+      throw err;
+    }
+    if (state === 'recording' || state === 'stopping') {
+      // Don't start a parallel acquisition while one is in flight.
+      return;
+    }
+    setError(null);
+    setState('requesting');
+    try {
+      const { stream: nextStream, dispose } = await acquireStream(optionsRef.current);
+      const resolved = resolveFormat(
+        captureKindFor(optionsRef.current.source),
+        optionsRef.current.mimeType,
+      );
+      const recorderOptions: MediaRecorderOptions = {};
+      if (resolved.mimeType) recorderOptions.mimeType = resolved.mimeType;
+      if (optionsRef.current.bitsPerSecond) {
+        recorderOptions.bitsPerSecond = optionsRef.current.bitsPerSecond;
+      }
+      const recorder = new MediaRecorder(nextStream, recorderOptions);
+
+      recorder.ondataavailable = (e) => {
+        if (e.data && e.data.size > 0) chunksRef.current.push(e.data);
+      };
+      recorder.onstop = () => {
+        // The recorded MIME type is authoritative once data is in hand —
+        // some browsers down-negotiate the format (e.g. drop codec hint).
+        const recordedType = recorder.mimeType || resolved.mimeType || 'application/octet-stream';
+        const finalBlob = new Blob(chunksRef.current, { type: recordedType });
+        chunksRef.current = [];
+        setBlob(finalBlob);
+        setState('stopped');
+        clearTicker();
+        stopResolversRef.current.splice(0).forEach((resolve) => resolve(finalBlob));
+      };
+      recorder.onerror = (event) => {
+        const detail = (event as unknown as { error?: DOMException }).error;
+        const err = detail instanceof Error ? detail : new Error('Recorder error');
+        setError(err);
+        setState('error');
+        clearTicker();
+        stopResolversRef.current.splice(0).forEach((resolve) => resolve(null));
+      };
+
+      recorderRef.current = recorder;
+      disposeStreamRef.current = dispose;
+      setStream(nextStream);
+      setFormat(resolved);
+      setBlob(null);
+      setDurationMs(0);
+      setState('ready');
+    } catch (err: unknown) {
+      const normalized = err instanceof Error ? err : new Error('Stream acquisition failed');
+      setError(normalized);
+      setState('error');
+      throw normalized;
+    }
+  }, [state, clearTicker]);
+
+  const start = useCallback(() => {
+    const rec = recorderRef.current;
+    if (!rec) {
+      const err = new Error('Recorder is not ready. Call request() first.');
+      setError(err);
+      setState('error');
+      return;
+    }
+    if (rec.state === 'recording') return;
+    chunksRef.current = [];
+    setBlob(null);
+    setDurationMs(0);
+    startTimestampRef.current = Date.now();
+    rec.start(1000);
+    setState('recording');
+    clearTicker();
+    tickerRef.current = setInterval(() => {
+      if (startTimestampRef.current !== null) {
+        setDurationMs(Date.now() - startTimestampRef.current);
+      }
+    }, 100);
+  }, [clearTicker]);
+
+  const stop = useCallback((): Promise<Blob | null> => {
+    const rec = recorderRef.current;
+    if (!rec || rec.state === 'inactive') {
+      return Promise.resolve(blob);
+    }
+    setState('stopping');
+    return new Promise<Blob | null>((resolve) => {
+      stopResolversRef.current.push(resolve);
+      try {
+        rec.stop();
+      } catch (err: unknown) {
+        const normalized = err instanceof Error ? err : new Error('Failed to stop recorder');
+        setError(normalized);
+        setState('error');
+        clearTicker();
+        stopResolversRef.current.splice(0).forEach((r) => r(null));
+      }
+    });
+  }, [blob, clearTicker]);
+
+  // Final unmount cleanup — make sure we don't leak the camera light /
+  // screen-capture indicator if the component disappears mid-recording.
+  useEffect(() => {
+    return () => {
+      const rec = recorderRef.current;
+      if (rec && rec.state !== 'inactive') {
+        try {
+          rec.stop();
+        } catch {
+          // ignore
+        }
+      }
+      releaseStream();
+      clearTicker();
+      stopResolversRef.current.splice(0).forEach((resolve) => resolve(null));
+    };
+  }, [releaseStream, clearTicker]);
+
+  return {
+    state,
+    stream,
+    blob,
+    mimeType: format?.mimeType ?? null,
+    extension: format?.extension ?? null,
+    directory: format?.directory ?? null,
+    durationMs,
+    error,
+    request,
+    start,
+    stop,
+    cancel,
+    reset,
+  };
+}

package/src/recorder/hooks/useStreamPreview.ts

@@ -0,0 +1,47 @@
+/**
+ * useStreamPreview — binds a `MediaStream` to a `<video>` element's
+ * `srcObject`. Decouples the preview surface from `useMediaRecorder`,
+ * letting hosts compose the preview element however they like.
+ */
+
+import { useEffect, type RefObject } from 'react';
+
+/**
+ * Assign `stream` to `<video>.srcObject` whenever either changes; clears
+ * it on unmount or when `stream` is `null`. The element is set to
+ * `playsInline` + `muted` automatically because previewing your own
+ * microphone with audio playthrough creates a feedback loop.
+ *
+ * @example
+ * ```tsx
+ * const videoRef = useRef<HTMLVideoElement>(null);
+ * const { stream } = useMediaRecorder({ source: 'camera' });
+ * useStreamPreview(videoRef, stream);
+ * return <video ref={videoRef} autoPlay />;
+ * ```
+ */
+export function useStreamPreview(
+  ref: RefObject<HTMLVideoElement | null>,
+  stream: MediaStream | null,
+): void {
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    el.muted = true;
+    el.playsInline = true;
+    el.srcObject = stream;
+    if (stream) {
+      // Some browsers don't auto-play on srcObject assignment; trigger
+      // it explicitly and ignore the inevitable "user gesture required"
+      // rejections — the preview will play on the next interaction.
+      void el.play().catch(() => {});
+    }
+    return () => {
+      // Only detach when this effect is tearing down. Don't stop tracks
+      // — that's the recorder's responsibility.
+      if (el.srcObject === stream) {
+        el.srcObject = null;
+      }
+    };
+  }, [ref, stream]);
+}

package/src/recorder/sources/cameraStream.ts

@@ -0,0 +1,32 @@
+/**
+ * Camera + microphone capture via `getUserMedia({ video, audio })`.
+ */
+
+import { supportsUserMedia } from '../formats.js';
+
+export interface CameraStreamOptions {
+  /** Video track constraints (resolution, facing mode, frame rate). Pass `true` for browser default, or `false` to omit video. */
+  video?: boolean | MediaTrackConstraints;
+  /** Audio track constraints. Pass `true` for browser default, or `false` to omit audio. */
+  audio?: boolean | MediaTrackConstraints;
+}
+
+/**
+ * Request a camera + mic `MediaStream`. Caller owns the stream and must
+ * stop its tracks when done.
+ *
+ * Both tracks are requested by default. To capture video only, pass
+ * `audio: false`; to capture audio only use {@link requestMicStream}
+ * instead.
+ *
+ * @throws When `mediaDevices` is unavailable, or when the user denies
+ *   permission.
+ */
+export async function requestCameraStream(options?: CameraStreamOptions): Promise<MediaStream> {
+  if (!supportsUserMedia()) {
+    throw new Error('navigator.mediaDevices.getUserMedia is not available in this environment.');
+  }
+  const video = options?.video ?? true;
+  const audio = options?.audio ?? true;
+  return navigator.mediaDevices.getUserMedia({ video, audio });
+}

package/src/recorder/sources/micStream.ts

@@ -0,0 +1,25 @@
+/**
+ * Microphone-only capture via `getUserMedia({ audio: true })`.
+ */
+
+import { supportsUserMedia } from '../formats.js';
+
+/**
+ * Request a microphone-only `MediaStream`. Caller owns the stream and
+ * must stop its tracks when done.
+ *
+ * @param constraints - Optional audio constraints (sample rate, device
+ *   id, echo cancellation, etc.). Defaults to `true` — let the browser
+ *   pick.
+ * @throws When `mediaDevices` is unavailable, or when the user denies
+ *   permission (the underlying `getUserMedia` rejection propagates).
+ */
+export async function requestMicStream(constraints?: MediaTrackConstraints): Promise<MediaStream> {
+  if (!supportsUserMedia()) {
+    throw new Error('navigator.mediaDevices.getUserMedia is not available in this environment.');
+  }
+  return navigator.mediaDevices.getUserMedia({
+    audio: constraints ?? true,
+    video: false,
+  });
+}