beets/docs/guides/main.rst

Getting Started
===============

Welcome to `beets`_! This guide will help you begin using it to make your music
collection better.

.. _beets: http://beets.radbox.org/

Installing
----------

You will need Python. (Beets is written for `Python 2.7`_, but it works with
2.6 as well. Python 3.x is not yet supported.)

.. _Python 2.7: http://www.python.org/download/releases/2.7.2/

* **Mac OS X** v10.7 (Lion) and 10.8 (Mountain Lion) include Python 2.7 out of
  the box; Snow Leopard ships with Python 2.6.

* 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``. To build from source, you can get everything you
  need by running: ``apt-get install python-dev python-setuptools python-pip``

* For **Arch Linux**, try getting `beets from AUR`_. (There's also a
  bleeding-edge `dev package`_, which will probably set your computer on fire.)

* For **Gentoo Linux**, beets is in Portage as ``media-sound/beets``. Just run
  ``emerge beets`` to install. There are several USE flags available for
  optional plugin dependencies.

* On **FreeBSD**, there's a `beets port`_ at ``audio/beets``.

.. _beets port: http://portsmon.freebsd.org/portoverview.py?category=audio&portname=beets
.. _beets from AUR: http://aur.archlinux.org/packages.php?ID=39577
.. _dev package: http://aur.archlinux.org/packages.php?ID=48617
.. _Debian details: http://packages.qa.debian.org/b/beets.html
.. _Ubuntu details: https://launchpad.net/ubuntu/+source/beets

If you have `pip`_, just say ``pip install beets`` (you might need ``sudo`` in
front of that). On Arch, you'll need to use ``pip2`` instead of ``pip``.

To install without pip, download beets from `its PyPI page`_ and run ``python
setup.py install`` in the directory therein.

.. _its PyPI page: http://pypi.python.org/pypi/beets#downloads
.. _pip: http://pip.openplans.org/

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: http://twitter.com/b33ts

Installing on Windows
^^^^^^^^^^^^^^^^^^^^^

Installing beets on Windows can be tricky. Following these steps might help you
get it right:

1. If you don't have it, `install Python`_ (you want Python 2.7).

2. Install `Setuptools`_ from PyPI. To do this, scroll to the bottom of that
   page and download the Windows installer (``.exe``, not ``.egg``) for your
   Python version (for example: ``setuptools-0.6c11.win32-py2.7.exe``).

3. If you haven't done so already, set your ``PATH`` environment variable to
   include Python and its scripts. To do so, you have to get the "Properties"
   window for "My Computer", then choose the "Advanced" tab, then hit the
   "Environment Variables" button, and then look for the ``PATH`` variable in
   the table. Add the following to the end of the variable's value:
   ``;C:\Python27;C:\Python27\Scripts``.

4. Open a command prompt and install pip by running: ``easy_install pip``

5. Now install beets by running: ``pip install beets``

6. 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. Just download and open `beets.reg`_ to add the necessary keys to the
registry. You can then right-click a directory and choose "Import with beets".
If Python is in a nonstandard location on your system, you may have to edit the
command path manually.

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 `let me know`_.

.. _let me know: mailto:adrian@radbox.org
.. _install Python: http://python.org/download/
.. _Setuptools: http://pypi.python.org/pypi/setuptools
.. _beets.reg: https://github.com/sampsyo/beets/blob/master/extra/beets.reg


Configuring
-----------

You'll want to set a few basic options before you start using beets. The
configuration is stored in a text file: on Unix-like OSes, the config file is
at ``~/.config/beets/config.yaml``; on Windows, it's at
``%APPDATA%\beets\config.yaml``. Create and edit the appropriate file with your
favorite text editor. (You may need to create the enclosing directories also.)
The file will start out empty, but here's good place to start::

    directory: ~/music
    library: ~/data/musiclibrary.blb

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 default configuration assumes you want to start a new organized music folder
(that ``directory`` above) and that you'll *copy* cleaned-up music into that
empty folder using beets' ``import`` command (see below). But you can configure
beets to behave many other ways:

