mirror of
https://github.com/beetbox/beets.git
synced 2025-12-06 08:39:17 +01:00
113 lines
5.4 KiB
ReStructuredText
113 lines
5.4 KiB
ReStructuredText
EmbedArt Plugin
|
||
===============
|
||
|
||
Typically, beets stores album art in a "file on the side": along with each
|
||
album, there is a file (named "cover.jpg" by default) that stores the album art.
|
||
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).
|
||
|
||
Embedding Art Automatically
|
||
---------------------------
|
||
|
||
To use the ``embedart`` plugin, first enable it in your configuration (see
|
||
:ref:`using-plugins`). Then, install ``beets`` with ``embedart`` extra
|
||
|
||
.. code-block:: bash
|
||
|
||
pip install "beets[embedart]"
|
||
|
||
You'll also want to enable the :doc:`/plugins/fetchart` to obtain the images to
|
||
be embedded. Art will be embedded after each album has its cover art set.
|
||
|
||
This behavior can be disabled with the ``auto`` config option (see below).
|
||
|
||
.. _image-similarity-check:
|
||
|
||
Image Similarity
|
||
~~~~~~~~~~~~~~~~
|
||
|
||
When importing a lot of files with the ``auto`` option, one may be reluctant to
|
||
overwrite existing embedded art for all of them.
|
||
|
||
You can tell beets to avoid embedding images that are too different from the
|
||
existing ones. This works by computing the perceptual hashes (PHASH_) of the two
|
||
images and checking that the difference between the two does not exceed a
|
||
threshold. You can set the threshold with the ``compare_threshold`` option.
|
||
|
||
A threshold of 0 (the default) disables similarity checking and always embeds
|
||
new images. Set the threshold to another number---we recommend between 10 and
|
||
100---to adjust the sensitivity of the comparison. The smaller the threshold
|
||
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).
|
||
- **quality**: The JPEG quality level to use when compressing images (when
|
||
``maxwidth`` is set). This should be either a number from 1 to 100 or 0 to use
|
||
the default quality. 65–75 is usually a good starting point. The default
|
||
behavior depends on the imaging tool used for scaling: ImageMagick tries to
|
||
estimate the input image quality and uses 92 if it cannot be determined, and
|
||
PIL defaults to 75. Default: 0 (disabled)
|
||
- **remove_art_file**: Automatically remove the album art file for the album
|
||
after it has been embedded. This option is best used alongside the
|
||
:doc:`FetchArt </plugins/fetchart>` plugin to download art with the purpose of
|
||
directly embedding it into the file's metadata without an "intermediate" album
|
||
art file. Default: ``no``.
|
||
|
||
Note: ``compare_threshold`` option requires ImageMagick_, and ``maxwidth``
|
||
requires either ImageMagick_ or Pillow_.
|
||
|
||
.. _imagemagick: https://www.imagemagick.org/
|
||
|
||
.. _phash: http://www.fmwconcepts.com/misc_tests/perceptual_hash_test_results_510/
|
||
|
||
.. _pillow: https://github.com/python-pillow/Pillow
|
||
|
||
Manually Embedding and Extracting Art
|
||
-------------------------------------
|
||
|
||
The ``embedart`` plugin provides a couple of commands for manually managing
|
||
embedded album art:
|
||
|
||
- ``beet embedart [-f IMAGE] QUERY``: embed images in every track of the albums
|
||
matching the query. If the ``-f`` (``--file``) option is given, then use a
|
||
specific image file from the filesystem; otherwise, each album embeds its own
|
||
currently associated album art. The command prompts for confirmation before
|
||
making the change unless you specify the ``-y`` (``--yes``) option.
|
||
- ``beet embedart [-u IMAGE_URL] QUERY``: embed image specified in the URL into
|
||
every track of the albums matching the query. The ``-u`` (``--url``) option
|
||
can be used to specify the URL of the image to be used. The command prompts
|
||
for confirmation before making the change unless you specify the ``-y``
|
||
(``--yes``) option.
|
||
- ``beet extractart [-a] [-n FILE] QUERY``: extracts the images for all albums
|
||
matching the query. The images are placed inside the album folder. You can
|
||
specify the destination file name using the ``-n`` option, but leave off the
|
||
extension: it will be chosen automatically. The destination filename is
|
||
specified using the ``art_filename`` configuration option. It defaults to
|
||
``cover`` if it's not specified via ``-o`` nor the config. Using ``-a``, the
|
||
extracted image files are automatically associated with the corresponding
|
||
album.
|
||
- ``beet extractart -o FILE QUERY``: extracts the image from an item matching
|
||
the query and stores it in a file. You have to specify the destination file
|
||
using the ``-o`` option, but leave off the extension: it will be chosen
|
||
automatically.
|
||
- ``beet clearart QUERY``: removes all embedded images from all items matching
|
||
the query. The command prompts for confirmation before making the change
|
||
unless you specify the ``-y`` (``--yes``) option.
|