smooth-player 1.0.4 → 2.0.0

package/README.md

@@ -6,13 +6,12 @@ Smooth Player is a TypeScript audio player for the web with built-in playlist ha
 
 - 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
+- Drag and drop audio files and playlist files (`.m3u`, `.m3u8`)
+- Built-in visualizer support and configurable visual styles
+- Automatic UI behavior for single-track vs multi-track playlists
+- Accent + background theming via config/API (with generated gradients)
+- Standard UI helpers with optional user preference persistence
+- Debug hooks and runtime telemetry bindings
 - Typed API (`.d.ts`) with ESM + CJS builds
 
 ## Install
@@ -26,7 +25,7 @@ npm install smooth-player
 ## Quick Start
 
 ```ts
-import { SmoothPlayer, mountStandardPlayerUI } from "smooth-player";
+import { SmoothPlayer, mountPlayerUI } from "smooth-player";
 import "smooth-player/dist/smooth-player.css";
 
 const tracks = [
@@ -47,21 +46,25 @@ const player = new SmoothPlayer({
   initialVolume: 0.8,
   visualizer: "spectrum",
   accentColor: "#0ed2a4",
+  backgroundColor: "#0b1220",
   debug: false,
 });
 
 const root = document.querySelector("#player-root");
 if (!(root instanceof HTMLElement)) throw new Error("Missing #player-root");
 
-mountStandardPlayerUI(player, root);
+mountPlayerUI(player, root);
 ```
 
 ## Core Config (`SmoothPlayerOptions`)
 
+- `audio?: HTMLAudioElement`
 - `playlist?: PlaylistEntry[]`
 - `visualizer?: "spectrum" | "waveform" | "none"` (default: `"spectrum"`)
 - `accentColor?: string` (default: `#0ed2a4`)
+- `backgroundColor?: string` (default: `#0b1220`)
 - `debug?: boolean` (default: `false`)
+- `crossOrigin?: HTMLMediaElement["crossOrigin"]` (default: `"anonymous"`)
 - `initialVolume?: number`
 - `initialTrackIndex?: number`
 - `initialShuffle?: boolean`
