From cb350de2eaa3c739462c174515cd36e3a627c94a Mon Sep 17 00:00:00 2001 From: Fabrice Laporte Date: Sun, 26 Oct 2014 22:29:10 +0100 Subject: [PATCH 01/15] harmonize all plugins docs Add a configuration section that lists all options for each plugin. List options in alphabetic order. Mention the default value for each option. Use same sentences to describe concepts common to different plugins eg 'auto option, install description --- docs/plugins/beatport.rst | 4 +- docs/plugins/bpd.rst | 40 ++++---- docs/plugins/bpm.rst | 19 ++-- docs/plugins/bucket.rst | 47 ++++++--- docs/plugins/chroma.rst | 31 +++--- docs/plugins/convert.rst | 56 +++++------ docs/plugins/discogs.rst | 4 +- docs/plugins/duplicates.rst | 163 ++++++++++---------------------- docs/plugins/echonest.rst | 73 ++++++-------- docs/plugins/echonest_tempo.rst | 42 ++++---- docs/plugins/embedart.rst | 68 +++++++------ docs/plugins/fetchart.rst | 60 ++++++------ docs/plugins/fromfilename.rst | 4 +- docs/plugins/ftintitle.rst | 27 ++++-- docs/plugins/fuzzy.rst | 22 ++--- docs/plugins/ihate.rst | 18 +++- docs/plugins/importadded.rst | 16 +++- docs/plugins/importfeeds.rst | 47 +++++---- docs/plugins/index.rst | 9 +- docs/plugins/info.rst | 3 +- docs/plugins/inline.rst | 7 +- docs/plugins/keyfinder.rst | 26 ++--- docs/plugins/lastgenre.rst | 96 +++++++++---------- docs/plugins/lyrics.rst | 60 ++++++------ docs/plugins/mbcollection.rst | 19 ++-- docs/plugins/mbsync.rst | 6 +- docs/plugins/missing.rst | 68 +++++-------- docs/plugins/mpdstats.rst | 59 +++++------- docs/plugins/mpdupdate.rst | 18 +++- docs/plugins/play.rst | 27 ++++-- docs/plugins/random.rst | 4 +- docs/plugins/replaygain.rst | 34 ++++--- docs/plugins/rewrite.rst | 11 +-- docs/plugins/scrub.rst | 13 ++- docs/plugins/smartplaylist.rst | 29 +++--- docs/plugins/spotify.rst | 38 ++++---- docs/plugins/the.rst | 48 +++++----- docs/plugins/web.rst | 13 ++- docs/plugins/zero.rst | 18 ++-- 39 files changed, 673 insertions(+), 674 deletions(-) diff --git a/docs/plugins/beatport.rst b/docs/plugins/beatport.rst index 0940ff501..539c80ffb 100644 --- a/docs/plugins/beatport.rst +++ b/docs/plugins/beatport.rst @@ -18,8 +18,8 @@ both MusicBrainz and (to a lesser degree) Discogs show no matches. Installation ------------ -To see matches from the ``beatport`` plugin, you first have to enable it in -your configuration (see :doc:`/plugins/index`). Then, install the `requests`_ +To use the plugin, first enable it in your configuration (see +:ref:`using-plugins`). Then, install the `requests`_ library (which we need for querying the Beatport API) by typing:: pip install requests diff --git a/docs/plugins/bpd.rst b/docs/plugins/bpd.rst index 919a45ec3..846d4638e 100644 --- a/docs/plugins/bpd.rst +++ b/docs/plugins/bpd.rst @@ -38,13 +38,11 @@ installing GStreamer plugins. .. _GStreamer WinBuilds: http://www.gstreamer-winbuild.ylatuya.es/ .. _Homebrew: http://mxcl.github.com/homebrew/ -Using and Configuring ---------------------- - -BPD is a plugin for beets. It comes with beets, but it's disabled by default. -To enable it, you'll need to edit your :doc:`configuration file -` and add ``bpd`` to your ``plugins:`` line. +Usage +----- +To use the plugin, first enable it in your configuration (see +:ref:`using-plugins`). Then, you can run BPD by invoking:: $ beet bpd @@ -69,10 +67,20 @@ the client can just as easily on a different computer from the server as it can be run locally. Control your music from your laptop (or phone!) while it plays on your headless server box. Rad! -To configure the BPD server, add a ``bpd:`` section to your ``config.yaml`` -file. The configuration values, which are pretty self-explanatory, are ``host``, -``port``, ``password`` and ``volume``. The volume option sets the initial -volume (in percent, default: 100). Here's an example:: +Configuration +------------- + +Available options are pretty self-explanatory : + +- ``host`` + Default: ``u''`` +- ``port`` + Default: ``6600`` +- ``password``: ``u'`` +- ``volume`` sets the initial volume in percent + Default: ``100`` + +Here's an example:: bpd: host: 127.0.0.1 @@ -83,13 +91,13 @@ volume (in percent, default: 100). Here's an example:: Implementation Notes -------------------- -In the real MPD, the user can browse a music directory as it appears on disk. In -beets, we like to abstract away from the directory structure. Therefore, BPD +In the real MPD, the user can browse a music directory as it appears on disk. +In beets, we like to abstract away from the directory structure. Therefore, BPD creates a "virtual" directory structure (artist/album/track) to present to -clients. This is static for now and cannot be reconfigured like the real on-disk -directory structure can. (Note that an obvious solution to this is just string -matching on items' destination, but this requires examining the entire library -Python-side for every query.) +clients. This is static for now and cannot be reconfigured like the real +on-disk directory structure can. (Note that an obvious solution to this is just +string matching on items' destination, but this requires examining the entire +library Python-side for every query.) We don't currently support versioned playlists. Many clients, however, use plchanges instead of playlistinfo to get the current playlist, so plchanges diff --git a/docs/plugins/bpm.rst b/docs/plugins/bpm.rst index 47a37a8c1..4494106dd 100644 --- a/docs/plugins/bpm.rst +++ b/docs/plugins/bpm.rst @@ -1,22 +1,29 @@ BPM Plugin ========== -This ``bpm`` plugin lets you to get the tempo (beats per minute) of a song by tapping out the beat on your keyboard. +This ``bpm`` plugin lets you to get the tempo (beats per minute) of a song by +tapping out the beat on your keyboard. Usage ----- -First, enable the plugin ``bpm`` as described in :doc:`/plugins/index`. Then, play a song you want to measure in your favorite media player and type:: +To use the plugin, first enable it in your configuration (see +:ref:`using-plugins`). - beet bpm +Then, play a song you want to measure in your favorite media player and type:: -You'll be prompted to press Enter three times to the rhythm. This typically allows to determine the BPM within 5% accuracy. + beet bpm -The plugin works best if you wrap it in a script that gets the playing song. for instance, with ``mpc`` you can do something like:: +You'll be prompted to press Enter three times to the rhythm. This typically +allows to determine the BPM within 5% accuracy. + +The plugin works best if you wrap it in a script that gets the playing song. +for instance, with ``mpc`` you can do something like:: beet bpm $(mpc |head -1|tr -d "-") Credit ------ -This plugin is inspired by a similar feature present in the Banshee media player. +This plugin is inspired by a similar feature present in the Banshee media +player. diff --git a/docs/plugins/bucket.rst b/docs/plugins/bucket.rst index c3b1ae601..43ffeec55 100644 --- a/docs/plugins/bucket.rst +++ b/docs/plugins/bucket.rst @@ -7,8 +7,9 @@ The ``bucket`` plugin groups your files into buckets folders representing smaller subfolders by grouping albums or artists alphabetically (e.g. *A-F*, *G-M*, *N-Z*). -To use the plugin, enable ``bucket`` in your configuration file (see -:ref:`using-plugins`). The plugin provides a :ref:`template function +To use the plugin, first enable it in your configuration (see +:ref:`using-plugins`). +The plugin provides a :ref:`template function ` called ``%bucket`` for use in path format expressions:: paths: @@ -25,25 +26,43 @@ The ``bucket_year`` parameter is used for all substitutions occuring on the The definition of a range is somewhat loose, and multiple formats are allowed: -- For alpha ranges: the range is defined by the lowest and highest (ASCII-wise) alphanumeric characters in the string you provide. For example, *ABCD*, *A-D*, *A->D*, and *[AD]* are all equivalent. -- For year ranges: digits characters are extracted and the two extreme years define the range. For example, *1975-77*, *1975,76,77* and *1975-1977* are equivalent. If no upper bound is given, the range is extended to current year (unless a later range is defined). For example, *1975* encompasses all years from 1975 until now. +- For alpha ranges: the range is defined by the lowest and highest (ASCII-wise) + alphanumeric characters in the string you provide. For example, *ABCD*, + *A-D*, *A->D*, and *[AD]* are all equivalent. +- For year ranges: digits characters are extracted and the two extreme years + define the range. For example, *1975-77*, *1975,76,77* and *1975-1977* are + equivalent. If no upper bound is given, the range is extended to current year + (unless a later range is defined). For example, *1975* encompasses all years + from 1975 until now. -If you want to group your files into multiple year ranges, you don't have to -enumerate them all in `bucket_year` parameter but can activate the ``extrapolate`` -option instead. This option will generate year bucket names by reproducing characteristics -of declared buckets:: +Configuration +------------- - bucket: - bucket_year: ['2000-05'] - extrapolate: true +Available options : -The above configuration creates five-year ranges for any input year. +- ``bucket_alpha`` defines ranges to use for all substitutions occuring on + textual fields. + Default: ``[]`` +- ``bucket_alpha_regex`` allows to define a regex to override a `bucket_alpha` + range definition + Default: ``{}`` +- ``bucket_year`` defines ranges to use for all substitutions occuring on the + `$year` field + Default: ``[]`` +- ``extrapolate`` : activate it when you want to group your files into multiple + year ranges without enumerating them all. This option will generate year + bucket names by reproducing characteristics of declared buckets. + Default: ``no`` -If the automatic range of an alpha bucket is not sufficient an overriding regular expression can be used:: +Here's an example:: bucket: + bucket_year: ['2000-05'] + extrapolate: true bucket_alpha: ['A - D', 'E - L', 'M - R', 'S - Z'] bucket_alpha_regex: 'A - D': ^[0-9a-dA-D…äÄ] -The *A - D* bucket now matches also all artists starting with ä or Ä and 0 to 9 and … (three dots). The other buckets work as ranges (see above). +The above configuration creates five-year ranges for any input year. +The *A - D* bucket now matches also all artists starting with ä or Ä and 0 to 9 +and … (three dots). The other alpha buckets work as ranges. diff --git a/docs/plugins/chroma.rst b/docs/plugins/chroma.rst index 511bde4b6..4603ee3de 100644 --- a/docs/plugins/chroma.rst +++ b/docs/plugins/chroma.rst @@ -65,10 +65,10 @@ You will also need a mechanism for decoding audio files supported by the need to install anything. * On Linux, you can install `GStreamer for Python`_, `FFmpeg`_, or `MAD`_ and - `pymad`_. How you install these will depend on your distribution. For example, - on Ubuntu, run ``apt-get install python-gst0.10-dev``. On Arch Linux, you want - ``pacman -S gstreamer0.10-python``. If you use GStreamer, be sure to install - its codec plugins also. + `pymad`_. How you install these will depend on your distribution. + For example, on Ubuntu, run ``apt-get install python-gst0.10-dev``. On Arch + Linux, you want ``pacman -S gstreamer0.10-python``. If you use GStreamer, be + sure to install its codec plugins also. * On Windows, try the Gstreamer "WinBuilds" from the `OSSBuild`_ project. @@ -87,13 +87,12 @@ standard set of Gstreamer plugins. For example, on Ubuntu, install the packages ``gstreamer0.10-plugins-good``, ``gstreamer0.10-plugins-bad``, and ``gstreamer0.10-plugins-ugly``. -Using +Usage ----- -Once you have all the dependencies sorted out, you can enable fingerprinting by -editing your :doc:`configuration file `. Put ``chroma`` on -your ``plugins:`` line. With that, beets will use fingerprinting the next time -you run ``beet import``. +Once you have all the dependencies sorted out, enable the plugin in your +configuration (see :ref:`using-plugins`) to benefit from fingerprinting the +next time you run ``beet import``. You can also use the ``beet fingerprint`` command to generate fingerprints for items already in your library. (Provide a query to fingerprint a subset of your @@ -101,16 +100,16 @@ library.) The generated fingerprints will be stored in the library database. If you have the ``import.write`` config option enabled, they will also be written to files' metadata. -You can disable fingerprinting on import by setting the ``auto`` option to -false, like so:: - - chroma: - auto: no - .. _submitfp: +Configuration +------------- + +The only option is **auto**, set it to 'no' to disable fingerprinting on +import. + Submitting Fingerprints -''''''''''''''''''''''' +----------------------- You can help expand the `Acoustid`_ database by submitting fingerprints for the music in your collection. To do this, first `get an API key`_ from the Acoustid diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst index 135d239a7..ee99e15a6 100644 --- a/docs/plugins/convert.rst +++ b/docs/plugins/convert.rst @@ -10,8 +10,8 @@ line. Installation ------------ -Enable the ``convert`` plugin in your configuration (see -:doc:`/plugins/index`). By default, the plugin depends on `FFmpeg`_ to +To use the plugin, first enable it in your configuration (see +:ref:`using-plugins`). By default, the plugin depends on `FFmpeg`_ to transcode the audio, so you might want to install it. .. _FFmpeg: http://ffmpeg.org @@ -50,35 +50,37 @@ them. Configuration ------------- -The plugin offers several configuration options, all of which live under the -``convert:`` section: +Available options : -* ``dest`` sets the directory the files will be converted (or copied) to. - A destination is required---you either have to provide it in the config file - or on the command-line using the ``-d`` flag. -* ``embed`` indicates whether or not to embed album art in converted items. - Default: true. -* If you set ``max_bitrate``, all lossy files with a higher bitrate will be - transcoded and those with a lower bitrate will simply be copied. Note that - this does not guarantee that all converted files will have a lower - bitrate---that depends on the encoder and its configuration. -* ``auto`` gives you the option to import transcoded versions of your files +- ``auto`` gives you the option to import transcoded versions of your files automatically during the ``import`` command. With this option enabled, the importer will transcode all non-MP3 files over the maximum bitrate before adding them to your library. -* ``quiet`` mode prevents the plugin from announcing every file it processes. - Default: false. -* ``never_convert_lossy_files`` means that lossy codecs, such as mp3, ogg vorbis, - etc, are never converted, as converting lossy files to other lossy codecs will - decrease quality further. If set to true, lossy files are always copied. - Default: false -* ``paths`` lets you specify the directory structure and naming scheme for the + Default: ``no``. +- ``dest`` sets the directory the files will be converted (or copied) to. + A destination is required---you either have to provide it in the config file + or on the command-line using the ``-d`` flag. +- ``embed`` indicates whether or not to embed album art in converted items. + Default: ``yes``. +- ``max_bitrate``: all lossy files with a higher bitrate will be + transcoded and those with a lower bitrate will simply be copied. Note that + this does not guarantee that all converted files will have a lower + bitrate---that depends on the encoder and its configuration. +- ``never_convert_lossy_files`` means that lossy codecs, such as mp3, ogg + vorbis, etc, are never converted, as converting lossy files to other lossy + codecs will decrease quality further. If set to ``yes``, lossy files are + always copied. + Default: ``no`` +- ``paths`` lets you specify the directory structure and naming scheme for the converted files. Use the same format as the top-level ``paths`` section (see - :ref:`path-format-config`). By default, the plugin reuses your top-level - path format settings. -* Finally, ``threads`` determines the number of threads to use for parallel - encoding. By default, the plugin will detect the number of processors - available and use them all. + :ref:`path-format-config`). + By default, the plugin reuses your top-level path format settings. +- ``quiet`` mode prevents the plugin from announcing every file it processes. + Default: ``false``. +- ``threads`` determines the number of threads to use for parallel + encoding. + By default, the plugin will detect the number of processors available and use + them all. .. _convert-format-config: @@ -114,7 +116,7 @@ formats: `mp3`, `alac`, `flac`, `aac`, `opus`, `ogg`, `wmv`. For details have a look at the output of ``beet config -d``. For a one-command-fits-all solution use the ``convert.command`` and -``convert.extension`` options. If these are set the formats are ignored +``convert.extension`` options. If these are set, the formats are ignored and the given command is used for all conversions.:: convert: diff --git a/docs/plugins/discogs.rst b/docs/plugins/discogs.rst index 1afee17d3..912aea7be 100644 --- a/docs/plugins/discogs.rst +++ b/docs/plugins/discogs.rst @@ -9,8 +9,8 @@ include matches from the `Discogs`_ database. Installation ------------ -First, enable the ``discogs`` plugin (see :doc:`/plugins/index`). Then, -install the `discogs-client`_ library by typing:: +To use the plugin, first enable it in your configuration (see +:ref:`using-plugins`). Then, install the `discogs-client`_ library by typing:: pip install discogs-client diff --git a/docs/plugins/duplicates.rst b/docs/plugins/duplicates.rst index b6be0a16a..eca009b5d 100644 --- a/docs/plugins/duplicates.rst +++ b/docs/plugins/duplicates.rst @@ -4,43 +4,20 @@ Duplicates Plugin This plugin adds a new command, ``duplicates`` or ``dup``, which finds and lists duplicate tracks or albums in your collection. -Installation ------------- +Usage +----- -Enable the plugin by putting ``duplicates`` on your ``plugins`` line in -your :doc:`config file `:: - - plugins: duplicates - -Configuration -------------- +To use the plugin, first enable it in your configuration (see +:ref:`using-plugins`). By default, the ``beet duplicates`` command lists the names of tracks in your library that are duplicates. It assumes that Musicbrainz track and album ids are unique to each track or album. That is, it lists every track or album with an ID that has been seen before in the library. - You can customize the output format, count the number of duplicate tracks or albums, and list all tracks that have duplicates or just the -duplicates themselves. These options can either be specified in the -config file:: - - duplicates: - checksum: no - copy: no - keys: mb_trackid album - album: no - count: no - delete: no - format: "$albumartist - $album - $title" - full: no - move: no - path: no - tag: no - - -or on the command-line:: +duplicates themselves via command-line switches :: -h, --help show this help message and exit -f FMT, --format=FMT print with custom format @@ -56,83 +33,50 @@ or on the command-line:: -p, --path print paths for matched items or albums -t TAG, --tag=TAG tag matched items with 'k=v' attribute +Configuration +------------- -format -~~~~~~ +Available options (mirroring the CLI ones) : -The ``format`` option (default: :ref:`list_format_item`) lets you -specify a specific format with which to print every track or -album. This uses the same template syntax as beets’ :doc:`path formats -`. The usage is inspired by, and therefore -similar to, the :ref:`list ` command. - -path -~~~~ - -Convenience wrapper for ``-f \$path``. - -count -~~~~~ - -The ``count`` option (default: false) prints a count of duplicate -tracks or albums, with ``format`` hard-coded to ``$albumartist - -$album - $title: $count`` or ``$albumartist - $album: $count`` (for -the ``-a`` option). - -album -~~~~~ - -The ``album`` option (default: false) lists duplicate albums instead -of tracks. - -full -~~~~ - -The ``full`` option (default: false) lists every track or album that -has duplicates, not just the duplicates themselves. - -keys -~~~~ - -The ``keys`` option (default: ``[mb_trackid, mb_albumid]``) defines in which track -or album fields duplicates are to be searched. By default, the plugin -uses the musicbrainz track and album IDs for this purpose. Using the -``keys`` option (as a YAML list in the configuration file, or as -space-delimited strings in the command-line), you can extend this behavior -to consider other attributes. - -checksum -~~~~~~~~ - -The ``checksum`` option (default: ``ffmpeg -i {file} -f crc -``) enables the use of -any arbitrary command to compute a checksum of items. It overrides the ``keys`` -option the first time it is run; however, because it caches the resulting checksums -as ``flexattrs`` in the database, you can use -``--keys=name_of_the_checksumming_program any_other_keys`` the second time around. - -copy -~~~~ - -The ``copy`` option (default: ``no``) takes a destination base directory into which -it will copy matched items. - -move -~~~~ - -The ``move`` option (default: ``no``) takes a destination base directory into which -it will move matched items. - -delete -~~~~~~ - -The ``delete`` option (default: ``no``) removes matched items from the library -and from the disk. - -tag -~~~ - -The ``tag`` option (default: ``no``) takes a ``key=value`` string, and adds a new -``key`` attribute with ``value`` value as a flexattr to the database. +- ``album`` lists duplicate albums instead of tracks. + Default: ``no``. +- ``checksum`` enables the use of any arbitrary command to compute a checksum + of items. It overrides the ``keys`` option the first time it is run; however, + because it caches the resulting checksum as ``flexattrs`` in the database, + you can use ``--keys=name_of_the_checksumming_program any_other_keys`` (or + set configuration ``keys``option) the second time around. + Default: ``ffmpeg -i {file} -f crc -``. +- ``copy`` takes a destination base directory into which it will copy matched + items. + Default: ``no``. +- `count` prints a count of duplicate tracks or albums, with ``format`` + hard-coded to ``$albumartist - $album - $title: $count`` or ``$albumartist - + $album: $count`` (for the ``-a`` option). + Default: ``no``. +- ``delete`` removes matched items from the library and from the disk. + Default: ``no`` +- `format` lets you specify a specific format with which to print every track + or album. This uses the same template syntax as beets + ’:doc:`path formats`. The usage is inspired by, and + therefore similar to, the :ref:`list ` command. + Default: :ref:`list_format_item` +- ``full`` lists every track or album that has duplicates, not just the + duplicates themselves. + Default: ``no``. +- ``keys`` defines in which track or album fields duplicates are to be + searched. By default, the plugin uses the musicbrainz track and album IDs for + this purpose. Using the ``keys`` option (as a YAML list in the configuration + file, or as space-delimited strings in the command-line), you can extend this + behavior to consider other attributes. + Default: ``[mb_trackid, mb_albumid]`` +- ``move`` takes a destination base directory into which it will move matched + items. + Default: ``no``. +- `path` is a convenience wrapper for ``-f \$path``. + Default: ``no``. +- ``tag`` takes a ``key=value`` string, and adds a new ``key`` attribute with + ``value`` value as a flexattr to the database. + Default: ``no``. Examples -------- @@ -150,7 +94,8 @@ Print out a unicode histogram of duplicate track years using `spark`_:: beet duplicates -f '$year' | spark ▆▁▆█▄▇▇▄▇▇▁█▇▆▇▂▄█▁██▂█▁▁██▁█▂▇▆▂▇█▇▇█▆▆▇█▇█▇▆██▂▇ -Print out a listing of all albums with duplicate tracks, and respective counts:: +Print out a listing of all albums with duplicate tracks, and respective +counts:: beet duplicates -ac @@ -162,8 +107,8 @@ Get tracks with the same title, artist, and album:: beet duplicates -k title albumartist album -Compute Adler CRC32 or MD5 checksums, storing them as flexattrs, and report back -duplicates based on those values:: +Compute Adler CRC32 or MD5 checksums, storing them as flexattrs, and report +back duplicates based on those values:: beet dup -C 'ffmpeg -i {file} -f crc -' beet dup -C 'md5sum {file}' @@ -181,12 +126,8 @@ Delete items (careful!), if they're Nickelback:: beet duplicates --delete --keys albumartist albumartist:nickelback Tag duplicate items with some flag:: - + beet duplicates --tag dup=1 -TODO ----- - -- better duplicate disambiaguation strategies (eg, based on bitrate, etc) .. _spark: https://github.com/holman/spark diff --git a/docs/plugins/echonest.rst b/docs/plugins/echonest.rst index 1189aca49..e5e033778 100644 --- a/docs/plugins/echonest.rst +++ b/docs/plugins/echonest.rst @@ -41,63 +41,44 @@ algorithms supported by the Echo Nest. Please note that fingerprinting is not required if ``upload`` and ``convert`` is enabled, which is the default (but it can be faster than uploading). +Finally, to use the plugin, enable it in your configuration (see +:ref:`using-plugins`). + .. _pip: http://pip.openplans.org/ .. _FFmpeg: http://ffmpeg.org .. _ENMFP: http://static.echonest.com/ENMFP_codegen.zip .. _Echoprint: http://echoprint.me -Configuring ------------ +Configuration +------------- -Beets includes its own Echo Nest API key, but you can `apply for your own`_ for -free from the Echo Nest. To specify your own API key, add the key to your -:doc:`configuration file ` as the value for ``apikey`` under -the key ``echonest`` like so:: +Available options : - echonest: - apikey: YOUR_API_KEY - -In addition, the ``auto`` config option lets you disable automatic metadata -fetching during import. To do so, add this to your ``config.yaml``:: - - echonest: - auto: no - -The ``echonest`` plugin tries to upload files to the Echo Nest server if it -can not be identified by other means. If you don't want that, disable the -``upload`` config option like so:: - - echonest: - upload: no - -The Echo Nest server only supports a limited range of file formats. The plugin -automatically converts unsupported files to ``ogg``. If you don't want that, -disable the ``convert`` config option like so:: - - echonest: - convert: no - -The Echo Nest server does not allow uploading of files with sizes greater than -50MB. The plugin automatically truncates large files to their first 5 -minutes. If you don't want that, disable the ``truncate`` config option like -so:: - - echonest: - truncate: no - -To enable fingerprinting, you'll need to tell the plugin where to find the -Echoprint or ENMFP codegen binary. Use the ``codegen`` key under the -``echonest`` section like so:: - - echonest: - codegen: /usr/bin/echoprint-codegen +- ``apikey``: set this option to specify your own EchoNest API key. + You can `apply for your own`_ for free from the EchoNest. + Default: beets includes its own Echo Nest API key. +- ``auto``: set it to ``no`` to disable automatic metadata fetching during + import. + Default: ``yes``. +- ``codegen``: Echoprint or ENMFP codegen binary path. + Default: ``None`` +- ``convert``: because the Echo Nest server only supports a limited range of + file formats, the plugin automatically converts unsupported files to ``ogg``. + Default: ``yes``. +- ``truncate``: automatically truncates large files to their first 5 minutes + before uploading them to The Echo Nest server (as files with sizes greater + than 50MB are rejected). + Default: ``yes``. +- ``upload``: send files to the Echo Nest server if it can not be identified by + other means. + Default: ``yes``. .. _apply for your own: http://developer.echonest.com/account/register Running Manually ---------------- -In addition to running automatically on import, the plugin can also be run manually -from the command line. Use the command ``beet echonest [QUERY]`` to fetch -acoustic attributes for albums matching a certain query. +In addition to running automatically on import, the plugin can also be run +manually from the command line. Use the command ``beet echonest [QUERY]`` to +fetch acoustic attributes for albums matching a certain query. diff --git a/docs/plugins/echonest_tempo.rst b/docs/plugins/echonest_tempo.rst index 2436044ab..99ffc3873 100644 --- a/docs/plugins/echonest_tempo.rst +++ b/docs/plugins/echonest_tempo.rst @@ -1,5 +1,5 @@ -EchoNest Tempo Plugin -===================== +Echo Nest Tempo Plugin +====================== .. note:: @@ -16,33 +16,27 @@ field) from the `Echo Nest API`_. Installing Dependencies ----------------------- -This plugin requires the pyechonest library in order to talk to the EchoNest +This plugin requires the pyechonest library in order to talk to the EchoNest API. There are packages for most major linux distributions, you can download the -library from the Echo Nest, or you can install the library from `pip`_, +library from the Echo Nest, or you can install the library from `pip`_, like so:: $ pip install pyechonest .. _pip: http://pip.openplans.org/ -Configuring ------------ +Configuration +------------- -Beets includes its own Echo Nest API key, but you can `apply for your own`_ for -free from the EchoNest. To specify your own API key, add the key to your -:doc:`configuration file ` as the value for ``apikey`` under -the key ``echonest_tempo`` like so:: +Available options: - echonest_tempo: - apikey: YOUR_API_KEY - -In addition, the ``autofetch`` config option lets you disable automatic tempo -fetching during import. To do so, add this to your ``config.yaml``:: - - echonest_tempo: - auto: no +- ``auto``: set to ``no``to disable automatic tempo fetching during import. + Default: ``true``. +- ``apikey``: set this option to specify your own EchoNest API key. + You can `apply for your own`_ for free from the EchoNest. + Default: beets includes its own Echo Nest API key. .. _apply for your own: http://developer.echonest.com/account/register @@ -61,12 +55,12 @@ This behavior can be disabled with the ``autofetch`` config option (see below). Fetching Tempo Manually ----------------------- -The ``tempo`` command provided by this plugin fetches tempos for -items that match a query (see :doc:`/reference/query`). For example, -``beet tempo magnetic fields absolutely cuckoo`` will get the tempo for the -appropriate Magnetic Fields song, ``beet tempo magnetic fields`` will get -tempos for all my tracks by that band, and ``beet tempo`` will get tempos for -my entire library. The tempos will be added to the beets database and, if +The ``tempo`` command provided by this plugin fetches tempos for +items that match a query (see :doc:`/reference/query`). For example, +``beet tempo magnetic fields absolutely cuckoo`` will get the tempo for the +appropriate Magnetic Fields song, ``beet tempo magnetic fields`` will get +tempos for all my tracks by that band, and ``beet tempo`` will get tempos for +my entire library. The tempos will be added to the beets database and, if ``import.write`` is on, embedded into files' metadata. The ``-p`` option to the ``tempo`` command makes it print tempos out to the diff --git a/docs/plugins/embedart.rst b/docs/plugins/embedart.rst index 387d6a3ff..e03a5f929 100644 --- a/docs/plugins/embedart.rst +++ b/docs/plugins/embedart.rst @@ -7,18 +7,14 @@ You might want to embed the album art directly into each file's metadata. While this will take more space than the external-file approach, it is necessary for displaying album art in some media players (iPods, for example). -This plugin was added in beets 1.0b8. +Usage +----- -Embedding Art Automatically ---------------------------- - -To automatically embed discovered album art into imported files, just enable the -plugin (see :doc:`/plugins/index`). You'll also want to enable the +To automatically embed discovered album art into imported files, just enable +the plugin (see :doc:`/plugins/index`). You'll also want to enable the :doc:`/plugins/fetchart` to obtain the images to be embedded. Art will be embedded after each album is added to the library. -This behavior can be disabled with the ``auto`` config option (see below). - .. _image-similarity-check: Image Similarity @@ -40,6 +36,34 @@ number, the more similar the images must be. This feature requires `ImageMagick`_. +Configuration +------------- + +Available options : + +- ``auto`` option lets you disable automatic album art embedding when set to + ``no``. + Default: ``true`` +- ``compare_threshold``: how similar must candidate art be regarding to + embedded art to be written to the file (see :ref:`image-similarity-check`). + Default: ``0`` (disabled). +- ``ifempty``: set to 'yes' to avoid embedding album art for files that already + have one. + Default: ``no``. +- ``maxwidth`` defines a maximum width to downscale images before embedding + them (the original image file is not altered). The resize operation reduces + image width to ``maxwidth`` pixels. The height is recomputed so that the + aspect ratio is preserved. See also :ref:`image-resizing` for further caveats + about image resizing. + Default: ``0`` (disabled). + +Note: ``compare_threshold`` option requires `ImageMagick`_ , ``maxwidth`` +requires `ImageMagick`_ or `PIL`_ + +.. _PIL: http://www.pythonware.com/products/pil/ +.. _ImageMagick: http://www.imagemagick.org/ +.. _PHASH: http://www.fmwconcepts.com/misc_tests/perceptual_hash_test_results_510/ + Manually Embedding and Extracting Art ------------------------------------- @@ -59,31 +83,3 @@ embedded album art: * ``beet clearart QUERY``: removes all embedded images from all items matching the query. (Use with caution!) - -Configuring ------------ - -The ``auto`` option lets you disable automatic album art embedding. -To do so, add this to your ``config.yaml``:: - - embedart: - auto: no - -A maximum image width can be configured as ``maxwidth`` to downscale images -before embedding them (the original image file is not altered). The resize -operation reduces image width to ``maxwidth`` pixels. The height is recomputed -so that the aspect ratio is preserved. `PIL`_ or `ImageMagick`_ is required to -use the ``maxwidth`` config option. See also :ref:`image-resizing` for further -so that the aspect ratio is preserved. - -The ``compare_threshold`` option defines how similar must candidate art be -regarding to embedded art to be written to the file (see -:ref:`image-similarity-check`). The default is 0 (no similarity check). -Requires `ImageMagick`_. - -To avoid embedding album art for files that already have album art, set the -``ifempty`` config option to ``yes``. - -.. _PIL: http://www.pythonware.com/products/pil/ -.. _ImageMagick: http://www.imagemagick.org/ -.. _PHASH: http://www.fmwconcepts.com/misc_tests/perceptual_hash_test_results_510/ diff --git a/docs/plugins/fetchart.rst b/docs/plugins/fetchart.rst index 1aa171dac..e217c804b 100644 --- a/docs/plugins/fetchart.rst +++ b/docs/plugins/fetchart.rst @@ -13,8 +13,8 @@ The plugin uses `requests`_ to fetch album art from the Web. .. _requests: http://docs.python-requests.org/en/latest/ -Fetching Album Art During Import --------------------------------- +Usage +----- When the plugin is enabled, it automatically gets album art for every album you import. @@ -23,11 +23,38 @@ By default, beets stores album art image files alongside the music files for an album in a file called ``cover.jpg``. To customize the name of this file, use the :ref:`art-filename` config option. -To disable automatic art downloading, just put this in your configuration -file:: +Configuration +------------- + +Available options : + +- ``auto``: set it to ``no`` to disable automatic album art fetching during + import. + Default: ``yes``. +- ``cautious``: pick only trusted album arts by ignoring filenames that do not + contain one of ``cover_names`` keywords. + Default: ``no``. +- ``cover_names``: image filenames that contain word(s) of this list will be + picked primarily. + Default: ``['cover', 'front', 'art', 'album', 'folder']``. +- ``google_search``: set it to `yes` gather images from Google Images search. + Default: ``no``. +- ``maxwidth``: maximum image width to downscale fetched images if they are + too big. The resize operation reduces image width to ``maxwidth`` pixels. The + height is recomputed so that the aspect ratio is preserved. +- ``remote_priority``: query remote sources every time and use local image only + as fallback. + Default: ``no``, remote (Web) art sources are only queried if no local art is + found in the filesystem. + +Here's an example that makes plugin select only images that contain *front* or +*back* keywords in their filenames:: fetchart: - auto: no + cautious: true + cover_names: front back + + Manually Fetching Album Art --------------------------- @@ -47,11 +74,6 @@ be processed; otherwise, the command processes every album in your library. Image Resizing -------------- -A maximum image width can be configured as ``maxwidth`` to downscale fetched -images if they are too big. The resize operation reduces image width to -``maxwidth`` pixels. The height is recomputed so that the aspect ratio is -preserved. - Beets can resize images using `PIL`_, `ImageMagick`_, or a server-side resizing proxy. If either PIL or ImageMagick is installed, beets will use those; otherwise, it falls back to the resizing proxy. If the resizing proxy is used, @@ -79,19 +101,6 @@ file whose name contains "cover", "front", "art", "album" or "folder", but in the absence of well-known names, it will use any image file in the same folder as your music files. -You can change the list of filename keywords using the ``cover_names`` config -option. Or, to use *only* filenames containing the keywords and not fall back -to any image, set ``cautious`` to true. For example:: - - fetchart: - cautious: true - cover_names: front back - -By default, remote (Web) art sources are only queried if no local art is found -in the filesystem. To query remote sources every time, set the -``remote_priority`` configuration option to true, which will cause beets to -prefer remote cover art over any local image files. - When you choose to apply changes during an import, beets will search for art as described above. For "as-is" imports (and non-autotagged imports using the ``-A`` flag), beets only looks for art on the local filesystem. @@ -106,11 +115,6 @@ unlikely). .. _Google Images: http://images.google.com/ -To enable gathering art from Google, enable the ``google_search`` option in -your config file:: - - fetchart: - google_search: true Embedding Album Art ------------------- diff --git a/docs/plugins/fromfilename.rst b/docs/plugins/fromfilename.rst index 51cf7ec45..634b49f98 100644 --- a/docs/plugins/fromfilename.rst +++ b/docs/plugins/fromfilename.rst @@ -9,6 +9,4 @@ When you attempt to import a track that's missing a title, this plugin will look at the track's filename and guess its track number, title, and artist. These will be used to search in MusicBrainz and match track ordering. -To use the plugin, just enable it by putting ``fromfilename`` on the -``plugins:`` line in your config file. There are currently no configuration -options. +To use the plugin, enable it in your configuration (see :ref:`using-plugins`). diff --git a/docs/plugins/ftintitle.rst b/docs/plugins/ftintitle.rst index c8bf48f46..4ba4224d9 100644 --- a/docs/plugins/ftintitle.rst +++ b/docs/plugins/ftintitle.rst @@ -1,7 +1,7 @@ FtInTitle Plugin ================ -The ``ftintitle`` plugin automatically moved "featured" artists from the +The ``ftintitle`` plugin automatically move "featured" artists from the ``artist`` field to the ``title`` field. According to `MusicBrainz style`_, featured artists are part of the artist @@ -10,17 +10,30 @@ tracks in your library like "Tellin' Me Things" by the artist "Blakroc feat. RZA". If you prefer to tag this as "Tellin' Me Things feat. RZA" by "Blakroc", then this plugin is for you. -To use the plugin, just enable it and run the command:: +To use the plugin, enable it in your configuration (see :ref:`using-plugins`). + +Configuration +------------- + +Available options : + +- ``auto``: set it to ``no`` to disable plugin during import. + Default: ``yes``. +- ``drop``: remove featured artists entirely instead of adding them to the + title field. + Default: ``no`` + +Running manually +---------------- + +From the command line, type:: $ beet ftintitle [QUERY] The query is optional; if it's left off, the transformation will be applied to your entire collection. -If you prefer to remove featured artists entirely instead of adding them to -the title field, either use the ``-d`` flag to the command or set the -``ftintitle.drop`` config option. - -To disable this plugin on import, set the ``auto`` config option to false. +Use the ``-d``flag to remove featured artists (equivalent of the ``drop`` +option). .. _MusicBrainz style: http://musicbrainz.org/doc/Style diff --git a/docs/plugins/fuzzy.rst b/docs/plugins/fuzzy.rst index 3f4115168..4f5524efd 100644 --- a/docs/plugins/fuzzy.rst +++ b/docs/plugins/fuzzy.rst @@ -1,25 +1,23 @@ Fuzzy Search Plugin =================== -The ``fuzzy`` plugin provides a prefixed query that search you library using +The ``fuzzy`` plugin provides a prefixed query that searches you library using fuzzy pattern matching. This can be useful if you want to find a track with complicated characters in the title. -First, enable the plugin named ``fuzzy`` (see :doc:`/plugins/index`). +First, enable the plugin named ``fuzzy`` (see :ref:`using-plugins`). You'll then be able to use the ``~`` prefix to use fuzzy matching:: $ beet ls '~Vareoldur' Sigur Rós - Valtari - Varðeldur -The plugin provides config options that let you choose the prefix and the -threshold.:: +Configuration +------------- - fuzzy: - threshold: 0.8 - prefix: '@' +Available options : -A threshold value of 1.0 will show only perfect matches and a value of 0.0 -will match everything. - -The default prefix ``~`` needs to be escaped or quoted in most shells. If this -bothers you, you can change the prefix in your config file. +- ``threshold``: a value of 1.0 will show only perfect matches and a value of + 0.0 will match everything. + Default: ``0.7`` +- ``prefix``: character to use to designate fuzzy queries. + Default: ``~`` (needs to be escaped or quoted in most shells) diff --git a/docs/plugins/ihate.rst b/docs/plugins/ihate.rst index 7cb6b4040..8c7631725 100644 --- a/docs/plugins/ihate.rst +++ b/docs/plugins/ihate.rst @@ -6,18 +6,26 @@ import or warn you about them. You specify queries (see :doc:`/reference/query`) and the plugin skips (or warns about) albums or items that match any query. -To use the plugin, first enable it in your configuration (see -:ref:`using-plugins`). Then, add an ``ihate:`` section to your configuration -file:: +To use the plugin, enable it in your configuration (see +:ref:`using-plugins`). + +Configuration +------------- + +Available options : + +- ``skip``: never import matches. Default: ``[]`` +- ``warn``: print a warning message for matches. Default: ``[]`` + + +Here's an example :: ihate: - # Print a warning message for these. warn: - artist:rnb - genre: soul # Only warn about tribute albums in rock genre. - genre:rock album:tribute - # Never import any of this. skip: - genre::russian\srock - genre:polka diff --git a/docs/plugins/importadded.rst b/docs/plugins/importadded.rst index 90101be56..6530e587a 100644 --- a/docs/plugins/importadded.rst +++ b/docs/plugins/importadded.rst @@ -16,10 +16,8 @@ The ``item.added`` field is populated as follows: set to the oldest mtime of the files in the album before they were imported. The mtime of album directories is ignored. -This plugin can optionally be configured to also preserve mtimes:: - - importadded: - preserve_mtimes: yes # default: no +This plugin can optionally be configured to also preserve mtimes using the +``preserve_mtimes`` option. File modification times are preserved as follows: @@ -32,7 +30,15 @@ File modification times are preserved as follows: Note that there is no ``album.mtime`` field in the database and that the mtime of album directories on disk aren't preserved. +Configuration +------------- + +Available option: + +- ``preserve_mtimes``: Default: ``no`` + Reimport -------- -This plugin will skip reimported singleton items and reimported albums and all of their items. +This plugin will skip reimported singleton items and reimported albums and all +of their items. diff --git a/docs/plugins/importfeeds.rst b/docs/plugins/importfeeds.rst index 3d8155e26..f0930aee5 100644 --- a/docs/plugins/importfeeds.rst +++ b/docs/plugins/importfeeds.rst @@ -1,30 +1,41 @@ ImportFeeds Plugin ================== -The ``importfeeds`` plugin helps you keep track of newly imported music in your library. +The ``importfeeds`` plugin helps you keep track of newly imported music in your +library. -To use the plugin, just put ``importfeeds`` on the ``plugins`` line in your -:doc:`configuration file `. Then set a few options under the -``importfeeds:`` section in the config file. +To use the plugin, enable it in your configuration (see :ref:`using-plugins`). -The ``dir`` configuration option can be set to specify another folder -than the default library directory. This is where your playlist will be created. +Configuration +------------- -The ``relative_to`` configuration option can be set to make the m3u paths -relative to another folder than where the playlist is being written. If you're -using importfeeds to generate a playlist for MPD, you should set this to the -root of your music library. +Available options : -The ``absolute_path`` configuration option can be set to use absolute paths -instead of relative paths. Some applications may need this to work properly. +- ``absolute_path`` option can be set to use absolute paths instead of relative + paths. Some applications may need this to work properly. + Default: ``no``. +- ``dir`` option can be set to specify another output folder than the default + library directory. + Default: ``None``. +- ``formats`` option can be set to select desired output type(s): -Four different types of outputs are available. Specify the ones you want to -use by setting the ``formats`` parameter: + - ``m3u``: catalog the imports in a centralized playlist. + - ``m3u_multi``: create a new playlist for each import (uniquely named by + appending the date and track/album name). + - ``link``: create a symlink for each imported item. This is the + recommended setting to propagate beets imports to your iTunes library: just + drag and drop the ``dir`` folder on the iTunes dock icon. + - ``echo``: do not write a playlist file at all, but echo a list of new + file paths to the terminal. -- ``m3u``: catalog the imports in a centralized playlist. By default, the playlist is named ``imported.m3u``. To use a different file, just set the ``m3u_name`` parameter inside the ``importfeeds`` config section. -- ``m3u_multi``: create a new playlist for each import (uniquely named by appending the date and track/album name). -- ``link``: create a symlink for each imported item. This is the recommended setting to propagate beets imports to your iTunes library: just drag and drop the ``dir`` folder on the iTunes dock icon. -- ``echo``: do not write a playlist file at all, but echo a list of new file paths to the terminal. + Default: ``[]``. +- ``m3u_name``: playlist name used by ``m3u`` format. + Default: ``imported.m3u``. +- ``relative_to`` option can be set to make the m3u paths relative to another + folder than where the playlist is being written. If you're using importfeeds + to generate a playlist for MPD, you should set this to the root of your music + library. + Default: ``None``. Here's an example configuration for this plugin:: diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index 6ef0c01ce..6f05827df 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -15,12 +15,19 @@ Using Plugins To use one of the plugins included with beets (see the rest of this page for a list), just use the `plugins` option in your :doc:`config.yaml `: file, like so:: - plugins: inline discogs web + plugins: inline convert web The value for `plugins` can be a space-separated list of plugin names or a YAML list like ``[foo, bar]``. You can see which plugins are currently enabled by typing ``beet version``. +Each plugin has its own set of options that can be defined in a section bearing its name:: + + plugins: inline convert web + + convert: + auto: true + .. toctree:: :hidden: diff --git a/docs/plugins/info.rst b/docs/plugins/info.rst index 7830d61c7..676102688 100644 --- a/docs/plugins/info.rst +++ b/docs/plugins/info.rst @@ -5,7 +5,8 @@ The ``info`` plugin provides a command that dumps the current tag values for any file format supported by beets. It works like a supercharged version of `mp3info`_ or `id3v2`_. -Enable the plugin and then type:: +Enable the plugin in your configuration (see :ref:`using-plugins`) and then + type:: $ beet info /path/to/music.flac diff --git a/docs/plugins/inline.rst b/docs/plugins/inline.rst index 1a7adebe4..99fad299a 100644 --- a/docs/plugins/inline.rst +++ b/docs/plugins/inline.rst @@ -6,9 +6,8 @@ it, you can define template fields in your beets configuration file and refer to them from your template strings in the ``paths:`` section (see :doc:`/reference/config/`). -To use inline field definitions, first enable the plugin by putting ``inline`` -on your ``plugins`` line in your configuration file. Then, make a -``item_fields:`` block in your config file. Under this key, every line defines a +To use the plugin, enable it in your configuration (see :ref:`using-plugins`). +Then, make a `item_fields:`` block in your config file. Under this key, every line defines a new template field; the key is the name of the field (you'll use the name to refer to the field in your templates) and the value is a Python expression or function body. The Python code has all of a track's fields in scope, so you can @@ -42,7 +41,7 @@ a result for the value of the path field, like so:: item_fields: filename: | import os - from beets.util import bytestring_path + from beets.util import bytestring_path return bytestring_path(os.path.basename(path)) You might want to use the YAML syntax for "block literals," in which a leading diff --git a/docs/plugins/keyfinder.rst b/docs/plugins/keyfinder.rst index fc6e28029..15d35a4ed 100644 --- a/docs/plugins/keyfinder.rst +++ b/docs/plugins/keyfinder.rst @@ -3,26 +3,28 @@ Key Finder Plugin The `keyfinder` plugin uses the `KeyFinder`_ program to detect the musical key of track from its audio data and store it in the -`initial_key` field of you database. If enabled, it does so +'initial_key' field of you database. It does so automatically when importing music or through the ``beet keyfinder [QUERY]`` command. -There are a couple of configuration options to customize the behavior of -the plugin. By default they are:: +To use the plugin, enable it in your configuration (see +:ref:`using-plugins`). - keyfinder: - bin: KeyFinder - auto: yes - overwrite: no +Configuration +------------- -* ``bin``: The name of the `KeyFinder` program on your system or +Available options: + +- ``bin``: The name of the `KeyFinder` program on your system or a path to the binary. If you installed the `KeyFinder`_ GUI on a Mac, for example, you want something like ``/Applications/KeyFinder.app/Contents/MacOS/KeyFinder``. -* ``auto``: If set to `yes`, the plugin will analyze every file on + Default: ``KeyFinder``. +- ``auto``: If set to `yes`, the plugin will analyze every file on import. Otherwise, you need to use the ``beet keyfinder`` command - explicitly. -* ``overwrite``: If set to `no`, the import hook and the command will skip - any file that already has an `initial_key` in the database. + explicitly. Default: ``yes``. +- ``overwrite``: If set to ``no``, the import hook and the command will skip + any file that already has an 'initial_key' in the database. + Default: ``no``. .. _KeyFinder: http://www.ibrahimshaath.co.uk/keyfinder/ diff --git a/docs/plugins/lastgenre.rst b/docs/plugins/lastgenre.rst index c2cd59160..069de9efa 100644 --- a/docs/plugins/lastgenre.rst +++ b/docs/plugins/lastgenre.rst @@ -4,30 +4,31 @@ LastGenre Plugin The MusicBrainz database `does not contain genre information`_. Therefore, when importing and autotagging music, beets does not assign a genre. The ``lastgenre`` plugin fetches *tags* from `Last.fm`_ and assigns them as genres -to your albums and items. The plugin is included with beets as of version -1.0b11. +to your albums and items. .. _does not contain genre information: http://musicbrainz.org/doc/General_FAQ#Why_does_MusicBrainz_not_support_genre_information.3F .. _Last.fm: http://last.fm/ +Installation +------------ + The plugin requires `pylast`_, which you can install using `pip`_ by typing:: pip install pylast -After you have pylast installed, enable the plugin by putting ``lastgenre`` on -your ``plugins`` line in :doc:`config file `. +After you have pylast installed, nable the plugin in your configuration (see +:ref:`using-plugins`). + +Usage +----- The plugin chooses genres based on a *whitelist*, meaning that only certain tags can be considered genres. This way, tags like "my favorite music" or "seen live" won't be considered genres. The plugin ships with a fairly extensive -`internal whitelist`_, but you can set your own in the config file using the -``whitelist`` configuration value:: - - lastgenre: - whitelist: /path/to/genres.txt - -…or go for no whitelist altogether by setting the option to `false`. +`internal whitelist`_, but you can set your own in the config file using the +``whitelist`` configuration value or go for no whitelist altogether by setting +the option to `false`. The genre list file should contain one genre per line. Blank lines are ignored. For the curious, the default genre list is generated by a `script that scrapes @@ -38,79 +39,70 @@ Wikipedia`_. .. _script that scrapes Wikipedia: https://gist.github.com/1241307 .. _internal whitelist: https://raw.githubusercontent.com/sampsyo/beets/master/beetsplug/lastgenre/genres.txt -By default, beets will always fetch new genres, even if the files already have -once. To instead leave genres in place in when they pass the whitelist, set -the ``force`` option to `no`. - -If no genre is found, the file will be left unchanged. To instead specify a -fallback genre, use the ``fallback`` configuration option. You can, of -course, use the empty string as a fallback, like so:: - - lastgenre: - fallback: '' - - Canonicalization ----------------- +^^^^^^^^^^^^^^^^ The plugin can also *canonicalize* genres, meaning that more obscure genres can be turned into coarser-grained ones that are present in the whitelist. This works using a tree of nested genre names, represented using `YAML`_, where the leaves of the tree represent the most specific genres. -To enable canonicalization, set the ``canonical`` configuration value:: - - lastgenre: - canonical: true - -Setting this value to `true` will use a built-in canonicalization -tree. You can also set it to a path, just like the ``whitelist`` config value, -to use your own tree. - .. _YAML: http://www.yaml.org/ Genre Source ------------- +^^^^^^^^^^^^ When looking up genres for albums or individual tracks, you can choose whether to use Last.fm tags on the album, the artist, or the track. For example, you -might want all the albums for a certain artist to carry the same genre. Set the -``source`` configuration value to "album", "track", or "artist", like so:: - - lastgenre: - source: artist - +might want all the albums for a certain artist to carry the same genre. The default is "album". When set to "track", the plugin will fetch *both* album-level and track-level genres for your music when importing albums. Multiple Genres ---------------- +^^^^^^^^^^^^^^^ By default, the plugin chooses the most popular tag on Last.fm as a genre. If you prefer to use a *list* of popular genre tags, you can increase the number -of the ``count`` config option:: - - lastgenre: - count: 3 +of the ``count`` config option. Lists of up to *count* genres will then be used instead of single genres. The genres are separated by commas by default, but you can change this with the -``separator`` config option:: - - lastgenre: - separator: ' / ' +``separator`` config option. `Last.fm`_ provides a popularity factor, a.k.a. *weight*, for each tag ranging from 100 for the most popular tag down to 0 for the least popular. The plugin uses this weight to discard unpopular tags. The default is to ignore tags with a weight less then 10. You can change this by setting -the ``min_weight`` config option:: +the ``min_weight`` config option. - lastgenre: - min_weight: 15 +Configuration +------------- +Available options: + +- ``auto``: set it to ``no`` to disable automatic genre fetching during import. + Default: ``yes``. +- ``canonical``: setting this value to ``true`` will use a built-in canonicalization + tree. You can also set it to a path, just like the ``whitelist`` config value, + to use your own tree. Default: ``no`` +- ``count``: number of genres to fetch. Default: ``1`` +- ``fallback``: by default, the file will be left unchanged when no genre is + found. Specify a string if you prefer to use a fallback genre. You can use the + empty string ``''` to reset the genre. Default: ``None`` +- ``force``: by default, beets will always fetch new genres, even if the files already have + once. To instead leave genres in place in when they pass the whitelist, set + the ``force`` option to ``no``. Default: ``yes`` +- ``min_weight``: minimum popularity factor below which genres are discarded. + Default: ``10`` +- ``source``: defines on which entity to perform Last.fm tags lookup. Can be + either ``artist``, ``album`` or ``track``. Default: ``album`` +- ``separator``: genres separator string + Default: ``u', '`` +- ``whitelist``: give it a custom genre list filepath or set it to 'yes' to use + internal whitelist. If set to 'no' then all genres are considered valids. + Default: ``yes`` Running Manually ---------------- diff --git a/docs/plugins/lyrics.rst b/docs/plugins/lyrics.rst index 94e3b704e..ec0ac56d7 100644 --- a/docs/plugins/lyrics.rst +++ b/docs/plugins/lyrics.rst @@ -12,14 +12,36 @@ and, optionally, the Google custom search API. Fetch Lyrics During Import -------------------------- -To automatically fetch lyrics for songs you import, just enable the plugin by -putting ``lyrics`` on your config file's ``plugins`` line (see -:doc:`/plugins/index`). When importing new files, beets will now fetch lyrics -for files that don't already have them. The lyrics will be stored in the beets -database. If the ``import.write`` config option is on, then the lyrics will also -be written to the files' tags. +To automatically fetch lyrics for songs you import, enable the plugin in your +configuration (see :ref:`using-plugins`). +When importing new files, beets will now fetch lyrics for files that don't +already have them. The lyrics will be stored in the beets database. If the +``import.write`` config option is on, then the lyrics will also be written to +the files' tags. -This behavior can be disabled with the ``auto`` config option (see below). + +Configuration +------------- + +Available options : + +- ``auto``: set it to ``no`` to disable automatic lyrics fetching during import. + Default: ``yes``. +- ``fallback``: by default, the file will be left unchanged when no lyrics are + found. Use the empty string ``''`` to reset the genre in such a case. + Default: ``None``; +- ``google_API_key``: your Google API key. + Default: ``None``; +- ``google_engine_ID``: custom search engine to use. + Default: ``009217259823014548361:lndtuqkycfu``, beets custom search engine + that gathers list of sources known to be scrapeable. + +Here's an example of ``config.yaml``:: + + lyrics: + fallback: '' + google_API_key: AZERTYUIOPQSDFGHJKLMWXCVBN1234567890_ab + google_engine_ID: 009217259823014548361:lndtuqkycfu Fetching Lyrics Manually @@ -39,26 +61,8 @@ console so you can view the fetched (or previously-stored) lyrics. The ``-f`` option forces the command to fetch lyrics, even for tracks that already have lyrics. - -Configuring ------------ - -To disable automatic lyric fetching during import, set the ``auto`` option to -false, like so:: - - lyrics: - auto: no - -By default, if no lyrics are found, the file will be left unchanged. To -specify a placeholder for the lyrics tag when none are found, use the -``fallback`` configuration option:: - - lyrics: - fallback: 'No lyrics found' - .. _activate-google-custom-search: - Activate Google custom search ------------------------------ @@ -78,12 +82,6 @@ default, beets use a list of sources known to be scrapeable. .. _define a custom search engine: http://www.google.com/cse/all -Here's an example of ``config.yaml``:: - - lyrics: - google_API_key: AZERTYUIOPQSDFGHJKLMWXCVBN1234567890_ab - google_engine_ID: 009217259823014548361:lndtuqkycfu - Note that the Google custom search API is limited to 100 queries per day. After that, the lyrics plugin will fall back on its other data sources. diff --git a/docs/plugins/mbcollection.rst b/docs/plugins/mbcollection.rst index 20b795732..615f1a4f6 100644 --- a/docs/plugins/mbcollection.rst +++ b/docs/plugins/mbcollection.rst @@ -6,7 +6,8 @@ maintain your `music collection`_ list there. .. _music collection: http://musicbrainz.org/doc/Collections -To begin, just enable the ``mbcollection`` plugin (see :doc:`/plugins/index`). +To begin, just enable the ``mbcollection`` plugin in your +configuration (see :ref:`using-plugins`). Then, add your MusicBrainz username and password to your :doc:`configuration file ` under a ``musicbrainz`` section:: @@ -19,16 +20,12 @@ command automatically adds all of your albums to the first collection it finds. If you don't have a MusicBrainz collection yet, you may need to add one to your profile first. +Configuration +------------- + + Automatically Update on Import ------------------------------ -You can also configure the plugin to automatically amend your MusicBrainz -collection whenever you import a new album. To do this, first enable the -plugin and add your MusicBrainz account as above. Then, add ``mbcollection`` -section and enable the enable ``auto`` flag therein:: - - mbcollection: - auto: yes - -During future imports, your default collection will be updated with each -imported album. +mbcollection: if set to ``yes``, the plugin will automatically amend your +MusicBrainz collection whenever you import a new album. Default: ``false`` diff --git a/docs/plugins/mbsync.rst b/docs/plugins/mbsync.rst index 4bb3da32f..5497d93f0 100644 --- a/docs/plugins/mbsync.rst +++ b/docs/plugins/mbsync.rst @@ -15,9 +15,9 @@ configuration. Usage ----- -Enable the plugin and then run ``beet mbsync QUERY`` to fetch updated metadata -for a part of your collection (or omit the query to run over your whole -library). +Enable the plugin in your configuration (see :ref:`using-plugins`) and then +run ``beet mbsync QUERY`` to fetch updated metadata for a part of your +collection (or omit the query to run over your whole library). This plugin treats albums and singletons (non-album tracks) separately. It first processes all matching singletons and then proceeds on to full albums. diff --git a/docs/plugins/missing.rst b/docs/plugins/missing.rst index c128b84b8..7cac8cbd6 100644 --- a/docs/plugins/missing.rst +++ b/docs/plugins/missing.rst @@ -7,58 +7,45 @@ tracks are missing. Listing missing files requires one network call to MusicBrainz. Merely counting missing files avoids any network calls. -Installation ------------- - -Enable the plugin by putting ``missing`` on your ``plugins`` line in -:doc:`config file `:: - - plugins: - missing - ... - -Configuration -------------- +Usage +------ +Add the ``missing`` plugin to your configuration (see :ref:`using-plugins`). By default, the ``beet missing`` command lists the names of tracks that your -library is missing from each album. You can customize the output format, count +library is missing from each album. +You can customize the output format, count the number of missing tracks per album, or total up the number of missing -tracks over your whole library. These options can either be specified in the -config file:: - - missing: - format: $albumartist - $album - $title - count: no - total: no - -or on the command-line:: +tracks over your whole library, using command-line switches :: -f FORMAT, --format=FORMAT print with custom FORMAT -c, --count count missing tracks per album -t, --total count total of missing tracks + ... or by editing corresponding options. -format -~~~~~~ +Configuration +------------- -The ``format`` option (default: :ref:`list_format_item`) lets you specify a -specific format with which to print every track. This uses the same template -syntax as beets’ :doc:`path formats `. The usage is -inspired by, and therefore similar to, the :ref:`list ` command. +Available options : -count -~~~~~ +- ``count`` prints a count of missing tracks per album, with ``format`` + defaulting to ``$albumartist - $album: $missing``. + Default: ``no``. +- ``format`` lets you specify a specific format with which to print every + track. This uses the same template syntax as beets’ + :doc:`path formats `. The usage is inspired by, and + therefore similar to, the :ref:`list ` command. + Default: :ref:`list_format_item`. +- ``total` prints a single count of missing tracks in all albums. + Default: ``false``. -The ``count`` option (default: false) prints a count of missing tracks -per album, with ``format`` defaulting to ``$albumartist - $album: -$missing``. +Here's an example :: -total -~~~~~ - -The ``total`` option (default: false) prints a single -count of missing tracks in all albums + missing: + format: $albumartist - $album - $title + count: no + total: no Template Fields --------------- @@ -94,9 +81,4 @@ Call this plugin from other beet commands:: beet ls -a -f '$albumartist - $album: $missing' -TODO ----- - -- Add caching. - .. _spark: https://github.com/holman/spark diff --git a/docs/plugins/mpdstats.rst b/docs/plugins/mpdstats.rst index 6d71de6b9..3e2d7f207 100644 --- a/docs/plugins/mpdstats.rst +++ b/docs/plugins/mpdstats.rst @@ -21,49 +21,38 @@ Install the library from `pip`_, like so:: $ pip install python-mpd +Add the ``mpdstats`` plugin to your configuration (see :ref:`using-plugins`). + .. _pip: http://www.pip-installer.org/ -Configuring ------------ - -To use it, enable it in your ``config.yaml`` by putting ``mpdstats`` on your -``plugins`` line. Then, you'll probably want to configure the specifics of -your MPD server. You can do that using an ``mpd:`` section in your -``config.yaml``, which looks like this:: - - mpd: - host: localhost - port: 6600 - password: seekrit - -If your MPD library is at another location then the beets library (e.g., -because one is mounted on a NFS share), you can specify the -``music_directory`` in the config like this:: - - mpdstats: - music_directory: /PATH/TO/YOUR/FILES - -If you don't want the plugin to update the rating, you can disable it with:: - - mpdstats: - rating: False - -If you want to change the way the rating is calculated, you can set the -``rating_mix`` option like this:: - - mpdstats: - rating_mix: 1.0 - -For details, see below. - - Usage ----- -Now use the ``mpdstats`` command to fire it up:: +Use the ``mpdstats`` command to fire it up:: $ beet mpdstats +Configuration +------------- + +Available options : + +- ``host``: mpd server name. + Default: ``localhost``. +- ``music_directory``: if your MPD library is at another location than the + beets library (e.g., because one is mounted on a NFS share), specify the path + here. + By default it uses beets library directory. +- ``password``: mpd server password. + Default: ``u''`` +- ``port``: mpd server port. + Default: ``6600``. +- ``rating``: set it to ``no`` if you don't want the plugin to update the + rating. + Default: ``yes`` +- ``rating_mix``: change it to tune the way rating is calculated. See below for + details. + Default: ``0.75`` A Word on Ratings ----------------- diff --git a/docs/plugins/mpdupdate.rst b/docs/plugins/mpdupdate.rst index b153dde0c..f16d5ffdd 100644 --- a/docs/plugins/mpdupdate.rst +++ b/docs/plugins/mpdupdate.rst @@ -6,9 +6,9 @@ update `MPD`_'s index whenever you change your beets library. .. _MPD: http://www.musicpd.org/ -To use it, enable it in your ``config.yaml`` by putting ``mpdupdate`` on your -``plugins`` line. Then, you'll probably want to configure the specifics of your -MPD server. You can do that using an ``mpd:`` section in your ``config.yaml``, +To use it, enable it in your configuration (see :ref:`using-plugins`). +Then, you'll probably want to configure the specifics of your MPD server. +You can do that using an ``mpd:`` section in your ``config.yaml``, which looks like this:: mpd: @@ -22,3 +22,15 @@ If you want to communicate with MPD over a Unix domain socket instead over TCP, just give the path to the socket in the filesystem for the ``host`` setting. (Any ``host`` value starting with a slash or a tilde is interpreted as a domain socket.) + +Configuration +------------- + +Available options : + +- ``host``: mpd server name. + Default: ``localhost``. +- ``password``: mpd server password. + Default: ``u''`` +- ``port``: mpd server port. + Default: ``6600``. diff --git a/docs/plugins/play.rst b/docs/plugins/play.rst index e9303a183..26182e18f 100644 --- a/docs/plugins/play.rst +++ b/docs/plugins/play.rst @@ -4,6 +4,9 @@ Play Plugin The ``play`` plugin allows you to pass the results of a query to a music player in the form of an m3u playlist. +Usage +----- + To use the plugin, enable it in your configuration (see :ref:`using-plugins`). Then use it by invoking the ``beet play`` command with a query. The command will create a temporary m3u file and open it using an @@ -23,15 +26,19 @@ would on the command-line):: play: command: /usr/bin/command --option1 --option2 some_other_option -You can configure the plugin to emit relative paths. Use the ``relative_to`` -configuration option:: - - play: - relative_to: /my/music/folder - -When using the ``-a`` option, the m3u will have the paths to each track on -the matched albums. If you wish to have folders instead, you can change that -by setting ``use_files: False`` in your configuration file. - Enable beets' verbose logging to see the command's output if you need to debug. + +Configuration +------------- + +- ``command``: command used to open the playlist. + Default: ``open`` on OS X, ``xdg-open`` on other Unixes and ``start`` on + Windows. +- ``relative_to``: set that option if you want to emit relative paths by giving + the refefence folder (eg '/my/music/folder') + Default: ``None`` +- ``use_folders``: when using the ``-a`` option, the m3u will have the paths to + each track on the matched albums. Set it to ``yes`` to store paths to folders + instead. + Default: ``no`` diff --git a/docs/plugins/random.rst b/docs/plugins/random.rst index 59e4b9483..5b04d5ab7 100644 --- a/docs/plugins/random.rst +++ b/docs/plugins/random.rst @@ -5,8 +5,8 @@ The ``random`` plugin provides a command that randomly selects tracks or albums from your library. This can be helpful if you need some help deciding what to listen to. -First, enable the plugin named ``random`` (see :doc:`/plugins/index`). You'll then -be able to use the ``beet random`` command:: +First, enable the plugin named ``random`` (see :ref:`using-plugins`). You'll +then be able to use the ``beet random`` command:: $ beet random Aesop Rock - None Shall Pass - The Harbor Is Yours diff --git a/docs/plugins/replaygain.rst b/docs/plugins/replaygain.rst index 382f3645e..0ddfed2ae 100644 --- a/docs/plugins/replaygain.rst +++ b/docs/plugins/replaygain.rst @@ -65,31 +65,35 @@ you can configure the path explicitly like so:: Configuration ------------- -Available configuration options for the ``replaygain`` section in your -configuration file include: +Available options : -* **overwrite**: By default, files that already have ReplayGain tags will not - be re-analyzed. If you want to analyze *every* file on import, you can set - the ``overwrite`` option for the plugin in your :doc:`configuration file - `, like so:: - replaygain: - overwrite: yes +- ``auto``: set it to ``no`` to disable replaygain analysis during import. + Default: ``yes``. +- ``backend``: which backend to use for ReplayGain analysis. + Must be one of ``gstreamer`` or ``command``. + Default: ``command`` +- ``overwrite``: by default, files that already have ReplayGain tags will not + be re-analyzed. Set to ``yes`` if you want to analyze *every* file on import. + Default: ``no``. +- ``targetlevel``: specify a number of decibels for the target loudness level + Default: ``89`` -* **targetlevel**: The target loudness level can be modified to any number of - decibels with the ``targetlevel`` option (default: 89 dB). + These options only work with the "command" backend: -These options only work with the "command" backend: - -* **apply**: If you use a player that does not support ReplayGain +- ``apply``: if you use a player that does not support ReplayGain specifications, you can force the volume normalization by applying the gain to the file via the ``apply`` option. This is a lossless and reversible operation with no transcoding involved. -* **noclip**: The use of ReplayGain can cause clipping if the average volume +- ``command``: use it to explicitely enter path to ``mp3gain`` or ``aacgain`` + executable, if beets cannot find it by itself. + For example: '/Applications/MacMP3Gain.app/Contents/Resources/aacgain' + Default: ``u''`` +- ``noclip``: the use of ReplayGain can cause clipping if the average volume of a song is below the target level. By default, a "prevent clipping" option named ``noclip`` is enabled to reduce the amount of ReplayGain adjustment to whatever amount would keep clipping from occurring. - + Default: ``yes``. Manual Analysis --------------- diff --git a/docs/plugins/rewrite.rst b/docs/plugins/rewrite.rst index d3151bac2..995783d55 100644 --- a/docs/plugins/rewrite.rst +++ b/docs/plugins/rewrite.rst @@ -6,12 +6,11 @@ path formats. Specifically, it is intended to let you *canonicalize* names such as artists: for example, perhaps you want albums from The Jimi Hendrix Experience to be sorted into the same folder as solo Hendrix albums. -To use field rewriting, first enable the plugin by putting ``rewrite`` on your -``plugins`` line. Then, make a ``rewrite:`` section in your config file to -contain your rewrite rules. Each rule consists of a field name, a regular -expression pattern, and a replacement value. Rules are written ``fieldname -regex: replacement``. For example, this line implements the Jimi Hendrix -example above:: +To use field rewriting, first enable the plugin (see :ref:`using-plugins`). +Then, make a ``rewrite:`` section in your config file to contain your rewrite +rules. Each rule consists of a field name, a regular expression pattern, and a +replacement value. Rules are written ``fieldname regex: replacement``. +For example, this line implements the Jimi Hendrix example above:: rewrite: artist The Jimi Hendrix Experience: Jimi Hendrix diff --git a/docs/plugins/scrub.rst b/docs/plugins/scrub.rst index c16a995c6..becb21d06 100644 --- a/docs/plugins/scrub.rst +++ b/docs/plugins/scrub.rst @@ -11,7 +11,7 @@ Automatic Scrubbing ------------------- To automatically remove files' tags before writing new ones, just -enable the plugin (see :doc:`/plugins/index`). When importing new files (with +enable the plugin (see :ref:`using-plugins`). When importing new files (with ``import.write`` turned on) or modifying files' tags with the ``beet modify`` command, beets will first strip all types of tags entirely and then write the database-tracked metadata to the file. @@ -31,11 +31,10 @@ The ``-W`` (or ``--nowrite``) option causes the command to just remove tags but not restore any information. This will leave the files with no metadata whatsoever. -Configuring ------------ +Configuration +------------- -The plugin has one configuration option, ``auto``, which lets you disable -automatic metadata stripping. To do so, add this to your ``config.yaml``:: +Available option : - scrub: - auto: no +- ``auto``: set it to ``no`` to disable metadata stripping during import. + Default: ``yes``. diff --git a/docs/plugins/smartplaylist.rst b/docs/plugins/smartplaylist.rst index 496558fa8..789b7c051 100644 --- a/docs/plugins/smartplaylist.rst +++ b/docs/plugins/smartplaylist.rst @@ -7,9 +7,8 @@ created to work well with `MPD's`_ playlist functionality. .. _MPD's: http://www.musicpd.org/ -To use it, enable the plugin by putting ``smartplaylist`` in the ``plugins`` -section in your ``config.yaml``. Then configure your smart playlists like the -following example:: +To use it, enable the plugin in your configuration (see :ref:`using-plugins`). +Then configure your smart playlists like the following example:: smartplaylist: relative_to: ~/Music @@ -21,12 +20,6 @@ following example:: - name: beatles.m3u query: 'artist:Beatles' -If you intend to use this plugin to generate playlists for MPD, you should set -``relative_to`` to your MPD music directory (by default, ``relative_to`` is -``None``, and the absolute paths to your music files will be generated). - -``playlist_dir`` is where the generated playlist files will be put. - You can generate as many playlists as you want by adding them to the ``playlists`` section, using beets query syntax (see :doc:`/reference/query`) for ``query`` and the file name to be generated for @@ -60,8 +53,7 @@ to albums that have a ``for_travel`` extensible field set to 1:: query: 'for_travel:1' By default, all playlists are automatically regenerated after every beets -command that changes the library database. This can be disabled by specifying -``auto: no``. To force regeneration, you can invoke it manually from the +command that changes the library database. To force regeneration, you can invoke it manually from the command line:: $ beet splupdate @@ -72,3 +64,18 @@ You can also use this plugin together with the :doc:`mpdupdate`, in order to automatically notify MPD of the playlist change, by adding ``mpdupdate`` to the ``plugins`` line in your config file *after* the ``smartplaylist`` plugin. + +Configuration +------------- + +Available options : + +- ``auto``: set it to ``no`` to tell beets to stop regenerate the playlist + after every database change. + Default: ``yes`` +- ``playlist_dir``: where the generated playlist files will be put. + Default: ``u'.'`` +- ``relative_to``: if you intend to use this plugin to generate playlists for + MPD, make it points to your MPD music directory. + Default: ``None``, which means that absolute paths to your music files will + be generated. diff --git a/docs/plugins/spotify.rst b/docs/plugins/spotify.rst index 78f48e720..14ef72c8a 100644 --- a/docs/plugins/spotify.rst +++ b/docs/plugins/spotify.rst @@ -37,27 +37,40 @@ Command-line options include: * ``--show-failures`` or ``-f``: List the tracks that did not match a Spotify ID. -Configuring ------------ +Configuration +------------- The default options should work as-is, but there are some options you can put in config.yaml: -* ``mode``: See the section below on modes. -* ``region_filter``: Use the 2-character country abbreviation to limit results +* ``mode``: one of the following : + + - "list": the default mode is to print out the playlist as a list of links. + This list can then be pasted in to a new or existing Spotify playlist. + - "open": This mode actually sends a link to your default browser with + instructions to open Spotify with the playlist you created. Until this + has been tested on all platforms, it will remain optional. + + Default: ``list``. +* ``region_filter``: use the 2-character country abbreviation to limit results to that market. -* ``show_failures``: Show the artist/album/track for each lookup that does not + Default: ``None`` +* ``show_failures``: qhow the artist/album/track for each lookup that does not return a Spotify ID (and therefore cannot be added to a playlist). -* ``tiebreak``: How to choose the track if there is more than one identical + Default: ``no`` +* ``tiebreak``: how to choose the track if there is more than one identical result. For example, there might be multiple releases of the same album. Currently, this defaults to "popularity", "first" simply chooses the first in the list returned by Spotify. -* ``regex``: An array of regex transformations to perform on the + Default: ``popularity`` +* ``regex``: an array of regex transformations to perform on the track/album/artist fields before sending them to Spotify. Can be useful for changing certain abbreviations, like ft. -> feat. See the examples below. -* ``artist_field`` / ``album_field`` / ``track_field``: These allow the user + Default: ``[]`` +* ``artist_field`` / ``album_field`` / ``track_field``: these allow the user to choose a different field to send to Spotify when looking up the track, album and artist. Most users will not want to change this. + Example Configuration --------------------- @@ -96,12 +109,3 @@ Example Configuration } ] -Spotify Plugin Modes ---------------------- - -* ``list``: The default mode is to print out the playlist as a list of links. - This list can then be pasted in to a new or existing Spotify playlist. -* ``open``: This mode actually sends a link to your default browser with - instructions to open Spotify with the playlist you created. Until this has - been tested on all platforms, it will remain optional. - diff --git a/docs/plugins/the.rst b/docs/plugins/the.rst index 4d807e113..493e79493 100644 --- a/docs/plugins/the.rst +++ b/docs/plugins/the.rst @@ -2,39 +2,41 @@ The Plugin ========== The ``the`` plugin allows you to move patterns in path formats. It's suitable, -for example, for moving articles from string start to the end. This is useful -for quick search on filesystems and generally looks good. Plugin DOES NOT -change tags. By default plugin supports English "the, a, an", but custom +for example, for moving articles from string start to the end. This is useful +for quick search on filesystems and generally looks good. Plugin DOES NOT +change tags. By default plugin supports English "the, a, an", but custom regexp patterns can be added by user. How it works:: The Something -> Something, The A Band -> Band, A An Orchestra -> Orchestra, An -To use plugin, enable it by including ``the`` into ``plugins`` line of your -beets config. The plugin provides a template function called ``%the`` for use -in path format expressions:: +Enable the plugin (see :doc:`/plugins/index`) and then make use of a template +function called ``%the`` for use in path format expressions:: paths: default: %the{$albumartist}/($year) $album/$track $title The default configuration moves all English articles to the end of the string, -but you can override these defaults to make more complex changes:: +but you can override these defaults to make more complex changes. - the: - # handle "The" (on by default) - the: yes - # handle "A/An" (on by default) - a: yes - # format string, {0} - part w/o article, {1} - article - # spaces already trimmed from ends of both parts - # default is '{0}, {1}' - format: '{0}, {1}' - # strip instead of moving to the end, default is off - strip: no - # custom regexp patterns, space-separated - patterns: ... +Configuration +------------- + +Available options: + +- ``a``: handle "A/An" moves + Default: ``yes`` +- ``format``: format string with *{0}: part w/o article* and *{1} - article*. + Spaces are already trimmed from ends of both parts. + Default: ``u'{0}, {1}'`` +- ``strip``: + Default: ``no`` +- ``patterns``: custom regexp patterns, space-separated. Custom patterns are + case-insensitive regular expressions. Patterns can be matched anywhere in the + string (not just the beginning), so use ``^`` if you intend to match leading + words. + Default: ``[]`` +- ``the``: handle "The" moves + Default: ``yes`` -Custom patterns are case-insensitive regular expressions. Patterns can be -matched anywhere in the string (not just the beginning), so use ``^`` if you -intend to match leading words. diff --git a/docs/plugins/web.rst b/docs/plugins/web.rst index f10142cc0..59a153dc2 100644 --- a/docs/plugins/web.rst +++ b/docs/plugins/web.rst @@ -20,8 +20,7 @@ flask``. .. _Flask: http://flask.pocoo.org/ -Put ``web`` on your ``plugins`` line in your configuration file to enable the -plugin. +Finally, enable the plugin in your configuration (see :ref:`using-plugins`). Run the Server -------------- @@ -50,6 +49,16 @@ Type queries into the little search box. Double-click a track to play it with .. _HTML5 Audio: http://www.w3.org/TR/html-markup/audio.html +Configuration +------------- + +Available options : + +- ``host``: server hostname + Default: ``u''`` +- ``port``: server port + Default: `8337` + Implementation -------------- diff --git a/docs/plugins/zero.rst b/docs/plugins/zero.rst index 8704d3d8e..81eaacedb 100644 --- a/docs/plugins/zero.rst +++ b/docs/plugins/zero.rst @@ -4,14 +4,18 @@ Zero Plugin The ``zero`` plugin allows you to null fields in files' metadata tags. Fields can be nulled unconditionally or conditioned on a pattern match. For example, the plugin can strip useless comments like "ripped by MyGreatRipper." This -plugin only affects files' tags; the beets database is unchanged. +plugin only affects files' tags ; the beets database is left unchanged. -To use the plugin, enable it by including ``zero`` in the ``plugins`` line of -your configuration file. To configure the plugin, use a ``zero:`` section in -your configuration file. Set ``fields`` to the (whitespace-separated) list of -fields to change. You can get the list of available fields by running ``beet -fields``. To conditionally filter a field, use ``field: [regexp, regexp]`` to -specify regular expressions. +To use the plugin, enable the plugin in your configuration (see :ref:`using-plugins`). + +Configuration +------------- + +Available option : + +- ``fields``: whitespace-separated list of fields to change. You can get the + list of available fields by running ``beet fields``. To conditionally filter + a field, use ``field: [regexp, regexp]`` to specify regular expressions. For example:: From 2cd76b67143de797438ec689fd1cd515b8ad3e5b Mon Sep 17 00:00:00 2001 From: Fabrice Laporte Date: Tue, 28 Oct 2014 23:23:10 +0100 Subject: [PATCH 02/15] docs: add plugin name in "how to configure" sentences --- docs/plugins/beatport.rst | 2 +- docs/plugins/bpd.rst | 2 +- docs/plugins/bpm.rst | 2 +- docs/plugins/bucket.rst | 2 +- docs/plugins/chroma.rst | 6 +-- docs/plugins/convert.rst | 2 +- docs/plugins/discogs.rst | 2 +- docs/plugins/duplicates.rst | 2 +- docs/plugins/echonest.rst | 2 +- docs/plugins/echonest_tempo.rst | 67 --------------------------------- docs/plugins/embedart.rst | 2 +- docs/plugins/fetchart.rst | 2 +- docs/plugins/fromfilename.rst | 3 +- docs/plugins/ftintitle.rst | 3 +- docs/plugins/fuzzy.rst | 2 +- docs/plugins/ihate.rst | 2 +- docs/plugins/importadded.rst | 2 +- docs/plugins/importfeeds.rst | 3 +- docs/plugins/info.rst | 4 +- docs/plugins/inline.rst | 3 +- docs/plugins/keyfinder.rst | 2 +- docs/plugins/lastgenre.rst | 4 +- docs/plugins/lyrics.rst | 4 +- docs/plugins/mbsync.rst | 4 +- docs/plugins/missing.rst | 2 +- docs/plugins/mpdstats.rst | 2 +- docs/plugins/mpdupdate.rst | 6 ++- docs/plugins/play.rst | 2 +- docs/plugins/replaygain.rst | 4 +- docs/plugins/rewrite.rst | 3 +- docs/plugins/scrub.rst | 2 +- docs/plugins/smartplaylist.rst | 3 +- docs/plugins/spotify.rst | 4 +- docs/plugins/the.rst | 4 +- docs/plugins/types.rst | 4 +- docs/plugins/web.rst | 3 +- docs/plugins/zero.rst | 3 +- 37 files changed, 57 insertions(+), 114 deletions(-) delete mode 100644 docs/plugins/echonest_tempo.rst diff --git a/docs/plugins/beatport.rst b/docs/plugins/beatport.rst index 539c80ffb..b10ee8c59 100644 --- a/docs/plugins/beatport.rst +++ b/docs/plugins/beatport.rst @@ -18,7 +18,7 @@ both MusicBrainz and (to a lesser degree) Discogs show no matches. Installation ------------ -To use the plugin, first enable it in your configuration (see +To use the ``beatport`` plugin, first enable it in your configuration (see :ref:`using-plugins`). Then, install the `requests`_ library (which we need for querying the Beatport API) by typing:: diff --git a/docs/plugins/bpd.rst b/docs/plugins/bpd.rst index 846d4638e..2af13152f 100644 --- a/docs/plugins/bpd.rst +++ b/docs/plugins/bpd.rst @@ -41,7 +41,7 @@ installing GStreamer plugins. Usage ----- -To use the plugin, first enable it in your configuration (see +To use the ``bpd`` plugin, first enable it in your configuration (see :ref:`using-plugins`). Then, you can run BPD by invoking:: diff --git a/docs/plugins/bpm.rst b/docs/plugins/bpm.rst index 4494106dd..ce1f62298 100644 --- a/docs/plugins/bpm.rst +++ b/docs/plugins/bpm.rst @@ -7,7 +7,7 @@ tapping out the beat on your keyboard. Usage ----- -To use the plugin, first enable it in your configuration (see +To use the ``bpm`` plugin, first enable it in your configuration (see :ref:`using-plugins`). Then, play a song you want to measure in your favorite media player and type:: diff --git a/docs/plugins/bucket.rst b/docs/plugins/bucket.rst index 43ffeec55..9992661e4 100644 --- a/docs/plugins/bucket.rst +++ b/docs/plugins/bucket.rst @@ -7,7 +7,7 @@ The ``bucket`` plugin groups your files into buckets folders representing smaller subfolders by grouping albums or artists alphabetically (e.g. *A-F*, *G-M*, *N-Z*). -To use the plugin, first enable it in your configuration (see +To use the ``bucket`` plugin, first enable it in your configuration (see :ref:`using-plugins`). The plugin provides a :ref:`template function ` called ``%bucket`` for use in path format expressions:: diff --git a/docs/plugins/chroma.rst b/docs/plugins/chroma.rst index 4603ee3de..3640e642b 100644 --- a/docs/plugins/chroma.rst +++ b/docs/plugins/chroma.rst @@ -90,9 +90,9 @@ standard set of Gstreamer plugins. For example, on Ubuntu, install the packages Usage ----- -Once you have all the dependencies sorted out, enable the plugin in your -configuration (see :ref:`using-plugins`) to benefit from fingerprinting the -next time you run ``beet import``. +Once you have all the dependencies sorted out, enable the ``chroma`` plugin in +your configuration (see :ref:`using-plugins`) to benefit from fingerprinting +the next time you run ``beet import``. You can also use the ``beet fingerprint`` command to generate fingerprints for items already in your library. (Provide a query to fingerprint a subset of your diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst index ee99e15a6..7b3a0c9fb 100644 --- a/docs/plugins/convert.rst +++ b/docs/plugins/convert.rst @@ -10,7 +10,7 @@ line. Installation ------------ -To use the plugin, first enable it in your configuration (see +To use the ``chroma`` plugin, first enable it in your configuration (see :ref:`using-plugins`). By default, the plugin depends on `FFmpeg`_ to transcode the audio, so you might want to install it. diff --git a/docs/plugins/discogs.rst b/docs/plugins/discogs.rst index 912aea7be..35fcaf455 100644 --- a/docs/plugins/discogs.rst +++ b/docs/plugins/discogs.rst @@ -9,7 +9,7 @@ include matches from the `Discogs`_ database. Installation ------------ -To use the plugin, first enable it in your configuration (see +To use the ``discogs`` plugin, first enable it in your configuration (see :ref:`using-plugins`). Then, install the `discogs-client`_ library by typing:: pip install discogs-client diff --git a/docs/plugins/duplicates.rst b/docs/plugins/duplicates.rst index eca009b5d..b5f0e32a0 100644 --- a/docs/plugins/duplicates.rst +++ b/docs/plugins/duplicates.rst @@ -7,7 +7,7 @@ and lists duplicate tracks or albums in your collection. Usage ----- -To use the plugin, first enable it in your configuration (see +To use the ``duplicates`` plugin, first enable it in your configuration (see :ref:`using-plugins`). By default, the ``beet duplicates`` command lists the names of tracks diff --git a/docs/plugins/echonest.rst b/docs/plugins/echonest.rst index e5e033778..e154a8816 100644 --- a/docs/plugins/echonest.rst +++ b/docs/plugins/echonest.rst @@ -41,7 +41,7 @@ algorithms supported by the Echo Nest. Please note that fingerprinting is not required if ``upload`` and ``convert`` is enabled, which is the default (but it can be faster than uploading). -Finally, to use the plugin, enable it in your configuration (see +Finally, enable the ``echonest`` plugin in your configuration (see :ref:`using-plugins`). .. _pip: http://pip.openplans.org/ diff --git a/docs/plugins/echonest_tempo.rst b/docs/plugins/echonest_tempo.rst deleted file mode 100644 index 99ffc3873..000000000 --- a/docs/plugins/echonest_tempo.rst +++ /dev/null @@ -1,67 +0,0 @@ -Echo Nest Tempo Plugin -====================== - -.. note:: - - A newer :doc:`echonest` is available that supersedes this plugin. In - addition to the tempo, the new plugin can fetch the Echo Nest's full - complement of acoustic attributes. This older tempo-specific plugin is - **deprecated**. - -The ``echonest_tempo`` plugin fetches and stores a track's tempo (the "bpm" -field) from the `Echo Nest API`_. - -.. _Echo Nest API: http://developer.echonest.com/ - -Installing Dependencies ------------------------ - -This plugin requires the pyechonest library in order to talk to the EchoNest -API. - -There are packages for most major linux distributions, you can download the -library from the Echo Nest, or you can install the library from `pip`_, -like so:: - - $ pip install pyechonest - -.. _pip: http://pip.openplans.org/ - -Configuration -------------- - -Available options: - -- ``auto``: set to ``no``to disable automatic tempo fetching during import. - Default: ``true``. -- ``apikey``: set this option to specify your own EchoNest API key. - You can `apply for your own`_ for free from the EchoNest. - Default: beets includes its own Echo Nest API key. - -.. _apply for your own: http://developer.echonest.com/account/register - -Fetch Tempo During Import -------------------------- - -To automatically fetch the tempo for songs you import, just enable the plugin -by putting ``echonest_tempo`` on your config file's ``plugins`` line (see -:doc:`/plugins/index`). When importing new files, beets will now fetch the -tempo for files that don't already have them. The bpm field will be stored in -the beets database. If the ``import.write`` config option is on, then the tempo -will also be written to the files' tags. - -This behavior can be disabled with the ``autofetch`` config option (see below). - -Fetching Tempo Manually ------------------------ - -The ``tempo`` command provided by this plugin fetches tempos for -items that match a query (see :doc:`/reference/query`). For example, -``beet tempo magnetic fields absolutely cuckoo`` will get the tempo for the -appropriate Magnetic Fields song, ``beet tempo magnetic fields`` will get -tempos for all my tracks by that band, and ``beet tempo`` will get tempos for -my entire library. The tempos will be added to the beets database and, if -``import.write`` is on, embedded into files' metadata. - -The ``-p`` option to the ``tempo`` command makes it print tempos out to the -console so you can view the fetched (or previously-stored) tempos. diff --git a/docs/plugins/embedart.rst b/docs/plugins/embedart.rst index e03a5f929..963c8f4cd 100644 --- a/docs/plugins/embedart.rst +++ b/docs/plugins/embedart.rst @@ -11,7 +11,7 @@ Usage ----- To automatically embed discovered album art into imported files, just enable -the plugin (see :doc:`/plugins/index`). You'll also want to enable the +the ``embedart`` plugin (see :doc:`/plugins/index`). You'll also want to enable the :doc:`/plugins/fetchart` to obtain the images to be embedded. Art will be embedded after each album is added to the library. diff --git a/docs/plugins/fetchart.rst b/docs/plugins/fetchart.rst index e217c804b..8733a21d9 100644 --- a/docs/plugins/fetchart.rst +++ b/docs/plugins/fetchart.rst @@ -4,7 +4,7 @@ FetchArt Plugin The ``fetchart`` plugin retrieves album art images from various sources on the Web and stores them as image files. -To use the plugin, first enable it in your configuration (see +To use the ``fetchart`` plugin, first enable it in your configuration (see :ref:`using-plugins`). Then, install the `requests`_ library by typing:: pip install requests diff --git a/docs/plugins/fromfilename.rst b/docs/plugins/fromfilename.rst index 634b49f98..5cb6ccb76 100644 --- a/docs/plugins/fromfilename.rst +++ b/docs/plugins/fromfilename.rst @@ -9,4 +9,5 @@ When you attempt to import a track that's missing a title, this plugin will look at the track's filename and guess its track number, title, and artist. These will be used to search in MusicBrainz and match track ordering. -To use the plugin, enable it in your configuration (see :ref:`using-plugins`). +To use the ``fromfilename`` plugin, enable it in your configuration +(see :ref:`using-plugins`). diff --git a/docs/plugins/ftintitle.rst b/docs/plugins/ftintitle.rst index 4ba4224d9..51b7772f7 100644 --- a/docs/plugins/ftintitle.rst +++ b/docs/plugins/ftintitle.rst @@ -10,7 +10,8 @@ tracks in your library like "Tellin' Me Things" by the artist "Blakroc feat. RZA". If you prefer to tag this as "Tellin' Me Things feat. RZA" by "Blakroc", then this plugin is for you. -To use the plugin, enable it in your configuration (see :ref:`using-plugins`). +To use the ``ftintitle`` plugin, enable it in your configuration +(see :ref:`using-plugins`). Configuration ------------- diff --git a/docs/plugins/fuzzy.rst b/docs/plugins/fuzzy.rst index 4f5524efd..64a086ed4 100644 --- a/docs/plugins/fuzzy.rst +++ b/docs/plugins/fuzzy.rst @@ -14,7 +14,7 @@ You'll then be able to use the ``~`` prefix to use fuzzy matching:: Configuration ------------- -Available options : +Available options: - ``threshold``: a value of 1.0 will show only perfect matches and a value of 0.0 will match everything. diff --git a/docs/plugins/ihate.rst b/docs/plugins/ihate.rst index 8c7631725..82203cf6e 100644 --- a/docs/plugins/ihate.rst +++ b/docs/plugins/ihate.rst @@ -6,7 +6,7 @@ import or warn you about them. You specify queries (see :doc:`/reference/query`) and the plugin skips (or warns about) albums or items that match any query. -To use the plugin, enable it in your configuration (see +To use the ``ihate`` plugin, enable it in your configuration (see :ref:`using-plugins`). Configuration diff --git a/docs/plugins/importadded.rst b/docs/plugins/importadded.rst index 6530e587a..8924aad2c 100644 --- a/docs/plugins/importadded.rst +++ b/docs/plugins/importadded.rst @@ -1,7 +1,7 @@ ImportAdded Plugin ================== -The ``importadded`` plugin is useful when an existing collection is imported +This plugin is useful when an existing collection is imported and the time when albums and items were added should be preserved. The :abbr:`mtime (modification time)` of files that are imported into the diff --git a/docs/plugins/importfeeds.rst b/docs/plugins/importfeeds.rst index f0930aee5..8f0180f20 100644 --- a/docs/plugins/importfeeds.rst +++ b/docs/plugins/importfeeds.rst @@ -4,7 +4,8 @@ ImportFeeds Plugin The ``importfeeds`` plugin helps you keep track of newly imported music in your library. -To use the plugin, enable it in your configuration (see :ref:`using-plugins`). +To use the ``importfeeds`` plugin, enable it in your configuration +(see :ref:`using-plugins`). Configuration ------------- diff --git a/docs/plugins/info.rst b/docs/plugins/info.rst index 676102688..944f17c55 100644 --- a/docs/plugins/info.rst +++ b/docs/plugins/info.rst @@ -5,8 +5,8 @@ The ``info`` plugin provides a command that dumps the current tag values for any file format supported by beets. It works like a supercharged version of `mp3info`_ or `id3v2`_. -Enable the plugin in your configuration (see :ref:`using-plugins`) and then - type:: +Enable the ``info`` plugin in your configuration (see :ref:`using-plugins`) and +then type:: $ beet info /path/to/music.flac diff --git a/docs/plugins/inline.rst b/docs/plugins/inline.rst index 99fad299a..ebe298ae7 100644 --- a/docs/plugins/inline.rst +++ b/docs/plugins/inline.rst @@ -6,7 +6,8 @@ it, you can define template fields in your beets configuration file and refer to them from your template strings in the ``paths:`` section (see :doc:`/reference/config/`). -To use the plugin, enable it in your configuration (see :ref:`using-plugins`). +To use the `ìnline`` plugin, enable it in your configuration +(see :ref:`using-plugins`). Then, make a `item_fields:`` block in your config file. Under this key, every line defines a new template field; the key is the name of the field (you'll use the name to refer to the field in your templates) and the value is a Python expression or diff --git a/docs/plugins/keyfinder.rst b/docs/plugins/keyfinder.rst index 15d35a4ed..71fea1770 100644 --- a/docs/plugins/keyfinder.rst +++ b/docs/plugins/keyfinder.rst @@ -7,7 +7,7 @@ musical key of track from its audio data and store it in the automatically when importing music or through the ``beet keyfinder [QUERY]`` command. -To use the plugin, enable it in your configuration (see +To use the ``keyfinder`` plugin, enable it in your configuration (see :ref:`using-plugins`). Configuration diff --git a/docs/plugins/lastgenre.rst b/docs/plugins/lastgenre.rst index 069de9efa..d998d19ab 100644 --- a/docs/plugins/lastgenre.rst +++ b/docs/plugins/lastgenre.rst @@ -17,8 +17,8 @@ The plugin requires `pylast`_, which you can install using `pip`_ by typing:: pip install pylast -After you have pylast installed, nable the plugin in your configuration (see -:ref:`using-plugins`). +After you have pylast installed, enable the ``lastgenre`` plugin in your +configuration (see :ref:`using-plugins`). Usage ----- diff --git a/docs/plugins/lyrics.rst b/docs/plugins/lyrics.rst index ec0ac56d7..a2f2996ba 100644 --- a/docs/plugins/lyrics.rst +++ b/docs/plugins/lyrics.rst @@ -12,8 +12,8 @@ and, optionally, the Google custom search API. Fetch Lyrics During Import -------------------------- -To automatically fetch lyrics for songs you import, enable the plugin in your -configuration (see :ref:`using-plugins`). +To automatically fetch lyrics for songs you import, enable the ``lyrics`` +plugin in your configuration (see :ref:`using-plugins`). When importing new files, beets will now fetch lyrics for files that don't already have them. The lyrics will be stored in the beets database. If the ``import.write`` config option is on, then the lyrics will also be written to diff --git a/docs/plugins/mbsync.rst b/docs/plugins/mbsync.rst index 5497d93f0..633725b69 100644 --- a/docs/plugins/mbsync.rst +++ b/docs/plugins/mbsync.rst @@ -15,8 +15,8 @@ configuration. Usage ----- -Enable the plugin in your configuration (see :ref:`using-plugins`) and then -run ``beet mbsync QUERY`` to fetch updated metadata for a part of your +Enable the ``mbsync`` plugin in your configuration (see :ref:`using-plugins`) +and then run ``beet mbsync QUERY`` to fetch updated metadata for a part of your collection (or omit the query to run over your whole library). This plugin treats albums and singletons (non-album tracks) separately. It diff --git a/docs/plugins/missing.rst b/docs/plugins/missing.rst index 7cac8cbd6..5062f298f 100644 --- a/docs/plugins/missing.rst +++ b/docs/plugins/missing.rst @@ -27,7 +27,7 @@ tracks over your whole library, using command-line switches :: Configuration ------------- -Available options : +Available options: - ``count`` prints a count of missing tracks per album, with ``format`` defaulting to ``$albumartist - $album: $missing``. diff --git a/docs/plugins/mpdstats.rst b/docs/plugins/mpdstats.rst index 3e2d7f207..d0ccc363a 100644 --- a/docs/plugins/mpdstats.rst +++ b/docs/plugins/mpdstats.rst @@ -35,7 +35,7 @@ Use the ``mpdstats`` command to fire it up:: Configuration ------------- -Available options : +Available options: - ``host``: mpd server name. Default: ``localhost``. diff --git a/docs/plugins/mpdupdate.rst b/docs/plugins/mpdupdate.rst index f16d5ffdd..92ca25794 100644 --- a/docs/plugins/mpdupdate.rst +++ b/docs/plugins/mpdupdate.rst @@ -6,7 +6,8 @@ update `MPD`_'s index whenever you change your beets library. .. _MPD: http://www.musicpd.org/ -To use it, enable it in your configuration (see :ref:`using-plugins`). +To use ``mpdupdate`` plugin, enable it in your configuration +(see :ref:`using-plugins`). Then, you'll probably want to configure the specifics of your MPD server. You can do that using an ``mpd:`` section in your ``config.yaml``, which looks like this:: @@ -16,7 +17,8 @@ which looks like this:: port: 6600 password: seekrit -With that all in place, you'll see beets send the "update" command to your MPD server every time you change your beets library. +With that all in place, you'll see beets send the "update" command to your MPD +server every time you change your beets library. If you want to communicate with MPD over a Unix domain socket instead over TCP, just give the path to the socket in the filesystem for the ``host`` diff --git a/docs/plugins/play.rst b/docs/plugins/play.rst index 26182e18f..595c7db0d 100644 --- a/docs/plugins/play.rst +++ b/docs/plugins/play.rst @@ -7,7 +7,7 @@ player in the form of an m3u playlist. Usage ----- -To use the plugin, enable it in your configuration (see +To use the ``play`` plugin, enable it in your configuration (see :ref:`using-plugins`). Then use it by invoking the ``beet play`` command with a query. The command will create a temporary m3u file and open it using an appropriate application. You can query albums instead of tracks using the diff --git a/docs/plugins/replaygain.rst b/docs/plugins/replaygain.rst index 0ddfed2ae..65bf31b74 100644 --- a/docs/plugins/replaygain.rst +++ b/docs/plugins/replaygain.rst @@ -28,8 +28,8 @@ You will need at least GStreamer 1.0 and `PyGObject 3.x`_ (a.k.a. python-gi). .. _PyGObject 3.x: https://wiki.gnome.org/action/show/Projects/PyGObject .. _GStreamer: http://gstreamer.freedesktop.org/ -Then, enable the plugin (see :ref:`using-plugins`) and specify the GStreamer -backend by adding this to your configuration file:: +Then, enable the ``replaygain`` plugin (see :ref:`using-plugins`) and specify +the GStreamer backend by adding this to your configuration file:: replaygain: backend: gstreamer diff --git a/docs/plugins/rewrite.rst b/docs/plugins/rewrite.rst index 995783d55..3706d940a 100644 --- a/docs/plugins/rewrite.rst +++ b/docs/plugins/rewrite.rst @@ -6,7 +6,8 @@ path formats. Specifically, it is intended to let you *canonicalize* names such as artists: for example, perhaps you want albums from The Jimi Hendrix Experience to be sorted into the same folder as solo Hendrix albums. -To use field rewriting, first enable the plugin (see :ref:`using-plugins`). +To use field rewriting, first enable the ``rewrite`` plugin +(see :ref:`using-plugins`). Then, make a ``rewrite:`` section in your config file to contain your rewrite rules. Each rule consists of a field name, a regular expression pattern, and a replacement value. Rules are written ``fieldname regex: replacement``. diff --git a/docs/plugins/scrub.rst b/docs/plugins/scrub.rst index becb21d06..4760df9d8 100644 --- a/docs/plugins/scrub.rst +++ b/docs/plugins/scrub.rst @@ -11,7 +11,7 @@ Automatic Scrubbing ------------------- To automatically remove files' tags before writing new ones, just -enable the plugin (see :ref:`using-plugins`). When importing new files (with +enable the ``scrub`` plugin (see :ref:`using-plugins`). When importing new files (with ``import.write`` turned on) or modifying files' tags with the ``beet modify`` command, beets will first strip all types of tags entirely and then write the database-tracked metadata to the file. diff --git a/docs/plugins/smartplaylist.rst b/docs/plugins/smartplaylist.rst index 789b7c051..8dfce724e 100644 --- a/docs/plugins/smartplaylist.rst +++ b/docs/plugins/smartplaylist.rst @@ -7,7 +7,8 @@ created to work well with `MPD's`_ playlist functionality. .. _MPD's: http://www.musicpd.org/ -To use it, enable the plugin in your configuration (see :ref:`using-plugins`). +To use it, enable the ``smartplaylist`` plugin in your configuration +(see :ref:`using-plugins`). Then configure your smart playlists like the following example:: smartplaylist: diff --git a/docs/plugins/spotify.rst b/docs/plugins/spotify.rst index 14ef72c8a..42370e855 100644 --- a/docs/plugins/spotify.rst +++ b/docs/plugins/spotify.rst @@ -16,8 +16,8 @@ Why Use This Plugin? Basic Usage ----------- -First, enable the plugin (see :ref:`using-plugins`). Then, use the ``spotify`` -command with a beets query:: +First, enable the ``spotify`` plugin (see :ref:`using-plugins`). +Then, use the ``spotify`` command with a beets query:: beet spotify [OPTIONS...] QUERY diff --git a/docs/plugins/the.rst b/docs/plugins/the.rst index 493e79493..dd16c7c7a 100644 --- a/docs/plugins/the.rst +++ b/docs/plugins/the.rst @@ -11,8 +11,8 @@ regexp patterns can be added by user. How it works:: A Band -> Band, A An Orchestra -> Orchestra, An -Enable the plugin (see :doc:`/plugins/index`) and then make use of a template -function called ``%the`` for use in path format expressions:: +Enable the ``the`` plugin (see :doc:`/plugins/index`) and then make use of a +template function called ``%the`` for use in path format expressions:: paths: default: %the{$albumartist}/($year) $album/$track $title diff --git a/docs/plugins/types.rst b/docs/plugins/types.rst index 978654e8d..94d56e288 100644 --- a/docs/plugins/types.rst +++ b/docs/plugins/types.rst @@ -6,8 +6,8 @@ library. For example, you can declare that a ``rating`` field is numeric so that you can query it with ranges---which isn't possible when the field is considered a string (the default). -Enable the plugin as described in :doc:`/plugins/index` and then add a -``types`` section to your :doc:`configuration file `. The +Enable the ``types`` plugin as described in :doc:`/plugins/index` and then add +a ``types`` section to your :doc:`configuration file `. The configuration section should map field name to one of ``int``, ``float``, ``bool``, or ``date``. diff --git a/docs/plugins/web.rst b/docs/plugins/web.rst index 59a153dc2..be8e158f7 100644 --- a/docs/plugins/web.rst +++ b/docs/plugins/web.rst @@ -20,7 +20,8 @@ flask``. .. _Flask: http://flask.pocoo.org/ -Finally, enable the plugin in your configuration (see :ref:`using-plugins`). +Finally, enable the ``web`` plugin in your configuration +(see :ref:`using-plugins`). Run the Server -------------- diff --git a/docs/plugins/zero.rst b/docs/plugins/zero.rst index 81eaacedb..781f95b31 100644 --- a/docs/plugins/zero.rst +++ b/docs/plugins/zero.rst @@ -6,7 +6,8 @@ can be nulled unconditionally or conditioned on a pattern match. For example, the plugin can strip useless comments like "ripped by MyGreatRipper." This plugin only affects files' tags ; the beets database is left unchanged. -To use the plugin, enable the plugin in your configuration (see :ref:`using-plugins`). +To use the ``zero`` plugin, enable the plugin in your configuration +(see :ref:`using-plugins`). Configuration ------------- From b922abef06d4dd8f3245f0f0f8a02d5df11e4646 Mon Sep 17 00:00:00 2001 From: Fabrice Laporte Date: Tue, 28 Oct 2014 23:23:44 +0100 Subject: [PATCH 03/15] docs: remove space before colon --- docs/plugins/bpd.rst | 2 +- docs/plugins/bucket.rst | 2 +- docs/plugins/convert.rst | 2 +- docs/plugins/duplicates.rst | 2 +- docs/plugins/echonest.rst | 2 +- docs/plugins/embedart.rst | 2 +- docs/plugins/fetchart.rst | 2 +- docs/plugins/ftintitle.rst | 2 +- docs/plugins/ihate.rst | 2 +- docs/plugins/importadded.rst | 6 ++++++ docs/plugins/importfeeds.rst | 5 ++--- docs/plugins/lyrics.rst | 2 +- docs/plugins/mpdupdate.rst | 2 +- docs/plugins/replaygain.rst | 2 +- docs/plugins/smartplaylist.rst | 2 +- docs/plugins/web.rst | 2 +- 16 files changed, 22 insertions(+), 17 deletions(-) diff --git a/docs/plugins/bpd.rst b/docs/plugins/bpd.rst index 2af13152f..d92ddd160 100644 --- a/docs/plugins/bpd.rst +++ b/docs/plugins/bpd.rst @@ -70,7 +70,7 @@ on your headless server box. Rad! Configuration ------------- -Available options are pretty self-explanatory : +Available options are pretty self-explanatory: - ``host`` Default: ``u''`` diff --git a/docs/plugins/bucket.rst b/docs/plugins/bucket.rst index 9992661e4..a46ebf580 100644 --- a/docs/plugins/bucket.rst +++ b/docs/plugins/bucket.rst @@ -38,7 +38,7 @@ The definition of a range is somewhat loose, and multiple formats are allowed: Configuration ------------- -Available options : +Available options: - ``bucket_alpha`` defines ranges to use for all substitutions occuring on textual fields. diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst index 7b3a0c9fb..051099124 100644 --- a/docs/plugins/convert.rst +++ b/docs/plugins/convert.rst @@ -50,7 +50,7 @@ them. Configuration ------------- -Available options : +Available options: - ``auto`` gives you the option to import transcoded versions of your files automatically during the ``import`` command. With this option enabled, the diff --git a/docs/plugins/duplicates.rst b/docs/plugins/duplicates.rst index b5f0e32a0..662f4f918 100644 --- a/docs/plugins/duplicates.rst +++ b/docs/plugins/duplicates.rst @@ -36,7 +36,7 @@ duplicates themselves via command-line switches :: Configuration ------------- -Available options (mirroring the CLI ones) : +Available options (mirroring the CLI ones): - ``album`` lists duplicate albums instead of tracks. Default: ``no``. diff --git a/docs/plugins/echonest.rst b/docs/plugins/echonest.rst index e154a8816..8609c7807 100644 --- a/docs/plugins/echonest.rst +++ b/docs/plugins/echonest.rst @@ -53,7 +53,7 @@ Finally, enable the ``echonest`` plugin in your configuration (see Configuration ------------- -Available options : +Available options: - ``apikey``: set this option to specify your own EchoNest API key. You can `apply for your own`_ for free from the EchoNest. diff --git a/docs/plugins/embedart.rst b/docs/plugins/embedart.rst index 963c8f4cd..e3a0a0313 100644 --- a/docs/plugins/embedart.rst +++ b/docs/plugins/embedart.rst @@ -39,7 +39,7 @@ This feature requires `ImageMagick`_. Configuration ------------- -Available options : +Available options: - ``auto`` option lets you disable automatic album art embedding when set to ``no``. diff --git a/docs/plugins/fetchart.rst b/docs/plugins/fetchart.rst index 8733a21d9..692575904 100644 --- a/docs/plugins/fetchart.rst +++ b/docs/plugins/fetchart.rst @@ -26,7 +26,7 @@ the :ref:`art-filename` config option. Configuration ------------- -Available options : +Available options: - ``auto``: set it to ``no`` to disable automatic album art fetching during import. diff --git a/docs/plugins/ftintitle.rst b/docs/plugins/ftintitle.rst index 51b7772f7..34264987d 100644 --- a/docs/plugins/ftintitle.rst +++ b/docs/plugins/ftintitle.rst @@ -16,7 +16,7 @@ To use the ``ftintitle`` plugin, enable it in your configuration Configuration ------------- -Available options : +Available options: - ``auto``: set it to ``no`` to disable plugin during import. Default: ``yes``. diff --git a/docs/plugins/ihate.rst b/docs/plugins/ihate.rst index 82203cf6e..f2099be8a 100644 --- a/docs/plugins/ihate.rst +++ b/docs/plugins/ihate.rst @@ -12,7 +12,7 @@ To use the ``ihate`` plugin, enable it in your configuration (see Configuration ------------- -Available options : +Available options: - ``skip``: never import matches. Default: ``[]`` - ``warn``: print a warning message for matches. Default: ``[]`` diff --git a/docs/plugins/importadded.rst b/docs/plugins/importadded.rst index 8924aad2c..773d9db90 100644 --- a/docs/plugins/importadded.rst +++ b/docs/plugins/importadded.rst @@ -4,6 +4,12 @@ ImportAdded Plugin This plugin is useful when an existing collection is imported and the time when albums and items were added should be preserved. +To use the ``importadded`` plugin, enable it in your configuration (see +:ref:`using-plugins`). + +Usage +----- + The :abbr:`mtime (modification time)` of files that are imported into the library are assumed to represent the time when the items were originally added. diff --git a/docs/plugins/importfeeds.rst b/docs/plugins/importfeeds.rst index 8f0180f20..97632f498 100644 --- a/docs/plugins/importfeeds.rst +++ b/docs/plugins/importfeeds.rst @@ -1,8 +1,7 @@ ImportFeeds Plugin ================== -The ``importfeeds`` plugin helps you keep track of newly imported music in your -library. +This plugin helps you keep track of newly imported music in your library. To use the ``importfeeds`` plugin, enable it in your configuration (see :ref:`using-plugins`). @@ -10,7 +9,7 @@ To use the ``importfeeds`` plugin, enable it in your configuration Configuration ------------- -Available options : +Available options: - ``absolute_path`` option can be set to use absolute paths instead of relative paths. Some applications may need this to work properly. diff --git a/docs/plugins/lyrics.rst b/docs/plugins/lyrics.rst index a2f2996ba..3d5f265a7 100644 --- a/docs/plugins/lyrics.rst +++ b/docs/plugins/lyrics.rst @@ -23,7 +23,7 @@ the files' tags. Configuration ------------- -Available options : +Available options: - ``auto``: set it to ``no`` to disable automatic lyrics fetching during import. Default: ``yes``. diff --git a/docs/plugins/mpdupdate.rst b/docs/plugins/mpdupdate.rst index 92ca25794..1dad856df 100644 --- a/docs/plugins/mpdupdate.rst +++ b/docs/plugins/mpdupdate.rst @@ -28,7 +28,7 @@ socket.) Configuration ------------- -Available options : +Available options: - ``host``: mpd server name. Default: ``localhost``. diff --git a/docs/plugins/replaygain.rst b/docs/plugins/replaygain.rst index 65bf31b74..75b3c4d15 100644 --- a/docs/plugins/replaygain.rst +++ b/docs/plugins/replaygain.rst @@ -65,7 +65,7 @@ you can configure the path explicitly like so:: Configuration ------------- -Available options : +Available options: - ``auto``: set it to ``no`` to disable replaygain analysis during import. diff --git a/docs/plugins/smartplaylist.rst b/docs/plugins/smartplaylist.rst index 8dfce724e..0a1db5b3a 100644 --- a/docs/plugins/smartplaylist.rst +++ b/docs/plugins/smartplaylist.rst @@ -69,7 +69,7 @@ plugin. Configuration ------------- -Available options : +Available options: - ``auto``: set it to ``no`` to tell beets to stop regenerate the playlist after every database change. diff --git a/docs/plugins/web.rst b/docs/plugins/web.rst index be8e158f7..1804e7deb 100644 --- a/docs/plugins/web.rst +++ b/docs/plugins/web.rst @@ -53,7 +53,7 @@ Type queries into the little search box. Double-click a track to play it with Configuration ------------- -Available options : +Available options: - ``host``: server hostname Default: ``u''`` From 155028257dbc839f8d394ba6b57b7f5fa1562cd0 Mon Sep 17 00:00:00 2001 From: Fabrice Laporte Date: Tue, 28 Oct 2014 23:31:15 +0100 Subject: [PATCH 04/15] fix typos --- docs/plugins/ftintitle.rst | 2 +- docs/plugins/fuzzy.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plugins/ftintitle.rst b/docs/plugins/ftintitle.rst index 34264987d..a45fb2285 100644 --- a/docs/plugins/ftintitle.rst +++ b/docs/plugins/ftintitle.rst @@ -1,7 +1,7 @@ FtInTitle Plugin ================ -The ``ftintitle`` plugin automatically move "featured" artists from the +The ``ftintitle`` plugin automatically moves "featured" artists from the ``artist`` field to the ``title`` field. According to `MusicBrainz style`_, featured artists are part of the artist diff --git a/docs/plugins/fuzzy.rst b/docs/plugins/fuzzy.rst index 64a086ed4..35b80b6b9 100644 --- a/docs/plugins/fuzzy.rst +++ b/docs/plugins/fuzzy.rst @@ -1,7 +1,7 @@ Fuzzy Search Plugin =================== -The ``fuzzy`` plugin provides a prefixed query that searches you library using +The ``fuzzy`` plugin provides a prefixed query that searches your library using fuzzy pattern matching. This can be useful if you want to find a track with complicated characters in the title. From 4a86a6fc520657be16a3decdccb5c2aee8c0ba58 Mon Sep 17 00:00:00 2001 From: Fabrice Laporte Date: Tue, 28 Oct 2014 23:31:40 +0100 Subject: [PATCH 05/15] fetch art doc: restore section title --- docs/plugins/fetchart.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plugins/fetchart.rst b/docs/plugins/fetchart.rst index 692575904..dc9b9a4d8 100644 --- a/docs/plugins/fetchart.rst +++ b/docs/plugins/fetchart.rst @@ -13,8 +13,8 @@ The plugin uses `requests`_ to fetch album art from the Web. .. _requests: http://docs.python-requests.org/en/latest/ -Usage ------ +Fetching Album Art During Import +-------------------------------- When the plugin is enabled, it automatically gets album art for every album you import. From 8bc665d7ad369bbccf7e32b28c45bf9abc01dcb2 Mon Sep 17 00:00:00 2001 From: Fabrice Laporte Date: Wed, 29 Oct 2014 06:59:14 +0100 Subject: [PATCH 06/15] fix index toc --- docs/plugins/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index 6f05827df..af02e1b4a 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -33,7 +33,6 @@ Each plugin has its own set of options that can be defined in a section bearing chroma lyrics - echonest_tempo echonest bpd mpdupdate From ff39174d925b2068ffe13a914e4b777419e8f927 Mon Sep 17 00:00:00 2001 From: Fabrice Laporte Date: Wed, 29 Oct 2014 07:20:35 +0100 Subject: [PATCH 07/15] changelog.rst: remove links to echonest_tempo --- docs/changelog.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index c05d08bce..90d969611 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -573,7 +573,7 @@ As usual, there are also innumerable little fixes and improvements: * :doc:`/plugins/missing`: Avoid a possible error when an album's ``tracktotal`` field is missing. * :doc:`/plugins/ftintitle`: Fix an error when the sort artist is missing. -* :doc:`/plugins/echonest_tempo`: The plugin should now match songs more +* ``echonest_tempo``: The plugin should now match songs more reliably (i.e., fewer "no tempo found" messages). Thanks to Peter Schnebel. * :doc:`/plugins/convert`: Fix an "Item has no library" error when using the ``auto`` config option. @@ -639,7 +639,7 @@ And some fixes: (instead of failing with an API error). * :doc:`/plugins/info`: Fail gracefully when used erroneously with a directory. -* :doc:`/plugins/echonest_tempo`: Fix an issue where the plugin could use the +* ``echonest_tempo``: Fix an issue where the plugin could use the tempo from the wrong song when the API did not contain the requested song. * Fix a crash when a file's metadata included a very large number (one wider than 64 bits). These huge numbers are now replaced with zeroes in the @@ -995,7 +995,7 @@ Other stuff: * :doc:`/plugins/chroma`: A new ``fingerprint`` command lets you generate and store fingerprints for items that don't yet have them. One more round of applause for Lucas Duailibe. -* :doc:`/plugins/echonest_tempo`: API errors now issue a warning instead of +* ``echonest_tempo``: API errors now issue a warning instead of exiting with an exception. We also avoid an error when track metadata contains newlines. * When the importer encounters an error (insufficient permissions, for @@ -1019,7 +1019,7 @@ Other stuff: import command. Thanks to Lucas Duailibe. * :doc:`/plugins/mbcollection`: Show friendly, human-readable errors when MusicBrainz exceptions occur. -* :doc:`/plugins/echonest_tempo`: Catch socket errors that are not handled by +* ``echonest_tempo``: Catch socket errors that are not handled by the Echo Nest library. * :doc:`/plugins/chroma`: Catch Acoustid Web service errors when submitting fingerprints. @@ -1118,7 +1118,7 @@ Other new stuff: Dang Mai Hai. * :doc:`/plugins/bpd`: Browse by album artist and album artist sort name. Thanks to Steinþór Pálsson. -* :doc:`/plugins/echonest_tempo`: Don't attempt a lookup when the artist or +* ``echonest_tempo``: Don't attempt a lookup when the artist or track title is missing. * Fix an error when migrating the ``.beetsstate`` file on Windows. * A nicer error message is now given when the configuration file contains tabs. @@ -1184,7 +1184,7 @@ This second release candidate follows quickly after rc1 and fixes a few small bugs found since that release. There were a couple of regressions and some bugs in a newly added plugin. -* :doc:`/plugins/echonest_tempo`: If the Echo Nest API limit is exceeded or a +* ``echonest_tempo``: If the Echo Nest API limit is exceeded or a communication error occurs, the plugin now waits and tries again instead of crashing. Thanks to Zach Denton. * :doc:`/plugins/fetchart`: Fix a regression that caused crashes when art was @@ -1214,7 +1214,7 @@ begins today on features for version 1.1. * New plugin: :doc:`/plugins/fuzzy` lets you find albums and tracks using **fuzzy string matching** so you don't have to type (or even remember) their exact names. Thanks to Philippe Mongeau. -* New plugin: :doc:`/plugins/echonest_tempo` fetches **tempo** (BPM) information +* New plugin: ``echonest_tempo`` fetches **tempo** (BPM) information from `The Echo Nest`_. Thanks to David Brenner. * New plugin: :doc:`/plugins/the` adds a template function that helps format text for nicely-sorted directory listings. Thanks to Blemjhoo Tezoulbr. From ca1d6a9899eb9a1fe66432e9d06da3e48a413e2f Mon Sep 17 00:00:00 2001 From: Fabrice Laporte Date: Wed, 29 Oct 2014 22:33:13 +0100 Subject: [PATCH 08/15] always a colon between the option name and the rest of the description plus typos and case change --- docs/plugins/bpd.rst | 5 +++-- docs/plugins/bucket.rst | 13 +++++++------ docs/plugins/convert.rst | 21 +++++++++------------ docs/plugins/duplicates.rst | 22 +++++++++++----------- docs/plugins/embedart.rst | 4 ++-- docs/plugins/importadded.rst | 3 ++- docs/plugins/keyfinder.rst | 6 +++--- docs/plugins/mbcollection.rst | 9 ++++----- docs/plugins/spotify.rst | 2 +- 9 files changed, 42 insertions(+), 43 deletions(-) diff --git a/docs/plugins/bpd.rst b/docs/plugins/bpd.rst index d92ddd160..4d87ebe13 100644 --- a/docs/plugins/bpd.rst +++ b/docs/plugins/bpd.rst @@ -76,8 +76,9 @@ Available options are pretty self-explanatory: Default: ``u''`` - ``port`` Default: ``6600`` -- ``password``: ``u'`` -- ``volume`` sets the initial volume in percent +- ``password`` + Default: ``u''`` +- ``volume``: initial volume in percent Default: ``100`` Here's an example:: diff --git a/docs/plugins/bucket.rst b/docs/plugins/bucket.rst index a46ebf580..3b96866aa 100644 --- a/docs/plugins/bucket.rst +++ b/docs/plugins/bucket.rst @@ -40,14 +40,15 @@ Configuration Available options: -- ``bucket_alpha`` defines ranges to use for all substitutions occuring on - textual fields. +- ``bucket_alpha``: ranges to use for all substitutions occuring on textual + fields. Default: ``[]`` -- ``bucket_alpha_regex`` allows to define a regex to override a `bucket_alpha` - range definition +- ``bucket_alpha_regex``: list of ``key: value`` (one per line) with 'key' + being one of the `bucket_alpha` range and 'value' a regex that override + original range definition. Default: ``{}`` -- ``bucket_year`` defines ranges to use for all substitutions occuring on the - `$year` field +- ``bucket_year``: ranges to use for all substitutions occuring on the + `$year` field. Default: ``[]`` - ``extrapolate`` : activate it when you want to group your files into multiple year ranges without enumerating them all. This option will generate year diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst index 051099124..9876507be 100644 --- a/docs/plugins/convert.rst +++ b/docs/plugins/convert.rst @@ -52,33 +52,30 @@ Configuration Available options: -- ``auto`` gives you the option to import transcoded versions of your files +- ``auto``: set it to ``yes`` to import transcoded versions of your files automatically during the ``import`` command. With this option enabled, the importer will transcode all non-MP3 files over the maximum bitrate before adding them to your library. Default: ``no``. -- ``dest`` sets the directory the files will be converted (or copied) to. - A destination is required---you either have to provide it in the config file - or on the command-line using the ``-d`` flag. +- ``dest``: the directory where the files will be converted (or copied) to. + Default: ``None`` - ``embed`` indicates whether or not to embed album art in converted items. Default: ``yes``. - ``max_bitrate``: all lossy files with a higher bitrate will be transcoded and those with a lower bitrate will simply be copied. Note that this does not guarantee that all converted files will have a lower bitrate---that depends on the encoder and its configuration. -- ``never_convert_lossy_files`` means that lossy codecs, such as mp3, ogg - vorbis, etc, are never converted, as converting lossy files to other lossy - codecs will decrease quality further. If set to ``yes``, lossy files are - always copied. +- ``never_convert_lossy_files``: cross-conversions between lossy codecs---such + as mp3, ogg vorbis, etc,---makes little sense as they will decrease quality + even further. If set to ``yes``, lossy files are always copied. Default: ``no`` -- ``paths`` lets you specify the directory structure and naming scheme for the +- ``paths``: lets you specify the directory structure and naming scheme for the converted files. Use the same format as the top-level ``paths`` section (see :ref:`path-format-config`). By default, the plugin reuses your top-level path format settings. -- ``quiet`` mode prevents the plugin from announcing every file it processes. +- ``quiet``: prevents the plugin from announcing every file it processes. Default: ``false``. -- ``threads`` determines the number of threads to use for parallel - encoding. +- ``threads``: number of threads to use for parallel encoding. By default, the plugin will detect the number of processors available and use them all. diff --git a/docs/plugins/duplicates.rst b/docs/plugins/duplicates.rst index 662f4f918..3cf99a1ed 100644 --- a/docs/plugins/duplicates.rst +++ b/docs/plugins/duplicates.rst @@ -38,43 +38,43 @@ Configuration Available options (mirroring the CLI ones): -- ``album`` lists duplicate albums instead of tracks. +- ``album``: lists duplicate albums instead of tracks. Default: ``no``. -- ``checksum`` enables the use of any arbitrary command to compute a checksum +- ``checksum``: enables the use of any arbitrary command to compute a checksum of items. It overrides the ``keys`` option the first time it is run; however, because it caches the resulting checksum as ``flexattrs`` in the database, you can use ``--keys=name_of_the_checksumming_program any_other_keys`` (or set configuration ``keys``option) the second time around. Default: ``ffmpeg -i {file} -f crc -``. -- ``copy`` takes a destination base directory into which it will copy matched +- ``copy``: takes a destination base directory into which it will copy matched items. Default: ``no``. -- `count` prints a count of duplicate tracks or albums, with ``format`` +- ``count``: prints a count of duplicate tracks or albums, with ``format`` hard-coded to ``$albumartist - $album - $title: $count`` or ``$albumartist - $album: $count`` (for the ``-a`` option). Default: ``no``. -- ``delete`` removes matched items from the library and from the disk. +- ``delete``: removes matched items from the library and from the disk. Default: ``no`` -- `format` lets you specify a specific format with which to print every track +- ``format``: lets you specify a specific format with which to print every track or album. This uses the same template syntax as beets ’:doc:`path formats`. The usage is inspired by, and therefore similar to, the :ref:`list ` command. Default: :ref:`list_format_item` -- ``full`` lists every track or album that has duplicates, not just the +- ``full``:lists every track or album that has duplicates, not just the duplicates themselves. Default: ``no``. -- ``keys`` defines in which track or album fields duplicates are to be +- ``keys``: defines in which track or album fields duplicates are to be searched. By default, the plugin uses the musicbrainz track and album IDs for this purpose. Using the ``keys`` option (as a YAML list in the configuration file, or as space-delimited strings in the command-line), you can extend this behavior to consider other attributes. Default: ``[mb_trackid, mb_albumid]`` -- ``move`` takes a destination base directory into which it will move matched +- ``move``: takes a destination base directory into which it will move matched items. Default: ``no``. -- `path` is a convenience wrapper for ``-f \$path``. +- ``path``: convenience wrapper for ``-f \$path``. Default: ``no``. -- ``tag`` takes a ``key=value`` string, and adds a new ``key`` attribute with +- ``tag``: takes a ``key=value`` string, and adds a new ``key`` attribute with ``value`` value as a flexattr to the database. Default: ``no``. diff --git a/docs/plugins/embedart.rst b/docs/plugins/embedart.rst index e3a0a0313..1fa24f22f 100644 --- a/docs/plugins/embedart.rst +++ b/docs/plugins/embedart.rst @@ -41,7 +41,7 @@ Configuration Available options: -- ``auto`` option lets you disable automatic album art embedding when set to +- ``auto``: lets you disable automatic album art embedding when set to ``no``. Default: ``true`` - ``compare_threshold``: how similar must candidate art be regarding to @@ -50,7 +50,7 @@ Available options: - ``ifempty``: set to 'yes' to avoid embedding album art for files that already have one. Default: ``no``. -- ``maxwidth`` defines a maximum width to downscale images before embedding +- ``maxwidth``: defines a maximum width to downscale images before embedding them (the original image file is not altered). The resize operation reduces image width to ``maxwidth`` pixels. The height is recomputed so that the aspect ratio is preserved. See also :ref:`image-resizing` for further caveats diff --git a/docs/plugins/importadded.rst b/docs/plugins/importadded.rst index 773d9db90..a320f4e3e 100644 --- a/docs/plugins/importadded.rst +++ b/docs/plugins/importadded.rst @@ -41,7 +41,8 @@ Configuration Available option: -- ``preserve_mtimes``: Default: ``no`` +- ``preserve_mtimes`` + Default: ``no`` Reimport -------- diff --git a/docs/plugins/keyfinder.rst b/docs/plugins/keyfinder.rst index 71fea1770..b35655cba 100644 --- a/docs/plugins/keyfinder.rst +++ b/docs/plugins/keyfinder.rst @@ -15,15 +15,15 @@ Configuration Available options: -- ``bin``: The name of the `KeyFinder` program on your system or +- ``bin``: the name of the `KeyFinder` program on your system or a path to the binary. If you installed the `KeyFinder`_ GUI on a Mac, for example, you want something like ``/Applications/KeyFinder.app/Contents/MacOS/KeyFinder``. Default: ``KeyFinder``. -- ``auto``: If set to `yes`, the plugin will analyze every file on +- ``auto``: if set to `yes`, the plugin will analyze every file on import. Otherwise, you need to use the ``beet keyfinder`` command explicitly. Default: ``yes``. -- ``overwrite``: If set to ``no``, the import hook and the command will skip +- ``overwrite``: if set to ``no``, the import hook and the command will skip any file that already has an 'initial_key' in the database. Default: ``no``. diff --git a/docs/plugins/mbcollection.rst b/docs/plugins/mbcollection.rst index 615f1a4f6..f948c3652 100644 --- a/docs/plugins/mbcollection.rst +++ b/docs/plugins/mbcollection.rst @@ -23,9 +23,8 @@ profile first. Configuration ------------- +Available option: -Automatically Update on Import ------------------------------- - -mbcollection: if set to ``yes``, the plugin will automatically amend your -MusicBrainz collection whenever you import a new album. Default: ``false`` +- ``auto``: if set to ``yes``, the plugin will automatically amend your + MusicBrainz collection whenever you import a new album. + Default: ``false`` diff --git a/docs/plugins/spotify.rst b/docs/plugins/spotify.rst index 42370e855..8b7bf2539 100644 --- a/docs/plugins/spotify.rst +++ b/docs/plugins/spotify.rst @@ -54,7 +54,7 @@ The default options should work as-is, but there are some options you can put in * ``region_filter``: use the 2-character country abbreviation to limit results to that market. Default: ``None`` -* ``show_failures``: qhow the artist/album/track for each lookup that does not +* ``show_failures``: show the artist/album/track for each lookup that does not return a Spotify ID (and therefore cannot be added to a playlist). Default: ``no`` * ``tiebreak``: how to choose the track if there is more than one identical From 613c85ad6e2d355ad2cf76e00f773888036d2e28 Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Thu, 30 Oct 2014 11:42:27 -0700 Subject: [PATCH 09/15] Plugin docs overhaul tweaks through "duplicates" Moving alphabetically through the docs. Got a long way to go... --- docs/Makefile | 6 ++++- docs/plugins/bpd.rst | 19 ++++++++------- docs/plugins/bucket.rst | 27 +++++++++++---------- docs/plugins/chroma.rst | 8 +++++-- docs/plugins/convert.rst | 33 +++++++++++++------------ docs/plugins/duplicates.rst | 48 +++++++++++++++++++------------------ docs/refresh_safari.js | 21 ++++++++++++++++ 7 files changed, 99 insertions(+), 63 deletions(-) create mode 100644 docs/refresh_safari.js diff --git a/docs/Makefile b/docs/Makefile index 3c8aa63d6..fd4676f6b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -17,7 +17,7 @@ PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest auto help: @echo "Please use \`make ' where is one of" @@ -38,6 +38,10 @@ help: @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" +# My magical rebuilding, Safari-reloading auto target. +auto: + watchmedo shell-command --patterns='*.rst' --ignore-pattern='_build/*' --recursive --command='make html ; osascript -l JavaScript refresh_safari.js' --wait + clean: -rm -rf $(BUILDDIR)/* diff --git a/docs/plugins/bpd.rst b/docs/plugins/bpd.rst index 4d87ebe13..b5082b220 100644 --- a/docs/plugins/bpd.rst +++ b/docs/plugins/bpd.rst @@ -70,16 +70,17 @@ on your headless server box. Rad! Configuration ------------- -Available options are pretty self-explanatory: +To configure the plugin, make a ``bpd:`` section in your configuration file. +The available options are: -- ``host`` - Default: ``u''`` -- ``port`` - Default: ``6600`` -- ``password`` - Default: ``u''`` -- ``volume``: initial volume in percent - Default: ``100`` +- ``host``: + Default: Bind to all interfaces. +- ``port``: + Default: 6600 +- ``password``: + Default: No password. +- ``volume``: Initial volume, as a percentage. + Default: 100 Here's an example:: diff --git a/docs/plugins/bucket.rst b/docs/plugins/bucket.rst index 3b96866aa..a325d4552 100644 --- a/docs/plugins/bucket.rst +++ b/docs/plugins/bucket.rst @@ -1,5 +1,5 @@ Bucket Plugin -============== +============= The ``bucket`` plugin groups your files into buckets folders representing *ranges*. This kind of organization can classify your music by periods of time @@ -38,19 +38,20 @@ The definition of a range is somewhat loose, and multiple formats are allowed: Configuration ------------- -Available options: +To configure the plugin, make a ``bucket:`` section in your configuration file. +The available options are: -- ``bucket_alpha``: ranges to use for all substitutions occuring on textual +- ``bucket_alpha``: Ranges to use for all substitutions occurring on textual fields. - Default: ``[]`` -- ``bucket_alpha_regex``: list of ``key: value`` (one per line) with 'key' - being one of the `bucket_alpha` range and 'value' a regex that override - original range definition. - Default: ``{}`` -- ``bucket_year``: ranges to use for all substitutions occuring on the + Default: none. +- ``bucket_alpha_regex``: A ``range: regex`` mapping (one per line) where + ``range`` is one of the `bucket_alpha` range and ``value`` is a regex that + override original range definition. + Default: none. +- ``bucket_year``: Ranges to use for all substitutions occurring on the `$year` field. - Default: ``[]`` -- ``extrapolate`` : activate it when you want to group your files into multiple + Default: none. +- ``extrapolate``: Enable this if you want to group your files into multiple year ranges without enumerating them all. This option will generate year bucket names by reproducing characteristics of declared buckets. Default: ``no`` @@ -64,6 +65,6 @@ Here's an example:: bucket_alpha_regex: 'A - D': ^[0-9a-dA-D…äÄ] -The above configuration creates five-year ranges for any input year. +THis configuration creates five-year ranges for any input year. The *A - D* bucket now matches also all artists starting with ä or Ä and 0 to 9 -and … (three dots). The other alpha buckets work as ranges. +and … (ellipsis). The other alpha buckets work as ranges. diff --git a/docs/plugins/chroma.rst b/docs/plugins/chroma.rst index 3640e642b..c770fe698 100644 --- a/docs/plugins/chroma.rst +++ b/docs/plugins/chroma.rst @@ -105,8 +105,12 @@ written to files' metadata. Configuration ------------- -The only option is **auto**, set it to 'no' to disable fingerprinting on -import. +There is one configuration option in the ``chroma:`` section, ``auto``, which +controls whether to fingerprint files during the import process. To disable +fingerprint-based autotagging, set it to ``no``, like so:: + + chroma: + auto: no Submitting Fingerprints ----------------------- diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst index 9876507be..a2ddeb10c 100644 --- a/docs/plugins/convert.rst +++ b/docs/plugins/convert.rst @@ -50,35 +50,38 @@ them. Configuration ------------- -Available options: +To configure the plugin, make a ``convert:`` section in your configuration +file. The available options are: -- ``auto``: set it to ``yes`` to import transcoded versions of your files - automatically during the ``import`` command. With this option enabled, the - importer will transcode all non-MP3 files over the maximum bitrate before - adding them to your library. +- ``auto``: Import transcoded versions of your files automatically during + imports. With this option enabled, the importer will transcode all (in the + default configuration) non-MP3 files over the maximum bitrate before adding + them to your library. Default: ``no``. -- ``dest``: the directory where the files will be converted (or copied) to. - Default: ``None`` -- ``embed`` indicates whether or not to embed album art in converted items. - Default: ``yes``. -- ``max_bitrate``: all lossy files with a higher bitrate will be +- ``dest``: The directory where the files will be converted (or copied) to. + Default: none. +- ``embed`` Embed album art in converted items. Default: ``yes``. +- ``max_bitrate``: All lossy files with a higher bitrate will be transcoded and those with a lower bitrate will simply be copied. Note that this does not guarantee that all converted files will have a lower bitrate---that depends on the encoder and its configuration. -- ``never_convert_lossy_files``: cross-conversions between lossy codecs---such + Default: none. +- ``never_convert_lossy_files``: Cross-conversions between lossy codecs---such as mp3, ogg vorbis, etc,---makes little sense as they will decrease quality even further. If set to ``yes``, lossy files are always copied. - Default: ``no`` -- ``paths``: lets you specify the directory structure and naming scheme for the + Default: ``no``. +- ``paths``: Lets you specify the directory structure and naming scheme for the converted files. Use the same format as the top-level ``paths`` section (see :ref:`path-format-config`). By default, the plugin reuses your top-level path format settings. -- ``quiet``: prevents the plugin from announcing every file it processes. +- ``quiet``: Prevent the plugin from announcing every file it processes. Default: ``false``. -- ``threads``: number of threads to use for parallel encoding. +- ``threads``: The number of threads to use for parallel encoding. By default, the plugin will detect the number of processors available and use them all. +You can also configure the format to use for transcoding. + .. _convert-format-config: Configuring the transcoding command diff --git a/docs/plugins/duplicates.rst b/docs/plugins/duplicates.rst index 3cf99a1ed..08379451f 100644 --- a/docs/plugins/duplicates.rst +++ b/docs/plugins/duplicates.rst @@ -36,46 +36,48 @@ duplicates themselves via command-line switches :: Configuration ------------- -Available options (mirroring the CLI ones): +To configure the plugin, make a ``duplicates:`` section in your configuration +file. The available options mirror the command-line options: -- ``album``: lists duplicate albums instead of tracks. +- ``album``: List duplicate albums instead of tracks. Default: ``no``. -- ``checksum``: enables the use of any arbitrary command to compute a checksum - of items. It overrides the ``keys`` option the first time it is run; however, - because it caches the resulting checksum as ``flexattrs`` in the database, - you can use ``--keys=name_of_the_checksumming_program any_other_keys`` (or - set configuration ``keys``option) the second time around. +- ``checksum``: Use an arbitrary command to compute a checksum + of items. This overrides the ``keys`` option the first time it is run; + however, because it caches the resulting checksum as ``flexattrs`` in the + database, you can use ``--keys=name_of_the_checksumming_program + any_other_keys`` (or set configuration ``keys`` option) the second time + around. Default: ``ffmpeg -i {file} -f crc -``. -- ``copy``: takes a destination base directory into which it will copy matched +- ``copy``: A destination base directory into which to copy matched items. + Default: none (disabled). +- ``count``: Print a count of duplicate tracks or albums in the format + ``$albumartist - $album - $title: $count`` (for tracks) or ``$albumartist - + $album: $count`` (for albums). Default: ``no``. -- ``count``: prints a count of duplicate tracks or albums, with ``format`` - hard-coded to ``$albumartist - $album - $title: $count`` or ``$albumartist - - $album: $count`` (for the ``-a`` option). - Default: ``no``. -- ``delete``: removes matched items from the library and from the disk. +- ``delete``: Removes matched items from the library and from the disk. Default: ``no`` -- ``format``: lets you specify a specific format with which to print every track - or album. This uses the same template syntax as beets - ’:doc:`path formats`. The usage is inspired by, and +- ``format``: A specific format with which to print every track + or album. This uses the same template syntax as beets' + :doc:`path formats`. The usage is inspired by, and therefore similar to, the :ref:`list ` command. Default: :ref:`list_format_item` -- ``full``:lists every track or album that has duplicates, not just the +- ``full``: List every track or album that has duplicates, not just the duplicates themselves. Default: ``no``. -- ``keys``: defines in which track or album fields duplicates are to be +- ``keys``: Define in which track or album fields duplicates are to be searched. By default, the plugin uses the musicbrainz track and album IDs for this purpose. Using the ``keys`` option (as a YAML list in the configuration file, or as space-delimited strings in the command-line), you can extend this behavior to consider other attributes. Default: ``[mb_trackid, mb_albumid]`` -- ``move``: takes a destination base directory into which it will move matched +- ``move``: A destination base directory into which it will move matched items. + Default: none (disabled). +- ``path``: Output the path instead of metadata when listing duplicates. Default: ``no``. -- ``path``: convenience wrapper for ``-f \$path``. - Default: ``no``. -- ``tag``: takes a ``key=value`` string, and adds a new ``key`` attribute with - ``value`` value as a flexattr to the database. +- ``tag``: A ``key=value`` pair. The plugin will add a new ``key`` attribute + with ``value`` value as a flexattr to the database for duplicate items. Default: ``no``. Examples diff --git a/docs/refresh_safari.js b/docs/refresh_safari.js new file mode 100644 index 000000000..8678a3664 --- /dev/null +++ b/docs/refresh_safari.js @@ -0,0 +1,21 @@ +var safari = Application('com.apple.Safari'); +safari.strictPropertyScope = true; +safari.strictCommandScope = true; + +for (var i = 0; i < safari.windows.length; ++i) { + var win = safari.windows[i]; + var tabs = win.tabs; + if (Object.keys(tabs).length) { + for (var j = 0; j < win.tabs.length; ++j) { + var tab = win.tabs[j]; + var url = tab.url(); + if (url.indexOf("file:") == 0) { + // A local file URL. + console.log(url); + tab.url = url; // Refresh. + } + } + } +} + +'done'; From a253eb4f7233b34a3c327841b304aa741ce2f42b Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Thu, 30 Oct 2014 14:37:02 -0700 Subject: [PATCH 10/15] Refresh without scrolling to top --- docs/plugins/convert.rst | 8 +++++--- docs/refresh_safari.js | 4 +--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst index a2ddeb10c..4169f3414 100644 --- a/docs/plugins/convert.rst +++ b/docs/plugins/convert.rst @@ -60,14 +60,14 @@ file. The available options are: Default: ``no``. - ``dest``: The directory where the files will be converted (or copied) to. Default: none. -- ``embed`` Embed album art in converted items. Default: ``yes``. +- ``embed``: Embed album art in converted items. Default: ``yes``. - ``max_bitrate``: All lossy files with a higher bitrate will be transcoded and those with a lower bitrate will simply be copied. Note that this does not guarantee that all converted files will have a lower bitrate---that depends on the encoder and its configuration. Default: none. - ``never_convert_lossy_files``: Cross-conversions between lossy codecs---such - as mp3, ogg vorbis, etc,---makes little sense as they will decrease quality + as mp3, ogg vorbis, etc.---makes little sense as they will decrease quality even further. If set to ``yes``, lossy files are always copied. Default: ``no``. - ``paths``: Lets you specify the directory structure and naming scheme for the @@ -89,7 +89,9 @@ Configuring the transcoding command You can customize the transcoding command through the ``formats`` map and select a command with the ``--format`` command-line option or the -``format`` configuration.:: +``format`` configuration. + +:: convert: format: speex diff --git a/docs/refresh_safari.js b/docs/refresh_safari.js index 8678a3664..7f5cc0ccc 100644 --- a/docs/refresh_safari.js +++ b/docs/refresh_safari.js @@ -1,6 +1,4 @@ var safari = Application('com.apple.Safari'); -safari.strictPropertyScope = true; -safari.strictCommandScope = true; for (var i = 0; i < safari.windows.length; ++i) { var win = safari.windows[i]; @@ -11,8 +9,8 @@ for (var i = 0; i < safari.windows.length; ++i) { var url = tab.url(); if (url.indexOf("file:") == 0) { // A local file URL. + safari.doJavaScript("location.reload();", { in: tab }); console.log(url); - tab.url = url; // Refresh. } } } From f7fe10a376727e18d7f1291e6a6477171f90d9fc Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Thu, 30 Oct 2014 15:54:39 -0700 Subject: [PATCH 11/15] make auto: Ignore "deleted" events vim's atomic writes delete the file and then re-add it, which was leading to Sphinx being triggered twice. --- docs/Makefile | 2 +- docs/plugins/convert.rst | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index fd4676f6b..fd1707f27 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -40,7 +40,7 @@ help: # My magical rebuilding, Safari-reloading auto target. auto: - watchmedo shell-command --patterns='*.rst' --ignore-pattern='_build/*' --recursive --command='make html ; osascript -l JavaScript refresh_safari.js' --wait + watchmedo shell-command --patterns='*.rst' --ignore-pattern='_build/*' --recursive --command='if [ "$${watch_event_type}" == "created" -o "$${watch_event_type}" == "modified" ]; then make html ; osascript -l JavaScript refresh_safari.js; fi' --wait clean: -rm -rf $(BUILDDIR)/* diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst index 4169f3414..9eec6c638 100644 --- a/docs/plugins/convert.rst +++ b/docs/plugins/convert.rst @@ -109,7 +109,7 @@ Each entry in the ``formats`` map consists of a key (the name of the format) as well as the command and the possibly the file extension. ``extension`` is the filename extension to be used for newly transcoded files. If only the command is given as a string, the file extension -defaults to the format’s name. ``command`` is the command-line to use +defaults to the format's name. ``command`` is the command-line to use to transcode audio. The tokens ``$source`` and ``$dest`` in the command are replaced with the paths to the existing and new file. @@ -119,7 +119,9 @@ details have a look at the output of ``beet config -d``. For a one-command-fits-all solution use the ``convert.command`` and ``convert.extension`` options. If these are set, the formats are ignored -and the given command is used for all conversions.:: +and the given command is used for all conversions. + +:: convert: command: ffmpeg -i $source -y -vn -aq 2 $dest From 918afbed42ee7d2954351c80c0eeae1ffce5d219 Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Thu, 30 Oct 2014 16:16:05 -0700 Subject: [PATCH 12/15] Docs cleanup through ftinitle --- docs/plugins/echonest.rst | 25 +++++++++++++------------ docs/plugins/embedart.rst | 38 ++++++++++++++++++++------------------ docs/plugins/fetchart.rst | 26 ++++++++++++-------------- docs/plugins/ftintitle.rst | 15 ++++++++------- 4 files changed, 53 insertions(+), 51 deletions(-) diff --git a/docs/plugins/echonest.rst b/docs/plugins/echonest.rst index 8609c7807..dfef807e6 100644 --- a/docs/plugins/echonest.rst +++ b/docs/plugins/echonest.rst @@ -53,29 +53,30 @@ Finally, enable the ``echonest`` plugin in your configuration (see Configuration ------------- -Available options: +To configure the plugin, make an ``echonest:`` section in your configuration +file. The available options are: -- ``apikey``: set this option to specify your own EchoNest API key. - You can `apply for your own`_ for free from the EchoNest. - Default: beets includes its own Echo Nest API key. -- ``auto``: set it to ``no`` to disable automatic metadata fetching during - import. +- ``apikey``: A custom EchoNest API key. You can `apply for your own`_ for + free from the EchoNest. + Default: beets' own Echo Nest API key. +- ``auto``: Enable automatic metadata fetching during import. Default: ``yes``. - ``codegen``: Echoprint or ENMFP codegen binary path. - Default: ``None`` -- ``convert``: because the Echo Nest server only supports a limited range of + Default: look for the executable in your ``$PATH``. +- ``upload``: Send files to the Echo Nest server if they can not be identified + by other means. + Default: ``yes``. +- ``convert``: Because the Echo Nest server only supports a limited range of file formats, the plugin automatically converts unsupported files to ``ogg``. Default: ``yes``. -- ``truncate``: automatically truncates large files to their first 5 minutes +- ``truncate``: Automatically truncate large files to their first 5 minutes before uploading them to The Echo Nest server (as files with sizes greater than 50MB are rejected). Default: ``yes``. -- ``upload``: send files to the Echo Nest server if it can not be identified by - other means. - Default: ``yes``. .. _apply for your own: http://developer.echonest.com/account/register + Running Manually ---------------- diff --git a/docs/plugins/embedart.rst b/docs/plugins/embedart.rst index 1fa24f22f..172ac6550 100644 --- a/docs/plugins/embedart.rst +++ b/docs/plugins/embedart.rst @@ -7,14 +7,16 @@ You might want to embed the album art directly into each file's metadata. While this will take more space than the external-file approach, it is necessary for displaying album art in some media players (iPods, for example). -Usage ------ +Embedding Art Automatically +--------------------------- To automatically embed discovered album art into imported files, just enable the ``embedart`` plugin (see :doc:`/plugins/index`). You'll also want to enable the :doc:`/plugins/fetchart` to obtain the images to be embedded. Art will be embedded after each album is added to the library. +This behavior can be disabled with the ``auto`` config option (see below). + .. _image-similarity-check: Image Similarity @@ -39,26 +41,26 @@ This feature requires `ImageMagick`_. Configuration ------------- -Available options: +To configure the plugin, make an ``embedart:`` section in your configuration +file. The available options are: -- ``auto``: lets you disable automatic album art embedding when set to - ``no``. - Default: ``true`` -- ``compare_threshold``: how similar must candidate art be regarding to - embedded art to be written to the file (see :ref:`image-similarity-check`). - Default: ``0`` (disabled). -- ``ifempty``: set to 'yes' to avoid embedding album art for files that already - have one. +- ``auto``: Enable automatic album art embedding. + Default: ``yes``. +- ``compare_threshold``: How similar candidate art must be to + existing art to be written to the file (see :ref:`image-similarity-check`). + Default: 0 (disabled). +- ``ifempty``: Avoid embedding album art for files that already have art + embedded. Default: ``no``. -- ``maxwidth``: defines a maximum width to downscale images before embedding +- ``maxwidth``: A maximum width to downscale images before embedding them (the original image file is not altered). The resize operation reduces - image width to ``maxwidth`` pixels. The height is recomputed so that the - aspect ratio is preserved. See also :ref:`image-resizing` for further caveats - about image resizing. - Default: ``0`` (disabled). + image width to at most ``maxwidth`` pixels. The height is recomputed so that + the aspect ratio is preserved. See also :ref:`image-resizing` for further + caveats about image resizing. + Default: 0 (disabled). -Note: ``compare_threshold`` option requires `ImageMagick`_ , ``maxwidth`` -requires `ImageMagick`_ or `PIL`_ +Note: ``compare_threshold`` option requires `ImageMagick`_, and ``maxwidth`` +requires either `ImageMagick`_ or `PIL`_. .. _PIL: http://www.pythonware.com/products/pil/ .. _ImageMagick: http://www.imagemagick.org/ diff --git a/docs/plugins/fetchart.rst b/docs/plugins/fetchart.rst index dc9b9a4d8..63b9d896f 100644 --- a/docs/plugins/fetchart.rst +++ b/docs/plugins/fetchart.rst @@ -26,25 +26,24 @@ the :ref:`art-filename` config option. Configuration ------------- -Available options: +To configure the plugin, make a ``fetchart:`` section in your configuration +file. The available options are: -- ``auto``: set it to ``no`` to disable automatic album art fetching during - import. +- ``auto``: Enable automatic album art fetching during import. Default: ``yes``. -- ``cautious``: pick only trusted album arts by ignoring filenames that do not - contain one of ``cover_names`` keywords. +- ``cautious``: Pick only trusted album art by ignoring filenames that do not + contain one of the keywords in ``cover_names``. Default: ``no``. -- ``cover_names``: image filenames that contain word(s) of this list will be - picked primarily. +- ``cover_names``: Prioritize images containing words in this list. Default: ``['cover', 'front', 'art', 'album', 'folder']``. -- ``google_search``: set it to `yes` gather images from Google Images search. +- ``google_search``: Gather images from Google Image Search. Default: ``no``. -- ``maxwidth``: maximum image width to downscale fetched images if they are - too big. The resize operation reduces image width to ``maxwidth`` pixels. The - height is recomputed so that the aspect ratio is preserved. -- ``remote_priority``: query remote sources every time and use local image only +- ``maxwidth``: A maximum image width to downscale fetched images if they are + too big. The resize operation reduces image width to at most ``maxwidth`` + pixels. The height is recomputed so that the aspect ratio is preserved. +- ``remote_priority``: Query remote sources every time and use local image only as fallback. - Default: ``no``, remote (Web) art sources are only queried if no local art is + Default: ``no``; remote (Web) art sources are only queried if no local art is found in the filesystem. Here's an example that makes plugin select only images that contain *front* or @@ -55,7 +54,6 @@ Here's an example that makes plugin select only images that contain *front* or cover_names: front back - Manually Fetching Album Art --------------------------- diff --git a/docs/plugins/ftintitle.rst b/docs/plugins/ftintitle.rst index a45fb2285..3a378b08c 100644 --- a/docs/plugins/ftintitle.rst +++ b/docs/plugins/ftintitle.rst @@ -16,15 +16,16 @@ To use the ``ftintitle`` plugin, enable it in your configuration Configuration ------------- -Available options: +To configure the plugin, make a ``ftintitle:`` section in your configuration +file. The available options are: -- ``auto``: set it to ``no`` to disable plugin during import. +- ``auto``: Enable metadata rewriting during import. Default: ``yes``. -- ``drop``: remove featured artists entirely instead of adding them to the +- ``drop``: Remove featured artists entirely instead of adding them to the title field. - Default: ``no`` + Default: ``no``. -Running manually +Running Manually ---------------- From the command line, type:: @@ -34,7 +35,7 @@ From the command line, type:: The query is optional; if it's left off, the transformation will be applied to your entire collection. -Use the ``-d``flag to remove featured artists (equivalent of the ``drop`` -option). +Use the ``-d`` flag to remove featured artists (equivalent of the ``drop`` +config option). .. _MusicBrainz style: http://musicbrainz.org/doc/Style From 930581ac99f7764c23303ca97ef5c82de7d3b68b Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Thu, 30 Oct 2014 22:42:11 -0700 Subject: [PATCH 13/15] Finish the pass over all plugin docs --- docs/plugins/fuzzy.rst | 13 ++++--- docs/plugins/ihate.rst | 12 +++--- docs/plugins/importadded.rst | 10 +++-- docs/plugins/importfeeds.rst | 40 +++++++++---------- docs/plugins/keyfinder.rst | 20 +++++----- docs/plugins/lastgenre.rst | 49 +++++++++++++----------- docs/plugins/lyrics.rst | 22 ++++++----- docs/plugins/mbcollection.rst | 9 +++-- docs/plugins/missing.rst | 20 +++++----- docs/plugins/mpdstats.rst | 27 +++++++------ docs/plugins/mpdupdate.rst | 12 +++--- docs/plugins/play.rst | 18 +++++---- docs/plugins/replaygain.rst | 37 +++++++++--------- docs/plugins/scrub.rst | 5 ++- docs/plugins/smartplaylist.rst | 21 +++++----- docs/plugins/spotify.rst | 70 ++++++++++++---------------------- docs/plugins/the.rst | 33 ++++++++-------- docs/plugins/web.rst | 19 ++++----- docs/plugins/zero.rst | 10 +++-- 19 files changed, 219 insertions(+), 228 deletions(-) diff --git a/docs/plugins/fuzzy.rst b/docs/plugins/fuzzy.rst index 35b80b6b9..b21801544 100644 --- a/docs/plugins/fuzzy.rst +++ b/docs/plugins/fuzzy.rst @@ -14,10 +14,11 @@ You'll then be able to use the ``~`` prefix to use fuzzy matching:: Configuration ------------- -Available options: +To configure the plugin, make a ``fuzzy:`` section in your configuration +file. The available options are: -- ``threshold``: a value of 1.0 will show only perfect matches and a value of - 0.0 will match everything. - Default: ``0.7`` -- ``prefix``: character to use to designate fuzzy queries. - Default: ``~`` (needs to be escaped or quoted in most shells) +- ``threshold``: The "sensitivity" of the fuzzy match. A value of 1.0 will + show only perfect matches and a value of 0.0 will match everything. + Default: 0.7. +- ``prefix``: The character used to designate fuzzy queries. + Default: ``~``, which may need to be escaped in some shells. diff --git a/docs/plugins/ihate.rst b/docs/plugins/ihate.rst index f2099be8a..d4ed62a1b 100644 --- a/docs/plugins/ihate.rst +++ b/docs/plugins/ihate.rst @@ -12,13 +12,15 @@ To use the ``ihate`` plugin, enable it in your configuration (see Configuration ------------- -Available options: +To configure the plugin, make an ``ihate:`` section in your configuration +file. The available options are: -- ``skip``: never import matches. Default: ``[]`` -- ``warn``: print a warning message for matches. Default: ``[]`` +- ``skip``: Never import items and albums that match a query in this list. + Default: ``[]`` (empty list). +- ``warn``: Print a warning message for matches in this list of queries. + Default: ``[]``. - -Here's an example :: +Here's an example:: ihate: warn: diff --git a/docs/plugins/importadded.rst b/docs/plugins/importadded.rst index a320f4e3e..bfad97afd 100644 --- a/docs/plugins/importadded.rst +++ b/docs/plugins/importadded.rst @@ -1,7 +1,7 @@ ImportAdded Plugin ================== -This plugin is useful when an existing collection is imported +The ``importadded`` plugin is useful when an existing collection is imported and the time when albums and items were added should be preserved. To use the ``importadded`` plugin, enable it in your configuration (see @@ -39,10 +39,12 @@ of album directories on disk aren't preserved. Configuration ------------- -Available option: +To configure the plugin, make an ``importadded:`` section in your +configuration file. There is one option available: -- ``preserve_mtimes`` - Default: ``no`` +- ``preserve_mtimes``: After writing files, re-set their mtimes to their + original value. + Default: ``no``. Reimport -------- diff --git a/docs/plugins/importfeeds.rst b/docs/plugins/importfeeds.rst index 97632f498..c85c10ca0 100644 --- a/docs/plugins/importfeeds.rst +++ b/docs/plugins/importfeeds.rst @@ -9,33 +9,31 @@ To use the ``importfeeds`` plugin, enable it in your configuration Configuration ------------- -Available options: +To configure the plugin, make an ``importfeeds:`` section in your +configuration file. The available options are: -- ``absolute_path`` option can be set to use absolute paths instead of relative - paths. Some applications may need this to work properly. +- ``absolute_path``: Use absolute paths instead of relative paths. Some + applications may need this to work properly. Default: ``no``. -- ``dir`` option can be set to specify another output folder than the default - library directory. - Default: ``None``. -- ``formats`` option can be set to select desired output type(s): - - - ``m3u``: catalog the imports in a centralized playlist. - - ``m3u_multi``: create a new playlist for each import (uniquely named by - appending the date and track/album name). - - ``link``: create a symlink for each imported item. This is the - recommended setting to propagate beets imports to your iTunes library: just - drag and drop the ``dir`` folder on the iTunes dock icon. - - ``echo``: do not write a playlist file at all, but echo a list of new - file paths to the terminal. - - Default: ``[]``. -- ``m3u_name``: playlist name used by ``m3u`` format. +- ``dir``: The output directory. + Default: Your beets library directory. +- ``formats``: Select the kind of output. Use one or more of: + - ``m3u``: Catalog the imports in a centralized playlist. + - ``m3u_multi``: Create a new playlist for each import (uniquely named by + appending the date and track/album name). + - ``link``: Create a symlink for each imported item. This is the + recommended setting to propagate beets imports to your iTunes library: + just drag and drop the ``dir`` folder on the iTunes dock icon. + - ``echo``: Do not write a playlist file at all, but echo a list of new + file paths to the terminal. + Default: None. +- ``m3u_name``: Playlist name used by the ``m3u`` format. Default: ``imported.m3u``. -- ``relative_to`` option can be set to make the m3u paths relative to another +- ``relative_to``: Make the m3u paths relative to another folder than where the playlist is being written. If you're using importfeeds to generate a playlist for MPD, you should set this to the root of your music library. - Default: ``None``. + Default: None. Here's an example configuration for this plugin:: diff --git a/docs/plugins/keyfinder.rst b/docs/plugins/keyfinder.rst index b35655cba..04a91ac19 100644 --- a/docs/plugins/keyfinder.rst +++ b/docs/plugins/keyfinder.rst @@ -3,7 +3,7 @@ Key Finder Plugin The `keyfinder` plugin uses the `KeyFinder`_ program to detect the musical key of track from its audio data and store it in the -'initial_key' field of you database. It does so +`initial_key` field of your database. It does so automatically when importing music or through the ``beet keyfinder [QUERY]`` command. @@ -13,18 +13,20 @@ To use the ``keyfinder`` plugin, enable it in your configuration (see Configuration ------------- -Available options: +To configure the plugin, make a ``keyfinder:`` section in your +configuration file. The available options are: -- ``bin``: the name of the `KeyFinder` program on your system or - a path to the binary. If you installed the `KeyFinder`_ GUI on a Mac, for +- ``bin``: The name of the `KeyFinder`_ program on your system or + a path to the binary. If you installed the KeyFinder GUI on a Mac, for example, you want something like ``/Applications/KeyFinder.app/Contents/MacOS/KeyFinder``. - Default: ``KeyFinder``. -- ``auto``: if set to `yes`, the plugin will analyze every file on + Default: ``KeyFinder`` (i.e., search for the program in your ``$PATH``). +- ``auto``: Analyze every file on import. Otherwise, you need to use the ``beet keyfinder`` command - explicitly. Default: ``yes``. -- ``overwrite``: if set to ``no``, the import hook and the command will skip - any file that already has an 'initial_key' in the database. + explicitly. + Default: ``yes``. +- ``overwrite``: Calculate a key even for files that already have an + `initial_key` value. Default: ``no``. .. _KeyFinder: http://www.ibrahimshaath.co.uk/keyfinder/ diff --git a/docs/plugins/lastgenre.rst b/docs/plugins/lastgenre.rst index d998d19ab..f6723572b 100644 --- a/docs/plugins/lastgenre.rst +++ b/docs/plugins/lastgenre.rst @@ -27,7 +27,7 @@ The plugin chooses genres based on a *whitelist*, meaning that only certain tags can be considered genres. This way, tags like "my favorite music" or "seen live" won't be considered genres. The plugin ships with a fairly extensive `internal whitelist`_, but you can set your own in the config file using the -``whitelist`` configuration value or go for no whitelist altogether by setting +``whitelist`` configuration value or forgo a whitelist altogether by setting the option to `false`. The genre list file should contain one genre per line. Blank lines are ignored. @@ -80,29 +80,34 @@ the ``min_weight`` config option. Configuration ------------- -Available options: +To configure the plugin, make a ``lastgenre:`` section in your +configuration file. The available options are: -- ``auto``: set it to ``no`` to disable automatic genre fetching during import. +- ``auto``: Fetch genres automatically during import. + Default: ``yes``. +- ``canonical``: Use a canonicalization tree. Setting this to ``yes`` will use + a built-in tree. You can also set it to a path, like the ``whitelist`` + config value, to use your own tree. + Default: ``no`` (disabled). +- ``count``: Number of genres to fetch. + Default: 1 +- ``fallback``: A string if to use a fallback genre when no genre is found. + You can use the empty string ``''`` to reset the genre. + Default: None. +- ``force``: By default, beets will always fetch new genres, even if the files + already have one. To instead leave genres in place in when they pass the + whitelist, set the ``force`` option to ``no``. + Default: ``yes``. +- ``min_weight``: Minimum popularity factor below which genres are discarded. + Default: 10. +- ``source``: Which entity to look up in Last.fm. Can be + either ``artist``, ``album`` or ``track``. + Default: ``album``. +- ``separator``: A separator for multiple genres. + Default: ``', '``. +- ``whitelist``: The filename of a custom genre list, ``yes`` to use + the internal whitelist, or ``no`` to consider all genres valid. Default: ``yes``. -- ``canonical``: setting this value to ``true`` will use a built-in canonicalization - tree. You can also set it to a path, just like the ``whitelist`` config value, - to use your own tree. Default: ``no`` -- ``count``: number of genres to fetch. Default: ``1`` -- ``fallback``: by default, the file will be left unchanged when no genre is - found. Specify a string if you prefer to use a fallback genre. You can use the - empty string ``''` to reset the genre. Default: ``None`` -- ``force``: by default, beets will always fetch new genres, even if the files already have - once. To instead leave genres in place in when they pass the whitelist, set - the ``force`` option to ``no``. Default: ``yes`` -- ``min_weight``: minimum popularity factor below which genres are discarded. - Default: ``10`` -- ``source``: defines on which entity to perform Last.fm tags lookup. Can be - either ``artist``, ``album`` or ``track``. Default: ``album`` -- ``separator``: genres separator string - Default: ``u', '`` -- ``whitelist``: give it a custom genre list filepath or set it to 'yes' to use - internal whitelist. If set to 'no' then all genres are considered valids. - Default: ``yes`` Running Manually ---------------- diff --git a/docs/plugins/lyrics.rst b/docs/plugins/lyrics.rst index 3d5f265a7..138f83655 100644 --- a/docs/plugins/lyrics.rst +++ b/docs/plugins/lyrics.rst @@ -23,18 +23,20 @@ the files' tags. Configuration ------------- -Available options: +To configure the plugin, make a ``lyrics:`` section in your +configuration file. The available options are: -- ``auto``: set it to ``no`` to disable automatic lyrics fetching during import. +- ``auto``: Fetch lyrics automatically during import. Default: ``yes``. -- ``fallback``: by default, the file will be left unchanged when no lyrics are - found. Use the empty string ``''`` to reset the genre in such a case. - Default: ``None``; -- ``google_API_key``: your Google API key. - Default: ``None``; -- ``google_engine_ID``: custom search engine to use. - Default: ``009217259823014548361:lndtuqkycfu``, beets custom search engine - that gathers list of sources known to be scrapeable. +- ``fallback``: By default, the file will be left unchanged when no lyrics are + found. Use the empty string ``''`` to reset the lyrics in such a case. + Default: None. +- ``google_API_key``: Your Google API key (to enable the Google Custom Search + backend). + Default: None. +- ``google_engine_ID``: The custom search engine to use. + Default: The beets custom search engine, which gathers a list of sources + known to be scrapeable. Here's an example of ``config.yaml``:: diff --git a/docs/plugins/mbcollection.rst b/docs/plugins/mbcollection.rst index f948c3652..3c176521f 100644 --- a/docs/plugins/mbcollection.rst +++ b/docs/plugins/mbcollection.rst @@ -23,8 +23,9 @@ profile first. Configuration ------------- -Available option: +To configure the plugin, make a ``mbcollection:`` section in your +configuration file. There is one option available: -- ``auto``: if set to ``yes``, the plugin will automatically amend your - MusicBrainz collection whenever you import a new album. - Default: ``false`` +- ``auto``: Automatically amend your MusicBrainz collection whenever you + import a new album. + Default: ``no``. diff --git a/docs/plugins/missing.rst b/docs/plugins/missing.rst index 5062f298f..1719a82a6 100644 --- a/docs/plugins/missing.rst +++ b/docs/plugins/missing.rst @@ -6,39 +6,39 @@ and lists, for every album in your collection, which or how many tracks are missing. Listing missing files requires one network call to MusicBrainz. Merely counting missing files avoids any network calls. - Usage ------- +----- Add the ``missing`` plugin to your configuration (see :ref:`using-plugins`). By default, the ``beet missing`` command lists the names of tracks that your library is missing from each album. You can customize the output format, count the number of missing tracks per album, or total up the number of missing -tracks over your whole library, using command-line switches :: +tracks over your whole library, using command-line switches:: -f FORMAT, --format=FORMAT print with custom FORMAT -c, --count count missing tracks per album -t, --total count total of missing tracks - ... or by editing corresponding options. +…or by editing corresponding options. Configuration ------------- -Available options: +To configure the plugin, make a ``missing:`` section in your +configuration file. The available options are: -- ``count`` prints a count of missing tracks per album, with ``format`` +- ``count``: Print a count of missing tracks per album, with ``format`` defaulting to ``$albumartist - $album: $missing``. Default: ``no``. -- ``format`` lets you specify a specific format with which to print every - track. This uses the same template syntax as beets’ +- ``format``: A specific format with which to print every + track. This uses the same template syntax as beets' :doc:`path formats `. The usage is inspired by, and therefore similar to, the :ref:`list ` command. Default: :ref:`list_format_item`. -- ``total` prints a single count of missing tracks in all albums. - Default: ``false``. +- ``total``: Print a single count of missing tracks in all albums. + Default: ``no``. Here's an example :: diff --git a/docs/plugins/mpdstats.rst b/docs/plugins/mpdstats.rst index d0ccc363a..bfd1ef53c 100644 --- a/docs/plugins/mpdstats.rst +++ b/docs/plugins/mpdstats.rst @@ -35,24 +35,23 @@ Use the ``mpdstats`` command to fire it up:: Configuration ------------- -Available options: +To configure the plugin, make an ``mpd:`` section in your +configuration file. The available options are: -- ``host``: mpd server name. +- ``host``: The MPD server hostname. Default: ``localhost``. -- ``music_directory``: if your MPD library is at another location than the +- ``port``: The MPD server port. + Default: 6600. +- ``password``: The MPD server password. + Default: None. +- ``music_directory``: If your MPD library is at a different location from the beets library (e.g., because one is mounted on a NFS share), specify the path here. - By default it uses beets library directory. -- ``password``: mpd server password. - Default: ``u''`` -- ``port``: mpd server port. - Default: ``6600``. -- ``rating``: set it to ``no`` if you don't want the plugin to update the - rating. - Default: ``yes`` -- ``rating_mix``: change it to tune the way rating is calculated. See below for - details. - Default: ``0.75`` + Default: The beets library directory. +- ``rating``: Enable rating updates. + Default: ``yes``. +- ``rating_mix``: Tune the way rating is calculated (see below). + Default: 0.75. A Word on Ratings ----------------- diff --git a/docs/plugins/mpdupdate.rst b/docs/plugins/mpdupdate.rst index 1dad856df..98e8fe5ca 100644 --- a/docs/plugins/mpdupdate.rst +++ b/docs/plugins/mpdupdate.rst @@ -28,11 +28,11 @@ socket.) Configuration ------------- -Available options: +The available options under teh ``mpd:`` section are: -- ``host``: mpd server name. +- ``host``: The MPD server name. Default: ``localhost``. -- ``password``: mpd server password. - Default: ``u''`` -- ``port``: mpd server port. - Default: ``6600``. +- ``password``: The MPD server password. + Default: None. +- ``port``: The MPD server port. + Default: 6600. diff --git a/docs/plugins/play.rst b/docs/plugins/play.rst index 595c7db0d..097b650f2 100644 --- a/docs/plugins/play.rst +++ b/docs/plugins/play.rst @@ -32,13 +32,15 @@ debug. Configuration ------------- -- ``command``: command used to open the playlist. +To configure the plugin, make a ``play:`` section in your +configuration file. The available options are: + +- ``command``: The command used to open the playlist. Default: ``open`` on OS X, ``xdg-open`` on other Unixes and ``start`` on Windows. -- ``relative_to``: set that option if you want to emit relative paths by giving - the refefence folder (eg '/my/music/folder') - Default: ``None`` -- ``use_folders``: when using the ``-a`` option, the m3u will have the paths to - each track on the matched albums. Set it to ``yes`` to store paths to folders - instead. - Default: ``no`` +- ``relative_to``: Emit paths relative to base directory. + Default: None. +- ``use_folders``: When using the ``-a`` option, the m3u will contain the + paths to each track on the matched albums. Enable this option to + store paths to folders instead. + Default: ``no``. diff --git a/docs/plugins/replaygain.rst b/docs/plugins/replaygain.rst index 75b3c4d15..5b5420025 100644 --- a/docs/plugins/replaygain.rst +++ b/docs/plugins/replaygain.rst @@ -65,34 +65,31 @@ you can configure the path explicitly like so:: Configuration ------------- -Available options: +To configure the plugin, make a ``replaygain:`` section in your +configuration file. The available options are: - -- ``auto``: set it to ``no`` to disable replaygain analysis during import. +- ``auto``: Enable ReplayGain analysis during import. Default: ``yes``. -- ``backend``: which backend to use for ReplayGain analysis. - Must be one of ``gstreamer`` or ``command``. - Default: ``command`` -- ``overwrite``: by default, files that already have ReplayGain tags will not - be re-analyzed. Set to ``yes`` if you want to analyze *every* file on import. +- ``backend``: The analysis backend; either ``gstreamer`` or ``command``. + Default: ``command``. +- ``overwrite``: Re-analyze files that already have ReplayGain tags. Default: ``no``. -- ``targetlevel``: specify a number of decibels for the target loudness level - Default: ``89`` +- ``targetlevel``: A number of decibels for the target loudness level. + Default: 89. - These options only work with the "command" backend: +These options only work with the "command" backend: -- ``apply``: if you use a player that does not support ReplayGain +- ``apply``: If you use a player that does not support ReplayGain specifications, you can force the volume normalization by applying the gain to the file via the ``apply`` option. This is a lossless and reversible operation with no transcoding involved. -- ``command``: use it to explicitely enter path to ``mp3gain`` or ``aacgain`` - executable, if beets cannot find it by itself. - For example: '/Applications/MacMP3Gain.app/Contents/Resources/aacgain' - Default: ``u''`` -- ``noclip``: the use of ReplayGain can cause clipping if the average volume - of a song is below the target level. By default, a "prevent clipping" option - named ``noclip`` is enabled to reduce the amount of ReplayGain adjustment to - whatever amount would keep clipping from occurring. + Default: ``no``. +- ``command``: The path to the ``mp3gain`` or ``aacgain`` executable (if beets + cannot find it by itself). + For example: ``/Applications/MacMP3Gain.app/Contents/Resources/aacgain``. + Default: Search in your ``$PATH``. +- ``noclip``: Reduce the amount of ReplayGain adjustment to whatever amount + would keep clipping from occurring. Default: ``yes``. Manual Analysis diff --git a/docs/plugins/scrub.rst b/docs/plugins/scrub.rst index 4760df9d8..0e7cbf4bd 100644 --- a/docs/plugins/scrub.rst +++ b/docs/plugins/scrub.rst @@ -34,7 +34,8 @@ whatsoever. Configuration ------------- -Available option : +To configure the plugin, make a ``scrub:`` section in your +configuration file. There is one option: -- ``auto``: set it to ``no`` to disable metadata stripping during import. +- ``auto``: Enable metadata stripping during import. Default: ``yes``. diff --git a/docs/plugins/smartplaylist.rst b/docs/plugins/smartplaylist.rst index 0a1db5b3a..fefc1be30 100644 --- a/docs/plugins/smartplaylist.rst +++ b/docs/plugins/smartplaylist.rst @@ -69,14 +69,15 @@ plugin. Configuration ------------- -Available options: +To configure the plugin, make a ``smartplaylist:`` section in your +configuration file. In addition to the ``playlists`` described above, the +other configuration options are: -- ``auto``: set it to ``no`` to tell beets to stop regenerate the playlist - after every database change. - Default: ``yes`` -- ``playlist_dir``: where the generated playlist files will be put. - Default: ``u'.'`` -- ``relative_to``: if you intend to use this plugin to generate playlists for - MPD, make it points to your MPD music directory. - Default: ``None``, which means that absolute paths to your music files will - be generated. +- ``auto``: Regenerate the playlist after every database change. + Default: ``yes``. +- ``playlist_dir``: Where to put the generated playlist files. + Default: The current working directory (i.e., ``'.'``). +- ``relative_to``: Generate paths in the playlist files relative to a base + directory. If you intend to use this plugin to generate playlists for MPD, + point this to your MPD music directory. + Default: Use absolute paths. diff --git a/docs/plugins/spotify.rst b/docs/plugins/spotify.rst index 8b7bf2539..88d8ddb60 100644 --- a/docs/plugins/spotify.rst +++ b/docs/plugins/spotify.rst @@ -40,61 +40,39 @@ Command-line options include: Configuration ------------- -The default options should work as-is, but there are some options you can put in config.yaml: - -* ``mode``: one of the following : - - - "list": the default mode is to print out the playlist as a list of links. - This list can then be pasted in to a new or existing Spotify playlist. - - "open": This mode actually sends a link to your default browser with - instructions to open Spotify with the playlist you created. Until this - has been tested on all platforms, it will remain optional. +The default options should work as-is, but there are some options you can put +in config.yaml under the ``spotify:`` section: +* ``mode``: One of the following: + - ``list``: Print out the playlist as a list of links. This list can then + be pasted in to a new or existing Spotify playlist. + - ``open``: This mode actually sends a link to your default browser with + instructions to open Spotify with the playlist you created. Until this + has been tested on all platforms, it will remain optional. Default: ``list``. -* ``region_filter``: use the 2-character country abbreviation to limit results +* ``region_filter``: A two-character country abbreviation, to limit results to that market. - Default: ``None`` -* ``show_failures``: show the artist/album/track for each lookup that does not - return a Spotify ID (and therefore cannot be added to a playlist). - Default: ``no`` -* ``tiebreak``: how to choose the track if there is more than one identical - result. For example, there might be multiple releases of the same album. - Currently, this defaults to "popularity", "first" simply chooses the first - in the list returned by Spotify. - Default: ``popularity`` -* ``regex``: an array of regex transformations to perform on the + Default: None. +* ``show_failures``: List each lookup that does not return a Spotify ID (and + therefore cannot be added to a playlist). + Default: ``no``. +* ``tiebreak``: How to choose the track if there is more than one identical + result. For example, there might be multiple releases of the same album. + The options are ``popularity`` and ``first`` (to just choose the first match + returned). + Default: ``popularity``. +* ``regex``: An array of regex transformations to perform on the track/album/artist fields before sending them to Spotify. Can be useful for changing certain abbreviations, like ft. -> feat. See the examples below. - Default: ``[]`` -* ``artist_field`` / ``album_field`` / ``track_field``: these allow the user - to choose a different field to send to Spotify when looking up the track, - album and artist. Most users will not want to change this. + Default: None. - -Example Configuration ---------------------- - -:: +Here's an example:: spotify: - # Default is list, shows the plugin output. Open attempts to open - # directly in Spotify (only tested on Mac). - mode: "open" - - # Filter tracks by only that market (2-letter code) - region_filter: "US" - - # Display the tracks that did not match a Spotify ID. + mode: open + region_filter: US show_faiulres: on - - # Need to break ties when then are multiple tracks. Default is - popularity. - tiebreak: "first" - - # Which beets fields to use for lookups. - artist_field: "albumartist" - album_field: "album" - track_field: "title" + tiebreak: first regex: [ { diff --git a/docs/plugins/the.rst b/docs/plugins/the.rst index dd16c7c7a..9f1ce95c0 100644 --- a/docs/plugins/the.rst +++ b/docs/plugins/the.rst @@ -3,7 +3,7 @@ The Plugin The ``the`` plugin allows you to move patterns in path formats. It's suitable, for example, for moving articles from string start to the end. This is useful -for quick search on filesystems and generally looks good. Plugin DOES NOT +for quick search on filesystems and generally looks good. Plugin does not change tags. By default plugin supports English "the, a, an", but custom regexp patterns can be added by user. How it works:: @@ -11,8 +11,8 @@ regexp patterns can be added by user. How it works:: A Band -> Band, A An Orchestra -> Orchestra, An -Enable the ``the`` plugin (see :doc:`/plugins/index`) and then make use of a -template function called ``%the`` for use in path format expressions:: +To use the ``the`` plugin, enable it (see :doc:`/plugins/index`) and then use +a template function called ``%the`` in path format expressions:: paths: default: %the{$albumartist}/($year) $album/$track $title @@ -23,20 +23,21 @@ but you can override these defaults to make more complex changes. Configuration ------------- -Available options: +To configure the plugin, make a ``the:`` section in your +configuration file. The available options are: -- ``a``: handle "A/An" moves - Default: ``yes`` -- ``format``: format string with *{0}: part w/o article* and *{1} - article*. - Spaces are already trimmed from ends of both parts. - Default: ``u'{0}, {1}'`` -- ``strip``: - Default: ``no`` -- ``patterns``: custom regexp patterns, space-separated. Custom patterns are +- ``a``: Handle "A/An" moves. + Default: ``yes``. +- ``the``: handle "The" moves. + Default: ``yes``. +- ``patterns``: Custom regexp patterns, space-separated. Custom patterns are case-insensitive regular expressions. Patterns can be matched anywhere in the string (not just the beginning), so use ``^`` if you intend to match leading words. - Default: ``[]`` -- ``the``: handle "The" moves - Default: ``yes`` - + Default: ``[]``. +- ``strip``: Remove the article altogether instead of moving it to the end. + Default: ``no``. +- ``format``: A Python format string for the output. Use ``{0}`` to indicate + the part without the article and ``{1}`` for the article. + Spaces are already trimmed from ends of both parts. + Default: ``'{0}, {1}'``. diff --git a/docs/plugins/web.rst b/docs/plugins/web.rst index 1804e7deb..e1be24a9b 100644 --- a/docs/plugins/web.rst +++ b/docs/plugins/web.rst @@ -35,12 +35,8 @@ You can also specify the hostname and port number used by the Web server. These can be specified on the command line or in the ``[web]`` section of your :doc:`configuration file `. -On the command line, use ``beet web [HOSTNAME] [PORT]``. In the config file, use -something like this:: - - web: - host: 127.0.0.1 - port: 8888 +On the command line, use ``beet web [HOSTNAME] [PORT]``. Or the configuration +options below. Usage ----- @@ -53,12 +49,13 @@ Type queries into the little search box. Double-click a track to play it with Configuration ------------- -Available options: +To configure the plugin, make a ``web:`` section in your +configuration file. The available options are: -- ``host``: server hostname - Default: ``u''`` -- ``port``: server port - Default: `8337` +- ``host``: The server hostname. + Default: Bind to all interfaces. +- ``port``: The server port. + Default: 8337. Implementation -------------- diff --git a/docs/plugins/zero.rst b/docs/plugins/zero.rst index 781f95b31..6a857e3de 100644 --- a/docs/plugins/zero.rst +++ b/docs/plugins/zero.rst @@ -12,11 +12,13 @@ To use the ``zero`` plugin, enable the plugin in your configuration Configuration ------------- -Available option : +Make a ``zero:`` section in your configuration file. You can specify the +fields to nullify and the conditions for nullifying them: -- ``fields``: whitespace-separated list of fields to change. You can get the - list of available fields by running ``beet fields``. To conditionally filter - a field, use ``field: [regexp, regexp]`` to specify regular expressions. +* Set ``fields`` to a whitespace-separated list of fields to change. You can + get the list of all available fields by running ``beet fields``. +* To conditionally filter a field, use ``field: [regexp, regexp]`` to specify + regular expressions. For example:: From e80f84e666e0f5d98de1e464369c8940ded3d293 Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Fri, 31 Oct 2014 09:48:19 -0700 Subject: [PATCH 14/15] Typo fixes --- docs/plugins/bucket.rst | 2 +- docs/plugins/convert.rst | 6 +++--- docs/plugins/mpdupdate.rst | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/plugins/bucket.rst b/docs/plugins/bucket.rst index a325d4552..254ebab4a 100644 --- a/docs/plugins/bucket.rst +++ b/docs/plugins/bucket.rst @@ -65,6 +65,6 @@ Here's an example:: bucket_alpha_regex: 'A - D': ^[0-9a-dA-D…äÄ] -THis configuration creates five-year ranges for any input year. +This configuration creates five-year ranges for any input year. The *A - D* bucket now matches also all artists starting with ä or Ä and 0 to 9 and … (ellipsis). The other alpha buckets work as ranges. diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst index 9eec6c638..81b9af7da 100644 --- a/docs/plugins/convert.rst +++ b/docs/plugins/convert.rst @@ -70,10 +70,10 @@ file. The available options are: as mp3, ogg vorbis, etc.---makes little sense as they will decrease quality even further. If set to ``yes``, lossy files are always copied. Default: ``no``. -- ``paths``: Lets you specify the directory structure and naming scheme for the - converted files. Use the same format as the top-level ``paths`` section (see +- ``paths``: The directory structure and naming scheme for the converted + files. Uses the same format as the top-level ``paths`` section (see :ref:`path-format-config`). - By default, the plugin reuses your top-level path format settings. + Default: Reuse your top-level path format settings. - ``quiet``: Prevent the plugin from announcing every file it processes. Default: ``false``. - ``threads``: The number of threads to use for parallel encoding. diff --git a/docs/plugins/mpdupdate.rst b/docs/plugins/mpdupdate.rst index 98e8fe5ca..b9eac0baa 100644 --- a/docs/plugins/mpdupdate.rst +++ b/docs/plugins/mpdupdate.rst @@ -28,7 +28,7 @@ socket.) Configuration ------------- -The available options under teh ``mpd:`` section are: +The available options under the ``mpd:`` section are: - ``host``: The MPD server name. Default: ``localhost``. From d4836beffb579ccde905bcb0621e15dfeb94c893 Mon Sep 17 00:00:00 2001 From: Fabrice Laporte Date: Fri, 31 Oct 2014 22:06:56 +0100 Subject: [PATCH 15/15] docs: make Travis happy --- docs/plugins/importfeeds.rst | 1 + docs/plugins/spotify.rst | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/plugins/importfeeds.rst b/docs/plugins/importfeeds.rst index c85c10ca0..04dad1206 100644 --- a/docs/plugins/importfeeds.rst +++ b/docs/plugins/importfeeds.rst @@ -26,6 +26,7 @@ configuration file. The available options are: just drag and drop the ``dir`` folder on the iTunes dock icon. - ``echo``: Do not write a playlist file at all, but echo a list of new file paths to the terminal. + Default: None. - ``m3u_name``: Playlist name used by the ``m3u`` format. Default: ``imported.m3u``. diff --git a/docs/plugins/spotify.rst b/docs/plugins/spotify.rst index 88d8ddb60..8b5bb1864 100644 --- a/docs/plugins/spotify.rst +++ b/docs/plugins/spotify.rst @@ -49,6 +49,7 @@ in config.yaml under the ``spotify:`` section: - ``open``: This mode actually sends a link to your default browser with instructions to open Spotify with the playlist you created. Until this has been tested on all platforms, it will remain optional. + Default: ``list``. * ``region_filter``: A two-character country abbreviation, to limit results to that market.