A terminal music player with a real-time RGB spectrum visualizer.
- Python 3.9+
- FFmpeg on system PATH:
- Windows:
winget install Gyan.FFmpeg - macOS:
brew install ffmpeg - Linux:
sudo apt install ffmpeg
- Windows:
git clone https://github.com/wyzuk/ttune.git
cd ttune
pip install -e .Once installed, the ttune command is available directly in your terminal.
Launch without arguments to open the startup menu and file browser:
ttunettune "path/to/song.flac"ttune "path/to/music_folder"ttune "path/to/music_folder" --volume 70- Real-Time FFT Spectrum Visualizer: Hardware-style equalizer bars rendered with truecolor RGB LED blocks with dynamic headroom.
- Multiple Visualizer Modes (
VKey): Toggle between Bottom-Up, Middle Mirror (center-out dual bloom), Middle Wave, Hanging Top-Down, and Split Mirror. - Equalizer Shapes & Sizes: Standard Brick, Fat Brick (4-wide), Extra Fat (6-wide), Mega Fat (8-wide), Giant (10-wide), Colossal (14-wide), Dense Fat, Matrix Dots, Shaded Blocks, and Braille Waves.
- Rich Color Gradients (
TKey): 18 high-contrast color palettes (Cyberpunk, Matrix, Synthwave, Fire, Ice, Amber, Vaporwave, Hyperpop, Toxic, Blood Moon, Ocean Abyss, Sunset Blaze, Aurora, Cyber Gold, Cotton Candy, Rainbow, Monochrome, Sakura). - Side-by-Side Playlist with Starred Active Track: Playlist sidebar displayed on the left of the visualizer, highlighting and starring (
*) the active track. - Fullscreen Visualizer Toggle (
LKey): Toggle the playlist sidebar to expand the visualizer to full width. - PC-Wide Music Search (
Sin Menu): Live search across drives and folders with instant filtering and playback. - Temporary Custom Playlist (
Pin Menu /Ato Add): Queue songs on the fly from the file browser or search screen, reorder tracks, and play custom queues. - Return to Menu (
BKey): Return from active playback to the startup menu at any time. - Visualizer-Only Mode (
HKey): Hide all song information and controls for clean full-screen visuals. - Centered Layout & Metadata: Centered song title, artist/album, bitrate badge, and progress bar below the visualizer.
- Universal Media Playback: Supports all common audio formats and decodes the audio track from video files without displaying video.
- Flicker-Free Screen Buffer: Double-buffered ANSI rendering at ~35 FPS with low CPU consumption (<3%).
| Key | Action |
|---|---|
| Space | Play / Pause |
| ← | Previous track |
| → | Next track |
| ↑ | Volume up (+5%) |
| ↓ | Volume down (-5%) |
| L | Toggle playlist sidebar (expand visualizer to full screen) |
| V | Cycle visualizer style (Bottom-Up, Middle Mirror, Wave, Hanging, Split) |
| T | Open Theme & Style Customizer |
| H | Toggle visualizer-only mode (hide all metadata & controls) |
| B | Return to Home Menu |
| [ | Seek backward (-5s) |
| ] | Seek forward (+5s) |
| R | Cycle repeat mode (ALL → ONE → OFF) |
| S | Toggle shuffle |
| M | Toggle mute |
| Q / Esc | Quit ttune |
| Screen | Key | Action |
|---|---|---|
| Home Menu | 1 / F | Pick Single File |
| 2 / D | Pick Folder / Playlist | |
| 3 / S | Search PC for Music | |
| 4 / P | Custom Playlist Builder | |
| 5 / T | Customize Themes & Shapes | |
| File Browser | ↑ / ↓ | Navigate files / folders |
| Enter | Open folder / Play file | |
| A | Add highlighted track to Custom Playlist | |
| B / Esc | Back | |
| Search Screen | Type text | Live query filtering across PC |
| Enter | Play selected track | |
| P | Play all matching tracks | |
| A | Add highlighted track to Custom Playlist | |
| Esc | Return to Menu | |
| Playlist Screen | Enter / P | Start playback of playlist |
| D | Remove selected track | |
| C | Clear playlist | |
| U / J | Move track Up / Down | |
| B / Esc | Return to Menu | |
| Theme Customizer | ← / → | Cycle Color Palettes |
| S | Cycle Visualizer Shapes | |
| P | Toggle Peak Decay Caps | |
| Enter / Esc | Apply & Return |
Playback and decoding are handled through FFmpeg / libav:
| Category | Formats |
|---|---|
| Audio | MP3, WAV, FLAC, AAC, M4A, OGG, OPUS, WMA, AIFF, ALAC, APE, AC3 |
| Video (Audio Track) | MP4, MKV, WebM, AVI, MOV, WMV, FLV, M4V, TS |
Video formats are supported through the media backend and are treated as audio sources.
- Python 3 — Core application architecture and CLI
- FFmpeg / libav — Multi-format streaming and raw PCM decoding
- NumPy — Fast Fourier Transform (FFT) and frequency band math
- sounddevice / PortAudio — Low-latency real-time audio output
- Mutagen — Audio tag metadata extraction
- Windows Console / ANSI Truecolor — Terminal styling and 24-bit color rendering
This project is licensed under the MIT License.