How to Install Termusic on Debian: A Terminal Music Player in Rust

Termusic is a feature-rich terminal music player written in Rust. It gives you a full text-based user interface for browsing your music library, building playlists and controlling playback, all without leaving the terminal or running a desktop audio application. For anyone who lives on the command line, it turns a spare terminal pane into a proper music player.

Termusic is more than a bare playback loop. It indexes your local collection into a searchable library, supports gapless playback, gapless queueing and a playlist you can reorder on the fly, and reads common formats including MP3, FLAC, OGG, M4A and WAV. It is built around a client/server split: a background termusic-server process owns the audio pipeline, while the termusic TUI connects to it, so playback keeps going even as you navigate.

Termusic is not in the official Debian repositories, and building it from source pulls in a Rust toolchain plus audio backend libraries. The unofficial deb.griffo.io repository makes it far simpler by providing a prebuilt Termusic package that installs with apt.

Install the Latest Termusic on Debian: The Short Version

If you only came for the commands, this adds the repository and installs the latest Termusic .deb package on Debian:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null
sudo apt update
sudo apt install termusic

The rest of this guide explains what each command does, how to verify the install, how to keep Termusic up to date, and what to check when something goes wrong.

What Makes Termusic Special?

  • 🎵 Full-featured TUI - Browse your library, queue tracks and control playback from the keyboard
  • 🦀 Written in Rust - Efficient, responsive and light on system resources
  • 🗂️ Music library indexing - Scans your collection into a fast, searchable database
  • 🔀 Playlist management - Build, reorder and save playlists with gapless queueing
  • 🎚️ Multiple audio backends - Pure-Rust (Symphonia), GStreamer or MPV backends
  • 🎧 Broad format support - MP3, FLAC, OGG, M4A, WAV and more
  • 🖥️ Client/server architecture - A background server keeps audio playing while you browse
  • 🎙️ Podcast support - Subscribe to and play podcast feeds alongside your music

Why Use the deb.griffo.io Repository?

Installing Termusic from deb.griffo.io on Debian gives you:

  • Easy installation and updates through the standard APT package manager
  • Automatic dependency management handled by the packaging
  • Always tracks upstream releases so you stay on a current Termusic
  • No compiling from source and no Rust toolchain to set up
  • Works across supported Debian releases (Bookworm, Trixie and Sid)

Prerequisites

Before we begin, make sure you have:

  • A Debian-based system (Bookworm 12, Trixie 13, or Sid)
  • sudo privileges
  • curl installed (install with sudo apt install curl if needed)
  • A working audio setup (PipeWire or PulseAudio) and a folder of music

Step 1: Add the deb.griffo.io Repository

Add the repository GPG key and source definition:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

What these commands do:

  1. Keyrings directory: Creates /etc/apt/keyrings with the correct permissions to hold the key.
  2. GPG key: Downloads and de-armours the signing key so APT can verify signatures.
  3. Repository: Adds the source line, with lsb_release -sc detecting your Debian codename.
  4. Update: Refreshes the package index so the new packages appear.

Step 2: Update the Package List

If you have not already refreshed the index, do so now:

sudo apt update

Step 3: Install Termusic

Install Termusic with a single command:

sudo apt install termusic

APT downloads and installs the latest packaged Termusic, including its server component and dependencies.

Step 4: Verify the Installation

Check the installed version:

termusic --version

You should see output similar to:

termusic 0.11.0

Getting Started with Termusic

Termusic pairs a TUI client with a background playback server. The steps below cover pointing it at your music, launching the interface, and getting comfortable with the controls.

First Launch and Library Setup

Start the player by running the command with no arguments:

termusic

You can also open it pointed straight at a music directory, which is a quick way to load a collection the first time:

termusic ~/Music

On the first run, use the interface to add your music folder to the library. Termusic scans the directory and builds an indexed database so future searches and browsing are instant.

Configuration

Termusic keeps its configuration under ~/.config/termusic/. The key files are:

~/.config/termusic/server.toml    # server and playback settings, music directories
~/.config/termusic/tui.toml       # interface and key binding settings
~/.config/termusic/themes/        # custom colour themes

