feat: add Web Audio routing to MediaElementTrack for fades (#318)

* feat: add Web Audio routing to MediaElementTrack for fades

Extract fade utilities from playout to core package so they can be
shared with media-element-playout. Add optional AudioContext support
to MediaElementTrack that routes audio through a Web Audio graph
(source → fadeGain → volumeGain → destination) enabling fade in/out
effects without Tone.js dependency.

Rewrite FadesExample and StylingExample to use MediaElementPlaylistProvider
with pre-computed peaks, giving each player instance independent playback
(no shared Tone.js Transport singleton).

* feat: add showFades prop to MediaElementWaveform

Expose fadeIn/fadeOut config via MediaElementDataContext and render
FadeOverlay components in MediaElementPlaylist when showFades is
enabled. Update FadesExample with show fades checkbox and lower
samplesPerPixel for visible fade curve shapes. Make StylingExample
theme descriptions explicit about color names and add boldTheme
with transparent progress for Extra Wide Bars.

* feat: add Tone.js effect bridging to MediaElement example

Add a third player to the media-element example demonstrating BitCrusher
effect via native→Tone.js bridge pattern. Tone.js is dynamically imported
after AudioContext is running to avoid AudioWorklet errors on page load.

- Add outputNode getter to MediaElementPlayout for effects wiring
- Add EffectWiring component with statechange-based lazy initialization
- Update guide, API docs, and llms.txt for audioContext prop, fades,
  and Tone.js effect bridging

* docs: document WaveformPlaylistProvider single-instance constraint

Add caution admonition to WaveformPlaylistProvider API doc explaining
the shared Tone.js Transport singleton. Add Instances row to
MediaElementPlaylistProvider comparison table. Update llms.txt and
CLAUDE.md files with Tone.js dynamic import and effect bridging patterns.

* fix: address PR review issues for MediaElement fades and effects

- Fix partial fade resume to use actual curve interpolation via generateCurve()
- Add error handling to wireEffect() with fallback reconnection
- Add console.warn diagnostics to all empty catch blocks
- Wrap createMediaElementSource() in try-catch with descriptive error
- Handle AudioContext.resume() promise rejection
- Separate disconnect/reconnect in cleanup with individual try-catch
- Fix stale JSDoc (PingPongDelay → BitCrusher)
- Deduplicate FadeConfig into @waveform-playlist/core as type alias
- Lazy AudioContext creation in FadesExample via useRef
- Use String(err) instead of passing error objects to console.warn
- Wrap disconnect() in try-catch for connectOutput/disconnectOutput
- Add reconnection to guide doc cleanup example

* fix: partial fade curve shape, resume race, and guide cleanup

- Partial fades now slice the original curve instead of generating a
  fresh one, preserving the correct curve shape for sCurve/logarithmic
  types when seeking mid-fade
- Await AudioContext.resume() before scheduling fades to prevent
  fades from being scheduled at currentTime=0 (in the past)
- Guide doc now removes statechange listener on cleanup, matching
  the actual implementation in MediaElementExample
- Document why MediaElementExample uses eager AudioContext (single
  context, always needed)

* fix: share single AudioContext across all fade players

Multiple AudioContexts per page is wasteful — createMediaElementSource
is per-element, not per-context, so all players can share one.

Author: naomiaro

CLAUDE.md

@@ -350,6 +350,9 @@ const LazyExample = createLazyExample(() =>
 27. **Stop Before Clear** — Always call `stop()` before clearing tracks. Clearing React state without stopping Tone.js Transport leaves orphaned audio playing. Use `ClearAllButton` (from `@waveform-playlist/browser`) which handles this automatically via `usePlaylistControls().stop()`.
 28. **Tone.js Panner Stereo Preservation** — `new Panner(pan)` defaults to `channelCount: 1`, downmixing stereo to mono at 1/√2 gain. Use `new Panner({ pan, channelCount: 2 })` for audio tracks with stereo content. MIDI/SoundFont tracks use mono synths so `channelCount: 1` is fine.
 29. **Never Use Tone.js `addAudioWorkletModule`** — Tone.js caches a single `_workletPromise` per context. Only the first URL is loaded; subsequent calls with different URLs are silently skipped. Always use `rawContext.audioWorklet.addModule(url)` directly. `context.createAudioWorkletNode()` is still fine for node creation.
+30. **Dynamic Import Tone.js Outside Playout Package** — `import * as Tone from 'tone'` eagerly creates a default context with AudioWorklet nodes, which fails before user gesture. Outside the playout package (which handles init via `getGlobalContext()`), use `import type` for types and `await import('tone')` inside effects after AudioContext is running. Call `Tone.setContext(new Tone.Context(audioContext))` to share the native AudioContext.
+31. **Tone.js Effect.input Is Not a Native AudioNode** — `Effect` subclasses (BitCrusher, etc.) set `this.input = new Tone.Gain(...)` (a Tone.js wrapper). Native `AudioNode.connect(effect.input)` fails with "Overload resolution failed". Use `Tone.Gain` as a bridge: `outputNode.connect(bridge.input)` works because `Tone.Gain.input` IS a native `GainNode`. Then `bridge.chain(effect, destination)` for the Tone chain.
+32. **Provider Child Effects and playoutRef Timing** — React runs child effects before parent effects. A child component's `useEffect` accessing `playoutRef.current` will find `null` on first run because the provider's effect hasn't created the playout yet. Add `duration` (from `useMediaElementData()`) as a dependency — it changes from 0 to the actual value when the playout is ready, retriggering the effect.
 
 ---
 

packages/browser/src/MediaElementPlaylistContext.tsx

@@ -9,7 +9,7 @@ import React, {
   type ReactNode,
 } from 'react';
 import { ThemeProvider } from 'styled-components';
-import { MediaElementPlayout } from '@waveform-playlist/media-element-playout';
+import { MediaElementPlayout, type FadeConfig } from '@waveform-playlist/media-element-playout';
 import { type WaveformDataObject } from '@waveform-playlist/core';
 import { type WaveformPlaylistTheme, defaultTheme } from '@waveform-playlist/ui-components';
 import type { AnnotationData } from '@waveform-playlist/core';
@@ -27,6 +27,10 @@ export interface MediaElementTrackConfig {
   waveformData: WaveformDataObject;
   /** Track name for display */
   name?: string;
+  /** Fade in configuration (requires audioContext on provider) */
+  fadeIn?: FadeConfig;
+  /** Fade out configuration (requires audioContext on provider) */
+  fadeOut?: FadeConfig;
 }
 
 // Context values for animation (high-frequency updates)
@@ -73,6 +77,8 @@ export interface MediaElementDataContextValue {
   barWidth: number;
   barGap: number;
   progressBarWidth: number;
+  fadeIn?: FadeConfig;
+  fadeOut?: FadeConfig;
 }
 
 // Create contexts
@@ -111,6 +117,16 @@ export interface MediaElementPlaylistProviderProps {
   progressBarWidth?: number;
   /** Callback when annotations are changed (drag, edit, etc.) */
   onAnnotationsChange?: (annotations: AnnotationData[]) => void;
+  /**
+   * AudioContext for Web Audio routing (fades, effects).
+   * When provided, audio routes through Web Audio nodes:
+   *   HTMLAudioElement → MediaElementSourceNode → fadeGain → volumeGain → destination
+   *
+   * Without this, playback uses HTMLAudioElement directly (no fades or effects).
+   * Each provider instance should use its own AudioContext or share one —
+   * createMediaElementSource() is called once per audio element.
+   */
+  audioContext?: AudioContext;
   /** Callback when audio is ready */
   onReady?: () => void;
   children: ReactNode;
@@ -145,6 +161,7 @@ export const MediaElementPlaylistProvider: React.FC<MediaElementPlaylistProvider
   barWidth = 1,
   barGap = 0,
   progressBarWidth: progressBarWidthProp,
+  audioContext,
   onAnnotationsChange,
   onReady,
   children,
@@ -235,6 +252,9 @@ export const MediaElementPlaylistProvider: React.FC<MediaElementPlaylistProvider
       source: track.source,
       peaks: track.waveformData,
       name: track.name,
+      audioContext,
+      fadeIn: track.fadeIn,
+      fadeOut: track.fadeOut,
     });
 
     // Set up time update callback
@@ -266,6 +286,9 @@ export const MediaElementPlaylistProvider: React.FC<MediaElementPlaylistProvider
     track.source,
     track.waveformData,
     track.name,
+    track.fadeIn,
+    track.fadeOut,
+    audioContext,
     initialPlaybackRate,
     onReady,
     stopAnimationFrameLoop,
@@ -497,6 +520,8 @@ export const MediaElementPlaylistProvider: React.FC<MediaElementPlaylistProvider
       barWidth,
       barGap,
       progressBarWidth,
+      fadeIn: track.fadeIn,
+      fadeOut: track.fadeOut,
     }),
     [
       duration,
@@ -509,6 +534,8 @@ export const MediaElementPlaylistProvider: React.FC<MediaElementPlaylistProvider
       barWidth,
       barGap,
       progressBarWidth,
+      track.fadeIn,
+      track.fadeOut,
     ]
   );
 

