Nightingale Karaoke Skill Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection. Nightingale is a self contained, ML powered karaoke application written in Rust (Bevy engine). It scans a local music folder, separates vocals from instrumentals (UVR Karaoke model or Demucs), transcribes lyrics with word level timestamps (WhisperX), and plays back with synchronized highlighting, real time pitch scoring, player profiles, and GPU shader / video backgrounds. Everything — ffmpeg, Python, PyTorch, ML models — is bootstrapped automatically on first launch. Installation Pre built Binary (Recommended) Download the latest release from the [Releases page](https://github.com/rzru/nightingale/releases) for your platform and run it. macOS only — remove quarantine after extracting: Build from Source Prerequisites: Rust 1.85+ (edition 2024) Linux additionally needs: libasound2 dev libudev dev libwayland dev libxkbcommon dev Release Packaging Outputs a .tar.gz (Linux/macOS) or .zip (Windows) ready for distribution. First Launch / Bootstrap On first run, Nightingale downloads and configures: ffmpeg binary uv (Python package manager) Python 3.10 via uv PyTorch + WhisperX + audio separator in a virtual environment UVR Karaoke ONNX model and WhisperX large v3 model This takes 2–10 minutes depending on network speed. A progress screen is shown in app. To force re bootstrap at any time: Bootstrap completion is marked by ~/.nightingale/vendor/.ready . CLI Flags Flag Description setup Force re run of the first launch bootstrap (re downloads vendor deps) Keyboard & Gamepad Controls Navigation Action Keyboard Gamepad Move Arrow keys D pad / Left stick Confirm Enter A (South) Back Escape B (East) / Start Switch panel Tab — Search Type to filter — Playback Action Keyboard Gamepad Pause / Resume Space Start Exit to menu Escape B (East) Toggle guide vocals G — Guide volume up/down + / — Cycle background T — Cycle video flavor F — Toggle microphone M — Next microphone N — Toggle fullscreen F11 — Configuration Main Config Located at ~/.nightingale/config.json . Edit directly or via in app settings. separator options: "uvr" (default, preserves backing vocals) "demucs" background theme options: "plasma" , "aurora" , "waves" , "nebula" , "starfield" , "video" , "source video" video flavor options: "nature" , "underwater" , "space" , "city" , "countryside" Profiles Located at ~/.nightingale/profiles.json : Pixabay Video Backgrounds (Dev) API key is embedded in release builds. For local development, create .env at project root: The release script ( make release.sh ) sources .env automatically. Data Storage Layout Cache keys are blake3 hashes of the source file — re analysis only triggers if the file changes or is manually invalidated. Supported File Formats Audio: .mp3 , .flac , .ogg , .wav , .m4a , .aac , .wma Video: .mp4 , .mkv , .avi , .webm , .mov , .m4v Video files: audio track is extracted, vocals separated, original video plays as background automatically. Hardware Acceleration PyTorch backend is auto detected: Backend Device Notes CUDA NVIDIA GPU Fastest; ~2–5 min/song MPS Apple Silicon macOS; WhisperX alignment falls back to CPU CPU Any Always works; ~10–20 min/song UVR Karaoke model uses ONNX Runtime with CUDA (NVIDIA) or CoreML (Apple Silicon) automatically. Processing Pipeline Code Patterns Adding a New Background Theme (Bevy System) Extending Config Deserialization Triggering Re analysis Programmatically Computing a Song's Blake3 Hash (for Cache Lookup) Profile Score Update Pattern Troubleshooting Bootstrap Fails / Stuck on Setup Screen Song Analysis Hangs or Errors macOS "App is damaged" Error GPU Not Being Used NVIDIA: Ensure CUDA drivers are installed and nvidia smi shows your GPU. Apple Silicon: MPS is used automatically on macOS with Apple Silicon; WhisperX alignment falls back to CPU (normal behavior). Check ~/.nightingale/vendor/venv — if PyTorch installed the CPU only build, re bootstrap after installing CUDA drivers. Cache Corruption / Wrong Lyrics Then re open the song in Nightingale to re analyze. Audio Playback Issues (Linux) Ensure ALSA/PulseAudio/PipeWire is running. Install missing deps: Video Backgrounds Not Loading Video backgrounds are pre downloaded during setup via the Pixabay API. For development builds, ensure .env contains a valid PIXABAY API KEY . If videos are missing in a release build, run setup to re trigger the download. Platform Targets Platform Target Triple Linux x86 64 x86 64 unknown linux gnu Linux aarch64 aarch64 unknown linux gnu macOS ARM aarch64 apple darwin macOS Intel x86 64 apple darwin Windows x86 64 x86 64 pc windows msvc Cross compile with: License GPL 3.0 or later. See [LICENSE](https://github.com/rzru/nightingale/blob/main/LICENSE).

nightingale-karaoke