waveframe 0.1.3 → 0.2.1

package/README.md

@@ -1,78 +1,75 @@
 # Waveframe
 
-A high-performance, professional React audio player featuring SoundCloud-style waveforms, built-in audio analysis, and deep customization.
-
-[![NPM Version](https://img.shields.io/npm/v/waveframe?color=blue&style=flat-square)](https://www.npmjs.com/package/waveframe)
-[![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
-[![GitHub](https://img.shields.io/badge/github-gradippp%2Fwaveframe-black?style=flat-square&logo=github)](https://github.com/gradippp/waveframe)
+Waveframe is a soundcloud-embed inspired web audio player for React. It handles audio playback and waveform visualization with a modular engine.
 
 ## Features
 
-- **Ultra-Efficient Rendering**: Uses a dual-layer CSS-clipped canvas engine. No 60fps re-draws during playback, saving CPU and battery.
-- **Auto-Analysis**: Don't have peak data? Just provide a URL. Waveframe uses the Web Audio API to analyze and generate waveforms on-the-fly.
-- **Modern Theming**: Fully customizable with a single theme object. Supports deep navy dark modes and crisp light themes.
-- **Responsive & Fluid**: Proportional scaling ensures your waveform looks perfect on any screen size, from mobile to ultra-wide.
-- **Developer First**: Built with TypeScript, fully memoized, and includes a live [Configuration Playground](https://gradippp.github.io/waveframe).
+- 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
 
 ```bash
 pnpm add waveframe
-# or
-npm install waveframe
 ```
 
-> **Note**: Waveframe requires **React 19+**.
+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'; // Essential styles
+import 'waveframe/style.css';
 
 const App = () => {
   return (
     <WaveframePlayer
       title="Electronic Sunset"
       artist="Digital Nomad"
-      audioUrl="https://example.com/audio.mp3"
-      artworkUrl="https://example.com/cover.jpg"
+      media="https://example.com/audio.mp3"
+      artwork="https://example.com/cover.jpg"
     />
   );
 };
 ```
 
-## API Reference
+## Component Reference
 
-### Props
+### Primary Props
 
-| Prop | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `audioUrl` | `string` | **Required** | Direct link to your audio file. |
-| `peaks` | `number[]` | `undefined` | Optional array of normalized peaks (0-1). Triggers **Auto-Analysis** if omitted. |
-| `title` | `string` | `undefined` | Track title. |
-| `artist` | `string` | `undefined` | Artist name. |
-| `artworkUrl` | `string` | `undefined` | Cover art image URL. |
-| `theme` | `WaveframeTheme` | `Light` | Object to customize colors (see below). |
-| `resolution` | `number \| 'auto'`| `'auto'` | Target number of waveform bars. |
-| `barWidth` | `number` | `2` | Width of waveform bars in pixels. |
-| `barGap` | `number` | `1` | Space between bars in pixels. |
-| `height` | `number` | `80` | Height of the waveform in pixels. |
-| `autoAnalyze`| `boolean` | `true` | Automatically generate peaks if missing. |
+| 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. |
 
-### Theme Object
+## Architecture
 
-Customizing the player's palette is straightforward:
+Waveframe separates playback logic from the UI to allow for custom implementations.
 
-```tsx
-theme={{
-  bg: "#111827",      // Main card background
-  primary: "#3b82f6", // Accent (progress & play button)
-  text: "#f9fafb",    // Text color
-  border: "#1f2937"   // Border and divider lines
-}}
-```
+- **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 © [Agradip](mailto:me@agradip.fyi)
+MIT

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export * from './src/index'
+export * from './src/index.js'
 export {}

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

@@ -1,20 +1,83 @@
 import { default as React } from 'react';
-import { WaveframeTheme } from '../types';
+import { WaveframeTheme } from '../types.js';
+import { WaveframeEngine } from '../core/WaveframeEngine.js';
+/**
+ * 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.js';
+/**
+ * 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.js';
+/**
+ * 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.js';
+/**
+ * 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 './components/WaveframePlayer.js';
+export * from './core/WaveframeEngine.js';
+export * from './core/PlayerCore.js';
+export * from './core/PeakAnalyzer.js';
+export * from './hooks/useWaveframeStore.js';
+export * from './types.js';
+export * from './utils.js';

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

@@ -1,11 +1,16 @@
 import { default as React } from 'react';
-import { WaveframeTheme, TrackInfo, WaveformConfig } from '../types';
+import { WaveframeTheme, TrackInfo, WaveformConfig } from '../types.js';
 interface SettingsPanelProps {
     theme: WaveframeTheme;
     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 {};