Package: beets-alternatives
beets-alternativesYou 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 thisbeetsplugin every file in you music library have
multiple alternate versions in separate locations.If you’re interested in contributing to this project, check out thedeveloper
documentation.Getting StartedInstall the plugin and make sure you using at least version 1.6.0 of beets and
Python 3.8.pipinstall--upgradebeets>=1.6.0beets-alternativesThen,enable the plugin. You may use thebeet config --editcommand to add thealternativesplugin to the configuration.plugins:-...-alternativesNow, you can get rolling with one of the use cases below.External FilesSuppose 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 theconvertplugin 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:/playerpaths:default:$album/$titleformats:aac mp3query:"onplayer:true"removable:trueThe first two options determine the location of the external files and
correspond to the globaldirectoryandpathssettings.  Theformatoption specifies the
formats we transcode the files to (more on that below).  Finally, thequeryoption tells the plugin which files you want to put in the
external location. The value is aquery stringas used for the
beets command line. In our case we use a flexible attribute to make the
selection transparent.Let’s add some files to our selection by setting the flexible attribute
from thequeryoption. (Since we use boolean values for the
‘onplayer’ field it might be a good idea to set the type of this field
toboolusing thetypesplugin)beetmodifyonplayer=trueartist:BachThe configured query also matches all tracks that are part of an album
where theonplayerattribute is ‘true’. We could also usebeetmodify-aonplayer=truealbumartist:BachWe 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/playerdirectory. All other formats will be transcodec to the
‘AAC’ format unsing theconvertplugin. The transcoding
process can be configured throughconvert’sconfiguration.If you update some tracks in your main collection, thealt updatecommand 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.beetmodifycomposer="Johann Sebastian Bach"artist:Bach
beetaltupdatemyplayerAfter 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.beetmodifyonplayer!artist:Bach
beetmodifyonplayer=trueartist:Beethoven
beetaltupdatemyplayerThis removes all Bach tracks from the player and adds Beethoven’s.Symlink ViewsInstead 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:/musicpaths:default:$artist/$album/$titlealternatives:by-year:directory:by-yearpaths:default:$year/$album/$titleformats:linkThe first thing to note here is thelinkformat. 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 globaldirectoryoption. We could also omit the directory configuration as it defaults
to the collection’s name. Finally, we omitted thequeryoption. 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.Thebeet alt update by-yearcommand will now create the symlinks. For
example/music/by-year/1982/Thriller/Beat It.mp3
-> /music/Michael Jackson/Thriller/Beat It.mp3You can also specify if you want absolute symlinks (default) or relative ones
withlink_type. The optionlink_typemust beabsoluteorrelativealternatives:by-year:directory:by-yearpaths:default:$year/$album/$titleformats:linklink_type:relativeWith this config, thebeet alt update by-yearcommand will create relative symlinks. E.g:/music/by-year/1982/Thriller/Beat It.mp3
-> ../../../Michael Jackson/Thriller/Beat It.mp3Now, if you move the/music/folder to another location, the links
will continue workingCLI Referencebeet alt update [--create|--no-create] NAMEUpdates the external collection configured underalternatives.NAME.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 collectionMove files to the path determined from thepathsconfiguration.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.--[no-]createIf theremovableconfiguration 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] NAMELists all tracks that are currently included in the collection.The--formatoption accepts abeets path formatstring that is
used to format each track.ConfigurationAn external collection is configured as a name-settings-pair under thealternativesconfiguration. The name is used to reference the
collection from the command line. The settings is a map of the
following settings.directoryThe root directory to store the external files under.
Relative paths are resolved with respect to the globaldirectoryconfiguration. If omitted it defaults to the name of the collection
and is therefore relative to the library directory. (optional)pathsPath templates for audio files underdirectory. Configured
like theglobal paths optionand defaults to it if
not given. (optional)queryAquery stringthat 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 theconvert.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 istrue(the default) anddirectorydoes
not exist, theupdatecommand will ask you to confirm the creation
of the external collection. (optional)link_typeCan beabsolute(default) orrelative. Ifformatsislink, it sets the type of links to create. For
differences between link types and examples seeSymlink Views.Feature RequestsIf you have an idea or a use case this plugin is missing, feel free toopen 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 thebeets issue)LicenseCopyright (c) 2014-2023 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.