mirror of
https://github.com/beetbox/beets.git
synced 2026-01-05 15:33:15 +01:00
revise docs for expanded RG plugin
Among other things, this clarifies which options are available with each backend.
This commit is contained in:
Adrian Sampson
parent
c6451cfc50
commit
8fb5ddc3b9
2 changed files with 51 additions and 56 deletions
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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 </reference/config>`, 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
|
||||
</reference/config>`, 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
|
||||
---------------
|
||||
|
|
|
|||
Loading…
Reference in a new issue