@waveform-playlist/browser 5.2.0-next.4 → 5.3.0

package/dist/index.d.ts

@@ -6,6 +6,7 @@ import { Fade as Fade_2 } from '@waveform-playlist/core';
 import { Gain } from 'tone';
 import { MediaElementPlayout } from '@waveform-playlist/media-element-playout';
 import { MutableRefObject } from 'react';
+import { Provider } from 'react';
 import react__default from 'react';
 import { ReactNode } from 'react';
 import { RefObject } from 'react';
@@ -166,6 +167,12 @@ export declare interface AudioTrackConfig {
     fadeIn?: Fade;
     fadeOut?: Fade;
     waveformData?: WaveformDataObject;
+    /** Visualization render mode: 'waveform' | 'spectrogram' | 'both'. Default: 'waveform' */
+    renderMode?: RenderMode;
+    /** Spectrogram configuration (FFT size, window, frequency scale, etc.) */
+    spectrogramConfig?: SpectrogramConfig;
+    /** Spectrogram color map name or custom color array */
+    spectrogramColorMap?: ColorMapValue;
 }
 
 /**
@@ -225,8 +232,23 @@ export declare interface ClipTrack {
     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;
 }
 
+/** A single color map entry: [r, g, b] or [r, g, b, a] */
+declare type ColorMapEntry = [number, number, number] | [number, number, number, number];
+
+/** Built-in color map names */
+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 */
+declare type ColorMapValue = ColorMapName | ColorMapEntry[];
+
 /**
  * Continuous play checkbox that uses the playlist context
  * Uses split contexts to avoid re-rendering during animation
@@ -424,6 +446,14 @@ export declare const FastForwardButton: default_2.FC<{
     className?: string;
 }>;
 
+/**
+ * Spectrogram Types
+ *
+ * Types for frequency-domain visualization of audio data.
+ */
+/** Valid FFT sizes (must be power of 2, 256–8192) */
+declare type FFTSize = 256 | 512 | 1024 | 2048 | 4096 | 8192;
+
 /**
  * Custom function to generate the label shown on annotation boxes in the waveform.
  * Receives the annotation data and its index in the list, returns a string label.
@@ -588,10 +618,16 @@ export declare interface MediaElementAnnotationListProps {
     onAnnotationUpdate?: OnAnnotationUpdateFn;
     /** Whether annotation text can be edited. Defaults to false. */
     editable?: boolean;
-    /** Whether dragging one annotation boundary also moves the adjacent annotation's boundary. Defaults to false. */
-    linkEndpoints?: boolean;
-    /** Override continuousPlay from context. Falls back to context value if not provided. */
-    continuousPlay?: boolean;
+    /**
+     * Action controls to show on each annotation item (e.g., delete, split).
+     * Only rendered when `editable` is true.
+     */
+    controls?: AnnotationAction[];
+    /**
+     * Override annotation list config. Falls back to context values
+     * `{ linkEndpoints: false, continuousPlay }` if not provided.
+     */
+    annotationListConfig?: AnnotationActionOptions;
     /** Where to position the active annotation when auto-scrolling. Defaults to 'center'. */
     scrollActivePosition?: ScrollLogicalPosition;
     /** Which scrollable containers to scroll: 'nearest' or 'all'. Defaults to 'nearest'. */
