Getting Started with TerminalDrome: A First-Time Users Guide

TerminalDrome 0.8.5 and later

TerminalDrome is a terminal-based music client for Navidrome (and other Subsonic-compatible servers) with optional Bandcamp support. It runs entirely in your terminal, plays audio through mpv, and shows album covers as ASCII art — no browser, no Electron, no fuss.

This guide walks you through everything from installing the prerequisites to playing your first album, in about ten minutes.

Table of Contents

1. What You’ll Need
2. Installing the Prerequisites
3. Installing TerminalDrome
4. First Start: The Interactive Setup
5. Navigating the Interface
6. Playing Music
7. Everyday Workflows
8. Optional: Bandcamp Support
9. Optional: Audio Visualizer
10. Troubleshooting
11. Where to Go Next

What You’ll Need

Before you begin, make sure you have:

• A Navidrome instance (or any Subsonic-compatible server) that you can reach over the network, along with a username and password for it.
• A terminal — any modern one works. On macOS, Terminal.app or iTerm2; on Linux, GNOME Terminal, Konsole, Alacritty, or similar.
• About 5 minutes and an internet connection.

TerminalDrome is a TUI (Text User Interface), which means it draws its interface with characters inside your terminal. You won’t need a graphical environment — it works perfectly over SSH.

Installing the Prerequisites

1. Install mpv

TerminalDrome delegates all audio decoding and playback to mpv, which is a well-established, lightweight media player. Install it first.

macOS (via Homebrew):

brew install mpv

Debian / Ubuntu:

sudo apt update
sudo apt install mpv

Arch Linux:

sudo pacman -S mpv

Fedora:

sudo dnf install mpv

Verify it’s on your PATH:

mpv --version

You should see version information. If you get command not found, the installation didn’t complete — check your distribution’s documentation.

2. Install Rust (only needed if you build from source)

If you plan to install TerminalDrome via cargo install, you’ll need the Rust toolchain. The easiest way is rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the prompts, then reload your shell:

source "$HOME/.cargo/env"

Verify:

cargo --version

If you’re on macOS and prefer Homebrew, brew install rust also works.

Installing TerminalDrome

You have three options. Pick whichever fits your setup.

Option A — From crates.io (recommended, simplest)

Once Rust is installed:

cargo install terminaldrome

Cargo will download, compile, and install the latest release. When it’s done, the terminaldrome binary is in ~/.cargo/bin/, which is on your PATH if you used rustup.

Option B — From source

git clone https://github.com/thafaker/terminaldrome
cd terminaldrome
cargo build --release
./target/release/terminaldrome

Option C — System-wide install from a local clone

git clone https://github.com/thafaker/terminaldrome
cd terminaldrome
cargo install --path .

After this, you can run terminaldrome from anywhere.

Verify the install:

terminaldrome --help

You should see the CLI help output listing --config, --server, and --user.

First Start: The Interactive Setup

On your very first run, TerminalDrome will notice that no valid configuration exists and walk you through a short setup.

terminaldrome

You’ll be greeted with a splash screen, then something like this:

⚙️ Erstkonfiguration für TerminalDrome

