From 116357e2f6585b538d8d5b0657d9ce2b73ff6f18 Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Tue, 27 May 2025 13:29:25 +0200 Subject: [PATCH 01/13] Removed outdated installation instructions. - macport: stuck on 1.6 - slackware: stuck on 1.6 - OpenBSD: stuck on 1.6 Remove twitter reference. Removed mailing list reference. --- docs/faq.rst | 51 ++++++++++-------- docs/guides/main.rst | 118 ++++++++++++++++++----------------------- docs/guides/tagger.rst | 2 - 3 files changed, 82 insertions(+), 89 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index 3e527e8bc..40da1216b 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -163,31 +163,38 @@ documentation ` pages. .. _bugs: …report a bug in beets? -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- -We use the `issue tracker`_ on GitHub where you can `open a new ticket`_. Please -follow these guidelines when reporting an issue: +We use the `issue tracker`_ on GitHub where you can `open a new ticket`_. +Please follow these guidelines when reporting an issue: -- Most importantly: if beets is crashing, please `include the traceback - `__. Tracebacks can be more readable if you put them - in a pastebin (e.g., `Gist `__ or `Hastebin - `__), especially when communicating over IRC or email. -- Turn on beets' debug output (using the -v option: for example, ``beet -v - import ...``) and include that with your bug report. Look through this verbose - output for any red flags that might point to the problem. -- If you can, try installing the latest beets source code to see if the bug is - fixed in an unreleased version. You can also look at the :doc:`latest - changelog entries ` for descriptions of the problem you're seeing. -- Try to narrow your problem down to something specific. Is a particular plugin - causing the problem? (You can disable plugins to see whether the problem goes - away.) Is a some music file or a single album leading to the crash? (Try - importing individual albums to determine which one is causing the problem.) Is - some entry in your configuration file causing it? Et cetera. -- If you do narrow the problem down to a particular audio file or album, include - it with your bug report so the developers can run tests. +- Most importantly: if beets is crashing, please `include the + traceback `__. Tracebacks can be more + readable if you put them in a pastebin (e.g., + `Gist `__ or + `Hastebin `__), especially when communicating + over IRC. +- Turn on beets' debug output (using the -v option: for example, + ``beet -v import ...``) and include that with your bug report. Look + through this verbose output for any red flags that might point to the + problem. +- If you can, try installing the latest beets source code to see if the + bug is fixed in an unreleased version. You can also look at the + :doc:`latest changelog entries ` + for descriptions of the problem you're seeing. +- Try to narrow your problem down to something specific. Is a + particular plugin causing the problem? (You can disable plugins to + see whether the problem goes away.) Is a some music file or a single + album leading to the crash? (Try importing individual albums to + determine which one is causing the problem.) Is some entry in your + configuration file causing it? Et cetera. +- If you do narrow the problem down to a particular audio file or + album, include it with your bug report so the developers can run + tests. -If you've never reported a bug before, Mozilla has some well-written `general -guidelines for good bug reports`_. +If you've never reported a bug before, Mozilla has some well-written +`general guidelines for good bug +reports`_. .. _find-config: diff --git a/docs/guides/main.rst b/docs/guides/main.rst index 0b502bfb1..1c6454958 100644 --- a/docs/guides/main.rst +++ b/docs/guides/main.rst @@ -9,13 +9,36 @@ collection better. Installing ---------- -You will need Python. Beets works on Python 3.8 or later. +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 `pip`_. -- **macOS** 11 (Big Sur) includes Python 3.8 out of the box. You can opt for a - more recent Python installing it via Homebrew_ (``brew install python3``). - There's also a MacPorts_ port. Run ``port install beets`` or ``port install - beets-full`` to include many third-party plugins. -- On **Debian or Ubuntu**, depending on the version, beets is available as an +Using pip +^^^^^^^^^ + +To use the most recent version of beets, we recommend installing it with +`pip`_, the Python package manager. If you don't have `pip`_ installed, you can +follow the instructions on the `pip installation page`_ to get it set up. + +.. code-block:: console + + pip install beets + # or, to install for the current user only: + pip install --user beets + + +.. attention:: Python 3.13 not officially supported yet! + + If you are using Python 3.13, please be aware that it is not yet officially supported yet. + You may encounter issues, and we recommend using Python 3.12 or earlier until support is confirmed. + + +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: + +* 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 @@ -55,48 +78,16 @@ You will need Python. Beets works on Python 3.8 or later. .. _macports: https://www.macports.org -.. _nixos: https://github.com/NixOS/nixpkgs/tree/master/pkgs/tools/audio/beets - -.. _openbsd: http://openports.se/audio/beets - -.. _slackbuild: https://slackbuilds.org/repository/14.2/multimedia/beets/ - -.. _ubuntu details: https://launchpad.net/ubuntu/+source/beets - -.. _void package: https://github.com/void-linux/void-packages/tree/master/srcpkgs/beets - -If you have pip_, just say ``pip install beets`` (or ``pip install --user -beets`` if you run into permissions problems). - -To install without pip, download beets from `its PyPI page`_ and run ``python -setup.py install`` in the directory therein. - -.. _its pypi page: https://pypi.org/project/beets/#files - -.. _pip: https://pip.pypa.io - -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. - -.. _@b33ts: https://twitter.com/b33ts - -Installing by Hand 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. (You probably *won't* run into this if you've installed -Python yourself with Homebrew_ or otherwise. You can also try MacPorts_.) - -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``. - -.. _homebrew: https://brew.sh - -.. _system integrity protection: https://support.apple.com/en-us/HT204899 +.. _DNF package: https://packages.fedoraproject.org/pkgs/beets/ +.. _FreeBSD: http://portsmon.freebsd.org/portoverview.py?category=audio&portname=beets +.. _AUR: https://aur.archlinux.org/packages/beets-git/ +.. _Debian details: https://tracker.debian.org/pkg/beets +.. _Ubuntu details: https://launchpad.net/ubuntu/+source/beets +.. _Arch extra: https://archlinux.org/packages/extra/any/beets/ +.. _Alpine package: https://pkgs.alpinelinux.org/package/edge/community/x86_64/beets +.. _NixOS: https://github.com/NixOS/nixpkgs/tree/master/pkgs/tools/audio/beets +.. _pip: https://pip.pypa.io/en/ +.. _pip installation page: https://pip.pypa.io/en/stable/installation/ Installing on Windows ~~~~~~~~~~~~~~~~~~~~~ @@ -104,17 +95,18 @@ 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 at least Python 3.8). 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. +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:\Python38;C:\Python38\Scripts``. You may need to adjust these paths 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 @@ -126,9 +118,8 @@ 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`_. +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 @@ -348,8 +339,5 @@ blog `_. Please let us know what you think of beets via `the discussion board`_ or Mastodon_. -.. _mastodon: https://fosstodon.org/@beets - .. _the discussion board: https://github.com/beetbox/beets/discussions - -.. _the mailing list: https://groups.google.com/group/beets-users +.. _mastodon: https://fosstodon.org/@beets diff --git a/docs/guides/tagger.rst b/docs/guides/tagger.rst index c07d5df58..f43c1608c 100644 --- a/docs/guides/tagger.rst +++ b/docs/guides/tagger.rst @@ -311,5 +311,3 @@ If we haven't made the process clear, please post on `the discussion board`_ and we'll try to improve this guide. .. _the discussion board: https://github.com/beetbox/beets/discussions/ - -.. _the mailing list: https://groups.google.com/group/beets-users From 103b501af790b54bc2e5c63df1f35287a8299947 Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Tue, 27 May 2025 13:30:59 +0200 Subject: [PATCH 02/13] Removed mailing list ref in index.rst --- docs/index.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 2b2c2e723..870f608c7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,12 +13,10 @@ Then you can get a more detailed look at beets' features in the be interested in exploring the :doc:`plugins `. If you still need help, you can drop by the ``#beets`` IRC channel on -Libera.Chat, 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. +Libera.Chat, drop by `the discussion board`_ or `file a bug`_ in the issue tracker. +Please let us know where you think this documentation can be improved. .. _beets: https://beets.io/ - .. _file a bug: https://github.com/beetbox/beets/issues .. _the discussion board: https://github.com/beetbox/beets/discussions/ From 3b5eee59eef79a7236e068409301aac71beb01ae Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Tue, 27 May 2025 13:32:50 +0200 Subject: [PATCH 03/13] Added changelog entry. --- docs/changelog.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 23278bb36..fd72f4f7a 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -15,6 +15,9 @@ For packagers: Other changes: +- Removed old mailing list contact info in docs :bug:`5462` +- :doc:`guides/main`: Modernized getting started guide using tabs and dropdown menue. Installtion instructions are now more condensed and there is a subpage for additional instructions. + 2.5.0 (October 11, 2025) ------------------------ @@ -61,8 +64,6 @@ Bug fixes: configuration option has been renamed to ``data_source_mismatch_penalty`` to better reflect its purpose. :bug:`6066` -For packagers: - Other changes: - :doc:`plugins/index`: Clarify that musicbrainz must be mentioned if plugin From 81c622bcecf442f4eda4dc184d4ae7dcaf3fd389 Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Tue, 27 May 2025 13:38:25 +0200 Subject: [PATCH 04/13] Removed duplicate yet. --- docs/guides/main.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/main.rst b/docs/guides/main.rst index 1c6454958..99fa9be91 100644 --- a/docs/guides/main.rst +++ b/docs/guides/main.rst @@ -29,7 +29,7 @@ follow the instructions on the `pip installation page`_ to get it set up. .. attention:: Python 3.13 not officially supported yet! - If you are using Python 3.13, please be aware that it is not yet officially supported yet. + If you are using Python 3.13, please be aware that it is not officially supported yet. You may encounter issues, and we recommend using Python 3.12 or earlier until support is confirmed. From 1aaaeb49ed595dab16350f9f3b51b06ac357e7a5 Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Sat, 31 May 2025 21:35:57 +0200 Subject: [PATCH 05/13] Added pipx refernces --- docs/guides/main.rst | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/guides/main.rst b/docs/guides/main.rst index 99fa9be91..abb6d5b3e 100644 --- a/docs/guides/main.rst +++ b/docs/guides/main.rst @@ -11,14 +11,20 @@ Installing 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 `pip`_. +manager, or you can install it with `pipx`_ or `pip`_. Using pip ^^^^^^^^^ To use the most recent version of beets, we recommend installing it with -`pip`_, the Python package manager. If you don't have `pip`_ installed, you can -follow the instructions on the `pip installation page`_ to get it set up. +`pipx`_, the Python package manager. If you don't have `pipx`_ installed, you can +follow the instructions on the `pipx installation page`_ to get it set up. + +.. code-block:: console + + pipx install beets + +If you prefer to use `pip`_, you can install beets with the following command: .. code-block:: console @@ -87,7 +93,8 @@ Depending on your operating system, you may be able to install beets using a pac .. _Alpine package: https://pkgs.alpinelinux.org/package/edge/community/x86_64/beets .. _NixOS: https://github.com/NixOS/nixpkgs/tree/master/pkgs/tools/audio/beets .. _pip: https://pip.pypa.io/en/ -.. _pip installation page: https://pip.pypa.io/en/stable/installation/ +.. _pipx: https://pipx.pypa.io/stable +.. _pipx installation page: https://pipx.pypa.io/stable/installation/ Installing on Windows ~~~~~~~~~~~~~~~~~~~~~ From e30772f0c1254a7d0084e5d01f3eb69817d9c25e Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Mon, 8 Sep 2025 15:33:54 +0200 Subject: [PATCH 06/13] Run formatter. --- docs/faq.rst | 49 ++++++++++------------ docs/guides/main.rst | 97 ++++++++++++++++++++++++-------------------- docs/index.rst | 5 ++- 3 files changed, 77 insertions(+), 74 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index 40da1216b..287dc88af 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -165,36 +165,29 @@ documentation ` pages. …report a bug in beets? ----------------------- -We use the `issue tracker`_ on GitHub where you can `open a new ticket`_. -Please follow these guidelines when reporting an issue: +We use the `issue tracker`_ on GitHub where you can `open a new ticket`_. Please +follow these guidelines when reporting an issue: -- Most importantly: if beets is crashing, please `include the - traceback `__. Tracebacks can be more - readable if you put them in a pastebin (e.g., - `Gist `__ or - `Hastebin `__), especially when communicating - over IRC. -- Turn on beets' debug output (using the -v option: for example, - ``beet -v import ...``) and include that with your bug report. Look - through this verbose output for any red flags that might point to the - problem. -- If you can, try installing the latest beets source code to see if the - bug is fixed in an unreleased version. You can also look at the - :doc:`latest changelog entries ` - for descriptions of the problem you're seeing. -- Try to narrow your problem down to something specific. Is a - particular plugin causing the problem? (You can disable plugins to - see whether the problem goes away.) Is a some music file or a single - album leading to the crash? (Try importing individual albums to - determine which one is causing the problem.) Is some entry in your - configuration file causing it? Et cetera. -- If you do narrow the problem down to a particular audio file or - album, include it with your bug report so the developers can run - tests. +- Most importantly: if beets is crashing, please `include the traceback + `__. Tracebacks can be more readable if you put them + in a pastebin (e.g., `Gist `__ or `Hastebin + `__), especially when communicating over IRC. +- Turn on beets' debug output (using the -v option: for example, ``beet -v + import ...``) and include that with your bug report. Look through this verbose + output for any red flags that might point to the problem. +- If you can, try installing the latest beets source code to see if the bug is + fixed in an unreleased version. You can also look at the :doc:`latest + changelog entries ` for descriptions of the problem you're seeing. +- Try to narrow your problem down to something specific. Is a particular plugin + causing the problem? (You can disable plugins to see whether the problem goes + away.) Is a some music file or a single album leading to the crash? (Try + importing individual albums to determine which one is causing the problem.) Is + some entry in your configuration file causing it? Et cetera. +- If you do narrow the problem down to a particular audio file or album, include + it with your bug report so the developers can run tests. -If you've never reported a bug before, Mozilla has some well-written -`general guidelines for good bug -reports`_. +If you've never reported a bug before, Mozilla has some well-written `general +guidelines for good bug reports`_. .. _find-config: diff --git a/docs/guides/main.rst b/docs/guides/main.rst index abb6d5b3e..070ab0e2c 100644 --- a/docs/guides/main.rst +++ b/docs/guides/main.rst @@ -9,22 +9,22 @@ collection better. Installing ---------- -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 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_. -Using pip -^^^^^^^^^ +Using pip(x) +~~~~~~~~~~~~ -To use the most recent version of beets, we recommend installing it with -`pipx`_, the Python package manager. If you don't have `pipx`_ installed, you can -follow the instructions on the `pipx installation page`_ to get it set up. +To use the most recent version of beets, we recommend installing it with pipx_, +the Python package manager. If you don't have pipx_ installed, you can follow +the instructions on the `pipx installation page`_ to get it set up. .. code-block:: console pipx install beets -If you prefer to use `pip`_, you can install beets with the following command: +If you prefer to use pip_, you can install beets with the following command: .. code-block:: console @@ -32,19 +32,35 @@ If you prefer to use `pip`_, you can install beets with the following command: # or, to install for the current user only: pip install --user beets +.. attention:: -.. attention:: Python 3.13 not officially supported yet! - - If you are using Python 3.13, please be aware that it is not officially supported yet. - You may encounter issues, and we recommend using Python 3.12 or earlier until support is confirmed. + Python 3.13 is not officially supported yet! + If you are using Python 3.13, please be aware that it is not officially + supported yet. You may encounter issues, and we recommend using Python 3.12 + or earlier until support is confirmed. + +.. _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: +Depending on your operating system, you may be able to install beets using a +package manager. Here are some common options: -* On **Debian or Ubuntu**, depending on the version, beets is available as an +.. 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. + +- 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 @@ -63,7 +79,6 @@ Depending on your operating system, you may be able to install beets using a pac - On **FreeBSD**, there's a `beets port `_ at ``audio/beets``. - On **OpenBSD**, there's a `beets port `_ can be installed with ``pkg_add beets``. -- For **Slackware**, there's a SlackBuild_ available. - 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``. @@ -82,38 +97,31 @@ Depending on your operating system, you may be able to install beets using a pac .. _freebsd: http://portsmon.freebsd.org/portoverview.py?category=audio&portname=beets -.. _macports: https://www.macports.org +.. _nixos: https://github.com/NixOS/nixpkgs/tree/master/pkgs/tools/audio/beets -.. _DNF package: https://packages.fedoraproject.org/pkgs/beets/ -.. _FreeBSD: http://portsmon.freebsd.org/portoverview.py?category=audio&portname=beets -.. _AUR: https://aur.archlinux.org/packages/beets-git/ -.. _Debian details: https://tracker.debian.org/pkg/beets -.. _Ubuntu details: https://launchpad.net/ubuntu/+source/beets -.. _Arch extra: https://archlinux.org/packages/extra/any/beets/ -.. _Alpine package: https://pkgs.alpinelinux.org/package/edge/community/x86_64/beets -.. _NixOS: https://github.com/NixOS/nixpkgs/tree/master/pkgs/tools/audio/beets -.. _pip: https://pip.pypa.io/en/ -.. _pipx: https://pipx.pypa.io/stable -.. _pipx installation page: https://pipx.pypa.io/stable/installation/ +.. _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 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 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. - + 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 + 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 @@ -125,8 +133,8 @@ 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`_. +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 @@ -137,7 +145,7 @@ If you have trouble or you have more detail to contribute here, please direct it .. _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 @@ -346,5 +354,6 @@ blog `_. Please let us know what you think of beets via `the discussion board`_ or Mastodon_. -.. _the discussion board: https://github.com/beetbox/beets/discussions .. _mastodon: https://fosstodon.org/@beets + +.. _the discussion board: https://github.com/beetbox/beets/discussions diff --git a/docs/index.rst b/docs/index.rst index 870f608c7..13e28c1c2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,10 +13,11 @@ Then you can get a more detailed look at beets' features in the be interested in exploring the :doc:`plugins `. If you still need help, you can drop by the ``#beets`` IRC channel on -Libera.Chat, drop by `the discussion board`_ or `file a bug`_ in the issue tracker. -Please let us know where you think this documentation can be improved. +Libera.Chat, drop by `the discussion board`_ or `file a bug`_ in the issue +tracker. Please let us know where you think this documentation can be improved. .. _beets: https://beets.io/ + .. _file a bug: https://github.com/beetbox/beets/issues .. _the discussion board: https://github.com/beetbox/beets/discussions/ From 7caa68a1412fff902597fa1e6b3cc8513f640921 Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Tue, 9 Sep 2025 12:25:05 +0200 Subject: [PATCH 07/13] Re-added macport instructions. Removed mailing list ref. Added section header for pip and pipx. Removed python 3.13 attention. --- docs/guides/main.rst | 26 +++++++++++++------------- docs/index.rst | 2 -- 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/docs/guides/main.rst b/docs/guides/main.rst index 070ab0e2c..2ac2dafe1 100644 --- a/docs/guides/main.rst +++ b/docs/guides/main.rst @@ -13,17 +13,20 @@ 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_. -Using pip(x) -~~~~~~~~~~~~ +Using ``pipx`` +~~~~~~~~~~~~~~ -To use the most recent version of beets, we recommend installing it with pipx_, -the Python package manager. If you don't have pipx_ installed, you can follow -the instructions on the `pipx installation page`_ to get it set up. +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. .. code-block:: console pipx install beets +Using ``pip`` +~~~~~~~~~~~~~ + If you prefer to use pip_, you can install beets with the following command: .. code-block:: console @@ -32,14 +35,6 @@ If you prefer to use pip_, you can install beets with the following command: # or, to install for the current user only: pip install --user beets -.. attention:: - - Python 3.13 is not officially supported yet! - - If you are using Python 3.13, please be aware that it is not officially - supported yet. You may encounter issues, and we recommend using Python 3.12 - or earlier until support is confirmed. - .. _pip: https://pip.pypa.io/en/ .. _pipx: https://pipx.pypa.io/stable @@ -60,6 +55,9 @@ package manager. Here are some common options: 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 @@ -84,6 +82,8 @@ package manager. Here are some common options: - On **Solus**, run ``eopkg install beets``. - On **NixOS**, there's a `package `_ 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 diff --git a/docs/index.rst b/docs/index.rst index 13e28c1c2..e9dd3b34f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,8 +22,6 @@ tracker. Please let us know where you think this documentation can be improved. .. _the discussion board: https://github.com/beetbox/beets/discussions/ -.. _the mailing list: https://groups.google.com/group/beets-users - Contents -------- From 7e81f23de6be00c7f70d30afc84bec01519f9487 Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Tue, 9 Sep 2025 12:52:37 +0200 Subject: [PATCH 08/13] Readded (outdated) mac instructions. No idea why they were dropped. --- docs/guides/main.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/guides/main.rst b/docs/guides/main.rst index 2ac2dafe1..84b719cbf 100644 --- a/docs/guides/main.rst +++ b/docs/guides/main.rst @@ -105,6 +105,19 @@ package manager. Here are some common options: .. _void package: https://github.com/void-linux/void-packages/tree/master/srcpkgs/beets +Installing by Hand 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. (You probably won't run into this if you've installed Python +yourself with Homebrew or otherwise. You can also try MacPorts.) + +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. + Installing on Windows +++++++++++++++++++++ From 1270364796cf6190e048f2f3c66101aeee72b716 Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Tue, 30 Sep 2025 19:21:21 +0200 Subject: [PATCH 09/13] Modernized getting started guide. --- docs/conf.py | 5 +- docs/guides/index.rst | 1 + docs/guides/installation.rst | 179 +++++++++++ docs/guides/main.rst | 565 +++++++++++++++++++---------------- poetry.lock | 45 ++- pyproject.toml | 7 +- 6 files changed, 540 insertions(+), 262 deletions(-) create mode 100644 docs/guides/installation.rst diff --git a/docs/conf.py b/docs/conf.py index c76f87524..057141d22 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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. diff --git a/docs/guides/index.rst b/docs/guides/index.rst index 08685abba..0695e9ff8 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -9,5 +9,6 @@ guide. :maxdepth: 1 main + installation tagger advanced diff --git a/docs/guides/installation.rst b/docs/guides/installation.rst new file mode 100644 index 000000000..648a72d0b --- /dev/null +++ b/docs/guides/installation.rst @@ -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. + +.. + +.. 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 + +.. + +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] `_, 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.) +- On **Alpine Linux**, `beets is in the community repository `_ + and can be installed with ``apk add beets``. +- On **Void Linux**, `beets is in the official repository `_ 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 `_ at ``audio/beets``. +- On **OpenBSD**, there's a `beets port `_ 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 `_ 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 diff --git a/docs/guides/main.rst b/docs/guides/main.rst index 84b719cbf..2b8947edb 100644 --- a/docs/guides/main.rst +++ b/docs/guides/main.rst @@ -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: + :end-before: -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? -.. code-block:: console + Having trouble with the commands above? Looking for package manager + instructions? See the :doc:`complete installation guide + ` for: - pipx install beets + - Operating system specific instructions + - Package manager options + - Troubleshooting help -Using ``pip`` -~~~~~~~~~~~~~ +.. _pypi: https://pypi.org/project/beets/ -If you prefer to use pip_, you can install beets with the following command: +Basic Configuration +------------------- -.. code-block:: console +Before using beets, you'll need a configuration file. This YAML_ file tells +beets where to store your music and how to organize it. - pip install beets - # or, to install for the current user only: - pip install --user beets +While beets is highly configurable, you only need a few basic settings to get +started. -.. _pip: https://pip.pypa.io/en/ +1. **Open the config file:** + .. code-block:: console -.. _pipx: https://pipx.pypa.io/stable + beet config -e -.. _pipx installation page: https://pipx.pypa.io/stable/installation/ + 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. -Using a Package Manager -~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: yaml -Depending on your operating system, you may be able to install beets using a -package manager. Here are some common options: + 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: -.. attention:: + .. tab-set:: - Package manager installations may not provide the latest version of beets. + .. tab-item:: Copy Files (Default) - 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. + 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. - Additionally, installing external beets plugins may be surprisingly - difficult when using a package manager. + .. code-block:: yaml -- 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] `_, 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.) -- On **Alpine Linux**, `beets is in the community repository `_ - and can be installed with ``apk add beets``. -- On **Void Linux**, `beets is in the official repository `_ 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 `_ at ``audio/beets``. -- On **OpenBSD**, there's a `beets port `_ 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 `_ 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. + import: + copy: yes # Copy files to new location -.. _alpine package: https://pkgs.alpinelinux.org/package/edge/community/x86_64/beets -.. _arch extra: https://archlinux.org/packages/extra/any/beets/ + .. tab-item:: Move Files -.. _aur: https://aur.archlinux.org/packages/beets-git/ + Start with a new empty directory, but *move* new music in instead of copying it (saving disk space). -.. _debian details: https://tracker.debian.org/pkg/beets + .. code-block:: yaml -.. _dnf package: https://packages.fedoraproject.org/pkgs/beets/ + import: + move: yes # Move files to new location -.. _freebsd: http://portsmon.freebsd.org/portoverview.py?category=audio&portname=beets + .. tab-item:: Use Existing Structure -.. _nixos: https://github.com/NixOS/nixpkgs/tree/master/pkgs/tools/audio/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. -.. _openbsd: http://openports.se/audio/beets + .. code-block:: yaml -.. _ubuntu details: https://launchpad.net/ubuntu/+source/beets + import: + copy: no # Use files in place -.. _void package: https://github.com/void-linux/void-packages/tree/master/srcpkgs/beets + .. tab-item:: Read-Only Mode -Installing by Hand on macOS 10.11 and Higher -++++++++++++++++++++++++++++++++++++++++++++ + 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.) -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.) + .. code-block:: yaml -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. + 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. -Installing on Windows -+++++++++++++++++++++ + We recommend adding at least one :ref:`Autotagger Plugin + ` to help with fetching metadata during import. + For getting started, :doc:`MusicBrainz ` is a good + choice. -Installing beets on Windows can be tricky. Following these steps might help you -get it right: + .. code-block:: yaml -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. + plugins: + - musicbrainz # Example plugin for fetching metadata + - ... other plugins you want ... -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 ` 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: - -:: - - 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 other configuration options you can set here, including the directory -and file naming scheme. See :doc:`/reference/config` for a full reference. + You can find a list of available plugins in the :doc:`plugins index + `. .. _yaml: https://yaml.org/ -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. +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. -Importing Your Library ----------------------- +.. dropdown:: Full configuration file -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. + Here's a sample configuration file that includes the settings mentioned above: -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 :doc:`tagger`. + .. code-block:: yaml -If you've got time and want to tag all your music right once and for all, do -this: + directory: ~/music + library: ~/data/musiclibrary.db -:: + import: + move: yes # Move files to new location + # copy: no # Use files in place + # write: no # Don't modify tags - $ beet import /path/to/my/music + plugins: + - musicbrainz # Example plugin for fetching metadata + # - ... other plugins you want ... -(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: + You can copy and paste this into your config file and modify it as needed. -:: +.. admonition:: Ready for more? - $ beet import -A /my/huge/mp3/library + For a complete reference of all configuration options, see the + :doc:`configuration reference `. -Note that you just need to add ``-A`` for "don't autotag". +Importing Your Music +-------------------- -Adding More Music ------------------ +Now you're ready to import your music into beets! -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: +.. important:: -:: + Importing can modify and move your music files. **Make sure you have a + recent backup** before proceeding. - $ beet import ~/some_great_album +Choose Your Import Method +~~~~~~~~~~~~~~~~~~~~~~~~~ -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. +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. + + 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`. + + + .. tab-item:: Quick Import + + 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. + + To use this method, run: + + .. code-block:: console + + beet import -A /my/huge/mp3/library + + The ``-A`` flag skips autotagging and uses your files' current metadata. + +.. admonition:: More Import Options + + 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 `. + +Adding More Music Later +~~~~~~~~~~~~~~~~~~~~~~~ + +When you acquire new music, use the same ``beet import`` command to add it to +your library: + +.. 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 `, -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 ` 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 ` +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 -` 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 `. + 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 `. 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 `_. +.. 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 + `_. diff --git a/poetry.lock b/poetry.lock index 8c109f930..0be47723f 100644 --- a/poetry.lock +++ b/poetry.lock @@ -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" diff --git a/pyproject.toml b/pyproject.toml index 62b5ac25a..1babdadd3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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"] From 3a6769d3b9a51ef0b1241b1d54520c3015b237d1 Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Wed, 1 Oct 2025 14:48:31 +0200 Subject: [PATCH 10/13] Set sphinx dependencies as optional --- poetry.lock | 8 ++++---- pyproject.toml | 7 ++----- 2 files changed, 6 insertions(+), 9 deletions(-) diff --git a/poetry.lock b/poetry.lock index 0be47723f..6f0523a42 100644 --- a/poetry.lock +++ b/poetry.lock @@ -3220,7 +3220,7 @@ test = ["cython (>=3.0)", "defusedxml (>=0.7.1)", "pytest (>=8.0)", "setuptools name = "sphinx-copybutton" version = "0.5.2" description = "Add a copy button to each of your code cells." -optional = false +optional = true python-versions = ">=3.7" files = [ {file = "sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd"}, @@ -3238,7 +3238,7 @@ rtd = ["ipython", "myst-nb", "sphinx", "sphinx-book-theme", "sphinx-examples"] name = "sphinx-design" version = "0.6.1" description = "A sphinx extension for designing beautiful, view size responsive web components." -optional = false +optional = true python-versions = ">=3.9" files = [ {file = "sphinx_design-0.6.1-py3-none-any.whl", hash = "sha256:b11f37db1a802a183d61b159d9a202314d4d2fe29c163437001324fe2f19549c"}, @@ -3650,7 +3650,7 @@ beatport = ["requests-oauthlib"] bpd = ["PyGObject"] chroma = ["pyacoustid"] discogs = ["python3-discogs-client"] -docs = ["pydata-sphinx-theme", "sphinx"] +docs = ["pydata-sphinx-theme", "sphinx", "sphinx-copybutton", "sphinx-design"] embedart = ["Pillow"] embyupdate = ["requests"] fetchart = ["Pillow", "beautifulsoup4", "langdetect", "requests"] @@ -3672,4 +3672,4 @@ web = ["flask", "flask-cors"] [metadata] lock-version = "2.0" python-versions = ">=3.9,<4" -content-hash = "caa669bfb1ff913d528553de4bc4f420279e6bc9b119d39c4db616041576266d" +content-hash = "1db39186aca430ef6f1fd9e51b9dcc3ed91880a458bc21b22d950ed8589fdf5a" diff --git a/pyproject.toml b/pyproject.toml index 1babdadd3..3a355418c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -79,6 +79,8 @@ soco = { version = "*", optional = true } pydata-sphinx-theme = { version = "*", optional = true } sphinx = { version = "*", optional = true } +sphinx-design = { version = "^0.6.1", optional = true } +sphinx-copybutton = { version = "^0.5.2", optional = true } [tool.poetry.group.test.dependencies] beautifulsoup4 = "*" @@ -119,11 +121,6 @@ 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 From 32fdad1411a671076385ebf9bd484c3cedc722b5 Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Sat, 11 Oct 2025 13:55:29 +0200 Subject: [PATCH 11/13] Enhanced changelog entry. --- docs/changelog.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index fd72f4f7a..4f32093fe 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -15,8 +15,11 @@ For packagers: Other changes: -- Removed old mailing list contact info in docs :bug:`5462` -- :doc:`guides/main`: Modernized getting started guide using tabs and dropdown menue. Installtion instructions are now more condensed and there is a subpage for additional instructions. +- Removed outdated mailing list contact information from the documentation + (:bug:`5462`). +- :doc:`guides/main`: Modernized the *Getting Started* guide with tabbed + sections and dropdown menus. Installation instructions have been streamlined, + and a new subpage now provides additional setup details. 2.5.0 (October 11, 2025) ------------------------ From dd9917d3f36935631d305cc1022d6d94efafb64b Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Sat, 11 Oct 2025 14:27:44 +0200 Subject: [PATCH 12/13] Removed yaml hyperlink. Changed dropdown naming. Use full console param instead of short form. --- docs/guides/main.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/guides/main.rst b/docs/guides/main.rst index 2b8947edb..b2d1aa00d 100644 --- a/docs/guides/main.rst +++ b/docs/guides/main.rst @@ -31,8 +31,8 @@ command: 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. +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. @@ -121,7 +121,7 @@ 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. -.. dropdown:: Full configuration file +.. dropdown:: Minimal configuration Here's a sample configuration file that includes the settings mentioned above: @@ -189,9 +189,9 @@ There are two good ways to bring your *existing* library into beets database. .. code-block:: console - beet import -A /my/huge/mp3/library + beet import --noautotag /my/huge/mp3/library - The ``-A`` flag skips autotagging and uses your files' current metadata. + The ``--noautotag`` / ``-A`` flag skips autotagging and uses your files' current metadata. .. admonition:: More Import Options From dcec32794227bbd5a613660f579a391af13ad591 Mon Sep 17 00:00:00 2001 From: Sebastian Mohr Date: Sat, 11 Oct 2025 14:32:35 +0200 Subject: [PATCH 13/13] Developer Resources card now links to doc page. --- docs/guides/main.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/main.rst b/docs/guides/main.rst index b2d1aa00d..48b248927 100644 --- a/docs/guides/main.rst +++ b/docs/guides/main.rst @@ -405,8 +405,8 @@ We'd love to hear about your experience with beets! - Get help from other users .. grid-item-card:: :octicon:`git-pull-request` Developer Resources - :link: https://github.com/beetbox/beets - :link-type: url + :link: /dev/index + :link-type: doc - Contribute code - Report issues