Tunez

A fast, beautiful terminal music player

Features • Installation • Quickstart • Keybindings • Configuration • Contributing

---

Tunez is a keyboard-driven terminal music player written in Go. It features a responsive Bubble Tea TUI, mpv for high-quality audio playback, and support for multiple music sources through a flexible provider system.

Features

• 🎵 Beautiful TUI — Rainbow-colored interface with smooth navigation
• ⚡ Responsive — Non-blocking UI, all I/O happens in the background
• 🎧 High-quality playback — Powered by mpv with gapless playback support
• 🖼️ Album artwork — Auto-detects terminal graphics (Sixel/Kitty) for pixel-perfect images
• 🔀 Queue management — Add, remove, reorder, shuffle, and repeat
• 🔍 Fast search — Search across tracks, albums, and artists
• 📚 Multiple providers — Local filesystem or Melodee API server
• ⚙️ Configurable — Custom keybindings, themes, and profiles
• ♿ Accessible — NO_COLOR support, works at 80×24

Installation

Prerequisites

• Go 1.22+
• mpv media player

Install mpv

# Debian/Ubuntu
sudo apt-get install -y mpv

# macOS (Homebrew)
brew install mpv

# Arch Linux
sudo pacman -S mpv

# Fedora
sudo dnf install mpv

Build from source

git clone https://github.com/yourusername/tunez.git
cd tunez/src
go build -o tunez ./cmd/tunez
./tunez --version

Quickstart

1. Create a config file

mkdir -p ~/.config/tunez
cp examples/config.example.toml ~/.config/tunez/config.toml

2. Edit the config

Point Tunez at your music library:

active_profile = "local"

[[profiles]]
id = "local"
name = "My Music"
provider = "filesystem"
enabled = true

[profiles.settings]
roots = ["/home/you/Music"]

3. Run Tunez

./tunez

Or run the doctor to verify your setup:

./tunez -doctor

Keybindings

Navigation

Key	Action
↑ / ↓	Navigate screens
j / k	Move selection down / up
Enter	Select / Play
Tab	Next screen
Shift+Tab	Previous screen
Backspace / Esc	Go back
/	Search
?	Help
q / Ctrl+C	Quit

Playback

Key	Action
Space	Play / Pause
n	Next track
p	Previous track
h / l	Seek -5s / +5s
H / L	Seek -30s / +30s
- / +	Volume down / up
m	Mute
s	Toggle shuffle
r	Cycle repeat (off → all → one)

Queue

Key	Action
a	Add to queue
A / P	Play next
x	Remove from queue
u / d	Move up / down
C	Clear queue

Configuration

Tunez uses a TOML configuration file located at:

• Linux/macOS: ~/.config/tunez/config.toml
• Windows: %APPDATA%\Tunez\config.toml

Example config

config_version = 1
active_profile = "local"

[ui]
theme = "rainbow"
page_size = 100
no_emoji = false

[player]
mpv_path = "mpv"
initial_volume = 70
seek_small_seconds = 5
seek_large_seconds = 30
volume_step = 5

[[profiles]]
id = "local"
name = "Local Music"
provider = "filesystem"
enabled = true

[profiles.settings]
roots = ["/home/you/Music", "/mnt/nas/music"]
scan_on_start = false

[[profiles]]
id = "melodee"
name = "Melodee Server"
provider = "melodee"
enabled = true

[profiles.settings]
base_url = "https://music.example.com"
username = "user"
password_env = "TUNEZ_MELODEE_PASSWORD"

See docs/CONFIG.md for the full configuration reference.

Themes & Accessibility

Tunez ships with 19 beautiful themes to match your terminal aesthetic:

Theme	Description
rainbow	Default colorful theme
mono	Elegant grayscale
green	Classic terminal green
nocolor	Accessible (respects NO_COLOR)
dracula	Popular dark theme
nord	Arctic, bluish tones
solarized	Precision colors
gruvbox	Retro, earthy tones
synthwave	80s neon vibes
matrix	Digital rain green
neon	Bright cyberpunk
...	and 8 more!

