wavesurf 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheDecipherist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# wavesurf
+
+A React audio player with WaveSurfer.js waveform visualization, global state management, and mini-player support.
+
+## Features
+
+- **WaveSurfer.js Integration** - Beautiful waveform visualization for audio playback
+- **Global Audio State** - React Context for managing playback across your app
+- **Mini Player** - A persistent bottom/top bar for controlling playback
+- **Pre-computed Peaks Support** - Fast loading with pre-generated waveform data
+- **Volume Fade-in Effect** - Smooth 3-second volume fade when starting playback
+- **Volume Persistence** - Remember user's volume preference via localStorage
+- **Lazy Loading** - Load waveforms only when visible using IntersectionObserver
+- **Mobile Responsive** - Adapts to different screen sizes
+- **CSS Variables** - Easy theming with CSS custom properties
+- **TypeScript** - Full TypeScript support with exported types
+
+## Installation
+
+```bash
+npm install wavesurf wavesurfer.js
+# or
+yarn add wavesurf wavesurfer.js
+# or
+pnpm add wavesurf wavesurfer.js
+```
+
+## Quick Start
+
+### 1. Wrap your app with the provider
+
+```tsx
+import { AudioPlayerProvider } from 'wavesurf';
+
+function App() {
+  return (
+    <AudioPlayerProvider>
+      <YourApp />
+    </AudioPlayerProvider>
+  );
+}
+```
+
+### 2. Add the MiniPlayer component
+
+```tsx
+import { MiniPlayer } from 'wavesurf';
+
+function Layout({ children }) {
+  return (
+    <div>
+      {children}
+      <MiniPlayer />
+    </div>
+  );
+}
+```
+
+### 3. Use the WaveformPlayer for songs
+
+```tsx
+import { WaveformPlayer } from 'wavesurf';
+import 'wavesurf/styles.css';
+
+function SongList({ songs }) {
+  return (
+    <div>
+      {songs.map((song) => (
+        <WaveformPlayer
+          key={song.id}
+          song={{
+            id: song.id,
+            title: song.title,
+            artist: song.artist,
+            audioUrl: song.url,
+            duration: song.duration,
+            peaks: song.peaks, // Optional: pre-computed waveform data
+          }}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### AudioPlayerProvider
+
+Wrap your application with this provider to enable global audio state management.
+
+```tsx
+<AudioPlayerProvider config={config}>
+  {children}
+</AudioPlayerProvider>
+```
+
+#### Config Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `fadeInEnabled` | `boolean` | `true` | Enable volume fade-in effect on play |
+| `fadeInDuration` | `number` | `3000` | Duration of fade-in in milliseconds |
+| `persistVolume` | `boolean` | `true` | Persist volume to localStorage |
+| `storageKey` | `string` | `'audioPlayerVolume'` | localStorage key for volume |
+| `defaultVolume` | `number` | `1` | Default volume level (0-1) |
+| `onPlay` | `(song: Song) => void` | - | Callback when playback starts |
+| `onPause` | `() => void` | - | Callback when playback pauses |
+| `onEnd` | `() => void` | - | Callback when song ends |
+| `onTimeUpdate` | `(time: number) => void` | - | Callback on time update |
+
+### useAudioPlayer Hook
+
+Access the audio player state and controls from any component.
+
+```tsx
+import { useAudioPlayer } from 'wavesurf';
+
+function CustomControls() {
+  const {
+    // State
+    currentSong,
+    isPlaying,
+    currentTime,
+    duration,
+    volume,
+    displayVolume,
+    isFadingIn,
+    // Actions
+    play,
+    pause,
+    togglePlay,
+    seek,
+    setVolume,
+    stop,
+  } = useAudioPlayer();
+
+  return (
+    <button onClick={togglePlay}>
+      {isPlaying ? 'Pause' : 'Play'}
+    </button>
+  );
+}
+```
+
+### WaveformPlayer
+
+Displays a waveform visualization with play controls for a single song.
+
+```tsx
+<WaveformPlayer
+  song={song}
+  waveformConfig={{
+    waveColor: '#666666',
+    progressColor: '#D4AF37',
+    height: 60,
+  }}
+  lazyLoad={true}
+  showTime={true}
+  className="my-player"
+  renderHeader={(song, isPlaying) => (
+    <div>{song.title} {isPlaying && '▶'}</div>
+  )}
+  renderControls={(song, isPlaying) => (
+    <button>Share</button>
+  )}
+/>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `song` | `Song` | required | The song object to play |
+| `waveformConfig` | `WaveformConfig` | - | Waveform styling options |
+| `lazyLoad` | `boolean` | `true` | Enable lazy loading via IntersectionObserver |
+| `showTime` | `boolean` | `true` | Show time display below waveform |
+| `className` | `string` | `''` | Additional CSS class |
+| `renderHeader` | `(song, isPlaying) => ReactNode` | - | Custom header renderer |
+| `renderControls` | `(song, isPlaying) => ReactNode` | - | Custom controls renderer |
+
+### MiniPlayer
+
+A fixed position player bar for persistent playback control.
+
+```tsx
+<MiniPlayer
+  position="bottom"
+  showVolume={true}
+  showClose={true}
+  onClose={() => console.log('Player closed')}
+  className="my-mini-player"
+  waveformConfig={{
+    progressColor: '#FF0000',
+  }}
+/>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `position` | `'top' \| 'bottom'` | `'bottom'` | Position on screen |
+| `showVolume` | `boolean` | `true` | Show volume control (auto-hidden on mobile) |
+| `showClose` | `boolean` | `true` | Show close button |
+| `onClose` | `() => void` | - | Callback when close is clicked |
+| `className` | `string` | `''` | Additional CSS class |
+| `waveformConfig` | `WaveformConfig` | - | Waveform styling options |
+
+### Song Interface
+
+```typescript
+interface Song {
+  id: string;           // Unique identifier
+  title: string;        // Display title
+  artist?: string;      // Artist name (optional)
+  album?: string;       // Album name (optional)
+  audioUrl: string;     // URL to the audio file
+  duration?: number;    // Duration in seconds (optional)
+  peaks?: number[];     // Pre-computed waveform peaks (optional)
+}
+```
+
+### WaveformConfig Interface
+
+```typescript
+interface WaveformConfig {
+  waveColor?: string;      // Color of the waveform (default: '#666666')
+  progressColor?: string;  // Color of played portion (default: '#D4AF37')
+  cursorColor?: string;    // Color of playhead (default: '#D4AF37')
+  barWidth?: number;       // Width of bars in px (default: 2)
+  barGap?: number;         // Gap between bars in px (default: 1)
+  barRadius?: number;      // Border radius of bars (default: 2)
+  height?: number;         // Height in pixels (default: 60)
+  normalize?: boolean;     // Normalize waveform (default: true)
+}
+```
+
+## Styling & Theming
+
+### Using the default styles
+
+Import the CSS file in your app:
+
+```tsx
+import 'wavesurf/styles.css';
+```
+
+### Customizing with CSS Variables
+
+Override the CSS variables to customize the appearance:
+
+```css
+:root {
+  /* Colors */
+  --wsp-wave-color: #888888;
+  --wsp-progress-color: #FF5500;
+  --wsp-cursor-color: #FF5500;
+  --wsp-background: transparent;
+
+  /* Button Colors */
+  --wsp-button-bg: #FF5500;
+  --wsp-button-bg-hover: #FF7733;
+  --wsp-button-text: #ffffff;
+
+  /* Text Colors */
+  --wsp-text: #ffffff;
+  --wsp-text-muted: #999999;
+
+  /* Sizing */
+  --wsp-height: 60px;
+  --wsp-mini-height: 40px;
+  --wsp-button-size: 56px;
+
+  /* Mini Player */
+  --wsp-mini-bg: #1a1a1a;
+  --wsp-mini-border-color: #FF5500;
+}
+```
+
+### Using your own styles
+
+You can also write completely custom CSS targeting the class names:
+
+- `.wsp-player` - Main player container
+- `.wsp-play-button` - Play/pause button
+- `.wsp-waveform` - Waveform container
+- `.wsp-time-display` - Time display
+- `.wsp-mini-player` - Mini player container
+- `.wsp-mini-play-button` - Mini player play button
+- `.wsp-mini-waveform` - Mini player waveform
+
+## Pre-computed Peaks
+
+For optimal performance, especially with large audio files, you can pre-compute waveform peaks on your server. This eliminates the need to decode audio on the client.
+
+### Generating peaks with audiowaveform
+
+```bash
+# Install audiowaveform (on Ubuntu/Debian)
+sudo apt install audiowaveform
+
+# Generate peaks JSON
+audiowaveform -i audio.mp3 -o peaks.json --pixels-per-second 10
+```
+
+### Using peaks in your app
+
+```tsx
+const song = {
+  id: '1',
+  title: 'My Song',
+  audioUrl: '/audio/song.mp3',
+  duration: 180, // 3 minutes
+  peaks: peaksData, // Array of numbers from audiowaveform
+};
+
+<WaveformPlayer song={song} />
+```
+
+## TypeScript
+
+All types are exported from the package:
+
+```typescript
+import type {
+  Song,
+  AudioPlayerState,
+  AudioPlayerActions,
+  AudioPlayerConfig,
+  WaveformConfig,
+  WaveformPlayerProps,
+  MiniPlayerProps,
+} from 'wavesurf';
+```
+
+## Browser Support
+
+This package requires browsers that support:
+- Web Audio API
+- CSS Custom Properties
+- IntersectionObserver (for lazy loading)
+
+All modern browsers (Chrome, Firefox, Safari, Edge) are supported.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,212 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Represents a song/track that can be played by the audio player.
+ */
+interface Song {
+    /** Unique identifier for the song */
+    id: string;
+    /** Display title of the song */
+    title: string;
+    /** Artist name (optional) */
+    artist?: string;
+    /** Album name (optional) */
+    album?: string;
+    /** URL to the audio file */
+    audioUrl: string;
+    /** Duration in seconds (optional, will be detected if not provided) */
+    duration?: number;
+    /** Pre-computed waveform peaks for fast visualization (optional) */
+    peaks?: number[];
+}
+/**
+ * Internal state of the audio player.
+ */
+interface AudioPlayerState {
+    /** Currently loaded song (null if none) */
+    currentSong: Song | null;
+    /** Whether audio is currently playing */
+    isPlaying: boolean;
+    /** Current playback position in seconds */
+    currentTime: number;
+    /** Total duration in seconds */
+    duration: number;
+    /** User's target/saved volume (0-1) */
+    volume: number;
+    /** Actual current volume, follows fade-in animation (0-1) */
+    displayVolume: number;
+    /** Whether volume is currently fading in */
+    isFadingIn: boolean;
+}
+/**
+ * Actions available to control the audio player.
+ */
+interface AudioPlayerActions {
+    /** Play a song (loads and starts playback with fade-in) */
+    play: (song: Song) => void;
+    /** Pause playback */
+    pause: () => void;
+    /** Toggle between play and pause */
+    togglePlay: () => void;
+    /** Seek to a specific time in seconds */
+    seek: (time: number) => void;
+    /** Set volume (0-1, persisted to localStorage if enabled) */
+    setVolume: (volume: number) => void;
+    /** Stop playback and clear current song */
+    stop: () => void;
+}
+/**
+ * Combined context value including state and actions.
+ */
+interface AudioPlayerContextValue extends AudioPlayerState, AudioPlayerActions {
+}
+/**
+ * Configuration options for the AudioPlayerProvider.
+ */
+interface AudioPlayerConfig {
+    /** Enable volume fade-in effect on play (default: true) */
+    fadeInEnabled?: boolean;
+    /** Duration of fade-in effect in milliseconds (default: 3000) */
+    fadeInDuration?: number;
+    /** Persist volume to localStorage (default: true) */
+    persistVolume?: boolean;
+    /** localStorage key for volume persistence (default: 'audioPlayerVolume') */
+    storageKey?: string;
+    /** Default volume level 0-1 (default: 1) */
+    defaultVolume?: number;
+    /** Callback when a song starts playing */
+    onPlay?: (song: Song) => void;
+    /** Callback when playback is paused */
+    onPause?: () => void;
+    /** Callback when a song ends */
+    onEnd?: () => void;
+    /** Callback when current time changes (called frequently) */
+    onTimeUpdate?: (time: number) => void;
+}
+/**
+ * Configuration options for waveform visualization.
+ */
+interface WaveformConfig {
+    /** Color of the waveform (default: '#666666') */
+    waveColor?: string;
+    /** Color of the played/progress portion (default: '#D4AF37') */
+    progressColor?: string;
+    /** Color of the cursor/playhead (default: '#D4AF37') */
+    cursorColor?: string;
+    /** Width of each bar in pixels (default: 2) */
+    barWidth?: number;
+    /** Gap between bars in pixels (default: 1) */
+    barGap?: number;
+    /** Border radius of bars in pixels (default: 2) */
+    barRadius?: number;
+    /** Height of the waveform in pixels (default: 60) */
+    height?: number;
+    /** Normalize waveform to fill height (default: true) */
+    normalize?: boolean;
+}
+/**
+ * Props for the WaveformPlayer component.
+ */
+interface WaveformPlayerProps {
+    /** The song to display/play */
+    song: Song;
+    /** Waveform styling configuration */
+    waveformConfig?: WaveformConfig;
+    /** Enable lazy loading via IntersectionObserver (default: true) */
+    lazyLoad?: boolean;
+    /** Show time display below waveform (default: true) */
+    showTime?: boolean;
+    /** Additional CSS class name */
+    className?: string;
+    /** Custom render function for the header area */
+    renderHeader?: (song: Song, isPlaying: boolean) => React.ReactNode;
+    /** Custom render function for additional controls */
+    renderControls?: (song: Song, isPlaying: boolean) => React.ReactNode;
+}
+/**
+ * Position of the mini player.
+ */
+type MiniPlayerPosition = 'top' | 'bottom';
+/**
+ * Props for the MiniPlayer component.
+ */
+interface MiniPlayerProps {
+    /** Position on screen (default: 'bottom') */
+    position?: MiniPlayerPosition;
+    /** Show volume control (default: true on desktop, false on mobile) */
+    showVolume?: boolean;
+    /** Show close button (default: true) */
+    showClose?: boolean;
+    /** Callback when close button is clicked */
+    onClose?: () => void;
+    /** Additional CSS class name */
+    className?: string;
+    /** Waveform styling configuration for the mini waveform */
+    waveformConfig?: WaveformConfig;
+}
+/**
+ * Return type for the useLazyLoad hook.
+ */
+interface UseLazyLoadResult {
+    /** Ref to attach to the element to observe */
+    ref: React.RefObject<HTMLDivElement>;
+    /** Whether the element is visible/intersecting */
+    isVisible: boolean;
+}
+/**
+ * Options for the useLazyLoad hook.
+ */
+interface UseLazyLoadOptions {
+    /** Root margin for IntersectionObserver (default: '100px') */
+    rootMargin?: string;
+    /** Visibility threshold 0-1 (default: 0) */
+    threshold?: number;
+    /** Start as visible (skip lazy loading) */
+    forceVisible?: boolean;
+}
+
+declare const MINI_PLAYER_PLAY_EVENT = "wavesurfer-player-mini-play";
+interface AudioPlayerProviderProps {
+    children: ReactNode;
+    config?: AudioPlayerConfig;
+}
+declare function AudioPlayerProvider({ children, config: userConfig, }: AudioPlayerProviderProps): react_jsx_runtime.JSX.Element;
+declare function useAudioPlayer(): AudioPlayerContextValue;
+
+declare function WaveformPlayer({ song, waveformConfig: userWaveformConfig, lazyLoad, showTime, className, renderHeader, renderControls, }: WaveformPlayerProps): react_jsx_runtime.JSX.Element;
+
+declare function MiniPlayer({ position, showVolume, showClose, onClose, className, waveformConfig: userWaveformConfig, }: MiniPlayerProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Hook for lazy loading elements using IntersectionObserver.
+ * Returns a ref to attach to the target element and a boolean indicating visibility.
+ *
+ * @param options - Configuration options for the IntersectionObserver
+ * @returns Object containing ref and isVisible state
+ *
+ * @example
+ * const { ref, isVisible } = useLazyLoad();
+ *
+ * return (
+ *   <div ref={ref}>
+ *     {isVisible && <ExpensiveComponent />}
+ *   </div>
+ * );
+ */
+declare function useLazyLoad(options?: UseLazyLoadOptions): UseLazyLoadResult;
+
+/**
+ * Formats seconds into a human-readable time string (M:SS or MM:SS).
+ *
+ * @param seconds - The number of seconds to format
+ * @returns Formatted time string (e.g., "3:45" or "12:05")
+ *
+ * @example
+ * formatTime(125) // "2:05"
+ * formatTime(0) // "0:00"
+ * formatTime(3600) // "60:00"
+ */
+declare function formatTime(seconds: number): string;
+
+export { type AudioPlayerActions, type AudioPlayerConfig, type AudioPlayerContextValue, AudioPlayerProvider, type AudioPlayerState, MINI_PLAYER_PLAY_EVENT, MiniPlayer, type MiniPlayerPosition, type MiniPlayerProps, type Song, type UseLazyLoadOptions, type UseLazyLoadResult, type WaveformConfig, WaveformPlayer, type WaveformPlayerProps, formatTime, useAudioPlayer, useLazyLoad };