Playlists as filesystem projections over a canonical music library.

playlist-fs is a local-first, file-based toolkit where playlists are just symlinked filesystem views over a canonical music library.

No daemon.
No cloud.
No login.
Just files + symlinks + shell.

• Your music lives in one place: ~/Music/_library/Artist/Album/Track
• Playlists are views: ~/Music/Playlists/<name>/ containing symlinks to tracks in _library
• New downloads go to _incoming/ until you curate them

Install the music command into ~/.local/bin for normal day-to-day use.

On Linux Mint:

sudo apt update
sudo apt install -y git mpg123
git clone https://github.com/ldamasio/playlist-fs.git
cd playlist-fs
./bin/install

If ~/.local/bin is not already in your PATH, ./bin/install prints the exact command to add it.

To remove the daily-use install later:

./bin/uninstall

For the full beginner flow on Linux Mint, see docs/linux-mint.md.

If you just want to test the repo before installing anything into your shell, run the script directly:

./bin/music "$HOME/Music/_library"
./bin/music "$HOME/Music/Playlists/focus"

Create the canonical library and one playlist:

mkdir -p "$HOME/Music/_library/Artist/Album"
mkdir -p "$HOME/Music/Playlists/focus"

Put .mp3 files into _library:

cp "/path/to/01 - Track.mp3" "$HOME/Music/_library/Artist/Album/"

Link one track into the playlist:

ln -s \
  "$HOME/Music/_library/Artist/Album/01 - Track.mp3" \
  "$HOME/Music/Playlists/focus/artist-album-track.mp3"

music is a stateless wrapper around mpg123.

• It reads the filesystem at launch time.
• It follows playlist symlinks with find -L.
• It only passes .mp3 files to mpg123.
• It backgrounds playback and leaves process control to the shell.

Examples:

music
music "$HOME/Music/Playlists/focus"
music "$HOME/Music/_library"
pkill -x mpg123

• Linux Mint quickstart: docs/linux-mint.md
• Examples: docs/examples.md
• Design: docs/design.md

bash tests/smoke.sh