Set a theme

[ui]
theme = "dracula"

NO_COLOR support

Tunez respects the NO_COLOR environment variable for accessibility:

NO_COLOR=1 ./tunez

You can also disable emoji in the config:

[ui]
no_emoji = true

Create your own theme

Want to create a custom theme? See the Theme Contributor Guide for step-by-step instructions.

Album Artwork

Tunez displays album artwork in the Now Playing screen. The quality depends on your terminal's graphics capabilities, which are automatically detected at startup.

Graphics Protocols

Protocol	Quality	Terminals
Kitty	Pixel-perfect	Kitty
Sixel	High quality	iTerm2, WezTerm, foot, mlterm, Konsole, Windows Terminal, xterm (with sixel)
ANSI	Good (half-blocks)	All terminals (fallback)

Run tunez --doctor to see which graphics protocol your terminal supports:

$ tunez --doctor
┌─────────────────────────────────────────┐
│           Tunez Doctor Report           │
└─────────────────────────────────────────┘

  ✓ Config file:    OK
  ✓ mpv:            OK (mpv 0.37.0)
  ✓ ffprobe:        OK (6.1.1)
  ✓ cava:           OK (0.10.1)

  ✓ Graphics:       sixel (Sixel graphics - high-quality images)

Artwork Configuration

[artwork]
enabled = true
width = 40       # Width in terminal columns
height = 20      # Height in terminal rows
quality = "high" # low, medium, high
scale_mode = "fit" # fit, fill, stretch

The artwork size automatically adjusts to fit your terminal window while preserving aspect ratio.

Supported Terminals for Best Quality

For pixel-perfect album artwork, use one of these terminals:

• Kitty — Best quality, native graphics protocol
• iTerm2 (macOS) — Sixel support
• WezTerm — Cross-platform, Sixel support
• foot — Fast Wayland terminal, Sixel support
• Windows Terminal — Sixel support in recent versions

Other terminals will use ANSI half-block characters, which still provide recognizable artwork.

Documentation

Document	Description
PHASE_PLAN.md	Development roadmap and phase breakdown
PRD.md	Product requirements
TUI_UX.md	Screen specifications and interactions
CONFIG.md	Configuration reference
PROVIDERS.md	Provider interface contract
TECH_DESIGN.md	Architecture decisions

Troubleshooting

Logs

Tunez writes logs to ~/.config/tunez/state/tunez-YYYYMMDD.log

Common issues

"mpv not found"

# Verify mpv is installed
mpv --version

# Or set an explicit path in config
[player]
mpv_path = "/usr/local/bin/mpv"

Filesystem provider fails

• Ensure roots paths exist and are readable
• Check log file for detailed errors

Melodee authentication fails

• Set the password environment variable:

  export TUNEZ_MELODEE_PASSWORD="your-password"
  ./tunez

Contributing

Contributions are welcome! Please read the following before submitting:

1. Keep the Bubble Tea Update loop free of blocking I/O
2. Add tests for non-trivial logic
3. Run go test ./... before submitting
4. Follow existing code style (go fmt)

Development commands

cd src
go test ./...      # Run all tests
go test ./... -v   # Verbose output
go fmt ./...       # Format code
go vet ./...       # Check for issues

TUI Testing with teatest

Tunez uses teatest for TUI integration testing. Tests use mock providers with fixture data—no real config or music files needed.

# Run golden file tests (compares rendered UI to snapshots)
go test ./internal/app/... -run TestScreensGolden -v

# Update golden files after intentional UI changes
go test ./internal/app/... -run TestScreensGolden -update

# Test keybindings
go test ./internal/app/... -run TestKeyboardShortcuts -v

Golden files are stored in src/internal/app/testdata/ and track expected screen output. See docs/TEST_STRATEGY.md for full details.

License

MIT License — see LICENSE for details.

---

Made with 🎵 and Go