playlist writes one portable .m3u in each selected album folder. Paths resolve relative to the playlist’s directory, so moving the album with its playlist preserves those links. A multi-disc release gets one playlist at the common album folder, with discs in order.
By default #EXTINF lines carry titles and duration. --simple leaves paths only. --artists also writes a chronological discography playlist when albums share a real artist folder; it does not invent an artist folder or clutter a flat music root. --dry-run previews exactly those files without writing.
This command creates/updates playlist sidecars, not audio copies. Folder permissions matter. To export a temporary selection somewhere else, use query --m3u --output or collection --m3u instead. To play the result, pass its M3U/M3U8 path to play.
Syntax and arguments#
aede playlist [folder…]
Optional catalogued music folders.
Options for this command#
| Option | Meaning |
|---|---|
--dry-run | Preview the work without making downloads or creating outputs. It can still validate tools and inputs. |
--simple | Write plain playlist paths without #EXTINF duration/title lines. |
--artists | Also create one playlist per shared artist folder when that folder can be identified safely. |
The shared options reference explains --data, --no-color, --help/-h, --version/-v/-V, option values and output/pagination rules. These shared presentation/data options do not make every command support CSV/JSON or pagination.
Examples#
aede playlist "$HOME/Music/Jazz" --dry-run
aede playlist "$HOME/Music/Jazz" --artists
Result and errors#
A selected path containing a carriage return or newline is refused before any playlist is written, because M3U cannot represent it without introducing another entry. Selection exports with --m3u enforce the same rule.
The summary distinguishes playlists to write, written, already up to date and failed. --dry-run lists at most the first 20 planned paths and counts the rest without writing; unchanged playlists retain their timestamps. Releases sharing a physical folder contribute to one combined playlist. Changed files are published from isolated temporary output only after a complete write. No selected catalog album returns an explanatory message and succeeds. Per-playlist filesystem errors are listed and counted, and any failure gives a nonzero exit status. Playlist output is UTF-8 text with a .m3u filename; the command copies no audio.
The unchanged-file check accepts only regular destination files and compares bytes with a fixed-size buffer, without reading an arbitrary existing file into memory. A destination link or special file is refused rather than accepted as current output or opened waiting for data. An unavailable album/artist folder is reported as a failure and is not recreated from retained catalog metadata; other available folders still receive their playlists. Explicit selection exports may still create their chosen output directories.
Related reading#
play, query, collection.
Detailed existing guide: playlists.md.