diff --git a/docs/Makefile b/docs/Makefile index 3c8aa63d6..fd1707f27 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='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/changelog.rst b/docs/changelog.rst index f62d7c14a..d6db832f0 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -593,7 +593,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. @@ -659,7 +659,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 @@ -1015,7 +1015,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 @@ -1039,7 +1039,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. @@ -1138,7 +1138,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. @@ -1204,7 +1204,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 @@ -1234,7 +1234,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. diff --git a/docs/plugins/beatport.rst b/docs/plugins/beatport.rst index 0940ff501..b10ee8c59 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 ``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:: pip install requests diff --git a/docs/plugins/bpd.rst b/docs/plugins/bpd.rst index 919a45ec3..b5082b220 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 ``bpd`` plugin, first enable it in your configuration (see +:ref:`using-plugins`). Then, you can run BPD by invoking:: $ beet bpd @@ -69,10 +67,22 @@ 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 +------------- + +To configure the plugin, make a ``bpd:`` section in your configuration file. +The available options are: + +- ``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:: bpd: host: 127.0.0.1 @@ -83,13 +93,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..ce1f62298 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 ``bpm`` 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..254ebab4a 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 @@ -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 ``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:: paths: @@ -25,25 +26,45 @@ 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 +To configure the plugin, make a ``bucket:`` section in your configuration file. +The available options are: -The above configuration creates five-year ranges for any input year. +- ``bucket_alpha``: Ranges to use for all substitutions occurring on textual + fields. + 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: 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`` -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). +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/chroma.rst b/docs/plugins/chroma.rst index 511bde4b6..c770fe698 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 ``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 @@ -101,16 +100,20 @@ 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:: +.. _submitfp: + +Configuration +------------- + +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 -.. _submitfp: - 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..81b9af7da 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 ``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. .. _FFmpeg: http://ffmpeg.org @@ -50,35 +50,37 @@ them. Configuration ------------- -The plugin offers several configuration options, all of which live under the -``convert:`` section: +To configure the plugin, make a ``convert:`` section in your configuration +file. The available options are: -* ``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 +- ``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``: 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. -* ``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 - 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. + 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``: 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`). + 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. + 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: @@ -87,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 @@ -105,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. @@ -114,8 +118,10 @@ 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 -and the given command is used for all conversions.:: +``convert.extension`` options. If these are set, the formats are ignored +and the given command is used for all conversions. + +:: convert: command: ffmpeg -i $source -y -vn -aq 2 $dest diff --git a/docs/plugins/discogs.rst b/docs/plugins/discogs.rst index 31d111dd6..7c263f324 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 ``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 b6be0a16a..08379451f 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 ``duplicates`` 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,52 @@ 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 -~~~~~~ +To configure the plugin, make a ``duplicates:`` section in your configuration +file. The available options mirror the command-line options: -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``: List duplicate albums instead of tracks. + Default: ``no``. +- ``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``: 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``. +- ``delete``: Removes matched items from the library and from the disk. + Default: ``no`` +- ``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``: List every track or album that has duplicates, not just the + duplicates themselves. + Default: ``no``. +- ``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``: 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``. +- ``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 -------- @@ -150,7 +96,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 +109,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 +128,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..dfef807e6 100644 --- a/docs/plugins/echonest.rst +++ b/docs/plugins/echonest.rst @@ -41,63 +41,45 @@ 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, enable the ``echonest`` plugin 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:: +To configure the plugin, make an ``echonest:`` section in your configuration +file. The available options are: - 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``: 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: 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 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``. .. _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 deleted file mode 100644 index 2436044ab..000000000 --- a/docs/plugins/echonest_tempo.rst +++ /dev/null @@ -1,73 +0,0 @@ -EchoNest 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/ - -Configuring ------------ - -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:: - - 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 - -.. _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 387d6a3ff..172ac6550 100644 --- a/docs/plugins/embedart.rst +++ b/docs/plugins/embedart.rst @@ -7,13 +7,11 @@ 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. - 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 ``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. @@ -40,6 +38,34 @@ number, the more similar the images must be. This feature requires `ImageMagick`_. +Configuration +------------- + +To configure the plugin, make an ``embedart:`` section in your configuration +file. The available options are: + +- ``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``: A maximum width to downscale images before embedding + them (the original image file is not altered). The resize operation reduces + 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`_, and ``maxwidth`` +requires either `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 +85,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..63b9d896f 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 @@ -23,11 +23,36 @@ 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 +------------- + +To configure the plugin, make a ``fetchart:`` section in your configuration +file. The available options are: + +- ``auto``: Enable automatic album art fetching during import. + Default: ``yes``. +- ``cautious``: Pick only trusted album art by ignoring filenames that do not + contain one of the keywords in ``cover_names``. + Default: ``no``. +- ``cover_names``: Prioritize images containing words in this list. + Default: ``['cover', 'front', 'art', 'album', 'folder']``. +- ``google_search``: Gather images from Google Image Search. + Default: ``no``. +- ``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 + 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 +72,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 +99,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 +113,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..5cb6ccb76 100644 --- a/docs/plugins/fromfilename.rst +++ b/docs/plugins/fromfilename.rst @@ -9,6 +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, just enable it by putting ``fromfilename`` on the -``plugins:`` line in your config file. There are currently no configuration -options. +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 c8bf48f46..3a378b08c 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 moves "featured" artists from the ``artist`` field to the ``title`` field. According to `MusicBrainz style`_, featured artists are part of the artist @@ -10,17 +10,32 @@ 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 ``ftintitle`` plugin, enable it in your configuration +(see :ref:`using-plugins`). + +Configuration +------------- + +To configure the plugin, make a ``ftintitle:`` section in your configuration +file. The available options are: + +- ``auto``: Enable metadata rewriting 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`` +config option). .. _MusicBrainz style: http://musicbrainz.org/doc/Style diff --git a/docs/plugins/fuzzy.rst b/docs/plugins/fuzzy.rst index 3f4115168..b21801544 100644 --- a/docs/plugins/fuzzy.rst +++ b/docs/plugins/fuzzy.rst @@ -1,25 +1,24 @@ Fuzzy Search Plugin =================== -The ``fuzzy`` plugin provides a prefixed query that search 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. -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: '@' +To configure the plugin, make a ``fuzzy:`` section in your configuration +file. The available options are: -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``: 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 7cb6b4040..d4ed62a1b 100644 --- a/docs/plugins/ihate.rst +++ b/docs/plugins/ihate.rst @@ -6,18 +6,28 @@ 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 ``ihate`` plugin, enable it in your configuration (see +:ref:`using-plugins`). + +Configuration +------------- + +To configure the plugin, make an ``ihate:`` section in your configuration +file. The available options are: + +- ``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:: 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..bfad97afd 100644 --- a/docs/plugins/importadded.rst +++ b/docs/plugins/importadded.rst @@ -4,6 +4,12 @@ ImportAdded Plugin 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 +: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. @@ -16,10 +22,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 +36,18 @@ 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 +------------- + +To configure the plugin, make an ``importadded:`` section in your +configuration file. There is one option available: + +- ``preserve_mtimes``: After writing files, re-set their mtimes to their + original value. + 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..04dad1206 100644 --- a/docs/plugins/importfeeds.rst +++ b/docs/plugins/importfeeds.rst @@ -1,30 +1,40 @@ 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 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 ``importfeeds`` 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. +To configure the plugin, make an ``importfeeds:`` section in your +configuration file. The available options are: -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``: Use absolute paths instead of relative paths. Some + applications may need this to work properly. + Default: ``no``. +- ``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. -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. 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: None. +- ``m3u_name``: Playlist name used by the ``m3u`` format. + Default: ``imported.m3u``. +- ``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. Here's an example configuration for this plugin:: diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index 2b8b48ba3..74058bf56 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -15,18 +15,24 @@ 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: chroma lyrics - echonest_tempo echonest bpd mpdupdate diff --git a/docs/plugins/info.rst b/docs/plugins/info.rst index 7830d61c7..944f17c55 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 ``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 1a7adebe4..ebe298ae7 100644 --- a/docs/plugins/inline.rst +++ b/docs/plugins/inline.rst @@ -6,9 +6,9 @@ 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 `ì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 function body. The Python code has all of a track's fields in scope, so you can @@ -42,7 +42,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..04a91ac19 100644 --- a/docs/plugins/keyfinder.rst +++ b/docs/plugins/keyfinder.rst @@ -3,26 +3,30 @@ 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 your 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 ``keyfinder`` 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 - a path to the binary. If you installed the `KeyFinder`_ GUI on a Mac, for +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 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`` (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. -* ``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: ``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 c2cd59160..f6723572b 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, enable the ``lastgenre`` 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 forgo a 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,75 @@ 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 +------------- +To configure the plugin, make a ``lastgenre:`` section in your +configuration file. The available options are: + +- ``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``. Running Manually ---------------- diff --git a/docs/plugins/lyrics.rst b/docs/plugins/lyrics.rst index 94e3b704e..138f83655 100644 --- a/docs/plugins/lyrics.rst +++ b/docs/plugins/lyrics.rst @@ -12,14 +12,38 @@ 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 ``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 +the files' tags. -This behavior can be disabled with the ``auto`` config option (see below). + +Configuration +------------- + +To configure the plugin, make a ``lyrics:`` section in your +configuration file. The available options are: + +- ``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 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``:: + + lyrics: + fallback: '' + google_API_key: AZERTYUIOPQSDFGHJKLMWXCVBN1234567890_ab + google_engine_ID: 009217259823014548361:lndtuqkycfu Fetching Lyrics Manually @@ -39,26 +63,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 +84,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..3c176521f 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. -Automatically Update on Import ------------------------------- +Configuration +------------- -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:: +To configure the plugin, make a ``mbcollection:`` section in your +configuration file. There is one option available: - mbcollection: - auto: yes - -During future imports, your default collection will be updated with each -imported album. +- ``auto``: Automatically amend your MusicBrainz collection whenever you + import a new album. + Default: ``no``. diff --git a/docs/plugins/mbsync.rst b/docs/plugins/mbsync.rst index 4bb3da32f..633725b69 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 ``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 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..1719a82a6 100644 --- a/docs/plugins/missing.rst +++ b/docs/plugins/missing.rst @@ -6,59 +6,46 @@ 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 +----- -Installation ------------- - -Enable the plugin by putting ``missing`` on your ``plugins`` line in -:doc:`config file `:: - - plugins: - missing - ... - -Configuration -------------- - +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. +To configure the plugin, make a ``missing:`` section in your +configuration file. The available options are: -count -~~~~~ +- ``count``: Print a count of missing tracks per album, with ``format`` + defaulting to ``$albumartist - $album: $missing``. + Default: ``no``. +- ``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``: Print a single count of missing tracks in all albums. + Default: ``no``. -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..bfd1ef53c 100644 --- a/docs/plugins/mpdstats.rst +++ b/docs/plugins/mpdstats.rst @@ -21,49 +21,37 @@ 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 +------------- + +To configure the plugin, make an ``mpd:`` section in your +configuration file. The available options are: + +- ``host``: The MPD server hostname. + Default: ``localhost``. +- ``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. + 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 b153dde0c..b9eac0baa 100644 --- a/docs/plugins/mpdupdate.rst +++ b/docs/plugins/mpdupdate.rst @@ -6,9 +6,10 @@ 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 ``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:: mpd: @@ -16,9 +17,22 @@ 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`` setting. (Any ``host`` value starting with a slash or a tilde is interpreted as a domain socket.) + +Configuration +------------- + +The available options under the ``mpd:`` section are: + +- ``host``: The MPD server name. + Default: ``localhost``. +- ``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 e9303a183..097b650f2 100644 --- a/docs/plugins/play.rst +++ b/docs/plugins/play.rst @@ -4,7 +4,10 @@ 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. -To use the plugin, enable it in your configuration (see +Usage +----- + +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 @@ -23,15 +26,21 @@ 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 +------------- + +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``: 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/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..5b5420025 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 @@ -65,31 +65,32 @@ you can configure the path explicitly like so:: Configuration ------------- -Available configuration options for the ``replaygain`` section in your -configuration file include: +To configure the plugin, make a ``replaygain:`` section in your +configuration file. The available options are: -* **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 - -* **targetlevel**: The target loudness level can be modified to any number of - decibels with the ``targetlevel`` option (default: 89 dB). +- ``auto``: Enable ReplayGain analysis during import. + Default: ``yes``. +- ``backend``: The analysis backend; either ``gstreamer`` or ``command``. + Default: ``command``. +- ``overwrite``: Re-analyze files that already have ReplayGain tags. + Default: ``no``. +- ``targetlevel``: A number of decibels for the target loudness level. + Default: 89. 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 - 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/rewrite.rst b/docs/plugins/rewrite.rst index d3151bac2..3706d940a 100644 --- a/docs/plugins/rewrite.rst +++ b/docs/plugins/rewrite.rst @@ -6,12 +6,12 @@ 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 ``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``. +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..0e7cbf4bd 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 ``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. @@ -31,11 +31,11 @@ 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``:: +To configure the plugin, make a ``scrub:`` section in your +configuration file. There is one option: - scrub: - auto: no +- ``auto``: Enable metadata stripping during import. + Default: ``yes``. diff --git a/docs/plugins/smartplaylist.rst b/docs/plugins/smartplaylist.rst index 496558fa8..fefc1be30 100644 --- a/docs/plugins/smartplaylist.rst +++ b/docs/plugins/smartplaylist.rst @@ -7,9 +7,9 @@ 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 ``smartplaylist`` plugin in your configuration +(see :ref:`using-plugins`). +Then configure your smart playlists like the following example:: smartplaylist: relative_to: ~/Music @@ -21,12 +21,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 +54,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 +65,19 @@ 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 +------------- + +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``: 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 78f48e720..8b5bb1864 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 @@ -37,51 +37,43 @@ 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: +The default options should work as-is, but there are some options you can put +in config.yaml under the ``spotify:`` section: -* ``mode``: See the section below on modes. -* ``region_filter``: Use the 2-character country abbreviation to limit results +* ``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``: A two-character country abbreviation, to limit results to that market. -* ``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: 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. - Currently, this defaults to "popularity", "first" simply chooses the first - in the list returned by Spotify. + 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. -* ``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: [ { @@ -96,12 +88,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..9f1ce95c0 100644 --- a/docs/plugins/the.rst +++ b/docs/plugins/the.rst @@ -2,39 +2,42 @@ 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:: +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 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 +------------- -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. +To configure the plugin, make a ``the:`` section in your +configuration file. The available options 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: ``[]``. +- ``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/types.rst b/docs/plugins/types.rst index b6503f353..67742ee0f 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 f10142cc0..e1be24a9b 100644 --- a/docs/plugins/web.rst +++ b/docs/plugins/web.rst @@ -20,8 +20,8 @@ flask``. .. _Flask: http://flask.pocoo.org/ -Put ``web`` on your ``plugins`` line in your configuration file to enable the -plugin. +Finally, enable the ``web`` plugin in your configuration +(see :ref:`using-plugins`). Run the Server -------------- @@ -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 ----- @@ -50,6 +46,17 @@ 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 +------------- + +To configure the plugin, make a ``web:`` section in your +configuration file. The available options are: + +- ``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 8704d3d8e..6a857e3de 100644 --- a/docs/plugins/zero.rst +++ b/docs/plugins/zero.rst @@ -4,14 +4,21 @@ 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 ``zero`` plugin, enable the plugin in your configuration +(see :ref:`using-plugins`). + +Configuration +------------- + +Make a ``zero:`` section in your configuration file. You can specify the +fields to nullify and the conditions for nullifying them: + +* 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:: diff --git a/docs/refresh_safari.js b/docs/refresh_safari.js new file mode 100644 index 000000000..7f5cc0ccc --- /dev/null +++ b/docs/refresh_safari.js @@ -0,0 +1,19 @@ +var safari = Application('com.apple.Safari'); + +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. + safari.doJavaScript("location.reload();", { in: tab }); + console.log(url); + } + } + } +} + +'done';