<p align="center">
<img src="logo.png" alt="Bebop logo" width="300">
</p>
# Bebop
A terminal music player and audio visualizer for local audio files.
Bebop combines real-time spectrum analysis, embedded album artwork via the Kitty graphics protocol, interactive playlists and library browsing, and a responsive keyboard- and touch-friendly interface built with Ratatui.
<p align="center">
<img src="screenshot.png" alt="Bebop screenshot" width="85%">
</p>
## Features
- **Local Audio Playback:** Decodes MP3, FLAC, WAV, OGG, and AAC/M4A with pure Rust decoders via Symphonia and outputs low-latency audio through CPAL.
- **Neon Rainbow Visualizers:** Multi-stop frequency spectrum equalizer bars with peak caps, smooth decay, and time-domain oscilloscope waveforms.
- **Kitty Album Artwork:** Renders embedded album art and local folder covers directly in Kitty, Ghostty, and WezTerm terminals with graceful fallback.
- **Interactive Library & Playlists:** Dual-column file and playlist browser (`2`) to open folders, play albums, enqueue tracks, and manage `.m3u` / `.m3u8` playlists.
- **Active Queue Management:** Inspect the queue (`3`), reorder, remove items (`d`), clear (`c`), or shuffle (`s`).
- **Synchronized Lyrics:** Reads companion `.lrc` files and embedded lyric tags with real-time center-scrolling and tap-to-seek (`4` or `l`).
- **Desktop Notifications:** Displays track title, artist, album, and duration on track changes via desktop notifications.
- **Linux MPRIS / D-Bus Integration:** Control playback with desktop media keys, `playerctl`, GNOME/KDE media widgets, and lock screens.
- **Audio Output Device Selector:** Press `o` / `O` or tap the device badge to switch audio output devices (headphones, DACs, HDMI) on the fly.
- **Full-Screen Visualizer Mode:** Press `f` for a focused visualizer experience with a minimal now-playing footer.
- **Touch & Mouse Support:** Click or tap progress bars to seek, drag volume, tap transport buttons, switch tabs, or cycle visualizers.
- **Sleek Minimal Aesthetics:** Charcoal dark palette (`#121214`) with crisp typography and vibrant accent palettes.
## Requirements
- Rust 1.75+ (tested on Rust 1.96)
- ALSA development libraries on Linux (`libasound2-dev` on Debian/Ubuntu, `alsa-lib-devel` on Fedora)
- A modern terminal emulator (Kitty, Ghostty, or WezTerm for album artwork; any UTF-8 terminal for playback and visualizers)
## Installation
Install Bebop from crates.io:
```bash
cargo install bebop-player
```
This installs the `bebop` executable. Launch it with a file, folder, playlist, or no argument:
```bash
bebop
```
### Build from source
Clone the repository and build the release executable:
```bash
git clone https://github.com/pinkpixel-dev/bebop.git
cd bebop
cargo build --release
```
The compiled executable is available at `./target/release/bebop`.
## Quick Start
Play an individual audio file:
```bash
bebop path/to/song.flac
```
Play a folder containing albums:
```bash
bebop ~/Music/Synthwave/
```
Load an M3U or M3U8 playlist:
```bash
bebop favorites.m3u
```
Launch without arguments to load your system music directory (`~/Music`):
```bash
bebop
```
## Keybindings & Controls
### Playback
| `Space` | Tap Play/Pause button | Toggle play and pause |
| `n` | Tap Next button | Next track in queue |
| `p` | Tap Previous button | Previous track in queue |
| `←` / `→` | Tap Timeline bar | Seek backward / forward 5 seconds |
| `↑` / `↓` | Tap Volume bar / Scroll | Adjust volume by 5% |
| `m` | - | Toggle mute |
| `r` | Tap Repeat label | Cycle repeat mode (All, One, Off) |
| `s` | Tap Shuffle label | Toggle shuffle mode |
| `o` / `O` | Tap Audio Device badge | Open audio output device selector |
### Visuals & Views
| `f` | Tap Artwork or Visualizer | Toggle full-screen visualizer mode |
| `v` | Tap Visualizer box | Cycle visualizer (Spectrum Bars, Waveform) |
| `t` | - | Cycle theme (Neon Rainbow, Vercel Dark, Ice, Sunset, Mono) |
| `a` | - | Toggle album artwork display |
| `x` | Tap the pet badge | Toggle dancing pixel pet display |
| `b` | Tap the Pet box | Pet the cat and watch it perk up |
| `1` | Tap Player tab | Switch to Player view |
| `2` | Tap Library tab | Switch to Library and Playlist browser |
| `3` | Tap Queue tab | Switch to Playback Queue manager |
| `4` / `l` | Tap Lyrics tab | Switch to Synchronized Lyrics view |
| `?` | Tap Help tab | Show or hide the keybindings overlay |
| `q` / `Ctrl+C` | - | Quit Bebop |
### Library View (`2`)
| `↑` / `↓` or `k` / `j` | Mouse wheel scroll | Move selection up or down |
| `PgUp` / `PgDn` | - | Scroll by page up or down |
| `Home` / `End` or `g` / `G` | - | Jump to top or bottom of list |
| `←` / `→` or `h` / `l` | Tap panel | Switch between Folders/Playlists and Tracks panels |
| `Enter` | Tap item twice | Open folder, load playlist, or play selected track |
| `a` | - | Add selected track or entire folder to queue |
| `p` | - | Save active queue as a new playlist |
| `1` | Tap Player tab | Return to Player view |
### Queue View (`3`)
| `↑` / `↓` or `k` / `j` | Mouse wheel scroll | Move selection up or down |
| `PgUp` / `PgDn` | - | Scroll by page up or down |
| `Home` / `End` or `g` / `G` | - | Jump to top or bottom of queue |
| `Enter` | Tap track twice | Jump directly to selected track |
| `d` / `Delete` | - | Remove selected track from queue |
| `c` | - | Clear entire queue |
| `s` | Tap Shuffle label | Shuffle queue order |
| `1` | Tap Player tab | Return to Player view |
### Lyrics View (`4` or `l`)
| `↑` / `↓` or `k` / `j` | Mouse wheel scroll | Browse lyric lines manually (pauses auto-scroll) |
| `Enter` | Tap any line | Seek playback directly to that timestamp |
| `s` | Tap re-sync badge | Snap back to active line and resume auto-scroll |
| `Space` | Tap Play/Pause button | Toggle playback |
| `n` / `p` | Tap Next/Prev button | Next or previous track |
| `1` / `l` / `Esc` | Tap Player tab | Return to Player view |
### Linux MPRIS & Media Keys
Bebop implements the standard MPRIS D-Bus interface (`org.mpris.MediaPlayer2` and `org.mpris.MediaPlayer2.Player`). You can control playback using your desktop keyboard media keys, lock screen widgets, or `playerctl`:
```bash
playerctl play-pause
playerctl next
playerctl previous
playerctl position 30
playerctl metadata
```
## Architecture
Bebop separates playback, analysis, and rendering into distinct layers:
1. **Audio Engine (`src/audio/`):** A background decode worker continuously buffers PCM samples from Symphonia into a ring buffer. The CPAL audio stream drains the buffer with volume scaling.
2. **Analysis Pipeline (`src/audio/analysis.rs`):** Applies a Hann window to recent PCM samples, executes forward FFT via `rustfft`, groups frequencies logarithmically into weighted bins, and applies fast-attack and smooth-decay filtering.
3. **Playlists & Library (`src/player/playlist.rs`, `src/ui/library.rs`):** Parses and writes standard M3U/M3U8 playlists, manages user playlists in `~/.config/bebop/playlists/`, and provides folder navigation.
4. **Ratatui Interface (`src/ui/`):** Computes responsive layout areas, renders custom widgets directly to the terminal buffer, and collects click hit zones for mobile/mouse interactions.
5. **Kitty Protocol (`src/terminal/`):** Transmits base64-encoded PNG image chunks directly to the terminal window and manages cleanup on view changes.
6. **Linux MPRIS Service (`src/mpris.rs`):** Serves `org.mpris.MediaPlayer2` on session D-Bus, routing player actions across an unbounded crossbeam channel to the main loop with zero audio or render latency.
7. **Audio Output Device Manager (`src/audio/output.rs`, `src/ui/device.rs`):** Dynamically enumerates output endpoints and hot-swaps CPAL streams without interrupting the background decoder worker or clearing ring-buffer samples.
8. **Pixel Pet View (`src/ui/pet/`):** Draws an audio-reactive dancing cat in ANSI half-blocks, with frames that speed up with rhythm and audio energy, three sprite sizes that follow the pane, an automatic sleep state when paused, and a tap or key press that pets the cat so it wakes up and shows hearts.
## License
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.