walcman

A lightweight music and audio player that lives in your terminal. Built with C and miniaudio for minimal resource consumption and maximum performance.

Features

• Play MP3, WAV, FLAC, M4A, OGG, AAC, WMA
• Single-key controls (no Enter required)
• Queue and playlist support 🚀
• File and folder argument support
• Auto-detect end of playback
• macOS installer with version management
• Optional non-blocking auto-update check

Platform Support

Platform	Status	Installer
macOS	Stable	Yes
Linux	Stable	Yes
Windows	Experimental	No

Linux and Windows require a manual build.

---

Installation

macOS / Linux

Note: only macOS currently supports the autoupdater, Linux users will have to manually reinstall on updates for now

git clone https://github.com/lassedtu/walcman.git
cd walcman
make install

Restart your terminal or source your shell config to update PATH:

source ~/.zshrc

To uninstall:

make uninstall

Windows (Manual Build)

Requirements: C compiler (clang or gcc), make, POSIX environment

git clone https://github.com/lassedtu/walcman.git
cd walcman
make
./build/walcman

---

Usage

Note: If installed via the macOS or Linux installer, run walcman from any directory. If built manually, use ./build/walcman.

walcman

To play a file directly:

walcman /path/to/song.mp3

To play a playlist/folder directly:

walcman /path/to/playlist

Controls

Key	Action
p	Play file
Space	Pause / Resume
s	Stop
r	Toggle repeat
n	Next track
b	Previous track
v	View queue
l	Load playlist folder
a	Add file to queue
f	Toggle shuffle
c	Toggle controls
o	Open settings
q	Quit

---

Configuration

Only available when installed via the macOS or Linux installer.

Config file: ~/.config/walcman/config

Option	Values	Description
update_check_enabled	1 / 0	Enable or disable update checks
check_interval_hours	Integer	How often to check for updates (hours)
ui_color	Color name	Color for entire UI text (optional)

Example:

update_check_enabled=1
check_interval_hours=24
ui_color=cyan

Available colors:

• red, green, yellow, blue
• pink, magenta, purple (magenta and purple are aliases for pink)
• cyan, white, gray, orange
• Leave empty for default terminal color

---

Contributing

Contributions are welcome! Fork the repo, make your changes on a new branch, and open a Pull Request.

Acknowledgments

• miniaudio: core audio library
• Ana: for the original concept and for helping refine the direction of the project from its earliest stages
• mashdtu: for providing Linux installation / uninstallation scripts