@waveform-playlist/browser 15.2.0 → 15.3.0

package/README.md

@@ -0,0 +1,104 @@
+# @waveform-playlist/browser
+
+React components, hooks, and context providers for building a multitrack Web Audio editor and player — canvas waveform rendering, clip-based editing, and playback controls on top of Tone.js or a native `HTMLAudioElement`.
+
+## Features
+
+- **Multitrack editor** — `<Waveform />` renders canvas waveforms, per-track controls (mute/solo/volume/pan), a time ruler, and a playhead for any number of tracks
+- **Clip-based editing** — drag-to-move, boundary trimming with collision detection, splitting at the playhead, snap-to-grid (beats/bars or timescale), undo/redo
+- **Split context providers** — `WaveformPlaylistProvider` (multitrack, Tone.js-backed) and `MediaElementPlaylistProvider` (single-track, `<audio>`-backed with pitch-preserving playback rate)
+- **Four focused context hooks** — `usePlaybackAnimation`, `usePlaylistState`, `usePlaylistControls`, `usePlaylistData` isolate 60fps playhead updates from low-frequency state so unrelated components don't re-render on every animation frame
+- **Audio effects** — 20 Tone.js effects (reverb, delay, modulation, filter, distortion, dynamics, spatial) with runtime parameter control, master and per-track chains, plus WAM 2.0 plugin hosting
+- **Recording** — pairs with `@waveform-playlist/recording` for mic input, overdubbing, and live waveform preview; punch-in takes replace overlapped content, and `setRecordingActive(active, armedTrackId)` suppresses the end-of-timeline auto-stop and transiently mutes the recorded-over track for the session
+- **Annotations & spectrogram** — optional integration contexts for `@waveform-playlist/annotations` and `@waveform-playlist/spectrogram`
+- **WAV export** — render the full mix (including effects) offline to a downloadable WAV file
+- **MediaElement player mode** — a lightweight single-track player with pitch-preserving speed control, for podcast/audiobook-style use cases that don't need multitrack mixing
+
+## Installation
+
+```bash
+npm install @waveform-playlist/browser tone @dnd-kit/react
+```
+
+`@waveform-playlist/browser` requires these peer dependencies:
+
+| Package | Purpose |
+|---------|---------|
+| `react` / `react-dom` | ^18.0.0 or ^19.0.0 |
+| `styled-components` | ^6.0.0 — CSS-in-JS styling |
+| `tone` | ^15.0.0 — Web Audio engine (optional if you supply your own `PlayoutAdapter`) |
+| `@dnd-kit/react` | ^0.3.0 — drag-and-drop (includes `@dnd-kit/dom` and `@dnd-kit/abstract`) |
+| `@waveform-playlist/playout` | Tone.js playout engine (optional peer, dynamically imported by default) |
+| `@waveform-playlist/media-element-playout` | engine for `MediaElementPlaylistProvider` (optional peer) |
+| `@waveform-playlist/annotations` / `@waveform-playlist/recording` / `@dawcore/wam` | optional, install only if you use those features |
+
+**Engine-free core:** the package's main entry has no static dependency on `tone` or `@waveform-playlist/playout` — a `MediaElementPlaylistProvider`-only consumer, or one supplying a custom `createAdapter`, never resolves either. Tone-coupled exports (`useAudioTracks`, `useDynamicTracks`, effects hooks, `useExportWav`, `useOutputMeter`, `useMasterAnalyser`) live at the **`@waveform-playlist/browser/tone`** subpath:
+
+```typescript
+import { useAudioTracks, useDynamicEffects, useExportWav } from '@waveform-playlist/browser/tone';
+```
+
+## Quick Start
+
+```tsx
+import {
+  WaveformPlaylistProvider,
+  Waveform,
+  PlayButton,
+  PauseButton,
+  StopButton,
+} from '@waveform-playlist/browser';
+import { useAudioTracks } from '@waveform-playlist/browser/tone';
+
+function MyPlaylist() {
+  const { tracks, loading, error } = useAudioTracks([
+    { src: '/audio/vocals.mp3', name: 'Vocals' },
+    { src: '/audio/guitar.mp3', name: 'Guitar' },
+  ]);
+
+  if (loading) return <div>Loading audio...</div>;
+  if (error) return <div>Error: {error}</div>;
+
+  return (
+    <WaveformPlaylistProvider
+      tracks={tracks}
+      samplesPerPixel={1024}
+      waveHeight={128}
+      timescale
+      controls={{ show: true, width: 200 }}
+    >
+      <div style={{ display: 'flex', gap: '0.5rem', marginBottom: '1rem' }}>
+        <PlayButton />
+        <PauseButton />
+        <StopButton />
+      </div>
+      <Waveform />
+    </WaveformPlaylistProvider>
+  );
+}
+```
+
+Prefer a lightweight single-track player instead? Use `MediaElementPlaylistProvider` with `@waveform-playlist/media-element-playout` — no Tone.js, no AudioBuffer decoding, and pitch-preserving playback rate out of the box.
+
+## Context Hooks
+
+`WaveformPlaylistProvider` splits its context into four hooks so components only re-render for the data they actually read:
+
+| Hook | Exposes |
+|------|---------|
+| `usePlaybackAnimation` | `isPlaying`, `currentTime`, animation refs, `getPlaybackTime()`, `registerFrameCallback()` for 60fps-driven UI (playhead, progress bars) |
+| `usePlaylistState` | Low-frequency state — selection, loop region, annotations, `selectedTrackId`, `canUndo`/`canRedo` |
+| `usePlaylistControls` | Actions — `play`, `pause`, `stop`, `seekTo`, track mute/solo/volume/pan, zoom, undo/redo, `setRecordingActive` (recording-session suppression + armed-track mute) |
+| `usePlaylistData` | Derived/config data — `tracks`, `duration`, `sampleRate`, `peaksDataArray`, `trackStates`, `isReady` |
+
+`usePlaylistDataOptional` is the same as `usePlaylistData` but returns `null` outside a provider (for components that render both inside and outside one). `MediaElementPlaylistProvider` has the equivalent `useMediaElementAnimation`, `useMediaElementState`, `useMediaElementControls`, `useMediaElementData`.
+
+## Examples & Documentation
+
+- [naomiaro.github.io/waveform-playlist](https://naomiaro.github.io/waveform-playlist/) — guides, API reference, and live examples
+- [Basic Usage guide](https://naomiaro.github.io/waveform-playlist/docs/react/getting-started/basic-usage) — walkthrough of the provider pattern
+- [`examples/media-element-player`](https://github.com/naomiaro/waveform-playlist/tree/main/examples/media-element-player) — `MediaElementPlaylistProvider` starter (`pnpm example:media-element`)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -94,8 +94,12 @@ interface PlaylistStateContextValue {
     selectedTrackId: string | null;
     loopStart: number;
     loopEnd: number;
-    /** Whether playback continues past the end of loaded audio */
+    /** Whether playback continues past the end of loaded audio instead of
+     *  auto-stopping (implies the fillViewport layout) */
     indefinitePlayback: boolean;
+    /** Whether the timeline visually fills the scroll container even when the
+     *  audio is shorter (layout only — no effect on playback) */
+    fillViewport: boolean;
     /** Whether undo is available */
     canUndo: boolean;
     /** Whether redo is available */
@@ -132,6 +136,16 @@ interface PlaylistControlsContextValue {
     clearLoopRegion: () => void;
     undo: () => void;
     redo: () => void;
+    /** Mark a recording session active/inactive. While active: (1) the
+     *  end-of-audio auto-stop is suppressed so overdub playback runs past the
+     *  end of existing material, and (2) with an `armedTrackId`, that track's
+     *  existing content is transiently muted — punch-in recording replaces
+     *  whatever the take overlaps (#579), so the doomed material must not play
+     *  under the overdub; its previous mute state is restored when the session
+     *  ends (audio-only, the UI mute control is untouched). Wired automatically
+     *  from the Waveform / PlaylistVisualization `recordingState` prop; overdub
+     *  flows should also call it eagerly (before `play()`). */
+    setRecordingActive: (active: boolean, armedTrackId?: string | null) => void;
 }
 interface PlaylistDataContextValue {
     duration: number;
@@ -222,9 +236,17 @@ interface WaveformPlaylistProviderProps {
      *  Use this during progressive loading to avoid rebuilding the engine for
      *  each track — flip to false when all tracks are ready for a single build. */
     deferEngineRebuild?: boolean;
-    /** Disable automatic stop when the cursor reaches the end of the longest
-     *  track. Useful for DAW-style recording beyond existing audio. */
+    /** Disable the automatic stop when the cursor reaches the end of the
+     *  longest track — the transport rolls until an explicit stop/pause
+     *  (DAW-style). Implies the fillViewport layout. Recording sessions
+     *  suppress the auto-stop automatically, so most recording UIs don't
+     *  need this. */
     indefinitePlayback?: boolean;
+    /** Extend the timeline (background + timescale) to fill the visible scroll
+     *  container even when the audio is shorter. Layout only. Recording UIs
+     *  typically want this so the empty timeline doesn't collapse to the audio
+     *  width. */
+    fillViewport?: boolean;
     /** Desired AudioContext sample rate. Creates a cross-browser AudioContext at
      *  this rate via standardized-audio-context. Pre-computed peaks (.dat files)
      *  render instantly when they match. On mismatch, falls back to worker. */

package/dist/index.d.ts

@@ -94,8 +94,12 @@ interface PlaylistStateContextValue {
     selectedTrackId: string | null;
     loopStart: number;
     loopEnd: number;
-    /** Whether playback continues past the end of loaded audio */
+    /** Whether playback continues past the end of loaded audio instead of
+     *  auto-stopping (implies the fillViewport layout) */
     indefinitePlayback: boolean;
+    /** Whether the timeline visually fills the scroll container even when the
+     *  audio is shorter (layout only — no effect on playback) */
+    fillViewport: boolean;
     /** Whether undo is available */
     canUndo: boolean;
     /** Whether redo is available */
@@ -132,6 +136,16 @@ interface PlaylistControlsContextValue {
     clearLoopRegion: () => void;
     undo: () => void;
     redo: () => void;
+    /** Mark a recording session active/inactive. While active: (1) the
+     *  end-of-audio auto-stop is suppressed so overdub playback runs past the
+     *  end of existing material, and (2) with an `armedTrackId`, that track's
+     *  existing content is transiently muted — punch-in recording replaces
+     *  whatever the take overlaps (#579), so the doomed material must not play
+     *  under the overdub; its previous mute state is restored when the session
+     *  ends (audio-only, the UI mute control is untouched). Wired automatically
+     *  from the Waveform / PlaylistVisualization `recordingState` prop; overdub
+     *  flows should also call it eagerly (before `play()`). */
+    setRecordingActive: (active: boolean, armedTrackId?: string | null) => void;
 }
 interface PlaylistDataContextValue {
     duration: number;
@@ -222,9 +236,17 @@ interface WaveformPlaylistProviderProps {
      *  Use this during progressive loading to avoid rebuilding the engine for
      *  each track — flip to false when all tracks are ready for a single build. */
     deferEngineRebuild?: boolean;
-    /** Disable automatic stop when the cursor reaches the end of the longest
-     *  track. Useful for DAW-style recording beyond existing audio. */
+    /** Disable the automatic stop when the cursor reaches the end of the
+     *  longest track — the transport rolls until an explicit stop/pause
+     *  (DAW-style). Implies the fillViewport layout. Recording sessions
+     *  suppress the auto-stop automatically, so most recording UIs don't
+     *  need this. */
     indefinitePlayback?: boolean;
+    /** Extend the timeline (background + timescale) to fill the visible scroll
+     *  container even when the audio is shorter. Layout only. Recording UIs
+     *  typically want this so the empty timeline doesn't collapse to the audio
+     *  width. */
+    fillViewport?: boolean;
     /** Desired AudioContext sample rate. Creates a cross-browser AudioContext at
      *  this rate via standardized-audio-context. Pre-computed peaks (.dat files)
      *  render instantly when they match. On mismatch, falls back to worker. */

package/dist/index.js

@@ -1881,14 +1881,13 @@ var WaveformPlaylistProvider = ({
   soundFontCache,
   deferEngineRebuild = false,
   indefinitePlayback = false,
+  fillViewport = false,
   sampleRate: sampleRateProp,
   createAdapter,
   children
 }) => {
   var _a, _b, _c, _d;
   const progressBarWidth = progressBarWidthProp != null ? progressBarWidthProp : barWidth + barGap;
-  const indefinitePlaybackRef = (0, import_react17.useRef)(indefinitePlayback);
-  indefinitePlaybackRef.current = indefinitePlayback;
   const stableZoomLevels = (0, import_react17.useMemo)(
     () => zoomLevels,
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -1926,6 +1925,28 @@ var WaveformPlaylistProvider = ({
   const engineRef = (0, import_react17.useRef)(null);
   const adapterRef = (0, import_react17.useRef)(null);
   const audioInitializedRef = (0, import_react17.useRef)(false);
+  const indefinitePlaybackRef = (0, import_react17.useRef)(indefinitePlayback);
+  indefinitePlaybackRef.current = indefinitePlayback;
+  const recordingActiveRef = (0, import_react17.useRef)(false);
+  const armedTrackMuteRef = (0, import_react17.useRef)(null);
+  const setRecordingActive = (0, import_react17.useCallback)((active, armedTrackId) => {
+    var _a2, _b2, _c2;
+    recordingActiveRef.current = active;
+    const engine = engineRef.current;
+    if (!engine) return;
+    if (active && armedTrackId) {
+      if (((_a2 = armedTrackMuteRef.current) == null ? void 0 : _a2.trackId) === armedTrackId) return;
+      if (armedTrackMuteRef.current) {
+        engine.setTrackMute(armedTrackMuteRef.current.trackId, armedTrackMuteRef.current.prevMuted);
+      }
+      const prevMuted = (_c2 = (_b2 = engine.getState().tracks.find((t) => t.id === armedTrackId)) == null ? void 0 : _b2.muted) != null ? _c2 : false;
+      armedTrackMuteRef.current = { trackId: armedTrackId, prevMuted };
+      engine.setTrackMute(armedTrackId, true);
+    } else if (!active && armedTrackMuteRef.current) {
+      engine.setTrackMute(armedTrackMuteRef.current.trackId, armedTrackMuteRef.current.prevMuted);
+      armedTrackMuteRef.current = null;
+    }
+  }, []);
   const isPlayingRef = (0, import_react17.useRef)(false);
   isPlayingRef.current = isPlaying;
   const playStartPositionRef = (0, import_react17.useRef)(0);
@@ -2517,7 +2538,7 @@ var WaveformPlaylistProvider = ({
         playbackEndTimeRef.current = null;
         return;
       }
-      if (time >= duration && !indefinitePlaybackRef.current) {
+      if (time >= duration && !indefinitePlaybackRef.current && !recordingActiveRef.current) {
         if (engineRef.current) {
           engineRef.current.stop();
         }
@@ -2788,6 +2809,7 @@ var WaveformPlaylistProvider = ({
       loopStart,
       loopEnd,
       indefinitePlayback,
+      fillViewport,
       canUndo,
       canRedo
     }),
@@ -2805,6 +2827,7 @@ var WaveformPlaylistProvider = ({
       loopStart,
       loopEnd,
       indefinitePlayback,
+      fillViewport,
       canUndo,
       canRedo
     ]
@@ -2860,7 +2883,9 @@ var WaveformPlaylistProvider = ({
       clearLoopRegion,
       // Undo/redo
       undo,
-      redo
+      redo,
+      // Recording
+      setRecordingActive
     }),
     [
       play,
@@ -2892,7 +2917,8 @@ var WaveformPlaylistProvider = ({
       setLoopRegionFromSelection,
       clearLoopRegion,
       undo,
-      redo
+      redo,
+      setRecordingActive
     ]
   );
   const dataValue = (0, import_react17.useMemo)(
@@ -4021,7 +4047,7 @@ var PlaylistVisualization = ({
   onRemoveTrack,
   recordingState
 }) => {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m;
   const theme = (0, import_ui_components8.useTheme)();
   const { isPlaying, getLookAhead, getOutputLatency } = usePlaybackAnimation();
   const {
@@ -4036,7 +4062,8 @@ var PlaylistVisualization = ({
     loopStart,
     loopEnd,
     isLoopEnabled,
-    indefinitePlayback
+    indefinitePlayback,
+    fillViewport
   } = usePlaylistState();
   const annotationIntegration = (0, import_react26.useContext)(AnnotationIntegrationContext);
   const {
@@ -4051,7 +4078,8 @@ var PlaylistVisualization = ({
     setScrollContainer,
     setSelectedTrackId,
     setCurrentTime,
-    setLoopRegion
+    setLoopRegion,
+    setRecordingActive
   } = usePlaylistControls();
   const {
     peaksDataArray,
@@ -4070,6 +4098,13 @@ var PlaylistVisualization = ({
     mono
   } = usePlaylistData();
   const spectrogram = (0, import_react26.useContext)(SpectrogramIntegrationContext);
+  const recordingActive = !!(recordingState == null ? void 0 : recordingState.isRecording);
+  const armedTrackId = (_a = recordingState == null ? void 0 : recordingState.trackId) != null ? _a : null;
+  (0, import_react26.useEffect)(() => {
+    if (!recordingActive) return void 0;
+    setRecordingActive(true, armedTrackId);
+    return () => setRecordingActive(false);
+  }, [recordingActive, armedTrackId, setRecordingActive]);
   const perTrackSpectrogramHelpers = (0, import_react26.useMemo)(() => {
     if (!spectrogram)
       return /* @__PURE__ */ new Map();
@@ -4107,8 +4142,8 @@ var PlaylistVisualization = ({
     }, max);
   }, 0);
   let displayDuration = tracksMaxDuration > 0 ? tracksMaxDuration : duration > 0 ? duration : DEFAULT_EMPTY_TRACK_DURATION;
-  if (indefinitePlayback) {
-    const containerWidth = (_b = (_a = scrollContainerRef.current) == null ? void 0 : _a.clientWidth) != null ? _b : 0;
+  if (indefinitePlayback || fillViewport) {
+    const containerWidth = (_c = (_b = scrollContainerRef.current) == null ? void 0 : _b.clientWidth) != null ? _c : 0;
     const minContainerDuration = containerWidth * samplesPerPixel / sampleRate;
     displayDuration = Math.max(displayDuration, minContainerDuration);
   }
@@ -4566,8 +4601,8 @@ var PlaylistVisualization = ({
         {
           open: settingsModalTrackId !== null,
           onClose: () => setSettingsModalTrackId(null),
-          config: settingsModalTrackId !== null ? (_g = (_f = (_e = (_c = spectrogram.trackSpectrogramOverrides.get(settingsModalTrackId)) == null ? void 0 : _c.config) != null ? _e : (_d = tracks.find((t) => t.id === settingsModalTrackId)) == null ? void 0 : _d.spectrogramConfig) != null ? _f : spectrogram.spectrogramConfig) != null ? _g : {} : {},
-          colorMap: settingsModalTrackId !== null ? (_l = (_k = (_j = (_h = spectrogram.trackSpectrogramOverrides.get(settingsModalTrackId)) == null ? void 0 : _h.colorMap) != null ? _j : (_i = tracks.find((t) => t.id === settingsModalTrackId)) == null ? void 0 : _i.spectrogramColorMap) != null ? _k : spectrogram.spectrogramColorMap) != null ? _l : "viridis" : "viridis",
+          config: settingsModalTrackId !== null ? (_h = (_g = (_f = (_d = spectrogram.trackSpectrogramOverrides.get(settingsModalTrackId)) == null ? void 0 : _d.config) != null ? _f : (_e = tracks.find((t) => t.id === settingsModalTrackId)) == null ? void 0 : _e.spectrogramConfig) != null ? _g : spectrogram.spectrogramConfig) != null ? _h : {} : {},
+          colorMap: settingsModalTrackId !== null ? (_m = (_l = (_k = (_i = spectrogram.trackSpectrogramOverrides.get(settingsModalTrackId)) == null ? void 0 : _i.colorMap) != null ? _k : (_j = tracks.find((t) => t.id === settingsModalTrackId)) == null ? void 0 : _j.spectrogramColorMap) != null ? _l : spectrogram.spectrogramColorMap) != null ? _m : "viridis" : "viridis",
           onApply: (newConfig, newColorMap) => {
             if (settingsModalTrackId !== null) {
               spectrogram.setTrackSpectrogramConfig(settingsModalTrackId, newConfig, newColorMap);