waveframe 0.1.2 → 0.2.0

package/README.md

@@ -1,13 +1,15 @@
 # Waveframe
 
-A customizable React audio player component with SoundCloud-style waveforms.
+Waveframe is a soundcloud-embed inspired web audio player for React. It handles audio playback and waveform visualization with a modular engine.
 
 ## Features
 
-- **SoundCloud-style Waveform**: Supports pre-calculated peak points for instant rendering.
-- **Customizable UI**: Styled with Tailwind CSS, easy to theme and adapt.
-- **Artwork Support**: Display track artwork prominently.
-- **High Performance**: Built with Vite and TypeScript.
+- Canvas-based waveform rendering.
+- Automatic peak analysis for URLs and Blobs.
+- Customizable colors via a theme object or CSS variables.
+- A hook-based API for building custom layouts.
+- Support for local audio and artwork file uploads.
+- Responsive scaling to fit different container sizes.
 
 ## Installation
 
@@ -15,26 +17,59 @@ A customizable React audio player component with SoundCloud-style waveforms.
 pnpm add waveframe
 ```
 
-## Usage
+Note: Waveframe requires React 19 or newer.
+
+## Quick Start
+
+The simplest way to use Waveframe is to provide an audio source via the `media` prop.
 
 ```tsx
 import { WaveframePlayer } from 'waveframe';
+import 'waveframe/style.css';
 
-const peaks = [0.1, 0.5, 0.8, 0.3, ...]; // 100-200 points recommended
-
-function App() {
+const App = () => {
   return (
     <WaveframePlayer
-      audioUrl="path/to/audio.mp3"
-      peaks={peaks}
-      artworkUrl="path/to/artwork.jpg"
-      title="Track Title"
-      artist="Artist Name"
+      title="Electronic Sunset"
+      artist="Digital Nomad"
+      media="https://example.com/audio.mp3"
+      artwork="https://example.com/cover.jpg"
     />
   );
-}
+};
 ```
 
+## Component Reference
+
+### Primary Props
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `media` | `string \| Blob` | Audio source (URL or local File/Blob). |
+| `peaks` | `number[]` | Optional pre-computed peaks to skip analysis. |
+| `artwork`| `string \| Blob` | Artwork image source (URL or local File/Blob). |
+| `title` | `string` | Track title. |
+| `artist` | `string` | Artist name. |
+| `theme` | `WaveframeTheme` | Object for color customization. |
+
+## Architecture
+
+Waveframe separates playback logic from the UI to allow for custom implementations.
+
+- **useWaveframe**: A hook for controlling the player state and analysis.
+- **WaveframeEngine**: The core logic class.
+- **Waveform**: A component for rendering peaks.
+
+For technical guides on building custom layouts or handling file workflows, refer to the full documentation.
+
+## Documentation and Playground
+
+### Interactive Playground
+`pnpm run dev`
+
+### API Reference
+`pnpm run docs`
+
 ## License
 
 MIT

package/dist/src/components/WaveframePlayer.d.ts

@@ -1,20 +1,83 @@
 import { default as React } from 'react';
 import { WaveframeTheme } from '../types';
+import { WaveframeEngine } from '../core/WaveframeEngine';
+/**
+ * Props for the WaveframePlayer component
+ */
 export interface WaveframePlayerProps {
-    audioUrl: string;
+    /**
+     * 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[];
-    artworkUrl?: string;
+    /**
+     * 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;
-    autoAnalyze?: boolean;
+    /**
+     * 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.
+ */
 export declare const WaveframePlayer: React.FC<WaveframePlayerProps>;

package/dist/src/core/PeakAnalyzer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+export 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;
+}

package/dist/src/core/PlayerCore.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Represents the low-level playback state of the audio element.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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;
+}

package/dist/src/core/WaveframeEngine.d.ts

@@ -0,0 +1,122 @@
+import { PlayerState } from './PlayerCore';
+/**
+ * Represents the complete state of the Waveframe engine, combining playback and analysis.
+ */
+export 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.
+ */
+export 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);
+ * });
+ * ```
+ */
+export 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;
+}

package/dist/src/hooks/useWaveframe.d.ts

