From 45baa6efe13d41035da106b9175234d848ea75dd Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Sun, 19 May 2013 17:35:23 -0700 Subject: [PATCH] first stab at "advanced guide" --- docs/guides/advanced.rst | 106 ++++++++++++++++++++++++++++++++++ docs/guides/index.rst | 1 + docs/plugins/index.rst | 2 + docs/reference/cli.rst | 2 + docs/reference/pathformat.rst | 2 + 5 files changed, 113 insertions(+) create mode 100644 docs/guides/advanced.rst diff --git a/docs/guides/advanced.rst b/docs/guides/advanced.rst new file mode 100644 index 000000000..876e3cad3 --- /dev/null +++ b/docs/guides/advanced.rst @@ -0,0 +1,106 @@ +Advanced Awesomeness +==================== + +So you have beets up and running and you've started :doc:`importing your +music `. There's a lot more that beets can do now that it has +cataloged your collection. Here's a few features to get you started. + +Most of these tips involve :doc:`plugins ` and fiddling with beets' +:doc:`configuration `. So use your favorite text editor +create a config file before you continue. + + +Fetch album art, genres, and lyrics +----------------------------------- + +Beets can help you fill in more than just the basic taxonomy metadata that +comes from MusicBrainz. Plugins can provide :doc:`album art +`, :doc:`lyrics `, and +:doc:`genres ` from databases around the Web. + +If you want beets to get any of this data automatically during the import +process, just enable any of the three relevant plugins (see +:ref:`using-plugins`). For example, put this line in your :doc:`config file +` to enable all three:: + + plugins: fetchart lyrics lastgenre + +Each plugin also has a command you can run to fetch data manually. For +example, if you want to get lyrics for all the Beatles tracks in your +collection, just type ``beet lyrics beatles`` after enabling the plugin. + +Read more about using each of these plugins: + +* :doc:`/plugins/fetchart` (and its accompanying :doc:`/plugins/embedart`) +* :doc:`/plugins/lyrics` +* :doc:`/plugins/lastgenre` + + +Customize your file and folder names +------------------------------------ + +Beets uses an extremely flexible template system to name the folders and files +that organize your music in your filesystem. Take a look at +:ref:`path-format-config` for the basics: use fields like ``$year`` and +``$title`` to build up a naming scheme. But if you need more flexibility, +there are two features you need to know about: + +* :ref:`Template functions ` are simple expressions you + can use in your path formats to add logic to your names. For example, you + can get an artist's first initial using ``%upper{%left{$albumartist,1}}``. +* If you need more flexibility, the :doc:`/plugins/inline` lets you write + snippets of Python code that generate parts of your filenames. The + equivalent code for getting an artist initial with the *inline* plugin looks + like ``initial: albumartist[0].upper()``. + +If you already have music in your library and want to update their names +according to a new scheme, just run the :ref:`move-cmd` command to rename +everything. + + +Stream your music to another computer +------------------------------------- + +Sometimes it can be really convenient to store your music on one machine and +play it on another. For example, I like to keep my music on a server at home +but play it at work (without copying my whole library locally). The +:doc:`/plugins/web` makes streaming your music easy---it's sort of like having +your own personal Spotify. + +First, enable the ``web`` plugin (see :ref:`using-plugins`). Run the server by +typing ``beet web`` and head to http://localhost:8337 in a browser. You can +browse your collection with queries and, if your browser supports it, play +music using HTML5 audio. + +But for a great listening experience, pair beets with the `Tomahawk`_ music +player. Tomahawk lets you listen to music from many different sources, +including a beets server. Just download Tomahawk and open its settings to +connect it to beets. `A post on the beets blog`_ has a more detailed guide. + +.. _A post on the beets blog: + http://beets.radbox.org/blog/tomahawk-resolver.html +.. _Tomahawk: http://www.tomahawk-player.org + + +Transcode music files for media players +--------------------------------------- + +Do you ever find yourself transcoding high-quality rips to a lower-bitrate, +lossy format for your phone or music player? Beets can help with that. + +You'll first need to install `ffmpeg`_. Then, enable beets' +:doc:`/plugins/convert`. Set a destination directory in your +:doc:`config file ` like so:: + + convert: + dest: ~/converted_music + +Then, use the command ``beet convert QUERY`` to transcode everything matching +the query and drop the resulting files in that directory, named according to +your path formats. For example, ``beet convert long winters`` will move over +everything by the Long Winters for listening on the go. + +The plugin has many more dials you can fiddle with to get your conversions how +you like them. Check out :doc:`its documentation `. + +.. _ffmpeg: http://www.ffmpeg.org diff --git a/docs/guides/index.rst b/docs/guides/index.rst index d9ec06d9b..9269b249e 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -10,4 +10,5 @@ guide. main tagger + advanced migration diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index db621f2a5..2ad472066 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -5,6 +5,8 @@ Plugins can extend beets' core functionality. Plugins can add new commands to the command-line interface, respond to events in beets, augment the autotagger, or provide new path template functions. +.. _using-plugins: + Using Plugins ------------- diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst index cedc4a233..ff8d0f8a8 100644 --- a/docs/reference/cli.rst +++ b/docs/reference/cli.rst @@ -199,6 +199,8 @@ 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-cmd: + move ```` :: diff --git a/docs/reference/pathformat.rst b/docs/reference/pathformat.rst index 53a8e1720..f037b4395 100644 --- a/docs/reference/pathformat.rst +++ b/docs/reference/pathformat.rst @@ -43,6 +43,8 @@ probably don't want that! So use ``$albumartist``. 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. +.. _template-functions: + Functions ---------