charmusic

A terminal music player in C, made for the foot terminal. Folders are albums; you can also play single songs.

• File browser, queue, shuffle and repeat
• Live spectrum visualizer
• Cover art (sixel or blocks)
• FLAC, MP3, WAV and Ogg Vorbis built in; Opus, AAC and others through ffmpeg
• Color themes, icon sets and border styles

Dependencies

• GNU make and a C compiler
• Linux with PipeWire, PulseAudio or ALSA (found at runtime)
• Optional: ffmpeg for formats such as Opus and AAC/M4A, and for covers stored as video streams

miniaudio, stb_vorbis and stb_image are bundled in vendor/.

For the static build only: zig and curl.

Build

make

Static x86_64 musl binary for other distros (downloads and builds alsa-lib on first run):

make static

This produces charmusic-static. It talks to ALSA directly, so it fails with "couldn't open an audio device" if PipeWire or PulseAudio holds the sound card. Use the normal build there.

Run

./charmusic                  # opens your music folder
./charmusic ~/Music/Album    # plays a folder or a single song

Press ? inside for the key list. Common keys: Space pause, n/p next/previous, ,/. seek, +/- volume, z shuffle, r repeat, v visualizer, s settings, q quit. The mouse works too.

Configuration

Settings are changed in the app (s, or the gear button): theme, music folder, album art, visualizer, icons, borders, scroll speed, seek step, hidden files and resume.

They are saved to charmusic.conf next to the binary, along with the resume point. The file is created on first save and nothing is written anywhere else. The default music folder is ~/Music.

Tests

make test

Needs no audio hardware. With ffmpeg installed it also checks generated media files.

make test-smoke

Runs the app in a pseudo-terminal. Needs Python 3 and a working audio backend.