From 338eb6388eccf0993d6fdfdcefe579b92e846813 Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Thu, 1 Nov 2012 14:25:46 -0700 Subject: [PATCH] documentation for convert.exe problem (#64) We currently just document the fact that convert.exe can interfere with finding ImageMagick's convert binary. We can solve this with a config option easily once confit is merged. This also changes the line endings for fetchart.rst back to Unix. --- beetsplug/fetchart.py | 2 +- docs/plugins/embedart.rst | 3 +- docs/plugins/fetchart.rst | 159 ++++++++++++++++++++------------------ 3 files changed, 86 insertions(+), 78 deletions(-) diff --git a/beetsplug/fetchart.py b/beetsplug/fetchart.py index e5ceccc72..567d8a64b 100644 --- a/beetsplug/fetchart.py +++ b/beetsplug/fetchart.py @@ -218,7 +218,7 @@ class FetchArtPlugin(BeetsPlugin): self.autofetch = ui.config_val(config, 'fetchart', 'autofetch', True, bool) self.maxwidth = int(ui.config_val(config, 'fetchart', - 'maxwidth', '0')) + 'maxwidth', '0')) if self.autofetch: # Enable two import hooks when fetching is enabled. self.import_stages = [self.fetch_art] diff --git a/docs/plugins/embedart.rst b/docs/plugins/embedart.rst index cf2639347..46b66913f 100644 --- a/docs/plugins/embedart.rst +++ b/docs/plugins/embedart.rst @@ -50,7 +50,8 @@ 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. +use the ``maxwidth`` config option. See also :ref:`image-resizing` for further +caveats about image resizing. .. _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 fbd5eb523..3f02937e8 100644 --- a/docs/plugins/fetchart.rst +++ b/docs/plugins/fetchart.rst @@ -1,76 +1,83 @@ -FetchArt Plugin -=============== - -The ``fetchart`` plugin retrieves album art images from various sources on the -Web and stores them as image files. - - -Fetching Album Art During Import --------------------------------- - -To automatically get album art for every album you import, just enable the -plugin by putting ``fetchart`` on your config file's ``plugins`` line (see -:doc:`/plugins/index`). - -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:: - - [fetchart] - autofetch: no - -Manually Fetching Album Art ---------------------------- - -Use the ``fetchart`` command to download album art after albums have already -been imported:: - - $ beet fetchart [-f] [query] - -By default, the command will only look for album art when the album doesn't -already have it; the ``-f`` or ``--force`` switch makes it search for art -regardless. If you specify a query, only matching albums will 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, -no resizing is performed for album art found on the filesystem---only downloaded -art is resized. Server-side resizing can also be slower than local resizing, so -consider installing one of the two backends for better performance. - -.. _PIL: http://www.pythonware.com/products/pil/ -.. _ImageMagick: http://www.imagemagick.org/ - -Album Art Sources ------------------ - -Currently, this plugin searches for art in the local filesystem as well as on -the Cover Art Archive, Amazon, and AlbumArt.org (in that order). - -When looking for local album art, beets checks for image files located in the -same folder as the music files you're importing. If you have an image file -called "cover," "front," "art," "album," for "folder" alongside your music, -beets will treat it as album art and skip searching any online databases. - -When you choose to apply changes during an import, beets searches all sources -for album art. For "as-is" imports (and non-autotagged imports using the ``-A`` -flag), beets only looks for art on the local filesystem. - -Embedding Album Art -------------------- - -This plugin fetches album art but does not embed images into files' tags. To do -that, use the :doc:`/plugins/embedart`. (You'll want to have both plugins -enabled.) +FetchArt Plugin +=============== + +The ``fetchart`` plugin retrieves album art images from various sources on the +Web and stores them as image files. + + +Fetching Album Art During Import +-------------------------------- + +To automatically get album art for every album you import, just enable the +plugin by putting ``fetchart`` on your config file's ``plugins`` line (see +:doc:`/plugins/index`). + +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:: + + [fetchart] + autofetch: no + +Manually Fetching Album Art +--------------------------- + +Use the ``fetchart`` command to download album art after albums have already +been imported:: + + $ beet fetchart [-f] [query] + +By default, the command will only look for album art when the album doesn't +already have it; the ``-f`` or ``--force`` switch makes it search for art +regardless. If you specify a query, only matching albums will be processed; +otherwise, the command processes every album in your library. + +.. _image-resizing: + +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, +no resizing is performed for album art found on the filesystem---only downloaded +art is resized. Server-side resizing can also be slower than local resizing, so +consider installing one of the two backends for better performance. + +When using ImageMagic, beets looks for the ``convert`` executable in your path. +On some versions Windows, the program can be shadowed by a system-provided +``convert.exe``. On these systems, you may need to modify your ``%PATH%`` +environment variable so that ImageMagick comes first or use PIL instead. + +.. _PIL: http://www.pythonware.com/products/pil/ +.. _ImageMagick: http://www.imagemagick.org/ + +Album Art Sources +----------------- + +Currently, this plugin searches for art in the local filesystem as well as on +the Cover Art Archive, Amazon, and AlbumArt.org (in that order). + +When looking for local album art, beets checks for image files located in the +same folder as the music files you're importing. If you have an image file +called "cover," "front," "art," "album," for "folder" alongside your music, +beets will treat it as album art and skip searching any online databases. + +When you choose to apply changes during an import, beets searches all sources +for album art. For "as-is" imports (and non-autotagged imports using the ``-A`` +flag), beets only looks for art on the local filesystem. + +Embedding Album Art +------------------- + +This plugin fetches album art but does not embed images into files' tags. To do +that, use the :doc:`/plugins/embedart`. (You'll want to have both plugins +enabled.)