From 4d3a6c727ddcf2a0b9fbb8ca58afb501ab8a284a Mon Sep 17 00:00:00 2001 From: Jan Holthuis Date: Fri, 15 Feb 2019 23:06:36 +0100 Subject: [PATCH] docs: Add documentation for the playlist plugin --- docs/plugins/index.rst | 2 ++ docs/plugins/playlist.rst | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 docs/plugins/playlist.rst diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index 6bf50e227b..e51354dacb 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -81,6 +81,7 @@ like this:: mpdupdate permissions play + playlist plexupdate random replaygain @@ -158,6 +159,7 @@ Interoperability * :doc:`mpdupdate`: Automatically notifies `MPD`_ whenever the beets library changes. * :doc:`play`: Play beets queries in your music player. +* :doc:`playlist`: Use M3U playlists tp query the beets library. * :doc:`plexupdate`: Automatically notifies `Plex`_ whenever the beets library changes. * :doc:`smartplaylist`: Generate smart playlists based on beets queries. diff --git a/docs/plugins/playlist.rst b/docs/plugins/playlist.rst new file mode 100644 index 0000000000..0a4e797c3a --- /dev/null +++ b/docs/plugins/playlist.rst @@ -0,0 +1,37 @@ +Smart Playlist Plugin +===================== + +``playlist`` is a plugin to use playlists in m3u format. + +To use it, enable the ``playlist`` plugin in your configuration +(see :ref:`using-plugins`). +Then configure your playlists like this:: + + playlist: + relative_to: ~/Music + playlist_dir: ~/.mpd/playlists + +It is possible to query the library based on a playlist by speicifying its +absolute path:: + + $ beet ls playlist:/path/to/someplaylist.m3u + +The plugin also supports referencing playlists by name. The playlist is then +seached in the playlist_dir and the ".m3u" extension is appended to the +name:: + + $ beet ls playlist:anotherplaylist + +Configuration +------------- + +To configure the plugin, make a ``smartplaylist:`` section in your +configuration file. In addition to the ``playlists`` described above, the +other configuration options are: + +- **playlist_dir**: Where to read playlist files from. + Default: The current working directory (i.e., ``'.'``). +- **relative_to**: Interpret paths in the playlist files relative to a base + directory. It is also possible to set it to ``playlist`` to use the + playlist's parent directory as base directory. + Default: ``library``