@@ -101,7 +104,7 @@ const player = new SmoothPlayer({
 });
 ```
 
-Use `mountDebugPanel(...)` to bind debug metrics to your elements, or call `mountStandardPlayerUI(player, root, { debugEnabled: true })` when your DOM includes the debug panel nodes.
+Use `mountDebugPanel(...)` to bind debug metrics to your own elements, or call `mountPlayerUI(player, root, { debugEnabled: true })` to auto-generate the debug panel in the mounted UI.
 
 Runtime methods:
 
@@ -157,9 +160,63 @@ Subscribe with `player.on(eventName, handler)`:
 - `volumechange`
 - `error`
 
+## Player API Overview
+
+Playback:
+
+- `play(index?)`
+- `pause()`
+- `toggle()`
+- `next()`
+- `previous()`
+- `seek(seconds)`
+- `setVolume(volume)`
+- `setLoop(loop)`
+
+Playlist and track management:
+
+- `setPlaylist(entries, startIndex?)`
+- `selectPlaylist(playlistId, startIndex?)`
+- `loadTrack(track)`
+- `getPlaylist()`
+- `getPlaylists()`
+- `getCurrentPlaylist()`
+- `getCurrentTrack()`
+- `getCurrentTrackIndex()`
+
+Visualizer and style:
+
+- `setVisualizer(mode)`
+- `getVisualizer()`
+- `setSpectrumStyle(options)`
+- `getSpectrumStyle()`
+- `setWaveformStyle(options)`
+- `getWaveformStyle()`
+- `configureAnalyzer(options)`
+- `getSpectrumData()`
+- `getWaveformData()`
+
+State and utility:
+
+- `getState()`
+- `formatTime(seconds)`
+- `getDuration()`
+- `getCurrentTime()`
+- `getAudioElement()`
+- `setAccentColor(color)`
+- `getAccentColor()`
+- `applyAccentColor(targetElement)`
+- `setDebug(enabled)`
+- `getDebug()`
+- `setBackgroundColor(color)`
+- `getBackgroundColor()`
+- `applyBackgroundColor(targetElement)`
+- `applyTheme(targetElement)` (accent + background)
+
 ## UI Mount Helpers
 
-- `mountStandardPlayerUI(player, root, options?)`
+- `mountPlayerUI(player, root, options?)`
+- `mountAudioDrop(target, options?)`
 - `mountTrackInfo(titleElement, artistElement, options?)`
 - `mountPlayButton(buttonElement, options?)`
 - `mountProgress(options)`
@@ -171,23 +228,63 @@ Subscribe with `player.on(eventName, handler)`:
 - `mountPlaylistTitle(element, options?)`
 - `mountDebugPanel(options)`
 
+### Player UI options
+
+`mountPlayerUI(player, root, options?)` supports:
+
+- `debugEnabled?: boolean`
+- `enableAudioDrop?: boolean` (default: `true`)
+- `enableErrorNotice?: boolean` (default: `true`)
+- `showLogo?: boolean` (default: `true`)
+- `persistUserPreferences?: boolean` (default: `true`)
+
+When preference persistence is enabled, user choices can override initial UI configuration on next sessions.
+
+### Drag and drop behavior
+
+`mountAudioDrop(target, options?)` accepts:
+
+- `activeClassName?: string` (default: `is-drag-over`)
+- `onDrop?: ({ file, track, tracks, kind }) => void`
+  - `kind` is `"audio"` or `"playlist"`
+  - `tracks` contains all resolved tracks (single/multiple audio files or parsed M3U/M3U8)
+
+Notes:
+
+- Dropping audio files builds a playlist from dropped files and starts playback from the first track.
+- Dropping an `.m3u`/`.m3u8` parses entries and starts playback from the first valid track.
+- If the drop includes both playlist + local audio files, local files are used when playlist entries match file names.
+
+### Error notices (including CORS)
+
+The standard UI listens for player `error` events and shows a temporary notice banner.
+For cross-origin sources that fail with `MEDIA_ERR_SRC_NOT_SUPPORTED`, the message indicates a likely CORS issue.
+
 ## Utility Methods
 
 - `setAccentColor(color)`
 - `getAccentColor()`
 - `applyAccentColor(targetElement)`
+- `setBackgroundColor(color)`
+- `getBackgroundColor()`
+- `applyBackgroundColor(targetElement)`
+- `applyTheme(targetElement)`
 - `formatTime(seconds)`
 - `getState()`
 - `getAudioElement()`
 
 ## Scripts
 
+- `npm run i18n:sync`
 - `npm run dev`
 - `npm run build`
 - `npm run build:css`
 - `npm run typecheck`
 - `npm run demo`
 
+`i18n:sync` generates `src/i18n/en.generated.ts` from `src/i18n/en.json`.
+This keeps runtime modules JavaScript-only while preserving JSON as the source of UI strings.
+
 ## Local Demo
 
 ```bash
@@ -198,13 +295,20 @@ npm run demo
 Open:
 
 - `http://127.0.0.1:4173/examples/demo.html`
+- `http://127.0.0.1:4173/examples/demo.html?debug=1`
+
+## Roadmap
+
+- Split reusable UI pieces into dedicated component packages
+- Keep `SmoothPlayer` core focused on engine + typed API
+- Provide clearer package boundaries for framework-specific integrations
 
 ## 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`.
