From 918afbed42ee7d2954351c80c0eeae1ffce5d219 Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Thu, 30 Oct 2014 16:16:05 -0700 Subject: [PATCH] Docs cleanup through ftinitle --- docs/plugins/echonest.rst | 25 +++++++++++++------------ docs/plugins/embedart.rst | 38 ++++++++++++++++++++------------------ docs/plugins/fetchart.rst | 26 ++++++++++++-------------- docs/plugins/ftintitle.rst | 15 ++++++++------- 4 files changed, 53 insertions(+), 51 deletions(-) diff --git a/docs/plugins/echonest.rst b/docs/plugins/echonest.rst index 8609c7807..dfef807e6 100644 --- a/docs/plugins/echonest.rst +++ b/docs/plugins/echonest.rst @@ -53,29 +53,30 @@ Finally, enable the ``echonest`` plugin in your configuration (see Configuration ------------- -Available options: +To configure the plugin, make an ``echonest:`` section in your configuration +file. The available options are: -- ``apikey``: set this option to specify your own EchoNest API key. - You can `apply for your own`_ for free from the EchoNest. - Default: beets includes its own Echo Nest API key. -- ``auto``: set it to ``no`` to disable automatic metadata fetching during - import. +- ``apikey``: A custom EchoNest API key. You can `apply for your own`_ for + free from the EchoNest. + Default: beets' own Echo Nest API key. +- ``auto``: Enable automatic metadata fetching during import. Default: ``yes``. - ``codegen``: Echoprint or ENMFP codegen binary path. - Default: ``None`` -- ``convert``: because the Echo Nest server only supports a limited range of + Default: look for the executable in your ``$PATH``. +- ``upload``: Send files to the Echo Nest server if they can not be identified + by other means. + Default: ``yes``. +- ``convert``: Because the Echo Nest server only supports a limited range of file formats, the plugin automatically converts unsupported files to ``ogg``. Default: ``yes``. -- ``truncate``: automatically truncates large files to their first 5 minutes +- ``truncate``: Automatically truncate large files to their first 5 minutes before uploading them to The Echo Nest server (as files with sizes greater than 50MB are rejected). Default: ``yes``. -- ``upload``: send files to the Echo Nest server if it can not be identified by - other means. - Default: ``yes``. .. _apply for your own: http://developer.echonest.com/account/register + Running Manually ---------------- diff --git a/docs/plugins/embedart.rst b/docs/plugins/embedart.rst index 1fa24f22f..172ac6550 100644 --- a/docs/plugins/embedart.rst +++ b/docs/plugins/embedart.rst @@ -7,14 +7,16 @@ You might want to embed the album art directly into each file's metadata. While this will take more space than the external-file approach, it is necessary for displaying album art in some media players (iPods, for example). -Usage ------ +Embedding Art Automatically +--------------------------- To automatically embed discovered album art into imported files, just enable the ``embedart`` plugin (see :doc:`/plugins/index`). You'll also want to enable the :doc:`/plugins/fetchart` to obtain the images to be embedded. Art will be embedded after each album is added to the library. +This behavior can be disabled with the ``auto`` config option (see below). + .. _image-similarity-check: Image Similarity @@ -39,26 +41,26 @@ This feature requires `ImageMagick`_. Configuration ------------- -Available options: +To configure the plugin, make an ``embedart:`` section in your configuration +file. The available options are: -- ``auto``: lets you disable automatic album art embedding when set to - ``no``. - Default: ``true`` -- ``compare_threshold``: how similar must candidate art be regarding to - embedded art to be written to the file (see :ref:`image-similarity-check`). - Default: ``0`` (disabled). -- ``ifempty``: set to 'yes' to avoid embedding album art for files that already - have one. +- ``auto``: Enable automatic album art embedding. + Default: ``yes``. +- ``compare_threshold``: How similar candidate art must be to + existing art to be written to the file (see :ref:`image-similarity-check`). + Default: 0 (disabled). +- ``ifempty``: Avoid embedding album art for files that already have art + embedded. Default: ``no``. -- ``maxwidth``: defines a maximum width to downscale images before embedding +- ``maxwidth``: A maximum width to downscale images before embedding them (the original image file is not altered). The resize operation reduces - image width to ``maxwidth`` pixels. The height is recomputed so that the - aspect ratio is preserved. See also :ref:`image-resizing` for further caveats - about image resizing. - Default: ``0`` (disabled). + image width to at most ``maxwidth`` pixels. The height is recomputed so that + the aspect ratio is preserved. See also :ref:`image-resizing` for further + caveats about image resizing. + Default: 0 (disabled). -Note: ``compare_threshold`` option requires `ImageMagick`_ , ``maxwidth`` -requires `ImageMagick`_ or `PIL`_ +Note: ``compare_threshold`` option requires `ImageMagick`_, and ``maxwidth`` +requires either `ImageMagick`_ or `PIL`_. .. _PIL: http://www.pythonware.com/products/pil/ .. _ImageMagick: http://www.imagemagick.org/ diff --git a/docs/plugins/fetchart.rst b/docs/plugins/fetchart.rst index dc9b9a4d8..63b9d896f 100644 --- a/docs/plugins/fetchart.rst +++ b/docs/plugins/fetchart.rst @@ -26,25 +26,24 @@ the :ref:`art-filename` config option. Configuration ------------- -Available options: +To configure the plugin, make a ``fetchart:`` section in your configuration +file. The available options are: -- ``auto``: set it to ``no`` to disable automatic album art fetching during - import. +- ``auto``: Enable automatic album art fetching during import. Default: ``yes``. -- ``cautious``: pick only trusted album arts by ignoring filenames that do not - contain one of ``cover_names`` keywords. +- ``cautious``: Pick only trusted album art by ignoring filenames that do not + contain one of the keywords in ``cover_names``. Default: ``no``. -- ``cover_names``: image filenames that contain word(s) of this list will be - picked primarily. +- ``cover_names``: Prioritize images containing words in this list. Default: ``['cover', 'front', 'art', 'album', 'folder']``. -- ``google_search``: set it to `yes` gather images from Google Images search. +- ``google_search``: Gather images from Google Image Search. Default: ``no``. -- ``maxwidth``: maximum image width to downscale fetched images if they are - too big. The resize operation reduces image width to ``maxwidth`` pixels. The - height is recomputed so that the aspect ratio is preserved. -- ``remote_priority``: query remote sources every time and use local image only +- ``maxwidth``: A maximum image width to downscale fetched images if they are + too big. The resize operation reduces image width to at most ``maxwidth`` + pixels. The height is recomputed so that the aspect ratio is preserved. +- ``remote_priority``: Query remote sources every time and use local image only as fallback. - Default: ``no``, remote (Web) art sources are only queried if no local art is + Default: ``no``; remote (Web) art sources are only queried if no local art is found in the filesystem. Here's an example that makes plugin select only images that contain *front* or @@ -55,7 +54,6 @@ Here's an example that makes plugin select only images that contain *front* or cover_names: front back - Manually Fetching Album Art --------------------------- diff --git a/docs/plugins/ftintitle.rst b/docs/plugins/ftintitle.rst index a45fb2285..3a378b08c 100644 --- a/docs/plugins/ftintitle.rst +++ b/docs/plugins/ftintitle.rst @@ -16,15 +16,16 @@ To use the ``ftintitle`` plugin, enable it in your configuration Configuration ------------- -Available options: +To configure the plugin, make a ``ftintitle:`` section in your configuration +file. The available options are: -- ``auto``: set it to ``no`` to disable plugin during import. +- ``auto``: Enable metadata rewriting during import. Default: ``yes``. -- ``drop``: remove featured artists entirely instead of adding them to the +- ``drop``: Remove featured artists entirely instead of adding them to the title field. - Default: ``no`` + Default: ``no``. -Running manually +Running Manually ---------------- From the command line, type:: @@ -34,7 +35,7 @@ From the command line, type:: The query is optional; if it's left off, the transformation will be applied to your entire collection. -Use the ``-d``flag to remove featured artists (equivalent of the ``drop`` -option). +Use the ``-d`` flag to remove featured artists (equivalent of the ``drop`` +config option). .. _MusicBrainz style: http://musicbrainz.org/doc/Style