waveframe 0.2.1 → 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,491 @@
+import React from 'react';
+
+/**
+ * Defines the core color palette for the Waveframe component.
+ *
+ * @example
+ * ```tsx
+ * const darkTheme: WaveframeTheme = {
+ *   bg: '#111827',
+ *   primary: '#ec4899',
+ *   text: '#f9fafb',
+ *   border: '#1f2937'
+ * };
+ * ```
+ */
+interface WaveframeTheme {
+    /** The main background color of the player */
+    bg: string;
+    /** The primary accent color (used for play button and progress) */
+    primary: string;
+    /** The color of the text elements (title, artist, time) */
+    text: string;
+    /** The color of borders and dividers */
+    border: string;
+}
+/**
+ * Metadata associated with an audio track.
+ *
+ * @example
+ * ```tsx
+ * const track: TrackInfo = {
+ *   title: 'Electronic Sunset',
+ *   artist: 'Digital Nomad',
+ *   artwork: 'https://example.com/art.jpg', // or a Blob object
+ *   audioUrl: 'https://example.com/audio.mp3'
+ * };
+ * ```
+ */
+interface TrackInfo {
+    /** The title of the track */
+    title: string;
+    /** The artist of the track */
+    artist: string;
+    /** The artwork source (URL string or Blob/File object) */
+    artwork: string | Blob;
+    /** The URL to the actual audio file */
+    audioUrl: string;
+}
+/**
+ * Defines the resolution of the waveform.
+ * - `number`: A fixed number of bars to render.
+ * - `'auto'`: Compute the number of bars dynamically based on the container width.
+ */
+type Resolution = number | 'auto';
+/**
+ * Configuration options for how the waveform is rendered visually.
+ *
+ * @example
+ * ```tsx
+ * const config: WaveformConfig = {
+ *   resolution: 'auto',
+ *   barWidth: 2,
+ *   barGap: 1,
+ *   height: 100
+ * };
+ * ```
+ */
+interface WaveformConfig {
+    /** The number of bars to render, or 'auto' to compute based on container width */
+    resolution: Resolution;
+    /** The width of each individual bar in pixels */
+    barWidth: number;
+    /** The spacing between each bar in pixels */
+    barGap: number;
+    /** The total height of the waveform in pixels */
+    height: number;
+}
+
+/**
+ * Represents the low-level playback state of the audio element.
+ */
+type PlayerState = {
+    /** Whether the audio is currently playing */
+    isPlaying: boolean;
+    /** The current playback time in seconds */
+    currentTime: number;
+    /** The total duration of the track in seconds */
+    duration: number;
+    /** The current volume level (0 to 1) */
+    volume: number;
+    /** Whether the audio is currently muted */
+    muted: boolean;
+};
+/**
+ * A callback function that receives the latest PlayerState.
+ */
+type PlayerListener = (state: PlayerState) => void;
+/**
+ * The internal core class responsible for managing the HTMLAudioElement.
+ *
+ * It handles raw playback logic, volume control, and synchronizes the
+ * internal `PlayerState` with DOM events from the underlying `Audio` instance.
+ */
+declare class PlayerCore {
+    private audio;
+    private listeners;
+    private _state;
+    /**
+     * Initializes a new PlayerCore instance and sets up event listeners on a new Audio object.
+     */
+    constructor();
+    /**
+     * Subscribes to various HTMLMediaElement events to keep the internal state in sync.
+     */
+    private initListeners;
+    /**
+     * Updates the internal state and notifies subscribers.
+     */
+    private updateState;
+    /**
+     * Triggers all registered listener callbacks.
+     */
+    private notify;
+    /**
+     * Registers a listener for state updates.
+     * @param listener The callback function.
+     * @returns An unsubscribe function.
+     */
+    subscribe(listener: PlayerListener): () => boolean;
+    /**
+     * Returns the current playback state.
+     */
+    get state(): PlayerState;
+    /**
+     * Updates the source URL of the underlying audio element.
+     * @param url The audio source URL.
+     */
+    setSource(url: string): void;
+    /**
+     * Starts playback. Returns a promise that resolves when playback begins.
+     */
+    play(): Promise<void>;
+    /**
+     * Pauses playback.
+     */
+    pause(): void;
+    /**
+     * Toggles between play and pause states.
+     */
+    togglePlay(): void;
+    /**
+     * Seeks to a specific time.
+     * @param time Time in seconds.
+     */
+    seek(time: number): void;
+    /**
+     * Sets the volume level.
+     * @param volume Level from 0 to 1.
+     */
+    setVolume(volume: number): void;
+    /**
+     * Mutes or unmutes the audio element.
+     * @param muted Mute status.
+     */
+    setMuted(muted: boolean): void;
+    /**
+     * Cleans up the audio element and removes all listeners.
+     */
+    dispose(): void;
+}
+
+/**
+ * Represents the complete state of the Waveframe engine, combining playback and analysis.
+ */
+type EngineState = PlayerState & {
+    /** The current set of generated or provided waveform peaks (0-1 range) */
+    peaks: number[];
+    /** Whether an audio analysis process is currently in progress */
+    isAnalyzing: boolean;
+    /** Any error message encountered during playback or analysis */
+    error: string | null;
+};
+/**
+ * A callback function that receives the latest EngineState.
+ */
+type EngineListener = (state: EngineState) => void;
+/**
+ * The orchestrator class for Waveframe.
+ *
+ * It manages the lifecycle of audio playback and waveform analysis, providing a unified
+ * store-like interface that can be easily consumed by React or other frameworks.
+ *
+ * @example
+ * ```typescript
+ * const engine = new WaveframeEngine();
+ *
+ * // Load from URL (automatic analysis if peaks omitted)
+ * engine.load('https://example.com/audio.mp3');
+ *
+ * // Load from Blob with pre-computed peaks
+ * engine.load(myBlob, [0.1, 0.5, 0.8]);
+ *
+ * // Subscription
+ * const unsubscribe = engine.subscribe((state) => {
+ *   console.log('Current time:', state.currentTime);
+ * });
+ * ```
+ */
+declare class WaveframeEngine {
+    private player;
+    private analyzer;
+    private listeners;
+    private _state;
+    private _media;
+    private _objectUrl;
+    /**
+     * Creates a new instance of the WaveframeEngine.
+     * Initializes internal PlayerCore and PeakAnalyzer.
+     */
+    constructor();
+    /**
+     * Internal method to update the state and notify all subscribers.
+     */
+    private updateState;
+    /**
+     * Notifies all registered listeners of a state change.
+     */
+    private notify;
+    /**
+     * Registers a listener to be called whenever the engine state changes.
+     * @param listener The callback function.
+     * @returns An unsubscribe function.
+     */
+    subscribe(listener: EngineListener): () => boolean;
+    /**
+     * Returns a snapshot of the current engine state.
+     * Useful for `useSyncExternalStore`.
+     */
+    getSnapshot(): EngineState;
+    /**
+     * Revokes any existing Object URLs to prevent memory leaks.
+     */
+    private revokeOldSource;
+    /**
+     * Loads media (URL or Blob) into the player.
+     *
+     * If a string is passed, it's treated as a URL and used directly for playback.
+     * If a Blob is passed, an Object URL is created for playback.
+     *
+     * If `peaks` are not provided, it automatically triggers an analysis.
+     *
+     * @param media The audio source (URL string or Blob/File object).
+     * @param peaks Optional pre-generated peaks for the waveform.
+     */
+    load(media: string | Blob, peaks?: number[]): void;
+    /**
+     * Analyzes the current media to generate waveform peaks.
+     * @param samples The number of peaks to generate. Defaults to 512.
+     */
+    analyze(samples?: number): Promise<void>;
+    /**
+     * Toggles playback between playing and paused.
+     */
+    togglePlay(): void;
+    /**
+     * Starts audio playback.
+     */
+    play(): void;
+    /**
+     * Pauses audio playback.
+     */
+    pause(): void;
+    /**
+     * Seeks to a specific position in the track.
+     * @param percentage The seek position as a decimal (0 to 1).
+     */
+    seek(percentage: number): void;
+    /**
+     * Sets the playback volume.
+     * @param volume The volume level (0 to 1).
+     */
+    setVolume(volume: number): void;
+    /**
+     * Mutes or unmutes the audio.
+     * @param muted Whether the audio should be muted.
+     */
+    setMuted(muted: boolean): void;
+    /**
+     * Disposes of the engine, pausing playback and clearing all listeners and resources.
+     */
+    dispose(): void;
+}
+
+/**
+ * Props for the WaveframePlayer component
+ */
+interface WaveframePlayerProps {
+    /**
+     * The audio source to play. Can be a URL string or a Blob/File object.
+     */
+    media?: string | Blob;
+    /**
+     * Optional pre-generated peaks for the waveform (0-1 range).
+     * If omitted or empty, the player will automatically analyze the media.
+     */
+    peaks?: number[];
+    /**
+     * The artwork source to display. Can be a URL string or a Blob/File object.
+     */
+    artwork?: string | Blob;
+    /**
+     * The title of the track
+     */
+    title?: string;
+    /**
+     * The artist of the track
+     */
+    artist?: string;
+    /**
+     * The base color of the waveform bars
+     * @default "#e5e7eb" (light) or "#374151" (dark)
+     */
+    waveColor?: string;
+    /**
+     * The color of the played progress part of the waveform
+     * @default theme.primary or "#3b82f6"
+     */
+    progressColor?: string;
+    /**
+     * The height of the waveform in pixels
+     * @default 80
+     */
+    height?: number;
+    /**
+     * Additional CSS classes for the container
+     */
+    className?: string;
+    /**
+     * Inline styles for the container
+     */
+    style?: React.CSSProperties;
+    /**
+     * The number of bars to render. Use 'auto' to fit the container width.
+     * @default "auto"
+     */
+    resolution?: number | 'auto';
+    /**
+     * The width of each bar in pixels (if resolution is 'auto')
+     * @default 2
+     */
+    barWidth?: number;
+    /**
+     * The gap between bars in pixels (if resolution is 'auto')
+     * @default 1
+     */
+    barGap?: number;
+    /**
+     * Custom theme configuration
+     */
+    theme?: WaveframeTheme;
+    /**
+     * Optional WaveframeEngine instance for external control.
+     * If provided, the player will sync with this engine instead of creating its own.
+     */
+    engine?: WaveframeEngine;
+}
+/**
+ * The standard "all-in-one" Waveframe player component.
+ *
+ * This component features a SoundCloud-inspired layout with a prominent
+ * play/pause button positioned next to the track metadata.
+ */
+declare const WaveframePlayer: React.FC<WaveframePlayerProps>;
+
+/**
+ * A specialized class for decoding audio data and generating waveform peaks.
+ *
+ * It leverages the Web Audio API (`AudioContext`) to process audio buffers
+ * and extract amplitude data for visualization.
+ */
+declare class PeakAnalyzer {
+    private audioCtx;
+    /**
+     * Initializes the analyzer. AudioContext creation is deferred to the first use
+     * to comply with browser autoplay and resource management policies.
+     */
+    constructor();
+    /**
+     * Lazily creates or returns the existing AudioContext.
+     */
+    private getContext;
+    /**
+     * Processes media (URL or Blob) and generates a set of normalized peaks.
+     *
+     * @param media The URL string or Blob object to analyze.
+     * @param samples The number of peaks (bars) to generate. Defaults to 512.
+     * @returns A promise resolving to an array of normalized peak values (0 to 1).
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new PeakAnalyzer();
+     *
+     * // Analyze from URL
+     * const peaksFromUrl = await analyzer.generatePeaks('https://example.com/audio.mp3');
+     *
+     * // Analyze from Blob
+     * const peaksFromBlob = await analyzer.generatePeaks(myAudioBlob);
+     * ```
+     */
+    generatePeaks(media: string | Blob, samples?: number): Promise<number[]>;
+    /**
+     * Closes the AudioContext and releases system audio resources.
+     */
+    dispose(): void;
+}
+
+/**
+ * A React hook that synchronizes a WaveframeEngine's state with a React component.
+ *
+ * It uses `useSyncExternalStore` for high-performance updates, ensuring that
+ * the component only re-renders when the engine's state snapshot actually changes.
+ *
+ * @param engine The WaveframeEngine instance to subscribe to.
+ * @returns The current EngineState (isPlaying, currentTime, peaks, etc.).
+ *
+ * @example
+ * ```tsx
+ * const MyPlayer = ({ engine }: { engine: WaveframeEngine }) => {
+ *   const { isPlaying, currentTime, duration } = useWaveframeStore(engine);
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => engine.togglePlay()}>
+ *         {isPlaying ? 'Pause' : 'Play'}
+ *       </button>
+ *       <p>{currentTime.toFixed(2)} / {duration.toFixed(2)}</p>
+ *     </div>
+ *   );
+ * };
+ * ```
+ */
+declare const useWaveframeStore: (engine: WaveframeEngine) => EngineState;
+
+/**
+ * Loads audio from a URL, decodes it, and generates a specific number of peaks (samples).
+ *
+ * This is a high-level utility function that internally manages a `PeakAnalyzer` instance.
+ *
+ * @param audioUrl The URL of the audio file to analyze.
+ * @param samples The number of peaks (bars) to generate. Defaults to 512.
+ * @returns A promise resolving to an array of normalized peak values (0 to 1).
+ *
+ * @example
+ * ```typescript
+ * const peaks = await generatePeaks('https://example.com/audio.mp3', 256);
+ * ```
+ */
+declare const generatePeaks: (audioUrl: string, samples?: number) => Promise<number[]>;
+/**
+ * Loads audio into memory as a Blob and returns a temporary Object URL.
+ *
+ * Useful for ensuring audio data is fully loaded locally before starting
+ * playback or analysis, which can help with CORS issues or slow networks.
+ *
+ * @param url The URL of the remote audio file.
+ * @returns A promise resolving to a temporary `blob:` URL.
+ */
+declare const loadAudioToMemory: (url: string) => Promise<string>;
+/**
+ * Cleanup function to prevent memory leaks from Object URLs.
+ *
+ * Call this when a `blob:` URL is no longer needed (e.g., when the component unmounts).
+ *
+ * @param url The Object URL to revoke.
+ */
+declare const revokeAudioMemory: (url: string) => void;
+
+/**
+ * Formats seconds into a M:SS string
+ */
+declare const formatTime: (seconds: number) => string;
+/**
+ * Resamples an array of peaks to a target count using bucket-max or linear interpolation
+ */
+declare const resamplePeaks: (peaks: number[], targetCount: number) => number[];
+/**
+ * High-performance token-based syntax highlighter for React snippets
+ */
+declare const highlightCode: (code: string) => string[];
+
+export { type EngineListener, type EngineState, PeakAnalyzer, PlayerCore, type PlayerListener, type PlayerState, type Resolution, type TrackInfo, type WaveformConfig, WaveframeEngine, WaveframePlayer, type WaveframePlayerProps, type WaveframeTheme, formatTime, generatePeaks, highlightCode, loadAudioToMemory, resamplePeaks, revokeAudioMemory, useWaveframeStore };