@@ -943,6 +979,8 @@ declare interface PlaylistDataContextValue {
     progressBarWidth: number;
     /** Whether the playlist has finished loading all tracks */
     isReady: boolean;
+    /** Whether tracks are rendered in mono mode */
+    mono: boolean;
 }
 
 declare interface PlaylistStateContextValue {
@@ -994,6 +1032,8 @@ export declare interface PlaylistVisualizationProps {
      * Use with useDragSensors({ touchOptimized: true }) for best results.
      */
     touchOptimized?: boolean;
+    /** Callback when a track's close button is clicked. Only renders close button when provided. */
+    onRemoveTrack?: (trackIndex: number) => void;
     recordingState?: {
         isRecording: boolean;
         trackId: string;
@@ -1014,6 +1054,9 @@ export declare interface RenderAnnotationItemProps {
     formatTime: (seconds: number) => string;
 }
 
+/** Render mode for a track's visualization */
+declare type RenderMode = 'waveform' | 'spectrogram' | 'both';
+
 /**
  * Type for custom playhead render functions.
  * Receives position, color, and animation refs for smooth 60fps animation.
@@ -1046,6 +1089,101 @@ export declare const SkipForwardButton: default_2.FC<{
     className?: string;
 }>;
 
+/**
+ * Configuration for spectrogram computation and rendering.
+ */
+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.
+ */
+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;
+}
+
+export declare interface SpectrogramIntegration {
+    spectrogramDataMap: Map<string, SpectrogramData[]>;
+    trackSpectrogramOverrides: Map<string, TrackSpectrogramOverrides>;
+    spectrogramWorkerApi: SpectrogramWorkerApi | null;
+    spectrogramConfig?: SpectrogramConfig;
+    spectrogramColorMap?: ColorMapValue;
+    setTrackRenderMode: (trackId: string, mode: RenderMode) => void;
+    setTrackSpectrogramConfig: (trackId: string, config: SpectrogramConfig, colorMap?: ColorMapValue) => void;
+    registerSpectrogramCanvases: (clipId: string, channelIndex: number, canvasIds: string[], canvasWidths: number[]) => void;
+    unregisterSpectrogramCanvases: (clipId: string, channelIndex: number) => void;
+    /** Render spectrogram menu items for a track's context menu */
+    renderMenuItems?: (props: {
+        renderMode: string;
+        onRenderModeChange: (mode: RenderMode) => void;
+        onOpenSettings: () => void;
+        onClose?: () => void;
+    }) => TrackMenuItem[];
+    /** Settings modal component provided by the spectrogram package */
+    SettingsModal?: React.ComponentType<{
+        open: boolean;
+        onClose: () => void;
+        config: SpectrogramConfig;
+        colorMap: ColorMapValue;
+        onApply: (config: SpectrogramConfig, colorMap: ColorMapValue) => void;
+    }>;
+    /** Get color lookup table for a color map name */
+    getColorMap: (name: ColorMapValue) => Uint8Array;
+    /** Get frequency scale function for a scale name */
+    getFrequencyScale: (name: string) => (f: number, minF: number, maxF: number) => number;
+}
+
+export declare const SpectrogramIntegrationProvider: Provider<SpectrogramIntegration | null>;
+
+/** Minimal type for the worker API surface used by browser components */
+declare interface SpectrogramWorkerApi {
+    registerCanvas: (canvasId: string, canvas: OffscreenCanvas) => void;
+    unregisterCanvas: (canvasId: string) => void;
+}
+
 export declare const StopButton: default_2.FC<{
     className?: string;
 }>;
@@ -1199,6 +1337,19 @@ export declare interface TrackEffectsState {
     activeEffects: TrackActiveEffect[];
 }
 
+declare interface TrackMenuItem {
+    id: string;
+    label?: string;
+    content: ReactNode;
+}
+
+/** Per-track overrides for spectrogram rendering (render mode, config, color map) */
+declare interface TrackSpectrogramOverrides {
+    renderMode: RenderMode;
+    config?: SpectrogramConfig;
+    colorMap?: ColorMapValue;
+}
+
 export declare interface TrackState {
     name: string;
     muted: boolean;
@@ -1716,6 +1867,8 @@ export declare const usePlaylistData: () => PlaylistDataContextValue;
 
 export declare const usePlaylistState: () => PlaylistStateContextValue;
 
+export declare function useSpectrogramIntegration(): SpectrogramIntegration | null;
+
 /**
  * Hook to manage time format state
  *
@@ -2033,6 +2186,8 @@ export declare interface WaveformProps {
      * Use with useDragSensors({ touchOptimized: true }) for best results.
      */
     touchOptimized?: boolean;
+    /** Callback when a track's close button is clicked. Only renders close button when provided. */
+    onRemoveTrack?: (trackIndex: number) => void;
     recordingState?: {
         isRecording: boolean;
         trackId: string;