Getting Started =============== Welcome to beets_! This guide will help get started with improving and organizing your music collection. .. _beets: https://beets.io/ Quick Installation ------------------ Beets is distributed via PyPI_ and can be installed by most users with a single command: .. include:: installation.rst :start-after: :end-before: .. admonition:: Need more installation options? Having trouble with the commands above? Looking for package manager instructions? See the :doc:`complete installation guide ` 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 beet config -e 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. .. code-block:: yaml 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: .. tab-set:: .. tab-item:: Copy Files (Default) 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. .. code-block:: yaml import: copy: yes # Copy files to new location .. tab-item:: Move Files Start with a new empty directory, but *move* new music in instead of copying it (saving disk space). .. code-block:: yaml import: move: yes # Move files to new location .. tab-item:: Use Existing Structure 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. .. code-block:: yaml import: copy: no # Use files in place .. tab-item:: Read-Only Mode 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.) .. code-block:: yaml 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. 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. .. code-block:: yaml plugins: - musicbrainz # Example plugin for fetching metadata - ... other plugins you want ... You can find a list of available plugins in the :doc:`plugins index `. .. _yaml: https://yaml.org/ 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:: Minimal configuration Here's a sample configuration file that includes the settings mentioned above: .. code-block:: yaml 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 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. .. admonition:: Ready for more? For a complete reference of all configuration options, see the :doc:`configuration reference `. Importing Your Music -------------------- Now you're ready to import your music into beets! .. important:: Importing can modify and move your music files. **Make sure you have a recent backup** before proceeding. Choose Your Import Method ~~~~~~~~~~~~~~~~~~~~~~~~~ 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 --noautotag /my/huge/mp3/library The ``--noautotag`` / ``-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 ----------------- 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 - 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 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 string, field references like ``$format``, ``$year``, ``$album``, etc., are replaced with data from each result. .. 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 Total time: 4.9 weeks Total size: 71.1 GB 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 ------------ Congratulations! You've now mastered the basics of beets. But this is only the beginning, beets has many more powerful features to explore. Continue Your Learning Journey ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *I was there to push people beyond what's expected of them.* .. grid:: 2 :gutter: 3 .. grid-item-card:: :octicon:`zap` Advanced Techniques :link: advanced :link-type: doc Explore sophisticated beets workflows including: - 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: /dev/index :link-type: doc - 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 `_.