Server URL [https://music.example.com]:
Benutzername:
Passwort für 'your-username':

Wait — the prompts are in German. That’s a known quirk of the current build; the setup wizard hasn’t been fully translated yet. The prompts map to:

What happens to your password

TerminalDrome never writes your password to disk in plaintext. Here’s what happens behind the scenes:

1. A random salt is generated from the current system time.
2. Your password is combined with the salt and hashed with MD5: token = MD5(password + salt).
3. Only the token and salt are written to config.toml.
4. On Unix systems, the file is saved with 600 permissions (owner read/write only).

This is the standard Subsonic token authentication scheme, so your password is also never sent over the network in cleartext.

Optional: Using a Navidrome App Token instead of your password

If you’d rather not type your account password into a terminal at all, you can create a Personal Access Token in Navidrome:

1. Log into your Navidrome web interface.
2. Go to Personal Settings → Personal Access Tokens.
3. Create a new token named TerminalDrome.
4. Copy the token, and paste that when TerminalDrome asks for your password.

From TerminalDrome’s point of view, an App Token is just a different string to hash. Either works.

Where the config lives

After setup, your config file will be at one of these locations:

• ./config.toml — if you ran TerminalDrome from a directory that already contained one.
• ~/.config/terminaldrome/config.toml on Linux.
• ~/Library/Application Support/terminaldrome/config.toml on macOS.

A typical config looks like this:

[server]
enabled = true
url = "https://music.example.com"
username = "alice"
token = "a1b2c3d4e5f6..."
salt = "1f4e9a2b"

You don’t have to edit this by hand unless you want to change something later.

Subsequent starts

From the second run onwards, TerminalDrome connects directly to your server. You’ll see:

Connecting to https://music.example.com...
Connection successful! Starting TerminalDrome...

If the connection fails at any point, TerminalDrome offers to re-run the setup wizard so you can fix your credentials.

Navigating the Interface

Once TerminalDrome is running, your terminal shows a three-panel layout:

┌─ Artists ────────────┐ ┌─ Cover Art ──────────┐ ┌─ Songs ─────────────┐
│ Autechre             │ │  ░▒▓█▓▒░             │ │ 1. Foil  (04:12)    │
│ Aphex Twin           │ │  ▒█▓▒░█▓             │ │ 2. Vletrmx (06:15)  │
│ Boards of Canada     │ │  █▓▒░█▓▒             │ │ 3. Drane   (10:47)  │
│ …                    │ │  …                   │ │ …                   │
└──────────────────────┘ └──────────────────────┘ └─────────────────────┘
┌──────────────────────────────────────────────────────────────────────┐
│ 🤖 NAVIDROME | VOL:50% | MUTE:OFF | B:Source | /:Search | Q:Quit …  │
└──────────────────────────────────────────────────────────────────────┘
▶ Boards of Canada – Roygbiv
01:23 ━━━━━━━━━─────── 04:05

Here’s what the keys do:

The status bar at the bottom always shows your current source (NAVIDROME or BANDCAMP), volume, mute state, and a handful of the most useful shortcuts.

Playing Music

Playing an album is three keystrokes:

1. Select an artist with ↑/↓.
2. Press → to load their albums. The Albums panel replaces the Cover Art panel at the top; the bottom panel still shows cover art.
3. Press → again to load the songs and start playback immediately.

The bottom bar shows the currently playing track, and mpv starts streaming from your server.

Playback controls

Liked songs get a permanent ❤️ next to their title, and the like persists across restarts.

Playing a playlist

Press Tab to switch to the Playlists view. You’ll see all your Navidrome playlists in the left panel; select one and press Enter to load and play it. The right panel shows playlist metadata plus now-playing info.

Everyday Workflows

Search

Press / anywhere to open the search box. Type a query and press Enter. Results appear in the Songs panel, ready to play.

Shuffle an album or playlist

While a song list is loaded, press Shift+S. TerminalDrome shuffles the list in memory (Fisher-Yates), restarts playback from the top of the new order, and turns the progress bar magenta so you know shuffle is active.

Party Mode (Jukebox)

Press Shift+J to enter Jukebox Mode. TerminalDrome fetches random songs from your entire library in batches of ~50, plays them back-to-back forever, and silently refills the queue in the background as you listen. The status bar shows 🎉 JUKEBOX in green.

Press Esc to stop and return to the Artists view.

Quick-jump by letter

In any list, press a letter A–Z to jump straight to the first entry starting with that letter. Handy when your library has 500 artists.

Resume where you left off

TerminalDrome saves its state (current view, selected artist/album, playback position) between sessions. The next time you launch it, you’ll be back where you were.

Optional: Bandcamp Support

If you have a Subsonic-compatible Bandcamp endpoint, you can add it as a second source. Open your config.toml and add:

[bandcamp]
enabled = true
url = "https://your-bandcamp-endpoint.example.com"
username = "your-bandcamp-username"
# token / salt will be filled in after first use, or set password and let TerminalDrome derive them

Restart TerminalDrome. Now press Shift+B to switch between Navidrome and Bandcamp. The status bar shows 🎸 BANDCAMP when the Bandcamp source is active.

Optional: Audio Visualizer

If you want a fullscreen audio visualizer while you listen, install cava:

# Arch
sudo pacman -S cava

# macOS
brew install cava

Then press Shift+E inside TerminalDrome. An eight-bar spectrum overlay appears, driven by real audio from cava. Press Shift+E again (or Esc) to return.

If cava isn’t installed, Shift+E still works — it shows a demo animation instead.

Troubleshooting

“Connection failed”

• Double-check the server URL. It should include https:// or http:// and not end with a trailing slash.
• Try visiting the URL in a browser. If it redirects to a login page, the URL is correct.
• If your server uses a self-signed certificate, mpv and reqwest may reject it. Consider using a valid certificate (Let’s Encrypt) or a reverse proxy.
• Answer y at the prompt when TerminalDrome offers to re-run setup.

“mpv: command not found”

mpv isn’t on your PATH. Install it (see Installing the Prerequisites) and restart your terminal.

Playback starts but there’s no sound

Check your system’s default audio output device. TerminalDrome doesn’t manage audio routing — mpv uses whatever your OS is configured to use.

The ASCII cover art looks broken

The cover renderer assumes a reasonable font and a terminal at least 80×24. Try enlarging your terminal window, or use a font with even spacing for block characters (█, ▓, ▒, ░). Most modern monospace fonts work fine.

“cargo: command not found”

You haven’t installed Rust. See Installing the Prerequisites.

The interface is redrawn slowly

If you’re on a very slow connection or an old machine, the album art fetch can be the bottleneck. This is normal — covers are cached after the first fetch.

My config is broken and I want a fresh start

Delete the config file and run TerminalDrome again:

rm ~/.config/terminaldrome/config.toml       # Linux
rm ~/Library/Application\ Support/terminaldrome/config.toml  # macOS

The setup wizard will appear on the next launch.

Where to Go Next

• Press Shift+H inside TerminalDrome to see the full keyboard reference. It’s always one keystroke away.
• Check the README for a complete feature list and changelog.
• Report bugs or request features via GitHub Issues.
• Contribute — pull requests are welcome.

TerminalDrome is a solo project, made with love in Mitteldeutschland. If it makes your music listening a little nicer, consider giving the repository a star ⭐.

Happy listening.

This tutorial was written for TerminalDrome 0.8.5. If you’re reading this in the future and something looks different, check the README for the latest changes.