@waveform-playlist/recording 12.2.0 → 13.0.1

package/README.md

@@ -1,14 +1,17 @@
 # @waveform-playlist/recording
 
-Audio recording support for waveform-playlist using AudioWorklet.
+Audio recording support for waveform-playlist using AudioWorklet — mic capture, live waveform preview, VU metering, and overdub, as a set of React hooks.
 
 ## Features
 
-- ✅ **AudioWorklet-based recording** - Low latency, direct PCM access
-- ✅ **Real-time waveform visualization** - See the waveform as you record
-- ✅ **React hooks** - Easy integration with React apps
-- ✅ **Device selection** - Choose from available microphone inputs
-- ✅ **Optional package** - Only include if you need recording
+- **AudioWorklet-based capture** — direct PCM access on the audio thread, no `ScriptProcessorNode`
+- **Live waveform preview** — incremental per-channel peaks as you record, before the final `AudioBuffer` exists
+- **Sample-accurate VU metering** — a dedicated meter worklet measures peak/RMS on every sample, not just once per animation frame
+- **Multi-channel recording** — auto-detects the microphone's actual channel count from the `MediaStream`
+- **Overdub with latency compensation** — record against existing playback; the finalized clip's timeline position accounts for output latency and Tone.js scheduling lookahead, with an optional manual override
+- **Device selection & hot-plug** — enumerate microphones, switch devices between takes (refused while actively recording — a mid-recording switch would silently record silence), auto-fallback if the active device disconnects
+- **Pause/resume** — pauses the worklet itself, not just the UI
+- **Hooks only** — no bundled UI components; wire the state into your own controls or `@waveform-playlist/ui-components`'s `SegmentedVUMeter`
 
 ## Installation
 
@@ -16,208 +19,219 @@ Audio recording support for waveform-playlist using AudioWorklet.
 npm install @waveform-playlist/recording
 ```
 
+`@waveform-playlist/recording` requires these peer dependencies:
+
+| Package | Purpose |
+|---------|---------|
+| `react` | ^18.0.0 |
+| `styled-components` | ^6.0.0 — required transitively by `@waveform-playlist/ui-components` |
+| `tone` | ^15.0.0 — recording shares the global AudioContext with `@waveform-playlist/playout` |
+
+Pairs with `@waveform-playlist/browser` — see the [Recording guide](https://naomiaro.github.io/waveform-playlist/docs/react/guides/recording) for a full `WaveformPlaylistProvider` integration.
+
 ## Usage
 
 ### Basic Recording
 
-```typescript
-import { useRecording, useMicrophoneAccess, RecordButton } from '@waveform-playlist/recording';
+```tsx
+import { useMicrophoneAccess, useRecording } from '@waveform-playlist/recording';
 
-function RecordingApp() {
-  const { stream, requestAccess } = useMicrophoneAccess();
-  const { isRecording, startRecording, stopRecording, peaks, duration } = useRecording(stream);
+function RecordButton() {
+  const { stream, hasPermission, requestAccess } = useMicrophoneAccess();
+  const { isRecording, duration, peaks, startRecording, stopRecording } = useRecording(stream);
 
   const handleRecord = async () => {
-    if (!stream) {
+    if (!hasPermission) {
       await requestAccess();
+      return;
     }
 
     if (isRecording) {
       const audioBuffer = await stopRecording();
-      // Use the recorded audio buffer
+      // audioBuffer is the finalized AudioBuffer — add it to a track, upload it, etc.
     } else {
       await startRecording();
     }
   };
 
   return (
-    <div>
-      <RecordButton isRecording={isRecording} onClick={handleRecord} />
-      <p>Duration: {duration.toFixed(1)}s</p>
-      {/* Display waveform using peaks */}
-    </div>
+    <button onClick={handleRecord}>
+      {isRecording ? `Stop (${duration.toFixed(1)}s)` : 'Record'}
+    </button>
   );
 }
 ```
 
