From ec6bbf53d4b34ee906ebf901cd62818d2c23f54d Mon Sep 17 00:00:00 2001
From: Jakob Schnitzer <mail@jakobschnitzer.de>
Date: Mon, 8 Oct 2012 12:25:56 +0200
Subject: [PATCH] convert: Add docs

---
 docs/plugins/convert.rst | 54 ++++++++++++++++++++++++++++++++++++++++
 docs/plugins/index.rst   |  2 ++
 2 files changed, 56 insertions(+)
 create mode 100644 docs/plugins/convert.rst

diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst
new file mode 100644
index 000000000..4ec52b152
--- /dev/null
+++ b/docs/plugins/convert.rst
@@ -0,0 +1,54 @@
+Convert Plugin
+==============
+
+The ``convert`` plugin lets you convert parts of your collection to a directory
+of your choice. Currently only converting from MP3 or FLAC to MP3 is supported.
+It will skip files that are already present in the target directory. It uses
+the same directory structure as your library.
+
+Installation
+------------
+
+This plugin requires ``flac`` and ``lame``. If thoses executables are in your
+path, they will be found automatically by the plugin, otherwise you have to set
+their respective config options. Of course you will have to enable the plugin
+as well (see :doc:`/plugins/index`)::
+
+    [convert]
+    flac:/usr/bin/flac
+    lame:/usr/bin/lame
+
+Usage
+-----
+
+To convert a part of your collection simply run ``beet convert QUERY``. This
+will display all items matching ``QUERY`` and ask you for confirmation before
+starting the conversion. The ``-a`` (or ``--album``) option causes the command
+to match albums instead of tracks.
+
+The ``-t`` (``--threads``) and ``-d`` (``--dest``) options allow you to specify
+or overwrite the respective configuration options.
+
+Configuration
+-------------
+
+This plugin offers a couple of configuration options: If you want to disable
+that album art is embedded in your converted items (enabled by default), you
+will have to set the ``embed`` option to false. If you set ``max_bitrate``, all
+MP3 files with a higher bitrate will be converted and thoses with a lower
+bitrate will simply be copied. Be aware that this doesn't mean that your
+converted files will have a lower bitrate since that depends on the specified
+encoding options. By default only FLAC files will be converted (and all MP3s
+will be copied). ``opts`` are the encoding options that are passed to ``lame``
+(defaults to "-V2"). Please refer to the ``lame`` docs for possible options.
+
+The ``dest`` sets the directory the files will be converted (or copied) to.
+Finally ``threads`` lets you determine the number of threads to use for
+encoding (default: 2). An example configuration::
+
+    [convert]
+    embed:false
+    max_bitrate:200
+    opts:-V4
+    dest:/home/user/MusicForPhone
+    threads:4
diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst
index 757d8a3ac..6ed238f0d 100644
--- a/docs/plugins/index.rst
+++ b/docs/plugins/index.rst
@@ -53,6 +53,7 @@ disabled by default, but you can turn them on as described above.
    the
    fuzzy_search
    zero
+   convert
 
 Autotagger Extensions
 ''''''''''''''''''''''
@@ -94,6 +95,7 @@ Miscellaneous
 * :doc:`mbcollection`: Maintain your MusicBrainz collection list.
 * :doc:`bpd`: A music player for your beets library that emulates `MPD`_ and is
   compatible with `MPD clients`_.
+* :doc:`convert`: Converts parts of your collection to an external directory
 
 .. _MPD: http://mpd.wikia.com/
 .. _MPD clients: http://mpd.wikia.com/wiki/Clients