ReplayGain

amaroK replaygain
v1.0.0-beta5 by Miguel Angel Alvarez (maacruz at gmail.com)
October 20, 2007

An amaroK script to normalize volume using the replaygain method
Now on your language: english, spanish, german, hungarian, french, russian, slovak, finnish, polish, portuguesse, italian, turkish, swedish
(more translators wanted!!!)

Using replaygain will make all your songs have the same perceived volume, making unnecesary to adjust the volume on each song change (specially if they are from different albums/artists)


--Release Notes--
1.0.0beta5: Workaround for amarok saving playlist with non valid utf8 characters, which in turn would cause the script to crash. The internal scanner for wma/asf files is now x10 faster.
1.0.0-beta series:
Major enhancements and new features.
Support for streams: now streams can be scanned. The scan must be manually started in track mode. It will rip 60 seconds and set the gain accordingly, so some variance can be expected. The stream must broadcast normalized somewhat for this to have any sense. Requires mplayer.
Support for wma: Using a new internal scanner (only for wma for now, but soon to be expanded for all filetypes). It is quite experimental but since beta5 it is very fast and will use 3dnow on AMD cpu's. Requires mplayer.
Autoscan mode: now replaygain will autoscan the playlist when it is modified (files are added or removed). The autoscan only can do track mode. Streams are not autoscanned (by now). The autoscan starts after a configurable amount of time once the playlist has changed, to avoid putting the cpu under high load during track change in dynamic playlists. Autoscan runs in a separated thread, so replaygain works while the scan is in progress; beware that the manual scan still runs in the main thread (the script will not work on anything else). Autoscan can be enabled/disabled using the playlist context menu, if you want to stop a running autoscan simply disable it; starting a manual scan will also stop a running autoscan; changing the playlist while autoscan is running will let it finish the current file and start a new autoscan. Requires amarok>=1.4.6 and python-xml
New anti-lag meassure: the script follows the playlist and will guess the next track to be played, avoiding to query amarok. Only works if amarok is not playing in random track mode. Requires amarok>=1.4.6 and python-xml.
Minor improvements:
The scripts keeps you informed while a scan is in progress (previous versions only informed when the scan started and finished).
The configuration dialog now informs you of what's supported and any dependency unmet.
Memory usage has been reduced
Files are checked if writeable before scanning them (many thanks to dAniel hAhler http://daniel.hahler.de/ for suggestion and patch)
Volume is updated if the current playing file hadn't replaygain tags after it is scanned (manually or automatically)
More bugs
--End of notes--

Please report any bug

Files supported:
vorbis (ogg), mp3, aac (mp4/m4a), flac, musepack (mpc), wma/asf

Dependencies:

Needed:
kdebase3 (kdialog and dcop), python 2.3 or later, and UTF8 filesystem character set (to use national characters in the filename).
Optional:
pygtk (python-gtk) for the advanced configuration interface.
python-xml for easy playlist album scanning, autoscan, lag-reduction
mplayer, oggenc (vorbis-tools), vorbisgain for streams and wma support.
kdebindings3-python for lag-reduction
The following external utilities:
. metaflac (flac): to apply replaygain tags on flac files. This is likely a standard package on your distribution
. vorbisgain: to apply replaygain tags on vorbis ogg files
. aacgain: to apply replaygain tags on mp4/m4a aac files (works for mp3 too)
. mp3gain: to apply replaygain tags on mp3 files. Not needed if you have aacgain
. replaygain (musepack): to apply replaygain info on mpc (musepack) files.
. mplayer plus oggenc (vorbis-tools) and vorbisgain: to apply replaygain tags on wma/asf files and streams.

Where you can get the needed utilities:

Check your distribution's software repositories first.
Guru's page for SuSE Linux has mp3gain and vorbisgain. (http://linux01.gwdg.de/~pbleser/rpm-navigation.php?cat=Sound/)
Packman has musepack packages (they include replaygain) for SuSE Linux (http://packman.links2linux.de/)
Musepack home page (http://www.musepack.net/index.php?pg=lin)
Vorbisgain home page (http://sjeng.org/vorbisgain.html)
mp3gain home page (http://mp3gain.sourceforge.net/download.php)
aacgain home page (http://altosdesign.com/aacgain/).
mplayer home page (http://mplayerhq.hu

How to use
First you need to analyze all your song files using replaygain. The replaygain algorithm calculates a perceptual volume (gain) for each track (track mode) and album (album mode) and uses this information to correct the playback volume so all tracks or albums sound equally loud. In album mode the relative differences between tracks of an album are preserved, so more quiet tracks will sound more quiet, and louder tracks will sound louder. Album mode is better for live recordings and albums meant to be more than a collection of tracks, while track mode is better for heterogeneus mixes and compillations.
This analysis will not change your file's sound data, it will store the information in tags.

You can analyze a stream, file, album or your whole collection from the playlist's context menu:
Apply Replaygain tags->
-- To selected files in track mode: tag one or more files (as selected in playlist) with their respective track gain (track mode).
-- To playlist in album mode: tag all files in the playlist with both album and track gain tags (album mode), as if the playlist is one album.
-- To entire collection using album tags: the script will group the files in the database using their "Album" tag, and scan each group in album mode.
-- Autoscan: if this is activated, files in the playlist will be automatically tagged (track mode tags only).
It is recommended to have python-xml installed for album tagging (if not installed, playlist tagging as such and autoscan will not be available).

Once a file is tagged with replaygain data, the script will be able to read such tags and it will update the volume as needed.

The mode tags used are selected from the playlist context menu:
- Replaygain mode: which mode will use (track or album)

If a file doesn't have replaygain tags or it is of an unsupported type, it will be played at the default gain.

You can configure the script's operation in the configure script dialog. The most important parameters are:
- Pregain: this is the reference gain in dB (from the 0 point set at 55% volume in amarok). The range goes aproximately from 11 dB to -17 dB. Any replaygain volume correction will be relative to this gain, so you should leave enough space in the range for the script to work. The recommended value is 6.0 dB.
- Peak protection: If enabled, the volume may be adjusted to avoid clipping.
- Default gain: this is the assumed gain for files with no replaygain information. A good value could be -6.0 dB.
- Autoscan delay: amount of time in seconds between the playlist change and the autoscan start. Avoids reacting too quickly to manual playlist changes, and most important, clogging the CPU at track change when using dynamic playlists.

Crossfade is supported, so the volume changes slowly when crossfading.
You have also the option of sudden or smooth volume change when crossfade is disabled in amarok.

Lag reducing howto
Some people are affected by large lag between track change and the replaygain volume update
Lag seems caused by amarok itself by taking too much time to return from dcop calls.
This has been related to high cpu load caused by sqllite and cover image rendering.
So, if you are affected, what can you do?
In amarok 1.4.6 and later the script keeps track of playlist changes, to guess what the next song is and tell amarok to adjust volume inmediatly, needs python-xml and only works if track are played secuentially.
The cpu load for using sqllite has been reduced in 1.4.0 and later, and if you are using 1.3.9 you can apply the patch included in the amarok replaygain script package. Install either of those. Using a external database may be a good idea if you have a large collection, too.
Install kdebindings3-python to take advantage of new script's code.
If you are using the script's OSD control (the "Disable OSD during...." option) disable the OSD or uncheck the script option, it couldn't be optimized because of bugs in pykde
To see how cover rendering affects you, you can move your covers elsewere (try with an author or two) so they are not found. Large cover files may have a big impact, if this is the case, use gimp to reduce them.
Run amarok minimized in the tray, it will not update visual elements saving much time.
Resource intensive software affects too (some screensavers, p2p, ...)
During this beta release debug output is enabled. Have a look at your lag (in seconds) by typing in a konsole/xterm:
tail -f ~/.kde/share/apps/amarok/scripts-data/replayggain.log|grep time
As a reference, my lag is well under 0.1 s (usually 0.01-0.05)


Feedback appreciated.

Enjoy!
Miguel Angel

0.1-0.3.3
Old vorbisgain releases

0.5-beta "Reborn"
Major rewriting, now it is python
Renamed to replaygain
Add Album and peak support
New nice pygtk interface
Thanks to Kevin Radloff and Jocke "Firetech" for their suggestions and testing

0.5
Uses the new (since amarok 1.3.2) readConfig dcop calls if available, now the script is aware of amarok configuration changes
Added support for musepack (mpc) files

0.5.5
Added support for AAC (mp4/m4a) files
The script checks for external utilities when closing the configure dialog

0.6 "Clean OSD"
New option to disable osd updates during volume changes solving the annoying quick osd changes
Changed detection of external utilities since mp3gain has different behaviour depending on its version (thanks Jocke for pointing this out)
Settings are reread only when the engine starts playing, not at every song change
Fixed the check for external utilities so it solves the "mp3gain not found" missleading message, and a typo which prevented using aacgain when present.
Fixed flac on latest flac releases (thanks Gary Virta)
Changed the "utility not found" dialog to a less annoying notification
Many optimizations and speedups
Thanks Jocke and Roberto for all your testing

0.6.1
Hotfix: fix script breaking on amarok older than 1.3.2 when osd is disabled

0.7
Many new configuration options, not all can be accesed through the kdialog interface
Clipping protection may be disabled so volume doesn't go to 0 on some broken mp3 files
Pregain (volume reference level) may be adjusted by moving the volume slider
Pregain is now adjusted to tenths of dB instead of integer dB
The volume transitions may be smoothed over any specified amount of time when crossfade is disabled
Accurate timing so crossfaded/smoothed volume changes don't take longer than they should
Pygtk interface now has help as tooltips
Changes in script configuration take effect inmediately instead of waiting till next song
Script configuration is saved when amarok stops playing

0.7.1
Added support for mp3 files tagged with foobar (id3v2 tags), it requires id3v2 installed
SIGTERM handler

0.7.2
Added context menu shortcut to change replaygain mode

0.8.0
Internacionalization. Spanish translation.
New option to set the gain (volume) for files without replaygain info (or unsupported files).
Context menu options to apply/delete replaygain tags to playlist/collection. It is recommended to have python-xml installed for almbum tagging.
Some bugfixes

0.8.1
German, french and hungarian translations

0.8.2
Hotfix: do not break while scanning collection if unsupported file has no album tag.

0.8.3
Fix problems with special shell characters in filenames

0.8.4
Fix breaking if enviroment LANG variable is not set (assumes ISO8859-1 charset)

0.8.5
Fix encoding strings headache caused by gettext not returning unicode strings

0.8.6
Couple of small fixes

0.9.0
This release is designed to reduce lag (thanks Stewie for all your testing). Requires installing kdebindings3-python (aka python-kde) to take advantage of new code. Uses pykde for dcop calls if possible
Finnish GUI translation thanks to Samu Voutilainen
Slovak GUI translation thanks to Jozef Říha
Russian translation thanks to Anton Chumak.
Reworked kdialog interface to fix problems caused by X error messages
Corrects collection scanning if using dynamic collection (patch by Frederic Dinh).
Use mutagen-1.4 library (http://www.sacredchao.net/quodlibet/wiki/Development/Mutagen) to read tags, except on mp4/m4a and mpc. Code for mpc and mp4 tag reading thanks to Justus Pendleton and QuodLibet player (needs ctypes python module). Dropped dependency on external utilities for tag reading.
Added support for RVA2 tags (used by QuodLibet and normalize)
Many bugfixes

0.9.1 Add portuguesse and polish GUI translations, updated finnish translation, thanks to Candido Lopes, Jaroslaw Gorny and Samu Voutilainen.

0.9.2: Add italian and turkish GUI translations. Many thanks to Davide "DuffyDac" and Fatih Çiroglu

0.9.3: Add swedish GUI and README translation. Many thanks to Göran Jartin