@stargate91/pill-player 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Levente Gall (https://leventegall.dev)
+
+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,382 @@
+# @stargate91/pill-player
+
+> A futuristic HUD floating audio player component for React. Features an expandable console, 16-band spectrum visualizer, interactive seekbar, multi-provider playback (Local HTML5, SoundCloud, YouTube, Mixcloud), 8 cybernetic themes, and zero runtime UI dependencies.
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@stargate91/pill-player"><img src="https://img.shields.io/npm/v/@stargate91/pill-player?color=3794ff&label=npm&style=flat-square" alt="npm version" /></a>
+  <a href="https://bundlephobia.com/package/@stargate91/pill-player"><img src="https://img.shields.io/bundlephobia/minzip/@stargate91/pill-player?color=3794ff&label=minzipped&style=flat-square" alt="bundle size" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3794ff?style=flat-square" alt="license" /></a>
+  <img src="https://img.shields.io/badge/react-18%2B%20%7C%2019%2B-20232a?style=flat-square&logo=react&logoColor=61dafb" alt="React 18 / 19" />
+  <img src="https://img.shields.io/badge/typescript-strict-20232a?style=flat-square&logo=typescript&logoColor=3178c6" alt="TypeScript Strict" />
+  <img src="https://img.shields.io/badge/engines-HTML5%20%7C%20SC%20%7C%20YT%20%7C%20Mixcloud-20232a?style=flat-square" alt="Multi-Engine" />
+  <img src="https://img.shields.io/badge/ui%20deps-zero-10b981?style=flat-square" alt="Zero UI Dependencies" />
+</p>
+
+---
+
+<p align="center">
+  <img src="assets/preview.png" alt="Pill Player Preview" width="380" />
+</p>
+
+
+## Features
+
+- **Multi-Engine Audio Playback**: Unified playback across **Local Audio** (.mp3, .wav, .ogg streams), **SoundCloud** tracks and sets, **YouTube** videos and streams, and **Mixcloud** DJ mixes.
+- **Interactive HUD AudioSeekbar**: Real-time progress tracker with timestamps (`mm:ss` / `hh:mm:ss`), smooth mouse and touch scrubbing, and full keyboard navigation (Left/Right arrows for +/- 5s, PageUp/PageDown for +/- 30s).
+- **Seamless Headless Mode (`embedMode: "seamless"`)**: Third-party iframe widgets (Mixcloud, SoundCloud, YouTube) can be concealed off-screen while playback, telemetry, and native HUD controls take over with a uniform sci-fi aesthetic.
+- **16-Band DSP Spectrum Visualizer**: Real-time frequency analysis powered by Web Audio API for direct audio, with procedural BPM-synchronized pulse fallback.
+- **Floating Capsule and HUD Console**: Compact, unobtrusive floating capsule with animated mini-equalizer bars that expands into a cybernetic HUD console.
+- **8 Built-in Themes + Hex Custom Colors**: `stargate` (Electric Azure), `orbital` (Emerald/Cyan), `cyberpunk` (Neon Pink), `matrix` (Phosphor Green), `synthwave` (Sunset Orange), `amber` (Golden CRT), `nordic` (Polar Frost), and `minimal` (Monochrome). Override exact hex colors via the `colors` prop.
+- **Dynamic Screen Docking**: Supports `bottom-right`, `bottom-left`, `top-right`, `top-left`, and `inline` docking with automatic expansion orientation.
+- **Flexible Playlists**: Load tracks from in-memory arrays or directly from a local or remote JSON URL (`tracks="/playlist.json"`).
+- **Zero-Dependency Icon Slots**: Ships with lightweight handcrafted SVGs, or plug in **Lucide**, **Phosphor**, **FontAwesome**, or pure CSS **UnoCSS / Tailwind** icons.
+- **Accessible**: ARIA dialog and slider roles, keyboard shortcuts (Escape to close, arrows to seek), and screen reader support.
+
+---
+
+## Installation
+
+```bash
+npm install @stargate91/pill-player
+# or
+yarn add @stargate91/pill-player
+# or
+pnpm add @stargate91/pill-player
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { PillPlayer } from "@stargate91/pill-player";
+import "@stargate91/pill-player/dist/index.css";
+
+// Multi-provider playlist: Mixcloud, SoundCloud, YouTube, and direct HTML5 audio
+const tracks = [
+  {
+    id: "track-1",
+    title: "Synthwave Chill Radio",
+    code: "YT 01",
+    artist: "Lofi Girl",
+    genre: "Synthwave",
+    bpm: 128,
+    youtube: "https://www.youtube.com/watch?v=4xDzrJKXOOY", // YouTube stream or video ID
+  },
+  {
+    id: "track-2",
+    title: "cast_01",
+    code: "CAST 01",
+    artist: "lvntex",
+    genre: "SoundCloud Set",
+    bpm: 135,
+    soundcloud: "https://soundcloud.com/lvntex/cast_01", // SoundCloud track or set URL
+  },
+  {
+    id: "track-3",
+    title: "Critical Drum & Bass",
+    code: "Mix 07",
+    artist: "Stargate91",
+    genre: "Drum & Bass",
+    bpm: 174,
+    duration: "30 min",
+    feed: "/lvnte/nypox-podcast-drum-bass-phase-episode-7-critical-x-shogun/", // Mixcloud feed
+  },
+  {
+    id: "track-4",
+    title: "Deep Space Atmosphere",
+    code: "Audio 01",
+    artist: "CyberLab DSP",
+    genre: "Direct MP3 Stream",
+    bpm: 120,
+    duration: "0:45",
+    src: "https://actions.google.com/sounds/v1/science_fiction/alien_hum.ogg", // Direct audio file
+  },
+];
+
+export default function App() {
+  return (
+    <PillPlayer
+      tracks={tracks}
+      theme="stargate"
+      position="bottom-right"
+    />
+  );
+}
+```
+
+---
+
+## Supported Audio Sources
+
+Pill Player automatically detects the provider for each track in your list:
+
+| Provider | Track Property | Example Value | Description |
+| :--- | :--- | :--- | :--- |
+| **Direct HTML5 Audio** | `src` | `"https://example.com/stream.mp3"` | Standard audio files (.mp3, .wav, .ogg, .aac, radio streams). Powers real-time Web Audio API frequency analysis. |
+| **SoundCloud** | `soundcloud` | `"https://soundcloud.com/user/track"` | Any public SoundCloud track or set URL. Synced via official SoundCloud Widget API. |
+| **YouTube** | `youtube` | `"dQw4w9WgXcQ"` or full URL | YouTube video ID, watch URL, youtu.be, or shorts link. Synced via YouTube IFrame API. |
+| **Mixcloud** | `feed` | `"/user/mix-title/"` | Mixcloud cloudcast feed path. Synced via official Mixcloud Widget API. |
+
+---
+
+## Embed Modes (`embedMode`)
+
+Third-party widgets (like Mixcloud, SoundCloud, or YouTube) often have clashing colors or intrusive default UI. With `embedMode`, you decide how third-party streams render:
+
+```tsx
+<PillPlayer
+  tracks={tracks}
+  features={{
+    // "seamless": (Default) Hides third-party widgets off-screen.
+    //             Audio plays through the futuristic HUD console with the native AudioSeekbar.
+    // "themed":   Displays the official widget with dynamic theme-matched CSS filters.
+    // "widget":   Shows the unstyled raw iframe widget.
+    embedMode: "seamless",
+    showSeekbar: true, // Active whenever widgets are hidden or for local files
+  }}
+/>
+```
+
+> Note: For local audio files (`src`), the native **AudioSeekbar** is **always active** because HTML5 audio has no visual widget.
+
+---
+
+## Loading from JSON (Local or Remote)
+
+Instead of hardcoding a JavaScript array, you can pass a local or remote JSON URL. Pill Player automatically fetches and caches the tracklist:
+
+```tsx
+// Automatic fetch from a local file or remote API:
+<PillPlayer tracks="/demo/tracks.json" theme="stargate" />
+```
+
+### Example `tracks.json` schema:
+```json
+[
+  {
+    "id": "yt-01",
+    "title": "Synthwave Chill Radio",
+    "code": "YT 01",
+    "artist": "Lofi Girl",
+    "genre": "Synthwave",
+    "bpm": 128,
+    "youtube": "https://www.youtube.com/watch?v=4xDzrJKXOOY"
+  },
+  {
+    "id": "sc-01",
+    "title": "cast_01",
+    "code": "CAST 01",
+    "artist": "lvntex",
+    "genre": "SoundCloud Set",
+    "bpm": 135,
+    "soundcloud": "https://soundcloud.com/lvntex/cast_01"
+  },
+  {
+    "id": "mix-07",
+    "title": "Critical Drum & Bass",
+    "code": "Mix 07",
+    "artist": "Stargate91",
+    "genre": "Drum & Bass",
+    "bpm": 174,
+    "feed": "/lvnte/nypox-podcast-drum-bass-phase-episode-7-critical-x-shogun/"
+  },
+  {
+    "id": "local-01",
+    "title": "Synthesizer Atmosphere",
+    "code": "Audio 01",
+    "artist": "CyberLab DSP",
+    "genre": "Direct MP3 Stream",
+    "bpm": 120,
+    "duration": "0:45",
+    "src": "https://actions.google.com/sounds/v1/science_fiction/alien_hum.ogg"
+  }
+]
+```
+
+---
+
+## Themes & Custom Colors
+
+### Built-in Themes (`theme`)
+Pass any of the 8 pre-configured cybernetic themes:
+
+| Theme | Accent | Glow / Mood | Best For |
+| :--- | :--- | :--- | :--- |
+| `"stargate"` | Electric Azure (`#3794ff`) | Cobalt Aura | Modern VS Code & sci-fi terminal interfaces |
+| `"orbital"` | Cyan / Emerald (`#00f0ff`) | Space Station Glow | Deep space and electronic ambient |
+| `"cyberpunk"` | Neon Pink (`#ff0055`) | Night City Neon | High contrast synthwave & cyberpunk |
+| `"matrix"` | Phosphor Green (`#00ff66`) | Terminal CRT | Retro hacker aesthetics & dark terminals |
+| `"synthwave"` | Sunset Orange (`#ff7700`) | Outrun Horizon | Retrowave, 80s vibes, and warm gradients |
+| `"amber"` | Warm Amber (`#ffb000`) | Vintage CRT Monitor | Industrial telemetry and retro audio gear |
+| `"nordic"` | Polar Frost (`#7aa2f7`) | Cool Ice & Arctic Blue | Clean minimalist dark palettes |
+| `"minimal"` | Monochrome White (`#f0f0f0`) | Subtle Slate White | High-end minimal portfolios and neutral UIs |
+
+### Custom Color Overrides (`colors`)
+Override theme variables with custom hex / rgba values:
+
+```tsx
+<PillPlayer
+  tracks={tracks}
+  colors={{
+    accent: "#3794ff",               // Controls, active items, seekbar progress
+    secondary: "#9cdcfe",            // Badges, LEDs, visualizer highlights
+    bg: "#121418",                   // Main HUD card & pill background
+    surface: "rgba(255, 255, 255, 0.04)", // Internal card surfaces
+    border: "rgba(55, 148, 255, 0.25)",
+    glow: "rgba(55, 148, 255, 0.4)",
+    text: "#ffffff",
+    textDim: "#858585",
+  }}
+/>
+```
+
+---
+
+## Custom Icons
+
+Pill Player has zero runtime icon dependencies by default. Supply custom icons via the `icons` prop using Lucide React, Phosphor, FontAwesome, or pure CSS UnoCSS / Tailwind classes:
+
+### Using with `lucide-react`
+```tsx
+import { Play, Pause, SkipBack, SkipForward, Volume2, VolumeX, X, ExternalLink } from "lucide-react";
+
+<PillPlayer
+  tracks={tracks}
+  icons={{
+    play: <Play size={15} fill="currentColor" />,
+    pause: <Pause size={15} fill="currentColor" />,
+    prev: <SkipBack size={16} />,
+    next: <SkipForward size={16} />,
+    mute: <Volume2 size={16} />,
+    unmute: <VolumeX size={16} />,
+    close: <X size={16} />,
+    external: <ExternalLink size={15} />,
+  }}
+/>
+```
+
+### Using with UnoCSS / Tailwind CSS (0 KB Runtime JS)
+```tsx
+<PillPlayer
+  tracks={tracks}
+  icons={{
+    play: <span className="i-lucide-play inline-block text-[15px]" />,
+    pause: <span className="i-lucide-pause inline-block text-[15px]" />,
+    prev: <span className="i-lucide-skip-back inline-block text-[16px]" />,
+    next: <span className="i-lucide-skip-forward inline-block text-[16px]" />,
+    mute: <span className="i-lucide-volume-2 inline-block text-[16px]" />,
+    unmute: <span className="i-lucide-volume-x inline-block text-[16px]" />,
+    close: <span className="i-lucide-x inline-block text-[15px]" />,
+    external: <span className="i-lucide-external-link inline-block text-[15px]" />,
+  }}
+/>
+```
+
+---
+
+## Complete API Reference
+
+### `<PillPlayer />` Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `tracks` | `AudioTrack[] | string` | **Required** | Array of track objects or URL path to a remote/local JSON playlist. |
+| `theme` | `PillTheme` | `"orbital"` | Built-in theme (`"stargate"`, `"orbital"`, `"cyberpunk"`, `"matrix"`, `"synthwave"`, `"amber"`, `"nordic"`, `"minimal"`). |
+| `colors` | `PillColors` | `undefined` | Optional hex/rgba overrides (`accent`, `secondary`, `bg`, `surface`, `border`, `glow`, `text`, `textDim`). |
+| `position` | `PillPosition` | `"bottom-right"` | Screen anchor position: `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"`, or `"inline"`. |
+| `icons` | `PillIcons` | Built-in SVGs | Custom icon elements for play, pause, prev, next, mute, unmute, close, external. |
+| `labels` | `Partial<PillLabels>` | English defaults | Custom i18n label dictionary for telemetry, buttons, and ARIA strings. |
+| `features` | `PillFeatures` | `{}` | Toggleable feature flags (see table below). |
+| `initialOpen` | `boolean` | `false` | Whether the HUD card starts expanded on page load. |
+| `className` | `string` | `""` | Additional CSS class for the player anchor container. |
+| `style` | `CSSProperties` | `undefined` | Additional inline style overrides. |
+| `onTrackChange` | `(track: AudioTrack, index: number) => void` | `undefined` | Callback fired whenever the active track changes. |
+| `onPlayStateChange` | `(isPlaying: boolean) => void` | `undefined` | Callback fired whenever playback toggles between play and pause. |
+
+---
+
+### `AudioTrack` Schema
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `id` | `string` | **Required**. Unique track identifier. |
+| `title` | `string` | **Required**. Track title displayed in HUD and playlist. |
+| `code` | `string` | Optional short identifier code (e.g. `"Mix 01"`, `"YT 01"`, `"EP-02"`). |
+| `artist` | `string` | Optional artist / creator name. |
+| `genre` | `string` | Optional genre tag badge (e.g. `"Drum & Bass"`, `"Synthwave"`). |
+| `bpm` | `number | string` | Optional BPM to drive procedural spectrum animation speed (e.g. `174`, `"128 BPM"`). |
+| `duration` | `string` | Optional display duration (e.g. `"3:45"`, `"30 min"`). |
+| `src` | `string` | Direct HTML5 audio stream or file URL (.mp3, .wav, .ogg, .aac). |
+| `soundcloud` | `string` | SoundCloud track or set URL. |
+| `youtube` | `string` | YouTube video ID (`"dQw4w9WgXcQ"`) or full video URL. |
+| `feed` | `string` | Mixcloud feed path (e.g. `"/user/mix-title/"`). |
+| `externalUrl` | `string` | Optional custom external link override. If omitted, provider URLs are automatically used. |
+
+---
+
+### `PillFeatures` Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `showSeekbar` | `boolean` | `true` | Displays the interactive HUD seekbar for local audio, SoundCloud, and headless streams. |
+| `showSpectrum` | `boolean` | `true` | Displays the 16-band DSP Equalizer stage. |
+| `showPlaylist` | `boolean` | `true` | Displays the tracklist selection area when more than 1 track is present. |
+| `embedMode` | `"seamless" | "themed" | "widget"` | `"seamless"` | Stream embed mode: `"seamless"` (headless HUD + seekbar), `"themed"` (color-filtered iframe), `"widget"` (raw iframe). |
+| `beaconGlow` | `boolean` | `false` | Adds a subtle periodic 4-second breathing dimming & opacity pulse to the HUD console. |
+| `persistState` | `boolean` | `true` | Remembers the last selected track in browser `localStorage`. |
+| `enableKeyboardShortcuts` | `boolean` | `true` | Enables Escape key to collapse HUD and Arrow keys to scrub audio. |
+
+---
+
+### `PillLabels` Localization Dictionary
+
+Pass a partial dictionary to the `labels` prop to translate or customize any string:
+
+```tsx
+<PillPlayer
+  tracks={tracks}
+  labels={{
+    badge: "AUDIO PLAYER",
+    openPlayer: "Open player",
+    closePlayer: "Close player",
+    play: "Play",
+    pause: "Pause",
+    prevTrack: "Previous",
+    nextTrack: "Next",
+    mute: "Mute",
+    unmute: "Unmute",
+    selectTrack: "PLAYLIST",
+    frequenciesActive: "PLAYING",
+    frequenciesStandby: "PAUSED",
+    spectrumHeader: "EQUALIZER",
+    subtitle: "Audio",
+  }}
+/>
+```
+
+---
+
+## Local Development & Demo
+
+Clone the repository and start the interactive Vite dev server:
+
+```bash
+cd pill-player
+npm install
+npm run dev
+```
+
+Open `http://localhost:5173/` to test all themes, positions, custom color pickers, providers, and seekbar controls.
+
+To compile the library bundle for distribution:
+
+```bash
+npm run build
+```
+
+---
+
+## License
+
+MIT (c) [Levente Gall](https://leventegall.dev)