vibeplay

Precision Audiophile Music Console & Lo-Fi Lounge for Linux (Ubuntu 24.04 LTS)
Bit-perfect ALSA hardware reservation, dynamic DAC detection, 15 tactile Lo-Fi Lounge screens, modular add-on architecture, Camelot harmonic key mixing, and local natural-language smart playlists.

• 🛡️ Bit-Perfect Hardware Reservation (hw:) & PipeWire Fallback: Direct hardware communication bypassing operating system resampling and mixers, with auto-fallback to PipeWire so audio never cuts out.
• 🎚️ Strict Bit-Perfect Audio Integrity: Enforces sample bit-perfection during direct ALSA streaming (hw:X,Y) by completely bypassing EQ and software volume processing, with a 1-click switcher to DSP mode when tone shaping is desired.
• ☕ 15-View Lo-Fi Lounge Interface: Complete tactile desktop suite featuring a responsive Boombox capsule transport bar (docked flush on standard displays, floating on high-DPI displays), Record Crate vinyl sleeve browser, sortable Master Table, and dedicated turntable Fullscreen Now-Playing mode with 60fps canvas visualizer.
• 🎛️ Natural-Language & Guided Smart Playlists:
  • Natural-Language Prompting: Type common-language prompts like "chill lofi study vibes", "high energy workout", or "dance party around 125 bpm" to instantly query your collection via local rule-based heuristics without cloud or LLM overhead.
  • Guided 4-Step Architect: Seed track picker, energy arc curves (Energy Ramp, Peak-Hour Wave, Steady Pulse, Late Night Chill), live Camelot harmonic key transition scoring (1.0, 0.95, 0.70, 0.50, 0.20), and native HTML5 drag-and-drop track reordering.
• 🧩 Modular Add-on / Plugin Subsystem: Clean separation between the lean audio core and optional features via vibeplay.plugins:
  • vibeplay.plugins.dsp: Sound DSP & Acoustics Convolver (5-band PEQ with interactive SVG curve and SOFA 7.1.4 HRTF binaural spatial convolution).
  • vibeplay.plugins.maintenance: Library Maintenance & Quality Tools (duplicate detection and MusicBrainz/AcoustID metadata enrichment).
  • Add-on Toybox: GUI dialog in the titlebar and preferences to inspect installed plugins and toggle their activation.
• 🔍 Track Inspector & Real-Time Telemetry: Acoustic inspection deck featuring Camelot harmonic key wheels, tempo, LUFS loudness, 7 heuristic mood bars, and a live Server-Sent Events (SSE) telemetry deck (SVG oscilloscope, 9-segment VU headroom meter, DMA ring buffer status).
• 🎨 "God of Ink" Design System: 9 audiophile dark theme presets (God of Ink, Wine / Uncut Amethyst, Obsidian / Lavender, Swimming with the Whales, Mint City, Slate Audiophile, Beyond the Boundary, The Unknown, Castle In The Sky) adhering strictly to WCAG 2.1 contrast standards with zero hardcoded CSS colors and session persistence.
• 🔒 Security Invariants: Loopback-only binding (127.0.0.1 / localhost), ephemeral IPC session tokens, and atomic settings storage with chmod 600 permissions.

Download the latest .deb package from GitHub Releases or install locally:

# Install the Debian package (includes standalone binary, .desktop launcher, icons, and systemd service)
sudo apt install ./dist/vibeplay_0.2.0_amd64.deb --reinstall
# or using dpkg:
sudo dpkg -i dist/vibeplay_0.2.0_amd64.deb

# Launch from your desktop app menu or run:
vibeplay-desktop

If you don't have root privileges or want to install strictly into your user environment (~/.local):

# 1. Clone repository
git clone https://github.com/defiqantcoder/vibeplay.git
cd vibeplay

# 2. Run the user-space installer
bash scripts/install-desktop.sh

# 3. Launch from your application menu or terminal
vibeplay-desktop

For fast iteration without rebuilding native binaries:

# 1. Install system prerequisites
sudo apt update && sudo apt install -y ffmpeg libsndfile1 libchromaprint-tools mpd

# 2. Install Astral uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Clone and sync dependencies
git clone https://github.com/defiqantcoder/vibeplay.git
cd vibeplay
uv sync

# 4. Launch Desktop Application
uv run vibeplay-desktop

# (Tip: Use --browser to launch in a standard web browser with developer tools)
uv run vibeplay-desktop --browser

vibeplay provides a complete command-line interface for headless automation, background indexing, and diagnostic audits:

# Scan a music directory recursively and index audio files
uv run vibeplay scan /path/to/your/music

# Fingerprint tracks with AcoustID and enrich with MusicBrainz metadata (via maintenance plugin)
uv run vibeplay enrich

# Extract rhythm, key, BPM, and mood features using Essentia
uv run vibeplay analyze

# Generate smart playlists using local rule heuristics
uv run vibeplay playlist --name "Chill Evening" --vibe chill
uv run vibeplay playlist --name "Energy Workout" --arc peak

# Export playlist to file (m3u, m3u8, json, csv)
uv run vibeplay export 1 --format m3u8

# Detect library duplicates by AcoustID and acoustic similarity (via maintenance plugin)
uv run vibeplay duplicates

# Control playback from terminal
uv run vibeplay control play
uv run vibeplay control pause
uv run vibeplay control next

# Check system capabilities and optional dependencies
uv run vibeplay doctor

# Run automated release gate validation (loopback, permissions, themes, templates)
uv run vibeplay desktop --release-gate

graph TD
    UI["Desktop UI Shell<br/>(WebKit2GTK / HTML5 / HTMX / SVG)"] -->|Loopback HTTP / SSE| API["FastAPI Application Server<br/>(127.0.0.1:Ephemeral Port)"]
    API -->|Lean Core Database| DB[("SQLite Database<br/>(WAL Mode, Fast Heuristics)")]
    API -->|Real-Time Telemetry| SSE["SSE Telemetry Stream<br/>(telemetry_tick / dac_lock / xrun)"]
    API -->|Playback Engine| PLY["Lean Player Engine<br/>(player.py / alsa_reservation.py)"]
    PLY -->|Pure Bit-Perfect Mode| ALSA["ALSA Direct Sink<br/>(hw:X,Y / Exclusive Hardware Lock)"]
    PLY -->|Shared System Mode| PW["PipeWire Universal Sink<br/>(Sound Server Fallback)"]
    API -->|Modular Plugin Manager| PLUG["vibeplay.plugins Subsystem<br/>(plugin_manager.py)"]
    PLUG -->|DSP Add-on| DSP["vibeplay.plugins.dsp<br/>(PEQ 5-Band / SOFA 7.1.4 3D)"]
    PLUG -->|Maintenance Add-on| MAINT["vibeplay.plugins.maintenance<br/>(AcoustID / MusicBrainz / Duplicates)"]
    API -->|Acoustic Intelligence| ESS["Essentia 2.1 / Librosa<br/>(BPM, Camelot Key, Danceability, Energy)"]

Run the test suite via pytest:

# Run all regression tests
uv run pytest

# Run with test coverage report
uv run pytest --cov=src/vibeplay --cov-report=term-missing

# Run release gate audit
uv run vibeplay desktop --release-gate

Distributed under the MIT License. See LICENSE for more information.