type GeneralEventTypes = { [EventName: string]: unknown[]; }; type EventListener = (...args: EventTypes[EventName]) => void; /** A simple event emitter that can be used to listen to and emit events. */ declare class EventEmitter { private listeners; /** Subscribe to an event. Returns an unsubscribe function. */ on(event: EventName, listener: EventListener, options?: { once?: boolean; }): () => void; /** Unsubscribe from an event */ un(event: EventName, listener: EventListener): void; /** Subscribe to an event only once */ once(event: EventName, listener: EventListener): () => void; /** Clear all events */ unAll(): void; /** Emit an event */ protected emit(eventName: EventName, ...args: EventTypes[EventName]): void; } type BasePluginEvents = { destroy: []; }; type GenericPlugin = BasePlugin; /** Base class for wavesurfer plugins */ declare class BasePlugin extends EventEmitter { protected wavesurfer?: WaveSurfer; protected subscriptions: (() => void)[]; protected options: Options; private isDestroyed; /** Create a plugin instance */ constructor(options: Options); /** Called after this.wavesurfer is available */ protected onInit(): void; /** Do not call directly, only called by WavesSurfer internally */ _init(wavesurfer: WaveSurfer): void; /** Destroy the plugin and unsubscribe from all events */ destroy(): void; } type TreeNode = { [key: string]: string | number | boolean | CSSStyleDeclaration | TreeNode | Node; } & { xmlns?: string; style?: Partial; textContent?: string | Node; children?: TreeNode; }; declare function createElement(tagName: string, content: TreeNode & { xmlns: string; }, container?: Node): SVGElement; declare function createElement(tagName: string, content?: TreeNode, container?: Node): HTMLElement; declare const dom_createElement: typeof createElement; declare namespace dom { export { dom_createElement as createElement, createElement as default }; } /** * Reactive primitives for managing state in WaveSurfer * * This module provides signal-based reactivity similar to SolidJS signals. * Signals are reactive values that notify subscribers when they change. */ /** * A reactive value that can be read and subscribed to */ interface Signal { /** Get the current value */ get value(): T; /** Subscribe to changes. Returns an unsubscribe function. */ subscribe(callback: (value: T) => void): () => void; } /** * A writable reactive value that can be updated */ interface WritableSignal extends Signal { /** Set a new value. Only notifies if value changed. */ set(value: T): void; /** Update value using a function. */ update(fn: (current: T) => T): void; } type PlayerOptions = { media?: HTMLMediaElement; mediaControls?: boolean; autoplay?: boolean; playbackRate?: number; }; declare class Player extends EventEmitter { protected media: HTMLMediaElement; private isExternalMedia; private _isPlaying; private _currentTime; private _duration; private _volume; private _muted; private _playbackRate; private _seeking; private reactiveMediaEventCleanups; get isPlayingSignal(): WritableSignal; get currentTimeSignal(): WritableSignal; get durationSignal(): WritableSignal; get volumeSignal(): WritableSignal; get mutedSignal(): WritableSignal; get playbackRateSignal(): WritableSignal; get seekingSignal(): WritableSignal; constructor(options: PlayerOptions); /** * Setup reactive media event handlers that update signals * This bridges the imperative HTMLMediaElement API to reactive state */ private setupReactiveMediaEvents; protected onMediaEvent(event: K, callback: (ev: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): () => void; protected getSrc(): string; private revokeSrc; private canPlayType; protected setSrc(url: string, blob?: Blob): void; protected destroy(): void; protected setMediaElement(element: HTMLMediaElement): void; /** Start playing the audio */ play(): Promise; /** Pause the audio */ pause(): void; /** Check if the audio is playing */ isPlaying(): boolean; /** Jump to a specific time in the audio (in seconds) */ setTime(time: number): void; /** Get the duration of the audio in seconds */ getDuration(): number; /** Get the current audio position in seconds */ getCurrentTime(): number; /** Get the audio volume */ getVolume(): number; /** Set the audio volume */ setVolume(volume: number): void; /** Get the audio muted state */ getMuted(): boolean; /** Mute or unmute the audio */ setMuted(muted: boolean): void; /** Get the playback speed */ getPlaybackRate(): number; /** Check if the audio is seeking */ isSeeking(): boolean; /** Set the playback speed, pass an optional false to NOT preserve the pitch */ setPlaybackRate(rate: number, preservePitch?: boolean): void; /** Get the HTML media element */ getMediaElement(): HTMLMediaElement; /** Set a sink id to change the audio output device */ setSinkId(sinkId: string): Promise; } type RendererEvents = { click: [relativeX: number, relativeY: number]; dblclick: [relativeX: number, relativeY: number]; drag: [relativeX: number]; dragstart: [relativeX: number]; dragend: [relativeX: number]; scroll: [relativeStart: number, relativeEnd: number, scrollLeft: number, scrollRight: number]; render: []; rendered: []; resize: []; }; declare class Renderer extends EventEmitter { private options; private parent; private container; private scrollContainer; private wrapper; private canvasWrapper; private progressWrapper; private cursor; private timeouts; private isScrollable; private audioData; private resizeObserver; private lastContainerWidth; private isDragging; private subscriptions; private unsubscribeOnScroll; private dragStream; private scrollStream; constructor(options: WaveSurferOptions, audioElement?: HTMLElement); private parentFromOptionsContainer; private initEvents; private onContainerResize; private initDrag; private initHtml; /** Wavesurfer itself calls this method. Do not call it manually. */ setOptions(options: WaveSurferOptions): void; getWrapper(): HTMLElement; getWidth(): number; getScroll(): number; setScroll(pixels: number): void; setScrollPercentage(percent: number): void; destroy(): void; private createDelay; private getHeight; private convertColorValues; private getPixelRatio; private renderBarWaveform; private renderLineWaveform; private renderWaveform; private renderSingleCanvas; private renderMultiCanvas; private renderChannel; render(audioData: AudioBuffer): Promise; reRender(): void; zoom(minPxPerSec: number): void; private scrollIntoView; renderProgress(progress: number, isPlaying?: boolean): void; exportImage(format: string, quality: number, type: 'dataURL' | 'blob'): Promise; } /** * Centralized reactive state for WaveSurfer * * This module provides a single source of truth for all WaveSurfer state. * State is managed using reactive signals that automatically notify subscribers. */ /** * Read-only reactive state for WaveSurfer */ interface WaveSurferState { readonly currentTime: Signal; readonly duration: Signal; readonly isPlaying: Signal; readonly isPaused: Signal; readonly isSeeking: Signal; readonly volume: Signal; readonly playbackRate: Signal; readonly audioBuffer: Signal; readonly peaks: Signal | null>; readonly url: Signal; readonly zoom: Signal; readonly scrollPosition: Signal; readonly canPlay: Signal; readonly isReady: Signal; readonly progress: Signal; readonly progressPercent: Signal; } /** * Actions for updating WaveSurfer state */ interface WaveSurferActions { setCurrentTime: (time: number) => void; setDuration: (duration: number) => void; setPlaying: (playing: boolean) => void; setSeeking: (seeking: boolean) => void; setVolume: (volume: number) => void; setPlaybackRate: (rate: number) => void; setAudioBuffer: (buffer: AudioBuffer | null) => void; setPeaks: (peaks: Array | null) => void; setUrl: (url: string) => void; setZoom: (zoom: number) => void; setScrollPosition: (position: number) => void; } type WaveSurferOptions = { /** Required: an HTML element or selector where the waveform will be rendered */ container: HTMLElement | string; /** The height of the waveform in pixels, or "auto" to fill the container height */ height?: number | 'auto'; /** The width of the waveform in pixels or any CSS value; defaults to 100% */ width?: number | string; /** The color of the waveform */ waveColor?: string | string[] | CanvasGradient; /** The color of the progress mask */ progressColor?: string | string[] | CanvasGradient; /** The color of the playback cursor */ cursorColor?: string; /** The cursor width */ cursorWidth?: number; /** If set, the waveform will be rendered with bars like this: ▁ ▂ ▇ ▃ ▅ ▂ */ barWidth?: number; /** Spacing between bars in pixels */ barGap?: number; /** Rounded borders for bars */ barRadius?: number; /** A vertical scaling factor for the waveform */ barHeight?: number; /** Vertical bar alignment */ barAlign?: 'top' | 'bottom'; /** Minimum height of bars in pixels */ barMinHeight?: number; /** Minimum pixels per second of audio (i.e. the zoom level) */ minPxPerSec?: number; /** Stretch the waveform to fill the container, true by default */ fillParent?: boolean; /** Audio URL */ url?: string; /** Pre-computed audio data, arrays of floats for each channel */ peaks?: Array; /** Pre-computed audio duration in seconds */ duration?: number; /** Use an existing media element instead of creating one */ media?: HTMLMediaElement; /** Whether to show default audio element controls */ mediaControls?: boolean; /** Play the audio on load */ autoplay?: boolean; /** Pass false to disable clicks on the waveform */ interact?: boolean; /** Allow to drag the cursor to seek to a new position. If an object with `debounceTime` is provided instead * then `dragToSeek` will also be true. If `true` the default is 200ms */ dragToSeek?: boolean | { debounceTime: number; }; /** Hide the scrollbar */ hideScrollbar?: boolean; /** Audio rate, i.e. the playback speed */ audioRate?: number; /** Automatically scroll the container to keep the current position in viewport */ autoScroll?: boolean; /** If autoScroll is enabled, keep the cursor in the center of the waveform during playback */ autoCenter?: boolean; /** Decoding sample rate. Doesn't affect the playback. Defaults to 8000 */ sampleRate?: number; /** Render each audio channel as a separate waveform */ splitChannels?: Array & { overlay?: boolean; }>; /** Stretch the waveform to the full height */ normalize?: boolean; /** Use a fixed max peak value for normalization instead of calculating from the current data */ maxPeak?: number; /** The list of plugins to initialize on start */ plugins?: GenericPlugin[]; /** Custom render function */ renderFunction?: (peaks: Array, ctx: CanvasRenderingContext2D) => void; /** Options to pass to the fetch method */ fetchParams?: RequestInit; /** Playback "backend" to use, defaults to MediaElement */ backend?: 'WebAudio' | 'MediaElement'; /** Nonce for CSP if necessary */ cspNonce?: string; /** Override the Blob MIME type */ blobMimeType?: string; }; declare const defaultOptions: { waveColor: string; progressColor: string; cursorWidth: number; minPxPerSec: number; fillParent: boolean; interact: boolean; dragToSeek: boolean; autoScroll: boolean; autoCenter: boolean; sampleRate: number; }; type WaveSurferEvents = { /** After wavesurfer is created */ init: []; /** When audio starts loading */ load: [url: string]; /** During audio loading */ loading: [percent: number]; /** When the audio has been decoded */ decode: [duration: number]; /** When the audio is both decoded and can play */ ready: [duration: number]; /** When visible waveform is drawn */ redraw: []; /** When all audio channel chunks of the waveform have drawn */ redrawcomplete: []; /** When the audio starts playing */ play: []; /** When the audio pauses */ pause: []; /** When the audio finishes playing */ finish: []; /** On audio position change, fires continuously during playback */ timeupdate: [currentTime: number]; /** An alias of timeupdate but only when the audio is playing */ audioprocess: [currentTime: number]; /** When the user seeks to a new position */ seeking: [currentTime: number]; /** When the user interacts with the waveform (i.g. clicks or drags on it) */ interaction: [newTime: number]; /** When the user clicks on the waveform */ click: [relativeX: number, relativeY: number]; /** When the user double-clicks on the waveform */ dblclick: [relativeX: number, relativeY: number]; /** When the user drags the cursor */ drag: [relativeX: number]; /** When the user starts dragging the cursor */ dragstart: [relativeX: number]; /** When the user ends dragging the cursor */ dragend: [relativeX: number]; /** When the waveform is scrolled (panned) */ scroll: [visibleStartTime: number, visibleEndTime: number, scrollLeft: number, scrollRight: number]; /** When the zoom level changes */ zoom: [minPxPerSec: number]; /** Just before the waveform is destroyed so you can clean up your events */ destroy: []; /** When source file is unable to be fetched, decoded, or an error is thrown by media element */ error: [error: Error]; /** When audio container resizing */ resize: []; }; declare class WaveSurfer extends Player { options: WaveSurferOptions & typeof defaultOptions; private renderer; private timer; private plugins; private decodedData; private stopAtPosition; protected subscriptions: Array<() => void>; protected mediaSubscriptions: Array<() => void>; protected abortController: AbortController | null; private wavesurferState; private wavesurferActions; private reactiveCleanups; static readonly BasePlugin: typeof BasePlugin; static readonly dom: typeof dom; /** Create a new WaveSurfer instance */ static create(options: WaveSurferOptions): WaveSurfer; /** Get the reactive state for advanced use cases */ getState(): WaveSurferState; /** Get the renderer instance for plugin access to reactive streams */ getRenderer(): Renderer; /** Create a new WaveSurfer instance */ constructor(options: WaveSurferOptions); private updateProgress; private initTimerEvents; private initReactiveState; private initPlayerEvents; private initRendererEvents; private initPlugins; private unsubscribePlayerEvents; /** Set new wavesurfer options and re-render it */ setOptions(options: Partial): void; /** Register a wavesurfer.js plugin */ registerPlugin(plugin: T): T; /** Unregister a wavesurfer.js plugin */ unregisterPlugin(plugin: GenericPlugin): void; /** For plugins only: get the waveform wrapper div */ getWrapper(): HTMLElement; /** For plugins only: get the scroll container client width */ getWidth(): number; /** Get the current scroll position in pixels */ getScroll(): number; /** Set the current scroll position in pixels */ setScroll(pixels: number): void; /** Move the start of the viewing window to a specific time in the audio (in seconds) */ setScrollTime(time: number): void; /** Get all registered plugins */ getActivePlugins(): GenericPlugin[]; private loadAudio; /** Load an audio file by URL, with optional pre-decoded audio data */ load(url: string, channelData?: WaveSurferOptions['peaks'], duration?: number): Promise; /** Load an audio blob */ loadBlob(blob: Blob, channelData?: WaveSurferOptions['peaks'], duration?: number): Promise; /** Zoom the waveform by a given pixels-per-second factor */ zoom(minPxPerSec: number): void; /** Get the decoded audio data */ getDecodedData(): AudioBuffer | null; /** Get decoded peaks */ exportPeaks({ channels, maxLength, precision }?: { channels?: number | undefined; maxLength?: number | undefined; precision?: number | undefined; }): Array; /** Get the duration of the audio in seconds */ getDuration(): number; /** Toggle if the waveform should react to clicks */ toggleInteraction(isInteractive: boolean): void; /** Jump to a specific time in the audio (in seconds) */ setTime(time: number): void; /** Seek to a ratio of audio as [0..1] (0 = beginning, 1 = end) */ seekTo(progress: number): void; /** Start playing the audio */ play(start?: number, end?: number): Promise; /** Play or pause the audio */ playPause(): Promise; /** Stop the audio and go to the beginning */ stop(): void; /** Skip N or -N seconds from the current position */ skip(seconds: number): void; /** Empty the waveform */ empty(): void; /** Set HTML media element */ setMediaElement(element: HTMLMediaElement): void; /** * Export the waveform image as a data-URI or a blob. * * @param format The format of the exported image, can be `image/png`, `image/jpeg`, `image/webp` or any other format supported by the browser. * @param quality The quality of the exported image, for `image/jpeg` or `image/webp`. Must be between 0 and 1. * @param type The type of the exported image, can be `dataURL` (default) or `blob`. * @returns A promise that resolves with an array of data-URLs or blobs, one for each canvas element. */ exportImage(format: string, quality: number, type: 'dataURL'): Promise; exportImage(format: string, quality: number, type: 'blob'): Promise; /** Unmount wavesurfer */ destroy(): void; } export { type Signal, type WaveSurferActions, type WaveSurferEvents, type WaveSurferOptions, type WaveSurferState, type WritableSignal, WaveSurfer as default };