beets Documentation Release 1.4.7 Adrian Sampson May 29, 2018 Contents 1 Contents 3 1.1 Guides..................................................3 1.2 Reference................................................. 13 1.3 Plugins.................................................. 42 1.4 FAQ.................................................... 103 1.5 For Developers.............................................. 108 1.6 Changelog................................................ 123 i ii beets Documentation, Release 1.4.7 Welcome to the documentation for beets, the media library management system for obsessive-compulsive music geeks. If you’re new to beets, begin with the Getting Started guide. That guide walks you through installing beets, setting it up how you like it, and starting to build your music library. Then you can get a more detailed look at beets’ features in the Command-Line Interface and Configuration references. You might also be interested in exploring the plugins. If you still need help, your can drop by the #beets IRC channel on Freenode, drop by the discussion board, send email to the mailing list, or file a bug in the issue tracker. Please let us know where you think this documentation can be improved. Contents 1 beets Documentation, Release 1.4.7 2 Contents CHAPTER 1 Contents 1.1 Guides This section contains a couple of walkthroughs that will help you get familiar with beets. If you’re new to beets, you’ll want to begin with the Getting Started guide. 1.1.1 Getting Started Welcome to beets! This guide will help you begin using it to make your music collection better. Installing You will need Python. Beets works on Python 2.7 and Python 3.4 or later. • macOS v10.7 (Lion) and later include Python 2.7 out of the box. You can opt for Python 3 by installing it via Homebrew: brew install python3 • On Debian or Ubuntu, depending on the version, beets is available as an official package (Debian details, Ubuntu details), so try typing: apt-get install beets. But the version in the repositories might lag behind, so make sure you read the right version of these docs. If you want the latest version, you can get everything you need to install with pip as described below by running: apt-get install python-dev python-pip • On Arch Linux, beets is in [community], so just run pacman -S beets. (There’s also a bleeding-edge dev package in the AUR, which will probably set your computer on fire.) • For Gentoo Linux, beets is in Portage as media-sound/beets. Just run emerge beets to install. There are several USE flags available for optional plugin dependencies. • On FreeBSD, there’s a beets port at audio/beets. • On OpenBSD, beets can be installed with pkg_add beets. • For Slackware, there’s a SlackBuild available. 3 beets Documentation, Release 1.4.7 • On Fedora 22 or later, there is a DNF package (or three): $ sudo dnf install beets beets-plugins beets-doc • On Solus, run eopkg install beets. • On NixOS, run nix-env -i beets. If you have pip, just say pip install beets (you might need sudo in front of that). To install without pip, download beets from its PyPI page and run python setup.py install in the directory therein. The best way to upgrade beets to a new version is by running pip install -U beets. You may want to follow @b33ts on Twitter to hear about progress on new versions. Installing on macOS 10.11 and Higher Starting with version 10.11 (El Capitan), macOS has a new security feature called System Integrity Protection (SIP) that prevents you from modifying some parts of the system. This means that some pip commands may fail with a permissions error, even when you use sudo. (You probably won’t run into this if you’ve installed Python yourself with Homebrew or otherwise.) If this happens, you can install beets for the current user only (sans sudo) by typing pip install --user beets. If you do that, you might want to add ~/Library/Python/3.6/bin to your $PATH. Installing on Windows Installing beets on Windows can be tricky. Following these steps might help you get it right: 1. If you don’t have it, install Python (you want Python 3.6). The installer should give you the option to “add Python to PATH.” Check this box. If you do that, you can skip the next step. 2. If you haven’t done so already, set your PATH environment variable to include Python and its scripts. To do so, you have to get the “Properties” window for “My Computer”, then choose the “Advanced” tab, then hit the “Environment Variables” button, and then look for the PATH variable in the table. Add the following to the end of the variable’s value: ;C:\Python36;C:\Python36\Scripts. You may need to adjust these paths to point to your Python installation. 3. Now install beets by running: pip install beets 4. You’re all set! Type beet at the command prompt to make sure everything’s in order. Windows users may also want to install a context menu item for importing files into beets. Download the beets.reg file and open it in a text file to make sure the paths to Python match your system. Then double-click the file add the necessary keys to your registry. You can then right-click a directory and choose “Import with beets”. Because I don’t use Windows myself, I may have missed something. If you have trouble or you have more detail to contribute here, please direct it to the mailing list. Configuring You’ll want to set a few basic options before you start using beets. The configuration is stored in a text file. You can show its location by running beet config -p, though it may not exist yet. Run beet config -e to edit the configuration in your favorite text editor. The file will start out empty, but here’s good place to start: 4 Chapter 1. Contents beets Documentation, Release 1.4.7 directory:~/music library:~/data/musiclibrary.db Change that first path to a directory where you’d like to keep your music. Then, for library, choose a good place to keep a database file that keeps an index of your music. (The config’s format is YAML. You’ll want to configure your text editor to use spaces, not real tabs, for indentation. Also, ~ means your home directory in these paths, even on Windows.) The default configuration assumes you want to start a new organized music folder (that directory above) and that you’ll copy cleaned-up music into that empty folder using beets’ import command (see below). But you can configure beets to behave many other ways: • Start with a new empty directory, but move new music in instead of copying it (saving disk space). Put this in your config file: import: move: yes • Keep your current directory structure; importing should never move or copy files but instead just correct the tags on music. Put the line copy: no under the import: heading in your config file to disable any copying or renaming. Make sure to point directory at the place where your music is currently stored. • Keep your current directory structure and do not correct files’ tags: leave files completely unmodified on your disk. (Corrected tags will still be stored in beets’ database, and you can use them to do renaming or tag changes later.) Put this in your config file: import: copy: no write: no to disable renaming and tag-writing. There are approximately six million other configuration options you can set here, including the directory and file naming scheme. See Configuration for a full reference. Importing Your Library The next step is to import your music files into the beets library database. Because this can involve modifying files and moving them around, data loss is always a possibility, so now would be a good time to make sure you have a recent backup of all your music. We’ll wait. There are two good ways to bring your existing library into beets. You can either: (a) quickly bring all your files with all their current metadata into beets’ database, or (b) use beets’ highly-refined autotagger to find canonical metadata for every album you import. Option (a) is really fast, but option (b) makes sure all your songs’ tags are exactly right from the get-go. The point about speed bears repeating: using the autotagger on a large library can take a very long time, and it’s an interactive process. So set aside a good chunk of time if you’re going to go that route. For more on the interactive tagging process, see Using the Auto-Tagger. If you’ve got time and want to tag all your music right once and for all, do this: $ beet import /path/to/my/music (Note that by default, this command will copy music into the directory you specified above. If you want to use your current directory structure, set the import.copy config option.) To take the fast, un-autotagged path, just say: $ beet import -A /my/huge/mp3/library 1.1. Guides 5 beets Documentation, Release 1.4.7 Note that you just need to add -A for “don’t autotag”. Adding More Music If you’ve ripped or. otherwise obtained some new music, you can add it with the beet import command, the same way you imported your library. Like so: $ beet import ~/some_great_album This will attempt to autotag the new album (interactively) and add it to your library. There are, of course, more options for this command—just type beet help import to see what’s available.