Editing server.toml lets you set your default music directories and choose the audio backend, while tui.toml controls appearance and key bindings. The indexed library lives alongside these files in a local database.

Everyday Controls

Termusic is keyboard-driven. The most common default bindings are:

Tab / Shift+Tab   switch between the library, playlist and lyrics panes
Enter             add the selected track to the playlist / play it
Space             pause or resume playback
n                 next track
N                 previous track
+ / -             raise or lower the volume
q                 quit

Press ? inside Termusic at any time to see the full, current list of key bindings.

Choosing an Audio Backend

Termusic supports several backends. The default pure-Rust backend (Symphonia) works without extra system libraries, while GStreamer and MPV backends add broader codec coverage. Select your preferred backend in server.toml:

# ~/.config/termusic/server.toml
[player]
backend = "rusty"   # options: rusty, gstreamer, mpv

If you switch backends, restart Termusic so the server picks up the change.

Keeping Termusic Updated

Because Termusic comes from the repository, keeping it current is part of your normal system upgrade:

sudo apt update && sudo apt upgrade

Other Tools from deb.griffo.io

The deb.griffo.io repository packages many other terminal tools that pair well with Termusic:

  • lowfi - A tiny, cozy terminal lofi music player
  • viu - A terminal image viewer for album art and previews
  • Yazi - A blazing fast terminal file manager written in Rust
  • Fastfetch - A fast, highly customizable system information tool

Troubleshooting

GPG or Key Issues

If APT reports the repository is not signed, re-add the signing key:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Package Not Found

If APT cannot find the termusic package:

  1. Run sudo apt update again after adding the repository.
  2. Confirm your Debian release is supported (Bookworm, Trixie or Sid).
  3. Check the source file: cat /etc/apt/sources.list.d/deb.griffo.io.list.

No Sound on Playback

If Termusic runs but nothing plays, the problem is usually the audio stack rather than Termusic:

  1. Confirm your system audio works: speaker-test -c2 -t wav should produce sound.
  2. Check that PipeWire or PulseAudio is running for your session with systemctl --user status pipewire (or pulseaudio).
  3. Try a different backend in ~/.config/termusic/server.toml; if the rusty backend cannot decode a file, switching to gstreamer or mpv often helps.

Uninstalling

To remove Termusic:

sudo apt remove termusic

To also remove the repository definition and key:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Your configuration and library database under ~/.config/termusic are left in place; delete that directory if you want a completely clean removal.

Conclusion

Termusic proves that a terminal music player can be genuinely comfortable to use every day. With an indexed library, editable playlists, gapless playback and a client/server design that keeps the music going while you browse, it comfortably replaces a graphical player for keyboard-first users. The deb.griffo.io repository reduces installing it on Debian to a single apt install, with updates flowing through your regular upgrades.

Point it at your music folder, learn a handful of key bindings, and Termusic becomes the soundtrack to your terminal sessions. Combine it with a terminal image viewer for album art and a file manager for organising your collection, and your whole music workflow can stay on the keyboard.

Frequently Asked Questions

How do I install the latest Termusic on Debian?

Add the deb.griffo.io APT repository and its signing key, then run sudo apt install termusic. The repository tracks upstream Termusic releases, so you get the latest packaged version rather than a build frozen when your distribution was released.

Is there a .deb package for Termusic?

Yes. deb.griffo.io publishes Termusic as a signed .deb for Debian. You could download that .deb and install it by hand, but adding the repository is the better option: APT then resolves dependencies and picks up new versions on its own.

How do I update Termusic to the latest version?

Run sudo apt update && sudo apt upgrade. Once Termusic is installed from APT there is no separate updater to remember, since new releases arrive with the rest of your system updates.

How do I install Termusic on Ubuntu?

Exactly the same way; lsb_release -sc simply resolves to a different codename. There is a companion guide with the Ubuntu specifics: How to install Termusic on Ubuntu.

Which Debian releases are supported?

Bookworm 12, Trixie 13 and Sid. Because the repository line is built from lsb_release -sc, the matching suite is selected for you.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream Termusic project.