@@ -0,0 +1,51 @@
+import { WaveframeEngine, EngineState } from '../core/WaveframeEngine';
+/**
+ * Configuration options for the `useWaveframe` hook.
+ */
+export interface UseWaveframeOptions {
+    /** Optional pre-computed peaks to skip automatic analysis */
+    peaks?: number[];
+    /** Optional external engine instance for shared playback across components */
+    engine?: WaveframeEngine;
+}
+/**
+ * A headless hook that provides full control over the Waveframe engine.
+ *
+ * It manages the engine's lifecycle, loads the provided media, and returns
+ * the current state along with playback controls.
+ *
+ * @param media The audio source (URL string or Blob/File object).
+ * @param options Additional configuration and an optional external engine.
+ *
+ * @example
+ * ```tsx
+ * const { state, togglePlay, seek } = useWaveframe('https://example.com/audio.mp3');
+ *
+ * return (
+ *   <div>
+ *     <button onClick={togglePlay}>{state.isPlaying ? 'Pause' : 'Play'}</button>
+ *     <div onClick={(e) => seek(0.5)}>Seek to Middle</div>
+ *   </div>
+ * );
+ * ```
+ */
+export declare const useWaveframe: (media: string | Blob | undefined, options?: UseWaveframeOptions) => {
+    /** The current reactive state of the engine */
+    state: EngineState;
+    /** The raw WaveframeEngine instance for advanced usage */
+    engine: WaveframeEngine;
+    /** Toggles playback between playing and paused */
+    togglePlay: () => void;
+    /** Starts audio playback */
+    play: () => void;
+    /** Pauses audio playback */
+    pause: () => void;
+    /** Seeks to a specific percentage (0-1) */
+    seek: (percentage: number) => void;
+    /** Sets the playback volume (0-1) */
+    setVolume: (v: number) => void;
+    /** Mutes or unmutes the audio */
+    setMuted: (m: boolean) => void;
+    /** Manually triggers a re-analysis of the current media */
+    analyze: (samples?: number) => Promise<void>;
+};

package/dist/src/hooks/useWaveframeStore.d.ts

@@ -0,0 +1,27 @@
+import { WaveframeEngine, EngineState } from '../core/WaveframeEngine';
+/**
+ * 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>
+ *   );
+ * };
+ * ```
+ */
+export declare const useWaveframeStore: (engine: WaveframeEngine) => EngineState;

package/dist/src/index.d.ts

@@ -1 +1,7 @@
 export * from './components/WaveframePlayer';
+export * from './core/WaveframeEngine';
+export * from './core/PlayerCore';
+export * from './core/PeakAnalyzer';
+export * from './hooks/useWaveframeStore';
+export * from './types';
+export * from './utils';

package/dist/src/molecules/ArtworkOverlay.d.ts

@@ -1,10 +1,20 @@
 import { default as React } from 'react';
+/**
+ * Props for the ArtworkOverlay component.
+ */
 interface ArtworkOverlayProps {
+    /** The URL or Object URL of the artwork image */
     artworkUrl?: string;
+    /** The title of the track (used for alt text) */
     title?: string;
-    isPlaying: boolean;
-    onToggle: (e: React.MouseEvent) => void;
+    /** Whether the artwork is currently being processed or the audio is analyzing */
     isLoading?: boolean;
 }
+/**
+ * A purely visual component for displaying track artwork.
+ *
+ * It handles loading states with a blur effect and provides a consistent
+ * container for the track image.
+ */
 export declare const ArtworkOverlay: React.FC<ArtworkOverlayProps>;
 export {};

package/dist/src/organisms/SettingsPanel.d.ts

@@ -5,7 +5,12 @@ interface SettingsPanelProps {
     trackInfo: TrackInfo;
     config: WaveformConfig;
     scale: number;
-    isAnalyzing: boolean;
+    engineState: {
+        isPlaying: boolean;
+        volume: number;
+        muted: boolean;
+        isAnalyzing: boolean;
+    };
     onAnalyze: () => void;
     onThemeChange: (theme: Partial<WaveframeTheme>) => void;
     onTrackChange: (track: Partial<TrackInfo>) => void;
@@ -13,6 +18,12 @@ interface SettingsPanelProps {
     onScaleChange: (scale: number) => void;
     onTogglePreset: (type: 'light' | 'dark') => void;
     onClearPeaks: () => void;
+    onFileUpload: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    onArtworkUpload: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    onReset: () => void;
+    onTogglePlay: () => void;
+    onSetVolume: (v: number) => void;
+    onSetMuted: (m: boolean) => void;
 }
 export declare const SettingsPanel: React.FC<SettingsPanelProps>;
 export {};

package/dist/src/types/index.d.ts

@@ -1,19 +1,75 @@
+/**
+ * Defines the core color palette for the Waveframe component.
+ *
+ * @example
+ * ```tsx
+ * const darkTheme: WaveframeTheme = {
+ *   bg: '#111827',
+ *   primary: '#ec4899',
+ *   text: '#f9fafb',
+ *   border: '#1f2937'
+ * };
+ * ```
+ */
 export 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'
+ * };
+ * ```
+ */
 export interface TrackInfo {
+    /** The title of the track */
     title: string;
+    /** The artist of the track */
     artist: string;
-    artworkUrl: 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.
+ */
 export 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
+ * };
+ * ```
+ */
 export 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;
 }

package/dist/src/utils/audio.d.ts

@@ -1,15 +1,33 @@
 /**
- * Advanced Audio Utilities using Web Audio API
- */
-/**
- * Loads audio from a URL, decodes it, and generates a specific number of peaks (samples)
+ * 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);
+ * ```
  */
 export declare const generatePeaks: (audioUrl: string, samples?: number) => Promise<number[]>;
 /**
- * Loads audio into memory as a Blob and returns a temporary Object URL
+ * 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.
  */
 export declare const loadAudioToMemory: (url: string) => Promise<string>;
 /**
- * Cleanup function to prevent memory leaks from Object URLs
+ * 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.
  */
 export declare const revokeAudioMemory: (url: string) => void;