+- Additional demo files are [SoundHelix songs](https://soundcloud.com/soundhelix) 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).

package/assets/icons/logo-wave-preview.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 220 220" fill="none" role="img" aria-labelledby="title desc">
+  <title id="title">Smooth Player Radial EQ Logo Preview</title>
+  <desc id="desc">Simple stylized radial equalizer icon.</desc>
+
+  <g transform="translate(110 110)" fill="currentColor">
+    <rect x="-1.8" y="-66" width="3.6" height="14" rx="1.8" transform="rotate(0)" />
+    <rect x="-1.8" y="-67" width="3.6" height="15" rx="1.8" transform="rotate(20)" />
+    <rect x="-1.8" y="-70" width="3.6" height="18" rx="1.8" transform="rotate(40)" />
+    <rect x="-1.8" y="-74" width="3.6" height="22" rx="1.8" transform="rotate(60)" />
+    <rect x="-1.8" y="-79" width="3.6" height="27" rx="1.8" transform="rotate(80)" />
+    <rect x="-1.8" y="-84" width="3.6" height="32" rx="1.8" transform="rotate(100)" />
+    <rect x="-1.8" y="-78" width="3.6" height="26" rx="1.8" transform="rotate(120)" />
+    <rect x="-1.8" y="-73" width="3.6" height="21" rx="1.8" transform="rotate(140)" />
+    <rect x="-1.8" y="-69" width="3.6" height="17" rx="1.8" transform="rotate(160)" />
+    <rect x="-1.8" y="-66" width="3.6" height="14" rx="1.8" transform="rotate(180)" />
+    <rect x="-1.8" y="-69" width="3.6" height="17" rx="1.8" transform="rotate(200)" />
+    <rect x="-1.8" y="-73" width="3.6" height="21" rx="1.8" transform="rotate(220)" />
+    <rect x="-1.8" y="-78" width="3.6" height="26" rx="1.8" transform="rotate(240)" />
+    <rect x="-1.8" y="-84" width="3.6" height="32" rx="1.8" transform="rotate(260)" />
+    <rect x="-1.8" y="-79" width="3.6" height="27" rx="1.8" transform="rotate(280)" />
+    <rect x="-1.8" y="-74" width="3.6" height="22" rx="1.8" transform="rotate(300)" />
+    <rect x="-1.8" y="-70" width="3.6" height="18" rx="1.8" transform="rotate(320)" />
+    <rect x="-1.8" y="-67" width="3.6" height="15" rx="1.8" transform="rotate(340)" />
+  </g>
+
+  <circle cx="110" cy="110" r="42" stroke="currentColor" stroke-width="6" />
+  <circle cx="110" cy="110" r="3.5" fill="currentColor" />
+</svg>

package/assets/icons/logo.svg

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_2" data-name="Layer 2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 719.94 512.71">
+  <g id="Layer_1-2" data-name="Layer 1">
+    <path d="M413.16,490.25c-57.26-21.12-103.19-70.69-126.86-127.41-11.89-27.4-19.05-56.99-25.69-85.52-2.08-8.77-4.14-17.52-6.59-26.22-3.13-10.29-6.52-24.33-15.95-29.79-13.13-6.64-28.03,10.64-37.54,18.38-17.69,15.88-36.21,31.98-57.01,44.46-13.51,8.56-33.41,15.43-35.37,33.35-.57,5,.27,10.58,1.95,16.42,40.81,126.49,190.52,206.15,322.7,170.08,9.61-5.13-13.86-11.13-19.44-13.68l-.19-.07Z"/>
+    <path d="M365.89,57.43c40.66,33.34,67.71,80.89,81.89,131.02,6.63,22.73,11.15,46.69,17.35,69.53,2.09,7.53,4.48,15.8,7.46,22.22,11.54,25.37,30.17,8.02,44.78-5.19,17.9-16.25,36.18-32.23,56.89-44.91,14.97-9.95,34.46-15.14,37.51-33.81.75-5.1.02-10.83-1.64-16.85C571.45,57.39,436.21-17.82,306.42,3.64c-5.43,1.02-28.88,4.41-20.84,10.41,5.26,3.54,13.28,5.63,19.56,8.12,21.83,8.01,42.56,20.25,60.59,35.12l.16.13Z"/>
+    <path d="M0,256.33c.16-2.17,2.42-3.29,4.42-4.67,4.31-2.51,9.11-4.6,13.93-6.71,24.87-10.21,57.01-25.84,77.89-49.13,44.3-48.31,66.45-112.27,140.9-121.77,68.74-8.25,124.54,43.84,146.34,105.42,22.37,52.67,19.47,160.73,85.38,177.19,48.3,8.84,82.28-45.34,117.64-71.14,16.82-13.13,35.7-23,56.52-28.47,19.86-5.57,52.31-8.41,69.25-4.55,11.81,2.68,9.57,6.94-3.92,12.92-5.19,2.41-11.94,5.22-19.53,8.62-21.23,9.29-43.05,21.6-59.76,38.27-32.53,31.3-51.43,75.95-88.23,103.12-32.42,24.86-77.3,31.49-115.31,16.15-35.32-13.64-62.84-43.07-79.55-76.74-19.72-38.62-24.46-83.52-35.94-124.85-5.57-19.35-13.14-38.79-26.57-54.02-26.91-30.22-60.79-24.68-89.72-1.85-28.45,22.05-53.78,54.65-87.58,70.86-20.88,10.66-45.96,16.01-68.93,17.21-10.29.51-35.49.73-37.21-5.8v-.07h-.02Z"/>
+  </g>
+</svg>

package/assets/icons/stop.svg

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

package/assets/icons/upload.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <path d="M12 16V6" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M8.5 9.5L12 6l3.5 3.5" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M6 14.5v2.1c0 1 .8 1.9 1.9 1.9h8.2c1 0 1.9-.8 1.9-1.9v-2.1" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/assets/icons/visualizer.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+  <path d="M4 14V10" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>
+  <path d="M8 17V7" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>
+  <path d="M12 15V9" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>
+  <path d="M16 19V5" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>
+  <path d="M20 13V11" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>
+</svg>

package/dist/SmoothPlayer.d.ts

@@ -1,4 +1,4 @@
-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";
+import { type AnalyzerOptions, type AudioTrack, type DebugPanelMountOptions, type AudioDropMountOptions, type PlaylistEntry, type PlaylistMountOptions, type PlaylistPanelController, type PlaylistPanelMountOptions, type PlaylistSwitcherMountOptions, type PlaylistTitleMountOptions, type PlayButtonMountOptions, type ProgressMountOptions, type PlaybackState, type PlayerEvents, type SmoothPlayerOptions, type SpectrumStyleOptions, type ShuffleToggleMountOptions, type TrackInfoMountOptions, type TransportControlsMountOptions, type VisualizerMode, type WaveformStyleOptions } from "./types.js";
 export declare class SmoothPlayer {
     private readonly audio;
     private readonly context;
@@ -9,7 +9,10 @@ export declare class SmoothPlayer {
     private activePlaylistId;
     private currentTrackIndex;
     private visualizerMode;
+    private spectrumStyle;
+    private waveformStyle;
     private accentColor;
+    private backgroundColor;
     private shuffleEnabled;
     private debugEnabled;
     private durationFallbackEnabled;
@@ -23,6 +26,10 @@ export declare class SmoothPlayer {
     setAccentColor(color: string): void;
     getAccentColor(): string;
     applyAccentColor(target: HTMLElement): void;
+    setBackgroundColor(color: string): void;
+    getBackgroundColor(): string;
+    applyBackgroundColor(target: HTMLElement): void;
+    applyTheme(target: HTMLElement): void;
     setShuffle(enabled: boolean): void;
     getShuffle(): boolean;
     setDebug(enabled: boolean): void;
@@ -53,6 +60,7 @@ export declare class SmoothPlayer {
     mountPlaylistPanel(options: PlaylistPanelMountOptions): PlaylistPanelController;
     mountDebugPanel(options: DebugPanelMountOptions): () => void;
     mountProgress(options: ProgressMountOptions): () => void;
+    mountAudioDrop(target: HTMLElement, options?: AudioDropMountOptions): () => void;
     play(index?: number): Promise<void>;
     pause(): void;
     toggle(): Promise<void>;
@@ -70,12 +78,19 @@ export declare class SmoothPlayer {
     getWaveformData(): Uint8Array;
     setVisualizer(mode: VisualizerMode): void;
     getVisualizer(): VisualizerMode;
+    setSpectrumStyle(options: Partial<SpectrumStyleOptions>): void;
+    getSpectrumStyle(): SpectrumStyleOptions;
+    setWaveformStyle(options: Partial<WaveformStyleOptions>): void;
+    getWaveformStyle(): WaveformStyleOptions;
     configureAnalyzer(options?: AnalyzerOptions): void;
+    private buildSurfaceGradient;
+    private buildPanelGradient;
     private getActivePlaylist;
     private getActiveTracks;
     private loadTrackByIndex;
     private emitPlaylistChange;
     private bindAudioEvents;
+    private isCrossOriginSource;
     private clamp;
     private pickRandomTrackIndex;
     private emitTimeUpdate;