@waveform-playlist/browser 9.0.4 → 9.1.0

package/dist/index.d.ts

@@ -203,6 +203,16 @@ export declare interface AudioClip {
      * Load with: `const waveformData = await loadWaveformData('/path/to/peaks.dat')`
      */
     waveformData?: WaveformDataObject;
+    /**
+     * MIDI note data — when present, this clip plays MIDI instead of audio.
+     * The playout adapter uses this field to detect MIDI clips and route them
+     * to MidiToneTrack (PolySynth) instead of ToneTrack (AudioBufferSourceNode).
+     */
+    midiNotes?: MidiNoteData[];
+    /** MIDI channel (0-indexed). Channel 9 = GM percussion. */
+    midiChannel?: number;
+    /** MIDI program number (0-127). GM instrument number for SoundFont playback. */
+    midiProgram?: number;
 }
 
 /**
@@ -294,6 +304,9 @@ declare interface ClipPeaks {
     durationSamples: number;
     fadeIn?: Fade;
     fadeOut?: Fade;
+    midiNotes?: MidiNoteData[];
+    sampleRate?: number;
+    offsetSamples?: number;
 }
 
 /**
@@ -861,6 +874,26 @@ export declare interface MediaElementWaveformProps {
     className?: string;
 }
 
+/**
+ * MIDI note data for clips that play MIDI instead of audio.
+ * When present on an AudioClip, the clip is treated as a MIDI clip
+ * by the playout adapter.
+ */
+declare interface MidiNoteData {
+    /** MIDI note number (0-127) */
+    midi: number;
+    /** Note name in scientific pitch notation ("C4", "G#3") */
+    name: string;
+    /** Start time in seconds, relative to clip start */
+    time: number;
+    /** Duration in seconds */
+    duration: number;
+    /** Velocity (0-1 normalized) */
+    velocity: number;
+    /** MIDI channel (0-indexed). Channel 9 = GM percussion. Enables per-note routing in flattened tracks. */
+    channel?: number;
+}
+
 /**
  * DragDropProvider plugins customizer that disables the Feedback plugin's drop animation.
  *
@@ -941,8 +974,8 @@ declare interface PlayheadProps {
     samplesPerPixel: number;
     /** Sample rate - for converting time to pixels */
     sampleRate: number;
-    /** Controls offset in pixels */
-    controlsOffset: number;
+    /** Controls offset in pixels (deprecated, always 0 — controls are now outside scroll area) */
+    controlsOffset?: number;
     /** Function to get current audio context time - required for smooth animation */
     getAudioContextTime?: () => number;
     /** Returns current playback time (auto-wraps at loop boundaries). Preferred over manual elapsed calculation. */
@@ -1122,7 +1155,7 @@ declare interface RenderAnnotationItemProps {
 }
 
 /** Render mode for a track's visualization */
