Documentation¶
Genplis generates M3U playlists from the tags and audio properties in your
local music files. Write your rules in a .m3ug file, run Genplis, and it
writes a matching .m3u playlist next to it.
Quickstart¶
1. Install¶
You need Python 3.12 or later.
Install Genplis with uv:
uv tool install genplis
genplis --version
Or with pipx:
pipx install genplis
If you prefer to work from a clone, follow the development setup.
2. Define a playlist¶
Save this as ~/Music/Metal.m3ug (adjust the collection path as needed):
# An hour of metal, shuffled
genre ~ "Metal"
@SORT random
@MAX-DURATION 1h
~ means “contains”, so this includes genres such as Heavy Metal.
All ordinary rules in one file must match; directives beginning with @
control ordering and selection.
3. Generate it¶
genplis ~/Music
When songs match, ~/Music/Metal.m3u appears next to your filter. Open it in
a player that supports local M3U playlists. Run Genplis again after adding
music or changing tags to refresh your playlists.
If nothing matches, no playlist is written. Check the tags of a song with:
genplis ~/Music/some-song.mp3
Where next?¶
| I want to… | Start here |
|---|---|
| Understand commands, options, playlists, or the cache | Usage guide |
| Write more expressive filters | M3UG reference |
| Have an AI agent write filters for my library | AI agents |
| Copy a ready-made playlist definition | M3UG Examples |
| Set defaults for my collection | Configuration |
| Find usable tags or understand rating scales | Tags |
| Regenerate playlists automatically | Scheduling |
| Work on Genplis itself | Development |
Use Search in the header to find a command, tag, directive, or example across the documentation. The search runs in your browser, with no external search service.
Looking for the project overview? Back to Home.