mirror of
https://github.com/beetbox/beets.git
synced 2025-12-06 08:39:17 +01:00
Modernized getting started guide.
This commit is contained in:
Sebastian Mohr
parent
7e81f23de6
commit
1270364796
6 changed files with 540 additions and 262 deletions
|
|
@ -23,13 +23,16 @@ extensions = [
|
|||
"sphinx.ext.autodoc",
|
||||
"sphinx.ext.autosummary",
|
||||
"sphinx.ext.extlinks",
|
||||
"sphinx.ext.viewcode",
|
||||
"sphinx_design",
|
||||
"sphinx_copybutton",
|
||||
]
|
||||
|
||||
autosummary_generate = True
|
||||
exclude_patterns = ["_build"]
|
||||
templates_path = ["_templates"]
|
||||
source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
|
||||
|
||||
|
||||
pygments_style = "sphinx"
|
||||
|
||||
# External links to the bug tracker and other sites.
|
||||
|
|
|
|||
|
|
@ -9,5 +9,6 @@ guide.
|
|||
:maxdepth: 1
|
||||
|
||||
main
|
||||
installation
|
||||
tagger
|
||||
advanced
|
||||
|
|
|
|||
179
docs/guides/installation.rst
Normal file
179
docs/guides/installation.rst
Normal file
|
|
@ -0,0 +1,179 @@
|
|||
Installation
|
||||
============
|
||||
|
||||
Beets requires `Python 3.9 or later`_. You can install it using package
|
||||
managers, pipx_, pip_ or by using package managers.
|
||||
|
||||
.. _python 3.9 or later: https://python.org/download/
|
||||
|
||||
Using ``pipx`` or ``pip``
|
||||
-------------------------
|
||||
|
||||
We recommend installing with pipx_ as it isolates beets and its dependencies
|
||||
from your system Python and other Python packages. This helps avoid dependency
|
||||
conflicts and keeps your system clean.
|
||||
|
||||
.. <!-- start-quick-install -->
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: pipx
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pipx install beets
|
||||
|
||||
.. tab-item:: pip
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pip install beets
|
||||
|
||||
.. tab-item:: pip (user install)
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pip install --user beets
|
||||
|
||||
.. <!-- end-quick-install -->
|
||||
|
||||
If you don't have pipx_ installed, you can follow the instructions on the `pipx
|
||||
installation page`_ to get it set up.
|
||||
|
||||
.. _pip: https://pip.pypa.io/en/
|
||||
|
||||
.. _pipx: https://pipx.pypa.io/stable
|
||||
|
||||
.. _pipx installation page: https://pipx.pypa.io/stable/installation/
|
||||
|
||||
Using a Package Manager
|
||||
-----------------------
|
||||
|
||||
Depending on your operating system, you may be able to install beets using a
|
||||
package manager. Here are some common options:
|
||||
|
||||
.. attention::
|
||||
|
||||
Package manager installations may not provide the latest version of beets.
|
||||
|
||||
Release cycles for package managers vary, and they may not always have the
|
||||
most recent version of beets. If you want the latest features and fixes,
|
||||
consider using pipx_ or pip_ as described above.
|
||||
|
||||
Additionally, installing external beets plugins may be surprisingly
|
||||
difficult when using a package manager.
|
||||
|
||||
- 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 [extra] <arch extra_>`_, so just run ``pacman
|
||||
-S beets``. (There's also a bleeding-edge `dev package <aur_>`_ in the AUR,
|
||||
which will probably set your computer on fire.)
|
||||
- On **Alpine Linux**, `beets is in the community repository <alpine package_>`_
|
||||
and can be installed with ``apk add beets``.
|
||||
- On **Void Linux**, `beets is in the official repository <void package_>`_ and
|
||||
can be installed with ``xbps-install -S beets``.
|
||||
- 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 <freebsd_>`_ at ``audio/beets``.
|
||||
- On **OpenBSD**, there's a `beets port <openbsd_>`_ can be installed with
|
||||
``pkg_add beets``.
|
||||
- On **Fedora** 22 or later, there's a `DNF package`_ you can install with
|
||||
``sudo dnf install beets beets-plugins beets-doc``.
|
||||
- On **Solus**, run ``eopkg install beets``.
|
||||
- On **NixOS**, there's a `package <nixos_>`_ you can install with ``nix-env -i
|
||||
beets``.
|
||||
- Using **MacPorts**, run ``port install beets`` or ``port install beets-full``
|
||||
to include many third-party plugins.
|
||||
|
||||
.. _alpine package: https://pkgs.alpinelinux.org/package/edge/community/x86_64/beets
|
||||
|
||||
.. _arch extra: https://archlinux.org/packages/extra/any/beets/
|
||||
|
||||
.. _aur: https://aur.archlinux.org/packages/beets-git/
|
||||
|
||||
.. _debian details: https://tracker.debian.org/pkg/beets
|
||||
|
||||
.. _dnf package: https://packages.fedoraproject.org/pkgs/beets/
|
||||
|
||||
.. _freebsd: http://portsmon.freebsd.org/portoverview.py?category=audio&portname=beets
|
||||
|
||||
.. _nixos: https://github.com/NixOS/nixpkgs/tree/master/pkgs/tools/audio/beets
|
||||
|
||||
.. _openbsd: http://openports.se/audio/beets
|
||||
|
||||
.. _ubuntu details: https://launchpad.net/ubuntu/+source/beets
|
||||
|
||||
.. _void package: https://github.com/void-linux/void-packages/tree/master/srcpkgs/beets
|
||||
|
||||
Installation FAQ
|
||||
----------------
|
||||
|
||||
MacOS Installation
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Q: I'm getting permission errors on macOS. What should I do?**
|
||||
|
||||
Due to System Integrity Protection on macOS 10.11+, you may need to install for
|
||||
your user only:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pip install --user beets
|
||||
|
||||
You might need to also add ``~/Library/Python/3.x/bin`` to your ``$PATH``.
|
||||
|
||||
Windows Installation
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Q: What's the process for installing on Windows?**
|
||||
|
||||
Installing beets on Windows can be tricky. Following these steps might help you
|
||||
get it right:
|
||||
|
||||
1. `Install Python`_ (check "Add Python to PATH" skip to 3)
|
||||
2. Ensure Python is in your ``PATH`` (add if needed):
|
||||
|
||||
- Settings → System → About → Advanced system settings → Environment
|
||||
Variables
|
||||
- Edit "PATH" and add: `;C:\Python39;C:\Python39\Scripts`
|
||||
- *Guide: [Adding Python to
|
||||
PATH](https://realpython.com/add-python-to-path/)*
|
||||
|
||||
3. Now install beets by running: ``pip install beets``
|
||||
4. You're all set! Type ``beet version`` in a new command prompt to verify the
|
||||
installation.
|
||||
|
||||
**Bonus: Windows Context Menu Integration**
|
||||
|
||||
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".
|
||||
|
||||
.. _beets.reg: https://github.com/beetbox/beets/blob/master/extra/beets.reg
|
||||
|
||||
.. _install pip: https://pip.pypa.io/en/stable/installing/
|
||||
|
||||
.. _install python: https://python.org/download/
|
||||
|
||||
ARM Installation
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
**Q: Can I run beets on a Raspberry Pi or other ARM device?**
|
||||
|
||||
Yes, but with some considerations: Beets on ARM devices is not recommended for
|
||||
Linux novices. If you are comfortable with troubleshooting tools like ``pip``,
|
||||
``make``, and binary dependencies (e.g. ``ffmpeg`` and ``ImageMagick``), you
|
||||
will be fine. We have `notes for ARM`_ and an `older ARM reference`_. Beets is
|
||||
generally developed on x86-64 based devices, and most plugins target that
|
||||
platform as well.
|
||||
|
||||
.. _notes for arm: https://github.com/beetbox/beets/discussions/4910
|
||||
|
||||
.. _older arm reference: https://discourse.beets.io/t/diary-of-beets-on-arm-odroid-hc4-armbian/1993
|
||||
|
|
@ -1,341 +1,310 @@
|
|||
Getting Started
|
||||
===============
|
||||
|
||||
Welcome to beets_! This guide will help you begin using it to make your music
|
||||
collection better.
|
||||
Welcome to beets_! This guide will help get started with improving and
|
||||
organizing your music collection.
|
||||
|
||||
.. _beets: https://beets.io/
|
||||
|
||||
Installing
|
||||
----------
|
||||
Quick Installation
|
||||
------------------
|
||||
|
||||
Beets requires Python 3.9 or later, you will need to install that first.
|
||||
Depending on your operating system, you may also be able to install beets from a
|
||||
package manager, or you can install it with pipx_ or pip_.
|
||||
Beets is distributed via PyPI_ and can be installed by most users with a single
|
||||
command:
|
||||
|
||||
Using ``pipx``
|
||||
~~~~~~~~~~~~~~
|
||||
.. include:: installation.rst
|
||||
:start-after: <!-- start-quick-install -->
|
||||
:end-before: <!-- end-quick-install -->
|
||||
|
||||
To use the most recent version of beets, we recommend installing it with pipx_.
|
||||
If you don't have pipx_ installed, you can follow the instructions on the `pipx
|
||||
installation page`_ to get it set up.
|
||||
.. admonition:: Need more installation options?
|
||||
|
||||
Having trouble with the commands above? Looking for package manager
|
||||
instructions? See the :doc:`complete installation guide
|
||||
</guides/installation>` for:
|
||||
|
||||
- Operating system specific instructions
|
||||
- Package manager options
|
||||
- Troubleshooting help
|
||||
|
||||
.. _pypi: https://pypi.org/project/beets/
|
||||
|
||||
Basic Configuration
|
||||
-------------------
|
||||
|
||||
Before using beets, you'll need a configuration file. This YAML_ file tells
|
||||
beets where to store your music and how to organize it.
|
||||
|
||||
While beets is highly configurable, you only need a few basic settings to get
|
||||
started.
|
||||
|
||||
1. **Open the config file:**
|
||||
.. code-block:: console
|
||||
|
||||
pipx install beets
|
||||
beet config -e
|
||||
|
||||
Using ``pip``
|
||||
~~~~~~~~~~~~~
|
||||
This creates the file (if needed) and opens it in your default editor.
|
||||
You can also find its location with ``beet config -p``.
|
||||
2. **Add required settings:**
|
||||
In the config file, set the ``directory`` option to the path where you
|
||||
want beets to store your music files. Set the ``library`` option to the
|
||||
path where you want beets to store its database file.
|
||||
|
||||
If you prefer to use pip_, you can install beets with the following command:
|
||||
.. code-block:: yaml
|
||||
|
||||
.. code-block:: console
|
||||
directory: ~/music
|
||||
library: ~/data/musiclibrary.db
|
||||
3. **Choose your import style** (pick one):
|
||||
Beets offers flexible import strategies to match your workflow. Choose
|
||||
one of the following approaches and put one of the following in your
|
||||
config file:
|
||||
|
||||
pip install beets
|
||||
# or, to install for the current user only:
|
||||
pip install --user beets
|
||||
.. tab-set::
|
||||
|
||||
.. _pip: https://pip.pypa.io/en/
|
||||
.. tab-item:: Copy Files (Default)
|
||||
|
||||
.. _pipx: https://pipx.pypa.io/stable
|
||||
This is the default configuration and assumes you want to start a new organized music folder (inside ``directory`` above). During import we will *copy* cleaned-up music into that empty folder.
|
||||
|
||||
.. _pipx installation page: https://pipx.pypa.io/stable/installation/
|
||||
.. code-block:: yaml
|
||||
|
||||
Using a Package Manager
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
import:
|
||||
copy: yes # Copy files to new location
|
||||
|
||||
Depending on your operating system, you may be able to install beets using a
|
||||
package manager. Here are some common options:
|
||||
|
||||
.. attention::
|
||||
.. tab-item:: Move Files
|
||||
|
||||
Package manager installations may not provide the latest version of beets.
|
||||
Start with a new empty directory, but *move* new music in instead of copying it (saving disk space).
|
||||
|
||||
Release cycles for package managers vary, and they may not always have the
|
||||
most recent version of beets. If you want the latest features and fixes,
|
||||
consider using pipx_ or pip_ as described above.
|
||||
.. code-block:: yaml
|
||||
|
||||
Additionally, installing external beets plugins may be surprisingly
|
||||
difficult when using a package manager.
|
||||
import:
|
||||
move: yes # Move files to new location
|
||||
|
||||
- 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 [extra] <arch extra_>`_, so just run ``pacman
|
||||
-S beets``. (There's also a bleeding-edge `dev package <aur_>`_ in the AUR,
|
||||
which will probably set your computer on fire.)
|
||||
- On **Alpine Linux**, `beets is in the community repository <alpine package_>`_
|
||||
and can be installed with ``apk add beets``.
|
||||
- On **Void Linux**, `beets is in the official repository <void package_>`_ and
|
||||
can be installed with ``xbps-install -S beets``.
|
||||
- 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 <freebsd_>`_ at ``audio/beets``.
|
||||
- On **OpenBSD**, there's a `beets port <openbsd_>`_ can be installed with
|
||||
``pkg_add beets``.
|
||||
- On **Fedora** 22 or later, there's a `DNF package`_ you can install with
|
||||
``sudo dnf install beets beets-plugins beets-doc``.
|
||||
- On **Solus**, run ``eopkg install beets``.
|
||||
- On **NixOS**, there's a `package <nixos_>`_ you can install with ``nix-env -i
|
||||
beets``.
|
||||
- Using **MacPorts**, run ``port install beets`` or ``port install beets-full``
|
||||
to include many third-party plugins.
|
||||
.. tab-item:: Use Existing Structure
|
||||
|
||||
.. _alpine package: https://pkgs.alpinelinux.org/package/edge/community/x86_64/beets
|
||||
Keep your current directory structure; importing should never move or copy files but instead just correct the tags on music. Make sure to point ``directory`` at the place where your music is currently stored.
|
||||
|
||||
.. _arch extra: https://archlinux.org/packages/extra/any/beets/
|
||||
.. code-block:: yaml
|
||||
|
||||
.. _aur: https://aur.archlinux.org/packages/beets-git/
|
||||
import:
|
||||
copy: no # Use files in place
|
||||
|
||||
.. _debian details: https://tracker.debian.org/pkg/beets
|
||||
.. tab-item:: Read-Only Mode
|
||||
|
||||
.. _dnf package: https://packages.fedoraproject.org/pkgs/beets/
|
||||
Keep everything exactly as-is; only track metadata in database. (Corrected tags will still be stored in beets' database, and you can use them to do renaming or tag changes later.)
|
||||
|
||||
.. _freebsd: http://portsmon.freebsd.org/portoverview.py?category=audio&portname=beets
|
||||
.. code-block:: yaml
|
||||
|
||||
.. _nixos: https://github.com/NixOS/nixpkgs/tree/master/pkgs/tools/audio/beets
|
||||
import:
|
||||
copy: no # Use files in place
|
||||
write: no # Don't modify tags
|
||||
4. **Add customization via plugins (optional):**
|
||||
Beets comes with many plugins that extend its functionality. You can
|
||||
enable plugins by adding a `plugins` section to your config file.
|
||||
|
||||
.. _openbsd: http://openports.se/audio/beets
|
||||
We recommend adding at least one :ref:`Autotagger Plugin
|
||||
<autotagger_extensions>` to help with fetching metadata during import.
|
||||
For getting started, :doc:`MusicBrainz </plugins/musicbrainz>` is a good
|
||||
choice.
|
||||
|
||||
.. _ubuntu details: https://launchpad.net/ubuntu/+source/beets
|
||||
.. code-block:: yaml
|
||||
|
||||
.. _void package: https://github.com/void-linux/void-packages/tree/master/srcpkgs/beets
|
||||
plugins:
|
||||
- musicbrainz # Example plugin for fetching metadata
|
||||
- ... other plugins you want ...
|
||||
|
||||
Installing by Hand on macOS 10.11 and Higher
|
||||
++++++++++++++++++++++++++++++++++++++++++++
|
||||
You can find a list of available plugins in the :doc:`plugins index
|
||||
</plugins/index>`.
|
||||
|
||||
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. (You probably won't run into this if you've installed Python
|
||||
yourself with Homebrew or otherwise. You can also try MacPorts.)
|
||||
.. _yaml: https://yaml.org/
|
||||
|
||||
If this happens, you can install beets for the current user only by typing pip
|
||||
install --user beets. If you do that, you might want to add
|
||||
~/Library/Python/3.6/bin to your $PATH.
|
||||
To validate that you've set up your configuration and it is valid YAML, you can
|
||||
type ``beet version`` to see a list of enabled plugins or ``beet config`` to get
|
||||
a complete listing of your current configuration.
|
||||
|
||||
Installing on Windows
|
||||
+++++++++++++++++++++
|
||||
.. dropdown:: Full configuration file
|
||||
|
||||
Installing beets on Windows can be tricky. Following these steps might help you
|
||||
get it right:
|
||||
Here's a sample configuration file that includes the settings mentioned above:
|
||||
|
||||
1. If you don't have it, `install Python`_ (you want at least Python 3.9). 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, open the "Settings" application,
|
||||
then access the "System" screen, then access the "About" tab, and then hit
|
||||
"Advanced system settings" located on the right side of the screen. This
|
||||
should open the "System Properties" screen, then select the "Advanced" tab,
|
||||
then hit the "Environmental Variables..." button, and then look for the PATH
|
||||
variable in the table. Add the following to the end of the variable's value:
|
||||
``;C:\Python39;C:\Python39\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".
|
||||
|
||||
If you have trouble or you have more detail to contribute here, please direct it
|
||||
to `the discussion board`_.
|
||||
|
||||
.. _beets.reg: https://github.com/beetbox/beets/blob/master/extra/beets.reg
|
||||
|
||||
.. _get-pip.py: https://bootstrap.pypa.io/get-pip.py
|
||||
|
||||
.. _install pip: https://pip.pypa.io/en/stable/installing/
|
||||
|
||||
.. _install python: https://python.org/download/
|
||||
|
||||
Installing on ARM (Raspberry Pi and similar)
|
||||
++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
Beets on ARM devices is not recommended for Linux novices. If you are
|
||||
comfortable with light troubleshooting in tools like ``pip``, ``make``, and
|
||||
beets' command-line binary dependencies (e.g. ``ffmpeg`` and ``ImageMagick``),
|
||||
you will probably be okay on ARM devices like the Raspberry Pi. We have `notes
|
||||
for ARM`_ and an `older ARM reference`_. Beets is generally developed on x86-64
|
||||
based devices, and most plugins target that platform as well.
|
||||
|
||||
.. _notes for arm: https://github.com/beetbox/beets/discussions/4910
|
||||
|
||||
.. _older arm reference: https://discourse.beets.io/t/diary-of-beets-on-arm-odroid-hc4-armbian/1993
|
||||
|
||||
Configuring
|
||||
-----------
|
||||
|
||||
You'll want to set a few basic options before you start using beets. The
|
||||
:doc:`configuration </reference/config>` 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:
|
||||
|
||||
::
|
||||
.. code-block:: yaml
|
||||
|
||||
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
|
||||
move: yes # Move files to new location
|
||||
# copy: no # Use files in place
|
||||
# write: no # Don't modify tags
|
||||
|
||||
- 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:
|
||||
plugins:
|
||||
- musicbrainz # Example plugin for fetching metadata
|
||||
# - ... other plugins you want ...
|
||||
|
||||
::
|
||||
You can copy and paste this into your config file and modify it as needed.
|
||||
|
||||
import:
|
||||
copy: no
|
||||
write: no
|
||||
.. admonition:: Ready for more?
|
||||
|
||||
to disable renaming and tag-writing.
|
||||
For a complete reference of all configuration options, see the
|
||||
:doc:`configuration reference </reference/config>`.
|
||||
|
||||
There are other configuration options you can set here, including the directory
|
||||
and file naming scheme. See :doc:`/reference/config` for a full reference.
|
||||
Importing Your Music
|
||||
--------------------
|
||||
|
||||
.. _yaml: https://yaml.org/
|
||||
Now you're ready to import your music into beets!
|
||||
|
||||
To check that you've set up your configuration how you want it, you can type
|
||||
``beet version`` to see a list of enabled plugins or ``beet config`` to get a
|
||||
complete listing of your current configuration.
|
||||
.. important::
|
||||
|
||||
Importing Your Library
|
||||
----------------------
|
||||
Importing can modify and move your music files. **Make sure you have a
|
||||
recent backup** before proceeding.
|
||||
|
||||
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.
|
||||
Choose Your Import Method
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
There are two good ways to bring your *existing* library into beets database.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Autotag (Recommended)
|
||||
|
||||
This method uses beets' autotagger to find canonical metadata for every album you import. It may take a while, especially for large libraries, and it's an interactive process. But it ensures all your songs' tags are exactly right from the get-go.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
beet import /a/chunk/of/my/library
|
||||
|
||||
.. warning::
|
||||
|
||||
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
|
||||
time if you're going to go that route.
|
||||
|
||||
We also recommend importing smaller batches of music at a time (e.g., a few albums) to make the process more manageable. For more on the interactive tagging
|
||||
process, see :doc:`tagger`.
|
||||
|
||||
If you've got time and want to tag all your music right once and for all, do
|
||||
this:
|
||||
|
||||
::
|
||||
.. tab-item:: Quick Import
|
||||
|
||||
$ beet import /path/to/my/music
|
||||
This method quickly brings all your files with all their current metadata into beets' database without any changes. It's really fast, but it doesn't clean up or correct any tags.
|
||||
|
||||
(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:
|
||||
To use this method, run:
|
||||
|
||||
::
|
||||
.. code-block:: console
|
||||
|
||||
$ beet import -A /my/huge/mp3/library
|
||||
beet import -A /my/huge/mp3/library
|
||||
|
||||
Note that you just need to add ``-A`` for "don't autotag".
|
||||
The ``-A`` flag skips autotagging and uses your files' current metadata.
|
||||
|
||||
Adding More Music
|
||||
-----------------
|
||||
.. admonition:: More Import Options
|
||||
|
||||
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:
|
||||
The ``beet import`` command has many options to customize its behavior. For
|
||||
a full list, type ``beet help import`` or see the :ref:`import command
|
||||
reference <import-cmd>`.
|
||||
|
||||
::
|
||||
Adding More Music Later
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
$ beet import ~/some_great_album
|
||||
When you acquire new music, use the same ``beet import`` command to add it to
|
||||
your library:
|
||||
|
||||
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.
|
||||
.. code-block:: console
|
||||
|
||||
beet import ~/new_totally_not_ripped_album
|
||||
|
||||
This will apply the same autotagging process to your new additions. For
|
||||
alternative import behaviors, consult the options mentioned above.
|
||||
|
||||
Seeing Your Music
|
||||
-----------------
|
||||
|
||||
If you want to query your music library, the ``beet list`` (shortened to ``beet
|
||||
ls``) command is for you. You give it a :doc:`query string </reference/query>`,
|
||||
which is formatted something like a Google search, and it gives you a list of
|
||||
songs. Thus:
|
||||
Once you've imported music into beets, you'll want to explore and query your
|
||||
library. Beets provides several commands for searching, browsing, and getting
|
||||
statistics about your collection.
|
||||
|
||||
::
|
||||
Basic Searching
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The ``beet list`` command (shortened to ``beet ls``) lets you search your music
|
||||
library using :doc:`query string </reference/query>` similar to web searches:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ beet ls the magnetic fields
|
||||
The Magnetic Fields - Distortion - Three-Way
|
||||
The Magnetic Fields - Distortion - California Girls
|
||||
The Magnetic Fields - Dist
|
||||
The Magnetic Fields - Distortion - Old Fools
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ beet ls hissing gronlandic
|
||||
of Montreal - Hissing Fauna, Are You the Destroyer? - Gronlandic Edit
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ beet ls bird
|
||||
The Knife - The Knife - Bird
|
||||
The Mae Shi - Terrorbird - Revelation Six
|
||||
|
||||
By default, search terms match against :ref:`common attributes <keywordquery>`
|
||||
of songs, and multiple terms are combined with AND logic (a track must match
|
||||
*all* criteria).
|
||||
|
||||
Searching Specific Fields
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To narrow a search term to a particular metadata field, prefix the term with the
|
||||
field name followed by a colon. For example, ``album:bird`` searches for "bird"
|
||||
only in the "album" field of your songs. For more details, see
|
||||
:doc:`/reference/query/`.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ beet ls album:bird
|
||||
The Mae Shi - Terrorbird - Revelation Six
|
||||
|
||||
By default, a search term will match any of a handful of :ref:`common attributes
|
||||
<keywordquery>` of songs. (They're also implicitly joined by ANDs: a track must
|
||||
match *all* criteria in order to match the query.) To narrow a search term to a
|
||||
particular metadata field, just put the field before the term, separated by a :
|
||||
character. So ``album:bird`` only looks for ``bird`` in the "album" field of
|
||||
your songs. (Need to know more? :doc:`/reference/query/` will answer all your
|
||||
questions.)
|
||||
This searches only the ``album`` field for the term ``bird``.
|
||||
|
||||
Searching for Albums
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The ``beet list`` command also has an ``-a`` option, which searches for albums
|
||||
instead of songs:
|
||||
|
||||
::
|
||||
.. code-block:: console
|
||||
|
||||
$ beet ls -a forever
|
||||
Bon Iver - For Emma, Forever Ago
|
||||
Freezepop - Freezepop Forever
|
||||
|
||||
Custom Output Formatting
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
There's also an ``-f`` option (for *format*) that lets you specify what gets
|
||||
displayed in the results of a search:
|
||||
|
||||
::
|
||||
.. code-block:: console
|
||||
|
||||
$ beet ls -a forever -f "[$format] $album ($year) - $artist - $title"
|
||||
[MP3] For Emma, Forever Ago (2009) - Bon Iver - Flume
|
||||
[AAC] Freezepop Forever (2011) - Freezepop - Harebrained Scheme
|
||||
|
||||
In the format option, field references like ``$format`` and ``$year`` are filled
|
||||
in with data from each result. You can see a full list of available fields by
|
||||
running ``beet fields``.
|
||||
In the format string, field references like ``$format``, ``$year``, ``$album``,
|
||||
etc., are replaced with data from each result.
|
||||
|
||||
Beets also has a ``stats`` command, just in case you want to see how much music
|
||||
you have:
|
||||
.. dropdown:: Available fields for formatting
|
||||
|
||||
::
|
||||
To see all available fields you can use in custom formats, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
beet fields
|
||||
|
||||
This will display a comprehensive list of metadata fields available for your music.
|
||||
|
||||
Library Statistics
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Beets can also show you statistics about your music collection:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ beet stats
|
||||
Tracks: 13019
|
||||
|
|
@ -344,29 +313,107 @@ you have:
|
|||
Artists: 548
|
||||
Albums: 1094
|
||||
|
||||
.. admonition:: Ready for more advanced queries?
|
||||
|
||||
The ``beet list`` command has many additional options for sorting, limiting
|
||||
results, and more complex queries. For a complete reference, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
beet help list
|
||||
|
||||
Or see the :ref:`list command reference <list-cmd>`.
|
||||
|
||||
Keep Playing
|
||||
------------
|
||||
|
||||
This is only the beginning of your long and prosperous journey with beets. To
|
||||
keep learning, take a look at :doc:`advanced` for a sampling of what else is
|
||||
possible. You'll also want to glance over the :doc:`/reference/cli` page for a
|
||||
more detailed description of all of beets' functionality. (Like deleting music!
|
||||
That's important.)
|
||||
Congratulations! You've now mastered the basics of beets. But this is only the
|
||||
beginning, beets has many more powerful features to explore.
|
||||
|
||||
Also, check out :doc:`beets' plugins </plugins/index>`. The real power of beets
|
||||
is in its extensibility---with plugins, beets can do almost anything for your
|
||||
music collection.
|
||||
Continue Your Learning Journey
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can always get help using the ``beet help`` command. The plain ``beet help``
|
||||
command lists all the available commands; then, for example, ``beet help
|
||||
import`` gives more specific help about the ``import`` command.
|
||||
*I was there to push people beyond what's expected of them.*
|
||||
|
||||
If you need more of a walkthrough, you can read an illustrated one `on the beets
|
||||
blog <https://beets.io/blog/walkthrough.html>`_.
|
||||
.. grid:: 2
|
||||
:gutter: 3
|
||||
|
||||
Please let us know what you think of beets via `the discussion board`_ or
|
||||
Mastodon_.
|
||||
.. grid-item-card:: :octicon:`zap` Advanced Techniques
|
||||
:link: advanced
|
||||
:link-type: doc
|
||||
|
||||
.. _mastodon: https://fosstodon.org/@beets
|
||||
Explore sophisticated beets workflows including:
|
||||
|
||||
.. _the discussion board: https://github.com/beetbox/beets/discussions
|
||||
- Advanced tagging strategies
|
||||
- Complex import scenarios
|
||||
- Custom metadata management
|
||||
- Workflow automation
|
||||
|
||||
.. grid-item-card:: :octicon:`terminal` Command Reference
|
||||
:link: /reference/cli
|
||||
:link-type: doc
|
||||
|
||||
Comprehensive guide to all beets commands:
|
||||
|
||||
- Complete command syntax
|
||||
- All available options
|
||||
- Usage examples
|
||||
- **Important operations like deleting music**
|
||||
|
||||
.. grid-item-card:: :octicon:`plug` Plugin Ecosystem
|
||||
:link: /plugins/index
|
||||
:link-type: doc
|
||||
|
||||
Discover beets' true power through plugins:
|
||||
|
||||
- Metadata fetching from multiple sources
|
||||
- Audio analysis and processing
|
||||
- Streaming service integration
|
||||
- Custom export formats
|
||||
|
||||
.. grid-item-card:: :octicon:`question` Illustrated Walkthrough
|
||||
:link: https://beets.io/blog/walkthrough.html
|
||||
:link-type: url
|
||||
|
||||
Visual, step-by-step guide covering:
|
||||
|
||||
- Real-world import examples
|
||||
- Screenshots of interactive tagging
|
||||
- Common workflow patterns
|
||||
- Troubleshooting tips
|
||||
|
||||
.. admonition:: Need Help?
|
||||
|
||||
Remember you can always use ``beet help`` to see all available commands, or
|
||||
``beet help [command]`` for detailed help on specific commands.
|
||||
|
||||
Join the Community
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
We'd love to hear about your experience with beets!
|
||||
|
||||
.. grid:: 2
|
||||
:gutter: 2
|
||||
|
||||
.. grid-item-card:: :octicon:`comment-discussion` Discussion Board
|
||||
:link: https://github.com/beetbox/beets/discussions
|
||||
:link-type: url
|
||||
|
||||
- Ask questions
|
||||
- Share tips and tricks
|
||||
- Discuss feature ideas
|
||||
- Get help from other users
|
||||
|
||||
.. grid-item-card:: :octicon:`git-pull-request` Developer Resources
|
||||
:link: https://github.com/beetbox/beets
|
||||
:link-type: url
|
||||
|
||||
- Contribute code
|
||||
- Report issues
|
||||
- Review pull requests
|
||||
- Join development discussions
|
||||
|
||||
.. admonition:: Found a Bug?
|
||||
|
||||
If you encounter any issues, please report them on our `GitHub Issues page
|
||||
<https://github.com/beetbox/beets/issues>`_.
|
||||
|
|
|
|||
45
poetry.lock
generated
45
poetry.lock
generated
|
|
@ -3216,6 +3216,49 @@ docs = ["sphinxcontrib-websupport"]
|
|||
lint = ["flake8 (>=6.0)", "importlib-metadata (>=6.0)", "mypy (==1.10.1)", "pytest (>=6.0)", "ruff (==0.5.2)", "sphinx-lint (>=0.9)", "tomli (>=2)", "types-docutils (==0.21.0.20240711)", "types-requests (>=2.30.0)"]
|
||||
test = ["cython (>=3.0)", "defusedxml (>=0.7.1)", "pytest (>=8.0)", "setuptools (>=70.0)", "typing_extensions (>=4.9)"]
|
||||
|
||||
[[package]]
|
||||
name = "sphinx-copybutton"
|
||||
version = "0.5.2"
|
||||
description = "Add a copy button to each of your code cells."
|
||||
optional = false
|
||||
python-versions = ">=3.7"
|
||||
files = [
|
||||
{file = "sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd"},
|
||||
{file = "sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e"},
|
||||
]
|
||||
|
||||
[package.dependencies]
|
||||
sphinx = ">=1.8"
|
||||
|
||||
[package.extras]
|
||||
code-style = ["pre-commit (==2.12.1)"]
|
||||
rtd = ["ipython", "myst-nb", "sphinx", "sphinx-book-theme", "sphinx-examples"]
|
||||
|
||||
[[package]]
|
||||
name = "sphinx-design"
|
||||
version = "0.6.1"
|
||||
description = "A sphinx extension for designing beautiful, view size responsive web components."
|
||||
optional = false
|
||||
python-versions = ">=3.9"
|
||||
files = [
|
||||
{file = "sphinx_design-0.6.1-py3-none-any.whl", hash = "sha256:b11f37db1a802a183d61b159d9a202314d4d2fe29c163437001324fe2f19549c"},
|
||||
{file = "sphinx_design-0.6.1.tar.gz", hash = "sha256:b44eea3719386d04d765c1a8257caca2b3e6f8421d7b3a5e742c0fd45f84e632"},
|
||||
]
|
||||
|
||||
[package.dependencies]
|
||||
sphinx = ">=6,<9"
|
||||
|
||||
[package.extras]
|
||||
code-style = ["pre-commit (>=3,<4)"]
|
||||
rtd = ["myst-parser (>=2,<4)"]
|
||||
testing = ["defusedxml", "myst-parser (>=2,<4)", "pytest (>=8.3,<9.0)", "pytest-cov", "pytest-regressions"]
|
||||
testing-no-myst = ["defusedxml", "pytest (>=8.3,<9.0)", "pytest-cov", "pytest-regressions"]
|
||||
theme-furo = ["furo (>=2024.7.18,<2024.8.0)"]
|
||||
theme-im = ["sphinx-immaterial (>=0.12.2,<0.13.0)"]
|
||||
theme-pydata = ["pydata-sphinx-theme (>=0.15.2,<0.16.0)"]
|
||||
theme-rtd = ["sphinx-rtd-theme (>=2.0,<3.0)"]
|
||||
theme-sbt = ["sphinx-book-theme (>=1.1,<2.0)"]
|
||||
|
||||
[[package]]
|
||||
name = "sphinx-lint"
|
||||
version = "1.0.0"
|
||||
|
|
@ -3629,4 +3672,4 @@ web = ["flask", "flask-cors"]
|
|||
[metadata]
|
||||
lock-version = "2.0"
|
||||
python-versions = ">=3.9,<4"
|
||||
content-hash = "faea27878ce1ca3f1335fd83e027b289351c51c73550bda72bf501a9c82166f7"
|
||||
content-hash = "caa669bfb1ff913d528553de4bc4f420279e6bc9b119d39c4db616041576266d"
|
||||
|
|
|
|||
|
|
@ -119,6 +119,11 @@ click = ">=8.1.7"
|
|||
packaging = ">=24.0"
|
||||
tomli = ">=2.0.1"
|
||||
|
||||
|
||||
[tool.poetry.group.docs.dependencies]
|
||||
sphinx-design = "^0.6.1"
|
||||
sphinx-copybutton = "^0.5.2"
|
||||
|
||||
[tool.poetry.extras]
|
||||
# inline comments note required external / non-python dependencies
|
||||
absubmit = ["requests"] # extractor binary from https://acousticbrainz.org/download
|
||||
|
|
@ -129,7 +134,7 @@ beatport = ["requests-oauthlib"]
|
|||
bpd = ["PyGObject"] # gobject-introspection, gstreamer1.0-plugins-base, python3-gst-1.0
|
||||
chroma = ["pyacoustid"] # chromaprint or fpcalc
|
||||
# convert # ffmpeg
|
||||
docs = ["pydata-sphinx-theme", "sphinx", "sphinx-lint"]
|
||||
docs = ["pydata-sphinx-theme", "sphinx", "sphinx-lint", "sphinx-design", "sphinx-copybutton"]
|
||||
discogs = ["python3-discogs-client"]
|
||||
embedart = ["Pillow"] # ImageMagick
|
||||
embyupdate = ["requests"]
|
||||
|
|
|
|||
Loading…
Reference in a new issue