█████╗ ██╗   ██╗██████╗ ██╗██╗   ██╗███╗   ███╗
██╔══██╗██║   ██║██╔══██╗██║██║   ██║████╗ ████║
███████║██║   ██║██║  ██║██║██║   ██║██╔████╔██║
██╔══██║██║   ██║██║  ██║██║██║   ██║██║╚██╔╝██║
██║  ██║╚██████╔╝██████╔╝██║╚██████╔╝██║ ╚═╝ ██║
╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═════╝ ╚═╝     ╚═╝

A terminal music player.

Website · Installation · Keybindings · Building

Features

• Keyboard-driven — every action is one key. No mouse required.
• It's your library — your tracks are stored as plain JSON at ~/.audium/library.json. Edit it by hand, back it up, move it anywhere. audium doesn't rename your files, doesn't embed metadata, and never phones home.
• Themes — 15 built-in themes (dark, light, nord, gruvbox, catppuccin, rosé pine, dracula, tokyo night, and more). Switch live from the settings menu with instant preview. Transparency support for composited terminals.
• Playlists — create, rename, delete. All Tracks is always there.
• Loop modes — off, loop queue, or loop track. Toggle with l.
• Built-in file picker — import audio files without leaving the app.
• Threaded audio — playback runs on its own thread; the UI never stutters your music.
• System audio output — audium plays through your default system output. Change the output device in your OS and audium follows — no in-app device switching, no surprises.
• Format agnostic — MP3, FLAC, OGG, WAV, AAC, M4A, Opus, AIFF and more via Symphonia. No FFmpeg required.
• Tiny binary — ~3 MB stripped release build. No runtime dependencies on macOS.

---

Installation

Cargo

cargo install audium

Requires Rust 1.85+ (MSRV). Installs the audium binary to ~/.cargo/bin/.

On Linux, ALSA is required to run and its development headers are required to build — see Building from source for distro-specific instructions.

AUR (Arch Linux)

paru -S audium
# or: yay -S audium

---

Usage

# Launch with your library
audium

# Open a specific file immediately (imports it to your library)
audium path/to/song.flac

audium stores your library at ~/.audium/library.json and your music at ~/.audium/music/.

---

Keybindings

Global

Key	Action
q	Quit
Tab	Cycle panel focus
?	Toggle help overlay

Playback

Key	Action
Space	Play / Pause
n	Next track
N	Previous track
← / →	Seek backward / forward
+ / =	Volume up
-	Volume down
l	Cycle loop mode

Navigation

Key	Action
j / ↓	Move cursor down
k / ↑	Move cursor up
Enter	Play selected track

Library & Queue

Key	Action
f	Open file picker
a	Add selected track to queue
p	Add selected track to a playlist
c	Create new playlist
z	Shuffle playlist into queue
d	Remove selected item
r	Rename selected track or playlist
m	Open menu

---

Building from source

git clone https://github.com/takashialpha/audium
cd audium
cargo build --release
# binary is at ./target/release/audium

Linux requires ALSA and its development headers:

# Debian / Ubuntu
sudo apt install alsa-base alsa-utils libasound2-dev

# Arch
sudo pacman -S alsa-utils alsa-lib

# Fedora
sudo dnf install alsa-utils alsa-lib-devel

macOS has no extra dependencies.

Windows: audium compiles on Windows (no additional dependencies) but is not an officially supported platform and has not been tested.

---

Library layout

~/.audium/
├── library.json   # track registry + playlists
├── settings.json  # user preferences (volume, theme, seek step)
└── music/         # copies of all imported audio files

library.json is human-readable and editable by hand. audium re-validates it on next launch, so feel free to reorganise playlists, fix track names, or move the file to another machine.

---

Why audium?

Alternatives like termusic and cmus are solid, but they come with tradeoffs: heavy dependency trees, FFmpeg requirements, daemon processes, or configuration formats that take longer to learn than the app itself. audium is different in a few concrete ways:

• No FFmpeg, no daemon — one binary, zero background processes.
• Smaller and faster to build — fewer dependencies means shorter compile times and a ~3 MB release binary.
• Cleaner UI — built on ratatui with a layout designed for actual daily use, not just feature completeness.
• More modern codebase — written in current Rust with edition 2024, Symphonia for decoding, and rodio for playback.
• Plain JSON library — your data is always readable, portable, and yours.

TODO

• custom track fields (author, album, tags, etc.) stored in library.json
• filtering by custom fields
• playback speed presets (0.5× → 2×)
• user-provided synced lyrics with overlay/panel support
• YouTube audio import (WIP by contributor)

Notes

• truncate long filenames in filepicker popups
• add more feature cards to the website grid
• make transparency update live + apply on startup
• use the GIF on the website too

Contributing

Issues and pull requests are welcome. Please open an issue before starting work on a large change.