# 🎵 rhyth-rs (v0.1.0-beta)
[](https://www.rust-lang.org/)
[](https://www.navidrome.org/)
[](https://opensubsonic.netlify.app/)
[](https://opensource.org/licenses/MIT)
[](https://ratatui.rs/)
*A blazing fast, modern, and beautiful terminal audio player for Navidrome and OpenSubsonic servers, written in pure Rust.*
---
## ✨ Features
- 🎧 **Pure Symphonia Audio Pipeline**: Flawless bit-perfect decoding for all major audio formats (**FLAC, MP3, AAC, ALAC, Vorbis, Opus, WAV**) with zero playback panics and crystal-clear sound via Rodio audio engine.
- 🌈 **Liquid-Smooth Audio Visualizer**: Multi-frequency spectrum analyzer with spring-damping physics, peak-hold indicators, and dynamic TrueColor frequency gradients (Pink ➔ Sapphire ➔ Mint ➔ Gold).
- 🖱️ **Full Mouse Interaction**:
- **Seek & Scrub**: Click or drag across the progress bar to jump anywhere in the song.
- **Click to Play**: Select artists, albums, and tracks directly with mouse clicks or double-click.
- **Scroll Wheel**: Scroll library panes or adjust volume seamlessly.
- **Interactive Controls**: Clickable play/pause, next/prev, shuffle, repeat, star, volume, and header buttons.
- 🔁 **Smart Queue & Playback Modes**:
- 📻 **Auto-DJ / Library Radio Mode**: Press a or click `[📻 DJ]` to start continuous, infinite playback of random tracks across your whole server library.
- 🖼️ **Terminal Cover Art**: Automatic album cover thumbnail downloading and TrueColor ANSI Half-block pixel art rendering in the dedicated sidebar pane with retro vinyl fallback animation!
- 🔁 **Smart Queue & Playback Modes**:
- Auto-advance to the next song when a track ends.
- **Shuffle** mode (`🔀`), **Repeat** modes (`🔁 Off`, `🔁 All`, `🔂 One`), and **Auto-DJ** (`📻 DJ`).
- Dedicated **Queue Viewer** (u) and **Lyrics Modal** (y).
- ❤️ **Favorites & Scrobbling**:
- Star / Like tracks (f / `❤️`) synced with your Navidrome server.
- Automatic playback scrobbling to Navidrome and Last.fm (>50% played).
- 🎨 **4 Premium TrueColor Themes**:
- **Catppuccin Mocha** (Default)
- **Tokyo Night**
- **Nord**
- **Gruvbox Dark**
- *(Press t to cycle themes instantly!)*
- ⚙️ **Interactive Setup & Settings**: Built-in 2-column configuration wizard on first launch with persistent TOML config.
- 🔍 **Instant Global Search**: Search artists, albums, and songs across your entire music library (/).
---
## 📸 Interface Preview
```text
🎵 rhyth-rs v0.1.0-beta │ Theme: Catppuccin Mocha [c] Settings [?] Help [/] Search [t] Theme [q] Quit
┌─ Artists [142] ────────────┐┌─ Albums [6] ───────────────────────────────────────────────────────────────────┐
│ 🎤 Daft Punk (6) ││ 💿 Discovery (2001) [14 tracks] │
│ 🎤 Gorillaz (8) ││ 💿 Random Access Memories (2013) [13 tracks] │
│ 🎤 Radiohead (9) ││ 💿 Alive 2007 (2007) [12 tracks] │
│ 🎤 Tame Impala (4) │└────────────────────────────────────────────────────────────────────────────────┘
├─ 🖼️ Now Playing & Cover ──┤┌─ Tracks [14] ──────────────────────────────────────────────────────────────────┐
│ ▄██████████████▄ ││ 🔊 ❤️ One More Time [05:20] │
│ ████████████████ ││ 02. Aerodynamic [03:27] │
│ ▀██████████████▀ ││ 03. Digital Love [04:58] │
│ Daft Punk - Discovery ││ 04. Harder, Better, Faster, Stronger [03:45] │
└────────────────────────────┘└────────────────────────────────────────────────────────────────────────────────┘
┌─ 🎵 rhyth-rs v0.1.0-beta ────────────────────────────────────────────────────────────────────────────────────┐
│ ❤️ One More Time • Daft Punk ⏮ ⏸ ⏭ │ 🔀 🔁 [📻 DJ] │ ▂▃▅▆▇▆▄▃▂▂▃▄▅ [y] Lyrics [u] Queue 🔊 85% │
│ 02:14 ━━━●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 05:20 (Click to Seek) │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```
---
## 🚀 Quick Start
### 1. Build & Run from Source
Make sure you have [Rust](https://rustup.rs/) installed:
```bash
# Clone the repository
git clone https://gitea.rardogsynapse.online/RarDog/rhyth-rs.git
cd rhyth-rs
# Run the player
cargo run --release
```
### 2. First-Time Setup
When you first launch `rhyth-rs`, an interactive connection modal will appear:
1. Enter your **Navidrome / Subsonic Server URL** (e.g. `http://localhost:4533` or `https://music.yourdomain.com`).
2. Enter your **Username** and **Password**.
3. Select your favorite **Theme** and press **`[ Connect & Save ]`**!
Configuration is automatically saved to:
* **Windows**: `%APPDATA%\rhyth-rs\config.toml`
* **Linux / macOS**: `~/.config/rhyth-rs/config.toml`
---
## ⌨️ Controls & Shortcuts
| Key | Action | Mouse Equivalent |
|:---|:---|:---|
| Space | Play / Pause toggle | Click `[ ▶ / ⏸ ]` |
| n / p | Next / Previous track | Click `[ ⏭ ]` / `[ ⏮ ]` |
| a | Toggle **Auto-DJ** (Infinite Library Radio) | Click `[ 📻 DJ ]` |
| s | Toggle Shuffle mode | Click `[ 🔀 ]` |
| r | Toggle Repeat mode (*Off* ➔ *All* ➔ *One*) | Click `[ 🔁 ]` |
| f / L | Star / Favorite track (Like) | Click `[ ❤️ ]` |
| y | Toggle Lyrics screen | Click `[y] Lyrics` |
| u | Toggle Queue screen | Click `[u] Queue` |
| Enter | Play selected track / Expand album | Double-click track |
| j / ↓ | Move down | Scroll wheel down |
| k / ↑ | Move up | Scroll wheel up |
| h / l / Tab | Switch between Artists, Albums, and Tracks | Click pane |
| + / = / ] | Volume Up (+5%) | Click / Drag Volume slider |
| - / _ / [ | Volume Down (-5%) | Click / Drag Volume slider |
| t | Cycle Color Theme | Click `[t] Theme` |
| / | Open Search Dialog | Click `[/] Search` |
| c / , | Open Settings & Connection Dialog | Click `[c] Settings` |
| ? | Toggle Help Popup | Click `[?] Help` |
| q / Esc | Quit rhyth-rs / Close Modal | Click `[q] Quit` |
---
## ⚙️ Configuration (`config.toml`)
```toml
server_url = "http://localhost:4533"
username = "your_username"
password = "your_password"
theme = "catppuccin_mocha" # "catppuccin_mocha", "tokyo_night", "nord", "gruvbox"
default_volume = 0.85
enable_visualizer = true
```
---
## 🛠️ Architecture
`rhyth-rs` is built with a modular, asynchronous architecture designed for performance and reliability:
- **`src/subsonic/`**: Strongly typed, robust OpenSubsonic client featuring MD5-token authentication, REST endpoints, scrobbling, and media streaming.
- **`src/audio/`**:
- **`decoder.rs`**: Symphonia pure decoding engine converting any stream container directly into floating-point PCM buffers.
- **`player.rs`**: Dedicated isolated audio thread managing sample playback with atomic progress tracking.
- **`src/ui/`**:
- **`theme.rs`**: TrueColor themes with semantic styles.
- **`visualizer.rs`**: Spring-physics audio spectrum engine with peak hold & color gradients.
- **`cover.rs`**: High-resolution image downsampling into Half-block ANSI characters.
- **`widgets/`**: Header, Library, Player Bar, Settings form, Search, Lyrics, and Queue modals.
- **`src/app.rs`**: Central state machine and async background channel router.
- **`src/main.rs`**: Fixed-timestep 30 FPS event loop with Crossterm mouse and keyboard capture.
---
## 📜 License
Distributed under the **MIT License**. See `LICENSE` for more information.