GhostWave

Open source local music player with local AI Integration.

Comment

πŸŽƒ GhostWave β€” Local-First Music Player & AI Crate Curator

GhostWave Hero Banner

A spooky, local-first music player, crate manager, and audio-reactive visualizer powered by local open-weight AI (Gemma 3 via Ollama).

The Origin Story β€’ Key Features β€’ Architecture β€’ Getting Started β€’ Local AI Setup β€’ Tauri Desktop β€’ QA & Testing β€’ Deployment

⚑ The "Ghost in the Machine" Origin Story

(An imagined product scenario inspired by seasonal thunderstorms and connectivity concerns)

Imagine Halloween Eve. Outside, a violent seasonal thunderstorm batters the neighborhood. The grid blinksβ€”and the house plunges into darkness.

When power snaps back on ten minutes later, the internet connection is dead. A gathering of friends is waiting for music, but the host's phone streaming app hangs on a spinning wheel: buffering error 404, no connection.

An offline backup drive of local music is plugged inβ€”thousands of anime themes, Vocaloid tracks, electronic synths, and classical recordings. But an immediate wall appears:

  • Half the files have missing ID3 tags or unicode filenames (Matsuri（Official VideoοΌ‰(MP3_160K).mp3).
  • Everyone wants a high-energy, fast-paced electronic Halloween playlist, but nobody wants to spend 45 minutes manually browsing through 2,000 files in a generic file explorer.
  • Mainstream "smart" playlist generators require active cloud connections to remote LLMs that scrape personal listening data and fail when the network dies.

Why should playing and organizing your own local music depend on external servers?

