From b9e2beddec6e260fdea38d42a28ec5c30b2fbe0b Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Fri, 12 Oct 2012 22:42:08 -0700 Subject: [PATCH] replaygain: changelog & doc enhancements for GH-55 --- beetsplug/replaygain.py | 32 ++++++++++--------------- docs/changelog.rst | 5 ++++ docs/plugins/replaygain.rst | 48 ++++++++++++++++++------------------- 3 files changed, 40 insertions(+), 45 deletions(-) diff --git a/beetsplug/replaygain.py b/beetsplug/replaygain.py index ebc18eed3..a1804b8d5 100755 --- a/beetsplug/replaygain.py +++ b/beetsplug/replaygain.py @@ -1,28 +1,20 @@ -#Copyright (c) 2012, Fabrice Laporte +# This file is part of beets. +# Copyright 2012, Fabrice Laporte and Peter Brunner. # -#Permission is hereby granted, free of charge, to any person obtaining a copy -#of this software and associated documentation files (the "Software"), to deal -#in the Software without restriction, including without limitation the rights -#to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -#copies of the Software, and to permit persons to whom the Software is -#furnished to do so, subject to the following conditions: +# Permission is hereby granted, free of charge, to any person obtaining +# a copy of this software and associated documentation files (the +# "Software"), to deal in the Software without restriction, including +# without limitation the rights to use, copy, modify, merge, publish, +# distribute, sublicense, and/or sell copies of the Software, and to +# permit persons to whom the Software is furnished to do so, subject to +# the following conditions: # -#The above copyright notice and this permission notice shall be included in -#all copies or substantial portions of the Software. -# -#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -#IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -#FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -#AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -#LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -#OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -#THE SOFTWARE. +# The above copyright notice and this permission notice shall be +# included in all copies or substantial portions of the Software. import logging import subprocess -import tempfile import os -import errno from beets import ui from beets.plugins import BeetsPlugin @@ -38,7 +30,7 @@ class RgainError(Exception): class RgainNoBackendError(RgainError): """The audio rgain could not be computed because neither mp3gain - nor aacgain command-line tool is installed. + nor aacgain command-line tool is installed. """ class ReplayGainPlugin(BeetsPlugin): diff --git a/docs/changelog.rst b/docs/changelog.rst index 03c773fe2..ec27a314c 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -16,6 +16,9 @@ Changelog * New plugin: :doc:`/plugins/ihate` automatically skips (or warns you about) importing albums that match certain criteria. Thanks once again to Blemjhoo Tezoulbr. +* :doc:`/plugins/replaygain`: This plugin has been completely overhauled to use + the `mp3gain`_ or `aacgain`_ command-line tools instead of the failure-prone + Gstreamer ReplayGain implementation. Thanks to Fabrice Laporte. * :doc:`/plugins/scrub`: Scrubbing now removes *all* types of tags from a file rather than just one. For example, if your FLAC file has both ordinary FLAC tags and ID3 tags, the ID3 tags are now also removed. @@ -52,6 +55,8 @@ Changelog unintentionally loading the plugins they contain. .. _Tomahawk resolver: http://beets.radbox.org/blog/tomahawk-resolver.html +.. _mp3gain: http://mp3gain.sourceforge.net/download.php +.. _aacgain: http://aacgain.altosdesign.com 1.0b15 (July 26, 2012) ---------------------- diff --git a/docs/plugins/replaygain.rst b/docs/plugins/replaygain.rst index eabd5f0ab..6eead058b 100644 --- a/docs/plugins/replaygain.rst +++ b/docs/plugins/replaygain.rst @@ -9,22 +9,21 @@ playback levels. Installation ------------ -This plugin use a command line tool to compute the ReplayGain information: +This plugin uses the `mp3gain`_ command-line tool or the `aacgain`_ fork +thereof. To get started, install this tool: * On Mac OS X, you can use `Homebrew`_. Type ``brew install aacgain``. -* On Windows, install the original `mp3gain`_. +* On Linux, `mp3gain`_ is probably in your repositories. On Debian or Ubuntu, + for example, you can run ``apt-get install mp3gain``. +* On Windows, download and install the original `mp3gain`_. .. _mp3gain: http://mp3gain.sourceforge.net/download.php +.. _aacgain: http://aacgain.altosdesign.com .. _Homebrew: http://mxcl.github.com/homebrew/ -To enable the plugin, you’ll need to edit your .beetsconfig file and add the -line ``plugins: replaygain``. - - [beets] - plugins = replaygain - -In case beets doesn't find the path to the ReplayGain binary, you can write it -explicitely in the plugin options like so : +Then enable 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:: [replaygain] command: /Applications/MacMP3Gain.app/Contents/Resources/aacgain @@ -43,23 +42,22 @@ for the plugin in your :doc:`/reference/config`, like so:: [replaygain] overwrite: yes -The target level can be modified to any target dB with the ``targetlevel``option -(default: 89 dB). +The target level can be modified to any target dB with the ``targetlevel`` +option (default: 89 dB). -ReplayGain allows to make consistent the loudness of a whole album while allowing - the dynamics from song to song on the album to remain intact. This is called - 'Album Gain' (especially important for classical music albums with large loudness - range). -'Track Gain' (each song considered independently) mode is used by default but can -be changed with ``albumgain`` switch:: +ReplayGain can normalize an entire album's loudness while allowing the dynamics +from song to song on the album to remain intact. This is called "album gain" and +is especially important for classical music albums with large loudness ranges. +"Track gain," in which each song is considered independently, is used by +default. To override this, use the ``albumgain`` option:: [replaygain] albumgain: yes -If you use a player that does not support ReplayGain specifications, you may want -to force the volume normalization by applying the gain to the file via the ``apply`` -option. This is a lossless and revertable operation with no decoding/re-encoding 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" feature named ``noclip`` is -enabled to reduce the amount of ReplayGain adjustment to whatever amount would -keep clipping from occurring. \ No newline at end of file +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.