-### With Microphone Selection
-
-```typescript
-import {
-  useMicrophoneAccess,
-  useRecording,
-  MicrophoneSelector,
-  RecordButton,
-  RecordingIndicator,
-} from '@waveform-playlist/recording';
-
-function RecordingApp() {
-  const { stream, devices, requestAccess } = useMicrophoneAccess();
-  const { isRecording, duration, startRecording, stopRecording } = useRecording(stream);
-  const [selectedDevice, setSelectedDevice] = useState<string>();
-
-  const handleDeviceChange = async (deviceId: string) => {
-    setSelectedDevice(deviceId);
-    await requestAccess(deviceId);
-  };
+### VU Meter
+
+`useMicrophoneLevel` drives level monitoring independently of recording — useful for an input-check screen before the user hits record.
+
+```tsx
+import { useMicrophoneAccess, useMicrophoneLevel } from '@waveform-playlist/recording';
+import { SegmentedVUMeter } from '@waveform-playlist/ui-components';
+
+function MicMonitor() {
+  const { stream, requestAccess } = useMicrophoneAccess();
+  const { levels, peakLevels } = useMicrophoneLevel(stream, { channelCount: 2 });
 
   return (
-    <div>
-      <MicrophoneSelector
-        devices={devices}
-        selectedDeviceId={selectedDevice}
-        onDeviceChange={handleDeviceChange}
-      />
-      <RecordButton
-        isRecording={isRecording}
-        onClick={isRecording ? stopRecording : startRecording}
-      />
-      <RecordingIndicator isRecording={isRecording} duration={duration} />
-    </div>
+    <>
+      <button onClick={() => requestAccess()}>Enable Microphone</button>
+      <SegmentedVUMeter levels={levels} peakLevels={peakLevels} />
+    </>
   );
 }
 ```
 
-### Integration with WaveformPlaylist
-
-```typescript
-import { WaveformPlaylistProvider, Waveform } from '@waveform-playlist/browser';
-import { useRecording, useMicrophoneAccess } from '@waveform-playlist/recording';
-
-function RecordingPlaylist() {
-  const { stream, requestAccess } = useMicrophoneAccess();
-  const { peaks, audioBuffer, startRecording, stopRecording } = useRecording(stream);
-  const [tracks, setTracks] = useState([]);
-
-  const handleStopRecording = async () => {
-    const buffer = await stopRecording();
-    if (buffer) {
-      // Add recorded track to playlist
-      setTracks([
-        ...tracks,
-        {
-          src: buffer,
-          name: 'Recording',
-        },
-      ]);
-    }
-  };
+### Integrated Recording (with a track list)
+
+`useIntegratedRecording` combines microphone access, metering, and recording into one hook that appends the finalized clip directly to a `ClipTrack[]` — the same array shape used by `@waveform-playlist/browser`'s `WaveformPlaylistProvider`.
+
+```tsx
+import { useIntegratedRecording } from '@waveform-playlist/recording';
+import type { ClipTrack } from '@waveform-playlist/core';
+
+function Recorder({
+  tracks,
+  setTracks,
+  selectedTrackId,
+  currentTime,
+}: {
+  tracks: ClipTrack[];
+  setTracks: (tracks: ClipTrack[]) => void;
+  selectedTrackId: string | null;
+  currentTime: number;
+}) {
+  const {
+    isRecording,
+    duration,
+    levels,
+    peakLevels,
+    devices,
+    selectedDevice,
+    requestMicAccess,
+    changeDevice,
+    startRecording,
+    stopRecording,
+    recordingPeaks, // live per-channel peaks — feed straight into your waveform preview
+    error,
+  } = useIntegratedRecording(tracks, setTracks, selectedTrackId, {
+    currentTime,
+    channelCount: 2,
+  });
 
   return (
-    <WaveformPlaylistProvider tracks={tracks}>
-      <button onClick={requestAccess}>Request Microphone</button>
-      <button onClick={startRecording}>Record</button>
-      <button onClick={handleStopRecording}>Stop</button>
-      <Waveform />
-    </WaveformPlaylistProvider>
+    <div>
+      <button onClick={() => requestMicAccess()}>Enable Microphone</button>
+      <button onClick={isRecording ? stopRecording : startRecording} disabled={!selectedTrackId}>
+        {isRecording ? `Stop (${duration.toFixed(1)}s)` : 'Record'}
+      </button>
+      {error && <p>{error.message}</p>}
+    </div>
   );
 }
 ```
 
+Stopping adds a new `AudioClip` to `selectedTrackId` at the timeline position captured when recording STARTED (punch-in semantics): the take lands exactly at the playhead and REPLACES any existing clip content it overlaps — partial overlaps are trimmed, fully-covered clips removed, and a clip spanning the take is split in two.
+
 ## API Reference
 
 ### Hooks
 
 #### `useMicrophoneAccess()`
 
-Manages microphone access and device enumeration.
+Manages microphone permission, device enumeration, and hot-plug detection.
 
-**Returns:**
-- `stream: MediaStream | null` - Active microphone stream
-- `devices: MicrophoneDevice[]` - Available microphone devices
-- `hasPermission: boolean` - Whether microphone permission is granted
-- `isLoading: boolean` - Loading state during access request
-- `requestAccess: (deviceId?: string) => Promise<void>` - Request microphone access
-- `stopStream: () => void` - Stop the microphone stream
-- `error: Error | null` - Error state
+**Returns (`UseMicrophoneAccessReturn`):**
+- `stream: MediaStream | null`
+- `devices: MicrophoneDevice[]` — `{ deviceId, label, groupId }`
+- `hasPermission: boolean`
+- `isLoading: boolean`
+- `requestAccess: (deviceId?: string, audioConstraints?: MediaTrackConstraints) => Promise<void>`
+- `stopStream: () => void`
+- `error: Error | null`
+
+Requested audio constraints default to `echoCancellation: false`, `noiseSuppression: false`, `autoGainControl: false`, `latency: 0` (raw signal, low latency) — pass `audioConstraints` to override.
 
 #### `useRecording(stream, options?)`
 
-Main recording hook using AudioWorklet.
+The core AudioWorklet-based recording hook.
 
 **Parameters:**
-- `stream: MediaStream | null` - Microphone stream from `useMicrophoneAccess`
+- `stream: MediaStream | null`
 - `options?: RecordingOptions`
-  - `sampleRate?: number` - Sample rate (defaults to AudioContext rate)
-  - `channelCount?: number` - Number of channels (default: 1)
-  - `samplesPerPixel?: number` - Samples per pixel for peaks (default: 1024)
+  - `channelCount?: number` — fallback used only if the stream doesn't report its own channel count (default: `1`)
+  - `samplesPerPixel?: number` — peak resolution for the live preview (default: `1024`)
+  - `bits?: 8 | 16` — peak value bit depth (default: `16`)
+
+**Returns (`UseRecordingReturn`):**
+- `isRecording: boolean`, `isPaused: boolean`, `duration: number` (seconds)
+- `peaks: (Int8Array | Int16Array)[]` — one entry per channel, growing live during recording
+- `audioBuffer: AudioBuffer | null` — set after `stopRecording()` resolves
+- `level: number`, `peakLevel: number` — **deprecated** (always `0`); use `useMicrophoneLevel` for metering. Removed in the next major
+- `startRecording: () => Promise<boolean>` — resolves `true` when the capture pipeline actually started (`false`: no stream, already recording, worklet failure); check it before starting synchronized playback
+- `stopRecording: () => Promise<AudioBuffer | null>` — awaits the worklet's final flush before resolving, so the last samples are never dropped
+- `pauseRecording: () => void`, `resumeRecording: () => void` — pause/resume the worklet itself, not just the UI
+- `error: Error | null`
 
-**Returns:**
-- `isRecording: boolean` - Whether recording is active
-- `isPaused: boolean` - Whether recording is paused
-- `duration: number` - Recording duration in seconds
-- `peaks: number[]` - Peak data for waveform visualization
-- `audioBuffer: AudioBuffer | null` - Final recorded audio buffer
-- `startRecording: () => Promise<void>` - Start recording
-- `stopRecording: () => Promise<AudioBuffer | null>` - Stop and finalize recording
-- `pauseRecording: () => void` - Pause recording
-- `resumeRecording: () => void` - Resume recording
-- `error: Error | null` - Error state
+#### `useMicrophoneLevel(stream, options?)`
 
-### Components
+Sample-accurate VU metering via a separate meter AudioWorklet — independent of `useRecording`, so it works before recording starts.
 
-#### `<RecordButton />`
+**Parameters:**
+- `stream: MediaStream | null`
+- `options?: UseMicrophoneLevelOptions`
+  - `updateRate?: number` — Hz (default: `60`)
+  - `channelCount?: number` (default: `1`)
 
-Button for starting/stopping recording.
+**Returns (`UseMicrophoneLevelReturn`):**
+- `levels: number[]`, `peakLevels: number[]`, `rmsLevels: number[]` — per channel, normalized 0–1
+- `level: number`, `peakLevel: number` — scalar convenience values (max across channels when `channelCount > 1`)
+- `resetPeak: () => void` — clears held peak indicators, e.g. on device switch
+- `error: Error | null`
 
-**Props:**
-- `isRecording: boolean` - Recording state
-- `onClick: () => void` - Click handler
-- `disabled?: boolean` - Disabled state
-- `className?: string` - CSS class name
+#### `useIntegratedRecording(tracks, setTracks, selectedTrackId, options?)`
 
-#### `<MicrophoneSelector />`
+Batteries-included hook: wires `useMicrophoneAccess` + `useMicrophoneLevel` + `useRecording` together and appends the finalized recording to `tracks` as a new `AudioClip`.
 
-Dropdown for selecting microphone device.
+**Parameters:**
+- `tracks: ClipTrack[]`, `setTracks: (tracks: ClipTrack[]) => void`, `selectedTrackId: string | null`
+- `options?: IntegratedRecordingOptions`
+  - `currentTime?: number` — playback/cursor position; the clip is captured at this position at record *start* (not stop), so overdubbing while transport is running lands the clip correctly
+  - `audioConstraints?: MediaTrackConstraints`
+  - `channelCount?: number` (default: `1`)
+  - `samplesPerPixel?: number` (default: `1024`)
+  - `latencyOffset?: number` — seconds; overrides the auto-computed `outputLatency + lookAhead` compensation applied to the clip's start. `0` disables compensation; omit to auto-compute
 
-**Props:**
-- `devices: MicrophoneDevice[]` - Available devices
-- `selectedDeviceId?: string` - Currently selected device
-- `onDeviceChange: (deviceId: string) => void` - Change handler
-- `disabled?: boolean` - Disabled state
-- `className?: string` - CSS class name
+**Returns (`UseIntegratedRecordingReturn`):** recording state (`isRecording`, `isPaused`, `duration`, `level`, `peakLevel`, `levels`, `peakLevels`, `rmsLevels`), microphone state (`stream`, `devices`, `hasPermission`, `selectedDevice`), controls (`startRecording` — resolves `true` when capture actually started, `stopRecording`, `pauseRecording`, `resumeRecording`, `requestMicAccess`, `changeDevice`), `recordingPeaks` (live per-channel peaks for preview), and a combined `error`.
 
-#### `<RecordingIndicator />`
+**Overdub with `@waveform-playlist/browser`:** call `usePlaylistControls().setRecordingActive(true, trackId)` *before* `play()` — while the session is active the end-of-timeline auto-stop is suppressed (the take can run past existing audio) and the recorded-over track's existing content is transiently muted (punch-in replaces it). Both reset automatically when the recording ends; check `startRecording()`'s boolean and release the session on `false`.
 
-Visual indicator showing recording status and duration.
+### Types
 
-**Props:**
-- `isRecording: boolean` - Recording state
-- `isPaused?: boolean` - Paused state
-- `duration: number` - Duration in seconds
-- `formatTime?: (seconds: number) => string` - Custom time formatter
-- `className?: string` - CSS class name
+`RecordingState`, `RecordingData`, `MicrophoneDevice`, `RecordingOptions`, `UseRecordingReturn`, `UseMicrophoneAccessReturn` are all exported from the package root for consumers building their own UI around these hooks.
 
 ## Architecture
 
-The recording implementation uses AudioWorklet for low-latency audio capture:
-
 ```
 getUserMedia → MediaStream
                     ↓
-        MediaStreamSource (Web Audio)
+   MediaStreamSource (shared global AudioContext)
                     ↓
-          AudioWorklet Processor
-          (captures raw PCM data)
+    AudioWorklet Processors (from @waveform-playlist/worklets)
+    - recording-processor: captures raw PCM per channel
+    - meter-processor: sample-accurate peak/RMS
                     ↓
-        Main Thread (React Hook)
-          - Accumulates audio data
-          - Generates peaks in real-time
-          - Updates waveform visualization
+        Main Thread (React Hooks)
+          - Accumulates audio data per channel
+          - Generates live peaks incrementally
+          - Updates VU meter state
                     ↓
-         Final AudioBuffer
+   Final AudioBuffer (after stopRecording's stop-handshake)
 ```
 
+Each hook creates its own `MediaStreamSource` from the shared context rather than reusing one across hooks — required for Firefox, which throws if source and destination nodes come from different context instances.
+
 ## Browser Support
 
 - Chrome 66+

package/dist/index.d.mts

@@ -55,9 +55,22 @@ interface UseRecordingReturn {
     duration: number;
     peaks: (Int8Array | Int16Array)[];
     audioBuffer: AudioBuffer | null;
+    /**
+     * @deprecated Always 0 — VU levels come from `useMicrophoneLevel`
+     * (meter-processor worklet), not this hook. Will be removed in the next
+     * major version.
+     */
     level: number;
+    /**
+     * @deprecated Always 0 — use `useMicrophoneLevel`'s `peakLevel` instead.
+     * Will be removed in the next major version.
+     */
     peakLevel: number;
-    startRecording: () => Promise<void>;
+    /** Start capturing. Resolves `true` when the capture pipeline actually
+     *  started, `false` when it could not (no stream, already recording,
+     *  worklet/module failure, unmounted). Callers that synchronize playback
+     *  with recording should check the result before starting playback. */
+    startRecording: () => Promise<boolean>;
     stopRecording: () => Promise<AudioBuffer | null>;
     pauseRecording: () => void;
     resumeRecording: () => void;
@@ -121,16 +134,19 @@ interface UseMicrophoneLevelReturn {
      */
     resetPeak: () => void;
     /**
-     * Per-channel peak levels (0-1). Array length matches channelCount.
+     * Per-channel peak levels (0-1). Array length matches the metered channel
+     * count: the mic's auto-detected channels, with mono mirrored up to the
+     * requested `channelCount`. A mic with MORE channels than `channelCount`
+     * yields one entry per actual channel.
      * True peak: max absolute sample value per analysis frame.
      */
     levels: number[];
     /**
-     * Per-channel held peak levels (0-1). Array length matches channelCount.
+     * Per-channel held peak levels (0-1). Same length contract as `levels`.
      */
     peakLevels: number[];
     /**
-     * Per-channel RMS levels (0-1). Array length matches channelCount.
+     * Per-channel RMS levels (0-1). Same length contract as `levels`.
      * RMS: root mean square of samples per analysis frame.
      */
     rmsLevels: number[];
@@ -164,8 +180,10 @@ declare function useMicrophoneLevel(stream: MediaStream | null, options?: UseMic
 
 interface IntegratedRecordingOptions {
     /**
-     * Current playback/cursor position in seconds
-     * Recording will start from max(currentTime, lastClipEndTime)
+     * Current playback/cursor position in seconds.
+     * Punch-in semantics (#579): the recorded clip lands exactly at this
+     * position and REPLACES any existing clip content it overlaps — partial
+     * overlaps are trimmed, fully-covered clips removed, spanning clips split.
      */
     currentTime?: number;
     /**
@@ -199,18 +217,25 @@ interface UseIntegratedRecordingReturn {
     duration: number;
     level: number;
     peakLevel: number;
-    /** Per-channel peak levels (0-1). Array length matches channelCount. */
+    /**
+     * Per-channel peak levels (0-1). Array length matches the metered channel
+     * count (auto-detected mic channels; mono mirrored up to channelCount —
+     * see UseMicrophoneLevelReturn.levels).
+     */
     levels: number[];
-    /** Per-channel held peak levels (0-1). Array length matches channelCount. */
+    /** Per-channel held peak levels (0-1). Same length contract as `levels`. */
     peakLevels: number[];
-    /** Per-channel RMS levels (0-1). Array length matches channelCount. */
+    /** Per-channel RMS levels (0-1). Same length contract as `levels`. */
     rmsLevels: number[];
     error: Error | null;
     stream: MediaStream | null;
     devices: MicrophoneDevice[];
     hasPermission: boolean;
     selectedDevice: string | null;
-    startRecording: () => void;
+    /** Start capturing on the selected track. Resolves `true` when the capture
+     *  pipeline actually started — callers that synchronize playback with
+     *  recording (overdub) should check this before starting playback. */
+    startRecording: () => Promise<boolean>;
     stopRecording: () => void;
     pauseRecording: () => void;
     resumeRecording: () => void;

package/dist/index.d.ts

@@ -55,9 +55,22 @@ interface UseRecordingReturn {
     duration: number;
     peaks: (Int8Array | Int16Array)[];
     audioBuffer: AudioBuffer | null;
+    /**
+     * @deprecated Always 0 — VU levels come from `useMicrophoneLevel`
+     * (meter-processor worklet), not this hook. Will be removed in the next
+     * major version.
+     */
     level: number;
+    /**
+     * @deprecated Always 0 — use `useMicrophoneLevel`'s `peakLevel` instead.
+     * Will be removed in the next major version.
+     */
     peakLevel: number;
-    startRecording: () => Promise<void>;
+    /** Start capturing. Resolves `true` when the capture pipeline actually
+     *  started, `false` when it could not (no stream, already recording,
+     *  worklet/module failure, unmounted). Callers that synchronize playback
+     *  with recording should check the result before starting playback. */
+    startRecording: () => Promise<boolean>;
     stopRecording: () => Promise<AudioBuffer | null>;
     pauseRecording: () => void;
     resumeRecording: () => void;
@@ -121,16 +134,19 @@ interface UseMicrophoneLevelReturn {
      */
     resetPeak: () => void;
     /**
-     * Per-channel peak levels (0-1). Array length matches channelCount.
+     * Per-channel peak levels (0-1). Array length matches the metered channel
+     * count: the mic's auto-detected channels, with mono mirrored up to the
+     * requested `channelCount`. A mic with MORE channels than `channelCount`
+     * yields one entry per actual channel.
      * True peak: max absolute sample value per analysis frame.
      */
     levels: number[];
     /**
-     * Per-channel held peak levels (0-1). Array length matches channelCount.
+     * Per-channel held peak levels (0-1). Same length contract as `levels`.
      */
     peakLevels: number[];
     /**
-     * Per-channel RMS levels (0-1). Array length matches channelCount.
+     * Per-channel RMS levels (0-1). Same length contract as `levels`.
      * RMS: root mean square of samples per analysis frame.
      */
     rmsLevels: number[];
@@ -164,8 +180,10 @@ declare function useMicrophoneLevel(stream: MediaStream | null, options?: UseMic
 
 interface IntegratedRecordingOptions {
     /**
-     * Current playback/cursor position in seconds
-     * Recording will start from max(currentTime, lastClipEndTime)
+     * Current playback/cursor position in seconds.
+     * Punch-in semantics (#579): the recorded clip lands exactly at this
+     * position and REPLACES any existing clip content it overlaps — partial
+     * overlaps are trimmed, fully-covered clips removed, spanning clips split.
      */
     currentTime?: number;
     /**
@@ -199,18 +217,25 @@ interface UseIntegratedRecordingReturn {
     duration: number;
     level: number;
     peakLevel: number;
-    /** Per-channel peak levels (0-1). Array length matches channelCount. */
+    /**
+     * Per-channel peak levels (0-1). Array length matches the metered channel
+     * count (auto-detected mic channels; mono mirrored up to channelCount —
+     * see UseMicrophoneLevelReturn.levels).
+     */
     levels: number[];
-    /** Per-channel held peak levels (0-1). Array length matches channelCount. */
+    /** Per-channel held peak levels (0-1). Same length contract as `levels`. */
     peakLevels: number[];
-    /** Per-channel RMS levels (0-1). Array length matches channelCount. */
+    /** Per-channel RMS levels (0-1). Same length contract as `levels`. */
     rmsLevels: number[];
     error: Error | null;
     stream: MediaStream | null;
     devices: MicrophoneDevice[];
     hasPermission: boolean;
     selectedDevice: string | null;
-    startRecording: () => void;
+    /** Start capturing on the selected track. Resolves `true` when the capture
+     *  pipeline actually started — callers that synchronize playback with
+     *  recording (overdub) should check this before starting playback. */
+    startRecording: () => Promise<boolean>;
     stopRecording: () => void;
     pauseRecording: () => void;
     resumeRecording: () => void;