That scenario is the creative spark behind GhostWave: A local-first music player that pairs a high-performance audio engine and Halloween-inspired reactive visualizer with local open-weight AI (Google's Gemma 3 4B running on your local machine via Ollama). When connectivity drops, the ghost in the machine awakensβ€”curating smart playlists, diagnosing missing metadata, and running reactive visualizers directly on your local hardware without remote AI subscriptions.

🎧 Key Features

1. πŸ—„οΈ Crate Deck (Local Music Vault)

  • Zero-Cloud Audio Indexing: Reads MP3, FLAC, WAV, OGG, and AAC directly into an IndexedDB catalog via music-metadata-browser.
  • Zero File Mutation Invariant: Your source music library is treated as a read-only vault. Files are never overwritten or deleted without explicit user confirmation.
  • Deep Search & Filtering: Instant fuzzy filtering by title, artist, album, format pill filters, and customizable sort orders.
  • Dual View Modes: Seamlessly switch between compact DJ Table view and rich Album Art Grid cards.

2. πŸŽ›οΈ Audio Deck & Slide-Up Spectral Visualizer

  • Web Audio API Engine: Real-time decoding, elapsed time tracking, seamless track queueing, volume control with mute toggle, shuffle, and cycle repeat modes (Off / All / Track).
  • Halloween Audio-Reactive Visualizers: Real-time frequency analysis with selectable styles (Waveform, Neon Bats, Spectral Columns, and Spooky Jack-o'-Lantern pulses) in Dark and Light Halloween palettes.
  • Queue Management: Slide-up queue drawer with drag reordering, removal, and auto-population from crates.

3. πŸ€– Local AI Playlist Curator (Gemma 3 + Ollama)

  • 100% Offline AI Invocations: Communicates with your local Ollama daemon (http://127.0.0.1:11434) using gemma3:4b.
  • Natural-Language Understanding: Ask for "Fast electronic workout tracks with punchy bass" or "Spooky atmospheric ambient tracks under 30 minutes".
  • Strict Structured Schema: Gemma 3 outputs deterministic JSON schemas with crateName, description, trackIds, and reasoning.
  • Hallucination Shield: Output track IDs are strictly validated against existing IndexedDB records. Any fabricated tracks are discarded before presentation.
  • Human-in-the-Loop Review: Preview proposed track selections, verify duration limits, and save proposals to Crates with one click.

4. 🩺 Library Health & Non-Destructive Tagging

  • Deterministic Health Audits: Flags missing tags, unicode inconsistencies, duplicate hashes, and metadata collisions.
  • Side-by-Side Tag Diff Inspector: Compare current metadata with proposed fixes before committing changes.
  • Safe Renaming Templates: Preview filename changes (e.g. {artist} - {title}) with collision detection before disk writing.

5. 🌐 Online Enrichment & External Intelligence (Optional)

  • Clear Separation: Core audio playback, visualizers, and crate management remain 100% functional offline without network access.
  • MusicBrainz Integration: Query open recording databases with rate-limit compliance.
  • Cover Art Archive & LRCLIB: Preview verified community release artwork and plain/synced lyrics.
  • SerpApi Search Partner: User-provided SerpApi key is stored locally in client-side browser storage and sent directly in the browser's request URL to SerpApi. It is not stored on a remote server.
  • Graceful Offline Degradation: If internet is absent, all core local audio and AI features continue working seamlessly.

6. πŸ”„ 16-Bit PCM Audio Converter

  • Non-Destructive Transcoding: Converts input audio to uncompressed 16-bit PCM WAV using Web Audio API buffer decoding and custom RIFF encoding (WAV is fully verified; other format options are experimental).
  • Configurable Audio Specs: Sample rate (44.1kHz, 48kHz, 96kHz), channels (Mono/Stereo), and custom filename suffixes.

7. πŸ“Š History & Transparent Recommendations

  • Local Scrobbling: Automatically records completed plays (>= 30s or >= 50% duration) versus skips.
  • Listening Analytics: Tracks total listening sessions, hours, skip rates, and favorite genres.
  • Transparent Recommendations: Offline recommendation engine prioritizing unplayed gems with clear human-readable rationales.
  • Local Control: Toggle history tracking on/off anytime or purge records with one click.

8. πŸ›‘οΈ Privacy-Preserving Sentry Telemetry (Optional)

  • Diagnostic Observability: Monitors application crashes and AI prompt latencies.
  • Sanitized Telemetry: Local filesystem paths, audio bytes, filenames, listening history, and user prompt strings are scrubbed by beforeSend filters prior to dispatch.
  • User Controlled: Can be disabled at any time in Settings.

πŸ›οΈ Architecture

GhostWave uses a modular, skeleton-first container architecture:

GhostWave Architecture
β”‚
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ components/
β”‚   β”‚   β”œβ”€β”€ common/           # Dialogs, modals, ScanModal, OnlineEnrichmentModal
β”‚   β”‚   β”œβ”€β”€ layout/           # AppShell, SidebarDeck, PlayerControls, VisualizerDrawer
β”‚   β”‚   └── player/           # Canvas visualizer renderers, audio transport
β”‚   β”œβ”€β”€ context/
β”‚   β”‚   └── AppContext.tsx    # Single source of truth (Library, Queue, Settings, Toast)
β”‚   β”œβ”€β”€ screens/
β”‚   β”‚   β”œβ”€β”€ LibraryScreen.tsx # Crate deck table/grid view
β”‚   β”‚   β”œβ”€β”€ PlaylistsScreen   # Saved crates management
β”‚   β”‚   β”œβ”€β”€ HealthCleanup     # Health audit and proposed tag diffs
β”‚   β”‚   β”œβ”€β”€ LocalAiScreen.tsx # Ollama Gemma 3 natural-language agent
β”‚   β”‚   β”œβ”€β”€ ListeningHistory  # Playback analytics and recommendations
β”‚   β”‚   └── SettingsScreen    # Platform config, Ollama endpoint, Sentry, SerpApi
β”‚   β”œβ”€β”€ services/
β”‚   β”‚   β”œβ”€β”€ ai/               # OllamaClient, AiPlaylistService, prompt templates
β”‚   β”‚   β”œβ”€β”€ audio/            # AudioPlayerEngine, AudioConversionService
β”‚   β”‚   β”œβ”€β”€ enrichment/       # MusicBrainz, SerpApi, CoverArtArchive, LRCLIB
β”‚   β”‚   β”œβ”€β”€ history/          # HistoryService, scrobbling, recommendations
β”‚   β”‚   β”œβ”€β”€ platform/         # WebFilePlatform vs TauriFilePlatform adapters
β”‚   β”‚   └── telemetry/        # SentryTelemetry with privacy sanitizers
β”‚   └── types/                # Domain models: Track, Crate, Proposal, PlaybackEvent
└── src-tauri/                # Native Tauri 2 Rust desktop wrapper

πŸš€ Getting Started

Prerequisites

  • Node.js: v20+ or v22+
  • npm: v9+
  • (Optional for AI) Ollama: Installed locally from ollama.com

Installation & Local Web Dev

# Clone the repository
git clone https://github.com/edgiaxel/GhostWave.git
cd GhostWave

# Install dependencies
npm install

# Start Vite development server
npm run dev

Open your browser at http://localhost:5173.

πŸ€– Running Local AI (Gemma 3)

GhostWave connects to Ollama over its standard local API endpoint (http://127.0.0.1:11434).

  1. Install Ollama: bash curl -fsSL https://ollama.com/install.sh | sh
  2. Pull the Gemma 3 4B model: bash ollama pull gemma3:4b
  3. Start the Ollama server: bash ollama serve
  4. In GhostWave, open Settings & Platform $\rightarrow$ Local AI (Ollama):
    • Endpoint: http://127.0.0.1:11434
    • Model: gemma3:4b
    • Click Test Connection to confirm connectivity.

πŸ–₯️ Tauri Desktop App

GhostWave is packaged as a native desktop application using Tauri 2.

Build Desktop Binaries (Linux / Windows)

# Install Linux development dependencies (Ubuntu/Debian)
sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf libgtk-3-dev

# Build native desktop package (.deb, .AppImage, or .exe)
npx tauri build

Generated packages will be located in: src-tauri/target/release/bundle/

Automated GitHub Actions CI & Desktop Releases

The repository includes automated CI in .github/workflows/desktop-build.yml that builds native packages:

  • Ubuntu Linux: .deb and .AppImage packages compiled on ubuntu-22.04.
  • Windows x64: .exe installer compiled on windows-latest.

Note: Binaries will become publicly downloadable on the GitHub Releases page once a tagged release (e.g. v0.14.0) is published.

🎬 Product Film & Demo Footage

A Remotion-edited 1080p product film is available in video/out/ alongside the original high-definition automated browser walkthrough:

πŸ§ͺ Testing & Verification

GhostWave enforces a zero-mock integration policy with automated regression suites:

# Run Vitest unit & integration suites (12 suites, 121 tests)
npm test

# Run Playwright End-to-End browser suites (10 suites, 30 tests)
npm run test:e2e

Test Coverage Highlights:

  • Suite 01: Shell navigation, theme toggling (Dark/Light Halloween), split pane resize handles, settings persistence.
  • Suite 02: Real library import from 74-track audio vault, multi-field search, format filters, corrupt file handling.
  • Suite 03: Audio playback progression, next/previous tracks, seek bar, volume, shuffle, repeat, slide-up visualizer drawer.
  • Suite 04: Crate creation, adding tracks, reordering, title edits, deletion confirmation.
  • Suite 05: Library health audits, tag proposal diffs, inline edits, safe rename previews.
  • Suite 06: Audio conversion to 16-bit PCM WAV, non-destructive source file preservation.
  • Suite 07: Playback scrobbling (30s/50% boundary), skip rates, transparent recommendation engine.
  • Suite 08: Real local Ollama daemon connection, Gemma 3 4B inference, structured JSON validation.
  • Suite 09: MusicBrainz candidate matching, Cover Art Archive, LRCLIB synced lyrics, SerpApi credentials.
  • Suite 10: Sentry envelope verification, "Break the world" error test, and privacy path scrubbers.

☁️ Deployment (Render)

GhostWave is deployed as a static web application on Render:

  • Blueprint File: render.yaml
  • Publish Path: ./dist
  • Build Command: npm install && npm run build
  • SPA Routing: Configured via render.yaml routes rewrite and public/_redirects (/* /index.html 200).

πŸ“œ License

This project is licensed under the terms of the MIT License. Developed for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine.

Share this project:

Updates