@stargate91/pill-player

v0.1.0

Published

a month ago

Futuristic HUD cyber audio player with 16-band DSP spectrum visualizer and collapsible floating pill widget.

0High
0Medium
0Low

stargate91

audio-player hud cyberpunk spectrum-visualizer react-audio-player web-audio-api floating-widget

@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.

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

npm install @stargate91/pill-player
# or
yarn add @stargate91/pill-player
# or
pnpm add @stargate91/pill-player

Quick Start

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:

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:

<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:

// Automatic fetch from a local file or remote API:
<PillPlayer tracks="/demo/tracks.json" theme="stargate" />

Example `tracks.json` schema:

[
  {
    "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:

Custom Color Overrides (`colors`)

Override theme variables with custom hex / rgba values:

<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`

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)

<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

`PillFeatures` Options

`PillLabels` Localization Dictionary

Pass a partial dictionary to the labels prop to translate or customize any string:

<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:

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:

npm run build

License

MIT (c) Levente Gall

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@stargate91/pill-player

Features

Installation

Quick Start

Supported Audio Sources

Embed Modes (embedMode)

Loading from JSON (Local or Remote)

Example tracks.json schema:

Themes & Custom Colors

Built-in Themes (theme)

Custom Color Overrides (colors)

Custom Icons

Using with lucide-react

Using with UnoCSS / Tailwind CSS (0 KB Runtime JS)

Complete API Reference

<PillPlayer /> Props

AudioTrack Schema

PillFeatures Options

PillLabels Localization Dictionary

Local Development & Demo

License

Embed Modes (`embedMode`)

Example `tracks.json` schema:

Built-in Themes (`theme`)

Custom Color Overrides (`colors`)

Using with `lucide-react`

`<PillPlayer />` Props

`AudioTrack` Schema

`PillFeatures` Options

`PillLabels` Localization Dictionary