gtm.rs 🦀

Feature rich terminal audio player with background playback support and YouTube/Spotify integration. Rust implementation of the gtm spec.

Demo GIF placeholder — regenerate with VHS, see tapes/VHS.md.

Features

• Background daemon (gtmd) — playback survives terminal close; control it from the TUI, the CLI, or MPRIS.
• YouTube, Spotify, Deezer integration — search, download, and resolve tracks, sync Spotify playlists, and fetch missing metadata/lyrics/cover art.
• Equalizer — 16 presets plus per-band gain, headroom stage, and a spectrum visualizer.
• Cover art — rendered inline via the kitty/terminal image protocol.
• Themes — 12 built-in themes (light and dark) plus user TOML themes.
• MPRIS — media player controls via D-Bus (optional feature).
• Termux / Android — runs on Android via PulseAudio (optional feature).

Install

You can use the shared install.sh script for an interactive, hassle free installation. It asks which implementation (gtm.rs or gtm.nim) and which install type you want:

curl -fsSL https://raw.githubusercontent.com/prjctimg/gtm.spec/main/install.sh | bash

Or pick this implementation directly:

curl -fsSL https://raw.githubusercontent.com/prjctimg/gtm.spec/main/install.sh | bash -s -- --impl rust

GitHub Release

Every release publishes complete per-target archives plus native distro packages. Each gtm-{platform}.tar.gz bundles both binaries (bin/gtm, bin/gtmd), man pages, shell completions, and the systemd user service. Grab one from the releases page.

Manual install for x86_64 Linux (tar.xvf style):

curl -fsSLO https://github.com/prjctimg/gtm.rs/releases/latest/download/gtm-x86_64-linux.tar.gz
tar xzf gtm-x86_64-linux.tar.gz
cd gtm-x86_64-linux

sudo install -Dm755 bin/gtm  /usr/local/bin/gtm
sudo install -Dm755 bin/gtmd /usr/local/bin/gtmd
sudo install -Dm644 man/man1/gtm.1 man/man1/gtmd.1 man/man1/gtmd-ipc.1 /usr/local/share/man/man1/
sudo install -Dm644 systemd/gtmd.service /usr/local/lib/systemd/user/gtmd.service
sudo install -Dm644 completions/gtm.bash completions/gtmd.bash /usr/local/share/bash-completion/completions/
sudo install -Dm644 completions/_gtm completions/_gtmd /usr/local/share/zsh/vendor-completions/
sudo install -Dm644 completions/gtm.fish completions/gtmd.fish /usr/local/share/fish/vendor_completions.d/

systemctl --user daemon-reload
systemctl --user enable --now gtmd

Substitute aarch64-linux, aarch64-linux-musl (musl), aarch64-darwin, or aarch64-android for x86_64-linux as needed. Verify the download with the release's checksums.txt.

Native packages are also published for each release:

Build from Source

Requires Rust 1.81+ and ALSA development headers (libasound2-dev on Debian/Ubuntu).

cargo build --release
sudo make install

To install just the client binary (for example to try the TUI against an already-running daemon), or to install without system packages:

cargo install --path gtm

Screenshots

Crates

The audio player is split into separate crates, allowing you to easily pick which component of the player you want to tweak.

Documentation

• Wiki
• gtm.spec
• gtm(1)
• gtmd(1)
• gtmd-ipc(1)

Contributing

[!note]

This is a hobby project but is feature complete and stable enough to use as my daily driver. However its still largely a WIP.

See CONTRIBUTING.md for build instructions, the crate layout and the green gates (fmt / clippy / test).

License 📜

(c) 2025 - present, prjctimg

This is free software, released under the GPL-3.0 license.