Core Waveform Control

/**
 * Create a new WaveSurfer instance with the specified options
 * @param options - Configuration options for the waveform
 * @returns New WaveSurfer instance
 */
static create(options: WaveSurferOptions): WaveSurfer;

/**
 * Constructor for WaveSurfer instance (use create() instead)
 * @param options - Configuration options for the waveform  
 */
constructor(options: WaveSurferOptions);

import WaveSurfer from "wavesurfer.js";

// Basic waveform creation
const wavesurfer = WaveSurfer.create({
  container: "#waveform",
  waveColor: "#4F4A85",
  progressColor: "#383351",
});

// Advanced configuration
const advancedWaveform = WaveSurfer.create({
  container: document.getElementById("advanced-waveform"),
  height: 200,
  waveColor: ["#ff0000", "#00ff00", "#0000ff"],
  progressColor: "#666",
  cursorColor: "#fff",
  barWidth: 2,
  barGap: 1,
  barRadius: 2,
  normalize: true,
  fillParent: true,
  autoScroll: true,
  interact: true,
});

/**
 * Load an audio file by URL, with optional pre-decoded audio data
 * @param url - URL of the audio file to load
 * @param peaks - Optional pre-computed peaks data for faster rendering
 * @param duration - Optional pre-computed duration in seconds
 * @returns Promise that resolves when audio is loaded and ready
 */
load(url: string, peaks?: Array<Float32Array | number[]>, duration?: number): Promise<void>;

/**
 * Load an audio blob with optional pre-decoded audio data
 * @param blob - Audio blob to load
 * @param peaks - Optional pre-computed peaks data for faster rendering  
 * @param duration - Optional pre-computed duration in seconds
 * @returns Promise that resolves when audio is loaded and ready
 */
loadBlob(blob: Blob, peaks?: Array<Float32Array | number[]>, duration?: number): Promise<void>;

/**
 * Empty the waveform (load silent audio)
 */
empty(): void;

// Load from URL
await wavesurfer.load("/path/to/audio.mp3");

// Load with pre-computed peaks for performance
const peaks = [[0.1, 0.3, -0.2, 0.8, -0.4], [0.05, 0.2, -0.1, 0.6, -0.3]];
await wavesurfer.load("/path/to/audio.mp3", peaks, 120.5);

// Load from blob (e.g., from file input)
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
await wavesurfer.loadBlob(file);

// Clear waveform
wavesurfer.empty();

/**
 * Start playing the audio from current position or specified time range
 * @param start - Optional start time in seconds
 * @param end - Optional end time in seconds (will stop at this time)
 * @returns Promise that resolves when playback starts
 */
play(start?: number, end?: number): Promise<void>;

/**
 * Pause the audio playback
 */
pause(): void;

/**
 * Toggle between play and pause states
 * @returns Promise that resolves when state change completes
 */
playPause(): Promise<void>;

/**
 * Stop the audio and return to the beginning
 */
stop(): void;

/**
 * Skip forward or backward by specified number of seconds
 * @param seconds - Number of seconds to skip (positive or negative)
 */
skip(seconds: number): void;

/**
 * Check if the audio is currently playing
 * @returns True if playing, false if paused or stopped
 */
isPlaying(): boolean;

/**
 * Check if the audio is currently seeking
 * @returns True if seeking, false otherwise
 */
isSeeking(): boolean;

// Basic playback control
await wavesurfer.play();
wavesurfer.pause();
await wavesurfer.playPause(); // Toggle state

// Play specific segment
await wavesurfer.play(30, 60); // Play from 30s to 60s

// Skip forward/backward
wavesurfer.skip(10);  // Skip forward 10 seconds
wavesurfer.skip(-5);  // Skip backward 5 seconds

// Stop and reset
wavesurfer.stop();

// Check playback state
if (wavesurfer.isPlaying()) {
  console.log("Audio is playing");
}

/**
 * Jump to a specific time in the audio (in seconds)
 * @param time - Time position in seconds
 */
setTime(time: number): void;

/**
 * Seek to a percentage of audio as [0..1] (0 = beginning, 1 = end)
 * @param progress - Progress as decimal between 0 and 1
 */
seekTo(progress: number): void;

/**
 * Get the current audio position in seconds
 * @returns Current playback position in seconds
 */  
getCurrentTime(): number;

