# Getting Started

› Quick Start (Windows)

Download tune.exe from the releases page and run it. No installation required.

› Installing on Linux and macOS

TuneTUI is a Rust project. Install Rust via rustup, then clone and build:

git clone https://github.com/Sqble/tui_music.git
cd tui_music
cargo build --release

The binary will be at target/release/tune. Add it to your PATH or run it directly.

To install system-wide: cargo install --path .

Check the releases page for prebuilt Linux or macOS binaries when available.

› Adding Your Music

1. Press h to switch to the Library page
2. Select [+] Add Directory and press Enter
3. Choose your music folder (or type the path)

› Basic Playback

• ↑ / ↓ — Navigate through your tracks
• Enter — Open or play the selected item
• Space — Pause / Resume
• n — Next track
• b — Previous track

› Want to Listen with Friends?

TuneTUI supports real-time listen-together via the Online tab. The public server at tunetui.online is already running and available for anyone to use.

1. Press l to open the Online page
2. Set a nickname if prompted
3. Press Enter on [ Show Public Servers ]
4. Select a room to join, or select [+] Create Room to host

› SSH Usage

If running over SSH, TuneTUI automatically sets TERM=xterm-256color when needed. For clipboard support over SSH, ensure your terminal allows OSC 52 escape sequences.

# Controls

› Navigation

› Playback

› Library Actions

› Actions Panel

Press / to open. Type to filter actions. Use ↑ / ↓ to navigate, Enter to select.

› Lyrics Tab

› Stats Tab

› Online Tab

› Quitting

# Configuration

› Config Directory

• Linux: $XDG_CONFIG_HOME/tunetui/ (defaults to ~/.config/tunetui/)
• Windows: %USERPROFILE%\.config\tunetui\
• Override: Set TUNETUI_CONFIG_DIR environment variable

› Files

• state.json — Playback state, library folders, playlists, settings
• library_index.json — Cached library metadata/fingerprints for faster startup
• stats.json — Listen history and statistics
• lyrics/ — LRC sidecar files (one per track)

› Playback Settings

Open actions panel (/) → "Playback settings"

• Loudness normalization — Normalize track volumes
• Crossfade — Smooth transitions between tracks
• Scrub length — How far to seek with a/d keys (5s/10s/15s/30s/1m)
• Stats tracking — Enable/disable listen history
• Top songs rows — How many rows to show in stats charts
• Missing cover fallback — Template for tracks without album art
• Online nickname — Your display name for online rooms
• Online sync delay — Manual delay, auto-ping, recalibrate, sync correction threshold

› Themes

Available themes (actions panel → Theme):

• Dark (default)
• System / Terminal
• Pitch Black
• Galaxy
• Matrix
• Demonic
• Cotton Candy

› Audio Output

Select your audio output device via actions panel → "Audio driver settings" → "Select output speaker". The selection persists across launches.

› Lyrics

TuneTUI looks for lyrics in this order:

1. .lrc sidecar file in the config lyrics folder
2. Embedded lyrics in audio file metadata

Sidecar files are named based on track path and stored in lyrics/. If no lyrics exist, the Lyrics tab offers to create a new sidecar.

To import plain .txt lyrics: actions panel → "Import TXT to lyrics"

› Metadata Editor

Actions panel → "Edit selected track metadata" to edit:

• Title
• Artist
• Album

You can also copy now-playing cover art to selected track, current folder, current playlist, or all songs.

# Online Sync

› Using the Public Server

The server at tunetui.online is already running and available for anyone to use. No setup required.

› Hosting a Room

1. Press l to reach the Online page
2. Set a nickname if prompted
3. Show public servers, or type a custom homeserver/link in Server / Link
4. Select [+] Create Room, then enter room name and optional password
5. Friends connect to the same server or use the copied room link/code

› Joining a Room

1. Press l to reach the Online page
2. Set a nickname if prompted
3. Show public servers, or type a custom homeserver/link in Server / Link
4. Search or browse the inline room directory and select a room
5. If password-protected, enter the password

› Room Modes

• Collaborative — Anyone can add music to the shared queue
• Host-only — Only the host controls playback; listeners are locked

Press o to toggle between modes (host only).

› Stream Quality

• Lossless — Direct audio streaming from host (best quality)
• Balanced — Opus 160kbps VBR (lower bandwidth, still great quality)

Press q to cycle quality (host only).

› Shared Queue

• In Library tab, select tracks and press Ctrl+s to add to shared queue
• You can add individual tracks, folders, playlists, or all songs
• The queue is FIFO — tracks play in order and are removed when played
• Press Ctrl+n in Online to start the shared queue now or jump to the next item

› Sync Mechanics

TuneTUI syncs playback state (track, position, pause) every sub-second, including:

• Ping-compensated target position
• Drift deadzone to avoid micro-seeks
• Periodic ping RTT measurements
• Automatic peer cleanup on disconnect

› File Streaming (Reverse Stream Safety)

When hosts don't have a track that listeners have added to the queue, listeners can upload that track to the host. This is limited to:

• Only shared-queue items owned by that peer
• Capped at 1 GiB per file

› Nickname

Your nickname is saved in state.json. Set or change it via: actions panel → Playback settings → Online nickname

# Hosting Your Own Server

› CLI Options

tune --help

Run only the home server (headless):

tune --host --host-ip 0.0.0.0

This runs the server on port 7878 (default).

--host-ip is the address the server binds to. Use 0.0.0.0 to listen on all IPv4 interfaces.

Run server + TUI app together:

tune --host --app --host-ip 0.0.0.0

This starts both the server and the client app in one process.

Custom port:

tune --host --host-ip 0.0.0.0:9000

Custom room port range:

tune --host --host-ip 0.0.0.0 --room-port-range 9000-9100

Default room range is 9000-9100.

Connect to your server from another machine:

tune --ip 192.168.1.100

--ip is the server address the app connects to. Replace with your server's IP or domain.

› Port Requirements

• 7878 — Home server signaling port (TCP)
• 9000-9100 — Room transport ports (TCP, default range)

› Room Port Range

The range determines how many simultaneous rooms can exist. Default is 9000-9100. Adjust with --room-port-range if needed.

# Troubleshooting

› No Audio Output

1. Open actions panel (/)
2. Select "Audio driver settings" → "Select output speaker"
3. Choose a valid audio device

› Missing Album Art

1. Actions panel → Playback settings
2. Set "Missing cover fallback" to a template (default: Music Note)

› Lyrics Not Showing

Check that:

• .lrc sidecar exists in lyrics/ folder in your config dir
• Or lyrics are embedded in audio file metadata

If neither exists, the Lyrics tab will offer to create a new sidecar file.

› Connection Issues

• Verify the server address is correct
• Check that port 7878 (server) and 9000-9100 (rooms) are open
• If using a password-protected room, ensure you're entering it correctly

› Stats Not Tracking

1. Actions panel → Playback settings
2. Ensure "Stats tracking" is enabled

› Clear Listen History

Actions panel → "Clear listen history (backup)" — resets stats but saves a .bak snapshot first.

› Debug Output

RUST_BACKTRACE=1 tune

This provides detailed error information for troubleshooting.

› Clipboard Over SSH

If clipboard copy fails natively, TuneTUI falls back to OSC 52 terminal escape sequences. Ensure your terminal (and tmux/screen if used) allows clipboard passthrough.