mirror of
https://github.com/beetbox/beets.git
synced 2025-12-09 18:12:19 +01:00
117 lines
4.8 KiB
ReStructuredText
117 lines
4.8 KiB
ReStructuredText
Convert Plugin
|
||
==============
|
||
|
||
The ``convert`` plugin lets you convert parts of your collection to a
|
||
directory of your choice, transcoding audio and embedding album art along the
|
||
way. It can transcode to and from any format using a configurable command
|
||
line.
|
||
|
||
|
||
Installation
|
||
------------
|
||
|
||
Enable the ``convert`` plugin in your configuration (see
|
||
:doc:`/plugins/index`). By default, the plugin depends on `FFmpeg`_ to
|
||
transcode the audio, so you might want to install it.
|
||
|
||
.. _FFmpeg: http://ffmpeg.org
|
||
|
||
|
||
Usage
|
||
-----
|
||
|
||
To convert a part of your collection, run ``beet convert QUERY``. This
|
||
will display all items matching ``QUERY`` and ask you for confirmation before
|
||
starting the conversion. The command will then transcode all the
|
||
matching files to the destination directory given by the ``-d``
|
||
(``--dest``) option or the ``dest`` configuration. The path layout
|
||
mirrors that of your library, but it may be customized through the
|
||
``paths`` configuration.
|
||
|
||
The plugin uses a command-line program to transcode the audio. With the
|
||
``-f`` (``--format``) option you can choose the transcoding command
|
||
and customize the available commands
|
||
:ref:`through the configuration <convert-format-config>`.
|
||
|
||
The ``-a`` (or ``--album``) option causes the command
|
||
to match albums instead of tracks.
|
||
|
||
By default, the command places converted files into the destination directory
|
||
and leaves your library pristine. To instead back up your original files into
|
||
the destination directory and keep converted files in your library, use the
|
||
``-k`` (or ``--keep-new``) option.
|
||
|
||
To test your configuration without taking any actions, use the ``--pretend``
|
||
flag. The plugin will print out the commands it will run instead of executing
|
||
them.
|
||
|
||
|
||
Configuration
|
||
-------------
|
||
|
||
The plugin offers several configuration options, all of which live under the
|
||
``convert:`` section:
|
||
|
||
* ``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
|
||
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.
|
||
* ``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.
|
||
|
||
.. _convert-format-config:
|
||
|
||
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.::
|
||
|
||
convert:
|
||
format: speex
|
||
formats:
|
||
speex:
|
||
command: ffmpeg -i $source -y -acodec speex $dest
|
||
extension: spx
|
||
wav: ffmpeg -i $source -y -acodec pcm_s16le $dest
|
||
|
||
In this example ``beet convert`` will use the *speex* command by
|
||
default. To convert the audio to `wav`, run ``beet convert -f wav``.
|
||
This will also use the format key (`wav`) as the file extension.
|
||
|
||
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
|
||
to transcode audio. The tokens ``$source`` and ``$dest`` in the command
|
||
are replaced with the paths to the existing and new file.
|
||
|
||
The plugin in comes with default commands for the most common audio
|
||
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:
|
||
command: ffmpeg -i $source -y -vn -aq 2 $dest
|
||
extension: mp3
|