From 737eabdb8cbc499f9549e9df30076b7962c7bbd1 Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Fri, 16 Sep 2011 17:08:10 -0700 Subject: [PATCH] translate reference pages from wiki --- docs/reference/cli.rst | 182 +++++++++++++++++++++++++++++++++- docs/reference/config.rst | 132 +++++++++++++++++++++++- docs/reference/index.rst | 4 + docs/reference/pathformat.rst | 83 ++++++++++++++++ docs/reference/query.rst | 115 +++++++++++++++++++++ 5 files changed, 514 insertions(+), 2 deletions(-) create mode 100644 docs/reference/pathformat.rst create mode 100644 docs/reference/query.rst diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst index 6770e4429..84fe6c71f 100644 --- a/docs/reference/cli.rst +++ b/docs/reference/cli.rst @@ -1,4 +1,184 @@ Command-Line Interface ====================== -cli +**beet** is the command-line interface to beets. + +TODO: global flags + +import +------ +:: + + beet import [-CWAPRqst] [-l LOGPATH] DIR... + beet import [options] -L QUERY + +Add music to your library, attempting to get correct tags for it from +MusicBrainz. + +Point the command at a directory full of music. The directory can be a single +album or a directory whose leaf subdirectories are albums (the latter case is +true of typical Artist/Album organizations and many people's "downloads" +folders). The music will be copied to a configurable directory structure (see +below) and added to a library database (see below). The command is interactive +and will try to get you to verify MusicBrainz tags that it thinks are suspect. +(This means that importing a large amount of music is therefore very tedious +right now; this is something we need to work on. Read the +:doc:`autotagging guide ` if you need help.) + +* By default, the command copies files your the library directory and + updates the ID3 tags on your music. If you'd like to leave your music + files untouched, try the ``-C`` (don't copy) and ``-W`` (don't write tags) + options. You can also disable this behavior by default in the + configuration file (below). + +* Also, you can disable the autotagging behavior entirely using ``-A`` + (don't autotag) -- then your music will be imported with its existing + metadata. + +* During a long tagging import, it can be useful to keep track of albums + that weren't tagged successfully -- either because they're not in the + MusicBrainz database or because something's wrong with the files. Use the + ``-l`` option to specify a filename to log every time you skip and album + or import it "as-is" or an album gets skipped as a duplicate. + +* Relatedly, the ``-q`` (quiet) option can help with large imports by + autotagging without ever bothering to ask for user input. Whenever the + normal autotagger mode would ask for confirmation, the quiet mode + pessimistically skips the album. The quiet mode also disables the tagger's + ability to resume interrupted imports. + +* Speaking of resuming interrupted imports, the tagger will prompt you if it + seems like the last import of the directory was interrupted (by you or by + a crash). If you want to skip this prompt, you can say "yes" automatically + by providing ``-p`` or "no" using ``-P``. The resuming feature can be + disabled by default using a configuration option (see below). + +* If you want to import only the *new* stuff from a directory, use the + ``-i`` + option to run an *incremental* import. With this flag, beets will keep + track of every directory it ever imports and avoid importing them again. + This is useful if you have an "incoming" directory that you periodically + add things to. + +* By default, beets will proceed without asking if it finds a very close + metadata match. To disable this and have the importer as you every time, + use the ``-t`` (for *timid*) option. + +* The importer automatically tries to download album art for each album it + finds. To disable or enable this, use the ``-r`` or ``-R`` options. + +* The importer typically works in a whole-album-at-a-time mode. If you + instead want to import individual, non-album tracks, use the *singleton* + mode by supplying the ``-s`` option. + +Reimporting +^^^^^^^^^^^ + +The ``import`` command can also be used to "reimport" music that you've already +added to your library. This is useful for updating tags as they are fixed in the +!MusicBrainz database, for when you change your mind about some selections you +made during the initial import, or if you prefer to import everything "as-is" +and then correct tags later. + +Just point the ``beet import`` command at a directory of files that are already +catalogged in your library. Beets will automatically detect this situation and +avoid duplicating any items. In this situation, the "copy files" option +(``-c``/``-C`` on the command line or ``import_copy`` in the config file) has +slightly different behavior: it causes files to be *moved*, rather than +duplicated, if they're already in your library. That is, your directory +structure will be updated to reflect the new tags if copying is enabled; you +never end up with two copies of the file. That means that the "delete files" +(``-d`` or ``import_delete``) option is ignored when re-importing as well. + +The ``-L`` (``--library``) flag is also useful for retagging. Instead of listing +paths you want to import on the command line, specify a :doc:`query string +` that matches items from your library. In this case, the ``-s`` +(singleton) flag controls whether the query matches individual items or full +albums. If you want to retag your whole library, just supply a null query, which +matches everything: ``beet import -L`` + +list +---- +:: + + beet list [-ap] QUERY + +:doc:`Queries ` the database for music. + +Want to search for "Gronlandic Edit" by of Montreal? Try ``beet list +gronlandic``. Maybe you want to see everything released in 2009 with +"vegetables" in the title? Try ``beet list year:2009 title:vegetables``. (Read +more in :doc:`query`.) You can use the ``-a`` switch to search for +albums instead of individual items. The ``-p`` option makes beets print out +filenames of matched items, which might be useful for piping into other Unix +commands (such as `xargs`_). + +.. _xargs: http://en.wikipedia.org/wiki/Xargs + +remove +------ +:: + + beet remove [-ad] QUERY + +Remove music from your library. + +This command uses the same :doc:`query ` syntax as the ``list`` command. +You'll be shown a list of the files that will be removed and asked to confirm. +By default, this just removes entries from the library database; it doesn't +touch the files on disk. To actually delete the files, use ``beet remove -d``. + +modify +------ +:: + + beet modify [-MWay] QUERY FIELD=VALUE... + +Change the metadata for items or albums in the database. + +Supply a :doc:`query ` matching the things you want to change and a +series of ``field=value`` pairs. For example, ``beet modify genius of love +artist="Tom Tom Club"`` will change the artist for the track "Genius of Love." +The ``-a`` switch operates on albums instead of individual tracks. Items will +automatically be moved around when necessary if they're in your library +directory, but you can disable that with ``-M``. Tags will be written to the +files according to the settings you have for imports, but these can be +overridden with ``-w`` (write tags, the default) and ``-W`` (don't write tags). +Finally, this command politely asks for your permission before making any +changes, but you can skip that prompt with the ``-y`` switch. + +move +---- +:: + + beet move [-ca] [-d DIR] QUERY + +Move or copy items in your library. + +This command, by default, acts as a library consolidator: items matching the +query are renamed into your library directory structure. By specifying a +destination directory with ``-d`` manually, you can move items matching a query +anywhere in your filesystem. The ``-c`` option copies files instead of moving +them. As with other commands, the ``-a`` option matches albums instead of items. + +update +------ +:: + + beet update [-aM] QUERY + +Update the library (and, optionally, move files) to reflect out-of-band metadata +changes and file deletions. + +This will scan all the matched files and read their tags, populating the +database with the new values. By default, files will be renamed according to +their new metadata; disable this with ``-M``. + +stats +----- +:: + + beet stats [QUERY] + +Show some statistics on your entire library (if you don't provide a +:doc:`query ` or the matched items (if you do). diff --git a/docs/reference/config.rst b/docs/reference/config.rst index fb0e365c9..736869d78 100644 --- a/docs/reference/config.rst +++ b/docs/reference/config.rst @@ -1,4 +1,134 @@ .beetsconfig ============ -Config +The ``beet`` command reads configuration information from ``~/.beetsconfig``. +The file is in INI format, and the following options are available, all of which +must appear under the ``[beets]`` section header: + +* ``library``: path to the beets library file. Defaults to + ``~/.beetsmusic.blb``. + +* ``directory``: the directory to which files will be copied/moved when adding + them to the library. Defaults to ``~/Music``. + +* ``import_copy``: either ``yes`` or ``no``, indicating whether to copy files + into the library directory when using ``beet import``. Defaults to ``yes``. + Can be overridden with the ``-c`` and ``-C`` command-line options. + +* ``import_write``: either ``yes`` or ``no``, controlling whether metadata + (e.g., ID3) tags are written to files when using ``beet import``. Defaults to + ``yes``. The ``-w`` and ``-W`` command-line options override this setting. + +* ``import_delete``: either ``yes`` or ``no``. When enabled in conjunction with + ``import_copy``, deletes original files after they are copied into your + library. This might be useful, for example, if you're low on disk space -- but + it's risky! Defaults to ``no``. + +* ``import_resume``: either ``yes``, ``no``, or ``ask``. Controls whether + interrupted imports should be resumed. "Yes" means that imports are always + resumed when possible; "no" means resuming is disabled entirely; "ask" (the + default) means that the user should be prompted when resuming is possible. The + ``-p`` and ``-P`` flags correspond to the "yes" and "no" settings and override + this option. + +* ``import_incremental``: either ``yes`` or ``no``, controlling whether imported + directories are recorded and whether these recorded directories are skipped. + This corresponds to the ``-i`` flag to ``beet import``. + +* ``import_art``: either ``yes`` or ``no``, indicating whether the autotagger + should attempt to find and download album cover art for the files it imports. + Defaults to ``yes``. The ``-r`` and ``-R`` command-line options override this + setting. + +* ``import_quiet_fallback``: either ``skip`` (default) or ``asis``, specifying + what should happen in quiet mode (see the ``-q`` flag to ``import``, above) + when there is no strong recommendation. + +* ``import_timid``: either ``yes`` or ``no``, controlling whether the importer + runs in *timid* mode, in which it asks for confirmation on every autotagging + match, even the ones that seem very close. Defaults to ``no``. The ``-t`` + command-line flag controls the same setting. + +* ``import_log``: specifies a filename where the importer's log should be kept. + By default, no log is written. This can be overridden with the ``-l`` flag to + ``import``. + +* ``art_filename``: when importing album art, the name of the file (without + extension) where the cover art image should be placed. Defaults to ``cover`` + (i.e., images will be named ``cover.jpg`` or ``cover.png`` and placed in the + album's directory). + +* ``plugins``: a space-separated list of plugin module names to load. For + instance, beets includes the [BPD BPD] plugin for playing music. + +* ``pluginpath``: a colon-separated list of directories to search for plugins. + These paths are just added to ``sys.path`` before the plugins are loaded. The + plugins still have to be contained in a ``beetsplug`` namespace package. + +* ``threaded``: either ``yes`` or ``no``, indicating whether the autotagger + should use multiple threads. This makes things faster but may behave + strangely. Defaults to ``yes``. + +* ``color``: either ``yes`` or ``no``; whether to use color in console output + (currently only in the ``import`` command). Turn this off if your terminal + doesn't support ANSI colors. + +You can also configure the directory hierarchy beets uses to store music. That +uses the ``[paths]`` section instead of the ``[beets]`` section. Each string is +a `Python template string`_ that can refer to metadata fields (see below for +examples). The extension is added automatically to the end. At the moment, you +can specify two special paths: ``default`` (for most releases) and ``comp`` (for +"various artist" releases with no dominant artist). You can also specify a +different path format for each `MusicBrainz release type`_. The defaults look +like this:: + + [paths] + default: $albumartist/$album/$track $title + comp: Compilations/$album/$track title + singleton: Non-Album/$artist/$title + +Note the use of ``$albumartist`` instead of ``$artist``; this ensure that albums +will be well-organized. (For more about these format strings, see +:doc:`pathformat`.) + +.. _Python template string: + http://docs.python.org/library/string.html#template-strings +.. _MusicBrainz release type: + http://wiki.musicbrainz.org/ReleaseType + +Here's an example file:: + + [beets] + library: /var/music.blb + directory: /var/mp3 + path_format: $genre/$artist/$album/$track $title + import_copy: yes + import_write: yes + import_resume: ask + import_art: yes + import_quiet_fallback: skip + import_timid: no + import_log: beetslog.txt + art_filename: albumart + plugins: bpd + pluginpath: ~/beets/myplugins + threaded: yes + color: yes + + [paths] + default: $genre/$albumartist/$album/$track $title + soundtrack: Soundtracks/$album/$track $title + comp: $genre/$album/$track $title + singleton: Singletons/$artist - $track + + [bpd] + host: 127.0.0.1 + port: 6600 + password: seekrit + +(That ``[bpd]`` section configures the optional :doc:`BPD ` +plugin.) + +If you want to store your ``.beetsconfig`` file somewhere else for whatever +reason, you can specify its path by setting the ``BEETSCONFIG`` environment +variable. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index e6e4b2c0a..216f70c51 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,8 +1,12 @@ Reference ========= +This section contains reference materials for various parts of beets. + .. toctree:: :maxdepth: 2 cli config + pathformat + query diff --git a/docs/reference/pathformat.rst b/docs/reference/pathformat.rst new file mode 100644 index 000000000..7e2e344a0 --- /dev/null +++ b/docs/reference/pathformat.rst @@ -0,0 +1,83 @@ +Path Formats +============ + +The ``[paths]`` section of the config file (read more on the [Usage] page) lets +you specify the directory and file naming scheme for your music library. You +specify templates using Python template string notation---that is, prefixing +names with ``$`` characters---and beets fills in the appropriate values. + +For example, consider this path format string: ``$albumartist/$album/$track +$title`` + +Here are some paths this format will generate: + +* ``Yeah Yeah Yeahs/It's Blitz!/01 Zero.mp3`` + +* ``Spank Rock/YoYoYoYoYo/11 Competition.mp3`` + +* ``The Magnetic Fields/Realism/01 You Must Be Out of Your Mind.mp3`` + +Note that in path formats, you almost certainly want to use ``$albumartist`` and +not ``$artist``. The latter refers to the "track artist" when it is present, +which means that albums that have tracks from different artists on them (like +`Stop Making Sense`_, for example) will be placed into different folders! +Continuing with the Stop Making Sense example, you'll end up with most of the +tracks in a "Talking Heads" directory and one in a "Tom Tom Club" directory. You +probably don't want that! So use ``$albumartist``. + +.. _Stop Making Sense: + http://musicbrainz.org/release/798dcaab-0f1a-4f02-a9cb-61d5b0ddfd36.html + +As a convenience, however, beets allows ``$albumartist`` to fall back to the value for ``$artist`` and vice-versa if one tag is present but the other is not. + +Upgrading from 1.0b6 +-------------------- + +Versions of beets prior to 1.0b7 didn't use a ``[paths]`` section. Instead, they +used a single ``path_format`` setting for all music. To support old +configuration files, this setting is still respected and overrides the default +path formats. However, the setting is deprecated and, if you want to use +flexible path formats, you need to remove the ``path_format`` setting and use a +``[paths]`` section instead. + +Possible Values +--------------- + +Here's a (comprehensive?) list of the different values available to path +formats. (I will try to keep it up to date, but I might forget. The current list +can be found definitively `in the source`_.) + +.. _in the source: + http://code.google.com/p/beets/source/browse/beets/library.py#36 + +Ordinary metadata: + +* title +* artist +* album +* genre +* composer +* grouping +* year +* month +* day +* track +* tracktotal +* disc +* disctotal +* lyrics +* comments +* bpm +* comp + +Audio information: + +* length +* bitrate +* format + +MusicBrainz IDs: + +* mb_trackid +* mb_albumid +* mb_artistid diff --git a/docs/reference/query.rst b/docs/reference/query.rst new file mode 100644 index 000000000..67af2ab50 --- /dev/null +++ b/docs/reference/query.rst @@ -0,0 +1,115 @@ +Queries +======= + +Many of beets' :doc:`commands ` are built around **query strings:** +searches that select tracks and albums from your library. This page explains the +query string syntax, which is meant to vaguely resemble the syntax used by Web +search engines. + +Keyword +------- + +This command:: + + $ beet list love + +will show all tracks matching the query string ``love``. Any unadorned word like this matches *anywhere* in a track's metadata, so you'll see all the tracks with "love" in their title, in their album name, in the artist, and so on. + +For example, this is what I might see when I run the command above:: + + Against Me! - Reinventing Axl Rose - I Still Love You Julie + Air - Love 2 - Do the Joy + Bag Raiders - Turbo Love - Shooting Stars + Bat for Lashes - Two Suns - Good Love + ... + +Combining Keywords +------------------ + +Multiple keywords are implicitly joined with a Boolean "and." That is, if a +query has two keywords, it only matches tracks that contain *both* keywords. For +example, this command:: + + $ beet ls magnetic tomorrow + +matches songs from the album "The House of Tomorrow" by The Magnetic Fields in +my library. It *doesn't* match other songs by the Magnetic Fields, nor does it +match "Tomorrowland" by Walter Meego---those songs only have *one* of the two +keywords I specified. + +Specific Fields +--------------- + +Sometimes, a broad keyword match isn't enough. Beets supports a syntax that lets +you query a specific field---only the artist, only the track title, and so on. +Just say ``field:value``, where ``field`` is the name of the thing you're trying +to match (such as ``artist``, ``album``, or ``title``) and ``value`` is the +keyword you're searching for. + +For example, while this query:: + + $ beet list dream + +matches a lot of songs in my library, this more-specific query:: + + $ beet list artist:dream + +only matches songs by the artist The-Dream. One query I especially appreciate is +one that matches albums by year:: + + $ beet list -a year:2011 + +Recall that ``-a`` makes the ``list`` command show albums instead of individual +tracks, so this command shows me all the releases I have from this year. + +Phrases +------- + +As of beets 1.0b9, you can query for strings with spaces in them by quoting or escaping them using your shell's argument syntax. For example, this command:: + + $ beet list the rebel + +shows several tracks in my library, but these (equivalent) commands:: + + $ beet list "the rebel" + $ beet list the\ rebel + +only match the track "The Rebel" by Buck 65. Note that the quotes and +backslashes are not part of beets' syntax; I'm just using the escaping +functionality of by shell (bash or zsh, for instance) to pass ``the rebel`` as a +single argument instead of two. + +Path Queries +------------ + +Sometimes it's useful to find all the items in your library that are +(recursively) inside a certain directory. With beets 1.0b9, use the ``path:`` +field to do this:: + + $ beet list path:/my/music/directory + +In fact, beets automatically recognizes any query term containing a path +separator (``/`` on POSIX systems) as a path query, so this command is +equivalent:: + + $ beet list /my/music/directory + +Note that this only matches items that are *already in your library*, so a path +query won't necessarily find *all* the audio files in a directory---just the +ones you've already added to your beets library. + +Future Work +----------- + +Here are a few things that the query syntax should eventually support but aren't +yet implemented. Please drop me a line if you have other ideas. + +* "Null" queries. It's currently impossible to query for items that have an + empty artist. Perhaps the syntax should look like ``artist:NULL`` or + ``artist:EMPTY``. + +* Regular expressions. Beets queries are based on simple case-insensitive + substring matching, but regexes might be useful occasionally as well. Maybe + the syntax should look something like ``re:artist:^.*$`` or, perhaps, + ``artist:/^.*$/``. Having regular expressions could help with null queries + (above): ``re:artist:^$``.