Advanced fetchart source config: documentation

docs/plugins/fetchart.rst

@@ -54,7 +54,8 @@ file. The available options are:
   matches at the cost of some speed. They are searched in the given order,
   thus in the default config, no remote (Web) art source are queried if
   local art is found in the filesystem. To use a local image as fallback,
-  move it to the end of the list.
+  move it to the end of the list. For even more fine-grained control over
+  the search order, see the section on :ref:`album-art-sources` below.
 - **google_key**: Your Google API key (to enable the Google Custom Search
   backend).
   Default: None.
@@ -135,6 +136,8 @@ environment variable so that ImageMagick comes first or use Pillow instead.
 .. _Pillow: https://github.com/python-pillow/Pillow
 .. _ImageMagick: http://www.imagemagick.org/
 
+.. _album-art-sources:
+
 Album Art Sources
 -----------------
 
@@ -150,6 +153,25 @@ 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.
 
+For some of the art sources, the backend service can match artwork by various
+criteria. If you want finer control over the search order in such cases, the
+following alternative syntax for the ``sources`` option can be used::
+
+    fetchart:
+        sources:
+            - filesystem
+            - coverart: release
+            - itunes
+            - coverart: releasegroup
+            - '*'
+
+where listing a source without matching criteria will default to trying all
+available strategies. Entries of the forms ``coverart: release releasegroup``
+and ``coverart: *`` are also valid.
+Currently, the ``coverart`` source is the only backend to support several
+such values, namely ``release`` and ``releasegroup``, which refer to the
+respective MusicBrainz IDs.
+
 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.