* Start with a new empty directory, but *move* new music in instead of copying
  it (saving disk space). Put this in your config file::

        import:
            move: yes

* Keep your current directory structure; importing should never move or copy
  files but instead just correct the tags on music. Put the line ``copy: no``
  under the ``import:`` heading in your config file to disable any copying or
  renaming. Make sure to point ``directory`` at the place where your music is
  currently stored.

* Keep your current directory structure and *do not* correct files' tags: leave
  files completely unmodified on your disk. (Corrected tags will still be stored
  in beets' database, and you can use them to do renaming or tag changes later.)
  Put this in your config file::

        import:
            copy: no
            write: no

  to disable renaming and tag-writing.

There are approximately six million other configuration options you can set
here, including the directory and file naming scheme. See
:doc:`/reference/config` for a full reference.

Importing Your Library
----------------------

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. (I'm working on improving the
autotagger's performance and automation.) For more information 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::

    $ beet import /path/to/my/music

(Note that by default, this command will *copy music into the directory you
specified above*. If you want to use your current directory structure, set the
``import.copy`` config option.) To take the fast,
un-autotagged path, just say::

    $ beet import -A /my/huge/mp3/library

Note that you just need to add ``-A`` for "don't autotag".

Adding More Music
-----------------

If you've ripped or... otherwise obtained some new music, you can add it with
the ``beet import`` command, the same way you imported your library. Like so::

    $ beet import ~/some_great_album

This will attempt to autotag the new album (interactively) and add it to your
library. There are, of course, more options for this command---just type ``beet
help import`` to see what's available.

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::

    $ beet ls the magnetic fields
    The Magnetic Fields - Distortion - Three-Way
    The Magnetic Fields - Distortion - California Girls
    The Magnetic Fields - Distortion - Old Fools
    $ beet ls hissing gronlandic
    of Montreal - Hissing Fauna, Are You the Destroyer? - Gronlandic Edit
    $ beet ls bird
    The Knife - The Knife - Bird
    The Mae Shi - Terrorbird - Revelation Six
    $ beet ls album:bird
    The Mae Shi - Terrorbird - Revelation Six

As you can see, search terms by default search all 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.)

The ``beet list`` command has another useful option worth mentioning, ``-a``,
which searches for albums instead of songs::

    $ beet ls -a forever
    Bon Iver - For Emma, Forever Ago
    Freezepop - Freezepop Forever

So handy!

Beets also has a ``stats`` command, just in case you want to see how much music
you have::

    $ beet stats
    Tracks: 13019
    Total time: 4.9 weeks
    Total size: 71.1 GB
    Artists: 548
    Albums: 1094

Playing Music
-------------

Beets is primarily intended as a music organizer, not a player. It's designed to
be used in conjunction with other players (consider `Decibel`_ or `cmus`_;
there's even :ref:`a cmus plugin for beets <other-plugins>`). However, it does
include a simple music player---it doesn't have a ton of features, but it gets
the job done.

.. _Decibel: http://decibel.silent-blade.org/
.. _cmus: http://cmus.sourceforge.net/

The player, called BPD, is a clone of an excellent music player called `MPD`_.
Like MPD, it runs as a daemon (i.e., without a user interface). Another program,
called an MPD client, controls the player and provides the user with an
interface. You'll need to enable the BPD plugin before you can use it. Check out
:doc:`/plugins/bpd`.

.. _MPD: http://mpd.wikia.com/

You can, of course, use the bona fide MPD server with your beets library. MPD is
a great player and has more features than BPD. BPD just provides a convenient,
built-in player that integrates tightly with your beets database.

Keep Playing
------------

The :doc:`/reference/cli` page has more detailed description of all of beets'
functionality.  (Like deleting music! That's important.) Start exploring!

Also, check out :ref:`included-plugins` as well as :ref:`other-plugins`.  The
real power of beets is in its extensibility---with plugins, beets can do almost
anything for your music collection.

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.

Please let me know what you think of beets via `email`_ or `Twitter`_.

.. _email: mailto:adrian@radbox.org
.. _twitter: http://twitter.com/b33ts