You want to manage multiple versions of your audio files with beets? Your favorite iPlayer has limited space and does not support Ogg Vorbis? You want to keep lossless versions on a large external drive? You want to symlink your audio to other locations?
With this beets plugin every file in you music library have multiple alternate versions in separate locations.
You will also need at least version 1.4.7 of beets.
pip install --upgrade beets>=1.4.7 beets-alternatives
Then, enable the plugin. You may use the
beet config --edit
command to add the alternatives plugin to the configuration.
plugins: - ... - alternatives
Now, you can get rolling with one of the use cases below.
Suppose your favorite portable player only supports MP3 and MP4, has
limited disk space and is mounted at
/player. Instead of selecting
its content manually and using the
convert plugin to transcode it, you
want to sync it automatically. First we give this external collection
the name ‘myplayer’ and start configuring beets.
alternatives: myplayer: directory: /player paths: default: $album/$title formats: aac mp3 query: "onplayer:true" removable: true
The first two options determine the location of the external files and
correspond to the global
paths settings. The
format option specifies the
formats we transcode the files to (more on that below). Finally, the
query option tells the plugin which files you want to put in the
external location. The value is a query string as used for the
beets command line. In our case we use a flexible attribute to make the
Let’s add some files to our selection by setting the flexible attribute
query option. (Since we use boolean values for the
‘onplayer’ field it might be a good idea to set the type of this field
bool using the types plugin)
$ beet modify onplayer=true artist:Bach
The configured query also matches all tracks that are part of an album
onplayer attribute is ‘true’. We could also use
$ beet modify -a onplayer=true albumartist:Bach
We then tell beets to create the external files.
$ beet alt update myplayer Collection at '/player' does not exists. Maybe you forgot to mount it. Do you want to create the collection? (y/N)
The question makes sure that you don’t recreate a external collection if the device is not mounted. Since this is our first go, we answer the question with yes.
The command will copy all files with the artist ‘Bach’ and format
either ‘AAC’ or ‘MP3’ to the
/player directory. All other formats
will be transcodec to the ‘AAC’ format unsing the [convert plugin].
The transcoding process can be configured through convert’s
If you update some tracks in your main collection, the
command will propagate the changes to your external collection. Since
we don’t need to convert the files but just update the tags, this will
be much faster the second time.
$ beet modify composer="Johann Sebastian Bach" artist:Bach $ beet alt update myplayer
After going for a run you mitght realize that Bach is probably not the right thing to work out to. So you decide to put Beethoven on your player.
$ beet modify onplayer! artist:Bach $ beet modify onplayer=true artist:Beethoven $ beet alt update myplayer
This removes all Bach tracks from the player and adds Beethoven’s.
Instead of copying and converting files this plugin can also create symbolic links to the files in your library. For example you want to have a directory containing all music sorted by year and album.
directory: /music paths: default: $artist/$album/$title alternatives: by-year: directory: by-year paths: default: $year/$album/$title formats: link
The first thing to note here is the
link format. Instead of
converting the files this tells the plugin to create symbolic links to
the original audio file. We also note that the directory is a relative
path: it will be resolved with respect to the global
option. We could also omit the directory configuration as it defaults
to the collection’s name. Finally, we omitted the
query option. This
means that we want to create symlinks for all files. Of course you can
still add a query to select only parts of your collection.
beet alt update by-year command will now create the symlinks. For
/music/by-year/1982/Thriller/Beat It.mp3 -> /music/Michael Jackson/Thriller/Beat It.mp3
You can also specify if you want absolute symlinks (default) or relative ones
link_type. The option
link_type must be
alternatives: by-year: directory: by-year paths: default: $year/$album/$title formats: link link_type: relative
With this config, the
beet alt update by-year command will create relative symlinks. E.g:
/music/by-year/1982/Thriller/Beat It.mp3 -> ../../../Michael Jackson/Thriller/Beat It.mp3
Now, if you move the
/music/ folder to another location, the links
will continue working
beet alt update [--create|--no-create] NAME
Updates the external collection configured under
Add missing files. Convert them to the configured format or copy them.
Remove files that don’t match the query but are still in the external collection
Move files to the path determined from the
Update tags if the modification time of the external file is older than that of the source file from the library.
The command accepts the following option.
removableconfiguration option is set and the external base directory does not exist, then the command will ask you to confirm the creation of the external collection. These options specify the answer as a cli option.
beet alt list-tracks [--format=FORMAT] NAME
Lists all tracks that are currently included in the collection.
--format option accepts a beets path format string that is
used to format each track.
An external collection is configured as a name-settings-pair under the
alternatives configuration. The name is used to reference the
collection from the command line. The settings is a map of the
directoryThe root directory to store the external files under. Relative paths are resolved with respect to the global
directoryconfiguration. If omitted it defaults to the name of the collection and is therefore relative to the library directory. (optional)
pathsPath templates for audio files under
directory. Configured like the global paths option and defaults to it if not given. (optional)
queryA query string that determine which tracks belong to the collection. A track belongs to the collection if itself or the album it is part of matches the query. To match all items, specify an empty string. (required)
formatsA list of space separated strings that determine the audio file formats in the external collection. If the ‘format’ field of a track is included in the list, the file is copied. Otherwise, the file is transcoded to the first format in the list. The name of the first format must correpond to a key in the
convert.formatsconfiguration. This configuration controls the transcoding process.
The special format ‘link’ is used to create symbolic links instead of transcoding the file. It can not be combined with other formats.
By default no transcoding is done.
removableIf this is
true(the default) and
directorydoes not exist, the
updatecommand will ask you to confirm the creation of the external collection. (optional)
link, it sets the type of links to create. For differences between link types and examples see Symlink Views.
If you have an idea or a use case this plugin is missing, feel free to open an issue.
The following is a list of things I might add in the feature.
- Symbolic links for each artist in a multiple artists release (see the beets issue)
Copyright (c) 2014 Thomas Scholtes.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.