beets-playlistmanager

A playlist management plugin for beets.

Configuration

Enable the plugin and, optionally, choose where its sidecar SQLite database is stored:

plugins: playlistmanager

playlistmanager:
  database: /path/to/playlist.db
  targets:
    - name: plists
      kind: m3u
      directory: ~/Playlists
      relative_to: library

The database defaults to playlist.db in the beets configuration directory, alongside the default config.yaml and library.db. Relative database paths are also resolved from that directory.

Each rendering target needs a unique name. The only target kind currently supported is m3u. Its directory is created when needed, and relative target directories are resolved from the beets library directory. relative_to controls the paths written for tracks:

• library makes paths relative to the beets library directory.
• playlist makes paths relative to the generated M3U file.
• An absolute path (with ~ and environment-variable expansion supported) uses that directory as the base.

Commands

Create an empty playlist:

beet playlist create "Road Trip"

List the stored playlists, one name per line:

beet playlist list

Add all items matching a beets query to the end of a playlist:

beet playlist add "J-Pop" "artist:YOASOBI"

Remove all occurrences of items matching a query from a playlist:

beet playlist remove "J-Pop" "artist:YOASOBI"

The add and remove commands print the proposed item-level changes and ask for confirmation before updating the playlist.

Render every stored playlist to every configured target:

beet playlist sync

An M3U target writes a UTF-8 <playlist name>.m3u file containing one track path per line. Playlist order and duplicate track occurrences are preserved. Entries referring to items no longer present in the beets library are skipped with a warning. Sync overwrites files for current playlists but does not delete stale or unrelated M3U files from the target directory.

Querying by playlist

Use the playlist query field anywhere beets accepts an item query:

beet list "playlist:My Mix"

Playlist names are matched case-insensitively. Quote the query when the name contains spaces. The filter composes with other beets queries and sorting:

beet list "playlist:My Mix" "genre:Rock" year+

This is a membership query: results use the normal beets sort order, and a track appears once even if the playlist contains it more than once.

Interactive editor

Install the optional TUI dependency:

pip install 'beets-playlistmanager[tui]'

Then open an existing playlist in the interactive editor:

beet playlist edit "Road Trip"

Enter a beets query and press Enter to populate the search pane. Space marks tracks in the focused pane; A appends marked search results and D removes marked playlist occurrences. Changes are staged until Ctrl+S saves them. Esc cancels, asking for confirmation when there are unsaved changes.

The playlist pane represents occurrences rather than unique track IDs, so a single occurrence of a duplicated track can be removed independently.