From 8fb5ddc3b9d4ee9ac0c86e2d80241ffc08e91117 Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Mon, 7 Apr 2014 20:07:39 -0700 Subject: [PATCH] revise docs for expanded RG plugin Among other things, this clarifies which options are available with each backend. --- docs/changelog.rst | 7 ++- docs/plugins/replaygain.rst | 100 +++++++++++++++++------------------- 2 files changed, 51 insertions(+), 56 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index ea868243c..0d00e9461 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -6,10 +6,9 @@ Changelog New stuff: -* :doc:`/plugins/replaygain`: Added support for calcuating ReplayGain values with - GStreamer as well as the mp3gain/aacgain command. This enables ReplayGain - calculation for practially all formats. The upgraded plugin is backward - compatible configuration-wise. +* :doc:`/plugins/replaygain`: Added support for calculating ReplayGain values + with GStreamer as well the mp3gain programs. This enables ReplayGain + calculation for any audio format. Fixes: diff --git a/docs/plugins/replaygain.rst b/docs/plugins/replaygain.rst index b571052c7..638f80123 100644 --- a/docs/plugins/replaygain.rst +++ b/docs/plugins/replaygain.rst @@ -6,40 +6,38 @@ playback levels. .. _ReplayGain: http://wiki.hydrogenaudio.org/index.php?title=ReplayGain + Installation ------------ -This plugin can use one of two backends to compute the ReplayGain values +This plugin can use one of two backends to compute the ReplayGain values: +GStreamer and mp3gain (and its cousin, aacgain). mp3gain can be easier to +install but GStreamer support more audio formats. + +Once installed, this plugin analyzes all files during the import process. This +can be a slow process; to instead analyze after the fact, disable automatic +analysis and use the ``beet replaygain`` command (see below). GStreamer ````````` -This backend uses the popular `GStreamer`_ multimedia framework. -In order to use this backend, you will need to install the GStreamer library -as well as a set of plugins for handling your selection of audio files. -Some linux distributions don't package plugins for some popular formats in -their default repositories, and packages for those plugins need to be -downloaded from elsewhere or compiled from source. - -The minimal version of the GStreamer library supported by this backend is 1.0 -The 0.x branch (which is the default on some older distributions) is not -supported. +To use `GStreamer`_ for ReplayGain analysis, you will of course need to +install GStreamer and plugins for compatibility with your audio files. +You will need at least GStreamer 1.0. .. _GStreamer: http://gstreamer.freedesktop.org/ -Then enable the GStreamer backend of the ``replaygain`` plugin -(see :doc:`/reference/config`) add the following to your config file:: +Then, enable the plugin (see :ref:`using-plugins`) and specify the GStreamer +backend by adding this to your configuration file:: replaygain: backend: gstreamer - -MP3Gain-based command-line tools -```````````````````````````````` +mp3gain and aacgain +``````````````````` In order to use this backend, you will need to install the `mp3gain`_ -command-line tool or the `aacgain`_ fork thereof. To get started, install this -tool: +command-line tool or the `aacgain`_ fork thereof. Here are some hints: * On Mac OS X, you can use `Homebrew`_. Type ``brew install aacgain``. * On Linux, `mp3gain`_ is probably in your repositories. On Debian or Ubuntu, @@ -50,49 +48,47 @@ tool: .. _aacgain: http://aacgain.altosdesign.com .. _Homebrew: http://mxcl.github.com/homebrew/ -Then enable the MP3gain backend of the ``replaygain`` plugin (see :doc:`/reference/config`). If beets -doesn't automatically find the ``mp3gain`` or ``aacgain`` executable, you can -configure the path explicitly like so:: +Then, enable the plugin (see :ref:`using-plugins`) and specify the "command" +backend in your configuration file:: replaygain: backend: command - command: /Applications/MacMP3Gain.app/Contents/Resources/aacgain -Usage & Configuration ---------------------- - -The plugin will automatically analyze albums and individual tracks as you import -them. It writes tags to each file according to the `ReplayGain`_ specification; -if your player supports these tags, it can use them to do level adjustment. - -Note that some of these options are backend specific and are not currently -supported on all backends. - -By default, files that already have ReplayGain tags will not be re-analyzed. If -you want to analyze *every* file on import, you can set the ``overwrite`` option -for the plugin in your :doc:`configuration file `, like so:: +If beets doesn't automatically find the ``mp3gain`` or ``aacgain`` executable, +you can configure the path explicitly like so:: replaygain: - overwrite: yes + command: /Applications/MacMP3Gain.app/Contents/Resources/aacgain -The target level can be modified to any target dB with the ``targetlevel`` -option (default: 89 dB). -When analyzing albums, this plugin can calculates an "album gain" alongside -individual track gains. Album gain normalizes an entire album's loudness while -allowing the dynamics from song to song on the album to remain intact. This is -especially important for classical music albums with large loudness ranges. -Players can choose which gain (track or album) to honor. By default, only -per-track gains are used; to calculate album gain also, set the ``albumgain`` -option to ``yes``. +Configuration +------------- + +Available configuration options for the ``replaygain`` section in your +configuration file include: + +* **overwrite**: By default, files that already have ReplayGain tags will not + be re-analyzed. If you want to analyze *every* file on import, you can set + the ``overwrite`` option for the plugin in your :doc:`configuration file + `, like so:: + + replaygain: + overwrite: yes + +* **targetlevel**: The target loudness level can be modified to any number of + decibels with the ``targetlevel`` option (default: 89 dB). + +These options only work with the "command" backend: + +* **apply**: If you use a player that does not support ReplayGain + specifications, you can force the volume normalization by applying the gain + to the file via the ``apply`` option. This is a lossless and reversible + operation with no transcoding involved. +* **noclip**: The use of ReplayGain can cause clipping if the average volume + of a song is below the target level. By default, a "prevent clipping" option + named ``noclip`` is enabled to reduce the amount of ReplayGain adjustment to + whatever amount would keep clipping from occurring. -If you use a player that does not support ReplayGain specifications, you can -force the volume normalization by applying the gain to the file via the -``apply`` option. This is a lossless and reversible operation with no -transcoding involved. The use of ReplayGain can cause clipping if the average -volume of a song is below the target level. By default, a "prevent clipping" -option named ``noclip`` is enabled to reduce the amount of ReplayGain adjustment -to whatever amount would keep clipping from occurring. Manual Analysis ---------------