Document gapless mp3 encoding.
@@ -140,3 +140,52 @@ and the given command is used for all conversions.
convert:
command: ffmpeg -i $source -y -vn -aq 2 $dest
extension: mp3
+
+
+Gapless MP3 encoding
+````````````````````
+
+Due to limitations in the ``ffmpeg`` encoder, by default the ``convert`` plugin
+does not produce MP3s with accurate length tags (it does not write a LAME MP3
+info tag). This means that the MP3s are not "`gapless`_", and can result in
+noticeable gaps between tracks during playback.
+
+.. _gapless: http://wiki.hydrogenaud.io/index.php?title=Gapless_playback
+
+To work around this problem, you must use the `LAME`_ MP3 encoder, which will
+produce MP3s with accurate length tags.
+
+.. _LAME: http://lame.sourceforge.net/
+
+To do this on Linux, you need to install ``lame``, create a script (e.g.
+``/home/user/.config/beets/mp3.sh``) with the following contents, and make it
+executable.
+
+::
+
+ #!/bin/sh
+ /usr/bin/ffmpeg -i "$1" -f wav - | /usr/bin/lame -V 2 --noreplaygain - "$2"
+
+Then configure the ``convert`` plugin to use the script.
+
+::
+
+ convert:
+ command: /home/user/.config/beets/mp3.sh $source $dest
+ extension: mp3
+
+.. note::
+
+ In the script above, ``ffmpeg`` output format ``wav`` is used to produce an
+ accurate length header to pass to ``lame``.
+
+ ``--noreplaygain`` configures ``lame`` not to do ReplayGain analysis and
+ tagging itself, because it can only do a track level analysis. Instead, you
+ can use the beets ``replaygain`` plugin to analyse and add both Album and
+ Track ReplayGain tags.
+
+ See the ``lame`` `documentation`_ and the `HydrogenAudio wiki`_ for other
+ ``lame`` configuration options, and a thorough discussion of MP3 encoding.
+
+.. _documentation: http://lame.sourceforge.net/using.php
+.. _HydrogenAudio wiki: http://wiki.hydrogenaud.io/index.php?title=LAME
