beets / docs / plugins / convert.rst

The default branch has multiple heads

Convert Plugin

The convert plugin lets you convert parts of your collection to a directory of your choice. It converts all input formats supported by FFmpeg to MP3. It will skip files that are already present in the target directory. Converted files follow the same path formats as your library.

Installation

First, enable the convert plugin (see :doc:`/plugins/index`).

To transcode music, this plugin requires the ffmpeg command-line tool. If its executable is in your path, it will be found automatically by the plugin. Otherwise, configure the plugin to locate the executable:

convert:
    ffmpeg: /usr/bin/ffmpeg

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 -a (or --album) option causes the command to match albums instead of tracks.

The -t (--threads) and -d (--dest) options allow you to specify or overwrite the respective configuration options.

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.

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 MP3 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. By default MP3s will be copied without transcoding and all other formats will be converted.
  • opts are the encoding options that are passed to ffmpeg. Default: "-aq 2". (Note that "-aq <num>" is equivalent to the LAME option "-V <num>".) If you want to specify a bitrate, use "-ab <bitrate>". Refer to the FFmpeg documentation for more details.
  • auto gives you the option to import transcoded versions of your files automatically during the import command.
  • 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.

Here's an example configuration:

convert:
    embed: false
    max_bitrate: 200
    opts: -aq 4
    dest: /home/user/MusicForPhone
    threads: 4
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.