@songram/songram-daw-engine 3.1.0

package/dist/index.d.ts

@@ -0,0 +1,2016 @@
+import { BaseContext } from 'tone';
+import { Context } from 'tone';
+import { Gain } from 'tone';
+import { Generator as Generator_2 } from 'soundfont2';
+import { GeneratorType } from 'soundfont2';
+import { SynthOptions } from 'tone';
+import { ToneAudioNode } from 'tone';
+import { Volume } from 'tone';
+import { ZoneMap } from 'soundfont2';
+
+/**
+ * An action control shown on annotation items (e.g., delete, split).
+ */
+export declare interface AnnotationAction {
+    class?: string;
+    text?: string;
+    title: string;
+    action: (annotation: AnnotationData, index: number, annotations: AnnotationData[], opts: AnnotationActionOptions) => void;
+}
+
+/**
+ * Configuration options passed to annotation action handlers.
+ * Used by both browser and annotations packages.
+ */
+export declare interface AnnotationActionOptions {
+    /** Whether annotation endpoints are linked (moving one endpoint moves the other) */
+    linkEndpoints?: boolean;
+    /** Whether to continue playing after an annotation ends */
+    continuousPlay?: boolean;
+    /** Additional custom properties */
+    [key: string]: unknown;
+}
+
+/**
+ * Shared annotation types used across Songram DAW modules
+ */
+/**
+ * Base annotation data structure
+ */
+export declare interface AnnotationData {
+    id: string;
+    start: number;
+    end: number;
+    lines: string[];
+    language?: string;
+}
+
+/**
+ * Event handlers for annotation operations
+ */
+export declare interface AnnotationEventMap {
+    'annotation-select': (annotation: AnnotationData) => void;
+    'annotation-update': (annotation: AnnotationData) => void;
+    'annotation-delete': (id: string) => void;
+    'annotation-create': (annotation: AnnotationData) => void;
+}
+
+/**
+ * Annotation format definition for parsing/serializing
+ */
+export declare interface AnnotationFormat {
+    name: string;
+    parse: (data: unknown) => AnnotationData[];
+    serialize: (annotations: AnnotationData[]) => unknown;
+}
+
+/**
+ * Options for annotation list behavior
+ */
+export declare interface AnnotationListOptions {
+    editable?: boolean;
+    linkEndpoints?: boolean;
+    isContinuousPlay?: boolean;
+}
+
+/**
+ * Apply a fade in to an AudioParam
+ *
+ * @param param - The AudioParam to apply the fade to (usually gain)
+ * @param startTime - When the fade starts (in seconds, AudioContext time)
+ * @param duration - Duration of the fade in seconds
+ * @param type - Type of fade curve
+ * @param startValue - Starting value (default: 0)
+ * @param endValue - Ending value (default: 1)
+ */
+export declare function applyFadeIn(param: AudioParam, startTime: number, duration: number, type?: FadeType, startValue?: number, endValue?: number): void;
+
+/**
+ * Apply a fade out to an AudioParam
+ *
+ * @param param - The AudioParam to apply the fade to (usually gain)
+ * @param startTime - When the fade starts (in seconds, AudioContext time)
+ * @param duration - Duration of the fade in seconds
+ * @param type - Type of fade curve
+ * @param startValue - Starting value (default: 1)
+ * @param endValue - Ending value (default: 0)
+ */
+export declare function applyFadeOut(param: AudioParam, startTime: number, duration: number, type?: FadeType, startValue?: number, endValue?: number): void;
+
+export declare interface AssistantPlugin extends EnginePlugin {
+    kind: 'assistant';
+    capabilities?: string[];
+}
+
+export declare interface AssistantRequestEvent {
+    assistantId: string;
+    action: string;
+    payload?: unknown;
+}
+
+declare interface AudioBuffer_2 {
+    length: number;
+    duration: number;
+    numberOfChannels: number;
+    sampleRate: number;
+    getChannelData(channel: number): Float32Array;
+}
+export { AudioBuffer_2 as AudioBuffer }
+
+/**
+ * Represents a single audio clip on the timeline
+ *
+ * IMPORTANT: All positions/durations are stored as SAMPLE COUNTS (integers)
+ * to avoid floating-point precision errors. Convert to seconds only when
+ * needed for playback using: seconds = samples / sampleRate
+ *
+ * Clips can be created with just waveformData (for instant visual rendering)
+ * and have audioBuffer added later when audio finishes loading.
+ */
+export declare interface AudioClip {
+    /** Unique identifier for this clip */
+    id: string;
+    /**
+     * The audio buffer containing the audio data.
+     * Optional for peaks-first rendering - can be added later.
+     * Required for playback and editing operations.
+     */
+    audioBuffer?: AudioBuffer;
+    /** Position on timeline where this clip starts (in samples at timeline sampleRate) */
+    startSample: number;
+    /** Duration of this clip (in samples) - how much of the audio buffer to play */
+    durationSamples: number;
+    /** Offset into the audio buffer where playback starts (in samples) - the "trim start" point */
+    offsetSamples: number;
+    /**
+     * Sample rate for this clip's audio.
+     * Required when audioBuffer is not provided (for peaks-first rendering).
+     * When audioBuffer is present, this should match audioBuffer.sampleRate.
+     */
+    sampleRate: number;
+    /**
+     * Total duration of the source audio in samples.
+     * Required when audioBuffer is not provided (for trim bounds calculation).
+     * When audioBuffer is present, this should equal audioBuffer.length.
+     */
+    sourceDurationSamples: number;
+    /** Optional fade in effect */
+    fadeIn?: Fade;
+    /** Optional fade out effect */
+    fadeOut?: Fade;
+    /** Clip-specific gain/volume multiplier (0.0 to 1.0+) */
+    gain: number;
+    /** Optional label/name for this clip */
+    name?: string;
+    /** Optional color for visual distinction */
+    color?: string;
+    /**
+     * Pre-computed waveform data from waveform-data.js library.
+     * When provided, the library will use this instead of computing peaks from the audioBuffer.
+     * Supports resampling to different zoom levels and slicing for clip trimming.
+     * 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;
+}
+
+/**
+ * Bits type - number of bits for peak data
+ */
+export declare type Bits = 8 | 16;
+
+/**
+ * Calculate total timeline duration in seconds from all tracks/clips.
+ * Iterates all clips, finds the furthest clip end (startSample + durationSamples),
+ * converts to seconds using each clip's sampleRate.
+ *
+ * @param tracks - Array of clip tracks
+ * @returns Duration in seconds
+ */
+export declare function calculateDuration(tracks: ClipTrack[]): number;
+
+/**
+ * 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)
+ */
+export declare function calculatePlaybackRate(params: PlaybackRateParams): number;
+
+/**
+ * Snap a split sample position to the nearest pixel boundary.
+ *
+ * @param splitSample - The sample position to snap
+ * @param samplesPerPixel - Current zoom level (samples per pixel)
+ * @returns Snapped sample position
+ */
+export declare function calculateSplitPoint(splitSample: number, samplesPerPixel: number): number;
+
+/**
+ * Viewport operations for virtual scrolling.
+ *
+ * Pure math helpers that determine which portion of the timeline
+ * is visible and which canvas chunks need to be mounted.
+ */
+/**
+ * Calculate the visible region with an overscan buffer for virtual scrolling.
+ *
+ * The buffer extends the visible range on both sides so that chunks are
+ * mounted slightly before they scroll into view, preventing flicker.
+ *
+ * @param scrollLeft - Current horizontal scroll position in pixels
+ * @param containerWidth - Width of the scroll container in pixels
+ * @param bufferRatio - Multiplier for buffer size (default 1.5x container width)
+ * @returns Object with visibleStart and visibleEnd in pixels
+ */
+export declare function calculateViewportBounds(scrollLeft: number, containerWidth: number, bufferRatio?: number): {
+    visibleStart: number;
+    visibleEnd: number;
+};
+
+/**
+ * Keep viewport centered during zoom changes.
+ * Calculates center time from old zoom, computes new pixel position at new zoom,
+ * and returns new scrollLeft clamped to >= 0.
+ *
+ * @param oldSamplesPerPixel - Previous zoom level
+ * @param newSamplesPerPixel - New zoom level
+ * @param scrollLeft - Current horizontal scroll position
+ * @param containerWidth - Viewport width in pixels
+ * @param sampleRate - Audio sample rate
+ * @param controlWidth - Width of track controls panel (defaults to 0)
+ * @returns New scrollLeft value
+ */
+export declare function calculateZoomScrollPosition(oldSamplesPerPixel: number, newSamplesPerPixel: number, scrollLeft: number, containerWidth: number, sampleRate: number, controlWidth?: number): number;
+
+/**
+ * Check whether a clip can be split at the given sample position.
+ *
+ * The split point must be strictly inside the clip (not at start or end),
+ * and both resulting clips must meet the minimum duration requirement.
+ *
+ * @param clip - The clip to check
+ * @param sample - The timeline sample position to test
+ * @param minDurationSamples - Minimum allowed clip duration in samples
+ * @returns true if the split is valid
+ */
+export declare function canSplitAt(clip: AudioClip, sample: number, minDurationSamples: number): boolean;
+
+/**
+ * Clamp a seek position to the valid range [0, duration].
+ *
+ * @param time - Requested seek time in seconds
+ * @param duration - Maximum duration in seconds
+ * @returns Clamped time value
+ */
+export declare function clampSeekPosition(time: number, duration: number): number;
+
+/** Clip duration in seconds */
+export declare function clipDurationTime(clip: AudioClip): number;
+
+/** Clip end position in seconds (start + duration) */
+export declare function clipEndTime(clip: AudioClip): number;
+
+declare interface ClipInfo {
+    buffer: AudioBuffer;
+    startTime: number;
+    duration: number;
+    offset: number;
+    fadeIn?: Fade;
+    fadeOut?: Fade;
+    gain: number;
+}
+
+/** Clip offset into source audio in seconds */
+export declare function clipOffsetTime(clip: AudioClip): number;
+
+/**
+ * Clip width in pixels at a given samplesPerPixel.
+ * Shared by Clip.tsx (container sizing) and ChannelWithProgress.tsx (progress overlay)
+ * to ensure pixel-perfect alignment. Floor-based endpoint subtraction guarantees
+ * adjacent clips have no pixel gaps.
+ */
+export declare function clipPixelWidth(startSample: number, durationSamples: number, samplesPerPixel: number): number;
+
+/**
+ * Utility: Check if two clips overlap
+ */
+export declare function clipsOverlap(clip1: AudioClip, clip2: AudioClip): boolean;
+
+/** Clip start position in seconds */
+export declare function clipStartTime(clip: AudioClip): number;
+
+/**
+ * Represents a track containing multiple audio clips
+ */
+export declare interface ClipTrack {
+    /** Unique identifier for this track */
+    id: string;
+    /** Display name for this track */
+    name: string;
+    /** Array of audio clips on this track */
+    clips: AudioClip[];
+    /** Whether this track is muted */
+    muted: boolean;
+    /** Whether this track is soloed */
+    soloed: boolean;
+    /** Track volume (0.0 to 1.0+) */
+    volume: number;
+    /** Stereo pan (-1.0 = left, 0 = center, 1.0 = right) */
+    pan: number;
+    /** Optional track color for visual distinction */
+    color?: string;
+    /** Track height in pixels (for UI) */
+    height?: number;
+    /** Optional effects function for this track */
+    effects?: TrackEffectsFunction_2;
+    /** Visualization render mode. Default: 'waveform' */
+    renderMode?: RenderMode;
+    /** Per-track spectrogram configuration (FFT size, window, frequency scale, etc.) */
+    spectrogramConfig?: SpectrogramConfig;
+    /** Per-track spectrogram color map name or custom color array */
+    spectrogramColorMap?: ColorMapValue;
+}
+
+/**
+ * Close the global AudioContext
+ * Should only be called when the application is shutting down
+ */
+export declare function closeGlobalAudioContext(): Promise<void>;
+
+/** A single color map entry: [r, g, b] or [r, g, b, a] */
+export declare type ColorMapEntry = [number, number, number] | [number, number, number, number];
+
+/** Built-in color map names */
+export declare type ColorMapName = 'viridis' | 'magma' | 'inferno' | 'grayscale' | 'igray' | 'roseus';
+
+/** Color map can be a named preset or a custom array of [r, g, b, a?] entries */
+export declare type ColorMapValue = ColorMapName | ColorMapEntry[];
+
+/**
+ * Constrain boundary trim delta for left or right edge of a clip.
+ *
+ * LEFT boundary: delta moves the left edge (positive = shrink, negative = expand)
+ * - startSample += delta, offsetSamples += delta, durationSamples -= delta
+ *
+ * RIGHT boundary: delta applied to durationSamples (positive = expand, negative = shrink)
+ * - durationSamples += delta
+ *
+ * @param clip - The clip being trimmed
+ * @param deltaSamples - Requested trim delta in samples
+ * @param boundary - Which edge is being trimmed: 'left' or 'right'
+ * @param sortedClips - All clips on the track, sorted by startSample
+ * @param clipIndex - Index of the trimmed clip in sortedClips
+ * @param minDurationSamples - Minimum allowed clip duration in samples
+ * @returns Constrained delta
+ */
+export declare function constrainBoundaryTrim(clip: AudioClip, deltaSamples: number, boundary: 'left' | 'right', sortedClips: AudioClip[], clipIndex: number, minDurationSamples: number): number;
+
+/**
+ * Constrain clip movement delta to prevent overlaps with adjacent clips
+ * and going before sample 0.
+ *
+ * @param clip - The clip being dragged
+ * @param deltaSamples - Requested movement in samples (negative = left, positive = right)
+ * @param sortedClips - All clips on the track, sorted by startSample
+ * @param clipIndex - Index of the dragged clip in sortedClips
+ * @returns Constrained delta that prevents overlaps
+ */
+export declare function constrainClipDrag(clip: AudioClip, deltaSamples: number, sortedClips: AudioClip[], clipIndex: number): number;
+
+/**
+ * Creates a new AudioClip with sensible defaults (using sample counts)
+ *
+ * For peaks-first rendering (no audioBuffer), sampleRate and sourceDurationSamples can be:
+ * - Provided explicitly via options
+ * - Derived from waveformData (sample_rate and duration properties)
+ */
+export declare function createClip(options: CreateClipOptions): AudioClip;
+
+/**
+ * Creates a new AudioClip from time-based values (convenience function)
+ * Converts seconds to samples using the audioBuffer's sampleRate or explicit sampleRate
+ *
+ * For peaks-first rendering (no audioBuffer), sampleRate and sourceDuration can be:
+ * - Provided explicitly via options
+ * - Derived from waveformData (sample_rate and duration properties)
+ */
+export declare function createClipFromSeconds(options: CreateClipOptionsSeconds): AudioClip;
+
+/**
+ * Options for creating a new audio clip (using sample counts)
+ *
+ * Either audioBuffer OR (sampleRate + sourceDurationSamples + waveformData) must be provided.
+ * Providing waveformData without audioBuffer enables peaks-first rendering.
+ */
+export declare interface CreateClipOptions {
+    /** Audio buffer - optional for peaks-first rendering */
+    audioBuffer?: AudioBuffer;
+    startSample: number;
+    durationSamples?: number;
+    offsetSamples?: number;
+    gain?: number;
+    name?: string;
+    color?: string;
+    fadeIn?: Fade;
+    fadeOut?: Fade;
+    /** Pre-computed waveform data from waveform-data.js (e.g., from BBC audiowaveform) */
+    waveformData?: WaveformDataObject;
+    /** Sample rate - required if audioBuffer not provided */
+    sampleRate?: number;
+    /** Total source audio duration in samples - required if audioBuffer not provided */
+    sourceDurationSamples?: number;
+    /** MIDI note data — passed through to the created AudioClip */
+    midiNotes?: MidiNoteData[];
+    /** MIDI channel (0-indexed). Channel 9 = GM percussion. */
+    midiChannel?: number;
+    /** MIDI program number (0-127). GM instrument for SoundFont playback. */
+    midiProgram?: number;
+}
+
+/**
+ * Options for creating a new audio clip (using seconds for convenience)
+ *
+ * Either audioBuffer OR (sampleRate + sourceDuration + waveformData) must be provided.
+ * Providing waveformData without audioBuffer enables peaks-first rendering.
+ */
+export declare interface CreateClipOptionsSeconds {
+    /** Audio buffer - optional for peaks-first rendering */
+    audioBuffer?: AudioBuffer;
+    startTime: number;
+    duration?: number;
+    offset?: number;
+    gain?: number;
+    name?: string;
+    color?: string;
+    fadeIn?: Fade;
+    fadeOut?: Fade;
+    /** Pre-computed waveform data from waveform-data.js (e.g., from BBC audiowaveform) */
+    waveformData?: WaveformDataObject;
+    /** Sample rate - required if audioBuffer not provided */
+    sampleRate?: number;
+    /** Total source audio duration in seconds - required if audioBuffer not provided */
+    sourceDuration?: number;
+    /** MIDI note data — passed through to the created AudioClip */
+    midiNotes?: MidiNoteData[];
+    /** MIDI channel (0-indexed). Channel 9 = GM percussion. */
+    midiChannel?: number;
+    /** MIDI program number (0-127). GM instrument for SoundFont playback. */
+    midiProgram?: number;
+}
+
+/**
+ * Create a control change message
+ */
+export declare function createControlChange(channel: number, cc: number, value: number): number[];
+
+/**
+ * Create a note off message
+ */
+export declare function createNoteOff(channel: number, note: number, velocity?: number): number[];
+
+/**
+ * Create a configured note on message
+ */
+export declare function createNoteOn(channel: number, note: number, velocity: number): number[];
+
+export declare function createSongramEngine(options?: SongramEngineOptions): SongramEngine;
+
+/**
+ * Creates a new Timeline with sensible defaults
+ */
+export declare function createTimeline(tracks: ClipTrack[], sampleRate?: number, options?: {
+    name?: string;
+    tempo?: number;
+    timeSignature?: {
+        numerator: number;
+        denominator: number;
+    };
+}): Timeline;
+
+export declare function createToneAdapter(options?: ToneAdapterOptions): PlayoutAdapter;
+
+/**
+ * Creates a new ClipTrack with sensible defaults
+ */
+export declare function createTrack(options: CreateTrackOptions): ClipTrack;
+
+/**
+ * Options for creating a new track
+ */
+export declare interface CreateTrackOptions {
+    name: string;
+    clips?: AudioClip[];
+    muted?: boolean;
+    soloed?: boolean;
+    volume?: number;
+    pan?: number;
+    color?: string;
+    height?: number;
+    spectrogramConfig?: SpectrogramConfig;
+    spectrogramColorMap?: ColorMapValue;
+}
+
+/**
+ * Convert a dB value to a normalized range.
+ *
+ * Maps dB values linearly: floor → 0, 0 dB → 1.
+ * Values above 0 dB map to > 1 (e.g., +5 dB → 1.05 with default floor).
+ *
+ * @param dB - Decibel value (typically -Infinity to +5)
+ * @param floor - Minimum dB value mapped to 0. Default: -100 (Firefox compat)
+ * @returns Normalized value (0 at floor, 1 at 0 dB, >1 above 0 dB)
+ */
+export declare function dBToNormalized(dB: number, floor?: number): number;
+
+export declare interface EffectPlugin extends EnginePlugin {
+    kind: 'effect';
+}
+
+export declare type EffectsFunction = (masterGainNode: Volume, destination: ToneAudioNode, isOffline: boolean) => void | (() => void);
+
+/**
+ * Events emitted by PlaylistEngine.
+ */
+export declare interface EngineEvents {
+    statechange: (state: EngineState) => void;
+    timeupdate: (time: number) => void;
+    play: () => void;
+    pause: () => void;
+    stop: () => void;
+}
+
+export declare interface EnginePlugin {
+    id: string;
+    kind?: SongramPluginKind;
+    setup?: (context: SongramPluginContext) => void | (() => void | Promise<void>) | Promise<void>;
+}
+
+/**
+ * Snapshot of playlist engine state, emitted on every state change.
+ */
+export declare interface EngineState {
+    tracks: ClipTrack[];
+    /** Monotonic counter incremented on any tracks mutation (setTracks, addTrack, removeTrack, moveClip, trimClip, splitClip). */
+    tracksVersion: number;
+    duration: number;
+    currentTime: number;
+    isPlaying: boolean;
+    samplesPerPixel: number;
+    sampleRate: number;
+    selectedTrackId: string | null;
+    zoomIndex: number;
+    canZoomIn: boolean;
+    canZoomOut: boolean;
+    /** Start of the audio selection range. Guaranteed: selectionStart <= selectionEnd. */
+    selectionStart: number;
+    /** End of the audio selection range. Guaranteed: selectionStart <= selectionEnd. */
+    selectionEnd: number;
+    /** Master output volume, 0.0–1.0. */
+    masterVolume: number;
+    /** Start of the loop region. Guaranteed: loopStart <= loopEnd. */
+    loopStart: number;
+    /** End of the loop region. Guaranteed: loopStart <= loopEnd. */
+    loopEnd: number;
+    /** Whether loop playback is active. */
+    isLoopEnabled: boolean;
+}
+
+export declare class EventBus<TEvents extends object> {
+    private readonly emitter;
+    on<K extends keyof TEvents>(event: K, listener: TEvents[K]): void;
+    off<K extends keyof TEvents>(event: K, listener: TEvents[K]): void;
+    once<K extends keyof TEvents>(event: K, listener: TEvents[K]): void;
+    emit<K extends keyof TEvents>(event: K, ...args: TEvents[K] extends (...params: infer TArgs) => void ? TArgs : never): void;
+    removeAllListeners(): void;
+}
+
+declare type EventName = keyof EngineEvents;
+
+/**
+ * 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.
+ */
+export declare function extractLoopAndEnvelope(params: LoopAndEnvelopeParams): Omit<SoundFontSample, 'buffer' | 'playbackRate'>;
+
+/**
+ * Simple fade configuration
+ */
+export declare interface Fade {
+    /** Duration of the fade in seconds */
+    duration: number;
+    /** Type of fade curve (default: 'linear') */
+    type?: FadeType_2;
+}
+
+/**
+ * Simple fade configuration - just duration and type
+ */
+export declare interface FadeConfig {
+    /** Duration of the fade in seconds */
+    duration: number;
+    /** Type of fade curve (default: 'linear') */
+    type?: FadeType;
+}
+
+export declare type FadeType = 'linear' | 'logarithmic' | 'exponential' | 'sCurve';
+
+declare type FadeType_2 = 'logarithmic' | 'linear' | 'sCurve' | 'exponential';
+
+/**
+ * Spectrogram Types
+ *
+ * Types for frequency-domain visualization of audio data.
+ */
+/** Valid FFT sizes (must be power of 2, 256–8192) */
+export declare type FFTSize = 256 | 512 | 1024 | 2048 | 4096 | 8192;
+
+/**
+ * Find the zoom level index closest to a given samplesPerPixel.
+ * Returns exact match if found, otherwise the index whose value is
+ * nearest to the target (by absolute difference).
+ *
+ * @param targetSamplesPerPixel - The samplesPerPixel value to find
+ * @param zoomLevels - Array of available zoom levels (samplesPerPixel values)
+ * @returns Index into the zoomLevels array
+ */
+export declare function findClosestZoomIndex(targetSamplesPerPixel: number, zoomLevels: number[]): number;
+
+export declare function findGaps(track: ClipTrack): Gap[];
+
+/**
+ * Convert a linear gain value (0-1+) to normalized 0-1 via dB.
+ *
+ * Combines gain-to-dB (20 * log10) with dBToNormalized for a consistent
+ * mapping from raw AudioWorklet peak/RMS values to the 0-1 range used
+ * by UI meter components.
+ *
+ * @param gain - Linear gain value (typically 0 to 1, can exceed 1)
+ * @param floor - Minimum dB value mapped to 0. Default: -100
+ * @returns Normalized value (0 at silence/floor, 1 at 0 dB, >1 above 0 dB)
+ */
+export declare function gainToNormalized(gain: number, floor?: number): number;
+
+/**
+ * Utility: Find gaps between clips (silent regions)
+ */
+export declare interface Gap {
+    startSample: number;
+    endSample: number;
+    durationSamples: number;
+}
+
+/**
+ * Utility: Get all clips at a specific sample position
+ */
+export declare function getClipsAtSample(track: ClipTrack, sample: number): AudioClip[];
+
+/**
+ * Utility: Get all clips within a sample range
+ */
+export declare function getClipsInRange(track: ClipTrack, startSample: number, endSample: number): AudioClip[];
+
+/**
+ * Get a numeric generator value from a zone map.
+ */
+export declare function getGeneratorValue(generators: ZoneMap<Generator_2>, type: GeneratorType): number | undefined;
+
+/**
+ * Get or create the global AudioContext
+ * Uses Tone.js Context for cross-browser compatibility
+ * @returns The global AudioContext instance (rawContext from Tone.Context)
+ */
+export declare function getGlobalAudioContext(): AudioContext;
+
+/**
+ * Get the current state of the global AudioContext
+ * @returns The AudioContext state ('suspended', 'running', or 'closed')
+ */
+export declare function getGlobalAudioContextState(): AudioContextState;
+
+/**
+ * Get the global Tone.js Context
+ * This is the main context for cross-browser audio operations.
+ * Use context.createAudioWorkletNode(), context.createMediaStreamSource(), etc.
+ * @returns The Tone.js Context instance
+ */
+export declare function getGlobalContext(): Context;
+
+/**
+ * @deprecated Use getGlobalContext() instead
+ * Get the Tone.js Context's rawContext typed as IAudioContext
+ * @returns The rawContext cast as IAudioContext
+ */
+export declare function getGlobalToneContext(): Context;
+
+/**
+ * Get GM instrument name from program number
+ */
+export declare function getInstrumentName(programNumber: number): string;
+
+/**
+ * MediaStreamSource Manager
+ *
+ * Manages MediaStreamAudioSourceNode instances to ensure only one source
+ * is created per MediaStream per AudioContext.
+ *
+ * Web Audio API constraint: You can only create one MediaStreamAudioSourceNode
+ * per MediaStream per AudioContext. Multiple attempts will fail or disconnect
+ * previous sources.
+ *
+ * This manager ensures a single source is shared across multiple consumers
+ * (e.g., AnalyserNode for VU meter, AudioWorkletNode for recording).
+ *
+ * NOTE: With Tone.js Context, you can also use context.createMediaStreamSource()
+ * directly, which handles cross-browser compatibility internally.
+ */
+/**
+ * Get or create a MediaStreamAudioSourceNode for the given stream
+ *
+ * @param stream - The MediaStream to create a source for
+ * @returns MediaStreamAudioSourceNode that can be connected to multiple nodes
+ *
+ * @example
+ * ```typescript
+ * const source = getMediaStreamSource(stream);
+ *
+ * // Multiple consumers can connect to the same source
+ * source.connect(analyserNode);  // For VU meter
+ * source.connect(workletNode);   // For recording
+ * ```
+ */
+export declare function getMediaStreamSource(stream: MediaStream): MediaStreamAudioSourceNode;
+
+/**
+ * Get list of connected MIDI input devices
+ */
+export declare function getMidiInputs(access: MIDIAccess): MidiInputDevice[];
+
+/**
+ * Get list of connected MIDI output devices
+ */
+export declare function getMidiOutputs(access: MIDIAccess): MidiOutputDevice[];
+
+/**
+ * Fade utilities for Web Audio API
+ *
+ * Applies fade in/out envelopes to AudioParam (typically gain)
+ * using various curve types.
+ */
+export declare function getUnderlyingAudioParam(signal: unknown): AudioParam | undefined;
+
+/**
+ * Get an array of chunk indices that overlap the visible viewport.
+ *
+ * Chunks are fixed-width segments of the total timeline width. Only chunks
+ * that intersect [visibleStart, visibleEnd) are included. The last chunk
+ * may be narrower than chunkWidth if totalWidth is not evenly divisible.
+ *
+ * @param totalWidth - Total width of the timeline in pixels
+ * @param chunkWidth - Width of each chunk in pixels
+ * @param visibleStart - Left edge of the visible region in pixels
+ * @param visibleEnd - Right edge of the visible region in pixels
+ * @returns Array of chunk indices (0-based) that are visible
+ */
+export declare function getVisibleChunkIndices(totalWidth: number, chunkWidth: number, visibleStart: number, visibleEnd: number): number[];
+
+/**
+ * Check if a MediaStreamSource exists for the given stream
+ *
+ * @param stream - The MediaStream to check
+ * @returns true if a source exists for this stream
+ */
+export declare function hasMediaStreamSource(stream: MediaStream): boolean;
+
+export declare interface InstrumentPlugin extends EnginePlugin {
+    kind: 'instrument';
+}
+
+/**
+ * Convert Int16Array sample data to Float32Array.
+ * SF2 samples are 16-bit signed integers; Web Audio needs Float32 [-1, 1].
+ */
+export declare function int16ToFloat32(samples: Int16Array): Float32Array;
+
+export declare enum InteractionState {
+    Cursor = "cursor",
+    Select = "select",
+    Shift = "shift",
+    FadeIn = "fadein",
+    FadeOut = "fadeout"
+}
+
+/**
+ * Check if Web MIDI API is supported
+ */
+export declare function isWebMidiSupported(): boolean;
+
+/**
+ * Input parameters for loop and envelope extraction.
+ */
+export declare interface LoopAndEnvelopeParams {
+    /** SF2 generators zone map */
+    generators: ZoneMap<Generator_2>;
+    /** Sample header with loop points and sample rate */
+    header: {
+        startLoop: number;
+        endLoop: number;
+        sampleRate: number;
+    };
+}
+
+/**
+ * Maximum width in CSS pixels for a single canvas chunk.
+ * Canvas elements are split into chunks of this width to enable
+ * horizontal virtual scrolling — only visible chunks are mounted.
+ */
+export declare const MAX_CANVAS_WIDTH = 1000;
+
+export declare const MIDI_CC: {
+    readonly MODULATION: 1;
+    readonly BREATH: 2;
+    readonly VOLUME: 7;
+    readonly PAN: 10;
+    readonly EXPRESSION: 11;
+    readonly SUSTAIN: 64;
+    readonly PORTAMENTO: 65;
+    readonly SOSTENUTO: 66;
+    readonly SOFT_PEDAL: 67;
+    readonly ALL_SOUND_OFF: 120;
+    readonly RESET_ALL: 121;
+    readonly ALL_NOTES_OFF: 123;
+};
+
+export declare const MIDI_COMMANDS: {
+    readonly NOTE_OFF: 8;
+    readonly NOTE_ON: 9;
+    readonly POLY_AFTERTOUCH: 10;
+    readonly CONTROL_CHANGE: 11;
+    readonly PROGRAM_CHANGE: 12;
+    readonly CHANNEL_AFTERTOUCH: 13;
+    readonly PITCH_BEND: 14;
+};
+
+export declare interface MidiClipInfo {
+    notes: MidiNoteData[];
+    startTime: number;
+    duration: number;
+    offset: number;
+}
+
+/**
+ * MIDI Controller Manager - handles connections and message routing
+ */
+export declare class MidiController {
+    private access;
+    private activeInputId;
+    private messageCallbacks;
+    private stateChangeCallbacks;
+    /**
+     * Initialize MIDI access
+     */
+    init(sysex?: boolean): Promise<boolean>;
+    /**
+     * Check if initialized
+     */
+    get isInitialized(): boolean;
+    /**
+     * Get available input devices
+     */
+    getInputs(): MidiInputDevice[];
+    /**
+     * Get available output devices
+     */
+    getOutputs(): MidiOutputDevice[];
+    /**
+     * Connect to a specific MIDI input
+     */
+    connectInput(deviceId: string): boolean;
+    /**
+     * Connect to the first available MIDI input
+     */
+    connectFirstInput(): boolean;
+    /**
+     * Disconnect from current MIDI input
+     */
+    disconnectInput(): void;
+    /**
+     * Get the currently connected input ID
+     */
+    get connectedInputId(): string | null;
+    /**
+     * Subscribe to MIDI messages
+     */
+    onMessage(callback: MidiMessageCallback): () => void;
+    /**
+     * Subscribe to device state changes (connect/disconnect)
+     */
+    onStateChange(callback: () => void): () => void;
+    /**
+     * Send MIDI message to an output device
+     */
+    sendMessage(deviceId: string, data: number[]): boolean;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}
+
+/**
+ * Web MIDI API utilities for connecting MIDI controllers
+ *
+ * Enables real-time MIDI input from hardware controllers for
+ * live playing, recording, and DAW control.
+ */
+export declare interface MidiInputDevice {
+    id: string;
+    name: string;
+    manufacturer: string;
+    state: 'connected' | 'disconnected';
+}
+
+export declare interface MidiMessage {
+    /** MIDI command (note on, note off, CC, etc.) */
+    command: number;
+    /** MIDI channel (0-15) */
+    channel: number;
+    /** Note number or CC number */
+    data1: number;
+    /** Velocity or CC value */
+    data2: number;
+    /** Raw MIDI bytes */
+    raw: Uint8Array;
+    /** Timestamp */
+    timestamp: number;
+}
+
+export declare type MidiMessageCallback = (message: MidiMessage) => void;
+
+/**
+ * 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.
+ */
+export 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;
+}
+
+/**
+ * MIDI note data for clips that play MIDI instead of audio.
+ * Matches the MidiNoteData interface from songram-daw core types.
+ */
+declare interface MidiNoteData_2 {
+    /** 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. */
+    channel?: number;
+}
+
+/**
+ * Convert MIDI note number to note name with octave
+ * @param midiNote - MIDI note number (0-127)
+ * @returns Note name like "C4", "F#3", "Bb5"
+ */
+export declare function midiNoteToName(midiNote: number): string;
+
+export declare interface MidiOutputDevice {
+    id: string;
+    name: string;
+    manufacturer: string;
+    state: 'connected' | 'disconnected';
+}
+
+/**
+ * MIDI track that always creates both melodic and percussion synths.
+ * Per-note routing uses the `channel` field on each MidiNoteData:
+ * channel 9 → percussion synths, all others → melodic PolySynth.
+ * This enables flattened tracks (mixed channels) to play correctly.
+ */
+export declare class MidiToneTrack implements PlayableTrack {
+    private scheduledClips;
+    private synth;
+    private kickSynth;
+    private snareSynth;
+    private cymbalSynth;
+    private tomSynth;
+    private volumeNode;
+    private panNode;
+    private muteGain;
+    private track;
+    private effectsCleanup?;
+    constructor(options: MidiToneTrackOptions);
+    /**
+     * Trigger a note using the appropriate synth.
+     * Routes per-note: channel 9 → percussion synths, others → melodic PolySynth.
+     */
+    private triggerNote;
+    private gainToDb;
+    /**
+     * No-op for MIDI — schedule guard is for AudioBufferSourceNode ghost tick prevention.
+     * Tone.Part handles its own scheduling relative to Transport.
+     */
+    setScheduleGuardOffset(_offset: number): void;
+    /**
+     * For MIDI, mid-clip sources are notes that should already be sounding.
+     * We trigger them with their remaining duration.
+     */
+    startMidClipSources(transportOffset: number, audioContextTime: number): void;
+    /**
+     * Stop all sounding notes and cancel scheduled Part events.
+     */
+    stopAllSources(): void;
+    /**
+     * No-op for MIDI — MIDI uses note velocity, not gain fades.
+     */
+    prepareFades(_when: number, _offset: number): void;
+    /**
+     * No-op for MIDI — no fade automation to cancel.
+     */
+    cancelFades(): void;
+    setVolume(gain: number): void;
+    setPan(pan: number): void;
+    setMute(muted: boolean): void;
+    setSolo(soloed: boolean): void;
+    dispose(): void;
+    get id(): string;
+    get duration(): number;
+    get muted(): boolean;
+    get startTime(): number;
+}
+
+export declare interface MidiToneTrackOptions {
+    clips: MidiClipInfo[];
+    track: Track;
+    effects?: TrackEffectsFunction;
+    destination?: ToneAudioNode;
+    synthOptions?: Partial<SynthOptions>;
+}
+
+/**
+ * Convert a normalized value back to dB.
+ *
+ * Maps linearly: 0 → floor, 1 → 0 dB.
+ * Values above 1 map to positive dB (e.g., 1.05 → +5 dB with default floor).
+ *
+ * @param normalized - Normalized value (0 = floor, 1 = 0 dB)
+ * @param floor - Minimum dB value (maps from 0). Must be negative. Default: -100
+ * @returns dB value (floor at 0, 0 dB at 1, positive dB above 1)
+ */
+export declare function normalizedToDb(normalized: number, floor?: number): number;
+
+/**
+ * Convert note name to MIDI note number
+ * @param name - Note name like "C4", "F#3", "Bb5"
+ * @returns MIDI note number (0-127)
+ */
+export declare function noteNameToMidi(name: string): number;
+
+/**
+ * Complete parsed MIDI file result
+ */
+export declare interface ParsedMidi {
+    /** Parsed tracks (one per channel or merged if flatten=true) */
+    tracks: ParsedMidiTrack[];
+    /** Total duration in seconds */
+    duration: number;
+    /** Song name from MIDI header */
+    name: string;
+    /** Tempo in BPM (from first tempo event, default 120) */
+    bpm: number;
+    /** Time signature [numerator, denominator] */
+    timeSignature: [number, number];
+}
+
+/**
+ * Parsed MIDI track with notes and metadata
+ */
+export declare interface ParsedMidiTrack {
+    /** Track name from MIDI file or generated */
+    name: string;
+    /** Notes in MidiNoteData format */
+    notes: MidiNoteData_2[];
+    /** Duration in seconds */
+    duration: number;
+    /** MIDI channel (0-indexed, 9 = percussion) */
+    channel: number;
+    /** GM instrument name */
+    instrument: string;
+    /** GM program number (0-127) */
+    programNumber: number;
+}
+
+/**
+ * Parse a MIDI file from an ArrayBuffer
+ *
+ * @param data - MIDI file as ArrayBuffer
+ * @param options - Parsing options
+ * @returns Parsed MIDI data with tracks and metadata
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch('/song.mid');
+ * const buffer = await response.arrayBuffer();
+ * const midi = parseMidiFile(buffer);
+ * console.log(midi.tracks.length, 'tracks');
+ * ```
+ */
+export declare function parseMidiFile(data: ArrayBuffer, options?: ParseMidiOptions): ParsedMidi;
+
+/**
+ * Parse a raw MIDI message into structured data
+ */
+export declare function parseMidiMessage(data: Uint8Array, timestamp: number): MidiMessage;
+
+export declare interface ParseMidiOptions {
+    /** Merge all MIDI tracks into one (default: false) */
+    flatten?: boolean;
+}
+
+/**
+ * Fetch and parse a MIDI file from a URL
+ *
+ * @param url - URL to MIDI file
+ * @param options - Parsing options
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns Promise resolving to parsed MIDI data
+ *
+ * @example
+ * ```typescript
+ * const midi = await parseMidiUrl('/songs/demo.mid');
+ * for (const track of midi.tracks) {
+ *   console.log(track.name, track.notes.length, 'notes');
+ * }
+ * ```
+ */
+export declare function parseMidiUrl(url: string, options?: ParseMidiOptions, signal?: AbortSignal): Promise<ParsedMidi>;
+
+/**
+ * PeakData - result of peak extraction
+ */
+export declare interface PeakData {
+    /** Number of peak pairs extracted */
+    length: number;
+    /** Array of peak data for each channel (interleaved min/max) */
+    data: Peaks[];
+    /** Bit depth of peak data */
+    bits: Bits;
+}
+
+/**
+ * Peaks type - represents a typed array of interleaved min/max peak data
+ */
+export declare type Peaks = Int8Array | Int16Array;
+
+export declare function pixelsToSamples(pixels: number, samplesPerPixel: number): number;
+
+export declare function pixelsToSeconds(pixels: number, samplesPerPixel: number, sampleRate: number): number;
+
+/**
+ * Shared interface for tracks managed by TonePlayout.
+ * Both ToneTrack (audio) and MidiToneTrack (MIDI) implement this,
+ * allowing TonePlayout to manage them uniformly.
+ */
+export declare interface PlayableTrack {
+    id: string;
+    startTime: number;
+    muted: boolean;
+    duration: number;
+    stopAllSources(): void;
+    startMidClipSources(offset: number, time: number): void;
+    setScheduleGuardOffset(offset: number): void;
+    prepareFades(when: number, offset: number): void;
+    cancelFades(): void;
+    setVolume(gain: number): void;
+    setPan(pan: number): void;
+    setMute(muted: boolean): void;
+    setSolo(soloed: boolean): void;
+    dispose(): void;
+}
+
+/**
+ * Input parameters for playback rate calculation.
+ */
+export declare interface PlaybackRateParams {
+    /** Target MIDI note number (0-127) */
+    midiNote: number;
+    /** OverridingRootKey generator value, or undefined if not set */
+    overrideRootKey: number | undefined;
+    /** sample.header.originalPitch (255 means unpitched) */
+    originalPitch: number;
+    /** CoarseTune generator value in semitones (default 0) */
+    coarseTune: number;
+    /** FineTune generator value in cents (default 0) */
+    fineTune: number;
+    /** sample.header.pitchCorrection in cents (default 0) */
+    pitchCorrection: number;
+}
+
+export declare interface PlaylistConfig {
+    samplesPerPixel?: number;
+    waveHeight?: number;
+    container?: HTMLElement;
+    isAutomaticScroll?: boolean;
+    timescale?: boolean;
+    colors?: {
+        waveOutlineColor?: string;
+        waveFillColor?: string;
+        waveProgressColor?: string;
+    };
+    controls?: {
+        show?: boolean;
+        width?: number;
+    };
+    zoomLevels?: number[];
+}
+
+export declare class PlaylistEngine {
+    private _tracks;
+    private _currentTime;
+    private _playStartPosition;
+    private _isPlaying;
+    private _selectedTrackId;
+    private _sampleRate;
+    private _zoomLevels;
+    private _zoomIndex;
+    private _selectionStart;
+    private _selectionEnd;
+    private _masterVolume;
+    private _loopStart;
+    private _loopEnd;
+    private _isLoopEnabled;
+    private _tracksVersion;
+    private _adapter;
+    private _animFrameId;
+    private _disposed;
+    private _listeners;
+    constructor(options?: PlaylistEngineOptions);
+    getState(): EngineState;
+    setTracks(tracks: ClipTrack[]): void;
+    addTrack(track: ClipTrack): void;
+    removeTrack(trackId: string): void;
+    selectTrack(trackId: string | null): void;
+    moveClip(trackId: string, clipId: string, deltaSamples: number): void;
+    splitClip(trackId: string, clipId: string, atSample: number): void;
+    trimClip(trackId: string, clipId: string, boundary: 'left' | 'right', deltaSamples: number): void;
+    init(): Promise<void>;
+    play(startTime?: number, endTime?: number): void;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    setMasterVolume(volume: number): void;
+    getCurrentTime(): number;
+    setSelection(start: number, end: number): void;
+    setLoopRegion(start: number, end: number): void;
+    setLoopEnabled(enabled: boolean): void;
+    setTrackVolume(trackId: string, volume: number): void;
+    setTrackMute(trackId: string, muted: boolean): void;
+    setTrackSolo(trackId: string, soloed: boolean): void;
+    setTrackPan(trackId: string, pan: number): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    setZoomLevel(samplesPerPixel: number): void;
+    on<K extends EventName>(event: K, listener: EngineEvents[K]): void;
+    off<K extends EventName>(event: K, listener: EngineEvents[K]): void;
+    dispose(): void;
+    private _emit;
+    /**
+     * Returns whether the current playback position is before loopEnd.
+     * Used by setLoopEnabled/setLoopRegion during playback — if past loopEnd,
+     * Transport loop stays off so playback continues to the end.
+     * Note: play() uses an inline check instead — _isPlaying is still false
+     * when play() runs, and this method returns true unconditionally when
+     * not playing.
+     */
+    private _isBeforeLoopEnd;
+    private _emitStateChange;
+    private _startTimeUpdateLoop;
+    private _stopTimeUpdateLoop;
+}
+
+/**
+ * Configuration options for PlaylistEngine constructor.
+ */
+export declare interface PlaylistEngineOptions {
+    adapter?: PlayoutAdapter;
+    sampleRate?: number;
+    samplesPerPixel?: number;
+    zoomLevels?: number[];
+}
+
+/**
+ * Interface for pluggable audio playback adapters.
+ * Implement this to connect PlaylistEngine to any audio backend
+ * (Tone.js, openDAW, HTMLAudioElement, etc.)
+ */
+export declare interface PlayoutAdapter {
+    init(): Promise<void>;
+    setTracks(tracks: ClipTrack[]): void;
+    /** Incrementally add a single track without rebuilding the entire playout. */
+    addTrack?(track: ClipTrack): void;
+    play(startTime: number, endTime?: number): void;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    getCurrentTime(): number;
+    isPlaying(): boolean;
+    setMasterVolume(volume: number): void;
+    setTrackVolume(trackId: string, volume: number): void;
+    setTrackMute(trackId: string, muted: boolean): void;
+    setTrackSolo(trackId: string, soloed: boolean): void;
+    setTrackPan(trackId: string, pan: number): void;
+    setLoop(enabled: boolean, start: number, end: number): void;
+    dispose(): void;
+}
+
+export declare interface PlayoutState {
+    isPlaying: boolean;
+    isPaused: boolean;
+    cursor: number;
+    duration: number;
+}
+
+export declare class PluginHost {
+    private readonly plugins;
+    private readonly disposers;
+    private readonly context;
+    constructor(context: SongramPluginContext);
+    getAll(): EnginePlugin[];
+    register(plugin: EnginePlugin): Promise<void>;
+    unregister(pluginId: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+
+/** Default PPQN matching Tone.js Transport (192 ticks per quarter note) */
+export declare const PPQN = 192;
+
+/**
+ * Manually release a MediaStreamSource
+ *
+ * Normally you don't need to call this - cleanup happens automatically
+ * when the stream ends. Only call this if you need to force cleanup.
+ *
+ * @param stream - The MediaStream to release the source for
+ */
+export declare function releaseMediaStreamSource(stream: MediaStream): void;
+
+/**
+ * Props passed to the renderAnnotationItem function for custom rendering.
+ */
+export declare interface RenderAnnotationItemProps {
+    annotation: AnnotationData;
+    index: number;
+    isActive: boolean;
+    onClick: () => void;
+    formatTime: (seconds: number) => string;
+}
+
+/** Render mode for a track's visualization */
+export declare type RenderMode = 'waveform' | 'spectrogram' | 'both' | 'piano-roll';
+
+/**
+ * Request Web MIDI API access
+ * @param sysex - Whether to request SysEx access (default: false)
+ */
+export declare function requestMidiAccess(sysex?: boolean): Promise<MIDIAccess | null>;
+
+/**
+ * Resume the global AudioContext if it's suspended
+ * Should be called in response to a user gesture (e.g., button click)
+ * @returns Promise that resolves when context is running
+ */
+export declare function resumeGlobalAudioContext(): Promise<void>;
+
+export declare function samplesToPixels(samples: number, samplesPerPixel: number): number;
+
+export declare function samplesToSeconds(samples: number, sampleRate: number): number;
+
+/** Convert sample count to PPQN ticks. Inverse of ticksToSamples. */
+export declare function samplesToTicks(samples: number, bpm: number, sampleRate: number, ppqn?: number): number;
+
+export declare function secondsToPixels(seconds: number, samplesPerPixel: number, sampleRate: number): number;
+
+export declare function secondsToSamples(seconds: number, sampleRate: number): number;
+
+/**
+ * Determine whether a scroll change is large enough to warrant
+ * recalculating the viewport and re-rendering chunks.
+ *
+ * Small scroll movements are ignored to avoid excessive recomputation
+ * during smooth scrolling.
+ *
+ * @param oldScrollLeft - Previous scroll position in pixels
+ * @param newScrollLeft - Current scroll position in pixels
+ * @param threshold - Minimum pixel delta to trigger an update (default 100)
+ * @returns true if the scroll delta meets or exceeds the threshold
+ */
+export declare function shouldUpdateViewport(oldScrollLeft: number, newScrollLeft: number, threshold?: number): boolean;
+
+/** Snap a tick position to the nearest grid line (rounds to nearest). */
+export declare function snapToGrid(ticks: number, gridSizeTicks: number): number;
+
+export declare class SongramEngine {
+    readonly events: EventBus<SongramEngineEventMap>;
+    readonly plugins: PluginHost;
+    readonly transport: {
+        play: (startTime?: number, endTime?: number) => void;
+        pause: () => void;
+        stop: () => void;
+        seek: (time: number) => void;
+        getCurrentTime: () => number;
+    };
+    readonly tracks: {
+        set: (tracks: ClipTrack[]) => void;
+        add: (track: ClipTrack) => void;
+        remove: (trackId: string) => void;
+        select: (trackId: string | null) => void;
+    };
+    readonly state: {
+        getSnapshot: () => EngineState;
+    };
+    readonly playlist: PlaylistEngine;
+    private readonly initialPlugins;
+    private readonly handleStateChange;
+    private readonly handleTimeUpdate;
+    private readonly handlePlay;
+    private readonly handlePause;
+    private readonly handleStop;
+    constructor(options?: SongramEngineOptions);
+    init(): Promise<void>;
+    registerPlugin(plugin: EnginePlugin): Promise<void>;
+    unregisterPlugin(pluginId: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+
+export declare interface SongramEngineEventMap {
+    ready: () => void;
+    dispose: () => void;
+    statechange: (state: unknown) => void;
+    timeupdate: (time: number) => void;
+    play: () => void;
+    pause: () => void;
+    stop: () => void;
+    'transport:seek': (time: number) => void;
+    'tracks:set': (trackIds: string[]) => void;
+    'tracks:add': (trackId: string) => void;
+    'tracks:remove': (trackId: string) => void;
+    'plugins:registered': (pluginId: string) => void;
+    'plugins:unregistered': (pluginId: string) => void;
+    'assistant:request': (payload: AssistantRequestEvent) => void;
+}
+
+export declare interface SongramEngineOptions extends Omit<PlaylistEngineOptions, 'adapter'> {
+    adapter?: PlayoutAdapter;
+    audio?: ToneAdapterOptions;
+    plugins?: EnginePlugin[];
+}
+
+export declare interface SongramPluginContext {
+    events: EventBus<SongramEngineEventMap>;
+    requestAssistant: (assistantId: string, action: string, payload?: unknown) => void;
+}
+
+export declare type SongramPluginKind = 'general' | 'effect' | 'instrument' | 'assistant';
+
+/**
+ * Utility: Sort clips by startSample
+ */
+export declare function sortClipsByTime(clips: AudioClip[]): AudioClip[];
+
+/**
+ * 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
+ */
+export 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;
+    /**
+     * Convert Int16Array sample data to an AudioBuffer.
+     * Uses the extracted int16ToFloat32 for the conversion, then copies into an AudioBuffer.
+     */
+    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.
+ */
+export 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;
+}
+
+/**
+ * MIDI track that uses SoundFont samples for playback.
+ *
+ * Instead of PolySynth synthesis, each note triggers the correct instrument
+ * sample from an SF2 file, pitch-shifted via AudioBufferSourceNode.playbackRate.
+ *
+ * Audio graph per note:
+ *   AudioBufferSourceNode (native, one-shot, pitch-shifted)
+ *     → GainNode (native, per-note velocity)
+ *     → Volume.input (Tone.js, shared per-track)
+ *     → Panner → muteGain → effects/destination
+ */
+export declare class SoundFontToneTrack implements PlayableTrack {
+    /** Rate-limit missing sample warnings — one per class lifetime */
+    private static _missingSampleWarned;
+    private scheduledClips;
+    private activeSources;
+    private soundFontCache;
+    private programNumber;
+    private bankNumber;
+    private volumeNode;
+    private panNode;
+    private muteGain;
+    private track;
+    private effectsCleanup?;
+    constructor(options: SoundFontToneTrackOptions);
+    /**
+     * Trigger a note by creating a native AudioBufferSourceNode from the SoundFont cache.
+     *
+     * Per-note routing: channel 9 → bank 128 (drums), others → bank 0 with programNumber.
+     */
+    private triggerNote;
+    private gainToDb;
+    /**
+     * No-op — Tone.Part handles scheduling internally, no ghost tick guard needed.
+     */
+    setScheduleGuardOffset(_offset: number): void;
+    /**
+     * Start notes that should already be sounding at the current transport offset.
+     */
+    startMidClipSources(transportOffset: number, audioContextTime: number): void;
+    /**
+     * Stop all active AudioBufferSourceNodes.
+     */
+    stopAllSources(): void;
+    /** No-op for MIDI — MIDI uses note velocity, not gain fades. */
+    prepareFades(_when: number, _offset: number): void;
+    /** No-op for MIDI — no fade automation to cancel. */
+    cancelFades(): void;
+    setVolume(gain: number): void;
+    setPan(pan: number): void;
+    setMute(muted: boolean): void;
+    setSolo(soloed: boolean): void;
+    dispose(): void;
+    get id(): string;
+    get duration(): number;
+    get muted(): boolean;
+    get startTime(): number;
+}
+
+export declare interface SoundFontToneTrackOptions {
+    clips: MidiClipInfo[];
+    track: Track;
+    soundFontCache: SoundFontCache;
+    /** GM program number (0-127) for melodic instruments */
+    programNumber?: number;
+    /** Whether this track uses percussion bank (channel 9) */
+    isPercussion?: boolean;
+    effects?: TrackEffectsFunction;
+    destination?: ToneAudioNode;
+}
+
+/** Subset of SpectrogramConfig fields that affect FFT computation (used for cache keys) */
+export declare type SpectrogramComputeConfig = Pick<SpectrogramConfig, 'fftSize' | 'hopSize' | 'windowFunction' | 'alpha' | 'zeroPaddingFactor'>;
+
+/**
+ * Configuration for spectrogram computation and rendering.
+ */
+export declare interface SpectrogramConfig {
+    /** FFT size: 256–8192, must be power of 2. Default: 2048 */
+    fftSize?: FFTSize;
+    /** Hop size between frames in samples. Default: fftSize / 4 */
+    hopSize?: number;
+    /** Window function applied before FFT. Default: 'hann' */
+    windowFunction?: 'hann' | 'hamming' | 'blackman' | 'rectangular' | 'bartlett' | 'blackman-harris';
+    /** Window function parameter (0-1), used by some window functions */
+    alpha?: number;
+    /** Frequency axis scale. Default: 'mel' */
+    frequencyScale?: 'linear' | 'logarithmic' | 'mel' | 'bark' | 'erb';
+    /** Minimum frequency in Hz. Default: 0 */
+    minFrequency?: number;
+    /** Maximum frequency in Hz. Default: sampleRate / 2 */
+    maxFrequency?: number;
+    /** Display brightness boost in dB. Default: 20 */
+    gainDb?: number;
+    /** Signal range in dB. Default: 80 */
+    rangeDb?: number;
+    /** Zero padding factor: actual FFT length = fftSize * zeroPaddingFactor. Default: 2 */
+    zeroPaddingFactor?: number;
+    /** Show frequency axis labels. Default: false */
+    labels?: boolean;
+    /** Label text color */
+    labelsColor?: string;
+    /** Label background color */
+    labelsBackground?: string;
+}
+
+/**
+ * Computed spectrogram data ready for rendering.
+ */
+export declare interface SpectrogramData {
+    /** Actual FFT length used for computation (includes zero padding) */
+    fftSize: number;
+    /** Original analysis window size before zero padding */
+    windowSize: number;
+    /** Number of frequency bins (fftSize / 2) */
+    frequencyBinCount: number;
+    /** Sample rate of the source audio */
+    sampleRate: number;
+    /** Hop size between FFT frames (in samples) */
+    hopSize: number;
+    /** Number of time frames */
+    frameCount: number;
+    /** dB values: frameCount * frequencyBinCount Float32Array (row-major, frame × bin) */
+    data: Float32Array;
+    /** Display brightness boost in dB */
+    gainDb: number;
+    /** Signal range in dB */
+    rangeDb: number;
+}
+
+/** Subset of SpectrogramConfig fields that only affect display/rendering (not FFT computation) */
+export declare type SpectrogramDisplayConfig = Pick<SpectrogramConfig, 'frequencyScale' | 'minFrequency' | 'maxFrequency' | 'gainDb' | 'rangeDb' | 'labels' | 'labelsColor' | 'labelsBackground'>;
+
+/**
+ * Split a clip into two clips at the given sample position.
+ *
+ * The left clip retains the original fadeIn; the right clip retains the original fadeOut.
+ * Both clips share the same waveformData reference.
+ * If the clip has a name, suffixes " (1)" and " (2)" are appended.
+ *
+ * @param clip - The clip to split
+ * @param splitSample - The timeline sample position where the split occurs
+ * @returns Object with `left` and `right` AudioClip
+ */
+export declare function splitClip(clip: AudioClip, splitSample: number): {
+    left: AudioClip;
+    right: AudioClip;
+};
+
+/** Number of PPQN ticks per bar for the given time signature. */
+export declare function ticksPerBar(timeSignature: [number, number], ppqn?: number): number;
+
+/** Number of PPQN ticks per beat for the given time signature. */
+export declare function ticksPerBeat(timeSignature: [number, number], ppqn?: number): number;
+
+/** Format ticks as a 1-indexed bar.beat label. Beat 1 shows bar number only (e.g., "3" not "3.1"). */
+export declare function ticksToBarBeatLabel(ticks: number, timeSignature: [number, number], ppqn?: number): string;
+
+/** Convert PPQN ticks to sample count. Uses Math.round for integer sample alignment. */
+export declare function ticksToSamples(ticks: number, bpm: number, sampleRate: number, ppqn?: number): number;
+
+/**
+ * Convert SF2 timecents to seconds.
+ * SF2 formula: seconds = 2^(timecents / 1200)
+ * Default -12000 timecents ≈ 0.001s (effectively instant).
+ */
+export declare function timecentsToSeconds(tc: number): number;
+
+/**
+ * Represents the entire timeline/project
+ */
+export declare interface Timeline {
+    /** All tracks in the timeline */
+    tracks: ClipTrack[];
+    /** Total timeline duration in seconds */
+    duration: number;
+    /** Sample rate for all audio (typically 44100 or 48000) */
+    sampleRate: number;
+    /** Optional project name */
+    name?: string;
+    /** Optional tempo (BPM) for grid snapping */
+    tempo?: number;
+    /** Optional time signature for grid snapping */
+    timeSignature?: {
+        numerator: number;
+        denominator: number;
+    };
+}
+
+export declare interface TimeSelection {
+    start: number;
+    end: number;
+}
+
+export declare interface ToneAdapterOptions {
+    effects?: EffectsFunction;
+    /** When provided, MIDI clips use SoundFont sample playback instead of PolySynth */
+    soundFontCache?: SoundFontCache;
+}
+
+export declare class TonePlayout {
+    private tracks;
+    private masterVolume;
+    private isInitialized;
+    private soloedTracks;
+    private manualMuteState;
+    private effectsCleanup?;
+    private onPlaybackCompleteCallback?;
+    private _completionEventId;
+    private _loopHandler;
+    private _loopEnabled;
+    private _loopStart;
+    private _loopEnd;
+    constructor(options?: TonePlayoutOptions);
+    private gainToDb;
+    private clearCompletionEvent;
+    init(): Promise<void>;
+    addTrack(trackOptions: ToneTrackOptions): ToneTrack;
+    addMidiTrack(trackOptions: MidiToneTrackOptions): MidiToneTrack;
+    addSoundFontTrack(trackOptions: SoundFontToneTrackOptions): SoundFontToneTrack;
+    /**
+     * Apply solo muting after all tracks have been added.
+     * Call this after adding all tracks to ensure solo logic is applied correctly.
+     */
+    applyInitialSoloState(): void;
+    removeTrack(trackId: string): void;
+    getTrack(trackId: string): PlayableTrack | undefined;
+    play(when?: number, offset?: number, duration?: number): void;
+    pause(): void;
+    stop(): void;
+    setMasterGain(gain: number): void;
+    setSolo(trackId: string, soloed: boolean): void;
+    private updateSoloMuting;
+    setMute(trackId: string, muted: boolean): void;
+    setLoop(enabled: boolean, loopStart: number, loopEnd: number): void;
+    getCurrentTime(): number;
+    seekTo(time: number): void;
+    dispose(): void;
+    get context(): BaseContext;
+    get sampleRate(): number;
+    setOnPlaybackComplete(callback: () => void): void;
+}
+
+export declare interface TonePlayoutOptions {
+    tracks?: ToneTrack[];
+    masterGain?: number;
+    effects?: EffectsFunction;
+}
+
+export declare class ToneTrack {
+    private scheduledClips;
+    private activeSources;
+    private volumeNode;
+    private panNode;
+    private muteGain;
+    private track;
+    private effectsCleanup?;
+    private _scheduleGuardOffset;
+    constructor(options: ToneTrackOptions);
+    /**
+     * Create and start an AudioBufferSourceNode for a clip.
+     * Sources are one-shot: each play or loop iteration creates a fresh one.
+     */
+    private startClipSource;
+    /**
+     * Set the schedule guard offset. Schedule callbacks for clips before this
+     * offset are suppressed (already handled by startMidClipSources).
+     * Must be called before transport.start() and in the loop handler.
+     */
+    setScheduleGuardOffset(offset: number): void;
+    /**
+     * Start sources for clips that span the given Transport position.
+     * Used for mid-playback seeking and loop boundary handling where
+     * Transport.schedule() callbacks have already passed.
+     *
+     * Uses strict < for absClipStart to avoid double-creation with
+     * schedule callbacks at exact Transport position (e.g., loopStart).
+     */
+    startMidClipSources(transportOffset: number, audioContextTime: number): void;
+    /**
+     * Stop all active AudioBufferSourceNodes and clear the set.
+     * Native AudioBufferSourceNodes ignore Transport state changes —
+     * they must be explicitly stopped.
+     */
+    stopAllSources(): void;
+    /**
+     * Schedule fade envelopes for a clip at the given AudioContext time.
+     * Uses native GainNode.gain (AudioParam) directly — no _param workaround needed.
+     */
+    private scheduleFades;
+    /**
+     * Prepare fade envelopes for all clips based on Transport offset.
+     * Called before Transport.start() to schedule fades at correct AudioContext times.
+     */
+    prepareFades(when: number, transportOffset: number): void;
+    /**
+     * Cancel all scheduled fade automation and reset to nominal gain.
+     * Called on pause/stop to prevent stale fade envelopes.
+     */
+    cancelFades(): void;
+    private gainToDb;
+    setVolume(gain: number): void;
+    setPan(pan: number): void;
+    setMute(muted: boolean): void;
+    setSolo(soloed: boolean): void;
+    dispose(): void;
+    get id(): string;
+    get duration(): number;
+    get buffer(): AudioBuffer;
+    get muted(): boolean;
+    get startTime(): number;
+}
+
+export declare interface ToneTrackOptions {
+    buffer?: AudioBuffer;
+    clips?: ClipInfo[];
+    track: Track;
+    effects?: TrackEffectsFunction;
+    destination?: ToneAudioNode;
+}
+
+export declare interface Track {
+    id: string;
+    name: string;
+    src?: string | AudioBuffer_2;
+    gain: number;
+    muted: boolean;
+    soloed: boolean;
+    stereoPan: number;
+    startTime: number;
+    endTime?: number;
+    fadeIn?: Fade;
+    fadeOut?: Fade;
+    cueIn?: number;
+    cueOut?: number;
+}
+
+export declare type TrackEffectsFunction = (graphEnd: Gain, masterGainNode: ToneAudioNode, isOffline: boolean) => void | (() => void);
+
+/**
+ * Generic effects function type for track-level audio processing.
+ *
+ * The actual implementation receives Tone.js audio nodes. Using generic types
+ * here to avoid circular dependencies with the playout package.
+ *
+ * @param graphEnd - The end of the track's audio graph (Tone.js Gain node)
+ * @param destination - Where to connect the effects output (Tone.js ToneAudioNode)
+ * @param isOffline - Whether rendering offline (for export)
+ * @returns Optional cleanup function called when track is disposed
+ *
+ * @example
+ * ```typescript
+ * const trackEffects: TrackEffectsFunction = (graphEnd, destination, isOffline) => {
+ *   const reverb = new Tone.Reverb({ decay: 1.5 });
+ *   graphEnd.connect(reverb);
+ *   reverb.connect(destination);
+ *
+ *   return () => {
+ *     reverb.dispose();
+ *   };
+ * };
+ * ```
+ */
+declare type TrackEffectsFunction_2 = (graphEnd: unknown, destination: unknown, isOffline: boolean) => void | (() => void);
+
+/** Per-track overrides for spectrogram rendering (render mode, config, color map) */
+export declare interface TrackSpectrogramOverrides {
+    renderMode: RenderMode;
+    config?: SpectrogramConfig;
+    colorMap?: ColorMapValue;
+}
+
+export declare interface WaveformConfig {
+    sampleRate: number;
+    samplesPerPixel: number;
+    waveHeight?: number;
+    waveOutlineColor?: string;
+    waveFillColor?: string;
+    waveProgressColor?: string;
+}
+
+/**
+ * WaveformData object from waveform-data.js library.
+ * Supports resample() and slice() for dynamic zoom levels.
+ * See: https://github.com/bbc/waveform-data.js
+ */
+export declare interface WaveformDataObject {
+    /** Sample rate of the original audio */
+    readonly sample_rate: number;
+    /** Number of audio samples per pixel */
+    readonly scale: number;
+    /** Length of waveform data in pixels */
+    readonly length: number;
+    /** Bit depth (8 or 16) */
+    readonly bits: number;
+    /** Duration in seconds */
+    readonly duration: number;
+    /** Number of channels */
+    readonly channels: number;
+    /** Get channel data */
+    channel: (index: number) => {
+        min_array: () => number[];
+        max_array: () => number[];
+    };
+    /** Resample to different scale */
+    resample: (options: {
+        scale: number;
+    } | {
+        width: number;
+    }) => WaveformDataObject;
+    /** Slice a portion of the waveform */
+    slice: (options: {
+        startTime: number;
+        endTime: number;
+    } | {
+        startIndex: number;
+        endIndex: number;
+    }) => WaveformDataObject;
+}
+
+export { }