smooth-player 1.0.0

package/README.md

@@ -0,0 +1,211 @@
+# Smooth Player
+
+Smooth Player is a TypeScript audio player for the web with built-in playlist handling, visualizers, accent-based styling, and reusable UI mount helpers.
+
+## Features
+
+- Single track and playlist playback
+- Nested playlists (`AudioPlaylist` inside `PlaylistEntry`)
+- Automatic playlist behavior:
+  - If there is only one track, playlist controls stay hidden
+  - If there are multiple tracks, next/previous + playlist panel are available
+- Visualizer modes: `spectrum`, `waveform`, `none`
+- Circular draggable progress ring support
+- Configurable `accentColor` through player config
+- Built-in debug panel support
+- Typed API (`.d.ts`) with ESM + CJS builds
+
+## Install
+
+```bash
+npm install smooth-player
+```
+
+![Smooth Player screenshot](examples/screenshot/example.png)
+
+## Quick Start
+
+```ts
+import { SmoothPlayer, mountStandardPlayerUI } from "smooth-player";
+import "smooth-player/dist/smooth-player.css";
+
+const tracks = [
+  {
+    id: "song-1",
+    src: "/audio/song-1.mp3",
+    metadata: { title: "Song 1", artist: "Artist 1" },
+  },
+  {
+    id: "song-2",
+    src: "/audio/song-2.mp3",
+    metadata: { title: "Song 2", artist: "Artist 2" },
+  },
+];
+
+const player = new SmoothPlayer({
+  playlist: tracks,
+  initialVolume: 0.8,
+  visualizer: "spectrum",
+  accentColor: "#0ed2a4",
+  debug: false,
+});
+
+const root = document.querySelector("#player-root");
+if (!(root instanceof HTMLElement)) throw new Error("Missing #player-root");
+
+mountStandardPlayerUI(player, root);
+```
+
+## Core Config (`SmoothPlayerOptions`)
+
+- `playlist?: PlaylistEntry[]`
+- `visualizer?: "spectrum" | "waveform" | "none"` (default: `"spectrum"`)
+- `accentColor?: string` (default: `#0ed2a4`)
+- `debug?: boolean` (default: `false`)
+- `initialVolume?: number`
+- `initialTrackIndex?: number`
+- `initialShuffle?: boolean`
+- `autoplay?: boolean`
+- `loop?: boolean`
+- `durationFallback?: boolean` (default: `true`, fallback decode for unknown metadata duration)
+- `analyzer?: { fftSize, smoothingTimeConstant, minDecibels, maxDecibels }`
+
+## Visualizer
+
+At runtime:
+
+```ts
+player.setVisualizer("waveform");
+const current = player.getVisualizer(); // "waveform"
+```
+
+Raw data API:
+
+- `getSpectrumData()`
+- `getWaveformData()`
+
+Exported visualizer classes:
+
+- `CanvasRadialVisualizer`
+- `CanvasSpectrumVisualizer`
+- `CanvasWaveformVisualizer`
+
+## Debug
+
+Enable debug directly in config:
+
+```ts
+const player = new SmoothPlayer({
+  playlist: tracks,
+  debug: true,
+});
+```
+
+Use `mountDebugPanel(...)` to bind debug metrics to your elements, or call `mountStandardPlayerUI(player, root, { debugEnabled: true })` when your DOM includes the debug panel nodes.
+
+Runtime methods:
+
+- `setDebug(enabled: boolean)`
+- `getDebug()`
+
+## Playlists (including nested)
+
+```ts
+const playlist = [
+  {
+    id: "focus",
+    title: "Focus",
+    tracks: [
+      { id: "f-1", src: "/audio/focus-1.mp3", metadata: { title: "Focus 1" } },
+      {
+        id: "focus-deep",
+        title: "Focus Deep",
+        tracks: [{ id: "fd-1", src: "/audio/focus-deep-1.mp3", metadata: { title: "Deep 1" } }],
+      },
+    ],
+  },
+  {
+    id: "chill",
+    title: "Chill",
+    tracks: [{ id: "c-1", src: "/audio/chill-1.mp3", metadata: { title: "Chill 1" } }],
+  },
+];
+
+const player = new SmoothPlayer({ playlist });
+player.selectPlaylist("chill");
+```
+
+Playlist API highlights:
+
+- `setPlaylist(entries, startIndex?)`
+- `getPlaylists()`
+- `getCurrentPlaylist()`
+- `selectPlaylist(playlistId, startIndex?)`
+
+## Events
+
+Subscribe with `player.on(eventName, handler)`:
+
+- `ready`
+- `play`
+- `pause`
+- `ended`
+- `playlistchange`
+- `trackchange`
+- `durationchange`
+- `timeupdate`
+- `volumechange`
+- `error`
+
+## UI Mount Helpers
+
+- `mountStandardPlayerUI(player, root, options?)`
+- `mountTrackInfo(titleElement, artistElement, options?)`
+- `mountPlayButton(buttonElement, options?)`
+- `mountProgress(options)`
+- `mountTransportControls(options)`
+- `mountShuffleToggle(options)`
+- `mountPlaylistPanel(options)`
+- `mountPlaylistSwitcher(container, options?)`
+- `mountPlaylist(container, options?)`
+- `mountPlaylistTitle(element, options?)`
+- `mountDebugPanel(options)`
+
+## Utility Methods
+
+- `setAccentColor(color)`
+- `getAccentColor()`
+- `applyAccentColor(targetElement)`
+- `formatTime(seconds)`
+- `getState()`
+- `getAudioElement()`
+
+## Scripts
+
+- `npm run dev`
+- `npm run build`
+- `npm run build:css`
+- `npm run typecheck`
+- `npm run demo`
+
+## Local Demo
+
+```bash
+npm install
+npm run demo
+```
+
+Open:
+
+- `http://127.0.0.1:4173/examples/demo.html`
+
+## Media Attribution and CORS
+
+Audio tracks included in this repository are provided for demonstration purposes only.
+
+- Part of the demo media is sourced from [Pixabay](https://pixabay.com/).
+- Additional demo files are SoundHelix songs available in `examples/audio`.
+
+If you load audio from external hosts, those sources must be CORS-enabled for browser playback and analysis features.
+The media server should return a valid `Access-Control-Allow-Origin` header for your application origin (or `*` when appropriate).
+Without proper CORS headers, browsers may block playback and prevent analyzer/visualizer processing.

package/assets/icons/menu.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <path d="M5 7.5H19" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>
+  <path d="M5 12H19" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>
+  <path d="M5 16.5H19" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>
+</svg>

package/assets/icons/next.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <path d="M17.5 6V18" stroke="currentColor" stroke-width="2.1" stroke-linecap="round"/>
+  <path d="M7.3 6.7C6.74 6.34 6 6.74 6 7.41V16.59C6 17.26 6.74 17.66 7.3 17.3L13.85 13.09C14.35 12.77 14.35 11.23 13.85 10.91L7.3 6.7Z" fill="currentColor"/>
+</svg>

package/assets/icons/note.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <path d="M14 4.8V14.2C13.3 13.8 12.4 13.6 11.4 13.6C9.1 13.6 7.2 14.8 7.2 16.5C7.2 18.2 9.1 19.4 11.4 19.4C13.7 19.4 15.6 18.2 15.6 16.5V8.6L20 7.4V13.2C19.3 12.8 18.4 12.6 17.4 12.6C15.1 12.6 13.2 13.8 13.2 15.5C13.2 17.2 15.1 18.4 17.4 18.4C19.7 18.4 21.6 17.2 21.6 15.5V4L14 4.8Z" fill="currentColor"/>
+</svg>

package/assets/icons/pause.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <rect x="7" y="6" width="3.6" height="12" rx="1.8" fill="currentColor"/>
+  <rect x="13.4" y="6" width="3.6" height="12" rx="1.8" fill="currentColor"/>
+</svg>

package/assets/icons/play.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <path d="M8 6.75C8 6.14 8.67 5.77 9.18 6.12L17.12 11.37C17.58 11.68 17.58 12.32 17.12 12.63L9.18 17.88C8.67 18.23 8 17.86 8 17.25V6.75Z" fill="currentColor"/>
+</svg>

package/assets/icons/playlist.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <path d="M5 8H14" stroke="currentColor" stroke-width="2.1" stroke-linecap="round"/>
+  <path d="M5 12H14" stroke="currentColor" stroke-width="2.1" stroke-linecap="round"/>
+  <path d="M5 16H10.5" stroke="currentColor" stroke-width="2.1" stroke-linecap="round"/>
+  <circle cx="17.8" cy="15.8" r="2.2" stroke="currentColor" stroke-width="1.9"/>
+  <path d="M20 15.8V8.2L16.2 9" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/assets/icons/prev.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <path d="M6.5 6V18" stroke="currentColor" stroke-width="2.1" stroke-linecap="round"/>
+  <path d="M16.7 6.7C17.26 6.34 18 6.74 18 7.41V16.59C18 17.26 17.26 17.66 16.7 17.3L10.15 13.09C9.65 12.77 9.65 11.23 10.15 10.91L16.7 6.7Z" fill="currentColor"/>
+</svg>

package/assets/icons/shuffle.svg

@@ -0,0 +1,7 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-hidden="true">
+  <path d="M16 5H20V9" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M4 7H9L15 17H20" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M20 15V19H16" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M4 17H9L10.5 14.5" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M13.5 9.5L15 7H20" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/dist/SmoothPlayer.d.ts

@@ -0,0 +1,91 @@
+import { type AnalyzerOptions, type AudioTrack, type DebugPanelMountOptions, type PlaylistEntry, type PlaylistMountOptions, type PlaylistPanelController, type PlaylistPanelMountOptions, type PlaylistSwitcherMountOptions, type PlaylistTitleMountOptions, type PlayButtonMountOptions, type ProgressMountOptions, type PlaybackState, type PlayerEvents, type SmoothPlayerOptions, type ShuffleToggleMountOptions, type TrackInfoMountOptions, type TransportControlsMountOptions, type VisualizerMode } from "./types.js";
+export declare class SmoothPlayer {
+    private readonly audio;
+    private readonly context;
+    private readonly sourceNode;
+    private readonly analyser;
+    private readonly events;
+    private playlists;
+    private activePlaylistId;
+    private currentTrackIndex;
+    private visualizerMode;
+    private accentColor;
+    private shuffleEnabled;
+    private debugEnabled;
+    private durationFallbackEnabled;
+    private resolvedDuration;
+    private readonly durationFallbackCache;
+    private resolvingDurationSrc;
+    constructor(options?: SmoothPlayerOptions);
+    on: <TKey extends keyof PlayerEvents>(event: TKey, listener: (payload: PlayerEvents[TKey]) => void) => () => void;
+    off: <TKey extends keyof PlayerEvents>(event: TKey, listener: (payload: PlayerEvents[TKey]) => void) => void;
+    destroy(): void;
+    setAccentColor(color: string): void;
+    getAccentColor(): string;
+    applyAccentColor(target: HTMLElement): void;
+    setShuffle(enabled: boolean): void;
+    getShuffle(): boolean;
+    setDebug(enabled: boolean): void;
+    getDebug(): boolean;
+    setPlaylist(entries: PlaylistEntry[], startIndex?: number): void;
+    selectPlaylist(playlistId: string, startIndex?: number): void;
+    getPlaylists(): Array<{
+        id: string;
+        title: string;
+        count: number;
+    }>;
+    getCurrentPlaylist(): {
+        id: string;
+        title: string;
+        tracks: AudioTrack[];
+    } | null;
+    getPlaylist(): AudioTrack[];
+    getCurrentTrack(): AudioTrack | null;
+    getCurrentTrackIndex(): number;
+    formatTime(value: number): string;
+    mountPlaylist(container: HTMLElement, options?: PlaylistMountOptions): () => void;
+    mountPlaylistSwitcher(container: HTMLElement, options?: PlaylistSwitcherMountOptions): () => void;
+    mountPlaylistTitle(element: HTMLElement, options?: PlaylistTitleMountOptions): () => void;
+    mountTrackInfo(titleElement: HTMLElement, artistElement: HTMLElement, options?: TrackInfoMountOptions): () => void;
+    mountPlayButton(button: HTMLButtonElement, options?: PlayButtonMountOptions): () => void;
+    mountTransportControls(options: TransportControlsMountOptions): () => void;
+    mountShuffleToggle(options: ShuffleToggleMountOptions): () => void;
+    mountPlaylistPanel(options: PlaylistPanelMountOptions): PlaylistPanelController;
+    mountDebugPanel(options: DebugPanelMountOptions): () => void;
+    mountProgress(options: ProgressMountOptions): () => void;
+    play(index?: number): Promise<void>;
+    pause(): void;
+    toggle(): Promise<void>;
+    next(): void;
+    previous(): void;
+    setLoop(loop: boolean): void;
+    setVolume(volume: number): void;
+    seek(seconds: number): void;
+    loadTrack(track: AudioTrack): void;
+    getState(): PlaybackState;
+    getAudioElement(): HTMLAudioElement;
+    getCurrentTime(): number;
+    getDuration(): number;
+    getSpectrumData(): Uint8Array;
+    getWaveformData(): Uint8Array;
+    setVisualizer(mode: VisualizerMode): void;
+    getVisualizer(): VisualizerMode;
+    configureAnalyzer(options?: AnalyzerOptions): void;
+    private getActivePlaylist;
+    private getActiveTracks;
+    private loadTrackByIndex;
+    private emitPlaylistChange;
+    private bindAudioEvents;
+    private clamp;
+    private pickRandomTrackIndex;
+    private emitTimeUpdate;
+    private emitDurationChange;
+    private syncDurationFromAudio;
+    private resolveDurationFallback;
+    private resolvePlaylists;
+    private collectDirectTracks;
+    private flattenTracks;
+    private collectNestedPlaylists;
+    private dedupePlaylistIds;
+    private isAudioPlaylist;
+}