mush

mush — music in the shell

A small POSIX C command-line tool for managing playlists and playing/downloading audio using mpv and yt-dlp.

Features

• Create and manage playlists
• Create playlist groups
• Download audio from URLs (YouTube via yt-dlp)
• Play playlists using mpv
• Local storage under ~/.config/mush/

Requirements

Runtime dependencies

• mpv
• yt-dlp
• ffmpeg (required for audio conversion)

Without ffmpeg, downloads may fail during post-processing:

Encoder not found

Build

make

Produces:

./mush

Install

sudo make install

Default install path:

/usr/local/bin/mush

Custom prefix:

make PREFIX=/usr install

Uninstall

sudo make uninstall

Clean

make clean

Usage

Run without arguments:

./mush

Commands

h, --help
 Show help screen
ap <name> [songs...]
 Add songs to a playlist
apg <name> [playlists...]
 Add playlists to a playlist group
d <url>
 Download audio from a URL via yt-dlp
lp, --list-playlists
 List all playlists
lpg, --list-playlist-groups
 List all playlist groups
ls, --list-songs
 List downloaded songs
pp <name>
 Play a playlist through mpv
ppg <name>
 Play a playlist group through mpv
rp <name>
 Remove a playlist
rpg <name>
 Remove a playlist group

Data directory

All data is stored in:

~/.config/mush/

Structure:

~/.config/mush/
 playlists/
 groups/
 songs/

Example

./mush ap mylist song1 song2
./mush lp
./mush pp mylist
./mush d "https://www.youtube.com/watch?v=VIDEO_ID"

Notes

• Playlist entries must exist in ~/.config/mush/songs/
• Missing files will cause playback errors
• Ensure downloaded filenames match playlist entries

Common issues

Encoder not found

Install ffmpeg:

• Arch: sudo pacman -S ffmpeg
• Debian/Ubuntu: sudo apt install ffmpeg

Time warning in make

If you see:

File 'main.c' has modification time in the future

Fix with:

find . -type f -exec touch {} +