/**
 * Get the duration of the audio in seconds
 * @returns Audio duration in seconds, or 0 if not loaded
 */
getDuration(): number;

// Jump to specific times
wavesurfer.setTime(45.7); // Jump to 45.7 seconds
wavesurfer.seekTo(0.5);   // Jump to middle of audio
wavesurfer.seekTo(0.25);  // Jump to 25% through audio

// Get timing information
const currentTime = wavesurfer.getCurrentTime();
const duration = wavesurfer.getDuration();
const progress = currentTime / duration;

console.log(`Playing at ${currentTime}s of ${duration}s (${Math.round(progress * 100)}%)`);

/**
 * Get the current audio volume
 * @returns Volume level between 0 and 1
 */
getVolume(): number;

/**
 * Set the audio volume
 * @param volume - Volume level between 0 and 1
 */
setVolume(volume: number): void;

/**
 * Get the current muted state
 * @returns True if muted, false otherwise
 */
getMuted(): boolean;

/**
 * Mute or unmute the audio
 * @param muted - True to mute, false to unmute
 */
setMuted(muted: boolean): void;

/**
 * Get the current playback rate/speed
 * @returns Playback rate (1.0 = normal speed)
 */
getPlaybackRate(): number;

/**
 * Set the playback speed, with optional pitch preservation
 * @param rate - Playback rate (0.5 = half speed, 2.0 = double speed)
 * @param preservePitch - Whether to preserve pitch (default: true)
 */
setPlaybackRate(rate: number, preservePitch?: boolean): void;

// Volume control
wavesurfer.setVolume(0.8);        // 80% volume
console.log(wavesurfer.getVolume()); // 0.8

// Muting
wavesurfer.setMuted(true);        // Mute
wavesurfer.setMuted(false);       // Unmute
console.log(wavesurfer.getMuted()); // false

// Playback speed
wavesurfer.setPlaybackRate(1.5);     // 1.5x speed
wavesurfer.setPlaybackRate(0.75, false); // 0.75x speed, pitch not preserved
console.log(wavesurfer.getPlaybackRate()); // 0.75

/**
 * Get the HTML media element (audio/video)
 * @returns The underlying HTMLMediaElement
 */
getMediaElement(): HTMLMediaElement;

/**
 * Set a custom HTML media element to use
 * @param element - HTMLAudioElement or HTMLVideoElement to use
 */
setMediaElement(element: HTMLMediaElement): void;

/**
 * Set audio output device (if supported by browser)
 * @param sinkId - Device ID for audio output
 * @returns Promise that resolves when device is set
 */
setSinkId(sinkId: string): Promise<void>;

// Access the media element for advanced control
const mediaElement = wavesurfer.getMediaElement();
mediaElement.playsinline = true;
mediaElement.crossOrigin = "anonymous";

// Use custom audio element
const customAudio = document.createElement("audio");
customAudio.crossOrigin = "anonymous";
wavesurfer.setMediaElement(customAudio);

// Set audio output device (if supported)
try {
  await wavesurfer.setSinkId("device-id-here");
  console.log("Audio output device changed");
} catch (error) {
  console.log("Device change not supported");
}

/**
 * Set new wavesurfer options and re-render
 * @param options - Partial options object with properties to update
 */
setOptions(options: Partial<WaveSurferOptions>): void;

/**
 * Toggle if the waveform should react to clicks and interactions
 * @param isInteractive - True to enable interaction, false to disable
 */
toggleInteraction(isInteractive: boolean): void;

// Update visual appearance
wavesurfer.setOptions({
  waveColor: "#ff0000",
  progressColor: "#00ff00",
  height: 150,
});

// Update behavior
wavesurfer.setOptions({
  autoScroll: false,
  dragToSeek: true,
  minPxPerSec: 100,
});

// Disable interaction
wavesurfer.toggleInteraction(false);

/**
 * Destroy the WaveSurfer instance and clean up all resources
 * Removes event listeners, stops audio, and cleans up DOM elements
 */
destroy(): void;

// Clean up when done
wavesurfer.destroy();

// Example cleanup in framework
// React useEffect cleanup
useEffect(() => {
  const ws = WaveSurfer.create({...});
  return () => ws.destroy();
}, []);

// Vue beforeUnmount
beforeUnmount(() => {
  wavesurfer.destroy();
});