-declare type RenderMode = 'waveform' | 'spectrogram' | 'both';
+declare type RenderMode = 'waveform' | 'spectrogram' | 'both' | 'piano-roll';
 
 /**
  * Type for custom playhead render functions.
@@ -1156,6 +1189,106 @@ export declare const SkipForwardButton: default_2.FC<{
     className?: string;
 }>;
 
+/**
+ * Caches parsed SoundFont2 data and AudioBuffers for efficient playback.
+ *
+ * AudioBuffers are created lazily on first access and cached by sample index.
+ * Pitch calculation uses the SF2 generator chain:
+ *   OverridingRootKey → sample.header.originalPitch → fallback 60
+ *
+ * Audio graph per note:
+ *   AudioBufferSourceNode (playbackRate for pitch) → GainNode (velocity) → track chain
+ */
+declare class SoundFontCache {
+    private sf2;
+    private audioBufferCache;
+    private context;
+    /**
+     * @param context Optional AudioContext for createBuffer(). If omitted, uses
+     *   an OfflineAudioContext which doesn't require user gesture — safe to
+     *   construct before user interaction (avoids Firefox autoplay warnings).
+     */
+    constructor(context?: BaseAudioContext);
+    /**
+     * Load and parse an SF2 file from a URL.
+     */
+    load(url: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Load from an already-fetched ArrayBuffer.
+     */
+    loadFromBuffer(data: ArrayBuffer): void;
+    get isLoaded(): boolean;
+    /**
+     * Look up a MIDI note and return the AudioBuffer + playbackRate.
+     *
+     * @param midiNote - MIDI note number (0-127)
+     * @param bankNumber - Bank number (0 for melodic, 128 for percussion/drums)
+     * @param presetNumber - GM program number (0-127)
+     * @returns SoundFontSample or null if no sample found for this note
+     */
+    getAudioBuffer(midiNote: number, bankNumber?: number, presetNumber?: number): SoundFontSample | null;
+    /**
+     * Extract loop points and volume envelope data from per-zone generators.
+     *
+     * Loop points are stored as absolute indices into the SF2 sample pool.
+     * We convert to AudioBuffer-relative seconds by subtracting header.start
+     * and dividing by sampleRate.
+     *
+     * Volume envelope times are in SF2 timecents; sustain is centibels attenuation.
+     */
+    private extractLoopAndEnvelope;
+    /**
+     * Calculate playback rate for a MIDI note using the SF2 generator chain.
+     *
+     * SF2 root key resolution priority:
+     *   1. OverridingRootKey generator (per-zone, most specific)
+     *   2. sample.header.originalPitch (sample header)
+     *   3. MIDI note 60 (middle C fallback)
+     *
+     * Tuning adjustments:
+     *   - CoarseTune generator (semitones, additive)
+     *   - FineTune generator (cents, additive)
+     *   - sample.header.pitchCorrection (cents, additive)
+     */
+    private calculatePlaybackRate;
+    /**
+     * Convert Int16Array sample data to an AudioBuffer.
+     * SF2 samples are 16-bit signed integers; Web Audio needs Float32 [-1, 1].
+     */
+    private int16ToAudioBuffer;
+    /**
+     * Clear all cached AudioBuffers and release the parsed SF2.
+     */
+    dispose(): void;
+}
+
+/**
+ * Result of looking up a MIDI note in the SoundFont.
+ * Contains the AudioBuffer, playbackRate, loop points, and volume envelope.
+ */
+declare interface SoundFontSample {
+    /** Cached AudioBuffer for this sample */
+    buffer: AudioBuffer;
+    /** Playback rate to pitch-shift from originalPitch to target note */
+    playbackRate: number;
+    /** Loop mode: 0=no loop, 1=continuous, 3=sustain loop */
+    loopMode: number;
+    /** Loop start in seconds, relative to AudioBuffer start */
+    loopStart: number;
+    /** Loop end in seconds, relative to AudioBuffer start */
+    loopEnd: number;
+    /** Volume envelope attack time in seconds */
+    attackVolEnv: number;
+    /** Volume envelope hold time in seconds */
+    holdVolEnv: number;
+    /** Volume envelope decay time in seconds */
+    decayVolEnv: number;
+    /** Volume envelope sustain level as linear gain 0-1 */
+    sustainVolEnv: number;
+    /** Volume envelope release time in seconds */
+    releaseVolEnv: number;
+}
+
 /**
  * Configuration for spectrogram computation and rendering.
  */
@@ -1448,7 +1581,7 @@ export declare function useAnnotationIntegration(): AnnotationIntegration;
  * });
  * ```
  */
-export declare function useAnnotationKeyboardControls({ annotations, activeAnnotationId, onAnnotationsChange, onActiveAnnotationChange, duration, linkEndpoints, continuousPlay, enabled, scrollContainerRef, samplesPerPixel, sampleRate, controlsWidth, onPlay, }: UseAnnotationKeyboardControlsOptions): {
+export declare function useAnnotationKeyboardControls({ annotations, activeAnnotationId, onAnnotationsChange, onActiveAnnotationChange, duration, linkEndpoints, continuousPlay, enabled, scrollContainerRef, samplesPerPixel, sampleRate, onPlay, }: UseAnnotationKeyboardControlsOptions): {
     moveStartBoundary: (delta: number) => void;
     moveEndBoundary: (delta: number) => void;
     selectPrevious: () => void;
@@ -1477,8 +1610,6 @@ declare interface UseAnnotationKeyboardControlsOptions {
     samplesPerPixel?: number;
     /** Optional: sample rate for scroll position calculation */
     sampleRate?: number;
-    /** Optional: controls width offset for scroll position calculation */
-    controlsWidth?: number;
     /** Optional: callback to start playback at a time with optional duration */
     onPlay?: (startTime: number, duration?: number) => void;
 }
@@ -2056,6 +2187,9 @@ declare interface WaveformPlaylistProviderProps {
      * identity (`tracks === engineTracksRef.current`) to detect engine-originated
      * updates and skip the expensive `loadAudio` rebuild. */
     onTracksChange?: (tracks: ClipTrack[]) => void;
+    /** SoundFont cache for sample-based MIDI playback. When provided, MIDI clips
+     *  use SoundFont samples instead of PolySynth synthesis. */
+    soundFontCache?: SoundFontCache;
     children: ReactNode;
 }
 
@@ -2104,6 +2238,10 @@ declare interface WaveformPlaylistTheme {
     annotationResizeHandleColor: string;
     annotationResizeHandleActiveColor: string;
     annotationTextItemHoverBackground: string;
+    playlistBackgroundColor?: string;
+    pianoRollNoteColor: string;
+    pianoRollSelectedNoteColor: string;
+    pianoRollBackgroundColor: string;
     borderRadius: string;
     fontFamily: string;
     fontSize: string;