packages/browser/src/components/MediaElementPlaylist.tsx

@@ -6,6 +6,7 @@ import {
   Track as TrackComponent,
   Clip,
   Selection,
+  FadeOverlay,
   PlaylistInfoContext,
   DevicePixelRatioProvider,
   SmartScale,
@@ -75,6 +76,8 @@ export interface MediaElementPlaylistProps {
   onAnnotationUpdate?: OnAnnotationUpdateFn;
   /** Custom playhead render function. Receives position, color, and animation refs for smooth 60fps animation. */
   renderPlayhead?: RenderPlayheadFunction;
+  /** Show fade in/out overlays on the waveform. Defaults to false. */
+  showFades?: boolean;
   className?: string;
 }
 
@@ -96,6 +99,7 @@ export const MediaElementPlaylist: React.FC<MediaElementPlaylistProps> = ({
   linkEndpoints: linkEndpointsProp = false,
   onAnnotationUpdate,
   renderPlayhead,
+  showFades = false,
   className,
 }) => {
   const theme = useTheme() as import('@waveform-playlist/ui-components').WaveformPlaylistTheme;
@@ -117,6 +121,8 @@ export const MediaElementPlaylist: React.FC<MediaElementPlaylistProps> = ({
     playoutRef,
     barWidth,
     barGap,
+    fadeIn,
+    fadeOut,
   } = useMediaElementData();
 
   const [selectionStart, setSelectionStart] = useState(0);
@@ -327,6 +333,24 @@ export const MediaElementPlaylist: React.FC<MediaElementPlaylistProps> = ({
                             clipDurationSamples={clip.durationSamples}
                           />
                         ))}
+                        {showFades && fadeIn && fadeIn.duration > 0 && (
+                          <FadeOverlay
+                            left={0}
+                            width={Math.floor((fadeIn.duration * sampleRate) / samplesPerPixel)}
+                            type="fadeIn"
+                            curveType={fadeIn.type}
+                          />
+                        )}
+                        {showFades && fadeOut && fadeOut.duration > 0 && (
+                          <FadeOverlay
+                            left={
+                              width - Math.floor((fadeOut.duration * sampleRate) / samplesPerPixel)
+                            }
+                            width={Math.floor((fadeOut.duration * sampleRate) / samplesPerPixel)}
+                            type="fadeOut"
+                            curveType={fadeOut.type}
+                          />
+                        )}
                       </Clip>
                     );
                   })}

packages/browser/src/components/MediaElementWaveform.tsx

@@ -35,6 +35,8 @@ export interface MediaElementWaveformProps {
   scrollActiveContainer?: 'nearest' | 'all';
   /** Custom playhead render function. Receives position, color, and animation refs for smooth 60fps animation. */
   renderPlayhead?: RenderPlayheadFunction;
+  /** Show fade in/out overlays on the waveform. Defaults to false. */
+  showFades?: boolean;
   className?: string;
 }
 
@@ -60,6 +62,7 @@ export const MediaElementWaveform: React.FC<MediaElementWaveformProps> = ({
   scrollActivePosition = 'center',
   scrollActiveContainer = 'nearest',
   renderPlayhead,
+  showFades = false,
   className,
 }) => {
   const { annotations } = useMediaElementState();
@@ -72,6 +75,7 @@ export const MediaElementWaveform: React.FC<MediaElementWaveformProps> = ({
         linkEndpoints={linkEndpoints}
         onAnnotationUpdate={onAnnotationUpdate}
         renderPlayhead={renderPlayhead}
+        showFades={showFades}
         className={className}
       />
       {annotations.length > 0 && (