Hydrogenaudio Knowledgebase - User contributions [en]

ReplayGain

2026-01-23T13:31:32Z

Case: /* foobar2000 ReplayGain scanner */

'''ReplayGain''' is the name of a technique invented to achieve the same perceived playback loudness of audio files. It defines an algorithm to measure the '''perceived''' loudness of audio data.

ReplayGain allows the loudness of each song within a collection of songs to be consistent. This is called 'Track Gain' (or 'Radio Gain' in earlier parlance). It also allows the loudness of a specific sub-collection (an "album") to be consistent with the rest of the collection, while allowing the dynamics from song to song on the album to remain intact. This is called 'Album Gain' (or 'Audiophile Gain' in earlier parlance). This is especially important when listening to classical music albums, because quiet tracks need to remain a certain degree quieter than the louder ones.

ReplayGain is different from [[Normalization|peak normalization]]. Peak normalization merely ensures that the peak amplitude reaches a certain level. This does not ensure equal loudness. The ReplayGain technique measures the ''effective power'' of the waveform (i.e. the RMS power after applying an "equal loudness contour"), and then adjusts the amplitude of the waveform accordingly. The result is that Replay Gained waveforms are usually more uniformly amplified than peak-normalized waveforms.

==Target loudness==
The target loudness of ReplayGain is [https://wiki.hydrogenaudio.org/index.php?title=Original_ReplayGain_specification#Reference_level '''89''' '''dB SPL'''] / '''-18''' '''[https://en.wikipedia.org/wiki/LUFS LUFS]''' (''Loudness Units relative to Full Scale'').

Some utilities have realized the inadequacies of the classic ReplayGain loudness calculation, switching to a more modern algorithm ([https://www.itu.int/rec/R-REC-BS.1770-5-202311-I/en ITU-R BS.1770]). However, the way it was integrated was extremely ''ad hoc'', at least until a draft of a [[ReplayGain 2.0 specification|revised specification]] started being written.

==Clipping==
Audio is generally recorded such that the loudest sounds don't clip, but the use of ReplayGain can cause clipping if the average volume of a song is below the target level. That is, upon playback, the volume of a quiet song is increased, so the parts of the song with above-average loudness, especially in the bass frequencies, will exceed the limits of the format and will be distorted. Whether this distortion is audible depends on the sounds in question, and the listener's sensitivity.

Implementations deal with the risk of clipping in different ways. Some have a "pre-amp" feature which reduces (or boosts) the original audio's level by a certain amount before doing whatever is needed for ReplayGain. Some have a "prevent clipping" feature to reduce the amount of ReplayGain adjustment to whatever amount would keep clipping from occurring, based on peak info stored in the file's metadata (thus reducing the effectiveness of ReplayGain). Some recommend using a compressor/limiter DSP to prevent or reduce clipping, regardless of whether it was caused by ReplayGain.

An alternative that may reduce the risk of clipping is the [https://tech.ebu.ch/docs/r/r128.pdf EBU R 128] recommendation of a -23 LUFS target, but that's a different standard, and some may find the additional reduction in volume excessive, particularly if it leads to maxing out volume on user hardware. [[Opus]] in particular has adopted that standard, using a global gain as well as <code>R128_TRACK_GAIN</code> / <code>R128_ALBUM_GAIN</code> tags. With ReplayGain, a simple (though somewhat radical) solution is to lower the preamp value by 5 dB (or whatever one feels comfortable with) in the playback software. The RG target will always be -18 LUFS, regardless of a user's volume or preamp settings.

== Implementations ==
There are different ReplayGain implementations, each with its own uses and strength. Most use [[metadata]] to indicate the level of the volume change that the player should make. Some modify the audio data itself, and optionally use metadata as well. There are advantages and disadvantages to both methods.

In the metadata method, information on both types of ReplayGain (Track Gain and Album Gain) can be stored. The volume-change information can be very precise. If audio data was also changed, the metadata can contain "undo" info. Not all audio players/decoders know how to read and use ReplayGain information stored in metadata. And there's no standard for where and how ReplayGain info is stored; each implementation uses different formats and puts the info in different locations.

In the audio data method, the file's actual audio data is modified so that its natural/default playback volume is at the target level. In this scenario, only one type of ReplayGain (Track Gain or Album Gain) can be applied. If no "undo" info is saved somewhere, it may not be possible to restore the original audio data. Limitations of the audio file format may prevent precise (finely tuned) gain adjustments with this method. For example, MP3 and AAC files can only be losslessly modified in 1.5 dB steps. Depending on the audio file format, the process may also be lossy in the sense that it could irreversibly push a signal above the format's maximum amplitude (resulting in clipping) or below the minimum (resulting in silence).

=== Old versus new algorithms ===
Since the ReplayGain standard does not define tags to specify which algorithm was used (classic or ITU-R BS.1770) or what target was set (RG's -18 LUFS, EBU R 128's -23 LUFS, or any other target set by the user or some piece of software), there may be confusion as to how the results were produced. Typically, utilities that ship with reference encoders (FLAC / metaflac, Vorbis / vorbisgain, WavPack / wvgain, Musepack / mpcgain…) use the original RG algorithm, which can produce values that differ from newer tools by several decibels in certain cases. Generally speaking, it is recommended to run other utilities or players that implement the ITU-R BS.1770 algorithm, although it may not be obvious which algorithm they use at first glance. Their documentation may provide that information.

==== RG1, RG2 ====
Although there are many references online, and within ReplayGain scanners, about version 1 vs. version 2 of the ReplayGain standard, at the time of writing this, there is (admittedly) only one ReplayGain standard. The core principle, as well as the 4 tags from the original specification, have not changed. More tags have been proposed but they are still subject to debate. As a rule of thumb, tools that advertise "ReplayGain 2" compliance employ the newer, more accurate ITU-R BS.1770 algorithm. [[foobar2000]] labels it "EBU R128" but it essentially means the same thing. Should a better algorithm be developed in the future, it will still work towards fulfilling ReplayGain's original goals, and probably write the same tags.

=== MP3Gain ===
[[MP3Gain]] is an implementation of classic ReplayGain. It can be used to just analyze files & recommend changes or to also modify the gain. If modifying the gain, it always modifies the global gain fields in the MP3 audio data. It can add somewhat precise metadata, including undo info. The gain can be modified to any target dB, or it can be changed by a specified amount. For balance correction, user-specified changes can even be made on just one channel in simple L/R stereo-mode files (not joint stereo).

* Format: [[MP3]]
* Method: Audio + Meta (in APE tag), or Audio only
* APE tag fields (ASCII bytes):
** <code>MP3GAIN_MINMAX ###,###</code> - minimum & maximum global gain values for this file. 3 digits, zero-padded if necessary.
** <code>MP3GAIN_ALBUM_MINMAX ###,###</code> - minimum & maximum global gain values across a set of files scanned as an album. Optional.
** <code>MP3GAIN_UNDO +###,+###,N</code> - the global gain adjustment to restore the original values in the left and right channels, respectively, followed by an indicator of whether to wrap at the extremes (<code>N</code> means no, <code>W</code> means yes). The adjustment values are 3 digits, zero-padded, preceded by a sign (<code>+</code> or <code>-</code>).
** <code>REPLAYGAIN_TRACK_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Examples: <code>+0.424046</code> and <code>-10.38500</code>
** <code>REPLAYGAIN_TRACK_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Example: <code>0.149923</code>
** <code>REPLAYGAIN_ALBUM_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Optional.
** <code>REPLAYGAIN_ALBUM_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Optional.
* Limitations: Although the metadata, if written, contains precise adjustment & peak values, the audio data modifications are limited to 1.5dB steps and may become irreversible (however, that's a very rare condition; see the [https://hydrogenaud.io/index.php/topic,34154.0.html "mp3gain is NOT lossless" forum thread])
* http://mp3gain.sourceforge.net/

=== AACGain ===
[[AACGain]] is a modified version of MP3Gain that works on both MP3 and AAC files.

* Format: [[MP3]], [[AAC]] (with or without MP4 container)
* Method: Audio + Meta, or Audio only
* Limitations: Limited to 1.5dB steps mode, may become irreversible (same caveat as for MP3Gain)
* http://aacgain.altosdesign.com/

=== [[LAME]] ===
* Method: Header ([http://gabriel.mp3-tech.org/mp3infotag.html mp3infotag])
* Notes:
** Uses the classic RG algorithm.
** Tags added during encoding; not supported by any player yet; Track Gain only
** Replay Gaining MP3's is usually done using MP3Gain (see [[ReplayGain#MP3Gain|above]]) or [[ReplayGain#foobar2000 ReplayGain scanner|foobar2000]]
* http://lame.sourceforge.net/

=== [[Musepack]] ReplayGain ===
* Method: Header (similar to Meta data method)
* Notes: Uses the classic RG algorithm. ReplayGain values are stored in the header and ReplayGain is part of the Musepack specifications; therefore any Musepack decoder that does not support ReplayGain can be considered broken.
* http://www.musepack.net/

=== VorbisGain ===
* Format: (Ogg) [[Vorbis]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://www.sjeng.org/vorbisgain.html
** new compiles of VorbisGain at [http://www.rarewares.org/ogg.html www.rarewares.org]
:'''''Note:''' Andavari has provided a very useful script to integrate VorbisGain, which is a CLI tool, into Windows Explorer. Please (Ogg) [[Vorbis#ReplayGain|check this section]].''

=== FLAC / METAFLAC ===
* Format: [[Free Lossless Audio Codec|FLAC]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://flac.sf.net

=== WavPack / WVGAIN ===
* Format: [[WavPack]]
* Method: Meta (in [[APEv2]] tag)
* Uses the classic RG algorithm.
* http://www.wavpack.com

=== Wavegain ===
* Format: waveform
* Method: Audio
* Uses the classic RG algorithm.
* Limitations: Irreversible
* http://www.rarewares.org/others.php#wavegain

=== MusicPlayer ===
* Custom implementation, inspired by MP3Gain.
* Format: any that FFmpeg supports
* Method: Audio
* Limitations: Doesn't modify the files at all. Stores the value in own database. Used only for playback.
* https://github.com/albertz/music-player

=== [[foobar2000]] ReplayGain scanner ===
* Since v1.1.6, defaults to ITU-R BS.1770 analysis (although it labels it EBU R128), but can be configured to use the "Classic ReplayGain" algorithm instead. The ITU-R BS.1770 implementation uses a reference level of -18 LUFS instead of -23, in order to retain compatibility with the ReplayGain standard.
* Format:
** [[MP3]]: Values written to [[ID3v2]] (default) or [[APEv2]] tags.
** [[Musepack]]: Values written to header.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]] and/or file header.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags
** [[MP4]] (AAC, ALAC, MP3): Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain).
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[TAK]]: Values written to [[APEv2]] tags.
** [[TTA]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** [[WMA]]: Values written to WMA tags.
** [[WAV]]: Values written to ID3 chunk.
** [[AIFF]]: Values written to ID3 chunk.
** [[Matroska]]: Values written to container tags.
** Modules ([[MOD]] etc.): Optionally saved into [[APEv2]] tags.
** Any non-taggable format or format supported by FFmpeg can store RG values in a database or external tag with a component.
** A separate function can be invoked to apply the tagged Track or Album Gain to the global gain fields in MP3, AAC (in container), or Opus files, and rewrite any existing tags to account for the peak change and compensate for the difference from 89 dB. The 89 dB reference level for tags isn't configurable, but the reference level applied to the global gain fields is.
** Can automatically copy Track or Album gain values to Apple's SoundCheck tag in MP4 files or any format that supports ID3v2 to effectively add ReplayGain support to Apple's players.
* https://foobar2000.org/

=== [[MediaMonkey]] ===
* Format:
** [[MP3]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in MediaMonkey's MDB database.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[WAV]]: Values stored in MediaMonkey's MDB database.
** [[MPC]]: Internal gain Structure.
* In addition to tags, all ReplayGain values are also stored in MediaMonkey's MDB database
* Album/Audiophile ReplayGain not supported until v3.0 (Dec 2007); support during burning & ripping added in 3.1 (Jun 2009)
* Also capable of (irreversibly) changing the volume of MP3 tracks, similar to [[MP3Gain]]
* http://www.mediamonkey.com/

=== [[Winamp]] ReplayGain scanner===
* Format:
** [[MP3]]: Values written to [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in Windows Media Audio tags.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags.
** [[MP4]]
** [[TAK]]: Values written to [[APEv2]] tags.
* Support Album/Track Gain

=== [[loudgain]] ===
* Format:
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** MP2, [[MP3]]: Values written to [[ID3v2]] tags (ID3v2.3/ID3v2.4 selectable).
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** (Ogg) [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** (Ogg) [[Speex]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]], based on -23 LUFS Opus standard. Only <code>R128_TRACK_GAIN</code> and <code>R128_ALBUM_GAIN</code> are written, but the calculated ''true peak'' value can still be used to reduce the gain values ([[Clipping]] prevention).
** [[MP4]], [[M4A]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain). ReplayGain values are stored under <code>----:com.apple.iTunes:…</code>. This is for [[AAC]] and [[ALAC]] in [[MPEG-4]] containers.
** [[ASF]], [[Windows Media Audio|WMA]]: Values written to WMA tags, no prefix.
** [[WAV]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] (ID3v2.3/ID3v2.4 selectable) format. Using the <code>bext</code> chunk (for BWF v2) isn’t (yet) supported, but won’t be destroyed on writing.
** [[Audio Interchange File Format|AIFF]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] format.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[Monkey's Audio]] (APE): Values written to [[APEv2]] tags.
* Follows EBU R128, ITU BS.1770 and the [[ReplayGain 2.0 specification|revised ReplayGain specification]].
* ''Never'' touches the actual audio data but ''only writes RG2 tags''.
* Uses ''true peak'' values calculated by oversampling to 192 kHz, using a custom polyphase FIR interpolator that will oversample 4x for sample rates < 96 kHz, 2x for sample rates < 192 kHz and leave the signal unchanged for 192 kHz.
* ''Clipping prevention'' can be used to lower the ReplayGain values to a safe margin (default -1 dBTP, can be changed).
* Many options for special cases: force RG tags upper-/lowercase, add extra tags (LRA, Reference loudness), strip unwanted tag types (APEv2 from MP2/MP3, ID3 from WavPack), tab-delimited table output for analysis with CSV file.
* ''Linux'' Free and Open Source software, can be installed on ''MacOS'' using ''HomeBrew'', on ''Windows 10'' using the Linux ''bash''.
* Also installs a <code>rgbpm</code> bash script for mass-tagging, which can be adapted to the user’s needs.
* '''Warning:''' Loudgain relies on standard libraries like ''TagLib''. Linux distros (except rolling releases) sometimes deliver outdated libraries, so be sure you use the latest version of ''TagLib''. Version 1.11.1 had a nasty bug for a while that [https://hydrogenaud.io/index.php/topic,118085.msg974957.html#msg974957 could corrupt Ogg Vorbis files]. This has been fixed in the meantime but the TagLib version not updated. Loudgain comes with a (slower) static version called <code>loudgain.static</code> in the repo’s <code>/bin</code> folder that doesn’t expose the bug and can also be used on older Linux versions (like Ubuntu 14.04, Linux Mint 17).
* https://github.com/Moonbase59/loudgain
* Bug tracker: https://github.com/Moonbase59/loudgain/issues

=== [[rsgain]] ===
rsgain is a newer ReplayGain command line utility designed with a "batteries included" philosophy, use the newer ITU-R BS.1770 algorithm.

Features:
* Cross-platform Windows / macOS / Linux
* Supports all popular audio formats
* Simplified "Easy Mode" command line syntax supports recursive, directory-based scanning
* Multithreaded scanning option that provides significant speed improvement with full library scans
* Option to skip files with existing ReplayGain metadata
* Scan presets allow the user to save advanced settings for consistent use

== Players support ==
ReplayGain being present in the specs of the FLAC, Musepack, and APE formats, any player that support those formats usually supports ReplayGain.

The situation with MP3 is rather different, as it was not part of the MP3 specs. The APEv2 tags metadata implementation is somewhat becoming the de-facto standard.

=== Windows ===
* [[foobar2000]] supports ReplayGain in all possible aspects.
* [[Winamp]] supports ReplayGain in album or track mode.
* [[MediaMonkey]] supports ReplayGain, with many configuration options.
* [[XMPlay]] recently implemented ReplayGain
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.

''...and probably others.''

=== Linux ===
* [[XMMS]]. Reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], [[Musepack]], (Ogg) [[Vorbis]] ..
:For [[MP3]], use the CVS version of the [http://xmms-mad.sourceforge.net/ xmms-mad] mp3 plugin (it's not yet released as binary, furthermore not available in distribs' versions for now. Meanwhile binaries are available here: [http://perso.crans.org/~krempp/xmms-mad/ custom binaries])
* [[amarok]]. By using the amarok-script [http://kde-apps.org/content/show.php?content=26073 ReplayGain]
:And possibly others, since [http://developer.kde.org/~wheeler/taglib.html TagLib] added support for [[APEv2]] tags in [[MP3]] files, players using this library (like [[amaroK]] and [[JuK]]) might support that kind of ReplayGain tags in the near future.
* [http://www.sacredchao.net/quodlibet Quod Libet] reads ReplayGain from (Ogg) [[Vorbis]], [[MP3]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:Requires support to be enabled (via the appropriate python bindings and libraries) for the above formats. Does not support ReplayGain values stored in [[APEv2]] tags in [[MP3]]s. ReplayGain values are stored in RVA2 id3v2.4 frames. See the [http://www.sacredchao.net/quodlibet/wiki/Development/ID3Notes Quod Libet RVA2 / ReplayGain notes].
* [http://www.musicpd.org/ Music Player Daemon] (MPD) reads ReplayGain from (Ogg) [[Vorbis]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:foobar2000-style TXXX frames in [[MP3]]s are also supported in the latest development releases.
* [http://www.mplayerhq.hu/ MPlayer]. Mplayer support for ReplayGain is codec dependent.
:Codecs that are known to support ReplayGain: vorbis
:Because of this, you need to prioritize the codecs that support it, or choose it individually on the command line. To add it to the command line, add an -ac [codec] option after each file that you want to choose the codec for, or at the beginning to make it apply to all files listed. To prioritize the codecs by default, list them in a line in mplayer.conf:
ac=[codec],[othercodec],vorbis,mad,
* [http://idjc.sourceforge.net/ IDJC] (Internet DJ Console) reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], (Ogg) FLAC, (Ogg) [[Vorbis]], MP2 (audio), [[MP3]], [[Opus]], but only the ''lowercase'' tags. There is a [https://sourceforge.net/p/idjc/bugs/100/ ticket] open to handle tags case-insensitively.
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.
* [https://www.videolan.org/vlc/ VLC] supports ReplayGain in many file formats, but usually only the ''uppercase'' variant of the tags.
* [https://kodi.tv/ KODI] reads ReplayGain from nearly all formats, but usually only the ''lowercase'' variant of the tags.

=== Portable devices ===
[http://www.rockbox.org/ Rockbox] supports ReplayGain (in album or track mode) for most formats, including WMA, MP1/2/3, AAC, ALAC, Musepack, Monkey's Audio, Wavpack, FLAC and Vorbis. Note that ReplayGain is only supported when using the respective codec's native tagging format. For example: ReplayGain stored in APEv2 tags is not supported for MP3, rather ID3v2.x tags are expected.

Sandisk Sansa Fuze with firmware 1.02.26 and 2.02.26

Sandisk Sansa Clip+

The iPod features ''Soundcheck'', which seems to produce roughly the same normalization gains as ReplayGain, but doesn't provide an Album Gain.

=== Hi-Fi ===
Slim Devices, a company owned by Logitech Inc, supports ReplayGain on both of their hi-end audiophile players, known as the [[Slim Devices Transporter|Transporter]] and the [[Slim Devices Squeezebox|Squeezebox]].

BluOS also supports ReplayGain with the selection of album- or track-gain and a so called Smart option that decides between the two by itself.
NAD devices that use BluOS consequently also support ReplayGain.

==Notes==
<references/>

== See also ==
* [[ReplayGain specification]]

== External links ==
* [http://en.wikipedia.org/wiki/Replay_Gain ReplayGain] at Wikipedia
* [http://www.bobulous.org.uk/misc/Replay-Gain.html ReplayGain using foobar2000] (how to use ReplayGain in Windows using foobar2000).
* [http://www.bobulous.org.uk/misc/Replay-Gain-in-Linux.html ReplayGain in Linux] (how to use ReplayGain in Linux using foobar2000 and Wine, or using metaflac or vorbisgain).

[[index.php?title=Category:Technical]]
[[index.php?title=Category:Metadata]]

Revised ReplayGain specification

2026-01-23T13:21:32Z

Case: /* De-Facto extensions */

''This is a proposed update to the [[ReplayGain 1.0 specification|original ReplayGain specification]]. This proposal is currently '''Under Construction'''. Please discuss this proposal on the [[Talk:ReplayGain 2.0 specification|discussion page]] or the [https://hydrogenaudio.org/index.php/topic,129032.0.html dedicated thread on Hydrogenaudio].'' --[[User:Skamp|Skamp]] 22:10 CET, January 22, 2026

Although music is encoded to a digital format with a clearly defined maximum peak amplitude, and although most recordings are normalized to utilize this peak amplitude, not all recordings sound equally loud. This is because once this peak amplitude is reached, perceived loudness can be further increased through signal-processing techniques such as dynamic range compression and equalization.<ref>Source: Wikipedia - [http://en.wikipedia.org/wiki/Loudness_war Loudness war]</ref> Therefore, the loudness of a given album has more to do with the year of issue or the whim of the producer than the intended emotional effect. Because of this, a random play through a music collection can have one leaping for the volume control every other track.

There is a solution to this annoyance: within each audio file, information can be stored about what volume change would be required to play each track or album at a standard loudness, and players can use this "replay gain" information to automatically nudge the volume up or down as required.

The ReplayGain specification is a standard which defines an appropriate reference level, explains a way of calculating and representing the ideal replay gain for a given track or album, and provides guidance for players to make the required volume adjustment during playback. The standard also specifies a means to prevent clipping when the calculated replay gain exceeds the limits of digital audio, and it describes how the replay gain information is stored within audio files.

==Loudness measurement==
Loudness is a subjective measure of the intensity of sound. The correlation of perceived loudness to sound pressure level is determined by the peculiarities of the auditory system.

The [[ReplayGain 1.0 specification|original ReplayGain specification]] described a loudness measurement system which included a weighting filter, root mean square (RMS) measurement and statistical processing that model human perception of loudness in both the frequency and time domains.

Since original ReplayGain proposal in 2001, the science, practice and standards for loudness normalization have been advanced significantly. The current industry standard approach to loudness measurement is described by the International Telecommunications Union<ref>http://www.itu.int/en/Pages/default.aspx</ref> (ITU) as BS.1770. The most recent version of this standard is known as ITU BS.1770-5<ref>https://www.itu.int/rec/R-REC-BS.1770-5-202311-I/en</ref> and was published in December 2023. The ITU work is freely available and is not believed to be encumbered by any patent issues. The ITU BS.1770-2 standard has been adopted in the United States by the [http://www.atsc.org ATSC] as [http://www.atsc.org/cms/standards/a_85-2011a.pdf A/85] and in Europe by the [http://www.ebu.ch European Broadcast Union] as [http://tech.ebu.ch/docs/tech/tech3343.pdf EBU R-128] for broadcast audio.

BS.1770 uses a "K-weighted" RMS measurement. This weighting function is significantly less complex than the inverted Fletcher-Munson weighting used by the original ReplayGain algorithm. A gating function designed measure the loudness of foreground components in the audio program. The gate in BS.1770 performs a similar function as the statistical processing in the original RG specification.

The computation required for BS.1770 loudness measurement is reduced compared to the original RG technique. Nevertheless, BS.1770 has been shown in several academic studies to be equally or more effective than the RG algorithm in modeling human loudness perception on music program as well as other material such as podcasts, television programs and movies.<ref>Paul Nygren. [http://www.speech.kth.se/prod/publications/files/3319.pdf Achieving equal loudness between audio files]. KTH Royal Institute of Technology</ref><ref>Martin Wolters; Harald Mundt; Jeffrey Riedmiller (May 2010). [http://www.aes.org/e-lib/browse.cfm?elib=15341 Loudness Normalization In The Age Of Portable Media Players]. Audio Engineering Society.</ref><ref>Esben Skovenborg; Søren H. Nielsen (October 2004). [http://web.archive.org/web/20120208024743/http://www.tcelectronic.com/media/skovenborg_2004_loudness_m.pdf Evaluation of Different Loudness Models with Music and Speech Material]. Audio Engineering Society. Archived from [http://www.tcelectronic.com/media/skovenborg_2004_loudness_m.pdf the original] on 2012-02-08.</ref>

Recent RG implementations use BS.1770 for loudness measurement. It is expected the ITU standard will evolve over time to meet the needs of broadcasters and governments. It is the intent of the ReplayGain community that RG follow any future backwards-compatible improvements to loudness measurement using the BS.1770 standard.

==Reference level==

Classic ReplayGain is calibrated to a pink noise reference signal with a RMS level 14 dB below a full-scale sinusoid. This reference signal is used to establish a reference level. ReplayGain will apply no gain or attenuation to the reference signal or any program material which has the same loudness measurements as the reference signal.

BS-1770 defines a loudness scale for program material. The units of BS.1770 loudness measurements are in Loudness Units [relative to] Full Scale (LUFS). LUFS can be treated like decibels.

In order to maintain backwards compatibility with classic RG, newer RG uses a -18 LUFS reference, which based on lots of music, can give similar loudness compared to classic RG.


==Gain calculation==
RG achieves loudness compensated playback by applying gain (or attenuation) dependent on the measured loudness of the audio file relative to the established reference level. The gain is calculated as follows:
:<math>RG=L_{r}-L</math>
Where:
:<math>RG</math> is the replay gain adjustment in decibels,
:<math>L_{r}</math> is the -18 LUFS reference level
:<math>L</math> is the measured loudness of the audio file in LUFS.

Gain is positive if the loudness of the audio file is lower than the reference level. The gain is negative (representing an attenuation) if the loudness of the audio file is higher than the reference level. The gain is stored as metadata with the audio file as described below and is used by players to adjust output volume of tracks as they are played as described in [[ReplayGain 2.0 specification#Player requirements|Player requirements]] below.

==Metadata==
For ReplayGain to do its work during playback, four values must be stored as metadata<ref>Metadata is "data about data." For example, the ID3 ''de facto'' standard provides a way to store artist, title, album title, track number, and other metadata in data blocks called "tags" immediately before or after the audio data in an MP3 file. Other metadata storage/tagging standards and conventions exist for other audio file formats.</ref> with or within the audio file:
# Peak track amplitude
# Peak album amplitude
# Track replay gain
# Album replay gain

If calculated for an individual track, the loudness measurement (as specified above) yields track replay gain. If calculated on an album basis, with all tracks concatenated to make one long audio file, the loudness measurement yields album replay gain.

===Replay gain===
Under some listening conditions, it's useful to have every track sound equally loud. The problem with a track-by-track approach is that tracks which should be quiet in the context of the album on which they reside will be brought up to the level of all the rest. For casual listening, or in a noisy background, this can be a good thing. For serious listening, it does not respect the intent of the artist or mastering engineer; a tender ballad track will be blasting at the same loudness as a hard rock track on the same album. It's generally ideal to leave the intentional loudness differences between tracks in place, yet still correct for unmusical and annoying loudness differences between albums. To accomplish this, ReplayGain suggests that two different gain adjustments should be stored as metadata with each sound file.

''Album replay gain'' represents the ideal listening gain for an entire album. ReplayGain reads the collection of tracks that comprise an album, and calculates a single replay gain for the whole set. This single gain can be used for playback of all tracks of the album. Intentionally quiet tracks then stay appropriately quieter than the rest. It still solves the basic problem (annoying, unwanted level differences between discs) because quiet or loud discs are still adjusted overall—so the pop CD that's 20 dB louder than the classical CD will be brought into line.

===Peak amplitude===
Scanning a track or album for the peak amplitude can be a time-consuming process. Therefore, it's helpful if this single value is stored as metadata. This is used to predict whether the required replay gain adjustment will cause clipping during playback.

The maximum peak amplitude value is stored as a floating point number, where 1.0 represents digital full scale. As with replay gain values, separate peak amplitude values are stored per track and per album.

For uncompressed files simply, scanners store the maximum absolute sample value held in the file on any channel for positive or negative excursion. The single sample value should be converted to a floating-point representation, such that digital full scale is equivalent to a value of 1.0.

Psychoacoustically coded audio, such as MP3, does not exist as a sequence of samples until it is decoded. Psychoacoustic coding of a heavily limited file can lead to sample values larger than digital full scale upon decoding. The coded files must be decoded using a fully compliant decoder that allows peak overflows (i.e. has headroom) and may result in peak amplitude values greater than 1.0.

==Metadata format==
From the standpoint of metadata storage, each audio file format presents a unique situation. There are three favored schemes defined for storage of ReplayGain metadata: '''ID3v2''', '''Vorbis comments''' and '''APEv2'''. A survey of file formats is listed below with metadata schemes in order of preference for each:
* .aac (Advanced Audio Coding raw format) – No metadata support (use .mp4 instead)
* .aiff, .aif, .aifc (Apple Interchange File Format) – '''ID3v2''' (in "ID3" IFF chunk)
* .ape, .apl (Monkey's Audio) – '''APEv2'''
* .bwf (Broadcast Wave Format) – '''ID3v2''' (in RIFF chunk)
* .flac (Free Lossless Audio Codec) – '''Vorbis comments'''
* .mp3 (MPEG audio layer 3) – '''ID3v2''', LAME VBR proposed tag specification
* .mp4 also .m4a, .m4b, .m4p, m4r (MPEG-4 Part 14) – '''ID3v2''' (in "ID32" box)
* .mpc (Musepack) – '''APEv2'''
* .ogg (Ogg Vorbis) – '''Vorbis comments''', same for other Ogg codecs
* .opus (Ogg Opus) – '''Vorbis comments''' available
** standard {{code|R128_TRACK_GAIN}} and {{code|R128_ALBUM_GAIN}} (MUST adjust for -23 LUFS) comment keys may be preferable (used by {{code|loudgain}})
* .tta (True Audio) – '''ID3v2''', '''APEv2'''
* .asf, .wma (Windows Media audio) - '''Vorbis comments''' in Extended Content Description Object
** {{code|loudgain}} instead uses native ASF/WMA attributes (itself a key-value storage) via TagLib, which is more sensible
* .wav (Windows PCM) – No metadata support (use .bwf instead)
** ID3 RIFF chunk possible (used by {{code|loudgain}})
* .wv (WavePak) – '''APEv2'''

===ID3v2===
The ID3v2 standard<ref>The ID3v2 format is explained at [http://www.id3.org/ www.id3.org]. The most useful document is the [http://www.id3.org/id3v2.3.0.html ID3v2 v2.3.0 standard]. Although this document has been superseded by v2.4.0, the earlier document is complete (rather than an update), and in indexed HTML form. As such, it represents a better technical introduction to ID3v2.</ref> defines a ''tag'' which is situated before the data in an MP3 file.<ref>The original ID3 (v1) tags resided at the end of the file, and contained a few fields of information. The ID3v1 tag is not extensible and therefore cannot support ReplayGain metadata.</ref> ID3 is used primarily with MP3 audio files but means of adapting the system to other file types have been developed.

The ID3v2 tag is divided into ''frames''. The preferred means of storing ReplayGain metadata is use of ''TXXX'' key/value pair frames. Two other legacy schemes for storing ReplayGain metadata exist: [[ReplayGain legacy metadata formats#ID3v2 RGAD|RGAD]] and [[ReplayGain legacy metadata formats#ID3v2 RVA2|RVA2]]. These formats are documented in the [[ReplayGain legacy metadata formats|appendix]]. Players may choose to look for these formats if metadata in the ''TXXX'' format is not found in the ID3v2 tag. New scanners may write these older formats in addition to the newer (TXXX) ones if they wish to remain backwards compatible with older players.

ReplayGain uses four TXXX frames. The header of a TXXX frame is coded as follows:

Frame ID $54 58 58 58 ("TXXX")
Size $xx xx xx xx (size of frame excluding this header)
Flags $40 $00 (discard frame if audio data is altered)

Frame data is coded as follows:

Text encoding $00 (ISO-8859-1 encoding)
Description <key string> $00
Value <value string>

The four frames associated with ReplayGain metadata use the following key/value pairs

{| class="wikitable"
|+Table 3: Metadata keys and value formatting
|-
!Metadata
!Key
!Value format
|-
|Track replay gain
|REPLAYGAIN_TRACK_GAIN
|[-]a.bb dB
|-
|Peak track amplitude
|REPLAYGAIN_TRACK_PEAK
|c.dddddd
|-
|Album replay gain
|REPLAYGAIN_ALBUM_GAIN
|[-]a.bb dB
|-
|Peak album amplitude
|REPLAYGAIN_ALBUM_PEAK
|c.dddddd
|}

Gains are specified textually in decibels. Negative gains (attenuation) are prefixed with a '-'. Positive gains have no prefix. Integral portion of the gain (a) may be one or two numeric (0-9) digits. If there is no integral portion the field is '0'. The decimal portion of the gain (bb) is two numeric digits. Gains are suffixed with a space followed by 'dB'.

Peak levels are specified textually as a positive decimal. Peak level is a dimensionless quantity with 1.000000 representing full scale. No suffix is included on peak values. The integer field (c) is typically 1 or 0. Six numeric digits in the decimal field (dddddd) is adequate to accurately represent peak values for 16-bit audio data.

A robust player should be prepared to parse the following variations in either replay gain or peak level metadata:
*Positive gains with leading '+'
*More or fewer significant digits than specified in any field
*Leading zeros or spaces in integer fields
*Missing or malformed 'dB' suffix (e.g. no space between numeric digits and suffix, alternate capitalization)
*Alternate capitalization of keys

Other formatting errors indicate more severe problems and should result in player ignoring data as if the frame did not exist.

===Vorbis comments===
A Vorbis comment<ref>[http://www.xiph.org/vorbis/doc/v-comment.html Vorbis comment metadata format]. ReplayGain metadata is documented on the [http://wiki.xiph.org/VorbisComment#Replay_Gain Xiph Wiki].</ref> uses an ASCII <tt>key=value</tt> format. When Vorbis comments are used, the four ReplayGain metadata items are stored as separate comments. The ''keys'' and formatting for ''values'' is the same as specified for ID3v2. Keys and values are required by the Vorbis comment specification to b separated by '=' (equal character).

===APEv2===
The APEv2 metadata format<ref>[http://wiki.hydrogenaudio.org/index.php?title=APEv2_specification APEv2 Specification at Hydrogen Audio Wiki]</ref> also organizes data into key/value pairs. Keys are ASCII format. A flags field allows support for several value formats including UTF-8 and binary. Under APEv2, ReplayGain meta data is stored using the same keys and data as ASCII values in the same format as specified for ID3v2.

===De-Facto extensions===
MusicBrainz Picard and [http://github.com/Moonbase59/loudgain#tags-written-andor-deleted LoudGain] also support the following additional tags, named using the same conventions:

{| class="wikitable"
|+Extension metadata keys
|-
!Metadata
!Key
!Value format
!Purpose
|-
|Track range
|REPLAYGAIN_TRACK_RANGE
|[-]a.bb dB
|rowspan=2 | Indicates dynamics (R-128 Loudness Range / LRA), may guide pre-amplification
|-
|Album range
|REPLAYGAIN_ALBUM_RANGE
|[-]a.bb dB
|-
|Reference loudness
|REPLAYGAIN_REFERENCE_LOUDNESS
|[-]a.bb LUFS
| Use alternative reference levels; change ref levels without re-scanning the file
(note: this field is harmful. The standard has only one reference level. The effective playback level is changed in player and does not require any form of rescanning.)
|}

==== Proposed extension(s) ====

{| class="wikitable"
|+Extension metadata keys
|-
!Metadata
!Key
!Value format
!Purpose
|-
|Algorithm
|REPLAYGAIN_ALGORITHM
|ITU-R BS.1770
|Method to produce values
|}

==Player requirements==
[[File:RG_Player_control.gif‎|frame|Figure 8: Example ReplayGain control panel]]

Loudness normalization, pre-amplification and clipping prevention are the operations performed by a ReplayGain player.

===Loudness normalization===
To properly normalize loudness, the player needs to determine if the user desires Track style level normalization (all tracks same loudness), or Album style level normalization (all albums same loudness, tracks of an album played at the same relative level as on the original release). This option should be selectable in the ReplayGain control panel (Figure 8). The player reads the corresponding gain metadata value from the file and scales the audio data as appropriate. Scaling the audio data simply means multiplying each sample value by a constant value. This constant is given by:

:<math>10^\frac{gain}{20}</math>

Or, in words, replay gain divided by 20 all raised to the power of ten.<ref>After any such operation, it's a good idea to dither the result. If this calculation and the pre-amp are implemented separately, then dither should only be added to the final result, just before the result is truncated back to 16 bits, or 24, or 8, as limited by the soundcard—not the file (i.e. after ReplayGain adjustment, an 8-bit file should be sent to a 16-bit soundcard at 16-bits).</ref>

If the file only contains one of the replay gain adjustments (e.g. Album) but the user has requested the other (Track), then the player should use the one that is available (in this case, Album). If neither (Track or Album) gain metadata is available, then the player needs to choose a suitable default gain. Potential choices include unity gain (0 dB) or an average of gains from other tracks in the album or playlist.

===Pre-amplification===
Although the calibration level used by ReplayGain suggests that the average level of an audio track should be 14 dB below full scale, some pop music is dynamically compressed to peak at 0 dB and average around 3 dB below full scale. This means that, when the replay gain is applied, the level of such tracks will be reduced by 11 dB! If users are listening to a mixture of highly compressed and more dynamic tracks, ReplayGain will make the listening experience more pleasurable by bringing the level of the compressed tracks down into line with that of the others. However, if users are only listening to highly compressed music, then they may complain that all their files are now too quiet.<ref>This problem can be especially noticeable on portable players with limited output or gain.</ref>

To address this problem, a pre-amp feature should be incorporated into the player. A user-supplied pre-amp setting is an adjustment to the calculated replay gain. It should default to perform no adjustment. This means that casual users will experience a moderate reduction in the loudness of their compressed pop music. Less-compressed material can generally be played at the same loudness without clipping. Normalization of more dynamic material may cause clipping or invoke the [[ReplayGain 2.0 specification#Clipping prevention|clipping prevention]] mechanism (see below). Power users and audiophiles can reduce the pre-amp gain to enjoy the full dynamic range of all of their music.

If enabled, the player should read the user selected pre-amp gain, and scale the audio signal by the appropriate amount. For example, a +6 dB gain requires a scale of 106/20, which is approximately 2. The replay gain and pre-amp scale factors can be combined<ref>Scale factors in Decibel units are added to produce the same effect as multiplying scale factors in linear units.</ref> for simplicity and ease of processing.

===Clipping prevention===
ReplayGain's suggestion of a -14 dB average playback level leaves sufficient headroom for the bulk of modern recordings. Nevertheless, there exists the possibility that after application of replay gain and pre-amp adjustment, a track may exceed full scale during its dynamic peaks. Without intervention, this will result in clipping, a severe form of distortion. Factors introducing the possibility of clipping include:

# Recordings from certain genres and certain periods in the history of commercial recordings require additional headroom. Although these recordings can be accommodated through a downwards adjustment of the pre-amp setting, it may be difficult to determine a safe adjustment and it may be undesirable to lower average level to accommodate the rare track which requires it.
# ReplayGain will make loud dynamically compressed tracks quieter, and quiet dynamically uncompressed tracks louder. The average levels will then be similar, but the quiet tracks will actually have louder peaks. If the user pushes the pre-amp gain upwards the peaks of the (originally) quieter tracks will be pushed well over full scale.
# In coded audio (e.g. MP3 files) a file that was hard-limited to digital full scale before encoding will often be pushed over the limit by the psychoacoustic compression. A decoder with headroom can recover the over full scale signal by reducing the gain.

ReplayGain suggests two possible solutions which prevent clipping in these situations. A player should support one or both of these.

====Audio limiting====
In situation 2 above, the user clearly wants all the music to sound very loud. To give them their wish, any signal which would peak above digital full scale should be hard limited at just below digital full scale. This is also useful at lower pre-amp gains, where it allows the average level of classical music to be raised to that of pop music, without distorting. The exact type of nature limiting or compression an implementation choice for the player.<ref>Something like the Hard Limiter found in Cool Edit Pro (Syntrillium) would be appropriate for pop music at least.</ref>

====Reduced gain====
The audiophile user will not want any compression or limiting on the signal. In this case the only option is to automatically and temporarily reduce the pre-amp gain below the user-selected setting for tracks where clipping would otherwise occur. Clipping can be predicted by examining the peak level of the track or album being played.

The player must read the peak amplitude metadata. If peak level metadata is unavailable, the player should assume a peak level of 1.0. If the peak level for both track and album is stored as metadata in the file, it is possible to calculate if, following the replay gain adjustment and pre-amp gain, the signal will clip at some point. If it won't, then no further action is necessary.

An overall scale factor for loudness normalization taking into account replay gain, pre-amp setting and clipping prevention through gain reduction is given below.

:<math>min( 10^\frac{RG + G_{pre-amp}}{20}, \frac{1}{peak amplitude} )</math>


===Hardware implementation===
The above three steps are appropriate to software players operating on the digital signal in order to scale it. However, it is possible to send the digital signal to the DAC without level correction, and to place an attenuator in the analogue signal path. The attenuator can then be driven by the Replay Gain value. The clipping problem can be addressed by providing adequate headroom in the analog circuitry. Bit transparency and maximum signal to noise ratio is maintained in the digital signal and DAC process.<ref>A system using today's 24-bit converters is unlikely to appreciate any overall gain in system performance with such an arrangement. A digitally-controlled analog gain element typically introduces significant noise and distortion.</ref>

==Acknowledgements==
The [http://replaygain.hydrogenaudio.org/proposal original ReplayGain proposal] (an [http://replay.waybackmachine.org/20090306202649/http://www.replaygain.org/ archive] is also available) was developed by David Robinson and was published 10 July 2001. Additional updates were published by David Robinson through 10 October 2001.

The following acknowledgement was included with the original proposal, "The algorithm to calculate an ideal replay gain has grown from my research into human hearing, with many additional ideas drawn from the work of E. Zwicker, and Brian Moore. I am currently completing my PhD at the University of Essex, and have been funded by the EPSRC." Additionally David Robinson credited Glen Sawyer (Snelg) and Jim Casaburi (Walrus) for software contributions and Bob Katz and Matt Ashland for ideas.

This updated ReplayGain specification reflecting current and recommended practice was prepared by Kevin Gross in 2011.

==Contact==
For ReplayGain-related questions or contributions, please post in the [http://www.hydrogenaudio.org/forums/index.php?showforum=1 General Audio] section of the Hydrogen Audio forums.

==Appendix==
# [[ReplayGain legacy metadata formats]]

==Notes==
<references />

ReplayGain

2026-01-23T11:02:51Z

Case: /* Target loudness */

'''ReplayGain''' is the name of a technique invented to achieve the same perceived playback loudness of audio files. It defines an algorithm to measure the '''perceived''' loudness of audio data.

ReplayGain allows the loudness of each song within a collection of songs to be consistent. This is called 'Track Gain' (or 'Radio Gain' in earlier parlance). It also allows the loudness of a specific sub-collection (an "album") to be consistent with the rest of the collection, while allowing the dynamics from song to song on the album to remain intact. This is called 'Album Gain' (or 'Audiophile Gain' in earlier parlance). This is especially important when listening to classical music albums, because quiet tracks need to remain a certain degree quieter than the louder ones.

ReplayGain is different from [[Normalization|peak normalization]]. Peak normalization merely ensures that the peak amplitude reaches a certain level. This does not ensure equal loudness. The ReplayGain technique measures the ''effective power'' of the waveform (i.e. the RMS power after applying an "equal loudness contour"), and then adjusts the amplitude of the waveform accordingly. The result is that Replay Gained waveforms are usually more uniformly amplified than peak-normalized waveforms.

==Target loudness==
The target loudness of ReplayGain is [https://wiki.hydrogenaudio.org/index.php?title=Original_ReplayGain_specification#Reference_level '''89''' '''dB SPL'''] / '''-18''' '''[https://en.wikipedia.org/wiki/LUFS LUFS]''' (''Loudness Units relative to Full Scale'').

Some utilities have realized the inadequacies of the classic ReplayGain loudness calculation, switching to a more modern algorithm ([https://www.itu.int/rec/R-REC-BS.1770-5-202311-I/en ITU-R BS.1770]). However, the way it was integrated was extremely ''ad hoc'', at least until a draft of a [[ReplayGain 2.0 specification|revised specification]] started being written.

==Clipping==
Audio is generally recorded such that the loudest sounds don't clip, but the use of ReplayGain can cause clipping if the average volume of a song is below the target level. That is, upon playback, the volume of a quiet song is increased, so the parts of the song with above-average loudness, especially in the bass frequencies, will exceed the limits of the format and will be distorted. Whether this distortion is audible depends on the sounds in question, and the listener's sensitivity.

Implementations deal with the risk of clipping in different ways. Some have a "pre-amp" feature which reduces (or boosts) the original audio's level by a certain amount before doing whatever is needed for ReplayGain. Some have a "prevent clipping" feature to reduce the amount of ReplayGain adjustment to whatever amount would keep clipping from occurring, based on peak info stored in the file's metadata (thus reducing the effectiveness of ReplayGain). Some recommend using a compressor/limiter DSP to prevent or reduce clipping, regardless of whether it was caused by ReplayGain.

An alternative that may reduce the risk of clipping is the [https://tech.ebu.ch/docs/r/r128.pdf EBU R 128] recommendation of a -23 LUFS target, but that's a different standard, and some may find the additional reduction in volume excessive, particularly if it leads to maxing out volume on user hardware. [[Opus]] in particular has adopted that standard, using a global gain as well as <code>R128_TRACK_GAIN</code> / <code>R128_ALBUM_GAIN</code> tags. With ReplayGain, a simple (though somewhat radical) solution is to lower the preamp value by 5 dB (or whatever one feels comfortable with) in the playback software. The RG target will always be -18 LUFS, regardless of a user's volume or preamp settings.

== Implementations ==
There are different ReplayGain implementations, each with its own uses and strength. Most use [[metadata]] to indicate the level of the volume change that the player should make. Some modify the audio data itself, and optionally use metadata as well. There are advantages and disadvantages to both methods.

In the metadata method, information on both types of ReplayGain (Track Gain and Album Gain) can be stored. The volume-change information can be very precise. If audio data was also changed, the metadata can contain "undo" info. Not all audio players/decoders know how to read and use ReplayGain information stored in metadata. And there's no standard for where and how ReplayGain info is stored; each implementation uses different formats and puts the info in different locations.

In the audio data method, the file's actual audio data is modified so that its natural/default playback volume is at the target level. In this scenario, only one type of ReplayGain (Track Gain or Album Gain) can be applied. If no "undo" info is saved somewhere, it may not be possible to restore the original audio data. Limitations of the audio file format may prevent precise (finely tuned) gain adjustments with this method. For example, MP3 and AAC files can only be losslessly modified in 1.5 dB steps. Depending on the audio file format, the process may also be lossy in the sense that it could irreversibly push a signal above the format's maximum amplitude (resulting in clipping) or below the minimum (resulting in silence).

=== Old versus new algorithms ===
Since the ReplayGain standard does not define tags to specify which algorithm was used (classic or ITU-R BS.1770) or what target was set (RG's -18 LUFS, EBU R 128's -23 LUFS, or any other target set by the user or some piece of software), there may be confusion as to how the results were produced. Typically, utilities that ship with reference encoders (FLAC / metaflac, Vorbis / vorbisgain, WavPack / wvgain, Musepack / mpcgain…) use the original RG algorithm, which can produce values that differ from newer tools by several decibels in certain cases. Generally speaking, it is recommended to run other utilities or players that implement the ITU-R BS.1770 algorithm, although it may not be obvious which algorithm they use at first glance. Their documentation may provide that information.

==== RG1, RG2 ====
Although there are many references online, and within ReplayGain scanners, about version 1 vs. version 2 of the ReplayGain standard, at the time of writing this, there is (admittedly) only one ReplayGain standard. The core principle, as well as the 4 tags from the original specification, have not changed. More tags have been proposed but they are still subject to debate. As a rule of thumb, tools that advertise "ReplayGain 2" compliance employ the newer, more accurate ITU-R BS.1770 algorithm. [[foobar2000]] labels it "EBU R128" but it essentially means the same thing. Should a better algorithm be developed in the future, it will still work towards fulfilling ReplayGain's original goals, and probably write the same tags.

=== MP3Gain ===
[[MP3Gain]] is an implementation of classic ReplayGain. It can be used to just analyze files & recommend changes or to also modify the gain. If modifying the gain, it always modifies the global gain fields in the MP3 audio data. It can add somewhat precise metadata, including undo info. The gain can be modified to any target dB, or it can be changed by a specified amount. For balance correction, user-specified changes can even be made on just one channel in simple L/R stereo-mode files (not joint stereo).

* Format: [[MP3]]
* Method: Audio + Meta (in APE tag), or Audio only
* APE tag fields (ASCII bytes):
** <code>MP3GAIN_MINMAX ###,###</code> - minimum & maximum global gain values for this file. 3 digits, zero-padded if necessary.
** <code>MP3GAIN_ALBUM_MINMAX ###,###</code> - minimum & maximum global gain values across a set of files scanned as an album. Optional.
** <code>MP3GAIN_UNDO +###,+###,N</code> - the global gain adjustment to restore the original values in the left and right channels, respectively, followed by an indicator of whether to wrap at the extremes (<code>N</code> means no, <code>W</code> means yes). The adjustment values are 3 digits, zero-padded, preceded by a sign (<code>+</code> or <code>-</code>).
** <code>REPLAYGAIN_TRACK_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Examples: <code>+0.424046</code> and <code>-10.38500</code>
** <code>REPLAYGAIN_TRACK_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Example: <code>0.149923</code>
** <code>REPLAYGAIN_ALBUM_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Optional.
** <code>REPLAYGAIN_ALBUM_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Optional.
* Limitations: Although the metadata, if written, contains precise adjustment & peak values, the audio data modifications are limited to 1.5dB steps and may become irreversible (however, that's a very rare condition; see the [https://hydrogenaud.io/index.php/topic,34154.0.html "mp3gain is NOT lossless" forum thread])
* http://mp3gain.sourceforge.net/

=== AACGain ===
[[AACGain]] is a modified version of MP3Gain that works on both MP3 and AAC files.

* Format: [[MP3]], [[AAC]] (with or without MP4 container)
* Method: Audio + Meta, or Audio only
* Limitations: Limited to 1.5dB steps mode, may become irreversible (same caveat as for MP3Gain)
* http://aacgain.altosdesign.com/

=== [[LAME]] ===
* Method: Header ([http://gabriel.mp3-tech.org/mp3infotag.html mp3infotag])
* Notes:
** Uses the classic RG algorithm.
** Tags added during encoding; not supported by any player yet; Track Gain only
** Replay Gaining MP3's is usually done using MP3Gain (see [[ReplayGain#MP3Gain|above]]) or [[ReplayGain#foobar2000 ReplayGain scanner|foobar2000]]
* http://lame.sourceforge.net/

=== [[Musepack]] ReplayGain ===
* Method: Header (similar to Meta data method)
* Notes: Uses the classic RG algorithm. ReplayGain values are stored in the header and ReplayGain is part of the Musepack specifications; therefore any Musepack decoder that does not support ReplayGain can be considered broken.
* http://www.musepack.net/

=== VorbisGain ===
* Format: (Ogg) [[Vorbis]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://www.sjeng.org/vorbisgain.html
** new compiles of VorbisGain at [http://www.rarewares.org/ogg.html www.rarewares.org]
:'''''Note:''' Andavari has provided a very useful script to integrate VorbisGain, which is a CLI tool, into Windows Explorer. Please (Ogg) [[Vorbis#ReplayGain|check this section]].''

=== FLAC / METAFLAC ===
* Format: [[Free Lossless Audio Codec|FLAC]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://flac.sf.net

=== WavPack / WVGAIN ===
* Format: [[WavPack]]
* Method: Meta (in [[APEv2]] tag)
* Uses the classic RG algorithm.
* http://www.wavpack.com

=== Wavegain ===
* Format: waveform
* Method: Audio
* Uses the classic RG algorithm.
* Limitations: Irreversible
* http://www.rarewares.org/others.php#wavegain

=== MusicPlayer ===
* Custom implementation, inspired by MP3Gain.
* Format: any that FFmpeg supports
* Method: Audio
* Limitations: Doesn't modify the files at all. Stores the value in own database. Used only for playback.
* https://github.com/albertz/music-player

=== [[foobar2000]] ReplayGain scanner ===
* Since v1.1.6, defaults to ITU-R BS.1770 analysis (although it labels it EBU R128), but can be configured to use the "Classic ReplayGain" algorithm instead. The ITU-R BS.1770 implementation uses a reference level of -18 LUFS instead of -23, in order to retain compatibility with the ReplayGain standard.
* Format:
** [[MP3]]: Values written to [[ID3v2]] (default) or [[APEv2]] tags.
** [[Musepack]]: Values written to header.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]] and/or file header.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags
** [[MP4]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain).
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[TAK]]: Values written to [[APEv2]] tags.
** [[TTA]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** [[WMA]]: Values written to WMA tags.
** [[WAV]]: Values written to ID3 chunk.
** [[AIFF]]: Values written to ID3 chunk.
** Modules ([[MOD]] etc.): Optionally saved into [[APEv2]] tags.
** Any non-taggable format or format supported by FFmpeg can store RG values in a database or external tag with a component.
** A separate function can be invoked to apply the tagged Track or Album Gain to the global gain fields in MP3, MP4 (AAC), or Opus files, and rewrite any existing tags to account for the peak change and compensate for the difference from 89 dB. The 89 dB reference level for tags isn't configurable, but the reference level applied to the global gain fields is.
** Can automatically copy Track or Album gain values to Apple's SoundCheck tag in MP4 files or any format that supports ID3v2 to effectively add ReplayGain support to Apple's players.
* https://foobar2000.org/

=== [[MediaMonkey]] ===
* Format:
** [[MP3]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in MediaMonkey's MDB database.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[WAV]]: Values stored in MediaMonkey's MDB database.
** [[MPC]]: Internal gain Structure.
* In addition to tags, all ReplayGain values are also stored in MediaMonkey's MDB database
* Album/Audiophile ReplayGain not supported until v3.0 (Dec 2007); support during burning & ripping added in 3.1 (Jun 2009)
* Also capable of (irreversibly) changing the volume of MP3 tracks, similar to [[MP3Gain]]
* http://www.mediamonkey.com/

=== [[Winamp]] ReplayGain scanner===
* Format:
** [[MP3]]: Values written to [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in Windows Media Audio tags.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags.
** [[MP4]]
** [[TAK]]: Values written to [[APEv2]] tags.
* Support Album/Track Gain

=== [[loudgain]] ===
* Format:
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** MP2, [[MP3]]: Values written to [[ID3v2]] tags (ID3v2.3/ID3v2.4 selectable).
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** (Ogg) [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** (Ogg) [[Speex]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]], based on -23 LUFS Opus standard. Only <code>R128_TRACK_GAIN</code> and <code>R128_ALBUM_GAIN</code> are written, but the calculated ''true peak'' value can still be used to reduce the gain values ([[Clipping]] prevention).
** [[MP4]], [[M4A]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain). ReplayGain values are stored under <code>----:com.apple.iTunes:…</code>. This is for [[AAC]] and [[ALAC]] in [[MPEG-4]] containers.
** [[ASF]], [[Windows Media Audio|WMA]]: Values written to WMA tags, no prefix.
** [[WAV]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] (ID3v2.3/ID3v2.4 selectable) format. Using the <code>bext</code> chunk (for BWF v2) isn’t (yet) supported, but won’t be destroyed on writing.
** [[Audio Interchange File Format|AIFF]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] format.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[Monkey's Audio]] (APE): Values written to [[APEv2]] tags.
* Follows EBU R128, ITU BS.1770 and the [[ReplayGain 2.0 specification|revised ReplayGain specification]].
* ''Never'' touches the actual audio data but ''only writes RG2 tags''.
* Uses ''true peak'' values calculated by oversampling to 192 kHz, using a custom polyphase FIR interpolator that will oversample 4x for sample rates < 96 kHz, 2x for sample rates < 192 kHz and leave the signal unchanged for 192 kHz.
* ''Clipping prevention'' can be used to lower the ReplayGain values to a safe margin (default -1 dBTP, can be changed).
* Many options for special cases: force RG tags upper-/lowercase, add extra tags (LRA, Reference loudness), strip unwanted tag types (APEv2 from MP2/MP3, ID3 from WavPack), tab-delimited table output for analysis with CSV file.
* ''Linux'' Free and Open Source software, can be installed on ''MacOS'' using ''HomeBrew'', on ''Windows 10'' using the Linux ''bash''.
* Also installs a <code>rgbpm</code> bash script for mass-tagging, which can be adapted to the user’s needs.
* '''Warning:''' Loudgain relies on standard libraries like ''TagLib''. Linux distros (except rolling releases) sometimes deliver outdated libraries, so be sure you use the latest version of ''TagLib''. Version 1.11.1 had a nasty bug for a while that [https://hydrogenaud.io/index.php/topic,118085.msg974957.html#msg974957 could corrupt Ogg Vorbis files]. This has been fixed in the meantime but the TagLib version not updated. Loudgain comes with a (slower) static version called <code>loudgain.static</code> in the repo’s <code>/bin</code> folder that doesn’t expose the bug and can also be used on older Linux versions (like Ubuntu 14.04, Linux Mint 17).
* https://github.com/Moonbase59/loudgain
* Bug tracker: https://github.com/Moonbase59/loudgain/issues

=== [[rsgain]] ===
rsgain is a newer ReplayGain command line utility designed with a "batteries included" philosophy, use the newer ITU-R BS.1770 algorithm.

Features:
* Cross-platform Windows / macOS / Linux
* Supports all popular audio formats
* Simplified "Easy Mode" command line syntax supports recursive, directory-based scanning
* Multithreaded scanning option that provides significant speed improvement with full library scans
* Option to skip files with existing ReplayGain metadata
* Scan presets allow the user to save advanced settings for consistent use

== Players support ==
ReplayGain being present in the specs of the FLAC, Musepack, and APE formats, any player that support those formats usually supports ReplayGain.

The situation with MP3 is rather different, as it was not part of the MP3 specs. The APEv2 tags metadata implementation is somewhat becoming the de-facto standard.

=== Windows ===
* [[foobar2000]] supports ReplayGain in all possible aspects.
* [[Winamp]] supports ReplayGain in album or track mode.
* [[MediaMonkey]] supports ReplayGain, with many configuration options.
* [[XMPlay]] recently implemented ReplayGain
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.

''...and probably others.''

=== Linux ===
* [[XMMS]]. Reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], [[Musepack]], (Ogg) [[Vorbis]] ..
:For [[MP3]], use the CVS version of the [http://xmms-mad.sourceforge.net/ xmms-mad] mp3 plugin (it's not yet released as binary, furthermore not available in distribs' versions for now. Meanwhile binaries are available here: [http://perso.crans.org/~krempp/xmms-mad/ custom binaries])
* [[amarok]]. By using the amarok-script [http://kde-apps.org/content/show.php?content=26073 ReplayGain]
:And possibly others, since [http://developer.kde.org/~wheeler/taglib.html TagLib] added support for [[APEv2]] tags in [[MP3]] files, players using this library (like [[amaroK]] and [[JuK]]) might support that kind of ReplayGain tags in the near future.
* [http://www.sacredchao.net/quodlibet Quod Libet] reads ReplayGain from (Ogg) [[Vorbis]], [[MP3]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:Requires support to be enabled (via the appropriate python bindings and libraries) for the above formats. Does not support ReplayGain values stored in [[APEv2]] tags in [[MP3]]s. ReplayGain values are stored in RVA2 id3v2.4 frames. See the [http://www.sacredchao.net/quodlibet/wiki/Development/ID3Notes Quod Libet RVA2 / ReplayGain notes].
* [http://www.musicpd.org/ Music Player Daemon] (MPD) reads ReplayGain from (Ogg) [[Vorbis]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:foobar2000-style TXXX frames in [[MP3]]s are also supported in the latest development releases.
* [http://www.mplayerhq.hu/ MPlayer]. Mplayer support for ReplayGain is codec dependent.
:Codecs that are known to support ReplayGain: vorbis
:Because of this, you need to prioritize the codecs that support it, or choose it individually on the command line. To add it to the command line, add an -ac [codec] option after each file that you want to choose the codec for, or at the beginning to make it apply to all files listed. To prioritize the codecs by default, list them in a line in mplayer.conf:
ac=[codec],[othercodec],vorbis,mad,
* [http://idjc.sourceforge.net/ IDJC] (Internet DJ Console) reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], (Ogg) FLAC, (Ogg) [[Vorbis]], MP2 (audio), [[MP3]], [[Opus]], but only the ''lowercase'' tags. There is a [https://sourceforge.net/p/idjc/bugs/100/ ticket] open to handle tags case-insensitively.
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.
* [https://www.videolan.org/vlc/ VLC] supports ReplayGain in many file formats, but usually only the ''uppercase'' variant of the tags.
* [https://kodi.tv/ KODI] reads ReplayGain from nearly all formats, but usually only the ''lowercase'' variant of the tags.

=== Portable devices ===
[http://www.rockbox.org/ Rockbox] supports ReplayGain (in album or track mode) for most formats, including WMA, MP1/2/3, AAC, ALAC, Musepack, Monkey's Audio, Wavpack, FLAC and Vorbis. Note that ReplayGain is only supported when using the respective codec's native tagging format. For example: ReplayGain stored in APEv2 tags is not supported for MP3, rather ID3v2.x tags are expected.

Sandisk Sansa Fuze with firmware 1.02.26 and 2.02.26

Sandisk Sansa Clip+

The iPod features ''Soundcheck'', which seems to produce roughly the same normalization gains as ReplayGain, but doesn't provide an Album Gain.

=== Hi-Fi ===
Slim Devices, a company owned by Logitech Inc, supports ReplayGain on both of their hi-end audiophile players, known as the [[Slim Devices Transporter|Transporter]] and the [[Slim Devices Squeezebox|Squeezebox]].

BluOS also supports ReplayGain with the selection of album- or track-gain and a so called Smart option that decides between the two by itself.
NAD devices that use BluOS consequently also support ReplayGain.

==Notes==
<references/>

== See also ==
* [[ReplayGain specification]]

== External links ==
* [http://en.wikipedia.org/wiki/Replay_Gain ReplayGain] at Wikipedia
* [http://www.bobulous.org.uk/misc/Replay-Gain.html ReplayGain using foobar2000] (how to use ReplayGain in Windows using foobar2000).
* [http://www.bobulous.org.uk/misc/Replay-Gain-in-Linux.html ReplayGain in Linux] (how to use ReplayGain in Linux using foobar2000 and Wine, or using metaflac or vorbisgain).

[[index.php?title=Category:Technical]]
[[index.php?title=Category:Metadata]]

ReplayGain

2026-01-23T10:25:15Z

Case: /* foobar2000 ReplayGain scanner */

'''ReplayGain''' is the name of a technique invented to achieve the same perceived playback loudness of audio files. It defines an algorithm to measure the '''perceived''' loudness of audio data.

ReplayGain allows the loudness of each song within a collection of songs to be consistent. This is called 'Track Gain' (or 'Radio Gain' in earlier parlance). It also allows the loudness of a specific sub-collection (an "album") to be consistent with the rest of the collection, while allowing the dynamics from song to song on the album to remain intact. This is called 'Album Gain' (or 'Audiophile Gain' in earlier parlance). This is especially important when listening to classical music albums, because quiet tracks need to remain a certain degree quieter than the louder ones.

ReplayGain is different from [[Normalization|peak normalization]]. Peak normalization merely ensures that the peak amplitude reaches a certain level. This does not ensure equal loudness. The ReplayGain technique measures the ''effective power'' of the waveform (i.e. the RMS power after applying an "equal loudness contour"), and then adjusts the amplitude of the waveform accordingly. The result is that Replay Gained waveforms are usually more uniformly amplified than peak-normalized waveforms.

==Target loudness==
The target loudness of all ReplayGain utilities is 89 dB SPL when replayed in an SMPTE RP 200 calibrated system (an early departure from the proposal, endorsed by its author<ref>[http://www.hydrogenaudio.org/forums/index.php?s=&showtopic=83397&view=findpost&p=721854 Does Replay gain work differtly in Media monkey]</ref>) — the ReplayGain proposal and SMPTE recommendation are 6 dB lower.<ref>[http://www.mars.org/mailman/public/mad-dev/2004-February/000993.html ReplayGain discussion at mad-dev]</ref> The target loudness may be more commonly known and understood as '''-18''' '''[https://en.wikipedia.org/wiki/LUFS LUFS]''' (''Loudness Units relative to Full Scale'').

Some utilities have realized the inadequacies of the classic ReplayGain loudness calculation, switching to a more modern algorithm ([https://www.itu.int/rec/R-REC-BS.1770-5-202311-I/en ITU-R BS.1770]). However, the way it was integrated was extremely ''ad hoc'', at least until a draft of a [[ReplayGain 2.0 specification|revised specification]] started being written.

==Clipping==
Audio is generally recorded such that the loudest sounds don't clip, but the use of ReplayGain can cause clipping if the average volume of a song is below the target level. That is, upon playback, the volume of a quiet song is increased, so the parts of the song with above-average loudness, especially in the bass frequencies, will exceed the limits of the format and will be distorted. Whether this distortion is audible depends on the sounds in question, and the listener's sensitivity.

Implementations deal with the risk of clipping in different ways. Some have a "pre-amp" feature which reduces (or boosts) the original audio's level by a certain amount before doing whatever is needed for ReplayGain. Some have a "prevent clipping" feature to reduce the amount of ReplayGain adjustment to whatever amount would keep clipping from occurring, based on peak info stored in the file's metadata (thus reducing the effectiveness of ReplayGain). Some recommend using a compressor/limiter DSP to prevent or reduce clipping, regardless of whether it was caused by ReplayGain.

An alternative that may reduce the risk of clipping is the [https://tech.ebu.ch/docs/r/r128.pdf EBU R 128] recommendation of a -23 LUFS target, but that's a different standard, and some may find the additional reduction in volume excessive, particularly if it leads to maxing out volume on user hardware. [[Opus]] in particular has adopted that standard, using a global gain as well as <code>R128_TRACK_GAIN</code> / <code>R128_ALBUM_GAIN</code> tags. With ReplayGain, a simple (though somewhat radical) solution is to lower the preamp value by 5 dB (or whatever one feels comfortable with) in the playback software. The RG target will always be -18 LUFS, regardless of a user's volume or preamp settings.

== Implementations ==
There are different ReplayGain implementations, each with its own uses and strength. Most use [[metadata]] to indicate the level of the volume change that the player should make. Some modify the audio data itself, and optionally use metadata as well. There are advantages and disadvantages to both methods.

In the metadata method, information on both types of ReplayGain (Track Gain and Album Gain) can be stored. The volume-change information can be very precise. If audio data was also changed, the metadata can contain "undo" info. Not all audio players/decoders know how to read and use ReplayGain information stored in metadata. And there's no standard for where and how ReplayGain info is stored; each implementation uses different formats and puts the info in different locations.

In the audio data method, the file's actual audio data is modified so that its natural/default playback volume is at the target level. In this scenario, only one type of ReplayGain (Track Gain or Album Gain) can be applied. If no "undo" info is saved somewhere, it may not be possible to restore the original audio data. Limitations of the audio file format may prevent precise (finely tuned) gain adjustments with this method. For example, MP3 and AAC files can only be losslessly modified in 1.5 dB steps. Depending on the audio file format, the process may also be lossy in the sense that it could irreversibly push a signal above the format's maximum amplitude (resulting in clipping) or below the minimum (resulting in silence).

=== Old versus new algorithms ===
Since the ReplayGain standard does not define tags to specify which algorithm was used (classic or ITU-R BS.1770) or what target was set (RG's -18 LUFS, EBU R 128's -23 LUFS, or any other target set by the user or some piece of software), there may be confusion as to how the results were produced. Typically, utilities that ship with reference encoders (FLAC / metaflac, Vorbis / vorbisgain, WavPack / wvgain, Musepack / mpcgain…) use the original RG algorithm, which can produce values that differ from newer tools by several decibels in certain cases. Generally speaking, it is recommended to run other utilities or players that implement the ITU-R BS.1770 algorithm, although it may not be obvious which algorithm they use at first glance. Their documentation may provide that information.

==== RG1, RG2 ====
Although there are many references online, and within ReplayGain scanners, about version 1 vs. version 2 of the ReplayGain standard, at the time of writing this, there is (admittedly) only one ReplayGain standard. The core principle, as well as the 4 tags from the original specification, have not changed. More tags have been proposed but they are still subject to debate. As a rule of thumb, tools that advertise "ReplayGain 2" compliance employ the newer, more accurate ITU-R BS.1770 algorithm. [[foobar2000]] labels it "EBU R128" but it essentially means the same thing. Should a better algorithm be developed in the future, it will still work towards fulfilling ReplayGain's original goals, and probably write the same tags.

=== MP3Gain ===
[[MP3Gain]] is an implementation of classic ReplayGain. It can be used to just analyze files & recommend changes or to also modify the gain. If modifying the gain, it always modifies the global gain fields in the MP3 audio data. It can add somewhat precise metadata, including undo info. The gain can be modified to any target dB, or it can be changed by a specified amount. For balance correction, user-specified changes can even be made on just one channel in simple L/R stereo-mode files (not joint stereo).

* Format: [[MP3]]
* Method: Audio + Meta (in APE tag), or Audio only
* APE tag fields (ASCII bytes):
** <code>MP3GAIN_MINMAX ###,###</code> - minimum & maximum global gain values for this file. 3 digits, zero-padded if necessary.
** <code>MP3GAIN_ALBUM_MINMAX ###,###</code> - minimum & maximum global gain values across a set of files scanned as an album. Optional.
** <code>MP3GAIN_UNDO +###,+###,N</code> - the global gain adjustment to restore the original values in the left and right channels, respectively, followed by an indicator of whether to wrap at the extremes (<code>N</code> means no, <code>W</code> means yes). The adjustment values are 3 digits, zero-padded, preceded by a sign (<code>+</code> or <code>-</code>).
** <code>REPLAYGAIN_TRACK_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Examples: <code>+0.424046</code> and <code>-10.38500</code>
** <code>REPLAYGAIN_TRACK_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Example: <code>0.149923</code>
** <code>REPLAYGAIN_ALBUM_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Optional.
** <code>REPLAYGAIN_ALBUM_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Optional.
* Limitations: Although the metadata, if written, contains precise adjustment & peak values, the audio data modifications are limited to 1.5dB steps and may become irreversible (however, that's a very rare condition; see the [https://hydrogenaud.io/index.php/topic,34154.0.html "mp3gain is NOT lossless" forum thread])
* http://mp3gain.sourceforge.net/

=== AACGain ===
[[AACGain]] is a modified version of MP3Gain that works on both MP3 and AAC files.

* Format: [[MP3]], [[AAC]] (with or without MP4 container)
* Method: Audio + Meta, or Audio only
* Limitations: Limited to 1.5dB steps mode, may become irreversible (same caveat as for MP3Gain)
* http://aacgain.altosdesign.com/

=== [[LAME]] ===
* Method: Header ([http://gabriel.mp3-tech.org/mp3infotag.html mp3infotag])
* Notes:
** Uses the classic RG algorithm.
** Tags added during encoding; not supported by any player yet; Track Gain only
** Replay Gaining MP3's is usually done using MP3Gain (see [[ReplayGain#MP3Gain|above]]) or [[ReplayGain#foobar2000 ReplayGain scanner|foobar2000]]
* http://lame.sourceforge.net/

=== [[Musepack]] ReplayGain ===
* Method: Header (similar to Meta data method)
* Notes: Uses the classic RG algorithm. ReplayGain values are stored in the header and ReplayGain is part of the Musepack specifications; therefore any Musepack decoder that does not support ReplayGain can be considered broken.
* http://www.musepack.net/

=== VorbisGain ===
* Format: (Ogg) [[Vorbis]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://www.sjeng.org/vorbisgain.html
** new compiles of VorbisGain at [http://www.rarewares.org/ogg.html www.rarewares.org]
:'''''Note:''' Andavari has provided a very useful script to integrate VorbisGain, which is a CLI tool, into Windows Explorer. Please (Ogg) [[Vorbis#ReplayGain|check this section]].''

=== FLAC / METAFLAC ===
* Format: [[Free Lossless Audio Codec|FLAC]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://flac.sf.net

=== WavPack / WVGAIN ===
* Format: [[WavPack]]
* Method: Meta (in [[APEv2]] tag)
* Uses the classic RG algorithm.
* http://www.wavpack.com

=== Wavegain ===
* Format: waveform
* Method: Audio
* Uses the classic RG algorithm.
* Limitations: Irreversible
* http://www.rarewares.org/others.php#wavegain

=== MusicPlayer ===
* Custom implementation, inspired by MP3Gain.
* Format: any that FFmpeg supports
* Method: Audio
* Limitations: Doesn't modify the files at all. Stores the value in own database. Used only for playback.
* https://github.com/albertz/music-player

=== [[foobar2000]] ReplayGain scanner ===
* Since v1.1.6, defaults to ITU-R BS.1770 analysis (although it labels it EBU R128), but can be configured to use the "Classic ReplayGain" algorithm instead. The ITU-R BS.1770 implementation uses a reference level of -18 LUFS instead of -23, in order to retain compatibility with the ReplayGain standard.
* Format:
** [[MP3]]: Values written to [[ID3v2]] (default) or [[APEv2]] tags.
** [[Musepack]]: Values written to header.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]] and/or file header.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags
** [[MP4]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain).
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[TAK]]: Values written to [[APEv2]] tags.
** [[TTA]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** [[WMA]]: Values written to WMA tags.
** [[WAV]]: Values written to ID3 chunk.
** [[AIFF]]: Values written to ID3 chunk.
** Modules ([[MOD]] etc.): Optionally saved into [[APEv2]] tags.
** Any non-taggable format or format supported by FFmpeg can store RG values in a database or external tag with a component.
** A separate function can be invoked to apply the tagged Track or Album Gain to the global gain fields in MP3, MP4 (AAC), or Opus files, and rewrite any existing tags to account for the peak change and compensate for the difference from 89 dB. The 89 dB reference level for tags isn't configurable, but the reference level applied to the global gain fields is.
** Can automatically copy Track or Album gain values to Apple's SoundCheck tag in MP4 files or any format that supports ID3v2 to effectively add ReplayGain support to Apple's players.
* https://foobar2000.org/

=== [[MediaMonkey]] ===
* Format:
** [[MP3]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in MediaMonkey's MDB database.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[WAV]]: Values stored in MediaMonkey's MDB database.
** [[MPC]]: Internal gain Structure.
* In addition to tags, all ReplayGain values are also stored in MediaMonkey's MDB database
* Album/Audiophile ReplayGain not supported until v3.0 (Dec 2007); support during burning & ripping added in 3.1 (Jun 2009)
* Also capable of (irreversibly) changing the volume of MP3 tracks, similar to [[MP3Gain]]
* http://www.mediamonkey.com/

=== [[Winamp]] ReplayGain scanner===
* Format:
** [[MP3]]: Values written to [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in Windows Media Audio tags.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags.
** [[MP4]]
** [[TAK]]: Values written to [[APEv2]] tags.
* Support Album/Track Gain

=== [[loudgain]] ===
* Format:
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** MP2, [[MP3]]: Values written to [[ID3v2]] tags (ID3v2.3/ID3v2.4 selectable).
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** (Ogg) [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** (Ogg) [[Speex]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]], based on -23 LUFS Opus standard. Only <code>R128_TRACK_GAIN</code> and <code>R128_ALBUM_GAIN</code> are written, but the calculated ''true peak'' value can still be used to reduce the gain values ([[Clipping]] prevention).
** [[MP4]], [[M4A]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain). ReplayGain values are stored under <code>----:com.apple.iTunes:…</code>. This is for [[AAC]] and [[ALAC]] in [[MPEG-4]] containers.
** [[ASF]], [[Windows Media Audio|WMA]]: Values written to WMA tags, no prefix.
** [[WAV]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] (ID3v2.3/ID3v2.4 selectable) format. Using the <code>bext</code> chunk (for BWF v2) isn’t (yet) supported, but won’t be destroyed on writing.
** [[Audio Interchange File Format|AIFF]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] format.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[Monkey's Audio]] (APE): Values written to [[APEv2]] tags.
* Follows EBU R128, ITU BS.1770 and the [[ReplayGain 2.0 specification|revised ReplayGain specification]].
* ''Never'' touches the actual audio data but ''only writes RG2 tags''.
* Uses ''true peak'' values calculated by oversampling to 192 kHz, using a custom polyphase FIR interpolator that will oversample 4x for sample rates < 96 kHz, 2x for sample rates < 192 kHz and leave the signal unchanged for 192 kHz.
* ''Clipping prevention'' can be used to lower the ReplayGain values to a safe margin (default -1 dBTP, can be changed).
* Many options for special cases: force RG tags upper-/lowercase, add extra tags (LRA, Reference loudness), strip unwanted tag types (APEv2 from MP2/MP3, ID3 from WavPack), tab-delimited table output for analysis with CSV file.
* ''Linux'' Free and Open Source software, can be installed on ''MacOS'' using ''HomeBrew'', on ''Windows 10'' using the Linux ''bash''.
* Also installs a <code>rgbpm</code> bash script for mass-tagging, which can be adapted to the user’s needs.
* '''Warning:''' Loudgain relies on standard libraries like ''TagLib''. Linux distros (except rolling releases) sometimes deliver outdated libraries, so be sure you use the latest version of ''TagLib''. Version 1.11.1 had a nasty bug for a while that [https://hydrogenaud.io/index.php/topic,118085.msg974957.html#msg974957 could corrupt Ogg Vorbis files]. This has been fixed in the meantime but the TagLib version not updated. Loudgain comes with a (slower) static version called <code>loudgain.static</code> in the repo’s <code>/bin</code> folder that doesn’t expose the bug and can also be used on older Linux versions (like Ubuntu 14.04, Linux Mint 17).
* https://github.com/Moonbase59/loudgain
* Bug tracker: https://github.com/Moonbase59/loudgain/issues

=== [[rsgain]] ===
rsgain is a newer ReplayGain command line utility designed with a "batteries included" philosophy, use the newer ITU-R BS.1770 algorithm.

Features:
* Cross-platform Windows / macOS / Linux
* Supports all popular audio formats
* Simplified "Easy Mode" command line syntax supports recursive, directory-based scanning
* Multithreaded scanning option that provides significant speed improvement with full library scans
* Option to skip files with existing ReplayGain metadata
* Scan presets allow the user to save advanced settings for consistent use

== Players support ==
ReplayGain being present in the specs of the FLAC, Musepack, and APE formats, any player that support those formats usually supports ReplayGain.

The situation with MP3 is rather different, as it was not part of the MP3 specs. The APEv2 tags metadata implementation is somewhat becoming the de-facto standard.

=== Windows ===
* [[foobar2000]] supports ReplayGain in all possible aspects.
* [[Winamp]] supports ReplayGain in album or track mode.
* [[MediaMonkey]] supports ReplayGain, with many configuration options.
* [[XMPlay]] recently implemented ReplayGain
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.

''...and probably others.''

=== Linux ===
* [[XMMS]]. Reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], [[Musepack]], (Ogg) [[Vorbis]] ..
:For [[MP3]], use the CVS version of the [http://xmms-mad.sourceforge.net/ xmms-mad] mp3 plugin (it's not yet released as binary, furthermore not available in distribs' versions for now. Meanwhile binaries are available here: [http://perso.crans.org/~krempp/xmms-mad/ custom binaries])
* [[amarok]]. By using the amarok-script [http://kde-apps.org/content/show.php?content=26073 ReplayGain]
:And possibly others, since [http://developer.kde.org/~wheeler/taglib.html TagLib] added support for [[APEv2]] tags in [[MP3]] files, players using this library (like [[amaroK]] and [[JuK]]) might support that kind of ReplayGain tags in the near future.
* [http://www.sacredchao.net/quodlibet Quod Libet] reads ReplayGain from (Ogg) [[Vorbis]], [[MP3]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:Requires support to be enabled (via the appropriate python bindings and libraries) for the above formats. Does not support ReplayGain values stored in [[APEv2]] tags in [[MP3]]s. ReplayGain values are stored in RVA2 id3v2.4 frames. See the [http://www.sacredchao.net/quodlibet/wiki/Development/ID3Notes Quod Libet RVA2 / ReplayGain notes].
* [http://www.musicpd.org/ Music Player Daemon] (MPD) reads ReplayGain from (Ogg) [[Vorbis]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:foobar2000-style TXXX frames in [[MP3]]s are also supported in the latest development releases.
* [http://www.mplayerhq.hu/ MPlayer]. Mplayer support for ReplayGain is codec dependent.
:Codecs that are known to support ReplayGain: vorbis
:Because of this, you need to prioritize the codecs that support it, or choose it individually on the command line. To add it to the command line, add an -ac [codec] option after each file that you want to choose the codec for, or at the beginning to make it apply to all files listed. To prioritize the codecs by default, list them in a line in mplayer.conf:
ac=[codec],[othercodec],vorbis,mad,
* [http://idjc.sourceforge.net/ IDJC] (Internet DJ Console) reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], (Ogg) FLAC, (Ogg) [[Vorbis]], MP2 (audio), [[MP3]], [[Opus]], but only the ''lowercase'' tags. There is a [https://sourceforge.net/p/idjc/bugs/100/ ticket] open to handle tags case-insensitively.
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.
* [https://www.videolan.org/vlc/ VLC] supports ReplayGain in many file formats, but usually only the ''uppercase'' variant of the tags.
* [https://kodi.tv/ KODI] reads ReplayGain from nearly all formats, but usually only the ''lowercase'' variant of the tags.

=== Portable devices ===
[http://www.rockbox.org/ Rockbox] supports ReplayGain (in album or track mode) for most formats, including WMA, MP1/2/3, AAC, ALAC, Musepack, Monkey's Audio, Wavpack, FLAC and Vorbis. Note that ReplayGain is only supported when using the respective codec's native tagging format. For example: ReplayGain stored in APEv2 tags is not supported for MP3, rather ID3v2.x tags are expected.

Sandisk Sansa Fuze with firmware 1.02.26 and 2.02.26

Sandisk Sansa Clip+

The iPod features ''Soundcheck'', which seems to produce roughly the same normalization gains as ReplayGain, but doesn't provide an Album Gain.

=== Hi-Fi ===
Slim Devices, a company owned by Logitech Inc, supports ReplayGain on both of their hi-end audiophile players, known as the [[Slim Devices Transporter|Transporter]] and the [[Slim Devices Squeezebox|Squeezebox]].

BluOS also supports ReplayGain with the selection of album- or track-gain and a so called Smart option that decides between the two by itself.
NAD devices that use BluOS consequently also support ReplayGain.

==Notes==
<references/>

== See also ==
* [[ReplayGain specification]]

== External links ==
* [http://en.wikipedia.org/wiki/Replay_Gain ReplayGain] at Wikipedia
* [http://www.bobulous.org.uk/misc/Replay-Gain.html ReplayGain using foobar2000] (how to use ReplayGain in Windows using foobar2000).
* [http://www.bobulous.org.uk/misc/Replay-Gain-in-Linux.html ReplayGain in Linux] (how to use ReplayGain in Linux using foobar2000 and Wine, or using metaflac or vorbisgain).

[[index.php?title=Category:Technical]]
[[index.php?title=Category:Metadata]]

ReplayGain

2026-01-23T10:24:41Z

Case: /* foobar2000 ReplayGain scanner */

'''ReplayGain''' is the name of a technique invented to achieve the same perceived playback loudness of audio files. It defines an algorithm to measure the '''perceived''' loudness of audio data.

ReplayGain allows the loudness of each song within a collection of songs to be consistent. This is called 'Track Gain' (or 'Radio Gain' in earlier parlance). It also allows the loudness of a specific sub-collection (an "album") to be consistent with the rest of the collection, while allowing the dynamics from song to song on the album to remain intact. This is called 'Album Gain' (or 'Audiophile Gain' in earlier parlance). This is especially important when listening to classical music albums, because quiet tracks need to remain a certain degree quieter than the louder ones.

ReplayGain is different from [[Normalization|peak normalization]]. Peak normalization merely ensures that the peak amplitude reaches a certain level. This does not ensure equal loudness. The ReplayGain technique measures the ''effective power'' of the waveform (i.e. the RMS power after applying an "equal loudness contour"), and then adjusts the amplitude of the waveform accordingly. The result is that Replay Gained waveforms are usually more uniformly amplified than peak-normalized waveforms.

==Target loudness==
The target loudness of all ReplayGain utilities is 89 dB SPL when replayed in an SMPTE RP 200 calibrated system (an early departure from the proposal, endorsed by its author<ref>[http://www.hydrogenaudio.org/forums/index.php?s=&showtopic=83397&view=findpost&p=721854 Does Replay gain work differtly in Media monkey]</ref>) — the ReplayGain proposal and SMPTE recommendation are 6 dB lower.<ref>[http://www.mars.org/mailman/public/mad-dev/2004-February/000993.html ReplayGain discussion at mad-dev]</ref> The target loudness may be more commonly known and understood as '''-18''' '''[https://en.wikipedia.org/wiki/LUFS LUFS]''' (''Loudness Units relative to Full Scale'').

Some utilities have realized the inadequacies of the classic ReplayGain loudness calculation, switching to a more modern algorithm ([https://www.itu.int/rec/R-REC-BS.1770-5-202311-I/en ITU-R BS.1770]). However, the way it was integrated was extremely ''ad hoc'', at least until a draft of a [[ReplayGain 2.0 specification|revised specification]] started being written.

==Clipping==
Audio is generally recorded such that the loudest sounds don't clip, but the use of ReplayGain can cause clipping if the average volume of a song is below the target level. That is, upon playback, the volume of a quiet song is increased, so the parts of the song with above-average loudness, especially in the bass frequencies, will exceed the limits of the format and will be distorted. Whether this distortion is audible depends on the sounds in question, and the listener's sensitivity.

Implementations deal with the risk of clipping in different ways. Some have a "pre-amp" feature which reduces (or boosts) the original audio's level by a certain amount before doing whatever is needed for ReplayGain. Some have a "prevent clipping" feature to reduce the amount of ReplayGain adjustment to whatever amount would keep clipping from occurring, based on peak info stored in the file's metadata (thus reducing the effectiveness of ReplayGain). Some recommend using a compressor/limiter DSP to prevent or reduce clipping, regardless of whether it was caused by ReplayGain.

An alternative that may reduce the risk of clipping is the [https://tech.ebu.ch/docs/r/r128.pdf EBU R 128] recommendation of a -23 LUFS target, but that's a different standard, and some may find the additional reduction in volume excessive, particularly if it leads to maxing out volume on user hardware. [[Opus]] in particular has adopted that standard, using a global gain as well as <code>R128_TRACK_GAIN</code> / <code>R128_ALBUM_GAIN</code> tags. With ReplayGain, a simple (though somewhat radical) solution is to lower the preamp value by 5 dB (or whatever one feels comfortable with) in the playback software. The RG target will always be -18 LUFS, regardless of a user's volume or preamp settings.

== Implementations ==
There are different ReplayGain implementations, each with its own uses and strength. Most use [[metadata]] to indicate the level of the volume change that the player should make. Some modify the audio data itself, and optionally use metadata as well. There are advantages and disadvantages to both methods.

In the metadata method, information on both types of ReplayGain (Track Gain and Album Gain) can be stored. The volume-change information can be very precise. If audio data was also changed, the metadata can contain "undo" info. Not all audio players/decoders know how to read and use ReplayGain information stored in metadata. And there's no standard for where and how ReplayGain info is stored; each implementation uses different formats and puts the info in different locations.

In the audio data method, the file's actual audio data is modified so that its natural/default playback volume is at the target level. In this scenario, only one type of ReplayGain (Track Gain or Album Gain) can be applied. If no "undo" info is saved somewhere, it may not be possible to restore the original audio data. Limitations of the audio file format may prevent precise (finely tuned) gain adjustments with this method. For example, MP3 and AAC files can only be losslessly modified in 1.5 dB steps. Depending on the audio file format, the process may also be lossy in the sense that it could irreversibly push a signal above the format's maximum amplitude (resulting in clipping) or below the minimum (resulting in silence).

=== Old versus new algorithms ===
Since the ReplayGain standard does not define tags to specify which algorithm was used (classic or ITU-R BS.1770) or what target was set (RG's -18 LUFS, EBU R 128's -23 LUFS, or any other target set by the user or some piece of software), there may be confusion as to how the results were produced. Typically, utilities that ship with reference encoders (FLAC / metaflac, Vorbis / vorbisgain, WavPack / wvgain, Musepack / mpcgain…) use the original RG algorithm, which can produce values that differ from newer tools by several decibels in certain cases. Generally speaking, it is recommended to run other utilities or players that implement the ITU-R BS.1770 algorithm, although it may not be obvious which algorithm they use at first glance. Their documentation may provide that information.

==== RG1, RG2 ====
Although there are many references online, and within ReplayGain scanners, about version 1 vs. version 2 of the ReplayGain standard, at the time of writing this, there is (admittedly) only one ReplayGain standard. The core principle, as well as the 4 tags from the original specification, have not changed. More tags have been proposed but they are still subject to debate. As a rule of thumb, tools that advertise "ReplayGain 2" compliance employ the newer, more accurate ITU-R BS.1770 algorithm. [[foobar2000]] labels it "EBU R128" but it essentially means the same thing. Should a better algorithm be developed in the future, it will still work towards fulfilling ReplayGain's original goals, and probably write the same tags.

=== MP3Gain ===
[[MP3Gain]] is an implementation of classic ReplayGain. It can be used to just analyze files & recommend changes or to also modify the gain. If modifying the gain, it always modifies the global gain fields in the MP3 audio data. It can add somewhat precise metadata, including undo info. The gain can be modified to any target dB, or it can be changed by a specified amount. For balance correction, user-specified changes can even be made on just one channel in simple L/R stereo-mode files (not joint stereo).

* Format: [[MP3]]
* Method: Audio + Meta (in APE tag), or Audio only
* APE tag fields (ASCII bytes):
** <code>MP3GAIN_MINMAX ###,###</code> - minimum & maximum global gain values for this file. 3 digits, zero-padded if necessary.
** <code>MP3GAIN_ALBUM_MINMAX ###,###</code> - minimum & maximum global gain values across a set of files scanned as an album. Optional.
** <code>MP3GAIN_UNDO +###,+###,N</code> - the global gain adjustment to restore the original values in the left and right channels, respectively, followed by an indicator of whether to wrap at the extremes (<code>N</code> means no, <code>W</code> means yes). The adjustment values are 3 digits, zero-padded, preceded by a sign (<code>+</code> or <code>-</code>).
** <code>REPLAYGAIN_TRACK_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Examples: <code>+0.424046</code> and <code>-10.38500</code>
** <code>REPLAYGAIN_TRACK_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Example: <code>0.149923</code>
** <code>REPLAYGAIN_ALBUM_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Optional.
** <code>REPLAYGAIN_ALBUM_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Optional.
* Limitations: Although the metadata, if written, contains precise adjustment & peak values, the audio data modifications are limited to 1.5dB steps and may become irreversible (however, that's a very rare condition; see the [https://hydrogenaud.io/index.php/topic,34154.0.html "mp3gain is NOT lossless" forum thread])
* http://mp3gain.sourceforge.net/

=== AACGain ===
[[AACGain]] is a modified version of MP3Gain that works on both MP3 and AAC files.

* Format: [[MP3]], [[AAC]] (with or without MP4 container)
* Method: Audio + Meta, or Audio only
* Limitations: Limited to 1.5dB steps mode, may become irreversible (same caveat as for MP3Gain)
* http://aacgain.altosdesign.com/

=== [[LAME]] ===
* Method: Header ([http://gabriel.mp3-tech.org/mp3infotag.html mp3infotag])
* Notes:
** Uses the classic RG algorithm.
** Tags added during encoding; not supported by any player yet; Track Gain only
** Replay Gaining MP3's is usually done using MP3Gain (see [[ReplayGain#MP3Gain|above]]) or [[ReplayGain#foobar2000 ReplayGain scanner|foobar2000]]
* http://lame.sourceforge.net/

=== [[Musepack]] ReplayGain ===
* Method: Header (similar to Meta data method)
* Notes: Uses the classic RG algorithm. ReplayGain values are stored in the header and ReplayGain is part of the Musepack specifications; therefore any Musepack decoder that does not support ReplayGain can be considered broken.
* http://www.musepack.net/

=== VorbisGain ===
* Format: (Ogg) [[Vorbis]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://www.sjeng.org/vorbisgain.html
** new compiles of VorbisGain at [http://www.rarewares.org/ogg.html www.rarewares.org]
:'''''Note:''' Andavari has provided a very useful script to integrate VorbisGain, which is a CLI tool, into Windows Explorer. Please (Ogg) [[Vorbis#ReplayGain|check this section]].''

=== FLAC / METAFLAC ===
* Format: [[Free Lossless Audio Codec|FLAC]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://flac.sf.net

=== WavPack / WVGAIN ===
* Format: [[WavPack]]
* Method: Meta (in [[APEv2]] tag)
* Uses the classic RG algorithm.
* http://www.wavpack.com

=== Wavegain ===
* Format: waveform
* Method: Audio
* Uses the classic RG algorithm.
* Limitations: Irreversible
* http://www.rarewares.org/others.php#wavegain

=== MusicPlayer ===
* Custom implementation, inspired by MP3Gain.
* Format: any that FFmpeg supports
* Method: Audio
* Limitations: Doesn't modify the files at all. Stores the value in own database. Used only for playback.
* https://github.com/albertz/music-player

=== [[foobar2000]] ReplayGain scanner ===
* Since v1.1.6, defaults to ITU-R BS.1770 analysis (although it labels it EBU R128), but can be configured to use the "Classic ReplayGain" algorithm instead. The ITU-R BS.1770 implementation uses a reference level of -18 LUFS instead of -23, in order to retain compatibility with the ReplayGain standard.
* Format:
** [[MP3]]: Values written to [[ID3v2]] (default) or [[APEv2]] tags.
** [[Musepack]]: Values written to header.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]] and/or file header.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags
** [[MP4]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain). Can write chosen Gain value to Apple's SoundCheck
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[TAK]]: Values written to [[APEv2]] tags.
** [[TTA]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** [[WMA]]: Values written to WMA tags.
** [[WAV]]: Values written to ID3 chunk.
** [[AIFF]]: Values written to ID3 chunk.
** Modules ([[MOD]] etc.): Optionally saved into [[APEv2]] tags.
** Any non-taggable format or format supported by FFmpeg can store RG values in a database or external tag with a component.
** A separate function can be invoked to apply the tagged Track or Album Gain to the global gain fields in MP3, MP4 (AAC), or Opus files, and rewrite any existing tags to account for the peak change and compensate for the difference from 89 dB. The 89 dB reference level for tags isn't configurable, but the reference level applied to the global gain fields is.
** Can automatically copy Track or Album gain values to Apple's SoundCheck tag in MP4 files or any format that supports ID3v2 to effectively add ReplayGain support to Apple's players.
* https://foobar2000.org/

=== [[MediaMonkey]] ===
* Format:
** [[MP3]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in MediaMonkey's MDB database.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[WAV]]: Values stored in MediaMonkey's MDB database.
** [[MPC]]: Internal gain Structure.
* In addition to tags, all ReplayGain values are also stored in MediaMonkey's MDB database
* Album/Audiophile ReplayGain not supported until v3.0 (Dec 2007); support during burning & ripping added in 3.1 (Jun 2009)
* Also capable of (irreversibly) changing the volume of MP3 tracks, similar to [[MP3Gain]]
* http://www.mediamonkey.com/

=== [[Winamp]] ReplayGain scanner===
* Format:
** [[MP3]]: Values written to [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in Windows Media Audio tags.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags.
** [[MP4]]
** [[TAK]]: Values written to [[APEv2]] tags.
* Support Album/Track Gain

=== [[loudgain]] ===
* Format:
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** MP2, [[MP3]]: Values written to [[ID3v2]] tags (ID3v2.3/ID3v2.4 selectable).
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** (Ogg) [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** (Ogg) [[Speex]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]], based on -23 LUFS Opus standard. Only <code>R128_TRACK_GAIN</code> and <code>R128_ALBUM_GAIN</code> are written, but the calculated ''true peak'' value can still be used to reduce the gain values ([[Clipping]] prevention).
** [[MP4]], [[M4A]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain). ReplayGain values are stored under <code>----:com.apple.iTunes:…</code>. This is for [[AAC]] and [[ALAC]] in [[MPEG-4]] containers.
** [[ASF]], [[Windows Media Audio|WMA]]: Values written to WMA tags, no prefix.
** [[WAV]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] (ID3v2.3/ID3v2.4 selectable) format. Using the <code>bext</code> chunk (for BWF v2) isn’t (yet) supported, but won’t be destroyed on writing.
** [[Audio Interchange File Format|AIFF]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] format.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[Monkey's Audio]] (APE): Values written to [[APEv2]] tags.
* Follows EBU R128, ITU BS.1770 and the [[ReplayGain 2.0 specification|revised ReplayGain specification]].
* ''Never'' touches the actual audio data but ''only writes RG2 tags''.
* Uses ''true peak'' values calculated by oversampling to 192 kHz, using a custom polyphase FIR interpolator that will oversample 4x for sample rates < 96 kHz, 2x for sample rates < 192 kHz and leave the signal unchanged for 192 kHz.
* ''Clipping prevention'' can be used to lower the ReplayGain values to a safe margin (default -1 dBTP, can be changed).
* Many options for special cases: force RG tags upper-/lowercase, add extra tags (LRA, Reference loudness), strip unwanted tag types (APEv2 from MP2/MP3, ID3 from WavPack), tab-delimited table output for analysis with CSV file.
* ''Linux'' Free and Open Source software, can be installed on ''MacOS'' using ''HomeBrew'', on ''Windows 10'' using the Linux ''bash''.
* Also installs a <code>rgbpm</code> bash script for mass-tagging, which can be adapted to the user’s needs.
* '''Warning:''' Loudgain relies on standard libraries like ''TagLib''. Linux distros (except rolling releases) sometimes deliver outdated libraries, so be sure you use the latest version of ''TagLib''. Version 1.11.1 had a nasty bug for a while that [https://hydrogenaud.io/index.php/topic,118085.msg974957.html#msg974957 could corrupt Ogg Vorbis files]. This has been fixed in the meantime but the TagLib version not updated. Loudgain comes with a (slower) static version called <code>loudgain.static</code> in the repo’s <code>/bin</code> folder that doesn’t expose the bug and can also be used on older Linux versions (like Ubuntu 14.04, Linux Mint 17).
* https://github.com/Moonbase59/loudgain
* Bug tracker: https://github.com/Moonbase59/loudgain/issues

=== [[rsgain]] ===
rsgain is a newer ReplayGain command line utility designed with a "batteries included" philosophy, use the newer ITU-R BS.1770 algorithm.

Features:
* Cross-platform Windows / macOS / Linux
* Supports all popular audio formats
* Simplified "Easy Mode" command line syntax supports recursive, directory-based scanning
* Multithreaded scanning option that provides significant speed improvement with full library scans
* Option to skip files with existing ReplayGain metadata
* Scan presets allow the user to save advanced settings for consistent use

== Players support ==
ReplayGain being present in the specs of the FLAC, Musepack, and APE formats, any player that support those formats usually supports ReplayGain.

The situation with MP3 is rather different, as it was not part of the MP3 specs. The APEv2 tags metadata implementation is somewhat becoming the de-facto standard.

=== Windows ===
* [[foobar2000]] supports ReplayGain in all possible aspects.
* [[Winamp]] supports ReplayGain in album or track mode.
* [[MediaMonkey]] supports ReplayGain, with many configuration options.
* [[XMPlay]] recently implemented ReplayGain
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.

''...and probably others.''

=== Linux ===
* [[XMMS]]. Reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], [[Musepack]], (Ogg) [[Vorbis]] ..
:For [[MP3]], use the CVS version of the [http://xmms-mad.sourceforge.net/ xmms-mad] mp3 plugin (it's not yet released as binary, furthermore not available in distribs' versions for now. Meanwhile binaries are available here: [http://perso.crans.org/~krempp/xmms-mad/ custom binaries])
* [[amarok]]. By using the amarok-script [http://kde-apps.org/content/show.php?content=26073 ReplayGain]
:And possibly others, since [http://developer.kde.org/~wheeler/taglib.html TagLib] added support for [[APEv2]] tags in [[MP3]] files, players using this library (like [[amaroK]] and [[JuK]]) might support that kind of ReplayGain tags in the near future.
* [http://www.sacredchao.net/quodlibet Quod Libet] reads ReplayGain from (Ogg) [[Vorbis]], [[MP3]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:Requires support to be enabled (via the appropriate python bindings and libraries) for the above formats. Does not support ReplayGain values stored in [[APEv2]] tags in [[MP3]]s. ReplayGain values are stored in RVA2 id3v2.4 frames. See the [http://www.sacredchao.net/quodlibet/wiki/Development/ID3Notes Quod Libet RVA2 / ReplayGain notes].
* [http://www.musicpd.org/ Music Player Daemon] (MPD) reads ReplayGain from (Ogg) [[Vorbis]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:foobar2000-style TXXX frames in [[MP3]]s are also supported in the latest development releases.
* [http://www.mplayerhq.hu/ MPlayer]. Mplayer support for ReplayGain is codec dependent.
:Codecs that are known to support ReplayGain: vorbis
:Because of this, you need to prioritize the codecs that support it, or choose it individually on the command line. To add it to the command line, add an -ac [codec] option after each file that you want to choose the codec for, or at the beginning to make it apply to all files listed. To prioritize the codecs by default, list them in a line in mplayer.conf:
ac=[codec],[othercodec],vorbis,mad,
* [http://idjc.sourceforge.net/ IDJC] (Internet DJ Console) reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], (Ogg) FLAC, (Ogg) [[Vorbis]], MP2 (audio), [[MP3]], [[Opus]], but only the ''lowercase'' tags. There is a [https://sourceforge.net/p/idjc/bugs/100/ ticket] open to handle tags case-insensitively.
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.
* [https://www.videolan.org/vlc/ VLC] supports ReplayGain in many file formats, but usually only the ''uppercase'' variant of the tags.
* [https://kodi.tv/ KODI] reads ReplayGain from nearly all formats, but usually only the ''lowercase'' variant of the tags.

=== Portable devices ===
[http://www.rockbox.org/ Rockbox] supports ReplayGain (in album or track mode) for most formats, including WMA, MP1/2/3, AAC, ALAC, Musepack, Monkey's Audio, Wavpack, FLAC and Vorbis. Note that ReplayGain is only supported when using the respective codec's native tagging format. For example: ReplayGain stored in APEv2 tags is not supported for MP3, rather ID3v2.x tags are expected.

Sandisk Sansa Fuze with firmware 1.02.26 and 2.02.26

Sandisk Sansa Clip+

The iPod features ''Soundcheck'', which seems to produce roughly the same normalization gains as ReplayGain, but doesn't provide an Album Gain.

=== Hi-Fi ===
Slim Devices, a company owned by Logitech Inc, supports ReplayGain on both of their hi-end audiophile players, known as the [[Slim Devices Transporter|Transporter]] and the [[Slim Devices Squeezebox|Squeezebox]].

BluOS also supports ReplayGain with the selection of album- or track-gain and a so called Smart option that decides between the two by itself.
NAD devices that use BluOS consequently also support ReplayGain.

==Notes==
<references/>

== See also ==
* [[ReplayGain specification]]

== External links ==
* [http://en.wikipedia.org/wiki/Replay_Gain ReplayGain] at Wikipedia
* [http://www.bobulous.org.uk/misc/Replay-Gain.html ReplayGain using foobar2000] (how to use ReplayGain in Windows using foobar2000).
* [http://www.bobulous.org.uk/misc/Replay-Gain-in-Linux.html ReplayGain in Linux] (how to use ReplayGain in Linux using foobar2000 and Wine, or using metaflac or vorbisgain).

[[index.php?title=Category:Technical]]
[[index.php?title=Category:Metadata]]

ReplayGain

2026-01-23T08:18:48Z

Case: /* foobar2000 ReplayGain scanner */

'''ReplayGain''' is the name of a technique invented to achieve the same perceived playback loudness of audio files. It defines an algorithm to measure the '''perceived''' loudness of audio data.

ReplayGain allows the loudness of each song within a collection of songs to be consistent. This is called 'Track Gain' (or 'Radio Gain' in earlier parlance). It also allows the loudness of a specific sub-collection (an "album") to be consistent with the rest of the collection, while allowing the dynamics from song to song on the album to remain intact. This is called 'Album Gain' (or 'Audiophile Gain' in earlier parlance). This is especially important when listening to classical music albums, because quiet tracks need to remain a certain degree quieter than the louder ones.

ReplayGain is different from [[Normalization|peak normalization]]. Peak normalization merely ensures that the peak amplitude reaches a certain level. This does not ensure equal loudness. The ReplayGain technique measures the ''effective power'' of the waveform (i.e. the RMS power after applying an "equal loudness contour"), and then adjusts the amplitude of the waveform accordingly. The result is that Replay Gained waveforms are usually more uniformly amplified than peak-normalized waveforms.

==Target loudness==
The target loudness of almost all ReplayGain utilities is 89 dB SPL when replayed in an SMPTE RP 200 calibrated system (an early departure from the proposal, endorsed by its author<ref>[http://www.hydrogenaudio.org/forums/index.php?s=&showtopic=83397&view=findpost&p=721854 Does Replay gain work differtly in Media monkey]</ref>) — the ReplayGain proposal and SMPTE recommendation are 6 dB lower.<ref>[http://www.mars.org/mailman/public/mad-dev/2004-February/000993.html ReplayGain discussion at mad-dev]</ref> The target loudness may be more commonly known and understood as '''-18''' '''[https://en.wikipedia.org/wiki/LUFS LUFS]''' (''Loudness Units relative to Full Scale'').

Some utilities have realized the inadequacies of the classic ReplayGain loudness calculation, switching to a more modern algorithm ([https://www.itu.int/rec/R-REC-BS.1770-5-202311-I/en ITU-R BS.1770]). However, the way it was integrated was extremely ''ad hoc'', at least until a draft of a [[ReplayGain 2.0 specification|revised specification]] started being written.

==Clipping==
Audio is generally recorded such that the loudest sounds don't clip, but the use of ReplayGain can cause clipping if the average volume of a song is below the target level. That is, upon playback, the volume of a quiet song is increased, so the parts of the song with above-average loudness, especially in the bass frequencies, will exceed the limits of the format and will be distorted. Whether this distortion is audible depends on the sounds in question, and the listener's sensitivity.

Implementations deal with the risk of clipping in different ways. Some have a "pre-amp" feature which reduces (or boosts) the original audio's level by a certain amount before doing whatever is needed for ReplayGain. Some have a "prevent clipping" feature to reduce the amount of ReplayGain adjustment to whatever amount would keep clipping from occurring, based on peak info stored in the file's metadata (thus reducing the effectiveness of ReplayGain). Some recommend using a compressor/limiter DSP to prevent or reduce clipping, regardless of whether it was caused by ReplayGain.

An alternative that may reduce the risk of clipping is the [https://tech.ebu.ch/docs/r/r128.pdf EBU R 128] recommendation of a '''-23''' '''LUFS''' target, although some may find the additional reduction in volume excessive, particularly if it leads to maxing out volume on user hardware. [[Opus]] in particular has adopted that recommendation.

== Implementations ==
There are different ReplayGain implementations, each with its own uses and strength. Most use [[metadata]] to indicate the level of the volume change that the player should make. Some modify the audio data itself, and optionally use metadata as well. There are advantages and disadvantages to both methods.

In the metadata method, information on both types of ReplayGain (Track Gain and Album Gain) can be stored. The volume-change information can be very precise. If audio data was also changed, the metadata can contain "undo" info. Not all audio players/decoders know how to read and use ReplayGain information stored in metadata. And there's no standard for where and how ReplayGain info is stored; each implementation uses different formats and puts the info in different locations.

In the audio data method, the file's actual audio data is modified so that its natural/default playback volume is at the target level. In this scenario, only one type of ReplayGain (Track Gain or Album Gain) can be applied. If no "undo" info is saved somewhere, it may not be possible to restore the original audio data. Limitations of the audio file format may prevent precise (finely tuned) gain adjustments with this method. For example, MP3 and AAC files can only be losslessly modified in 1.5 dB steps. Depending on the audio file format, the process may also be lossy in the sense that it could irreversibly push a signal above the format's maximum amplitude (resulting in clipping) or below the minimum (resulting in silence).

=== Old versus new algorithms ===
Since the ReplayGain standard does not define tags to specify which algorithm was used (classic or ITU-R BS.1770) or what target was set (RG's -18 LUFS, EBU R 128's -23 LUFS, or any other target set by the user or some piece of software), there may be confusion as to how the results were produced. Typically, utilities that ship with reference encoders (FLAC / metaflac, Vorbis / vorbisgain, WavPack / wvgain, Musepack / mpcgain…) use the original RG algorithm, which can produce values that differ from newer tools by several decibels in certain cases. Generally speaking, it is recommended to run other utilities or players that implement the ITU-R BS.1770 algorithm, although it may not be obvious which algorithm they use at first glance. Their documentation may provide that information.

==== RG1, RG2 ====
Although there are many references online, and within ReplayGain scanners, about version 1 vs. version 2 of the ReplayGain standard, at the time of writing this, there is (admittedly) only one ReplayGain standard. The core principle, as well as the 4 tags from the original specification, have not changed. More tags have been proposed but they are still subject to debate. As a rule of thumb, tools that advertise "ReplayGain 2" compliance employ the newer, more accurate ITU-R BS.1770 algorithm. [[foobar2000]] labels it "EBU R128" but it essentially means the same thing. Should a better algorithm be developed in the future, it will still work towards fulfilling ReplayGain's original goals, and probably write the same tags.

=== MP3Gain ===
[[MP3Gain]] is an implementation of classic ReplayGain. It can be used to just analyze files & recommend changes or to also modify the gain. If modifying the gain, it always modifies the global gain fields in the MP3 audio data. It can add somewhat precise metadata, including undo info. The gain can be modified to any target dB, or it can be changed by a specified amount. For balance correction, user-specified changes can even be made on just one channel in simple L/R stereo-mode files (not joint stereo).

* Format: [[MP3]]
* Method: Audio + Meta (in APE tag), or Audio only
* APE tag fields (ASCII bytes):
** <code>MP3GAIN_MINMAX ###,###</code> - minimum & maximum global gain values for this file. 3 digits, zero-padded if necessary.
** <code>MP3GAIN_ALBUM_MINMAX ###,###</code> - minimum & maximum global gain values across a set of files scanned as an album. Optional.
** <code>MP3GAIN_UNDO +###,+###,N</code> - the global gain adjustment to restore the original values in the left and right channels, respectively, followed by an indicator of whether to wrap at the extremes (<code>N</code> means no, <code>W</code> means yes). The adjustment values are 3 digits, zero-padded, preceded by a sign (<code>+</code> or <code>-</code>).
** <code>REPLAYGAIN_TRACK_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Examples: <code>+0.424046</code> and <code>-10.38500</code>
** <code>REPLAYGAIN_TRACK_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Example: <code>0.149923</code>
** <code>REPLAYGAIN_ALBUM_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Optional.
** <code>REPLAYGAIN_ALBUM_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Optional.
* Limitations: Although the metadata, if written, contains precise adjustment & peak values, the audio data modifications are limited to 1.5dB steps and may become irreversible (however, that's a very rare condition; see the [https://hydrogenaud.io/index.php/topic,34154.0.html "mp3gain is NOT lossless" forum thread])
* http://mp3gain.sourceforge.net/

=== AACGain ===
[[AACGain]] is a modified version of MP3Gain that works on both MP3 and AAC files.

* Format: [[MP3]], [[AAC]] (with or without MP4 container)
* Method: Audio + Meta, or Audio only
* Limitations: Limited to 1.5dB steps mode, may become irreversible (same caveat as for MP3Gain)
* http://aacgain.altosdesign.com/

=== [[LAME]] ===
* Method: Header ([http://gabriel.mp3-tech.org/mp3infotag.html mp3infotag])
* Notes:
** Uses the classic RG algorithm.
** Tags added during encoding; not supported by any player yet; Track Gain only
** Replay Gaining MP3's is usually done using MP3Gain (see [[ReplayGain#MP3Gain|above]]) or [[ReplayGain#foobar2000 ReplayGain scanner|foobar2000]]
* http://lame.sourceforge.net/

=== [[Musepack]] ReplayGain ===
* Method: Header (similar to Meta data method)
* Notes: Uses the classic RG algorithm. ReplayGain values are stored in the header and ReplayGain is part of the Musepack specifications; therefore any Musepack decoder that does not support ReplayGain can be considered broken.
* http://www.musepack.net/

=== VorbisGain ===
* Format: (Ogg) [[Vorbis]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://www.sjeng.org/vorbisgain.html
** new compiles of VorbisGain at [http://www.rarewares.org/ogg.html www.rarewares.org]
:'''''Note:''' Andavari has provided a very useful script to integrate VorbisGain, which is a CLI tool, into Windows Explorer. Please (Ogg) [[Vorbis#ReplayGain|check this section]].''

=== FLAC / METAFLAC ===
* Format: [[Free Lossless Audio Codec|FLAC]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://flac.sf.net

=== WavPack / WVGAIN ===
* Format: [[WavPack]]
* Method: Meta (in [[APEv2]] tag)
* Uses the classic RG algorithm.
* http://www.wavpack.com

=== Wavegain ===
* Format: waveform
* Method: Audio
* Uses the classic RG algorithm.
* Limitations: Irreversible
* http://www.rarewares.org/others.php#wavegain

=== MusicPlayer ===
* Custom implementation, inspired by MP3Gain.
* Format: any that FFmpeg supports
* Method: Audio
* Limitations: Doesn't modify the files at all. Stores the value in own database. Used only for playback.
* https://github.com/albertz/music-player

=== [[foobar2000]] ReplayGain scanner ===
* Since v1.1.6, defaults to ITU-R BS.1770 analysis (although it labels it EBU R128), but can be configured to use the "Classic ReplayGain" algorithm instead. The ITU-R BS.1770 implementation uses a reference level of -18 LUFS instead of -23, in order to retain compatibility with the ReplayGain standard.
* Format:
** [[MP3]]: Values written to [[ID3v2]] (default) or [[APEv2]] tags.
** [[Musepack]]: Values written to header.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]] and/or file header.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags. As with MP3, it is also an option to apply gain via a separate function.
** [[MP4]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain). Can write chosen Gain value to Apple's SoundCheck
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[TAK]]: Values written to [[APEv2]] tags.
** [[TTA]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** [[WMA]]: Values written to WMA tags.
** Modules ([[MOD]] etc.): Optionally saved into [[APEv2]] tags.
** Any non-taggable format or format supported by FFmpeg can store RG values in a database or external tag with a component.
** A separate function can be invoked to apply the tagged Track or Album Gain to the global gain fields in MP3, MP4 (AAC), or Opus files, and rewrite any existing tags to account for the peak change and compensate for the difference from 89 dB. The 89 dB reference level for tags isn't configurable, but the reference level applied to the global gain fields is.
** Can automatically copy Track or Album gain values to Apple's SoundCheck tag in MP4 files or any format that supports ID3v2 to effectively add ReplayGain support to Apple's players.
* https://foobar2000.org/

=== [[MediaMonkey]] ===
* Format:
** [[MP3]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in MediaMonkey's MDB database.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[WAV]]: Values stored in MediaMonkey's MDB database.
** [[MPC]]: Internal gain Structure.
* In addition to tags, all ReplayGain values are also stored in MediaMonkey's MDB database
* Album/Audiophile ReplayGain not supported until v3.0 (Dec 2007); support during burning & ripping added in 3.1 (Jun 2009)
* Also capable of (irreversibly) changing the volume of MP3 tracks, similar to [[MP3Gain]]
* http://www.mediamonkey.com/

=== [[Winamp]] ReplayGain scanner===
* Format:
** [[MP3]]: Values written to [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in Windows Media Audio tags.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags.
** [[MP4]]
** [[TAK]]: Values written to [[APEv2]] tags.
* Support Album/Track Gain

=== [[loudgain]] ===
* Format:
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** MP2, [[MP3]]: Values written to [[ID3v2]] tags (ID3v2.3/ID3v2.4 selectable).
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** (Ogg) [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** (Ogg) [[Speex]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]], based on -23 LUFS Opus standard. Only <code>R128_TRACK_GAIN</code> and <code>R128_ALBUM_GAIN</code> are written, but the calculated ''true peak'' value can still be used to reduce the gain values ([[Clipping]] prevention).
** [[MP4]], [[M4A]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain). ReplayGain values are stored under <code>----:com.apple.iTunes:…</code>. This is for [[AAC]] and [[ALAC]] in [[MPEG-4]] containers.
** [[ASF]], [[Windows Media Audio|WMA]]: Values written to WMA tags, no prefix.
** [[WAV]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] (ID3v2.3/ID3v2.4 selectable) format. Using the <code>bext</code> chunk (for BWF v2) isn’t (yet) supported, but won’t be destroyed on writing.
** [[Audio Interchange File Format|AIFF]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] format.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[Monkey's Audio]] (APE): Values written to [[APEv2]] tags.
* Follows EBU R128, ITU BS.1770 and the [[ReplayGain 2.0 specification|revised ReplayGain specification]].
* ''Never'' touches the actual audio data but ''only writes RG2 tags''.
* Uses ''true peak'' values calculated by oversampling to 192 kHz, using a custom polyphase FIR interpolator that will oversample 4x for sample rates < 96 kHz, 2x for sample rates < 192 kHz and leave the signal unchanged for 192 kHz.
* ''Clipping prevention'' can be used to lower the ReplayGain values to a safe margin (default -1 dBTP, can be changed).
* Many options for special cases: force RG tags upper-/lowercase, add extra tags (LRA, Reference loudness), strip unwanted tag types (APEv2 from MP2/MP3, ID3 from WavPack), tab-delimited table output for analysis with CSV file.
* ''Linux'' Free and Open Source software, can be installed on ''MacOS'' using ''HomeBrew'', on ''Windows 10'' using the Linux ''bash''.
* Also installs a <code>rgbpm</code> bash script for mass-tagging, which can be adapted to the user’s needs.
* '''Warning:''' Loudgain relies on standard libraries like ''TagLib''. Linux distros (except rolling releases) sometimes deliver outdated libraries, so be sure you use the latest version of ''TagLib''. Version 1.11.1 had a nasty bug for a while that [https://hydrogenaud.io/index.php/topic,118085.msg974957.html#msg974957 could corrupt Ogg Vorbis files]. This has been fixed in the meantime but the TagLib version not updated. Loudgain comes with a (slower) static version called <code>loudgain.static</code> in the repo’s <code>/bin</code> folder that doesn’t expose the bug and can also be used on older Linux versions (like Ubuntu 14.04, Linux Mint 17).
* https://github.com/Moonbase59/loudgain
* Bug tracker: https://github.com/Moonbase59/loudgain/issues

=== [[rsgain]] ===
rsgain is a newer ReplayGain command line utility designed with a "batteries included" philosophy, use the newer ITU-R BS.1770 algorithm.

Features:
* Cross-platform Windows / macOS / Linux
* Supports all popular audio formats
* Simplified "Easy Mode" command line syntax supports recursive, directory-based scanning
* Multithreaded scanning option that provides significant speed improvement with full library scans
* Option to skip files with existing ReplayGain metadata
* Scan presets allow the user to save advanced settings for consistent use

== Players support ==
ReplayGain being present in the specs of the FLAC, Musepack, and APE formats, any player that support those formats usually supports ReplayGain.

The situation with MP3 is rather different, as it was not part of the MP3 specs. The APEv2 tags metadata implementation is somewhat becoming the de-facto standard.

=== Windows ===
* [[foobar2000]] supports ReplayGain in all possible aspects.
* [[Winamp]] supports ReplayGain in album or track mode.
* [[MediaMonkey]] supports ReplayGain, with many configuration options.
* [[XMPlay]] recently implemented ReplayGain
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.

''...and probably others.''

=== Linux ===
* [[XMMS]]. Reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], [[Musepack]], (Ogg) [[Vorbis]] ..
:For [[MP3]], use the CVS version of the [http://xmms-mad.sourceforge.net/ xmms-mad] mp3 plugin (it's not yet released as binary, furthermore not available in distribs' versions for now. Meanwhile binaries are available here: [http://perso.crans.org/~krempp/xmms-mad/ custom binaries])
* [[amarok]]. By using the amarok-script [http://kde-apps.org/content/show.php?content=26073 ReplayGain]
:And possibly others, since [http://developer.kde.org/~wheeler/taglib.html TagLib] added support for [[APEv2]] tags in [[MP3]] files, players using this library (like [[amaroK]] and [[JuK]]) might support that kind of ReplayGain tags in the near future.
* [http://www.sacredchao.net/quodlibet Quod Libet] reads ReplayGain from (Ogg) [[Vorbis]], [[MP3]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:Requires support to be enabled (via the appropriate python bindings and libraries) for the above formats. Does not support ReplayGain values stored in [[APEv2]] tags in [[MP3]]s. ReplayGain values are stored in RVA2 id3v2.4 frames. See the [http://www.sacredchao.net/quodlibet/wiki/Development/ID3Notes Quod Libet RVA2 / ReplayGain notes].
* [http://www.musicpd.org/ Music Player Daemon] (MPD) reads ReplayGain from (Ogg) [[Vorbis]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:foobar2000-style TXXX frames in [[MP3]]s are also supported in the latest development releases.
* [http://www.mplayerhq.hu/ MPlayer]. Mplayer support for ReplayGain is codec dependent.
:Codecs that are known to support ReplayGain: vorbis
:Because of this, you need to prioritize the codecs that support it, or choose it individually on the command line. To add it to the command line, add an -ac [codec] option after each file that you want to choose the codec for, or at the beginning to make it apply to all files listed. To prioritize the codecs by default, list them in a line in mplayer.conf:
ac=[codec],[othercodec],vorbis,mad,
* [http://idjc.sourceforge.net/ IDJC] (Internet DJ Console) reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], (Ogg) FLAC, (Ogg) [[Vorbis]], MP2 (audio), [[MP3]], [[Opus]], but only the ''lowercase'' tags. There is a [https://sourceforge.net/p/idjc/bugs/100/ ticket] open to handle tags case-insensitively.
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.
* [https://www.videolan.org/vlc/ VLC] supports ReplayGain in many file formats, but usually only the ''uppercase'' variant of the tags.
* [https://kodi.tv/ KODI] reads ReplayGain from nearly all formats, but usually only the ''lowercase'' variant of the tags.

=== Portable devices ===
[http://www.rockbox.org/ Rockbox] supports ReplayGain (in album or track mode) for most formats, including WMA, MP1/2/3, AAC, ALAC, Musepack, Monkey's Audio, Wavpack, FLAC and Vorbis. Note that ReplayGain is only supported when using the respective codec's native tagging format. For example: ReplayGain stored in APEv2 tags is not supported for MP3, rather ID3v2.x tags are expected.

Sandisk Sansa Fuze with firmware 1.02.26 and 2.02.26

Sandisk Sansa Clip+

The iPod features ''Soundcheck'', which seems to produce roughly the same normalization gains as ReplayGain, but doesn't provide an Album Gain.

=== Hi-Fi ===
Slim Devices, a company owned by Logitech Inc, supports ReplayGain on both of their hi-end audiophile players, known as the [[Slim Devices Transporter|Transporter]] and the [[Slim Devices Squeezebox|Squeezebox]].

BluOS also supports ReplayGain with the selection of album- or track-gain and a so called Smart option that decides between the two by itself.
NAD devices that use BluOS consequently also support ReplayGain.

==Notes==
<references/>

== See also ==
* [[ReplayGain specification]]

== External links ==
* [http://en.wikipedia.org/wiki/Replay_Gain ReplayGain] at Wikipedia
* [http://www.bobulous.org.uk/misc/Replay-Gain.html ReplayGain using foobar2000] (how to use ReplayGain in Windows using foobar2000).
* [http://www.bobulous.org.uk/misc/Replay-Gain-in-Linux.html ReplayGain in Linux] (how to use ReplayGain in Linux using foobar2000 and Wine, or using metaflac or vorbisgain).

[[index.php?title=Category:Technical]]
[[index.php?title=Category:Metadata]]

ReplayGain

2026-01-23T08:14:08Z

Case: /* foobar2000 ReplayGain scanner */

'''ReplayGain''' is the name of a technique invented to achieve the same perceived playback loudness of audio files. It defines an algorithm to measure the '''perceived''' loudness of audio data.

ReplayGain allows the loudness of each song within a collection of songs to be consistent. This is called 'Track Gain' (or 'Radio Gain' in earlier parlance). It also allows the loudness of a specific sub-collection (an "album") to be consistent with the rest of the collection, while allowing the dynamics from song to song on the album to remain intact. This is called 'Album Gain' (or 'Audiophile Gain' in earlier parlance). This is especially important when listening to classical music albums, because quiet tracks need to remain a certain degree quieter than the louder ones.

ReplayGain is different from [[Normalization|peak normalization]]. Peak normalization merely ensures that the peak amplitude reaches a certain level. This does not ensure equal loudness. The ReplayGain technique measures the ''effective power'' of the waveform (i.e. the RMS power after applying an "equal loudness contour"), and then adjusts the amplitude of the waveform accordingly. The result is that Replay Gained waveforms are usually more uniformly amplified than peak-normalized waveforms.

==Target loudness==
The target loudness of almost all ReplayGain utilities is 89 dB SPL when replayed in an SMPTE RP 200 calibrated system (an early departure from the proposal, endorsed by its author<ref>[http://www.hydrogenaudio.org/forums/index.php?s=&showtopic=83397&view=findpost&p=721854 Does Replay gain work differtly in Media monkey]</ref>) — the ReplayGain proposal and SMPTE recommendation are 6 dB lower.<ref>[http://www.mars.org/mailman/public/mad-dev/2004-February/000993.html ReplayGain discussion at mad-dev]</ref> The target loudness may be more commonly known and understood as '''-18''' '''[https://en.wikipedia.org/wiki/LUFS LUFS]''' (''Loudness Units relative to Full Scale'').

Some utilities have realized the inadequacies of the classic ReplayGain loudness calculation, switching to a more modern algorithm ([https://www.itu.int/rec/R-REC-BS.1770-5-202311-I/en ITU-R BS.1770]). However, the way it was integrated was extremely ''ad hoc'', at least until a draft of a [[ReplayGain 2.0 specification|revised specification]] started being written.

==Clipping==
Audio is generally recorded such that the loudest sounds don't clip, but the use of ReplayGain can cause clipping if the average volume of a song is below the target level. That is, upon playback, the volume of a quiet song is increased, so the parts of the song with above-average loudness, especially in the bass frequencies, will exceed the limits of the format and will be distorted. Whether this distortion is audible depends on the sounds in question, and the listener's sensitivity.

Implementations deal with the risk of clipping in different ways. Some have a "pre-amp" feature which reduces (or boosts) the original audio's level by a certain amount before doing whatever is needed for ReplayGain. Some have a "prevent clipping" feature to reduce the amount of ReplayGain adjustment to whatever amount would keep clipping from occurring, based on peak info stored in the file's metadata (thus reducing the effectiveness of ReplayGain). Some recommend using a compressor/limiter DSP to prevent or reduce clipping, regardless of whether it was caused by ReplayGain.

An alternative that may reduce the risk of clipping is the [https://tech.ebu.ch/docs/r/r128.pdf EBU R 128] recommendation of a '''-23''' '''LUFS''' target, although some may find the additional reduction in volume excessive, particularly if it leads to maxing out volume on user hardware. [[Opus]] in particular has adopted that recommendation.

== Implementations ==
There are different ReplayGain implementations, each with its own uses and strength. Most use [[metadata]] to indicate the level of the volume change that the player should make. Some modify the audio data itself, and optionally use metadata as well. There are advantages and disadvantages to both methods.

In the metadata method, information on both types of ReplayGain (Track Gain and Album Gain) can be stored. The volume-change information can be very precise. If audio data was also changed, the metadata can contain "undo" info. Not all audio players/decoders know how to read and use ReplayGain information stored in metadata. And there's no standard for where and how ReplayGain info is stored; each implementation uses different formats and puts the info in different locations.

In the audio data method, the file's actual audio data is modified so that its natural/default playback volume is at the target level. In this scenario, only one type of ReplayGain (Track Gain or Album Gain) can be applied. If no "undo" info is saved somewhere, it may not be possible to restore the original audio data. Limitations of the audio file format may prevent precise (finely tuned) gain adjustments with this method. For example, MP3 and AAC files can only be losslessly modified in 1.5 dB steps. Depending on the audio file format, the process may also be lossy in the sense that it could irreversibly push a signal above the format's maximum amplitude (resulting in clipping) or below the minimum (resulting in silence).

=== Old versus new algorithms ===
Since the ReplayGain standard does not define tags to specify which algorithm was used (classic or ITU-R BS.1770) or what target was set (RG's -18 LUFS, EBU R 128's -23 LUFS, or any other target set by the user or some piece of software), there may be confusion as to how the results were produced. Typically, utilities that ship with reference encoders (FLAC / metaflac, Vorbis / vorbisgain, WavPack / wvgain, Musepack / mpcgain…) use the original RG algorithm, which can produce values that differ from newer tools by several decibels in certain cases. Generally speaking, it is recommended to run other utilities or players that implement the ITU-R BS.1770 algorithm, although it may not be obvious which algorithm they use at first glance. Their documentation may provide that information.

==== RG1, RG2 ====
Although there are many references online, and within ReplayGain scanners, about version 1 vs. version 2 of the ReplayGain standard, at the time of writing this, there is (admittedly) only one ReplayGain standard. The core principle, as well as the 4 tags from the original specification, have not changed. More tags have been proposed but they are still subject to debate. As a rule of thumb, tools that advertise "ReplayGain 2" compliance employ the newer, more accurate ITU-R BS.1770 algorithm. [[foobar2000]] labels it "EBU R128" but it essentially means the same thing. Should a better algorithm be developed in the future, it will still work towards fulfilling ReplayGain's original goals, and probably write the same tags.

=== MP3Gain ===
[[MP3Gain]] is an implementation of classic ReplayGain. It can be used to just analyze files & recommend changes or to also modify the gain. If modifying the gain, it always modifies the global gain fields in the MP3 audio data. It can add somewhat precise metadata, including undo info. The gain can be modified to any target dB, or it can be changed by a specified amount. For balance correction, user-specified changes can even be made on just one channel in simple L/R stereo-mode files (not joint stereo).

* Format: [[MP3]]
* Method: Audio + Meta (in APE tag), or Audio only
* APE tag fields (ASCII bytes):
** <code>MP3GAIN_MINMAX ###,###</code> - minimum & maximum global gain values for this file. 3 digits, zero-padded if necessary.
** <code>MP3GAIN_ALBUM_MINMAX ###,###</code> - minimum & maximum global gain values across a set of files scanned as an album. Optional.
** <code>MP3GAIN_UNDO +###,+###,N</code> - the global gain adjustment to restore the original values in the left and right channels, respectively, followed by an indicator of whether to wrap at the extremes (<code>N</code> means no, <code>W</code> means yes). The adjustment values are 3 digits, zero-padded, preceded by a sign (<code>+</code> or <code>-</code>).
** <code>REPLAYGAIN_TRACK_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Examples: <code>+0.424046</code> and <code>-10.38500</code>
** <code>REPLAYGAIN_TRACK_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Example: <code>0.149923</code>
** <code>REPLAYGAIN_ALBUM_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Optional.
** <code>REPLAYGAIN_ALBUM_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Optional.
* Limitations: Although the metadata, if written, contains precise adjustment & peak values, the audio data modifications are limited to 1.5dB steps and may become irreversible (however, that's a very rare condition; see the [https://hydrogenaud.io/index.php/topic,34154.0.html "mp3gain is NOT lossless" forum thread])
* http://mp3gain.sourceforge.net/

=== AACGain ===
[[AACGain]] is a modified version of MP3Gain that works on both MP3 and AAC files.

* Format: [[MP3]], [[AAC]] (with or without MP4 container)
* Method: Audio + Meta, or Audio only
* Limitations: Limited to 1.5dB steps mode, may become irreversible (same caveat as for MP3Gain)
* http://aacgain.altosdesign.com/

=== [[LAME]] ===
* Method: Header ([http://gabriel.mp3-tech.org/mp3infotag.html mp3infotag])
* Notes:
** Uses the classic RG algorithm.
** Tags added during encoding; not supported by any player yet; Track Gain only
** Replay Gaining MP3's is usually done using MP3Gain (see [[ReplayGain#MP3Gain|above]]) or [[ReplayGain#foobar2000 ReplayGain scanner|foobar2000]]
* http://lame.sourceforge.net/

=== [[Musepack]] ReplayGain ===
* Method: Header (similar to Meta data method)
* Notes: Uses the classic RG algorithm. ReplayGain values are stored in the header and ReplayGain is part of the Musepack specifications; therefore any Musepack decoder that does not support ReplayGain can be considered broken.
* http://www.musepack.net/

=== VorbisGain ===
* Format: (Ogg) [[Vorbis]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://www.sjeng.org/vorbisgain.html
** new compiles of VorbisGain at [http://www.rarewares.org/ogg.html www.rarewares.org]
:'''''Note:''' Andavari has provided a very useful script to integrate VorbisGain, which is a CLI tool, into Windows Explorer. Please (Ogg) [[Vorbis#ReplayGain|check this section]].''

=== FLAC / METAFLAC ===
* Format: [[Free Lossless Audio Codec|FLAC]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://flac.sf.net

=== WavPack / WVGAIN ===
* Format: [[WavPack]]
* Method: Meta (in [[APEv2]] tag)
* Uses the classic RG algorithm.
* http://www.wavpack.com

=== Wavegain ===
* Format: waveform
* Method: Audio
* Uses the classic RG algorithm.
* Limitations: Irreversible
* http://www.rarewares.org/others.php#wavegain

=== MusicPlayer ===
* Custom implementation, inspired by MP3Gain.
* Format: any that FFmpeg supports
* Method: Audio
* Limitations: Doesn't modify the files at all. Stores the value in own database. Used only for playback.
* https://github.com/albertz/music-player

=== [[foobar2000]] ReplayGain scanner ===
* Since v1.1.6, defaults to ITU-R BS.1770 analysis (although it labels it EBU R128), but can be configured to use the "Classic ReplayGain" algorithm instead. The ITU-R BS.1770 implementation uses a reference level of -18 LUFS instead of -23, in order to retain compatibility with the ReplayGain standard.
* Format:
** [[MP3]]: Values written to [[ID3v2]] (default) or [[APEv2]] tags.
** [[Musepack]]: Values written to header.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]] and/or file header.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags. As with MP3, it is also an option to apply gain via a separate function.
** [[MP4]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain). Can write chosen Gain value to Apple's SoundCheck
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[TAK]]: Values written to [[APEv2]] tags.
** [[TTA]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** [[WMA]]: Values written to WMA tags.
** Modules ([[MOD]] etc.): Optionally saved into [[APEv2]] tags.
** Any non-taggable format or format supported by FFmpeg can store RG values in a database or external tag with a component.
** A separate function can be invoked to apply the tagged Track or Album Gain to the global gain fields in MP3, MP4 (AAC), or Opus files, and rewrite any existing tags to account for the peak change and compensate for the difference from 89 dB. The 89 dB reference level for tags isn't configurable, but the reference level applied to the global gain fields is.
* https://foobar2000.org/

=== [[MediaMonkey]] ===
* Format:
** [[MP3]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in MediaMonkey's MDB database.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[WAV]]: Values stored in MediaMonkey's MDB database.
** [[MPC]]: Internal gain Structure.
* In addition to tags, all ReplayGain values are also stored in MediaMonkey's MDB database
* Album/Audiophile ReplayGain not supported until v3.0 (Dec 2007); support during burning & ripping added in 3.1 (Jun 2009)
* Also capable of (irreversibly) changing the volume of MP3 tracks, similar to [[MP3Gain]]
* http://www.mediamonkey.com/

=== [[Winamp]] ReplayGain scanner===
* Format:
** [[MP3]]: Values written to [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in Windows Media Audio tags.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags.
** [[MP4]]
** [[TAK]]: Values written to [[APEv2]] tags.
* Support Album/Track Gain

=== [[loudgain]] ===
* Format:
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** MP2, [[MP3]]: Values written to [[ID3v2]] tags (ID3v2.3/ID3v2.4 selectable).
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** (Ogg) [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** (Ogg) [[Speex]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]], based on -23 LUFS Opus standard. Only <code>R128_TRACK_GAIN</code> and <code>R128_ALBUM_GAIN</code> are written, but the calculated ''true peak'' value can still be used to reduce the gain values ([[Clipping]] prevention).
** [[MP4]], [[M4A]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain). ReplayGain values are stored under <code>----:com.apple.iTunes:…</code>. This is for [[AAC]] and [[ALAC]] in [[MPEG-4]] containers.
** [[ASF]], [[Windows Media Audio|WMA]]: Values written to WMA tags, no prefix.
** [[WAV]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] (ID3v2.3/ID3v2.4 selectable) format. Using the <code>bext</code> chunk (for BWF v2) isn’t (yet) supported, but won’t be destroyed on writing.
** [[Audio Interchange File Format|AIFF]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] format.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[Monkey's Audio]] (APE): Values written to [[APEv2]] tags.
* Follows EBU R128, ITU BS.1770 and the [[ReplayGain 2.0 specification|revised ReplayGain specification]].
* ''Never'' touches the actual audio data but ''only writes RG2 tags''.
* Uses ''true peak'' values calculated by oversampling to 192 kHz, using a custom polyphase FIR interpolator that will oversample 4x for sample rates < 96 kHz, 2x for sample rates < 192 kHz and leave the signal unchanged for 192 kHz.
* ''Clipping prevention'' can be used to lower the ReplayGain values to a safe margin (default -1 dBTP, can be changed).
* Many options for special cases: force RG tags upper-/lowercase, add extra tags (LRA, Reference loudness), strip unwanted tag types (APEv2 from MP2/MP3, ID3 from WavPack), tab-delimited table output for analysis with CSV file.
* ''Linux'' Free and Open Source software, can be installed on ''MacOS'' using ''HomeBrew'', on ''Windows 10'' using the Linux ''bash''.
* Also installs a <code>rgbpm</code> bash script for mass-tagging, which can be adapted to the user’s needs.
* '''Warning:''' Loudgain relies on standard libraries like ''TagLib''. Linux distros (except rolling releases) sometimes deliver outdated libraries, so be sure you use the latest version of ''TagLib''. Version 1.11.1 had a nasty bug for a while that [https://hydrogenaud.io/index.php/topic,118085.msg974957.html#msg974957 could corrupt Ogg Vorbis files]. This has been fixed in the meantime but the TagLib version not updated. Loudgain comes with a (slower) static version called <code>loudgain.static</code> in the repo’s <code>/bin</code> folder that doesn’t expose the bug and can also be used on older Linux versions (like Ubuntu 14.04, Linux Mint 17).
* https://github.com/Moonbase59/loudgain
* Bug tracker: https://github.com/Moonbase59/loudgain/issues

=== [[rsgain]] ===
rsgain is a newer ReplayGain command line utility designed with a "batteries included" philosophy, use the newer ITU-R BS.1770 algorithm.

Features:
* Cross-platform Windows / macOS / Linux
* Supports all popular audio formats
* Simplified "Easy Mode" command line syntax supports recursive, directory-based scanning
* Multithreaded scanning option that provides significant speed improvement with full library scans
* Option to skip files with existing ReplayGain metadata
* Scan presets allow the user to save advanced settings for consistent use

== Players support ==
ReplayGain being present in the specs of the FLAC, Musepack, and APE formats, any player that support those formats usually supports ReplayGain.

The situation with MP3 is rather different, as it was not part of the MP3 specs. The APEv2 tags metadata implementation is somewhat becoming the de-facto standard.

=== Windows ===
* [[foobar2000]] supports ReplayGain in all possible aspects.
* [[Winamp]] supports ReplayGain in album or track mode.
* [[MediaMonkey]] supports ReplayGain, with many configuration options.
* [[XMPlay]] recently implemented ReplayGain
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.

''...and probably others.''

=== Linux ===
* [[XMMS]]. Reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], [[Musepack]], (Ogg) [[Vorbis]] ..
:For [[MP3]], use the CVS version of the [http://xmms-mad.sourceforge.net/ xmms-mad] mp3 plugin (it's not yet released as binary, furthermore not available in distribs' versions for now. Meanwhile binaries are available here: [http://perso.crans.org/~krempp/xmms-mad/ custom binaries])
* [[amarok]]. By using the amarok-script [http://kde-apps.org/content/show.php?content=26073 ReplayGain]
:And possibly others, since [http://developer.kde.org/~wheeler/taglib.html TagLib] added support for [[APEv2]] tags in [[MP3]] files, players using this library (like [[amaroK]] and [[JuK]]) might support that kind of ReplayGain tags in the near future.
* [http://www.sacredchao.net/quodlibet Quod Libet] reads ReplayGain from (Ogg) [[Vorbis]], [[MP3]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:Requires support to be enabled (via the appropriate python bindings and libraries) for the above formats. Does not support ReplayGain values stored in [[APEv2]] tags in [[MP3]]s. ReplayGain values are stored in RVA2 id3v2.4 frames. See the [http://www.sacredchao.net/quodlibet/wiki/Development/ID3Notes Quod Libet RVA2 / ReplayGain notes].
* [http://www.musicpd.org/ Music Player Daemon] (MPD) reads ReplayGain from (Ogg) [[Vorbis]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:foobar2000-style TXXX frames in [[MP3]]s are also supported in the latest development releases.
* [http://www.mplayerhq.hu/ MPlayer]. Mplayer support for ReplayGain is codec dependent.
:Codecs that are known to support ReplayGain: vorbis
:Because of this, you need to prioritize the codecs that support it, or choose it individually on the command line. To add it to the command line, add an -ac [codec] option after each file that you want to choose the codec for, or at the beginning to make it apply to all files listed. To prioritize the codecs by default, list them in a line in mplayer.conf:
ac=[codec],[othercodec],vorbis,mad,
* [http://idjc.sourceforge.net/ IDJC] (Internet DJ Console) reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], (Ogg) FLAC, (Ogg) [[Vorbis]], MP2 (audio), [[MP3]], [[Opus]], but only the ''lowercase'' tags. There is a [https://sourceforge.net/p/idjc/bugs/100/ ticket] open to handle tags case-insensitively.
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.
* [https://www.videolan.org/vlc/ VLC] supports ReplayGain in many file formats, but usually only the ''uppercase'' variant of the tags.
* [https://kodi.tv/ KODI] reads ReplayGain from nearly all formats, but usually only the ''lowercase'' variant of the tags.

=== Portable devices ===
[http://www.rockbox.org/ Rockbox] supports ReplayGain (in album or track mode) for most formats, including WMA, MP1/2/3, AAC, ALAC, Musepack, Monkey's Audio, Wavpack, FLAC and Vorbis. Note that ReplayGain is only supported when using the respective codec's native tagging format. For example: ReplayGain stored in APEv2 tags is not supported for MP3, rather ID3v2.x tags are expected.

Sandisk Sansa Fuze with firmware 1.02.26 and 2.02.26

Sandisk Sansa Clip+

The iPod features ''Soundcheck'', which seems to produce roughly the same normalization gains as ReplayGain, but doesn't provide an Album Gain.

=== Hi-Fi ===
Slim Devices, a company owned by Logitech Inc, supports ReplayGain on both of their hi-end audiophile players, known as the [[Slim Devices Transporter|Transporter]] and the [[Slim Devices Squeezebox|Squeezebox]].

BluOS also supports ReplayGain with the selection of album- or track-gain and a so called Smart option that decides between the two by itself.
NAD devices that use BluOS consequently also support ReplayGain.

==Notes==
<references/>

== See also ==
* [[ReplayGain specification]]

== External links ==
* [http://en.wikipedia.org/wiki/Replay_Gain ReplayGain] at Wikipedia
* [http://www.bobulous.org.uk/misc/Replay-Gain.html ReplayGain using foobar2000] (how to use ReplayGain in Windows using foobar2000).
* [http://www.bobulous.org.uk/misc/Replay-Gain-in-Linux.html ReplayGain in Linux] (how to use ReplayGain in Linux using foobar2000 and Wine, or using metaflac or vorbisgain).

[[index.php?title=Category:Technical]]
[[index.php?title=Category:Metadata]]

ReplayGain

2026-01-23T07:48:40Z

Case: /* MusicPlayer */

'''ReplayGain''' is the name of a technique invented to achieve the same perceived playback loudness of audio files. It defines an algorithm to measure the '''perceived''' loudness of audio data.

ReplayGain allows the loudness of each song within a collection of songs to be consistent. This is called 'Track Gain' (or 'Radio Gain' in earlier parlance). It also allows the loudness of a specific sub-collection (an "album") to be consistent with the rest of the collection, while allowing the dynamics from song to song on the album to remain intact. This is called 'Album Gain' (or 'Audiophile Gain' in earlier parlance). This is especially important when listening to classical music albums, because quiet tracks need to remain a certain degree quieter than the louder ones.

ReplayGain is different from [[Normalization|peak normalization]]. Peak normalization merely ensures that the peak amplitude reaches a certain level. This does not ensure equal loudness. The ReplayGain technique measures the ''effective power'' of the waveform (i.e. the RMS power after applying an "equal loudness contour"), and then adjusts the amplitude of the waveform accordingly. The result is that Replay Gained waveforms are usually more uniformly amplified than peak-normalized waveforms.

==Target loudness==
The target loudness of almost all ReplayGain utilities is 89 dB SPL when replayed in an SMPTE RP 200 calibrated system (an early departure from the proposal, endorsed by its author<ref>[http://www.hydrogenaudio.org/forums/index.php?s=&showtopic=83397&view=findpost&p=721854 Does Replay gain work differtly in Media monkey]</ref>) — the ReplayGain proposal and SMPTE recommendation are 6 dB lower.<ref>[http://www.mars.org/mailman/public/mad-dev/2004-February/000993.html ReplayGain discussion at mad-dev]</ref> The target loudness may be more commonly known and understood as '''-18''' '''[https://en.wikipedia.org/wiki/LUFS LUFS]''' (''Loudness Units relative to Full Scale'').

Some utilities have realized the inadequacies of the classic ReplayGain loudness calculation, switching to a more modern algorithm ([https://www.itu.int/rec/R-REC-BS.1770-5-202311-I/en ITU-R BS.1770]). However, the way it was integrated was extremely ''ad hoc'', at least until a draft of a [[ReplayGain 2.0 specification|revised specification]] started being written.

==Clipping==
Audio is generally recorded such that the loudest sounds don't clip, but the use of ReplayGain can cause clipping if the average volume of a song is below the target level. That is, upon playback, the volume of a quiet song is increased, so the parts of the song with above-average loudness, especially in the bass frequencies, will exceed the limits of the format and will be distorted. Whether this distortion is audible depends on the sounds in question, and the listener's sensitivity.

Implementations deal with the risk of clipping in different ways. Some have a "pre-amp" feature which reduces (or boosts) the original audio's level by a certain amount before doing whatever is needed for ReplayGain. Some have a "prevent clipping" feature to reduce the amount of ReplayGain adjustment to whatever amount would keep clipping from occurring, based on peak info stored in the file's metadata (thus reducing the effectiveness of ReplayGain). Some recommend using a compressor/limiter DSP to prevent or reduce clipping, regardless of whether it was caused by ReplayGain.

An alternative that may reduce the risk of clipping is the [https://tech.ebu.ch/docs/r/r128.pdf EBU R 128] recommendation of a '''-23''' '''LUFS''' target, although some may find the additional reduction in volume excessive, particularly if it leads to maxing out volume on user hardware. [[Opus]] in particular has adopted that recommendation.

== Implementations ==
There are different ReplayGain implementations, each with its own uses and strength. Most use [[metadata]] to indicate the level of the volume change that the player should make. Some modify the audio data itself, and optionally use metadata as well. There are advantages and disadvantages to both methods.

In the metadata method, information on both types of ReplayGain (Track Gain and Album Gain) can be stored. The volume-change information can be very precise. If audio data was also changed, the metadata can contain "undo" info. Not all audio players/decoders know how to read and use ReplayGain information stored in metadata. And there's no standard for where and how ReplayGain info is stored; each implementation uses different formats and puts the info in different locations.

In the audio data method, the file's actual audio data is modified so that its natural/default playback volume is at the target level. In this scenario, only one type of ReplayGain (Track Gain or Album Gain) can be applied. If no "undo" info is saved somewhere, it may not be possible to restore the original audio data. Limitations of the audio file format may prevent precise (finely tuned) gain adjustments with this method. For example, MP3 and AAC files can only be losslessly modified in 1.5 dB steps. Depending on the audio file format, the process may also be lossy in the sense that it could irreversibly push a signal above the format's maximum amplitude (resulting in clipping) or below the minimum (resulting in silence).

=== Old versus new algorithms ===
Since the ReplayGain standard does not define tags to specify which algorithm was used (classic or ITU-R BS.1770) or what target was set (RG's -18 LUFS, EBU R 128's -23 LUFS, or any other target set by the user or some piece of software), there may be confusion as to how the results were produced. Typically, utilities that ship with reference encoders (FLAC / metaflac, Vorbis / vorbisgain, WavPack / wvgain, Musepack / mpcgain…) use the original RG algorithm, which can produce values that differ from newer tools by several decibels in certain cases. Generally speaking, it is recommended to run other utilities or players that implement the ITU-R BS.1770 algorithm, although it may not be obvious which algorithm they use at first glance. Their documentation may provide that information.

==== RG1, RG2 ====
Although there are many references online, and within ReplayGain scanners, about version 1 vs. version 2 of the ReplayGain standard, at the time of writing this, there is (admittedly) only one ReplayGain standard. The core principle, as well as the 4 tags from the original specification, have not changed. More tags have been proposed but they are still subject to debate. As a rule of thumb, tools that advertise "ReplayGain 2" compliance employ the newer, more accurate ITU-R BS.1770 algorithm. [[foobar2000]] labels it "EBU R128" but it essentially means the same thing. Should a better algorithm be developed in the future, it will still work towards fulfilling ReplayGain's original goals, and probably write the same tags.

=== MP3Gain ===
[[MP3Gain]] is an implementation of classic ReplayGain. It can be used to just analyze files & recommend changes or to also modify the gain. If modifying the gain, it always modifies the global gain fields in the MP3 audio data. It can add somewhat precise metadata, including undo info. The gain can be modified to any target dB, or it can be changed by a specified amount. For balance correction, user-specified changes can even be made on just one channel in simple L/R stereo-mode files (not joint stereo).

* Format: [[MP3]]
* Method: Audio + Meta (in APE tag), or Audio only
* APE tag fields (ASCII bytes):
** <code>MP3GAIN_MINMAX ###,###</code> - minimum & maximum global gain values for this file. 3 digits, zero-padded if necessary.
** <code>MP3GAIN_ALBUM_MINMAX ###,###</code> - minimum & maximum global gain values across a set of files scanned as an album. Optional.
** <code>MP3GAIN_UNDO +###,+###,N</code> - the global gain adjustment to restore the original values in the left and right channels, respectively, followed by an indicator of whether to wrap at the extremes (<code>N</code> means no, <code>W</code> means yes). The adjustment values are 3 digits, zero-padded, preceded by a sign (<code>+</code> or <code>-</code>).
** <code>REPLAYGAIN_TRACK_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Examples: <code>+0.424046</code> and <code>-10.38500</code>
** <code>REPLAYGAIN_TRACK_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Example: <code>0.149923</code>
** <code>REPLAYGAIN_ALBUM_GAIN +#.###### dB</code> - The value is always 9 characters including the sign and decimal point. Optional.
** <code>REPLAYGAIN_ALBUM_PEAK #.###### dB</code> - The value is always 8 characters including the decimal point. Optional.
* Limitations: Although the metadata, if written, contains precise adjustment & peak values, the audio data modifications are limited to 1.5dB steps and may become irreversible (however, that's a very rare condition; see the [https://hydrogenaud.io/index.php/topic,34154.0.html "mp3gain is NOT lossless" forum thread])
* http://mp3gain.sourceforge.net/

=== AACGain ===
[[AACGain]] is a modified version of MP3Gain that works on both MP3 and AAC files.

* Format: [[MP3]], [[AAC]] (with or without MP4 container)
* Method: Audio + Meta, or Audio only
* Limitations: Limited to 1.5dB steps mode, may become irreversible (same caveat as for MP3Gain)
* http://aacgain.altosdesign.com/

=== [[LAME]] ===
* Method: Header ([http://gabriel.mp3-tech.org/mp3infotag.html mp3infotag])
* Notes:
** Uses the classic RG algorithm.
** Tags added during encoding; not supported by any player yet; Track Gain only
** Replay Gaining MP3's is usually done using MP3Gain (see [[ReplayGain#MP3Gain|above]]) or [[ReplayGain#foobar2000 ReplayGain scanner|foobar2000]]
* http://lame.sourceforge.net/

=== [[Musepack]] ReplayGain ===
* Method: Header (similar to Meta data method)
* Notes: Uses the classic RG algorithm. ReplayGain values are stored in the header and ReplayGain is part of the Musepack specifications; therefore any Musepack decoder that does not support ReplayGain can be considered broken.
* http://www.musepack.net/

=== VorbisGain ===
* Format: (Ogg) [[Vorbis]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://www.sjeng.org/vorbisgain.html
** new compiles of VorbisGain at [http://www.rarewares.org/ogg.html www.rarewares.org]
:'''''Note:''' Andavari has provided a very useful script to integrate VorbisGain, which is a CLI tool, into Windows Explorer. Please (Ogg) [[Vorbis#ReplayGain|check this section]].''

=== FLAC / METAFLAC ===
* Format: [[Free Lossless Audio Codec|FLAC]]
* Method: Meta (in [[Vorbis comment]])
* Uses the classic RG algorithm.
* http://flac.sf.net

=== WavPack / WVGAIN ===
* Format: [[WavPack]]
* Method: Meta (in [[APEv2]] tag)
* Uses the classic RG algorithm.
* http://www.wavpack.com

=== Wavegain ===
* Format: waveform
* Method: Audio
* Uses the classic RG algorithm.
* Limitations: Irreversible
* http://www.rarewares.org/others.php#wavegain

=== MusicPlayer ===
* Custom implementation, inspired by MP3Gain.
* Format: any that FFmpeg supports
* Method: Audio
* Limitations: Doesn't modify the files at all. Stores the value in own database. Used only for playback.
* https://github.com/albertz/music-player

=== [[foobar2000]] ReplayGain scanner ===
* Since v1.1.6, defaults to ITU-R BS.1770 analysis (although it labels it EBU R128), but can be configured to use the "Classic ReplayGain" algorithm instead. The ITU-R BS.1770 implementation uses a reference level of -18 LUFS instead of -23, in order to retain compatibility with the ReplayGain standard.
* Format:
** [[MP3]]: Values written to [[ID3v2]] (default) or [[APEv2]] tags. A separate function can be invoked to apply the tagged Track or Album Gain to the MP3 global gain fields (as MP3Gain does), and rewrite any existing tags to account for the peak change and compensate for the difference from 89 dB. The 89 dB reference level for tags isn't configurable, but the reference level applied to the global gain fields is (it's under Preferences > Advanced > Tools > ReplayGain Scanner > Target MP3 alteration volume level).
** [[Musepack]]: Values written to header.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags. As with MP3, it is also an option to apply gain via a separate function.
** [[MP4]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain).
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** Modules ([[MOD]] etc.): Optionally saved into [[APEv2]] tags.
* https://foobar2000.org/

=== [[MediaMonkey]] ===
* Format:
** [[MP3]]: Values written to [[APEv2]] or [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in MediaMonkey's MDB database.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[WAV]]: Values stored in MediaMonkey's MDB database.
** [[MPC]]: Internal gain Structure.
* In addition to tags, all ReplayGain values are also stored in MediaMonkey's MDB database
* Album/Audiophile ReplayGain not supported until v3.0 (Dec 2007); support during burning & ripping added in 3.1 (Jun 2009)
* Also capable of (irreversibly) changing the volume of MP3 tracks, similar to [[MP3Gain]]
* http://www.mediamonkey.com/

=== [[Winamp]] ReplayGain scanner===
* Format:
** [[MP3]]: Values written to [[ID3v2]] tags.
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** [[WMA]]: Values stored in Windows Media Audio tags.
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** [[APE]]: Values written to [[APEv2]] tags.
** [[AAC]]: Values written to [[APEv2]] tags.
** [[MP4]]
** [[TAK]]: Values written to [[APEv2]] tags.
* Support Album/Track Gain

=== [[loudgain]] ===
* Format:
** [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** MP2, [[MP3]]: Values written to [[ID3v2]] tags (ID3v2.3/ID3v2.4 selectable).
** (Ogg) [[Vorbis]]: Values written to [[Vorbis comment]].
** (Ogg) [[Free Lossless Audio Codec|FLAC]]: Values written to [[Vorbis comment]].
** (Ogg) [[Speex]]: Values written to [[Vorbis comment]].
** [[Opus]]: Values written to [[Vorbis comment]], based on -23 LUFS Opus standard. Only <code>R128_TRACK_GAIN</code> and <code>R128_ALBUM_GAIN</code> are written, but the calculated ''true peak'' value can still be used to reduce the gain values ([[Clipping]] prevention).
** [[MP4]], [[M4A]]: Uses its own iTunes-compatible tagging system (though iTunes does not support ReplayGain). ReplayGain values are stored under <code>----:com.apple.iTunes:…</code>. This is for [[AAC]] and [[ALAC]] in [[MPEG-4]] containers.
** [[ASF]], [[Windows Media Audio|WMA]]: Values written to WMA tags, no prefix.
** [[WAV]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] (ID3v2.3/ID3v2.4 selectable) format. Using the <code>bext</code> chunk (for BWF v2) isn’t (yet) supported, but won’t be destroyed on writing.
** [[Audio Interchange File Format|AIFF]]: Values written to the <code>ID3 </code> chunk, in [[ID3v2]] format.
** [[WavPack]]: Values written to [[APEv2]] tags.
** [[Monkey's Audio]] (APE): Values written to [[APEv2]] tags.
* Follows EBU R128, ITU BS.1770 and the [[ReplayGain 2.0 specification|revised ReplayGain specification]].
* ''Never'' touches the actual audio data but ''only writes RG2 tags''.
* Uses ''true peak'' values calculated by oversampling to 192 kHz, using a custom polyphase FIR interpolator that will oversample 4x for sample rates < 96 kHz, 2x for sample rates < 192 kHz and leave the signal unchanged for 192 kHz.
* ''Clipping prevention'' can be used to lower the ReplayGain values to a safe margin (default -1 dBTP, can be changed).
* Many options for special cases: force RG tags upper-/lowercase, add extra tags (LRA, Reference loudness), strip unwanted tag types (APEv2 from MP2/MP3, ID3 from WavPack), tab-delimited table output for analysis with CSV file.
* ''Linux'' Free and Open Source software, can be installed on ''MacOS'' using ''HomeBrew'', on ''Windows 10'' using the Linux ''bash''.
* Also installs a <code>rgbpm</code> bash script for mass-tagging, which can be adapted to the user’s needs.
* '''Warning:''' Loudgain relies on standard libraries like ''TagLib''. Linux distros (except rolling releases) sometimes deliver outdated libraries, so be sure you use the latest version of ''TagLib''. Version 1.11.1 had a nasty bug for a while that [https://hydrogenaud.io/index.php/topic,118085.msg974957.html#msg974957 could corrupt Ogg Vorbis files]. This has been fixed in the meantime but the TagLib version not updated. Loudgain comes with a (slower) static version called <code>loudgain.static</code> in the repo’s <code>/bin</code> folder that doesn’t expose the bug and can also be used on older Linux versions (like Ubuntu 14.04, Linux Mint 17).
* https://github.com/Moonbase59/loudgain
* Bug tracker: https://github.com/Moonbase59/loudgain/issues

=== [[rsgain]] ===
rsgain is a newer ReplayGain command line utility designed with a "batteries included" philosophy, use the newer ITU-R BS.1770 algorithm.

Features:
* Cross-platform Windows / macOS / Linux
* Supports all popular audio formats
* Simplified "Easy Mode" command line syntax supports recursive, directory-based scanning
* Multithreaded scanning option that provides significant speed improvement with full library scans
* Option to skip files with existing ReplayGain metadata
* Scan presets allow the user to save advanced settings for consistent use

== Players support ==
ReplayGain being present in the specs of the FLAC, Musepack, and APE formats, any player that support those formats usually supports ReplayGain.

The situation with MP3 is rather different, as it was not part of the MP3 specs. The APEv2 tags metadata implementation is somewhat becoming the de-facto standard.

=== Windows ===
* [[foobar2000]] supports ReplayGain in all possible aspects.
* [[Winamp]] supports ReplayGain in album or track mode.
* [[MediaMonkey]] supports ReplayGain, with many configuration options.
* [[XMPlay]] recently implemented ReplayGain
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.

''...and probably others.''

=== Linux ===
* [[XMMS]]. Reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], [[Musepack]], (Ogg) [[Vorbis]] ..
:For [[MP3]], use the CVS version of the [http://xmms-mad.sourceforge.net/ xmms-mad] mp3 plugin (it's not yet released as binary, furthermore not available in distribs' versions for now. Meanwhile binaries are available here: [http://perso.crans.org/~krempp/xmms-mad/ custom binaries])
* [[amarok]]. By using the amarok-script [http://kde-apps.org/content/show.php?content=26073 ReplayGain]
:And possibly others, since [http://developer.kde.org/~wheeler/taglib.html TagLib] added support for [[APEv2]] tags in [[MP3]] files, players using this library (like [[amaroK]] and [[JuK]]) might support that kind of ReplayGain tags in the near future.
* [http://www.sacredchao.net/quodlibet Quod Libet] reads ReplayGain from (Ogg) [[Vorbis]], [[MP3]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:Requires support to be enabled (via the appropriate python bindings and libraries) for the above formats. Does not support ReplayGain values stored in [[APEv2]] tags in [[MP3]]s. ReplayGain values are stored in RVA2 id3v2.4 frames. See the [http://www.sacredchao.net/quodlibet/wiki/Development/ID3Notes Quod Libet RVA2 / ReplayGain notes].
* [http://www.musicpd.org/ Music Player Daemon] (MPD) reads ReplayGain from (Ogg) [[Vorbis]], [[Free Lossless Audio Codec|FLAC]], and [[Musepack]].
:foobar2000-style TXXX frames in [[MP3]]s are also supported in the latest development releases.
* [http://www.mplayerhq.hu/ MPlayer]. Mplayer support for ReplayGain is codec dependent.
:Codecs that are known to support ReplayGain: vorbis
:Because of this, you need to prioritize the codecs that support it, or choose it individually on the command line. To add it to the command line, add an -ac [codec] option after each file that you want to choose the codec for, or at the beginning to make it apply to all files listed. To prioritize the codecs by default, list them in a line in mplayer.conf:
ac=[codec],[othercodec],vorbis,mad,
* [http://idjc.sourceforge.net/ IDJC] (Internet DJ Console) reads ReplayGain from [[Free Lossless Audio Codec|FLAC]], (Ogg) FLAC, (Ogg) [[Vorbis]], MP2 (audio), [[MP3]], [[Opus]], but only the ''lowercase'' tags. There is a [https://sourceforge.net/p/idjc/bugs/100/ ticket] open to handle tags case-insensitively.
* [https://picard.musicbrainz.org/ MusicBrainz Picard] is a tagger (and player) that tags using metadata from the MusicBrainz.org database. Picard supports ReplayGain tags for files tagged with APE, ASF, ID3, MP4 and Vorbis tags. There is a ReplayGain plugin that can be used to calculate the ReplayGain values for both Albums and Tracks.
* [https://www.videolan.org/vlc/ VLC] supports ReplayGain in many file formats, but usually only the ''uppercase'' variant of the tags.
* [https://kodi.tv/ KODI] reads ReplayGain from nearly all formats, but usually only the ''lowercase'' variant of the tags.

=== Portable devices ===
[http://www.rockbox.org/ Rockbox] supports ReplayGain (in album or track mode) for most formats, including WMA, MP1/2/3, AAC, ALAC, Musepack, Monkey's Audio, Wavpack, FLAC and Vorbis. Note that ReplayGain is only supported when using the respective codec's native tagging format. For example: ReplayGain stored in APEv2 tags is not supported for MP3, rather ID3v2.x tags are expected.

Sandisk Sansa Fuze with firmware 1.02.26 and 2.02.26

Sandisk Sansa Clip+

The iPod features ''Soundcheck'', which seems to produce roughly the same normalization gains as ReplayGain, but doesn't provide an Album Gain.

=== Hi-Fi ===
Slim Devices, a company owned by Logitech Inc, supports ReplayGain on both of their hi-end audiophile players, known as the [[Slim Devices Transporter|Transporter]] and the [[Slim Devices Squeezebox|Squeezebox]].

BluOS also supports ReplayGain with the selection of album- or track-gain and a so called Smart option that decides between the two by itself.
NAD devices that use BluOS consequently also support ReplayGain.

==Notes==
<references/>

== See also ==
* [[ReplayGain specification]]

== External links ==
* [http://en.wikipedia.org/wiki/Replay_Gain ReplayGain] at Wikipedia
* [http://www.bobulous.org.uk/misc/Replay-Gain.html ReplayGain using foobar2000] (how to use ReplayGain in Windows using foobar2000).
* [http://www.bobulous.org.uk/misc/Replay-Gain-in-Linux.html ReplayGain in Linux] (how to use ReplayGain in Linux using foobar2000 and Wine, or using metaflac or vorbisgain).

[[index.php?title=Category:Technical]]
[[index.php?title=Category:Metadata]]

Foobar2000:Title Formatting Reference

2024-11-19T08:38:00Z

Case: /* $info(name) */

{{sidebar foobar2000 title formatting}}
This article contains information about built-in title formatting functions and field references, plus additional documentation about fields and functions which can only be used in specific components or which are provided by specific components.

Please see [[Foobar2000:Title Formatting Introduction|Title Formatting Introduction]] for a general overview of title format syntax and its basic rules. The article [[foobar2000:Titleformat Examples|Titleformat Examples]] offers user-submitted examples of code for specific purposes; feel free to add your own if you think it can be of use to others.

For details of the query syntax, which uses some of these fields to find files for playlists, etc., see the [[Foobar2000:Query_syntax|Query Syntax]] article.

== Syntax ==

A title formatting script consists of any combination of literal text, field references, function calls, comments, and line break characters. The script always outputs a text string (which can be empty).

A '''comment''' is a line starting with two slashes, e.g. {{code|// this is a comment}}.

A '''field reference''' is a field name enclosed in percent signs, for example {{code|%artist%}}.

A '''function call''' starts with a dollar sign, followed by the function name and the parameter list. A parameter list can either be empty – denoted as {{code|()}} – or contain one or more parameters separated by commas, for example {{code|$abbr(%artist%)}}. A parameter can be literal text, a field reference, or another function call. Note that there must be no whitespace between the dollar sign and the function name, or the function name and the opening parenthesis of the parameter list.

Any other text is '''literal text'''. In literal text, the character {{code|%}}, {{code|$}}, {{code|[}}, {{code|]}}, or {{code|'}} (apostrophe/single quote) must be escaped by enclosing it in {{code|'}} (apostrophe/single quote) characters. For example, {{code|'['}} (a left bracket in single quotes) results in a literal {{code|[}} (left bracket). As a special case, {{code|<nowiki>''</nowiki>}} (two single quotes in a row) results in one single quote. In the playlist, {{code|<}} and {{code|>}} are also special; see [[#Dimmed and highlighted text|Dimmed and highlighted text]].

When the script is evaluated, the output string is assembled by evaluating the function parameters, function calls, and field references. Comments and line break characters (CR and LF/newline) are ignored; to output a line break, use {{code|$crlf()}}. Each field reference becomes the field's value, as a string. Each function becomes a string or number, and/or a truth value (not output) which can be used by another function.

'''Note: The interface for entering custom columns and grouping schemes for the Default UI playlist does not support line breaks; scripts must be written all on one line, without comments.'''

== Arithmetic functions ==

The functions in this section can be used to perform arithmetic on integer numbers. A string will be automatically converted to a number and vice versa. The conversion to a number uses the longest prefix of the string that can be interpreted as number. Leading whitespace is ignored. Decimal points are not supported. Examples:
* ''c3po'' → 0
* ''4.8'' → 4
* ''-12'' → -12
* ''- 12'' → 0

=== $add(a,b, ...) ===

Adds ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$add(a,b,...)'' is the same as ''$add($add(a,b),...)''.

=== $div(a,b) ===

Divides ''a'' by ''b'' and rounds down to an integer. If ''b'' evaluates to zero, it returns ''a''.

Can be used with an arbitrary number of arguments. ''$div(a,b,...)'' is the same as ''$div($div(a,b),...)''.

=== $greater(a,b) ===

Returns true, if ''a'' is greater than ''b'', otherwise false.

=== $max(a,b) ===

Returns the maximum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$max(a,b,...)'' is the same as ''$max($max(a,b),...)''.

=== $min(a,b) ===

Returns the minimum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$min(a,b,...)'' is the same as ''$min($min(a,b),...)''.

=== $mod(a,b) ===

Computes the remainder of dividing ''a'' through ''b''. The result has the same sign as ''a''. If ''b'' evaluates to zero, the result is ''a''.

Can be used with an arbitrary number of arguments. ''$mod(a,b,...)'' is the same as ''$mod($mod(a,b),...)''.

=== $mul(a,b) ===

Multiplies ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$mul(a,b,...)'' is the same as ''$mul($mul(a,b),...)''.

=== $muldiv(a,b,c) ===

Multiplies ''a'' and ''b'', then divides by ''c''. The result is rounded to the nearest integer.

=== $rand() ===

Generates a random number in the range from 0 to 232-1. Available only in sort-related contexts, such as the ''Edit → Sort → Sort by ...'' menu command.

=== $sub(a,b) ===

Subtracts ''b'' from ''a''.

Can be used with an arbitrary number of arguments. ''$sub(a,b,...)'' is the same as ''$sub($sub(a,b),...)''.

== Boolean functions ==

The functions in this section can be used to work with truth values (''true'' and ''false''), which have no explicit representation in titleformat scripts. They do not return a string or number value. You can use them for more complex conditions with ''$if'' and related functions.

Foobar does not have a concept of TRUE and FALSE in a programming language sense where 0 or empty string are considered FALSE and other values TRUE. Therefore there is no difference between numeric 0 and string representation '0' which both are considered as values, and being attached a boolean value FALSE. Apostrophes are only required to escape certain syntax characters. Values are treated as numbers during arithmetic operations like'' $add()''.

=== $and(expr, ...) ===

Logical And of an arbitrary number of arguments. Returns ''true'', if and only if all ''expr'' arguments evaluate to ''true''.

=== $or(expr, ...) ===

Logical Or of an arbitrary number of arguments. Returns ''true'', if at least one expression evaluates to ''true''.

=== $not(expr) ===

Logical Not. Returns the logical opposite of EXPR: ''false'', if ''expr'' is ''true'' and ''true'' if ''expr'' is false.

=== $xor(expr,...) ===

Logical Exclusive-or of an arbitrary number of arguments. Returns ''true'', if an odd number of arguments evaluate to ''true''.

Special case: ''$xor(expr1,expr2)'' returns ''true'', if EXPR1 or EXPR2 is ''true''. If both expressions are true, returns ''false''.

== Control flow functions ==

The functions in this section can be used to conditionally execute statements.

=== [...] (conditional section) ===

Evaluates the expression between ''['' and '']''. If it has the truth value ''true'', its string value and the truth value ''true'' are returned. Otherwise an empty string and ''false'' are returned.

Example: ''[%artist%]'' returns the value of the artist tag, if it exists. Otherwise it returns nothing, when ''artist'' would return "?".

=== $if(cond,then) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, ''false'' is returned.

Plain strings are FALSE. Field lookups and functions can introduce a boolean value of TRUE. 
Examples: 
1
<code>
#False:
$if(0,True,False)
# False:
$if('0',True,False)
# True or False:
[$add(%rating%,1)]
</code> 
The last one would display the value of %rating% plus one, if and only if %rating% is set for the track.

2
Ignore inserting the %album artist%, if it contains the word "various".
<code>
# Wrong:
$if([%album artist%=Various],,%artist%-)
# Good approach:
$if($stricmp(%album artist%,Various),,%artist%-)
</code>

=== $if(cond,then,else) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, the ''else'' part is evaluated and its value returned.

=== $if2(expr,else) ===

Like ''$if(expr,expr,else)'' except that ''expr'' is only evaluated once. In other words, if expression ''expr'' is true, ''expr'' is returned, otherwise the ''else'' part is evaluated and ''expr'' is returned as true.

=== $if3(a1,a2,...,aN,else) ===

Evaluates arguments ''a1'' ... ''aN'', until one is found that evaluates to ''true''. If that happens, its value is returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifequal(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is equal to ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifgreater(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is greater than ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $iflonger(str,n,then,else) ===

Compares the length of the string ''str'' to the number ''n'', if ''str'' is longer than ''n'' characters, the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $select(n,a1,...,aN) ===

If the value of ''n'' is between 1 and N, ''an'' is evaluated and its value returned. Otherwise ''false'' is returned.

== String functions ==

The functions in this section can be used to manipulate character strings.

=== $abbr(str) ===

Returns abbreviation of string ''str''. Words which begin with an alphanumeric character are shortened to the first character. Spaces and parentheses are stripped. Example:
* $abbr('This is a Long Title (12-inch version) [needs tags]') → TiaLT1v[needst

=== $abbr(str,len) ===

Returns abbreviation of ''str'', if ''str'' is longer than ''len'' characters, otherwise returns ''str''.

=== $ansi(str) ===

Converts string ''str'' to system codepage and back. Any characters that are not present in the system codepage will be removed / replaced. Useful for mass-renaming files to ensure compatibility with non-unicode-capable software.

=== $ascii(str) ===

Converts string ''str'' to ASCII. Any characters that are not present in ASCII will be removed / replaced.

=== $caps(str) ===

Converts first letter in every word of string ''str'' to uppercase, and all other letters to lowercase.

=== $caps2(str) ===

Converts first letter in every word of string ''str'' to uppercase, and leaves all other letters as they are.

=== $char(nbr) ===

Returns Unicode character of ''nbr''. You can search for characters and find the matching decimal number on this [http://www.fileformat.info/info/unicode/char/search.htm site].

=== $crc32(str) ===

Computes the CRC32 of the string ''str'' as a number. Intended for use in coloring scripts.

Example: $rgb($mod($crc32(%album%),256),128,128)

=== $crlf() ===

Inserts end-of-line marker (carriage return, line feed). Can be used to generate multiple lines in the output, for example for the tooltip of the system notification area ("systray") icon.

=== $cut(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $left(a,len). Negative numbers produce the entire string. Examples:
* ''$cut('abc123',3)'' → abc
* ''$cut('abc123',0)'' → (nothing)
* ''$cut('abc123',-1)'' → abc123

=== $directory(path) ===

Extracts only the directory name (not full path, ie given path as 'D:\music\jazz\filename.mp3', this will output 'jazz') from the file ''path''.

=== $directory(path,n) ===

Extracts directory name from the file ''path''; goes up by ''n'' levels.

=== $directory_path(path) ===

Extracts directory path from the file ''path''.
ie. given path as 'D:\music\jazz\filename.mp3', this will output 'D:\music\jazz'

=== $ext(path) ===

Extracts file extension from string ''path''; a file name or full path.

=== $filename(path) ===

Extracts file name from full ''path''.

=== $fix_eol(str) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by " (...)". Otherwise ''str'' is returned unaltered.

=== $fix_eol(str,indicator) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by ''indicator''. Otherwise ''str'' is returned unaltered.

=== $hex(int,len) ===

Formats the integer number ''int'' in hexadecimal notation with ''len'' digits. Pads with zeros from the left if necessary.

=== $insert(str,insert,n) ===

Inserts ''insert'' into ''str'' after ''n'' characters.

=== $left(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $cut(str,len). Negative numbers produce the entire string. Examples:
* ''$left('abc123',3)'' → abc
* ''$left('abc123',0)'' → (nothing)
* ''$left('abc123',-1)'' → abc123

=== $len(str) ===

Returns length of string ''str'' in characters.

=== $len2(str) ===

Returns length of string ''str'' in characters, respecting double-width character rules (double-width characters will be counted as two).

=== $longer(str1,str2) ===

Returns ''true'', if string ''str1'' is longer than string ''str2'', false otherwise.

=== $lower(str) ===

Converts string ''str'' to lowercase.

=== $longest(arg,...) ===

Returns the longest of its arguments. Can be used with an arbitrary number of strings.

=== $num(nbr,len) ===

Formats the integer number ''nbr'' in decimal notation with ''len'' characters. Pads with zeros from the left if necessary. ''len'' includes the dash when the number is negative. If ''nbr'' is not numeric, it is treated as zero. Examples:

* ''$num(123,5)'' → 00123
* ''$num(-123,5)'' → -0123
* ''$num(4.8,5)'' → 00004
* ''$num(A1,5)'' → 00000

=== $pad(str,len) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad(str,len,char) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len,char) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $padcut(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the right of ''str'' to make the result ''len'' characters long.

=== $padcut(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the right of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the left of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the left of ''str'' to make the result ''len'' characters long.

=== $progress(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with.

Example:''$progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'#','=')'' produces "====#===============", the # character is moving with playback position.

=== $progress2(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with. Produces different appearance than ''$progress''.

=== $repeat(expr,count) ===

Returns ''count'' copies of ''expr''. Note that ''expr'' is evaluated once before its value is used, so ''$repeat'' cannot be used for loops.

=== $replace(str,search,replace) ===

Replaces all occurrences of string ''search'' in string ''str'' with string ''replace''.

Can also be used with an arbitrary number of arguments. Note that ''$replace(str,search1,replace1,search2,replace2)'' is generally not the same as ''$replace($replace(str,search1,replace1),search2,replace2)''.

Example: ''$replace(ab,a,b,b,c)'' → "bc", ''$replace($replace(ab,a,b),b,c)'' → "cc"

=== $right(str,len) ===

Returns the first ''len'' characters from the right of string ''str''.

=== $roman(int) ===

Formats the integer number ''int'' in roman notation.

=== $rot13(str) ===

Performs [http://en.wikipedia.org/wiki/ROT13 ROT13] transformation to given string.

Example: ''$rot13('foobar2000')'' → "sbbone2000".

=== $shortest(str,...strN) ===

Returns the first shortest element of its arguments. Can be used with an arbitrary number of strings.

=== $strchr(str,char) ===

Returns position of first occurrence of character ''char'' in string ''str''.

Example: ''$strchr(abca,a)'' → 1

=== $strrchr(str,char) ===

Returns positions of last occurrence of character ''char'' in string ''str''.

Example: ''$strrchr(abca,a)'' → 4

=== $strstr(str1,str2) ===

Returns position of first occurrence of string ''str2'' in string ''str1''. Function is case-sensitive.

=== $strcmp(str1,str2) ===

Performs a case-sensitive comparison of the strings ''str1'' and ''str2''.

=== $stricmp(str1,str2) ===

Performs a case-insensitive comparison of the strings ''str1'' and ''str2''.

=== $stripprefix(str) ===

Removes ''A'' and ''The'' prefixes from string ''str''.

=== $stripprefix(str,prefix1,prefix2,...) ===

Removes the specified prefixes from string ''str''.

=== $substr(str,from,to) ===

Returns substring of string ''str'', starting from ''FROM''-th character and ending at ''TO''-th character.

=== $swapprefix(str) ===

Moves ''A'' and ''The'' prefixes to the end of string ''str''.

=== $swapprefix(str,prefix1,prefix2,...) ===

Moves the specified prefixes to the end of string ''str''.

=== $trim(str) ===

Removes leading and trailing spaces from string ''str''.

=== $tab() ===

Inserts one tabulator character.

=== $tab(count) ===

Inserts ''count'' tabulator characters.

=== $upper(str) ===

Converts string ''str'' to uppercase.

== Track info fields and functions ==

The functions and fields in this section can be used to access information about tracks.

=== Metadata fields and functions ===

Generally, metadata from the files (whether in tags or a cue sheet) is mapped directly to a field which can be referenced case-insensitively. For example, the first tag named ''URL'' can be referenced as ''%url%'', and the first standard comment tag can be referenced as ''%comment%''.

The following functions are also available for accessing metadata:

==== $meta(name) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ", " as separator.

Example: ''$meta(artist)'' → "He, She, They"

==== $meta(name,n) ====
Returns value of ''n''-th (0,1,2 and so on) tag called ''name''.

Example: ''$meta(artist,1)'' → "She"

==== $meta_sep(name,sep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator.

Example: ''$meta_sep(artist,' + ')'' → "He + She + They"

==== $meta_sep(name,sep,lastsep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator between all but the last two values which are concatenated with ''lastsep''.

Example: ''$meta_sep(artist,', ',', and ')'' → "He, She, and They"

==== $meta_test(...) ====
Returns ''1'', if all given tags exist, ''undefined'' otherwise.

Example: ''$meta_test(artist,title)'' → true

==== $meta_num(name) ====
Returns the number of values for the tag called ''name''.

Example: ''$meta_num(artist)'' → 3

=== Remapped metadata fields ===

The following fields have special remapped values to make writing title format scripts more convenient:

==== %album artist% ====
Name of the artist of the album specified track belongs to. Checks following metadata fields, in this order: "album artist", "artist", "composer", "performer". The difference between this and ''%artist%'' is that ''%album artist%'' is intended for use where consistent value across entire album is needed even when per-track artists values vary.

==== %album% ====
Name of the album specified track belongs to. Checks following metadata fields, in this order: "album", "venue".

==== %artist% ====
Name of the artist of the track. Checks following metadata fields, in this order: "artist", "album artist", "composer", "performer". For a SHOUTcast stream which contains metadata, it is the StreamTitle up to the first "-" character.

==== %discnumber% ====
Index of disc specified track belongs to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %totaldiscs% ====
Index of total discs specified tracks belong to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %track artist% ====
Name of the artist of the track; present only if ''%album artist%'' is different than ''%artist%'' for specific track. Intended for use together with ''%album artist%'', to indicate track-specific artist info, e.g. "%album artist% - %title%[ '//' %track artist%]". In this case, the last part will be displayed only when track-specific artist info is present.

==== %title% ====
Title of the track. If "title" metadata field is missing, file name is used instead. For a SHOUTcast stream which contains metadata, it is the StreamTitle after the first "-" character.

==== %tracknumber% ====
Two-digit index of specified track within the album. Available only when "tracknumber" field is present in track’s metadata. An extra '0' is placed in front of single digit track numbers (5 becomes 05) – otherwise the tracknumber field is returned unchanged (e.g. the following values remain as they are: 006, 05, 104, A3, two, -1, -).

==== %track number% ====
Similar to %tracknumber%, however single digit track numbers are not reformatted to have an extra 0.

==== %totaltracks% ====
Index of total tracks specified tracks belong to, within the album. Available only when "totaltracks" field is present in track’s metadata.

=== Technical information fields ===

==== %bitrate% ====
Bitrate of the track in kilobits per second. VBR files will show a dynamic display for currently played track (outside of the playlist).

==== %channels% ====
Number of channels in the track, as text; either "mono", "stereo" for 1 or 2 channels, respectively, otherwise a number followed by "ch", e.g. "6ch".

==== %channel_mask% ====
Description of the used audio channels in the track, e.g. "FL FR FC LFE SL SR". Introduced in foobar2000 preview 2024-06-30.

==== %codec% ====
Name of codec used to encode the track, e.g. "PCM", "FLAC", "MP3", or "AAC". If exact codec name is not available, file extension is used.

==== %codec_profile% ====
Additional information about encoding settings used, e.g. "CBR". Not always available.

==== %codec_long% ====
Long name of the codec, including profile, e.g. "HE-AACv2". Some codecs, such as HE-AAC, supply this. If long name isn't supplied by the codec, %codec_long% falls back to %codec% / %codec_profile%. The Default UI's standard Codec column displays the same info.

==== %filesize% ====
The exact file size in bytes.
Old version: <code>%_filesize%</code>

==== %filesize_natural% ====
The approximate file size, automatically formatted in appropriate units such as megabytes or kilobytes, e.g. "8.49 MB"

==== %length% ====
The length of the track formatted as hours, minutes, and seconds, rounded to the nearest second.
Old version: <code>%_time_total%</code>

==== %length_ex% ====
The length of the track formatted as hours, minutes, seconds, and milliseconds, rounded to the nearest millisecond.

==== %length_seconds% ====
The length of the track in seconds, rounded to the nearest second.
Old version: <code>%_time_total_seconds%</code>

==== %length_seconds_fp% ====
The length of the track in seconds as a floating point number.

==== %length_samples% ====
The length of the track in samples.

==== %samplerate% ====
Sample rate of the track, in Hz.

=== Technical information functions ===

==== $info(name) ====
Returns value of technical information field called ''name''.

For convenience, the '''%__name%''' alias is also available.

Example: ''$info(channels)'' → 2

Here is an '''informative''' list of recognized fields. Some of these depend on the media file type being queried.

{| border="0" cellspacing="0" cellpadding="2"
! field name
! Description
|-
| colspan="2" style="background-color:#CCF"|'''General'''
|-
|codec
| style="background-color:#EEF"|'''Codec''' (''e.g.'' MP3)
|-
|codec_profile
| style="background-color:#EEF"|'''Codec Profile''' (''e.g.'' CBR)
|-
|samplerate
| style="background-color:#EEF"|'''Sample Rate''', in hertz (''e.g.'' 44100)
|-
|bitrate
| style="background-color:#EEF"|'''Bitrate''', in kilobits per second (''e.g.'' 320)
|-
|tool
| style="background-color:#EEF"|'''Tool''' used to produce the file, possibly guessed (''e.g.'' LAME3.97)
|-
|encoding
| style="background-color:#EEF"|'''Encoding''' lossiness (''e.g.'' lossy)
|-
|channels
| style="background-color:#EEF"|'''Channels''' count (''e.g.'' 2 <nowiki>[for stereo]</nowiki>)
|-
|bitspersample
| style="background-color:#EEF"|'''Bits Per Sample''' (''e.g.'' 16)
|-
|decoded_bitspersample
| style="background-color:#EEF"|'''Bits Per Sample''' after decoding (''e.g.'' 24)
|-
|bitspersample_extra
| style="background-color:#EEF"|'''Format''' of 32-bit audio data (floating-point or fixed-point)
|-
|tagtype
| style="background-color:#EEF"|'''Tag Type''', comma-separated list of tag formats (''e.g.'' id3v2|apev2)
|-
|cue_embedded
| style="background-color:#EEF"|'''Embedded Cuesheet''' presence (''e.g.'' no <nowiki>[may be empty!]</nowiki>)
|-
|md5
| style="background-color:#EEF"|'''Audio MD5''' hash, if container defines it (''e.g.'' 1E24A910D91EF09A8CF403C9B6963961)
|-
|WAVEFORMATEXTENSIBLE_CHANNEL_MASK
| style="background-color:#EEF"|'''Channel mask''', channel layout of the track coded as hex (''e.g.'' 0x0003 for regular stereo)
|-
| colspan="2" style="background-color:#CCF"|'''Other'''
|-
|ENC_DELAY
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_delay''' value for gapless playback (''e.g.'' 576)
|-
|ENC_PADDING
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_padding''' value for gapless playback (''e.g.'' 1536)
|-
|MP3_ACCURATE_LENGTH
| style="background-color:#EEF"|MP3 duration (%length% etc.) takes into account LAME or iTunes gapless playback info (''e.g.'' yes)*
|-
|MP3_STEREO_MODE
| style="background-color:#EEF"|Stereo mode used in MP3 file (''e.g.'' mono, stereo, joint stereo, etc.)
|-
|VERSION
| style="background-color:#EEF"|'''Version''' of tool (''e.g.'' 3.99)
|-
|FLAGS
| style="background-color:#EEF"|'''Flags''' of tool (''e.g.'' 22)
|-
|channel_mode
| style="background-color:#EEF"|'''Channel Mode''', description of channels (note: this field was only used by obsolete foo_ac3. ''e.g.'' 3 front, 2 rear surround channels + LFE)
|}

<div style="font-size: 90%"><nowiki>*</nowiki> ''MP3_ACCURATE_LENGTH won't exist if gapless playback info isn't present or the file is not an MP3. The info can be in a LAME tag in the VBR header, or in an iTunSMPB ID3v2 comment tag. Gapless playback info is taken into account in .m4a files, but there's no special field to say so.''</div>

==== $channels() ====
The number of channels in text format.

Example: ''$channels()'' → "stereo"

==== %replaygain_album_gain% ====
The ReplayGain album gain value.

==== %replaygain_album_peak% ====
The ReplayGain album peak value.

==== %replaygain_album_peak_db% ====
The ReplayGain album peak value in decibels.

==== %replaygain_track_gain% ====
The ReplayGain track gain value.

==== %replaygain_track_peak% ====
The ReplayGain track peak value.

==== %replaygain_track_peak_db% ====
The ReplayGain track peak value in decibels.

=== Special fields ===

==== %filename% ====
The filename without directory and extension.

==== %filename_ext% ====
The filename with extension, but without the directory.

==== %directoryname% ====
The name of the parent directory only, not the complete path.

==== %last_modified% ====
The date and time the file was last modified. Eg: ''2005-12-22 00:04:10''

==== %path% ====
The complete path, including the filename and extension.

==== %_path_raw% ====
The path as URL including the protocol scheme.

==== %subsong% ====
The subsong index. The subsong index is used to distuingish multiple tracks in a single file, for example for cue sheets, tracker modules and various container formats.

==== %_foobar2000_version% ====
A string representing the version of foobar2000.

== Time and date functions ==

These functions are used to manipulate time/date strings, notably (but not limited to), [[Foobar2000:Titleformat_Playback_Statistics|those gathered]] by the [[Foobar2000:Components/Playback Statistics v3.x (foo playcount)|Playback Statistics component]].

=== $year(time) ===
Retrieves the year part (formatted as four digits) from a time/date string.

=== $month(time) ===
Retrieves the month part (formatted as two digits) from a time/date string.

=== $day_of_month(time) ===
Retrieves the day of month part (formatted as two digits) from a time/date string.

=== $date(time) ===
Retrieves the date part (formatted as YYYY-MM-DD) from a time/date string.

=== $time(time) ===
Retrieves the time part (formatted as HH:MM:SS or HH:MM) from a date/time string.

== Variable operations ==

Variables can be used to store strings and numbers. They cannot store truth values. They are best used to store intermediate results that you need multiple times. Variable names are not case-sensitive.

For example:
{| border="0" cellspacing="0" cellpadding="2"
! code
! output
|-
|<pre>$put(foo,bar)$char(10)
$get(foo)$char(10)
$get(Foo)$char(10)
$puts(foo,2000)$char(10)
$get(foo)$char(10)</pre>
| style="background-color:#EEF" |<pre>bar
bar
bar

2000</pre>
|}

=== $get(name) ===
Returns the value that was last stored in the variable ''name'', if the variable was not defined (yet), it returns nothing. The truth value returned by ''$get'' indicates if the variable ''name'' was defined and is a non-empty string.

=== $put(name,value) ===
Stores ''value'' in the variable ''name'' and returns ''value'' unaltered.

=== $puts(name,value) ===
Stores ''value'' in the variable ''name'' and returns nothing.

== Component-specific fields and functions ==

This section lists fields and functions which are specific to certain components. Unless otherwise stated, the fields and functions are only usable in the context of those components.

=== Now playing info ===

The following fields related to the currently playing item are only usable in certain locations outside of the playlist, e.g. in the status bar, the main window title and the copy command script.

==== %playback_time% ====
The elapsed time formatted as [HH:]MM:SS.

==== %playback_time_seconds% ====
The elapsed time in seconds.
Old version: <code>%_time_elapsed%</code>

==== %playback_time_remaining% ====
The time remaining until the track ends, formatted as [HH:]MM:SS.
Old version: <code>%_time_remaining%</code>

==== %playback_time_remaining_seconds% ====
The time remaining until the track ends, in seconds.
Old version: <code>%_time_remaining_seconds%</code>

=== Playlist-only fields ===

The following fields are only usable in playlist display formatting (i.e., the column title formatting patterns).

==== %isplaying% ====
"1" if file is currently playing, empty string otherwise.

==== %ispaused% ====
"1" if playback is paused, empty string otherwise.

==== %list_index% ====
A zero-padded playlist index of specified item. The first item is at index 1.

==== %list_total% ====
The number of items in the playlist.

==== %queue_index% ====
Index of the specified item in the playback queue. If the item has been queued multiple times, %queue_index% evaluates to the first index.

==== %queue_indexes% ====
List of indexes of the specified item in the playback queue. Same as %queue_index% unless the item has been queued more than once.

==== %queue_total% ====
Total amount of tracks in playback queue. Available only for queued tracks, for technical reasons.

=== Playlist text color ===

==== Dimmed and highlighted text ====

In the Default UI playlist, text color can be adjusted by enclosing it in angle-brackets. The only options are to make the text dimmer (mixing the default color with the background color) or brighter (mixing the default color with the highlight color):

* ''<text>'' – dim ''text''
* ''<<text>>'' – dimmer ''text''
* ''<<<text>>>'' – dimmest ''text''
* ''>text<'' – bright ''text''
* ''>>text<<'' – brighter ''text''
* ''>>>text<<<'' – brightest ''text''

==== Historical and Columns UI color functions ====

Prior to version 1.0, the default UI playlist supported the following color functions, which are still available in the Columns UI playlist:

===== $blend(color1,color2,part,total) =====
Returns a color that is a blend between ''color1'' and ''color2''. If ''part'' is smaller than or equal to zero, ''color1'' is returned. If ''part'' is greater than or equal to ''total'', ''color2'' is returned. Otherwise a blended color is returned that is ''part'' parts ''color1'' and ''total''-''part'' parts ''color2''. The blending is performed in the RGB color space.

===== $hsl() =====
Resets the text color to the default color.

===== $hsl(h,s,l) =====
Sets the color for text in the HSL color space. ''h'', ''s'' and ''l'' are the hue, saturation, and lightness of the color for unselected text. The color for selected text is set to the inverse color.
The ranges of ''h'', ''s'', and ''l'' are from 0 to 240; the function is designed to interpret those values in the same way as the standard Windows color dialog.

===== $hsl(h1,s1,l1,h2,s2,l2) =====
Sets the color for text in the HSL color space. ''h1'', ''s1'' and ''l1'' are the hue, saturation, and lightness of the color for unselected text. ''h2'', ''s2'' and ''l2'' are the hue, saturation, and lightness of the color for selected text.

===== $rgb() =====
Resets the text color to the default color.

===== $rgb(r,g,b) =====
Sets the color for text. ''r'', ''g'' and ''b'' are the red, green and blue component of the color for unselected text. The color for selected text is set to the inverse color.

===== $rgb(r1,g1,b1,r2,g2,b2) =====
Sets the color for text. ''r1'', ''g1'' and ''b1'' are the red, green and blue component of the color for unselected text. ''r2'', ''g2'' and ''b2'' are the red, green and blue component of the color for selected text.

===== $transition(string,color1,color2) =====
Inserts color codes into ''string'', so that the first character has ''color1'', the last character has ''color2'', and intermediate characters have blended colors. The blending is performed in the RGB color space. Note that color codes are additional characters that will also be counted by string manipulation functions. For example, if you need to truncate a string, you should do this before applying ''$transition''.

=== Album List ===

* [[Foobar2000:Titleformat_Album_List|Album List Title Formatting]]
* [[Foobar2000:Preferences:Album List|Preferences: Album List]]

=== Playback Statistics ===

The foo_playcount component adds a number of fields for playback statistics and ratings. The fields can be used anywhere track info can be displayed. See the documentation for details:
* [http://www.foobar2000.org/components/view/foo_playcount Playback statistics homepage]
* [[Foobar2000:Titleformat Playback Statistics|Playback statistics titleformat reference]]

=== Playlist Organizer ===

This component adds a number of fields to control the display of a list of playlists. See the documentation for details:
* [[Foobar2000:Components/Playlist Organizer (foo_plorg)#Nodes|Playlist Organizer: Nodes Title Formatting]]

=== Columns UI ===

This component replaces the Default UI framework, including the playlist. See the documentation for details:
* [http://yuo.be/columns.php Columns UI homepage]
* [http://yuo.be/wiki/columns_ui:config:global_variables Global variables reference]
* [http://yuo.be/wiki/columns_ui:config:colour_string Playlist colors reference]
* [http://yuo.be/wiki/columns_ui:config:playlist_switcher_titleformatting Playlist switcher reference]

== Additional Reading ==

* [[Foobar2000:Title Formatting Introduction|Introduction to titleformat scripts]]
* The file '''titleformat_help.html''' in your Foobar2000 directory, e.g. file:///C:/Program%20Files%20(x86)/foobar2000/titleformat_help.html

[[Category:foobar2000 Guides|Titleformat Reference]]

Foobar2000:Title Formatting Reference

2024-11-19T08:36:45Z

Case: /* $info(name) */

{{sidebar foobar2000 title formatting}}
This article contains information about built-in title formatting functions and field references, plus additional documentation about fields and functions which can only be used in specific components or which are provided by specific components.

Please see [[Foobar2000:Title Formatting Introduction|Title Formatting Introduction]] for a general overview of title format syntax and its basic rules. The article [[foobar2000:Titleformat Examples|Titleformat Examples]] offers user-submitted examples of code for specific purposes; feel free to add your own if you think it can be of use to others.

For details of the query syntax, which uses some of these fields to find files for playlists, etc., see the [[Foobar2000:Query_syntax|Query Syntax]] article.

== Syntax ==

A title formatting script consists of any combination of literal text, field references, function calls, comments, and line break characters. The script always outputs a text string (which can be empty).

A '''comment''' is a line starting with two slashes, e.g. {{code|// this is a comment}}.

A '''field reference''' is a field name enclosed in percent signs, for example {{code|%artist%}}.

A '''function call''' starts with a dollar sign, followed by the function name and the parameter list. A parameter list can either be empty – denoted as {{code|()}} – or contain one or more parameters separated by commas, for example {{code|$abbr(%artist%)}}. A parameter can be literal text, a field reference, or another function call. Note that there must be no whitespace between the dollar sign and the function name, or the function name and the opening parenthesis of the parameter list.

Any other text is '''literal text'''. In literal text, the character {{code|%}}, {{code|$}}, {{code|[}}, {{code|]}}, or {{code|'}} (apostrophe/single quote) must be escaped by enclosing it in {{code|'}} (apostrophe/single quote) characters. For example, {{code|'['}} (a left bracket in single quotes) results in a literal {{code|[}} (left bracket). As a special case, {{code|<nowiki>''</nowiki>}} (two single quotes in a row) results in one single quote. In the playlist, {{code|<}} and {{code|>}} are also special; see [[#Dimmed and highlighted text|Dimmed and highlighted text]].

When the script is evaluated, the output string is assembled by evaluating the function parameters, function calls, and field references. Comments and line break characters (CR and LF/newline) are ignored; to output a line break, use {{code|$crlf()}}. Each field reference becomes the field's value, as a string. Each function becomes a string or number, and/or a truth value (not output) which can be used by another function.

'''Note: The interface for entering custom columns and grouping schemes for the Default UI playlist does not support line breaks; scripts must be written all on one line, without comments.'''

== Arithmetic functions ==

The functions in this section can be used to perform arithmetic on integer numbers. A string will be automatically converted to a number and vice versa. The conversion to a number uses the longest prefix of the string that can be interpreted as number. Leading whitespace is ignored. Decimal points are not supported. Examples:
* ''c3po'' → 0
* ''4.8'' → 4
* ''-12'' → -12
* ''- 12'' → 0

=== $add(a,b, ...) ===

Adds ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$add(a,b,...)'' is the same as ''$add($add(a,b),...)''.

=== $div(a,b) ===

Divides ''a'' by ''b'' and rounds down to an integer. If ''b'' evaluates to zero, it returns ''a''.

Can be used with an arbitrary number of arguments. ''$div(a,b,...)'' is the same as ''$div($div(a,b),...)''.

=== $greater(a,b) ===

Returns true, if ''a'' is greater than ''b'', otherwise false.

=== $max(a,b) ===

Returns the maximum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$max(a,b,...)'' is the same as ''$max($max(a,b),...)''.

=== $min(a,b) ===

Returns the minimum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$min(a,b,...)'' is the same as ''$min($min(a,b),...)''.

=== $mod(a,b) ===

Computes the remainder of dividing ''a'' through ''b''. The result has the same sign as ''a''. If ''b'' evaluates to zero, the result is ''a''.

Can be used with an arbitrary number of arguments. ''$mod(a,b,...)'' is the same as ''$mod($mod(a,b),...)''.

=== $mul(a,b) ===

Multiplies ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$mul(a,b,...)'' is the same as ''$mul($mul(a,b),...)''.

=== $muldiv(a,b,c) ===

Multiplies ''a'' and ''b'', then divides by ''c''. The result is rounded to the nearest integer.

=== $rand() ===

Generates a random number in the range from 0 to 232-1. Available only in sort-related contexts, such as the ''Edit → Sort → Sort by ...'' menu command.

=== $sub(a,b) ===

Subtracts ''b'' from ''a''.

Can be used with an arbitrary number of arguments. ''$sub(a,b,...)'' is the same as ''$sub($sub(a,b),...)''.

== Boolean functions ==

The functions in this section can be used to work with truth values (''true'' and ''false''), which have no explicit representation in titleformat scripts. They do not return a string or number value. You can use them for more complex conditions with ''$if'' and related functions.

Foobar does not have a concept of TRUE and FALSE in a programming language sense where 0 or empty string are considered FALSE and other values TRUE. Therefore there is no difference between numeric 0 and string representation '0' which both are considered as values, and being attached a boolean value FALSE. Apostrophes are only required to escape certain syntax characters. Values are treated as numbers during arithmetic operations like'' $add()''.

=== $and(expr, ...) ===

Logical And of an arbitrary number of arguments. Returns ''true'', if and only if all ''expr'' arguments evaluate to ''true''.

=== $or(expr, ...) ===

Logical Or of an arbitrary number of arguments. Returns ''true'', if at least one expression evaluates to ''true''.

=== $not(expr) ===

Logical Not. Returns the logical opposite of EXPR: ''false'', if ''expr'' is ''true'' and ''true'' if ''expr'' is false.

=== $xor(expr,...) ===

Logical Exclusive-or of an arbitrary number of arguments. Returns ''true'', if an odd number of arguments evaluate to ''true''.

Special case: ''$xor(expr1,expr2)'' returns ''true'', if EXPR1 or EXPR2 is ''true''. If both expressions are true, returns ''false''.

== Control flow functions ==

The functions in this section can be used to conditionally execute statements.

=== [...] (conditional section) ===

Evaluates the expression between ''['' and '']''. If it has the truth value ''true'', its string value and the truth value ''true'' are returned. Otherwise an empty string and ''false'' are returned.

Example: ''[%artist%]'' returns the value of the artist tag, if it exists. Otherwise it returns nothing, when ''artist'' would return "?".

=== $if(cond,then) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, ''false'' is returned.

Plain strings are FALSE. Field lookups and functions can introduce a boolean value of TRUE. 
Examples: 
1
<code>
#False:
$if(0,True,False)
# False:
$if('0',True,False)
# True or False:
[$add(%rating%,1)]
</code> 
The last one would display the value of %rating% plus one, if and only if %rating% is set for the track.

2
Ignore inserting the %album artist%, if it contains the word "various".
<code>
# Wrong:
$if([%album artist%=Various],,%artist%-)
# Good approach:
$if($stricmp(%album artist%,Various),,%artist%-)
</code>

=== $if(cond,then,else) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, the ''else'' part is evaluated and its value returned.

=== $if2(expr,else) ===

Like ''$if(expr,expr,else)'' except that ''expr'' is only evaluated once. In other words, if expression ''expr'' is true, ''expr'' is returned, otherwise the ''else'' part is evaluated and ''expr'' is returned as true.

=== $if3(a1,a2,...,aN,else) ===

Evaluates arguments ''a1'' ... ''aN'', until one is found that evaluates to ''true''. If that happens, its value is returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifequal(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is equal to ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifgreater(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is greater than ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $iflonger(str,n,then,else) ===

Compares the length of the string ''str'' to the number ''n'', if ''str'' is longer than ''n'' characters, the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $select(n,a1,...,aN) ===

If the value of ''n'' is between 1 and N, ''an'' is evaluated and its value returned. Otherwise ''false'' is returned.

== String functions ==

The functions in this section can be used to manipulate character strings.

=== $abbr(str) ===

Returns abbreviation of string ''str''. Words which begin with an alphanumeric character are shortened to the first character. Spaces and parentheses are stripped. Example:
* $abbr('This is a Long Title (12-inch version) [needs tags]') → TiaLT1v[needst

=== $abbr(str,len) ===

Returns abbreviation of ''str'', if ''str'' is longer than ''len'' characters, otherwise returns ''str''.

=== $ansi(str) ===

Converts string ''str'' to system codepage and back. Any characters that are not present in the system codepage will be removed / replaced. Useful for mass-renaming files to ensure compatibility with non-unicode-capable software.

=== $ascii(str) ===

Converts string ''str'' to ASCII. Any characters that are not present in ASCII will be removed / replaced.

=== $caps(str) ===

Converts first letter in every word of string ''str'' to uppercase, and all other letters to lowercase.

=== $caps2(str) ===

Converts first letter in every word of string ''str'' to uppercase, and leaves all other letters as they are.

=== $char(nbr) ===

Returns Unicode character of ''nbr''. You can search for characters and find the matching decimal number on this [http://www.fileformat.info/info/unicode/char/search.htm site].

=== $crc32(str) ===

Computes the CRC32 of the string ''str'' as a number. Intended for use in coloring scripts.

Example: $rgb($mod($crc32(%album%),256),128,128)

=== $crlf() ===

Inserts end-of-line marker (carriage return, line feed). Can be used to generate multiple lines in the output, for example for the tooltip of the system notification area ("systray") icon.

=== $cut(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $left(a,len). Negative numbers produce the entire string. Examples:
* ''$cut('abc123',3)'' → abc
* ''$cut('abc123',0)'' → (nothing)
* ''$cut('abc123',-1)'' → abc123

=== $directory(path) ===

Extracts only the directory name (not full path, ie given path as 'D:\music\jazz\filename.mp3', this will output 'jazz') from the file ''path''.

=== $directory(path,n) ===

Extracts directory name from the file ''path''; goes up by ''n'' levels.

=== $directory_path(path) ===

Extracts directory path from the file ''path''.
ie. given path as 'D:\music\jazz\filename.mp3', this will output 'D:\music\jazz'

=== $ext(path) ===

Extracts file extension from string ''path''; a file name or full path.

=== $filename(path) ===

Extracts file name from full ''path''.

=== $fix_eol(str) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by " (...)". Otherwise ''str'' is returned unaltered.

=== $fix_eol(str,indicator) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by ''indicator''. Otherwise ''str'' is returned unaltered.

=== $hex(int,len) ===

Formats the integer number ''int'' in hexadecimal notation with ''len'' digits. Pads with zeros from the left if necessary.

=== $insert(str,insert,n) ===

Inserts ''insert'' into ''str'' after ''n'' characters.

=== $left(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $cut(str,len). Negative numbers produce the entire string. Examples:
* ''$left('abc123',3)'' → abc
* ''$left('abc123',0)'' → (nothing)
* ''$left('abc123',-1)'' → abc123

=== $len(str) ===

Returns length of string ''str'' in characters.

=== $len2(str) ===

Returns length of string ''str'' in characters, respecting double-width character rules (double-width characters will be counted as two).

=== $longer(str1,str2) ===

Returns ''true'', if string ''str1'' is longer than string ''str2'', false otherwise.

=== $lower(str) ===

Converts string ''str'' to lowercase.

=== $longest(arg,...) ===

Returns the longest of its arguments. Can be used with an arbitrary number of strings.

=== $num(nbr,len) ===

Formats the integer number ''nbr'' in decimal notation with ''len'' characters. Pads with zeros from the left if necessary. ''len'' includes the dash when the number is negative. If ''nbr'' is not numeric, it is treated as zero. Examples:

* ''$num(123,5)'' → 00123
* ''$num(-123,5)'' → -0123
* ''$num(4.8,5)'' → 00004
* ''$num(A1,5)'' → 00000

=== $pad(str,len) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad(str,len,char) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len,char) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $padcut(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the right of ''str'' to make the result ''len'' characters long.

=== $padcut(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the right of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the left of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the left of ''str'' to make the result ''len'' characters long.

=== $progress(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with.

Example:''$progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'#','=')'' produces "====#===============", the # character is moving with playback position.

=== $progress2(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with. Produces different appearance than ''$progress''.

=== $repeat(expr,count) ===

Returns ''count'' copies of ''expr''. Note that ''expr'' is evaluated once before its value is used, so ''$repeat'' cannot be used for loops.

=== $replace(str,search,replace) ===

Replaces all occurrences of string ''search'' in string ''str'' with string ''replace''.

Can also be used with an arbitrary number of arguments. Note that ''$replace(str,search1,replace1,search2,replace2)'' is generally not the same as ''$replace($replace(str,search1,replace1),search2,replace2)''.

Example: ''$replace(ab,a,b,b,c)'' → "bc", ''$replace($replace(ab,a,b),b,c)'' → "cc"

=== $right(str,len) ===

Returns the first ''len'' characters from the right of string ''str''.

=== $roman(int) ===

Formats the integer number ''int'' in roman notation.

=== $rot13(str) ===

Performs [http://en.wikipedia.org/wiki/ROT13 ROT13] transformation to given string.

Example: ''$rot13('foobar2000')'' → "sbbone2000".

=== $shortest(str,...strN) ===

Returns the first shortest element of its arguments. Can be used with an arbitrary number of strings.

=== $strchr(str,char) ===

Returns position of first occurrence of character ''char'' in string ''str''.

Example: ''$strchr(abca,a)'' → 1

=== $strrchr(str,char) ===

Returns positions of last occurrence of character ''char'' in string ''str''.

Example: ''$strrchr(abca,a)'' → 4

=== $strstr(str1,str2) ===

Returns position of first occurrence of string ''str2'' in string ''str1''. Function is case-sensitive.

=== $strcmp(str1,str2) ===

Performs a case-sensitive comparison of the strings ''str1'' and ''str2''.

=== $stricmp(str1,str2) ===

Performs a case-insensitive comparison of the strings ''str1'' and ''str2''.

=== $stripprefix(str) ===

Removes ''A'' and ''The'' prefixes from string ''str''.

=== $stripprefix(str,prefix1,prefix2,...) ===

Removes the specified prefixes from string ''str''.

=== $substr(str,from,to) ===

Returns substring of string ''str'', starting from ''FROM''-th character and ending at ''TO''-th character.

=== $swapprefix(str) ===

Moves ''A'' and ''The'' prefixes to the end of string ''str''.

=== $swapprefix(str,prefix1,prefix2,...) ===

Moves the specified prefixes to the end of string ''str''.

=== $trim(str) ===

Removes leading and trailing spaces from string ''str''.

=== $tab() ===

Inserts one tabulator character.

=== $tab(count) ===

Inserts ''count'' tabulator characters.

=== $upper(str) ===

Converts string ''str'' to uppercase.

== Track info fields and functions ==

The functions and fields in this section can be used to access information about tracks.

=== Metadata fields and functions ===

Generally, metadata from the files (whether in tags or a cue sheet) is mapped directly to a field which can be referenced case-insensitively. For example, the first tag named ''URL'' can be referenced as ''%url%'', and the first standard comment tag can be referenced as ''%comment%''.

The following functions are also available for accessing metadata:

==== $meta(name) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ", " as separator.

Example: ''$meta(artist)'' → "He, She, They"

==== $meta(name,n) ====
Returns value of ''n''-th (0,1,2 and so on) tag called ''name''.

Example: ''$meta(artist,1)'' → "She"

==== $meta_sep(name,sep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator.

Example: ''$meta_sep(artist,' + ')'' → "He + She + They"

==== $meta_sep(name,sep,lastsep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator between all but the last two values which are concatenated with ''lastsep''.

Example: ''$meta_sep(artist,', ',', and ')'' → "He, She, and They"

==== $meta_test(...) ====
Returns ''1'', if all given tags exist, ''undefined'' otherwise.

Example: ''$meta_test(artist,title)'' → true

==== $meta_num(name) ====
Returns the number of values for the tag called ''name''.

Example: ''$meta_num(artist)'' → 3

=== Remapped metadata fields ===

The following fields have special remapped values to make writing title format scripts more convenient:

==== %album artist% ====
Name of the artist of the album specified track belongs to. Checks following metadata fields, in this order: "album artist", "artist", "composer", "performer". The difference between this and ''%artist%'' is that ''%album artist%'' is intended for use where consistent value across entire album is needed even when per-track artists values vary.

==== %album% ====
Name of the album specified track belongs to. Checks following metadata fields, in this order: "album", "venue".

==== %artist% ====
Name of the artist of the track. Checks following metadata fields, in this order: "artist", "album artist", "composer", "performer". For a SHOUTcast stream which contains metadata, it is the StreamTitle up to the first "-" character.

==== %discnumber% ====
Index of disc specified track belongs to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %totaldiscs% ====
Index of total discs specified tracks belong to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %track artist% ====
Name of the artist of the track; present only if ''%album artist%'' is different than ''%artist%'' for specific track. Intended for use together with ''%album artist%'', to indicate track-specific artist info, e.g. "%album artist% - %title%[ '//' %track artist%]". In this case, the last part will be displayed only when track-specific artist info is present.

==== %title% ====
Title of the track. If "title" metadata field is missing, file name is used instead. For a SHOUTcast stream which contains metadata, it is the StreamTitle after the first "-" character.

==== %tracknumber% ====
Two-digit index of specified track within the album. Available only when "tracknumber" field is present in track’s metadata. An extra '0' is placed in front of single digit track numbers (5 becomes 05) – otherwise the tracknumber field is returned unchanged (e.g. the following values remain as they are: 006, 05, 104, A3, two, -1, -).

==== %track number% ====
Similar to %tracknumber%, however single digit track numbers are not reformatted to have an extra 0.

==== %totaltracks% ====
Index of total tracks specified tracks belong to, within the album. Available only when "totaltracks" field is present in track’s metadata.

=== Technical information fields ===

==== %bitrate% ====
Bitrate of the track in kilobits per second. VBR files will show a dynamic display for currently played track (outside of the playlist).

==== %channels% ====
Number of channels in the track, as text; either "mono", "stereo" for 1 or 2 channels, respectively, otherwise a number followed by "ch", e.g. "6ch".

==== %channel_mask% ====
Description of the used audio channels in the track, e.g. "FL FR FC LFE SL SR". Introduced in foobar2000 preview 2024-06-30.

==== %codec% ====
Name of codec used to encode the track, e.g. "PCM", "FLAC", "MP3", or "AAC". If exact codec name is not available, file extension is used.

==== %codec_profile% ====
Additional information about encoding settings used, e.g. "CBR". Not always available.

==== %codec_long% ====
Long name of the codec, including profile, e.g. "HE-AACv2". Some codecs, such as HE-AAC, supply this. If long name isn't supplied by the codec, %codec_long% falls back to %codec% / %codec_profile%. The Default UI's standard Codec column displays the same info.

==== %filesize% ====
The exact file size in bytes.
Old version: <code>%_filesize%</code>

==== %filesize_natural% ====
The approximate file size, automatically formatted in appropriate units such as megabytes or kilobytes, e.g. "8.49 MB"

==== %length% ====
The length of the track formatted as hours, minutes, and seconds, rounded to the nearest second.
Old version: <code>%_time_total%</code>

==== %length_ex% ====
The length of the track formatted as hours, minutes, seconds, and milliseconds, rounded to the nearest millisecond.

==== %length_seconds% ====
The length of the track in seconds, rounded to the nearest second.
Old version: <code>%_time_total_seconds%</code>

==== %length_seconds_fp% ====
The length of the track in seconds as a floating point number.

==== %length_samples% ====
The length of the track in samples.

==== %samplerate% ====
Sample rate of the track, in Hz.

=== Technical information functions ===

==== $info(name) ====
Returns value of technical information field called ''name''.

For convenience, the '''%__name%''' alias is also available.

Example: ''$info(channels)'' → 2

Here is an '''informative''' list of recognized fields. Some of these depend on the media file type being queried.

{| border="0" cellspacing="0" cellpadding="2"
! field name
! Description
|-
| colspan="2" style="background-color:#CCF"|'''General'''
|-
|codec
| style="background-color:#EEF"|'''Codec''' (''e.g.'' MP3)
|-
|codec_profile
| style="background-color:#EEF"|'''Codec Profile''' (''e.g.'' CBR)
|-
|samplerate
| style="background-color:#EEF"|'''Sample Rate''', in hertz (''e.g.'' 44100)
|-
|bitrate
| style="background-color:#EEF"|'''Bitrate''', in kilobits per second (''e.g.'' 320)
|-
|tool
| style="background-color:#EEF"|'''Tool''' used to produce the file, possibly guessed (''e.g.'' LAME3.97)
|-
|encoding
| style="background-color:#EEF"|'''Encoding''' lossiness (''e.g.'' lossy)
|-
|channels
| style="background-color:#EEF"|'''Channels''' count (''e.g.'' 2 <nowiki>[for stereo]</nowiki>)
|-
|bitspersample
| style="background-color:#EEF"|'''Bits Per Sample''' (''e.g.'' 16)
|-
|decoded_bitspersample
| style="background-color:#EEF"|'''Bits Per Sample after decoding''' (''e.g.'' 24)
|-
|bitspersample_extra
| style="background-color:#EEF"|'''Format of 32-bit audio data''' (floating-point or fixed-point)
|-
|tagtype
| style="background-color:#EEF"|'''Tag Type''', comma-separated list of tag formats (''e.g.'' id3v2|apev2)
|-
|cue_embedded
| style="background-color:#EEF"|'''Embedded Cuesheet''' presence (''e.g.'' no <nowiki>[may be empty!]</nowiki>)
|-
|md5
| style="background-color:#EEF"|'''Audio MD5''' hash, if container defines it (''e.g.'' 1E24A910D91EF09A8CF403C9B6963961)
|-
|WAVEFORMATEXTENSIBLE_CHANNEL_MASK
| style="background-color:#EEF"|'''Channel mask''', channel layout of the track coded as hex (''e.g.'' 0x0003 for regular stereo)
|-
| colspan="2" style="background-color:#CCF"|'''Other'''
|-
|ENC_DELAY
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_delay''' value for gapless playback (''e.g.'' 576)
|-
|ENC_PADDING
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_padding''' value for gapless playback (''e.g.'' 1536)
|-
|MP3_ACCURATE_LENGTH
| style="background-color:#EEF"|MP3 duration (%length% etc.) takes into account LAME or iTunes gapless playback info (''e.g.'' yes)*
|-
|MP3_STEREO_MODE
| style="background-color:#EEF"|Stereo mode used in MP3 file (''e.g.'' mono, stereo, joint stereo, etc.)
|-
|VERSION
| style="background-color:#EEF"|'''Version''' of tool (''e.g.'' 3.99)
|-
|FLAGS
| style="background-color:#EEF"|'''Flags''' of tool (''e.g.'' 22)
|-
|channel_mode
| style="background-color:#EEF"|'''Channel Mode''', description of channels (note: this field was only used by obsolete foo_ac3. ''e.g.'' 3 front, 2 rear surround channels + LFE)
|}

<div style="font-size: 90%"><nowiki>*</nowiki> ''MP3_ACCURATE_LENGTH won't exist if gapless playback info isn't present or the file is not an MP3. The info can be in a LAME tag in the VBR header, or in an iTunSMPB ID3v2 comment tag. Gapless playback info is taken into account in .m4a files, but there's no special field to say so.''</div>

==== $channels() ====
The number of channels in text format.

Example: ''$channels()'' → "stereo"

==== %replaygain_album_gain% ====
The ReplayGain album gain value.

==== %replaygain_album_peak% ====
The ReplayGain album peak value.

==== %replaygain_album_peak_db% ====
The ReplayGain album peak value in decibels.

==== %replaygain_track_gain% ====
The ReplayGain track gain value.

==== %replaygain_track_peak% ====
The ReplayGain track peak value.

==== %replaygain_track_peak_db% ====
The ReplayGain track peak value in decibels.

=== Special fields ===

==== %filename% ====
The filename without directory and extension.

==== %filename_ext% ====
The filename with extension, but without the directory.

==== %directoryname% ====
The name of the parent directory only, not the complete path.

==== %last_modified% ====
The date and time the file was last modified. Eg: ''2005-12-22 00:04:10''

==== %path% ====
The complete path, including the filename and extension.

==== %_path_raw% ====
The path as URL including the protocol scheme.

==== %subsong% ====
The subsong index. The subsong index is used to distuingish multiple tracks in a single file, for example for cue sheets, tracker modules and various container formats.

==== %_foobar2000_version% ====
A string representing the version of foobar2000.

== Time and date functions ==

These functions are used to manipulate time/date strings, notably (but not limited to), [[Foobar2000:Titleformat_Playback_Statistics|those gathered]] by the [[Foobar2000:Components/Playback Statistics v3.x (foo playcount)|Playback Statistics component]].

=== $year(time) ===
Retrieves the year part (formatted as four digits) from a time/date string.

=== $month(time) ===
Retrieves the month part (formatted as two digits) from a time/date string.

=== $day_of_month(time) ===
Retrieves the day of month part (formatted as two digits) from a time/date string.

=== $date(time) ===
Retrieves the date part (formatted as YYYY-MM-DD) from a time/date string.

=== $time(time) ===
Retrieves the time part (formatted as HH:MM:SS or HH:MM) from a date/time string.

== Variable operations ==

Variables can be used to store strings and numbers. They cannot store truth values. They are best used to store intermediate results that you need multiple times. Variable names are not case-sensitive.

For example:
{| border="0" cellspacing="0" cellpadding="2"
! code
! output
|-
|<pre>$put(foo,bar)$char(10)
$get(foo)$char(10)
$get(Foo)$char(10)
$puts(foo,2000)$char(10)
$get(foo)$char(10)</pre>
| style="background-color:#EEF" |<pre>bar
bar
bar

2000</pre>
|}

=== $get(name) ===
Returns the value that was last stored in the variable ''name'', if the variable was not defined (yet), it returns nothing. The truth value returned by ''$get'' indicates if the variable ''name'' was defined and is a non-empty string.

=== $put(name,value) ===
Stores ''value'' in the variable ''name'' and returns ''value'' unaltered.

=== $puts(name,value) ===
Stores ''value'' in the variable ''name'' and returns nothing.

== Component-specific fields and functions ==

This section lists fields and functions which are specific to certain components. Unless otherwise stated, the fields and functions are only usable in the context of those components.

=== Now playing info ===

The following fields related to the currently playing item are only usable in certain locations outside of the playlist, e.g. in the status bar, the main window title and the copy command script.

==== %playback_time% ====
The elapsed time formatted as [HH:]MM:SS.

==== %playback_time_seconds% ====
The elapsed time in seconds.
Old version: <code>%_time_elapsed%</code>

==== %playback_time_remaining% ====
The time remaining until the track ends, formatted as [HH:]MM:SS.
Old version: <code>%_time_remaining%</code>

==== %playback_time_remaining_seconds% ====
The time remaining until the track ends, in seconds.
Old version: <code>%_time_remaining_seconds%</code>

=== Playlist-only fields ===

The following fields are only usable in playlist display formatting (i.e., the column title formatting patterns).

==== %isplaying% ====
"1" if file is currently playing, empty string otherwise.

==== %ispaused% ====
"1" if playback is paused, empty string otherwise.

==== %list_index% ====
A zero-padded playlist index of specified item. The first item is at index 1.

==== %list_total% ====
The number of items in the playlist.

==== %queue_index% ====
Index of the specified item in the playback queue. If the item has been queued multiple times, %queue_index% evaluates to the first index.

==== %queue_indexes% ====
List of indexes of the specified item in the playback queue. Same as %queue_index% unless the item has been queued more than once.

==== %queue_total% ====
Total amount of tracks in playback queue. Available only for queued tracks, for technical reasons.

=== Playlist text color ===

==== Dimmed and highlighted text ====

In the Default UI playlist, text color can be adjusted by enclosing it in angle-brackets. The only options are to make the text dimmer (mixing the default color with the background color) or brighter (mixing the default color with the highlight color):

* ''<text>'' – dim ''text''
* ''<<text>>'' – dimmer ''text''
* ''<<<text>>>'' – dimmest ''text''
* ''>text<'' – bright ''text''
* ''>>text<<'' – brighter ''text''
* ''>>>text<<<'' – brightest ''text''

==== Historical and Columns UI color functions ====

Prior to version 1.0, the default UI playlist supported the following color functions, which are still available in the Columns UI playlist:

===== $blend(color1,color2,part,total) =====
Returns a color that is a blend between ''color1'' and ''color2''. If ''part'' is smaller than or equal to zero, ''color1'' is returned. If ''part'' is greater than or equal to ''total'', ''color2'' is returned. Otherwise a blended color is returned that is ''part'' parts ''color1'' and ''total''-''part'' parts ''color2''. The blending is performed in the RGB color space.

===== $hsl() =====
Resets the text color to the default color.

===== $hsl(h,s,l) =====
Sets the color for text in the HSL color space. ''h'', ''s'' and ''l'' are the hue, saturation, and lightness of the color for unselected text. The color for selected text is set to the inverse color.
The ranges of ''h'', ''s'', and ''l'' are from 0 to 240; the function is designed to interpret those values in the same way as the standard Windows color dialog.

===== $hsl(h1,s1,l1,h2,s2,l2) =====
Sets the color for text in the HSL color space. ''h1'', ''s1'' and ''l1'' are the hue, saturation, and lightness of the color for unselected text. ''h2'', ''s2'' and ''l2'' are the hue, saturation, and lightness of the color for selected text.

===== $rgb() =====
Resets the text color to the default color.

===== $rgb(r,g,b) =====
Sets the color for text. ''r'', ''g'' and ''b'' are the red, green and blue component of the color for unselected text. The color for selected text is set to the inverse color.

===== $rgb(r1,g1,b1,r2,g2,b2) =====
Sets the color for text. ''r1'', ''g1'' and ''b1'' are the red, green and blue component of the color for unselected text. ''r2'', ''g2'' and ''b2'' are the red, green and blue component of the color for selected text.

===== $transition(string,color1,color2) =====
Inserts color codes into ''string'', so that the first character has ''color1'', the last character has ''color2'', and intermediate characters have blended colors. The blending is performed in the RGB color space. Note that color codes are additional characters that will also be counted by string manipulation functions. For example, if you need to truncate a string, you should do this before applying ''$transition''.

=== Album List ===

* [[Foobar2000:Titleformat_Album_List|Album List Title Formatting]]
* [[Foobar2000:Preferences:Album List|Preferences: Album List]]

=== Playback Statistics ===

The foo_playcount component adds a number of fields for playback statistics and ratings. The fields can be used anywhere track info can be displayed. See the documentation for details:
* [http://www.foobar2000.org/components/view/foo_playcount Playback statistics homepage]
* [[Foobar2000:Titleformat Playback Statistics|Playback statistics titleformat reference]]

=== Playlist Organizer ===

This component adds a number of fields to control the display of a list of playlists. See the documentation for details:
* [[Foobar2000:Components/Playlist Organizer (foo_plorg)#Nodes|Playlist Organizer: Nodes Title Formatting]]

=== Columns UI ===

This component replaces the Default UI framework, including the playlist. See the documentation for details:
* [http://yuo.be/columns.php Columns UI homepage]
* [http://yuo.be/wiki/columns_ui:config:global_variables Global variables reference]
* [http://yuo.be/wiki/columns_ui:config:colour_string Playlist colors reference]
* [http://yuo.be/wiki/columns_ui:config:playlist_switcher_titleformatting Playlist switcher reference]

== Additional Reading ==

* [[Foobar2000:Title Formatting Introduction|Introduction to titleformat scripts]]
* The file '''titleformat_help.html''' in your Foobar2000 directory, e.g. file:///C:/Program%20Files%20(x86)/foobar2000/titleformat_help.html

[[Category:foobar2000 Guides|Titleformat Reference]]

Foobar2000:Title Formatting Reference

2024-10-27T07:37:41Z

Case: /* Technical information fields */

{{sidebar foobar2000 title formatting}}
This article contains information about built-in title formatting functions and field references, plus additional documentation about fields and functions which can only be used in specific components or which are provided by specific components.

Please see [[Foobar2000:Title Formatting Introduction|Title Formatting Introduction]] for a general overview of title format syntax and its basic rules. The article [[foobar2000:Titleformat Examples|Titleformat Examples]] offers user-submitted examples of code for specific purposes; feel free to add your own if you think it can be of use to others.

For details of the query syntax, which uses some of these fields to find files for playlists, etc., see the [[Foobar2000:Query_syntax|Query Syntax]] article.

== Syntax ==

A title formatting script consists of any combination of literal text, field references, function calls, comments, and line break characters. The script always outputs a text string (which can be empty).

A '''comment''' is a line starting with two slashes, e.g. {{code|// this is a comment}}.

A '''field reference''' is a field name enclosed in percent signs, for example {{code|%artist%}}.

A '''function call''' starts with a dollar sign, followed by the function name and the parameter list. A parameter list can either be empty – denoted as {{code|()}} – or contain one or more parameters separated by commas, for example {{code|$abbr(%artist%)}}. A parameter can be literal text, a field reference, or another function call. Note that there must be no whitespace between the dollar sign and the function name, or the function name and the opening parenthesis of the parameter list.

Any other text is '''literal text'''. In literal text, the character {{code|%}}, {{code|$}}, {{code|[}}, {{code|]}}, or {{code|'}} (apostrophe/single quote) must be escaped by enclosing it in {{code|'}} (apostrophe/single quote) characters. For example, {{code|'['}} (a left bracket in single quotes) results in a literal {{code|[}} (left bracket). As a special case, {{code|<nowiki>''</nowiki>}} (two single quotes in a row) results in one single quote. In the playlist, {{code|<}} and {{code|>}} are also special; see [[#Dimmed and highlighted text|Dimmed and highlighted text]].

When the script is evaluated, the output string is assembled by evaluating the function parameters, function calls, and field references. Comments and line break characters (CR and LF/newline) are ignored; to output a line break, use {{code|$crlf()}}. Each field reference becomes the field's value, as a string. Each function becomes a string or number, and/or a truth value (not output) which can be used by another function.

'''Note: The interface for entering custom columns and grouping schemes for the Default UI playlist does not support line breaks; scripts must be written all on one line, without comments.'''

== Arithmetic functions ==

The functions in this section can be used to perform arithmetic on integer numbers. A string will be automatically converted to a number and vice versa. The conversion to a number uses the longest prefix of the string that can be interpreted as number. Leading whitespace is ignored. Decimal points are not supported. Examples:
* ''c3po'' → 0
* ''4.8'' → 4
* ''-12'' → -12
* ''- 12'' → 0

=== $add(a,b, ...) ===

Adds ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$add(a,b,...)'' is the same as ''$add($add(a,b),...)''.

=== $div(a,b) ===

Divides ''a'' by ''b'' and rounds down to an integer. If ''b'' evaluates to zero, it returns ''a''.

Can be used with an arbitrary number of arguments. ''$div(a,b,...)'' is the same as ''$div($div(a,b),...)''.

=== $greater(a,b) ===

Returns true, if ''a'' is greater than ''b'', otherwise false.

=== $max(a,b) ===

Returns the maximum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$max(a,b,...)'' is the same as ''$max($max(a,b),...)''.

=== $min(a,b) ===

Returns the minimum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$min(a,b,...)'' is the same as ''$min($min(a,b),...)''.

=== $mod(a,b) ===

Computes the remainder of dividing ''a'' through ''b''. The result has the same sign as ''a''. If ''b'' evaluates to zero, the result is ''a''.

Can be used with an arbitrary number of arguments. ''$mod(a,b,...)'' is the same as ''$mod($mod(a,b),...)''.

=== $mul(a,b) ===

Multiplies ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$mul(a,b,...)'' is the same as ''$mul($mul(a,b),...)''.

=== $muldiv(a,b,c) ===

Multiplies ''a'' and ''b'', then divides by ''c''. The result is rounded to the nearest integer.

=== $rand() ===

Generates a random number in the range from 0 to 232-1. Available only in sort-related contexts, such as the ''Edit → Sort → Sort by ...'' menu command.

=== $sub(a,b) ===

Subtracts ''b'' from ''a''.

Can be used with an arbitrary number of arguments. ''$sub(a,b,...)'' is the same as ''$sub($sub(a,b),...)''.

== Boolean functions ==

The functions in this section can be used to work with truth values (''true'' and ''false''), which have no explicit representation in titleformat scripts. They do not return a string or number value. You can use them for more complex conditions with ''$if'' and related functions.

Foobar does not have a concept of TRUE and FALSE in a programming language sense where 0 or empty string are considered FALSE and other values TRUE. Therefore there is no difference between numeric 0 and string representation '0' which both are considered as values, and being attached a boolean value FALSE. Apostrophes are only required to escape certain syntax characters. Values are treated as numbers during arithmetic operations like'' $add()''.

=== $and(expr, ...) ===

Logical And of an arbitrary number of arguments. Returns ''true'', if and only if all ''expr'' arguments evaluate to ''true''.

=== $or(expr, ...) ===

Logical Or of an arbitrary number of arguments. Returns ''true'', if at least one expression evaluates to ''true''.

=== $not(expr) ===

Logical Not. Returns the logical opposite of EXPR: ''false'', if ''expr'' is ''true'' and ''true'' if ''expr'' is false.

=== $xor(expr,...) ===

Logical Exclusive-or of an arbitrary number of arguments. Returns ''true'', if an odd number of arguments evaluate to ''true''.

Special case: ''$xor(expr1,expr2)'' returns ''true'', if EXPR1 or EXPR2 is ''true''. If both expressions are true, returns ''false''.

== Control flow functions ==

The functions in this section can be used to conditionally execute statements.

=== [...] (conditional section) ===

Evaluates the expression between ''['' and '']''. If it has the truth value ''true'', its string value and the truth value ''true'' are returned. Otherwise an empty string and ''false'' are returned.

Example: ''[%artist%]'' returns the value of the artist tag, if it exists. Otherwise it returns nothing, when ''artist'' would return "?".

=== $if(cond,then) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, ''false'' is returned.

Plain strings are FALSE. Field lookups and functions can introduce a boolean value of TRUE. 
Examples: 
1
<code>
#False:
$if(0,True,False)
# False:
$if('0',True,False)
# True or False:
[$add(%rating%,1)]
</code> 
The last one would display the value of %rating% plus one, if and only if %rating% is set for the track.

2
Ignore inserting the %album artist%, if it contains the word "various".
<code>
# Wrong:
$if([%album artist%=Various],,%artist%-)
# Good approach:
$if($stricmp(%album artist%,Various),,%artist%-)
</code>

=== $if(cond,then,else) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, the ''else'' part is evaluated and its value returned.

=== $if2(expr,else) ===

Like ''$if(expr,expr,else)'' except that ''expr'' is only evaluated once. In other words, if expression ''expr'' is true, ''expr'' is returned, otherwise the ''else'' part is evaluated and ''expr'' is returned as true.

=== $if3(a1,a2,...,aN,else) ===

Evaluates arguments ''a1'' ... ''aN'', until one is found that evaluates to ''true''. If that happens, its value is returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifequal(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is equal to ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifgreater(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is greater than ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $iflonger(str,n,then,else) ===

Compares the length of the string ''str'' to the number ''n'', if ''str'' is longer than ''n'' characters, the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $select(n,a1,...,aN) ===

If the value of ''n'' is between 1 and N, ''an'' is evaluated and its value returned. Otherwise ''false'' is returned.

== String functions ==

The functions in this section can be used to manipulate character strings.

=== $abbr(str) ===

Returns abbreviation of string ''str''. Words which begin with an alphanumeric character are shortened to the first character. Spaces and parentheses are stripped. Example:
* $abbr('This is a Long Title (12-inch version) [needs tags]') → TiaLT1v[needst

=== $abbr(str,len) ===

Returns abbreviation of ''str'', if ''str'' is longer than ''len'' characters, otherwise returns ''str''.

=== $ansi(str) ===

Converts string ''str'' to system codepage and back. Any characters that are not present in the system codepage will be removed / replaced. Useful for mass-renaming files to ensure compatibility with non-unicode-capable software.

=== $ascii(str) ===

Converts string ''str'' to ASCII. Any characters that are not present in ASCII will be removed / replaced.

=== $caps(str) ===

Converts first letter in every word of string ''str'' to uppercase, and all other letters to lowercase.

=== $caps2(str) ===

Converts first letter in every word of string ''str'' to uppercase, and leaves all other letters as they are.

=== $char(nbr) ===

Returns Unicode character of ''nbr''. You can search for characters and find the matching decimal number on this [http://www.fileformat.info/info/unicode/char/search.htm site].

=== $crc32(str) ===

Computes the CRC32 of the string ''str'' as a number. Intended for use in coloring scripts.

Example: $rgb($mod($crc32(%album%),256),128,128)

=== $crlf() ===

Inserts end-of-line marker (carriage return, line feed). Can be used to generate multiple lines in the output, for example for the tooltip of the system notification area ("systray") icon.

=== $cut(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $left(a,len). Negative numbers produce the entire string. Examples:
* ''$cut('abc123',3)'' → abc
* ''$cut('abc123',0)'' → (nothing)
* ''$cut('abc123',-1)'' → abc123

=== $directory(path) ===

Extracts only the directory name (not full path, ie given path as 'D:\music\jazz\filename.mp3', this will output 'jazz') from the file ''path''.

=== $directory(path,n) ===

Extracts directory name from the file ''path''; goes up by ''n'' levels.

=== $directory_path(path) ===

Extracts directory path from the file ''path''.
ie. given path as 'D:\music\jazz\filename.mp3', this will output 'D:\music\jazz'

=== $ext(path) ===

Extracts file extension from string ''path''; a file name or full path.

=== $filename(path) ===

Extracts file name from full ''path''.

=== $fix_eol(str) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by " (...)". Otherwise ''str'' is returned unaltered.

=== $fix_eol(str,indicator) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by ''indicator''. Otherwise ''str'' is returned unaltered.

=== $hex(int,len) ===

Formats the integer number ''int'' in hexadecimal notation with ''len'' digits. Pads with zeros from the left if necessary.

=== $insert(str,insert,n) ===

Inserts ''insert'' into ''str'' after ''n'' characters.

=== $left(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $cut(str,len). Negative numbers produce the entire string. Examples:
* ''$left('abc123',3)'' → abc
* ''$left('abc123',0)'' → (nothing)
* ''$left('abc123',-1)'' → abc123

=== $len(str) ===

Returns length of string ''str'' in characters.

=== $len2(str) ===

Returns length of string ''str'' in characters, respecting double-width character rules (double-width characters will be counted as two).

=== $longer(str1,str2) ===

Returns ''true'', if string ''str1'' is longer than string ''str2'', false otherwise.

=== $lower(str) ===

Converts string ''str'' to lowercase.

=== $longest(arg,...) ===

Returns the longest of its arguments. Can be used with an arbitrary number of strings.

=== $num(nbr,len) ===

Formats the integer number ''nbr'' in decimal notation with ''len'' characters. Pads with zeros from the left if necessary. ''len'' includes the dash when the number is negative. If ''nbr'' is not numeric, it is treated as zero. Examples:

* ''$num(123,5)'' → 00123
* ''$num(-123,5)'' → -0123
* ''$num(4.8,5)'' → 00004
* ''$num(A1,5)'' → 00000

=== $pad(str,len) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad(str,len,char) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len,char) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $padcut(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the right of ''str'' to make the result ''len'' characters long.

=== $padcut(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the right of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the left of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the left of ''str'' to make the result ''len'' characters long.

=== $progress(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with.

Example:''$progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'#','=')'' produces "====#===============", the # character is moving with playback position.

=== $progress2(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with. Produces different appearance than ''$progress''.

=== $repeat(expr,count) ===

Returns ''count'' copies of ''expr''. Note that ''expr'' is evaluated once before its value is used, so ''$repeat'' cannot be used for loops.

=== $replace(str,search,replace) ===

Replaces all occurrences of string ''search'' in string ''str'' with string ''replace''.

Can also be used with an arbitrary number of arguments. Note that ''$replace(str,search1,replace1,search2,replace2)'' is generally not the same as ''$replace($replace(str,search1,replace1),search2,replace2)''.

Example: ''$replace(ab,a,b,b,c)'' → "bc", ''$replace($replace(ab,a,b),b,c)'' → "cc"

=== $right(str,len) ===

Returns the first ''len'' characters from the right of string ''str''.

=== $roman(int) ===

Formats the integer number ''int'' in roman notation.

=== $rot13(str) ===

Performs [http://en.wikipedia.org/wiki/ROT13 ROT13] transformation to given string.

Example: ''$rot13('foobar2000')'' → "sbbone2000".

=== $shortest(str,...strN) ===

Returns the first shortest element of its arguments. Can be used with an arbitrary number of strings.

=== $strchr(str,char) ===

Returns position of first occurrence of character ''char'' in string ''str''.

Example: ''$strchr(abca,a)'' → 1

=== $strrchr(str,char) ===

Returns positions of last occurrence of character ''char'' in string ''str''.

Example: ''$strrchr(abca,a)'' → 4

=== $strstr(str1,str2) ===

Returns position of first occurrence of string ''str2'' in string ''str1''. Function is case-sensitive.

=== $strcmp(str1,str2) ===

Performs a case-sensitive comparison of the strings ''str1'' and ''str2''.

=== $stricmp(str1,str2) ===

Performs a case-insensitive comparison of the strings ''str1'' and ''str2''.

=== $stripprefix(str) ===

Removes ''A'' and ''The'' prefixes from string ''str''.

=== $stripprefix(str,prefix1,prefix2,...) ===

Removes the specified prefixes from string ''str''.

=== $substr(str,from,to) ===

Returns substring of string ''str'', starting from ''FROM''-th character and ending at ''TO''-th character.

=== $swapprefix(str) ===

Moves ''A'' and ''The'' prefixes to the end of string ''str''.

=== $swapprefix(str,prefix1,prefix2,...) ===

Moves the specified prefixes to the end of string ''str''.

=== $trim(str) ===

Removes leading and trailing spaces from string ''str''.

=== $tab() ===

Inserts one tabulator character.

=== $tab(count) ===

Inserts ''count'' tabulator characters.

=== $upper(str) ===

Converts string ''str'' to uppercase.

== Track info fields and functions ==

The functions and fields in this section can be used to access information about tracks.

=== Metadata fields and functions ===

Generally, metadata from the files (whether in tags or a cue sheet) is mapped directly to a field which can be referenced case-insensitively. For example, the first tag named ''URL'' can be referenced as ''%url%'', and the first standard comment tag can be referenced as ''%comment%''.

The following functions are also available for accessing metadata:

==== $meta(name) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ", " as separator.

Example: ''$meta(artist)'' → "He, She, They"

==== $meta(name,n) ====
Returns value of ''n''-th (0,1,2 and so on) tag called ''name''.

Example: ''$meta(artist,1)'' → "She"

==== $meta_sep(name,sep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator.

Example: ''$meta_sep(artist,' + ')'' → "He + She + They"

==== $meta_sep(name,sep,lastsep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator between all but the last two values which are concatenated with ''lastsep''.

Example: ''$meta_sep(artist,', ',', and ')'' → "He, She, and They"

==== $meta_test(...) ====
Returns ''1'', if all given tags exist, ''undefined'' otherwise.

Example: ''$meta_test(artist,title)'' → true

==== $meta_num(name) ====
Returns the number of values for the tag called ''name''.

Example: ''$meta_num(artist)'' → 3

=== Remapped metadata fields ===

The following fields have special remapped values to make writing title format scripts more convenient:

==== %album artist% ====
Name of the artist of the album specified track belongs to. Checks following metadata fields, in this order: "album artist", "artist", "composer", "performer". The difference between this and ''%artist%'' is that ''%album artist%'' is intended for use where consistent value across entire album is needed even when per-track artists values vary.

==== %album% ====
Name of the album specified track belongs to. Checks following metadata fields, in this order: "album", "venue".

==== %artist% ====
Name of the artist of the track. Checks following metadata fields, in this order: "artist", "album artist", "composer", "performer". For a SHOUTcast stream which contains metadata, it is the StreamTitle up to the first "-" character.

==== %discnumber% ====
Index of disc specified track belongs to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %totaldiscs% ====
Index of total discs specified tracks belong to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %track artist% ====
Name of the artist of the track; present only if ''%album artist%'' is different than ''%artist%'' for specific track. Intended for use together with ''%album artist%'', to indicate track-specific artist info, e.g. "%album artist% - %title%[ '//' %track artist%]". In this case, the last part will be displayed only when track-specific artist info is present.

==== %title% ====
Title of the track. If "title" metadata field is missing, file name is used instead. For a SHOUTcast stream which contains metadata, it is the StreamTitle after the first "-" character.

==== %tracknumber% ====
Two-digit index of specified track within the album. Available only when "tracknumber" field is present in track’s metadata. An extra '0' is placed in front of single digit track numbers (5 becomes 05) – otherwise the tracknumber field is returned unchanged (e.g. the following values remain as they are: 006, 05, 104, A3, two, -1, -).

==== %track number% ====
Similar to %tracknumber%, however single digit track numbers are not reformatted to have an extra 0.

==== %totaltracks% ====
Index of total tracks specified tracks belong to, within the album. Available only when "totaltracks" field is present in track’s metadata.

=== Technical information fields ===

==== %bitrate% ====
Bitrate of the track in kilobits per second. VBR files will show a dynamic display for currently played track (outside of the playlist).

==== %channels% ====
Number of channels in the track, as text; either "mono", "stereo" for 1 or 2 channels, respectively, otherwise a number followed by "ch", e.g. "6ch".

==== %channel_mask% ====
Description of the used audio channels in the track, e.g. "FL FR FC LFE SL SR". Introduced in foobar2000 preview 2024-06-30.

==== %codec% ====
Name of codec used to encode the track, e.g. "PCM", "FLAC", "MP3", or "AAC". If exact codec name is not available, file extension is used.

==== %codec_profile% ====
Additional information about encoding settings used, e.g. "CBR". Not always available.

==== %codec_long% ====
Long name of the codec, including profile, e.g. "HE-AACv2". Some codecs, such as HE-AAC, supply this. If long name isn't supplied by the codec, %codec_long% falls back to %codec% / %codec_profile%. The Default UI's standard Codec column displays the same info.

==== %filesize% ====
The exact file size in bytes.
Old version: <code>%_filesize%</code>

==== %filesize_natural% ====
The approximate file size, automatically formatted in appropriate units such as megabytes or kilobytes, e.g. "8.49 MB"

==== %length% ====
The length of the track formatted as hours, minutes, and seconds, rounded to the nearest second.
Old version: <code>%_time_total%</code>

==== %length_ex% ====
The length of the track formatted as hours, minutes, seconds, and milliseconds, rounded to the nearest millisecond.

==== %length_seconds% ====
The length of the track in seconds, rounded to the nearest second.
Old version: <code>%_time_total_seconds%</code>

==== %length_seconds_fp% ====
The length of the track in seconds as a floating point number.

==== %length_samples% ====
The length of the track in samples.

==== %samplerate% ====
Sample rate of the track, in Hz.

=== Technical information functions ===

==== $info(name) ====
Returns value of technical information field called ''name''.

For convenience, the '''%__name%''' alias is also available.

Example: ''$info(channels)'' → 2

Here is an '''informative''' list of recognized fields. Some of these depend on the media file type being queried.

{| border="0" cellspacing="0" cellpadding="2"
! field name
! Description
|-
| colspan="2" style="background-color:#CCF"|'''General'''
|-
|codec
| style="background-color:#EEF"|'''Codec''' (''e.g.'' MP3)
|-
|codec_profile
| style="background-color:#EEF"|'''Codec Profile''' (''e.g.'' CBR)
|-
|samplerate
| style="background-color:#EEF"|'''Sample Rate''', in hertz (''e.g.'' 44100)
|-
|bitrate
| style="background-color:#EEF"|'''Bitrate''', in kilobits per second (''e.g.'' 320)
|-
|tool
| style="background-color:#EEF"|'''Tool''' used to produce the file, possibly guessed (''e.g.'' LAME3.97)
|-
|encoding
| style="background-color:#EEF"|'''Encoding''' lossiness (''e.g.'' lossy)
|-
|channels
| style="background-color:#EEF"|'''Channels''' count (''e.g.'' 2 <nowiki>[for stereo]</nowiki>)
|-
|bitspersample
| style="background-color:#EEF"|'''Bits Per Sample''' (''e.g.'' 16)
|-
|tagtype
| style="background-color:#EEF"|'''Tag Type''', comma-separated list of tag formats (''e.g.'' id3v2|apev2)
|-
|cue_embedded
| style="background-color:#EEF"|'''Embedded Cuesheet''' presence (''e.g.'' no <nowiki>[may be empty!]</nowiki>)
|-
|md5
| style="background-color:#EEF"|'''Audio MD5''' hash, if container defines it (''e.g.'' 1E24A910D91EF09A8CF403C9B6963961)
|-
|WAVEFORMATEXTENSIBLE_CHANNEL_MASK
| style="background-color:#EEF"|'''Channel mask''', channel layout of the track coded as hex (''e.g.'' 0x0003 for regular stereo)
|-
| colspan="2" style="background-color:#CCF"|'''Other'''
|-
|ENC_DELAY
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_delay''' value for gapless playback (''e.g.'' 576)
|-
|ENC_PADDING
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_padding''' value for gapless playback (''e.g.'' 1536)
|-
|MP3_ACCURATE_LENGTH
| style="background-color:#EEF"|MP3 duration (%length% etc.) takes into account LAME or iTunes gapless playback info (''e.g.'' yes)*
|-
|MP3_STEREO_MODE
| style="background-color:#EEF"|Stereo mode used in MP3 file (''e.g.'' mono, stereo, joint stereo, etc.)
|-
|VERSION
| style="background-color:#EEF"|'''Version''' of tool (''e.g.'' 3.99)
|-
|FLAGS
| style="background-color:#EEF"|'''Flags''' of tool (''e.g.'' 22)
|-
|channel_mode
| style="background-color:#EEF"|'''Channel Mode''', description of channels (note: this field was only used by obsolete foo_ac3. ''e.g.'' 3 front, 2 rear surround channels + LFE)
|}

<div style="font-size: 90%"><nowiki>*</nowiki> ''MP3_ACCURATE_LENGTH won't exist if gapless playback info isn't present or the file is not an MP3. The info can be in a LAME tag in the VBR header, or in an iTunSMPB ID3v2 comment tag. Gapless playback info is taken into account in .m4a files, but there's no special field to say so.''</div>

==== $channels() ====
The number of channels in text format.

Example: ''$channels()'' → "stereo"

==== %replaygain_album_gain% ====
The ReplayGain album gain value.

==== %replaygain_album_peak% ====
The ReplayGain album peak value.

==== %replaygain_album_peak_db% ====
The ReplayGain album peak value in decibels.

==== %replaygain_track_gain% ====
The ReplayGain track gain value.

==== %replaygain_track_peak% ====
The ReplayGain track peak value.

==== %replaygain_track_peak_db% ====
The ReplayGain track peak value in decibels.

=== Special fields ===

==== %filename% ====
The filename without directory and extension.

==== %filename_ext% ====
The filename with extension, but without the directory.

==== %directoryname% ====
The name of the parent directory only, not the complete path.

==== %last_modified% ====
The date and time the file was last modified. Eg: ''2005-12-22 00:04:10''

==== %path% ====
The complete path, including the filename and extension.

==== %_path_raw% ====
The path as URL including the protocol scheme.

==== %subsong% ====
The subsong index. The subsong index is used to distuingish multiple tracks in a single file, for example for cue sheets, tracker modules and various container formats.

==== %_foobar2000_version% ====
A string representing the version of foobar2000.

== Time and date functions ==

These functions are used to manipulate time/date strings, notably (but not limited to), [[Foobar2000:Titleformat_Playback_Statistics|those gathered]] by the [[Foobar2000:Components/Playback Statistics v3.x (foo playcount)|Playback Statistics component]].

=== $year(time) ===
Retrieves the year part (formatted as four digits) from a time/date string.

=== $month(time) ===
Retrieves the month part (formatted as two digits) from a time/date string.

=== $day_of_month(time) ===
Retrieves the day of month part (formatted as two digits) from a time/date string.

=== $date(time) ===
Retrieves the date part (formatted as YYYY-MM-DD) from a time/date string.

=== $time(time) ===
Retrieves the time part (formatted as HH:MM:SS or HH:MM) from a date/time string.

== Variable operations ==

Variables can be used to store strings and numbers. They cannot store truth values. They are best used to store intermediate results that you need multiple times. Variable names are not case-sensitive.

For example:
{| border="0" cellspacing="0" cellpadding="2"
! code
! output
|-
|<pre>$put(foo,bar)$char(10)
$get(foo)$char(10)
$get(Foo)$char(10)
$puts(foo,2000)$char(10)
$get(foo)$char(10)</pre>
| style="background-color:#EEF" |<pre>bar
bar
bar

2000</pre>
|}

=== $get(name) ===
Returns the value that was last stored in the variable ''name'', if the variable was not defined (yet), it returns nothing. The truth value returned by ''$get'' indicates if the variable ''name'' was defined and is a non-empty string.

=== $put(name,value) ===
Stores ''value'' in the variable ''name'' and returns ''value'' unaltered.

=== $puts(name,value) ===
Stores ''value'' in the variable ''name'' and returns nothing.

== Component-specific fields and functions ==

This section lists fields and functions which are specific to certain components. Unless otherwise stated, the fields and functions are only usable in the context of those components.

=== Now playing info ===

The following fields related to the currently playing item are only usable in certain locations outside of the playlist, e.g. in the status bar, the main window title and the copy command script.

==== %playback_time% ====
The elapsed time formatted as [HH:]MM:SS.

==== %playback_time_seconds% ====
The elapsed time in seconds.
Old version: <code>%_time_elapsed%</code>

==== %playback_time_remaining% ====
The time remaining until the track ends, formatted as [HH:]MM:SS.
Old version: <code>%_time_remaining%</code>

==== %playback_time_remaining_seconds% ====
The time remaining until the track ends, in seconds.
Old version: <code>%_time_remaining_seconds%</code>

=== Playlist-only fields ===

The following fields are only usable in playlist display formatting (i.e., the column title formatting patterns).

==== %isplaying% ====
"1" if file is currently playing, empty string otherwise.

==== %ispaused% ====
"1" if playback is paused, empty string otherwise.

==== %list_index% ====
A zero-padded playlist index of specified item. The first item is at index 1.

==== %list_total% ====
The number of items in the playlist.

==== %queue_index% ====
Index of the specified item in the playback queue. If the item has been queued multiple times, %queue_index% evaluates to the first index.

==== %queue_indexes% ====
List of indexes of the specified item in the playback queue. Same as %queue_index% unless the item has been queued more than once.

==== %queue_total% ====
Total amount of tracks in playback queue. Available only for queued tracks, for technical reasons.

=== Playlist text color ===

==== Dimmed and highlighted text ====

In the Default UI playlist, text color can be adjusted by enclosing it in angle-brackets. The only options are to make the text dimmer (mixing the default color with the background color) or brighter (mixing the default color with the highlight color):

* ''<text>'' – dim ''text''
* ''<<text>>'' – dimmer ''text''
* ''<<<text>>>'' – dimmest ''text''
* ''>text<'' – bright ''text''
* ''>>text<<'' – brighter ''text''
* ''>>>text<<<'' – brightest ''text''

==== Historical and Columns UI color functions ====

Prior to version 1.0, the default UI playlist supported the following color functions, which are still available in the Columns UI playlist:

===== $blend(color1,color2,part,total) =====
Returns a color that is a blend between ''color1'' and ''color2''. If ''part'' is smaller than or equal to zero, ''color1'' is returned. If ''part'' is greater than or equal to ''total'', ''color2'' is returned. Otherwise a blended color is returned that is ''part'' parts ''color1'' and ''total''-''part'' parts ''color2''. The blending is performed in the RGB color space.

===== $hsl() =====
Resets the text color to the default color.

===== $hsl(h,s,l) =====
Sets the color for text in the HSL color space. ''h'', ''s'' and ''l'' are the hue, saturation, and lightness of the color for unselected text. The color for selected text is set to the inverse color.
The ranges of ''h'', ''s'', and ''l'' are from 0 to 240; the function is designed to interpret those values in the same way as the standard Windows color dialog.

===== $hsl(h1,s1,l1,h2,s2,l2) =====
Sets the color for text in the HSL color space. ''h1'', ''s1'' and ''l1'' are the hue, saturation, and lightness of the color for unselected text. ''h2'', ''s2'' and ''l2'' are the hue, saturation, and lightness of the color for selected text.

===== $rgb() =====
Resets the text color to the default color.

===== $rgb(r,g,b) =====
Sets the color for text. ''r'', ''g'' and ''b'' are the red, green and blue component of the color for unselected text. The color for selected text is set to the inverse color.

===== $rgb(r1,g1,b1,r2,g2,b2) =====
Sets the color for text. ''r1'', ''g1'' and ''b1'' are the red, green and blue component of the color for unselected text. ''r2'', ''g2'' and ''b2'' are the red, green and blue component of the color for selected text.

===== $transition(string,color1,color2) =====
Inserts color codes into ''string'', so that the first character has ''color1'', the last character has ''color2'', and intermediate characters have blended colors. The blending is performed in the RGB color space. Note that color codes are additional characters that will also be counted by string manipulation functions. For example, if you need to truncate a string, you should do this before applying ''$transition''.

=== Album List ===

* [[Foobar2000:Titleformat_Album_List|Album List Title Formatting]]
* [[Foobar2000:Preferences:Album List|Preferences: Album List]]

=== Playback Statistics ===

The foo_playcount component adds a number of fields for playback statistics and ratings. The fields can be used anywhere track info can be displayed. See the documentation for details:
* [http://www.foobar2000.org/components/view/foo_playcount Playback statistics homepage]
* [[Foobar2000:Titleformat Playback Statistics|Playback statistics titleformat reference]]

=== Playlist Organizer ===

This component adds a number of fields to control the display of a list of playlists. See the documentation for details:
* [[Foobar2000:Components/Playlist Organizer (foo_plorg)#Nodes|Playlist Organizer: Nodes Title Formatting]]

=== Columns UI ===

This component replaces the Default UI framework, including the playlist. See the documentation for details:
* [http://yuo.be/columns.php Columns UI homepage]
* [http://yuo.be/wiki/columns_ui:config:global_variables Global variables reference]
* [http://yuo.be/wiki/columns_ui:config:colour_string Playlist colors reference]
* [http://yuo.be/wiki/columns_ui:config:playlist_switcher_titleformatting Playlist switcher reference]

== Additional Reading ==

* [[Foobar2000:Title Formatting Introduction|Introduction to titleformat scripts]]
* The file '''titleformat_help.html''' in your Foobar2000 directory, e.g. file:///C:/Program%20Files%20(x86)/foobar2000/titleformat_help.html

[[Category:foobar2000 Guides|Titleformat Reference]]

Foobar2000:Title Formatting Reference

2024-10-27T07:37:09Z

Case: /* Technical information fields */

{{sidebar foobar2000 title formatting}}
This article contains information about built-in title formatting functions and field references, plus additional documentation about fields and functions which can only be used in specific components or which are provided by specific components.

Please see [[Foobar2000:Title Formatting Introduction|Title Formatting Introduction]] for a general overview of title format syntax and its basic rules. The article [[foobar2000:Titleformat Examples|Titleformat Examples]] offers user-submitted examples of code for specific purposes; feel free to add your own if you think it can be of use to others.

For details of the query syntax, which uses some of these fields to find files for playlists, etc., see the [[Foobar2000:Query_syntax|Query Syntax]] article.

== Syntax ==

A title formatting script consists of any combination of literal text, field references, function calls, comments, and line break characters. The script always outputs a text string (which can be empty).

A '''comment''' is a line starting with two slashes, e.g. {{code|// this is a comment}}.

A '''field reference''' is a field name enclosed in percent signs, for example {{code|%artist%}}.

A '''function call''' starts with a dollar sign, followed by the function name and the parameter list. A parameter list can either be empty – denoted as {{code|()}} – or contain one or more parameters separated by commas, for example {{code|$abbr(%artist%)}}. A parameter can be literal text, a field reference, or another function call. Note that there must be no whitespace between the dollar sign and the function name, or the function name and the opening parenthesis of the parameter list.

Any other text is '''literal text'''. In literal text, the character {{code|%}}, {{code|$}}, {{code|[}}, {{code|]}}, or {{code|'}} (apostrophe/single quote) must be escaped by enclosing it in {{code|'}} (apostrophe/single quote) characters. For example, {{code|'['}} (a left bracket in single quotes) results in a literal {{code|[}} (left bracket). As a special case, {{code|<nowiki>''</nowiki>}} (two single quotes in a row) results in one single quote. In the playlist, {{code|<}} and {{code|>}} are also special; see [[#Dimmed and highlighted text|Dimmed and highlighted text]].

When the script is evaluated, the output string is assembled by evaluating the function parameters, function calls, and field references. Comments and line break characters (CR and LF/newline) are ignored; to output a line break, use {{code|$crlf()}}. Each field reference becomes the field's value, as a string. Each function becomes a string or number, and/or a truth value (not output) which can be used by another function.

'''Note: The interface for entering custom columns and grouping schemes for the Default UI playlist does not support line breaks; scripts must be written all on one line, without comments.'''

== Arithmetic functions ==

The functions in this section can be used to perform arithmetic on integer numbers. A string will be automatically converted to a number and vice versa. The conversion to a number uses the longest prefix of the string that can be interpreted as number. Leading whitespace is ignored. Decimal points are not supported. Examples:
* ''c3po'' → 0
* ''4.8'' → 4
* ''-12'' → -12
* ''- 12'' → 0

=== $add(a,b, ...) ===

Adds ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$add(a,b,...)'' is the same as ''$add($add(a,b),...)''.

=== $div(a,b) ===

Divides ''a'' by ''b'' and rounds down to an integer. If ''b'' evaluates to zero, it returns ''a''.

Can be used with an arbitrary number of arguments. ''$div(a,b,...)'' is the same as ''$div($div(a,b),...)''.

=== $greater(a,b) ===

Returns true, if ''a'' is greater than ''b'', otherwise false.

=== $max(a,b) ===

Returns the maximum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$max(a,b,...)'' is the same as ''$max($max(a,b),...)''.

=== $min(a,b) ===

Returns the minimum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$min(a,b,...)'' is the same as ''$min($min(a,b),...)''.

=== $mod(a,b) ===

Computes the remainder of dividing ''a'' through ''b''. The result has the same sign as ''a''. If ''b'' evaluates to zero, the result is ''a''.

Can be used with an arbitrary number of arguments. ''$mod(a,b,...)'' is the same as ''$mod($mod(a,b),...)''.

=== $mul(a,b) ===

Multiplies ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$mul(a,b,...)'' is the same as ''$mul($mul(a,b),...)''.

=== $muldiv(a,b,c) ===

Multiplies ''a'' and ''b'', then divides by ''c''. The result is rounded to the nearest integer.

=== $rand() ===

Generates a random number in the range from 0 to 232-1. Available only in sort-related contexts, such as the ''Edit → Sort → Sort by ...'' menu command.

=== $sub(a,b) ===

Subtracts ''b'' from ''a''.

Can be used with an arbitrary number of arguments. ''$sub(a,b,...)'' is the same as ''$sub($sub(a,b),...)''.

== Boolean functions ==

The functions in this section can be used to work with truth values (''true'' and ''false''), which have no explicit representation in titleformat scripts. They do not return a string or number value. You can use them for more complex conditions with ''$if'' and related functions.

Foobar does not have a concept of TRUE and FALSE in a programming language sense where 0 or empty string are considered FALSE and other values TRUE. Therefore there is no difference between numeric 0 and string representation '0' which both are considered as values, and being attached a boolean value FALSE. Apostrophes are only required to escape certain syntax characters. Values are treated as numbers during arithmetic operations like'' $add()''.

=== $and(expr, ...) ===

Logical And of an arbitrary number of arguments. Returns ''true'', if and only if all ''expr'' arguments evaluate to ''true''.

=== $or(expr, ...) ===

Logical Or of an arbitrary number of arguments. Returns ''true'', if at least one expression evaluates to ''true''.

=== $not(expr) ===

Logical Not. Returns the logical opposite of EXPR: ''false'', if ''expr'' is ''true'' and ''true'' if ''expr'' is false.

=== $xor(expr,...) ===

Logical Exclusive-or of an arbitrary number of arguments. Returns ''true'', if an odd number of arguments evaluate to ''true''.

Special case: ''$xor(expr1,expr2)'' returns ''true'', if EXPR1 or EXPR2 is ''true''. If both expressions are true, returns ''false''.

== Control flow functions ==

The functions in this section can be used to conditionally execute statements.

=== [...] (conditional section) ===

Evaluates the expression between ''['' and '']''. If it has the truth value ''true'', its string value and the truth value ''true'' are returned. Otherwise an empty string and ''false'' are returned.

Example: ''[%artist%]'' returns the value of the artist tag, if it exists. Otherwise it returns nothing, when ''artist'' would return "?".

=== $if(cond,then) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, ''false'' is returned.

Plain strings are FALSE. Field lookups and functions can introduce a boolean value of TRUE. 
Examples: 
1
<code>
#False:
$if(0,True,False)
# False:
$if('0',True,False)
# True or False:
[$add(%rating%,1)]
</code> 
The last one would display the value of %rating% plus one, if and only if %rating% is set for the track.

2
Ignore inserting the %album artist%, if it contains the word "various".
<code>
# Wrong:
$if([%album artist%=Various],,%artist%-)
# Good approach:
$if($stricmp(%album artist%,Various),,%artist%-)
</code>

=== $if(cond,then,else) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, the ''else'' part is evaluated and its value returned.

=== $if2(expr,else) ===

Like ''$if(expr,expr,else)'' except that ''expr'' is only evaluated once. In other words, if expression ''expr'' is true, ''expr'' is returned, otherwise the ''else'' part is evaluated and ''expr'' is returned as true.

=== $if3(a1,a2,...,aN,else) ===

Evaluates arguments ''a1'' ... ''aN'', until one is found that evaluates to ''true''. If that happens, its value is returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifequal(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is equal to ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifgreater(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is greater than ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $iflonger(str,n,then,else) ===

Compares the length of the string ''str'' to the number ''n'', if ''str'' is longer than ''n'' characters, the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $select(n,a1,...,aN) ===

If the value of ''n'' is between 1 and N, ''an'' is evaluated and its value returned. Otherwise ''false'' is returned.

== String functions ==

The functions in this section can be used to manipulate character strings.

=== $abbr(str) ===

Returns abbreviation of string ''str''. Words which begin with an alphanumeric character are shortened to the first character. Spaces and parentheses are stripped. Example:
* $abbr('This is a Long Title (12-inch version) [needs tags]') → TiaLT1v[needst

=== $abbr(str,len) ===

Returns abbreviation of ''str'', if ''str'' is longer than ''len'' characters, otherwise returns ''str''.

=== $ansi(str) ===

Converts string ''str'' to system codepage and back. Any characters that are not present in the system codepage will be removed / replaced. Useful for mass-renaming files to ensure compatibility with non-unicode-capable software.

=== $ascii(str) ===

Converts string ''str'' to ASCII. Any characters that are not present in ASCII will be removed / replaced.

=== $caps(str) ===

Converts first letter in every word of string ''str'' to uppercase, and all other letters to lowercase.

=== $caps2(str) ===

Converts first letter in every word of string ''str'' to uppercase, and leaves all other letters as they are.

=== $char(nbr) ===

Returns Unicode character of ''nbr''. You can search for characters and find the matching decimal number on this [http://www.fileformat.info/info/unicode/char/search.htm site].

=== $crc32(str) ===

Computes the CRC32 of the string ''str'' as a number. Intended for use in coloring scripts.

Example: $rgb($mod($crc32(%album%),256),128,128)

=== $crlf() ===

Inserts end-of-line marker (carriage return, line feed). Can be used to generate multiple lines in the output, for example for the tooltip of the system notification area ("systray") icon.

=== $cut(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $left(a,len). Negative numbers produce the entire string. Examples:
* ''$cut('abc123',3)'' → abc
* ''$cut('abc123',0)'' → (nothing)
* ''$cut('abc123',-1)'' → abc123

=== $directory(path) ===

Extracts only the directory name (not full path, ie given path as 'D:\music\jazz\filename.mp3', this will output 'jazz') from the file ''path''.

=== $directory(path,n) ===

Extracts directory name from the file ''path''; goes up by ''n'' levels.

=== $directory_path(path) ===

Extracts directory path from the file ''path''.
ie. given path as 'D:\music\jazz\filename.mp3', this will output 'D:\music\jazz'

=== $ext(path) ===

Extracts file extension from string ''path''; a file name or full path.

=== $filename(path) ===

Extracts file name from full ''path''.

=== $fix_eol(str) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by " (...)". Otherwise ''str'' is returned unaltered.

=== $fix_eol(str,indicator) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by ''indicator''. Otherwise ''str'' is returned unaltered.

=== $hex(int,len) ===

Formats the integer number ''int'' in hexadecimal notation with ''len'' digits. Pads with zeros from the left if necessary.

=== $insert(str,insert,n) ===

Inserts ''insert'' into ''str'' after ''n'' characters.

=== $left(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $cut(str,len). Negative numbers produce the entire string. Examples:
* ''$left('abc123',3)'' → abc
* ''$left('abc123',0)'' → (nothing)
* ''$left('abc123',-1)'' → abc123

=== $len(str) ===

Returns length of string ''str'' in characters.

=== $len2(str) ===

Returns length of string ''str'' in characters, respecting double-width character rules (double-width characters will be counted as two).

=== $longer(str1,str2) ===

Returns ''true'', if string ''str1'' is longer than string ''str2'', false otherwise.

=== $lower(str) ===

Converts string ''str'' to lowercase.

=== $longest(arg,...) ===

Returns the longest of its arguments. Can be used with an arbitrary number of strings.

=== $num(nbr,len) ===

Formats the integer number ''nbr'' in decimal notation with ''len'' characters. Pads with zeros from the left if necessary. ''len'' includes the dash when the number is negative. If ''nbr'' is not numeric, it is treated as zero. Examples:

* ''$num(123,5)'' → 00123
* ''$num(-123,5)'' → -0123
* ''$num(4.8,5)'' → 00004
* ''$num(A1,5)'' → 00000

=== $pad(str,len) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad(str,len,char) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len,char) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $padcut(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the right of ''str'' to make the result ''len'' characters long.

=== $padcut(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the right of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the left of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the left of ''str'' to make the result ''len'' characters long.

=== $progress(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with.

Example:''$progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'#','=')'' produces "====#===============", the # character is moving with playback position.

=== $progress2(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with. Produces different appearance than ''$progress''.

=== $repeat(expr,count) ===

Returns ''count'' copies of ''expr''. Note that ''expr'' is evaluated once before its value is used, so ''$repeat'' cannot be used for loops.

=== $replace(str,search,replace) ===

Replaces all occurrences of string ''search'' in string ''str'' with string ''replace''.

Can also be used with an arbitrary number of arguments. Note that ''$replace(str,search1,replace1,search2,replace2)'' is generally not the same as ''$replace($replace(str,search1,replace1),search2,replace2)''.

Example: ''$replace(ab,a,b,b,c)'' → "bc", ''$replace($replace(ab,a,b),b,c)'' → "cc"

=== $right(str,len) ===

Returns the first ''len'' characters from the right of string ''str''.

=== $roman(int) ===

Formats the integer number ''int'' in roman notation.

=== $rot13(str) ===

Performs [http://en.wikipedia.org/wiki/ROT13 ROT13] transformation to given string.

Example: ''$rot13('foobar2000')'' → "sbbone2000".

=== $shortest(str,...strN) ===

Returns the first shortest element of its arguments. Can be used with an arbitrary number of strings.

=== $strchr(str,char) ===

Returns position of first occurrence of character ''char'' in string ''str''.

Example: ''$strchr(abca,a)'' → 1

=== $strrchr(str,char) ===

Returns positions of last occurrence of character ''char'' in string ''str''.

Example: ''$strrchr(abca,a)'' → 4

=== $strstr(str1,str2) ===

Returns position of first occurrence of string ''str2'' in string ''str1''. Function is case-sensitive.

=== $strcmp(str1,str2) ===

Performs a case-sensitive comparison of the strings ''str1'' and ''str2''.

=== $stricmp(str1,str2) ===

Performs a case-insensitive comparison of the strings ''str1'' and ''str2''.

=== $stripprefix(str) ===

Removes ''A'' and ''The'' prefixes from string ''str''.

=== $stripprefix(str,prefix1,prefix2,...) ===

Removes the specified prefixes from string ''str''.

=== $substr(str,from,to) ===

Returns substring of string ''str'', starting from ''FROM''-th character and ending at ''TO''-th character.

=== $swapprefix(str) ===

Moves ''A'' and ''The'' prefixes to the end of string ''str''.

=== $swapprefix(str,prefix1,prefix2,...) ===

Moves the specified prefixes to the end of string ''str''.

=== $trim(str) ===

Removes leading and trailing spaces from string ''str''.

=== $tab() ===

Inserts one tabulator character.

=== $tab(count) ===

Inserts ''count'' tabulator characters.

=== $upper(str) ===

Converts string ''str'' to uppercase.

== Track info fields and functions ==

The functions and fields in this section can be used to access information about tracks.

=== Metadata fields and functions ===

Generally, metadata from the files (whether in tags or a cue sheet) is mapped directly to a field which can be referenced case-insensitively. For example, the first tag named ''URL'' can be referenced as ''%url%'', and the first standard comment tag can be referenced as ''%comment%''.

The following functions are also available for accessing metadata:

==== $meta(name) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ", " as separator.

Example: ''$meta(artist)'' → "He, She, They"

==== $meta(name,n) ====
Returns value of ''n''-th (0,1,2 and so on) tag called ''name''.

Example: ''$meta(artist,1)'' → "She"

==== $meta_sep(name,sep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator.

Example: ''$meta_sep(artist,' + ')'' → "He + She + They"

==== $meta_sep(name,sep,lastsep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator between all but the last two values which are concatenated with ''lastsep''.

Example: ''$meta_sep(artist,', ',', and ')'' → "He, She, and They"

==== $meta_test(...) ====
Returns ''1'', if all given tags exist, ''undefined'' otherwise.

Example: ''$meta_test(artist,title)'' → true

==== $meta_num(name) ====
Returns the number of values for the tag called ''name''.

Example: ''$meta_num(artist)'' → 3

=== Remapped metadata fields ===

The following fields have special remapped values to make writing title format scripts more convenient:

==== %album artist% ====
Name of the artist of the album specified track belongs to. Checks following metadata fields, in this order: "album artist", "artist", "composer", "performer". The difference between this and ''%artist%'' is that ''%album artist%'' is intended for use where consistent value across entire album is needed even when per-track artists values vary.

==== %album% ====
Name of the album specified track belongs to. Checks following metadata fields, in this order: "album", "venue".

==== %artist% ====
Name of the artist of the track. Checks following metadata fields, in this order: "artist", "album artist", "composer", "performer". For a SHOUTcast stream which contains metadata, it is the StreamTitle up to the first "-" character.

==== %discnumber% ====
Index of disc specified track belongs to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %totaldiscs% ====
Index of total discs specified tracks belong to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %track artist% ====
Name of the artist of the track; present only if ''%album artist%'' is different than ''%artist%'' for specific track. Intended for use together with ''%album artist%'', to indicate track-specific artist info, e.g. "%album artist% - %title%[ '//' %track artist%]". In this case, the last part will be displayed only when track-specific artist info is present.

==== %title% ====
Title of the track. If "title" metadata field is missing, file name is used instead. For a SHOUTcast stream which contains metadata, it is the StreamTitle after the first "-" character.

==== %tracknumber% ====
Two-digit index of specified track within the album. Available only when "tracknumber" field is present in track’s metadata. An extra '0' is placed in front of single digit track numbers (5 becomes 05) – otherwise the tracknumber field is returned unchanged (e.g. the following values remain as they are: 006, 05, 104, A3, two, -1, -).

==== %track number% ====
Similar to %tracknumber%, however single digit track numbers are not reformatted to have an extra 0.

==== %totaltracks% ====
Index of total tracks specified tracks belong to, within the album. Available only when "totaltracks" field is present in track’s metadata.

=== Technical information fields ===

==== %bitrate% ====
Bitrate of the track in kilobits per second. VBR files will show a dynamic display for currently played track (outside of the playlist).

==== %channels% ====
Number of channels in the track, as text; either "mono", "stereo" for 1 or 2 channels, respectively, otherwise a number followed by "ch", e.g. "6ch".

==== %channel_mask% ====
Description of the used audio channels in the track, e.g. "FL FR FC LFE SL SR". Introduced in foobar2000 preview 2024-06-30.

==== %codec% ====
Name of codec used to encode the track, e.g. "PCM", "FLAC", "MP3", or "AAC". If exact codec name is not available, file extension is used.

==== %codec_profile% ====
Additional information about encoding settings used, e.g. "CBR". Not always available.

==== %codec_long% ====
Long name of the codec, including profile, e.g. HE-AACv2. Some codecs, such as HE-AAC, supply this. If long name isn't supplied by the codec, %codec_long% falls back to %codec% / %codec_profile%. The Default UI's standard Codec column displays the same info.

==== %filesize% ====
The exact file size in bytes.
Old version: <code>%_filesize%</code>

==== %filesize_natural% ====
The approximate file size, automatically formatted in appropriate units such as megabytes or kilobytes, e.g. "8.49 MB"

==== %length% ====
The length of the track formatted as hours, minutes, and seconds, rounded to the nearest second.
Old version: <code>%_time_total%</code>

==== %length_ex% ====
The length of the track formatted as hours, minutes, seconds, and milliseconds, rounded to the nearest millisecond.

==== %length_seconds% ====
The length of the track in seconds, rounded to the nearest second.
Old version: <code>%_time_total_seconds%</code>

==== %length_seconds_fp% ====
The length of the track in seconds as a floating point number.

==== %length_samples% ====
The length of the track in samples.

==== %samplerate% ====
Sample rate of the track, in Hz.

=== Technical information functions ===

==== $info(name) ====
Returns value of technical information field called ''name''.

For convenience, the '''%__name%''' alias is also available.

Example: ''$info(channels)'' → 2

Here is an '''informative''' list of recognized fields. Some of these depend on the media file type being queried.

{| border="0" cellspacing="0" cellpadding="2"
! field name
! Description
|-
| colspan="2" style="background-color:#CCF"|'''General'''
|-
|codec
| style="background-color:#EEF"|'''Codec''' (''e.g.'' MP3)
|-
|codec_profile
| style="background-color:#EEF"|'''Codec Profile''' (''e.g.'' CBR)
|-
|samplerate
| style="background-color:#EEF"|'''Sample Rate''', in hertz (''e.g.'' 44100)
|-
|bitrate
| style="background-color:#EEF"|'''Bitrate''', in kilobits per second (''e.g.'' 320)
|-
|tool
| style="background-color:#EEF"|'''Tool''' used to produce the file, possibly guessed (''e.g.'' LAME3.97)
|-
|encoding
| style="background-color:#EEF"|'''Encoding''' lossiness (''e.g.'' lossy)
|-
|channels
| style="background-color:#EEF"|'''Channels''' count (''e.g.'' 2 <nowiki>[for stereo]</nowiki>)
|-
|bitspersample
| style="background-color:#EEF"|'''Bits Per Sample''' (''e.g.'' 16)
|-
|tagtype
| style="background-color:#EEF"|'''Tag Type''', comma-separated list of tag formats (''e.g.'' id3v2|apev2)
|-
|cue_embedded
| style="background-color:#EEF"|'''Embedded Cuesheet''' presence (''e.g.'' no <nowiki>[may be empty!]</nowiki>)
|-
|md5
| style="background-color:#EEF"|'''Audio MD5''' hash, if container defines it (''e.g.'' 1E24A910D91EF09A8CF403C9B6963961)
|-
|WAVEFORMATEXTENSIBLE_CHANNEL_MASK
| style="background-color:#EEF"|'''Channel mask''', channel layout of the track coded as hex (''e.g.'' 0x0003 for regular stereo)
|-
| colspan="2" style="background-color:#CCF"|'''Other'''
|-
|ENC_DELAY
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_delay''' value for gapless playback (''e.g.'' 576)
|-
|ENC_PADDING
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_padding''' value for gapless playback (''e.g.'' 1536)
|-
|MP3_ACCURATE_LENGTH
| style="background-color:#EEF"|MP3 duration (%length% etc.) takes into account LAME or iTunes gapless playback info (''e.g.'' yes)*
|-
|MP3_STEREO_MODE
| style="background-color:#EEF"|Stereo mode used in MP3 file (''e.g.'' mono, stereo, joint stereo, etc.)
|-
|VERSION
| style="background-color:#EEF"|'''Version''' of tool (''e.g.'' 3.99)
|-
|FLAGS
| style="background-color:#EEF"|'''Flags''' of tool (''e.g.'' 22)
|-
|channel_mode
| style="background-color:#EEF"|'''Channel Mode''', description of channels (note: this field was only used by obsolete foo_ac3. ''e.g.'' 3 front, 2 rear surround channels + LFE)
|}

<div style="font-size: 90%"><nowiki>*</nowiki> ''MP3_ACCURATE_LENGTH won't exist if gapless playback info isn't present or the file is not an MP3. The info can be in a LAME tag in the VBR header, or in an iTunSMPB ID3v2 comment tag. Gapless playback info is taken into account in .m4a files, but there's no special field to say so.''</div>

==== $channels() ====
The number of channels in text format.

Example: ''$channels()'' → "stereo"

==== %replaygain_album_gain% ====
The ReplayGain album gain value.

==== %replaygain_album_peak% ====
The ReplayGain album peak value.

==== %replaygain_album_peak_db% ====
The ReplayGain album peak value in decibels.

==== %replaygain_track_gain% ====
The ReplayGain track gain value.

==== %replaygain_track_peak% ====
The ReplayGain track peak value.

==== %replaygain_track_peak_db% ====
The ReplayGain track peak value in decibels.

=== Special fields ===

==== %filename% ====
The filename without directory and extension.

==== %filename_ext% ====
The filename with extension, but without the directory.

==== %directoryname% ====
The name of the parent directory only, not the complete path.

==== %last_modified% ====
The date and time the file was last modified. Eg: ''2005-12-22 00:04:10''

==== %path% ====
The complete path, including the filename and extension.

==== %_path_raw% ====
The path as URL including the protocol scheme.

==== %subsong% ====
The subsong index. The subsong index is used to distuingish multiple tracks in a single file, for example for cue sheets, tracker modules and various container formats.

==== %_foobar2000_version% ====
A string representing the version of foobar2000.

== Time and date functions ==

These functions are used to manipulate time/date strings, notably (but not limited to), [[Foobar2000:Titleformat_Playback_Statistics|those gathered]] by the [[Foobar2000:Components/Playback Statistics v3.x (foo playcount)|Playback Statistics component]].

=== $year(time) ===
Retrieves the year part (formatted as four digits) from a time/date string.

=== $month(time) ===
Retrieves the month part (formatted as two digits) from a time/date string.

=== $day_of_month(time) ===
Retrieves the day of month part (formatted as two digits) from a time/date string.

=== $date(time) ===
Retrieves the date part (formatted as YYYY-MM-DD) from a time/date string.

=== $time(time) ===
Retrieves the time part (formatted as HH:MM:SS or HH:MM) from a date/time string.

== Variable operations ==

Variables can be used to store strings and numbers. They cannot store truth values. They are best used to store intermediate results that you need multiple times. Variable names are not case-sensitive.

For example:
{| border="0" cellspacing="0" cellpadding="2"
! code
! output
|-
|<pre>$put(foo,bar)$char(10)
$get(foo)$char(10)
$get(Foo)$char(10)
$puts(foo,2000)$char(10)
$get(foo)$char(10)</pre>
| style="background-color:#EEF" |<pre>bar
bar
bar

2000</pre>
|}

=== $get(name) ===
Returns the value that was last stored in the variable ''name'', if the variable was not defined (yet), it returns nothing. The truth value returned by ''$get'' indicates if the variable ''name'' was defined and is a non-empty string.

=== $put(name,value) ===
Stores ''value'' in the variable ''name'' and returns ''value'' unaltered.

=== $puts(name,value) ===
Stores ''value'' in the variable ''name'' and returns nothing.

== Component-specific fields and functions ==

This section lists fields and functions which are specific to certain components. Unless otherwise stated, the fields and functions are only usable in the context of those components.

=== Now playing info ===

The following fields related to the currently playing item are only usable in certain locations outside of the playlist, e.g. in the status bar, the main window title and the copy command script.

==== %playback_time% ====
The elapsed time formatted as [HH:]MM:SS.

==== %playback_time_seconds% ====
The elapsed time in seconds.
Old version: <code>%_time_elapsed%</code>

==== %playback_time_remaining% ====
The time remaining until the track ends, formatted as [HH:]MM:SS.
Old version: <code>%_time_remaining%</code>

==== %playback_time_remaining_seconds% ====
The time remaining until the track ends, in seconds.
Old version: <code>%_time_remaining_seconds%</code>

=== Playlist-only fields ===

The following fields are only usable in playlist display formatting (i.e., the column title formatting patterns).

==== %isplaying% ====
"1" if file is currently playing, empty string otherwise.

==== %ispaused% ====
"1" if playback is paused, empty string otherwise.

==== %list_index% ====
A zero-padded playlist index of specified item. The first item is at index 1.

==== %list_total% ====
The number of items in the playlist.

==== %queue_index% ====
Index of the specified item in the playback queue. If the item has been queued multiple times, %queue_index% evaluates to the first index.

==== %queue_indexes% ====
List of indexes of the specified item in the playback queue. Same as %queue_index% unless the item has been queued more than once.

==== %queue_total% ====
Total amount of tracks in playback queue. Available only for queued tracks, for technical reasons.

=== Playlist text color ===

==== Dimmed and highlighted text ====

In the Default UI playlist, text color can be adjusted by enclosing it in angle-brackets. The only options are to make the text dimmer (mixing the default color with the background color) or brighter (mixing the default color with the highlight color):

* ''<text>'' – dim ''text''
* ''<<text>>'' – dimmer ''text''
* ''<<<text>>>'' – dimmest ''text''
* ''>text<'' – bright ''text''
* ''>>text<<'' – brighter ''text''
* ''>>>text<<<'' – brightest ''text''

==== Historical and Columns UI color functions ====

Prior to version 1.0, the default UI playlist supported the following color functions, which are still available in the Columns UI playlist:

===== $blend(color1,color2,part,total) =====
Returns a color that is a blend between ''color1'' and ''color2''. If ''part'' is smaller than or equal to zero, ''color1'' is returned. If ''part'' is greater than or equal to ''total'', ''color2'' is returned. Otherwise a blended color is returned that is ''part'' parts ''color1'' and ''total''-''part'' parts ''color2''. The blending is performed in the RGB color space.

===== $hsl() =====
Resets the text color to the default color.

===== $hsl(h,s,l) =====
Sets the color for text in the HSL color space. ''h'', ''s'' and ''l'' are the hue, saturation, and lightness of the color for unselected text. The color for selected text is set to the inverse color.
The ranges of ''h'', ''s'', and ''l'' are from 0 to 240; the function is designed to interpret those values in the same way as the standard Windows color dialog.

===== $hsl(h1,s1,l1,h2,s2,l2) =====
Sets the color for text in the HSL color space. ''h1'', ''s1'' and ''l1'' are the hue, saturation, and lightness of the color for unselected text. ''h2'', ''s2'' and ''l2'' are the hue, saturation, and lightness of the color for selected text.

===== $rgb() =====
Resets the text color to the default color.

===== $rgb(r,g,b) =====
Sets the color for text. ''r'', ''g'' and ''b'' are the red, green and blue component of the color for unselected text. The color for selected text is set to the inverse color.

===== $rgb(r1,g1,b1,r2,g2,b2) =====
Sets the color for text. ''r1'', ''g1'' and ''b1'' are the red, green and blue component of the color for unselected text. ''r2'', ''g2'' and ''b2'' are the red, green and blue component of the color for selected text.

===== $transition(string,color1,color2) =====
Inserts color codes into ''string'', so that the first character has ''color1'', the last character has ''color2'', and intermediate characters have blended colors. The blending is performed in the RGB color space. Note that color codes are additional characters that will also be counted by string manipulation functions. For example, if you need to truncate a string, you should do this before applying ''$transition''.

=== Album List ===

* [[Foobar2000:Titleformat_Album_List|Album List Title Formatting]]
* [[Foobar2000:Preferences:Album List|Preferences: Album List]]

=== Playback Statistics ===

The foo_playcount component adds a number of fields for playback statistics and ratings. The fields can be used anywhere track info can be displayed. See the documentation for details:
* [http://www.foobar2000.org/components/view/foo_playcount Playback statistics homepage]
* [[Foobar2000:Titleformat Playback Statistics|Playback statistics titleformat reference]]

=== Playlist Organizer ===

This component adds a number of fields to control the display of a list of playlists. See the documentation for details:
* [[Foobar2000:Components/Playlist Organizer (foo_plorg)#Nodes|Playlist Organizer: Nodes Title Formatting]]

=== Columns UI ===

This component replaces the Default UI framework, including the playlist. See the documentation for details:
* [http://yuo.be/columns.php Columns UI homepage]
* [http://yuo.be/wiki/columns_ui:config:global_variables Global variables reference]
* [http://yuo.be/wiki/columns_ui:config:colour_string Playlist colors reference]
* [http://yuo.be/wiki/columns_ui:config:playlist_switcher_titleformatting Playlist switcher reference]

== Additional Reading ==

* [[Foobar2000:Title Formatting Introduction|Introduction to titleformat scripts]]
* The file '''titleformat_help.html''' in your Foobar2000 directory, e.g. file:///C:/Program%20Files%20(x86)/foobar2000/titleformat_help.html

[[Category:foobar2000 Guides|Titleformat Reference]]

Foobar2000:Title Formatting Reference

2024-10-27T07:24:27Z

Case: /* Technical information fields */

{{sidebar foobar2000 title formatting}}
This article contains information about built-in title formatting functions and field references, plus additional documentation about fields and functions which can only be used in specific components or which are provided by specific components.

Please see [[Foobar2000:Title Formatting Introduction|Title Formatting Introduction]] for a general overview of title format syntax and its basic rules. The article [[foobar2000:Titleformat Examples|Titleformat Examples]] offers user-submitted examples of code for specific purposes; feel free to add your own if you think it can be of use to others.

For details of the query syntax, which uses some of these fields to find files for playlists, etc., see the [[Foobar2000:Query_syntax|Query Syntax]] article.

== Syntax ==

A title formatting script consists of any combination of literal text, field references, function calls, comments, and line break characters. The script always outputs a text string (which can be empty).

A '''comment''' is a line starting with two slashes, e.g. {{code|// this is a comment}}.

A '''field reference''' is a field name enclosed in percent signs, for example {{code|%artist%}}.

A '''function call''' starts with a dollar sign, followed by the function name and the parameter list. A parameter list can either be empty – denoted as {{code|()}} – or contain one or more parameters separated by commas, for example {{code|$abbr(%artist%)}}. A parameter can be literal text, a field reference, or another function call. Note that there must be no whitespace between the dollar sign and the function name, or the function name and the opening parenthesis of the parameter list.

Any other text is '''literal text'''. In literal text, the character {{code|%}}, {{code|$}}, {{code|[}}, {{code|]}}, or {{code|'}} (apostrophe/single quote) must be escaped by enclosing it in {{code|'}} (apostrophe/single quote) characters. For example, {{code|'['}} (a left bracket in single quotes) results in a literal {{code|[}} (left bracket). As a special case, {{code|<nowiki>''</nowiki>}} (two single quotes in a row) results in one single quote. In the playlist, {{code|<}} and {{code|>}} are also special; see [[#Dimmed and highlighted text|Dimmed and highlighted text]].

When the script is evaluated, the output string is assembled by evaluating the function parameters, function calls, and field references. Comments and line break characters (CR and LF/newline) are ignored; to output a line break, use {{code|$crlf()}}. Each field reference becomes the field's value, as a string. Each function becomes a string or number, and/or a truth value (not output) which can be used by another function.

'''Note: The interface for entering custom columns and grouping schemes for the Default UI playlist does not support line breaks; scripts must be written all on one line, without comments.'''

== Arithmetic functions ==

The functions in this section can be used to perform arithmetic on integer numbers. A string will be automatically converted to a number and vice versa. The conversion to a number uses the longest prefix of the string that can be interpreted as number. Leading whitespace is ignored. Decimal points are not supported. Examples:
* ''c3po'' → 0
* ''4.8'' → 4
* ''-12'' → -12
* ''- 12'' → 0

=== $add(a,b, ...) ===

Adds ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$add(a,b,...)'' is the same as ''$add($add(a,b),...)''.

=== $div(a,b) ===

Divides ''a'' by ''b'' and rounds down to an integer. If ''b'' evaluates to zero, it returns ''a''.

Can be used with an arbitrary number of arguments. ''$div(a,b,...)'' is the same as ''$div($div(a,b),...)''.

=== $greater(a,b) ===

Returns true, if ''a'' is greater than ''b'', otherwise false.

=== $max(a,b) ===

Returns the maximum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$max(a,b,...)'' is the same as ''$max($max(a,b),...)''.

=== $min(a,b) ===

Returns the minimum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$min(a,b,...)'' is the same as ''$min($min(a,b),...)''.

=== $mod(a,b) ===

Computes the remainder of dividing ''a'' through ''b''. The result has the same sign as ''a''. If ''b'' evaluates to zero, the result is ''a''.

Can be used with an arbitrary number of arguments. ''$mod(a,b,...)'' is the same as ''$mod($mod(a,b),...)''.

=== $mul(a,b) ===

Multiplies ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$mul(a,b,...)'' is the same as ''$mul($mul(a,b),...)''.

=== $muldiv(a,b,c) ===

Multiplies ''a'' and ''b'', then divides by ''c''. The result is rounded to the nearest integer.

=== $rand() ===

Generates a random number in the range from 0 to 232-1. Available only in sort-related contexts, such as the ''Edit → Sort → Sort by ...'' menu command.

=== $sub(a,b) ===

Subtracts ''b'' from ''a''.

Can be used with an arbitrary number of arguments. ''$sub(a,b,...)'' is the same as ''$sub($sub(a,b),...)''.

== Boolean functions ==

The functions in this section can be used to work with truth values (''true'' and ''false''), which have no explicit representation in titleformat scripts. They do not return a string or number value. You can use them for more complex conditions with ''$if'' and related functions.

Foobar does not have a concept of TRUE and FALSE in a programming language sense where 0 or empty string are considered FALSE and other values TRUE. Therefore there is no difference between numeric 0 and string representation '0' which both are considered as values, and being attached a boolean value FALSE. Apostrophes are only required to escape certain syntax characters. Values are treated as numbers during arithmetic operations like'' $add()''.

=== $and(expr, ...) ===

Logical And of an arbitrary number of arguments. Returns ''true'', if and only if all ''expr'' arguments evaluate to ''true''.

=== $or(expr, ...) ===

Logical Or of an arbitrary number of arguments. Returns ''true'', if at least one expression evaluates to ''true''.

=== $not(expr) ===

Logical Not. Returns the logical opposite of EXPR: ''false'', if ''expr'' is ''true'' and ''true'' if ''expr'' is false.

=== $xor(expr,...) ===

Logical Exclusive-or of an arbitrary number of arguments. Returns ''true'', if an odd number of arguments evaluate to ''true''.

Special case: ''$xor(expr1,expr2)'' returns ''true'', if EXPR1 or EXPR2 is ''true''. If both expressions are true, returns ''false''.

== Control flow functions ==

The functions in this section can be used to conditionally execute statements.

=== [...] (conditional section) ===

Evaluates the expression between ''['' and '']''. If it has the truth value ''true'', its string value and the truth value ''true'' are returned. Otherwise an empty string and ''false'' are returned.

Example: ''[%artist%]'' returns the value of the artist tag, if it exists. Otherwise it returns nothing, when ''artist'' would return "?".

=== $if(cond,then) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, ''false'' is returned.

Plain strings are FALSE. Field lookups and functions can introduce a boolean value of TRUE. 
Examples: 
1
<code>
#False:
$if(0,True,False)
# False:
$if('0',True,False)
# True or False:
[$add(%rating%,1)]
</code> 
The last one would display the value of %rating% plus one, if and only if %rating% is set for the track.

2
Ignore inserting the %album artist%, if it contains the word "various".
<code>
# Wrong:
$if([%album artist%=Various],,%artist%-)
# Good approach:
$if($stricmp(%album artist%,Various),,%artist%-)
</code>

=== $if(cond,then,else) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, the ''else'' part is evaluated and its value returned.

=== $if2(expr,else) ===

Like ''$if(expr,expr,else)'' except that ''expr'' is only evaluated once. In other words, if expression ''expr'' is true, ''expr'' is returned, otherwise the ''else'' part is evaluated and ''expr'' is returned as true.

=== $if3(a1,a2,...,aN,else) ===

Evaluates arguments ''a1'' ... ''aN'', until one is found that evaluates to ''true''. If that happens, its value is returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifequal(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is equal to ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifgreater(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is greater than ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $iflonger(str,n,then,else) ===

Compares the length of the string ''str'' to the number ''n'', if ''str'' is longer than ''n'' characters, the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $select(n,a1,...,aN) ===

If the value of ''n'' is between 1 and N, ''an'' is evaluated and its value returned. Otherwise ''false'' is returned.

== String functions ==

The functions in this section can be used to manipulate character strings.

=== $abbr(str) ===

Returns abbreviation of string ''str''. Words which begin with an alphanumeric character are shortened to the first character. Spaces and parentheses are stripped. Example:
* $abbr('This is a Long Title (12-inch version) [needs tags]') → TiaLT1v[needst

=== $abbr(str,len) ===

Returns abbreviation of ''str'', if ''str'' is longer than ''len'' characters, otherwise returns ''str''.

=== $ansi(str) ===

Converts string ''str'' to system codepage and back. Any characters that are not present in the system codepage will be removed / replaced. Useful for mass-renaming files to ensure compatibility with non-unicode-capable software.

=== $ascii(str) ===

Converts string ''str'' to ASCII. Any characters that are not present in ASCII will be removed / replaced.

=== $caps(str) ===

Converts first letter in every word of string ''str'' to uppercase, and all other letters to lowercase.

=== $caps2(str) ===

Converts first letter in every word of string ''str'' to uppercase, and leaves all other letters as they are.

=== $char(nbr) ===

Returns Unicode character of ''nbr''. You can search for characters and find the matching decimal number on this [http://www.fileformat.info/info/unicode/char/search.htm site].

=== $crc32(str) ===

Computes the CRC32 of the string ''str'' as a number. Intended for use in coloring scripts.

Example: $rgb($mod($crc32(%album%),256),128,128)

=== $crlf() ===

Inserts end-of-line marker (carriage return, line feed). Can be used to generate multiple lines in the output, for example for the tooltip of the system notification area ("systray") icon.

=== $cut(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $left(a,len). Negative numbers produce the entire string. Examples:
* ''$cut('abc123',3)'' → abc
* ''$cut('abc123',0)'' → (nothing)
* ''$cut('abc123',-1)'' → abc123

=== $directory(path) ===

Extracts only the directory name (not full path, ie given path as 'D:\music\jazz\filename.mp3', this will output 'jazz') from the file ''path''.

=== $directory(path,n) ===

Extracts directory name from the file ''path''; goes up by ''n'' levels.

=== $directory_path(path) ===

Extracts directory path from the file ''path''.
ie. given path as 'D:\music\jazz\filename.mp3', this will output 'D:\music\jazz'

=== $ext(path) ===

Extracts file extension from string ''path''; a file name or full path.

=== $filename(path) ===

Extracts file name from full ''path''.

=== $fix_eol(str) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by " (...)". Otherwise ''str'' is returned unaltered.

=== $fix_eol(str,indicator) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by ''indicator''. Otherwise ''str'' is returned unaltered.

=== $hex(int,len) ===

Formats the integer number ''int'' in hexadecimal notation with ''len'' digits. Pads with zeros from the left if necessary.

=== $insert(str,insert,n) ===

Inserts ''insert'' into ''str'' after ''n'' characters.

=== $left(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $cut(str,len). Negative numbers produce the entire string. Examples:
* ''$left('abc123',3)'' → abc
* ''$left('abc123',0)'' → (nothing)
* ''$left('abc123',-1)'' → abc123

=== $len(str) ===

Returns length of string ''str'' in characters.

=== $len2(str) ===

Returns length of string ''str'' in characters, respecting double-width character rules (double-width characters will be counted as two).

=== $longer(str1,str2) ===

Returns ''true'', if string ''str1'' is longer than string ''str2'', false otherwise.

=== $lower(str) ===

Converts string ''str'' to lowercase.

=== $longest(arg,...) ===

Returns the longest of its arguments. Can be used with an arbitrary number of strings.

=== $num(nbr,len) ===

Formats the integer number ''nbr'' in decimal notation with ''len'' characters. Pads with zeros from the left if necessary. ''len'' includes the dash when the number is negative. If ''nbr'' is not numeric, it is treated as zero. Examples:

* ''$num(123,5)'' → 00123
* ''$num(-123,5)'' → -0123
* ''$num(4.8,5)'' → 00004
* ''$num(A1,5)'' → 00000

=== $pad(str,len) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad(str,len,char) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len,char) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $padcut(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the right of ''str'' to make the result ''len'' characters long.

=== $padcut(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the right of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the left of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the left of ''str'' to make the result ''len'' characters long.

=== $progress(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with.

Example:''$progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'#','=')'' produces "====#===============", the # character is moving with playback position.

=== $progress2(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with. Produces different appearance than ''$progress''.

=== $repeat(expr,count) ===

Returns ''count'' copies of ''expr''. Note that ''expr'' is evaluated once before its value is used, so ''$repeat'' cannot be used for loops.

=== $replace(str,search,replace) ===

Replaces all occurrences of string ''search'' in string ''str'' with string ''replace''.

Can also be used with an arbitrary number of arguments. Note that ''$replace(str,search1,replace1,search2,replace2)'' is generally not the same as ''$replace($replace(str,search1,replace1),search2,replace2)''.

Example: ''$replace(ab,a,b,b,c)'' → "bc", ''$replace($replace(ab,a,b),b,c)'' → "cc"

=== $right(str,len) ===

Returns the first ''len'' characters from the right of string ''str''.

=== $roman(int) ===

Formats the integer number ''int'' in roman notation.

=== $rot13(str) ===

Performs [http://en.wikipedia.org/wiki/ROT13 ROT13] transformation to given string.

Example: ''$rot13('foobar2000')'' → "sbbone2000".

=== $shortest(str,...strN) ===

Returns the first shortest element of its arguments. Can be used with an arbitrary number of strings.

=== $strchr(str,char) ===

Returns position of first occurrence of character ''char'' in string ''str''.

Example: ''$strchr(abca,a)'' → 1

=== $strrchr(str,char) ===

Returns positions of last occurrence of character ''char'' in string ''str''.

Example: ''$strrchr(abca,a)'' → 4

=== $strstr(str1,str2) ===

Returns position of first occurrence of string ''str2'' in string ''str1''. Function is case-sensitive.

=== $strcmp(str1,str2) ===

Performs a case-sensitive comparison of the strings ''str1'' and ''str2''.

=== $stricmp(str1,str2) ===

Performs a case-insensitive comparison of the strings ''str1'' and ''str2''.

=== $stripprefix(str) ===

Removes ''A'' and ''The'' prefixes from string ''str''.

=== $stripprefix(str,prefix1,prefix2,...) ===

Removes the specified prefixes from string ''str''.

=== $substr(str,from,to) ===

Returns substring of string ''str'', starting from ''FROM''-th character and ending at ''TO''-th character.

=== $swapprefix(str) ===

Moves ''A'' and ''The'' prefixes to the end of string ''str''.

=== $swapprefix(str,prefix1,prefix2,...) ===

Moves the specified prefixes to the end of string ''str''.

=== $trim(str) ===

Removes leading and trailing spaces from string ''str''.

=== $tab() ===

Inserts one tabulator character.

=== $tab(count) ===

Inserts ''count'' tabulator characters.

=== $upper(str) ===

Converts string ''str'' to uppercase.

== Track info fields and functions ==

The functions and fields in this section can be used to access information about tracks.

=== Metadata fields and functions ===

Generally, metadata from the files (whether in tags or a cue sheet) is mapped directly to a field which can be referenced case-insensitively. For example, the first tag named ''URL'' can be referenced as ''%url%'', and the first standard comment tag can be referenced as ''%comment%''.

The following functions are also available for accessing metadata:

==== $meta(name) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ", " as separator.

Example: ''$meta(artist)'' → "He, She, They"

==== $meta(name,n) ====
Returns value of ''n''-th (0,1,2 and so on) tag called ''name''.

Example: ''$meta(artist,1)'' → "She"

==== $meta_sep(name,sep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator.

Example: ''$meta_sep(artist,' + ')'' → "He + She + They"

==== $meta_sep(name,sep,lastsep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator between all but the last two values which are concatenated with ''lastsep''.

Example: ''$meta_sep(artist,', ',', and ')'' → "He, She, and They"

==== $meta_test(...) ====
Returns ''1'', if all given tags exist, ''undefined'' otherwise.

Example: ''$meta_test(artist,title)'' → true

==== $meta_num(name) ====
Returns the number of values for the tag called ''name''.

Example: ''$meta_num(artist)'' → 3

=== Remapped metadata fields ===

The following fields have special remapped values to make writing title format scripts more convenient:

==== %album artist% ====
Name of the artist of the album specified track belongs to. Checks following metadata fields, in this order: "album artist", "artist", "composer", "performer". The difference between this and ''%artist%'' is that ''%album artist%'' is intended for use where consistent value across entire album is needed even when per-track artists values vary.

==== %album% ====
Name of the album specified track belongs to. Checks following metadata fields, in this order: "album", "venue".

==== %artist% ====
Name of the artist of the track. Checks following metadata fields, in this order: "artist", "album artist", "composer", "performer". For a SHOUTcast stream which contains metadata, it is the StreamTitle up to the first "-" character.

==== %discnumber% ====
Index of disc specified track belongs to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %totaldiscs% ====
Index of total discs specified tracks belong to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %track artist% ====
Name of the artist of the track; present only if ''%album artist%'' is different than ''%artist%'' for specific track. Intended for use together with ''%album artist%'', to indicate track-specific artist info, e.g. "%album artist% - %title%[ '//' %track artist%]". In this case, the last part will be displayed only when track-specific artist info is present.

==== %title% ====
Title of the track. If "title" metadata field is missing, file name is used instead. For a SHOUTcast stream which contains metadata, it is the StreamTitle after the first "-" character.

==== %tracknumber% ====
Two-digit index of specified track within the album. Available only when "tracknumber" field is present in track’s metadata. An extra '0' is placed in front of single digit track numbers (5 becomes 05) – otherwise the tracknumber field is returned unchanged (e.g. the following values remain as they are: 006, 05, 104, A3, two, -1, -).

==== %track number% ====
Similar to %tracknumber%, however single digit track numbers are not reformatted to have an extra 0.

==== %totaltracks% ====
Index of total tracks specified tracks belong to, within the album. Available only when "totaltracks" field is present in track’s metadata.

=== Technical information fields ===

==== %bitrate% ====
Bitrate of the track in kilobits per second. VBR files will show a dynamic display for currently played track (outside of the playlist).

==== %channels% ====
Number of channels in the track, as text; either "mono", "stereo" for 1 or 2 channels, respectively, otherwise a number followed by "ch", e.g. "6ch".

==== %channel_mask% ====
Description of the used audio channels in the track, e.g. "FL FR FC LFE SL SR". Introduced in foobar2000 preview 2024-06-30.

==== %codec% ====
Name of codec used to encode the track, e.g. PCM, FLAC, MP3, or AAC. If exact codec name is not available, file extension is used. The Default UI's standard Codec column displays the same info, but sometimes adds details, e.g. "MP3 / VBR V2" or "AAC / LC".

==== %filesize% ====
The exact file size in bytes.
Old version: <code>%_filesize%</code>

==== %filesize_natural% ====
The approximate file size, automatically formatted in appropriate units such as megabytes or kilobytes, e.g. "8.49 MB"

==== %length% ====
The length of the track formatted as hours, minutes, and seconds, rounded to the nearest second.
Old version: <code>%_time_total%</code>

==== %length_ex% ====
The length of the track formatted as hours, minutes, seconds, and milliseconds, rounded to the nearest millisecond.

==== %length_seconds% ====
The length of the track in seconds, rounded to the nearest second.
Old version: <code>%_time_total_seconds%</code>

==== %length_seconds_fp% ====
The length of the track in seconds as a floating point number.

==== %length_samples% ====
The length of the track in samples.

==== %samplerate% ====
Sample rate of the track, in Hz.

=== Technical information functions ===

==== $info(name) ====
Returns value of technical information field called ''name''.

For convenience, the '''%__name%''' alias is also available.

Example: ''$info(channels)'' → 2

Here is an '''informative''' list of recognized fields. Some of these depend on the media file type being queried.

{| border="0" cellspacing="0" cellpadding="2"
! field name
! Description
|-
| colspan="2" style="background-color:#CCF"|'''General'''
|-
|codec
| style="background-color:#EEF"|'''Codec''' (''e.g.'' MP3)
|-
|codec_profile
| style="background-color:#EEF"|'''Codec Profile''' (''e.g.'' CBR)
|-
|samplerate
| style="background-color:#EEF"|'''Sample Rate''', in hertz (''e.g.'' 44100)
|-
|bitrate
| style="background-color:#EEF"|'''Bitrate''', in kilobits per second (''e.g.'' 320)
|-
|tool
| style="background-color:#EEF"|'''Tool''' used to produce the file, possibly guessed (''e.g.'' LAME3.97)
|-
|encoding
| style="background-color:#EEF"|'''Encoding''' lossiness (''e.g.'' lossy)
|-
|channels
| style="background-color:#EEF"|'''Channels''' count (''e.g.'' 2 <nowiki>[for stereo]</nowiki>)
|-
|bitspersample
| style="background-color:#EEF"|'''Bits Per Sample''' (''e.g.'' 16)
|-
|tagtype
| style="background-color:#EEF"|'''Tag Type''', comma-separated list of tag formats (''e.g.'' id3v2|apev2)
|-
|cue_embedded
| style="background-color:#EEF"|'''Embedded Cuesheet''' presence (''e.g.'' no <nowiki>[may be empty!]</nowiki>)
|-
|md5
| style="background-color:#EEF"|'''Audio MD5''' hash, if container defines it (''e.g.'' 1E24A910D91EF09A8CF403C9B6963961)
|-
|WAVEFORMATEXTENSIBLE_CHANNEL_MASK
| style="background-color:#EEF"|'''Channel mask''', channel layout of the track coded as hex (''e.g.'' 0x0003 for regular stereo)
|-
| colspan="2" style="background-color:#CCF"|'''Other'''
|-
|ENC_DELAY
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_delay''' value for gapless playback (''e.g.'' 576)
|-
|ENC_PADDING
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_padding''' value for gapless playback (''e.g.'' 1536)
|-
|MP3_ACCURATE_LENGTH
| style="background-color:#EEF"|MP3 duration (%length% etc.) takes into account LAME or iTunes gapless playback info (''e.g.'' yes)*
|-
|MP3_STEREO_MODE
| style="background-color:#EEF"|Stereo mode used in MP3 file (''e.g.'' mono, stereo, joint stereo, etc.)
|-
|VERSION
| style="background-color:#EEF"|'''Version''' of tool (''e.g.'' 3.99)
|-
|FLAGS
| style="background-color:#EEF"|'''Flags''' of tool (''e.g.'' 22)
|-
|channel_mode
| style="background-color:#EEF"|'''Channel Mode''', description of channels (note: this field was only used by obsolete foo_ac3. ''e.g.'' 3 front, 2 rear surround channels + LFE)
|}

<div style="font-size: 90%"><nowiki>*</nowiki> ''MP3_ACCURATE_LENGTH won't exist if gapless playback info isn't present or the file is not an MP3. The info can be in a LAME tag in the VBR header, or in an iTunSMPB ID3v2 comment tag. Gapless playback info is taken into account in .m4a files, but there's no special field to say so.''</div>

==== $channels() ====
The number of channels in text format.

Example: ''$channels()'' → "stereo"

==== %replaygain_album_gain% ====
The ReplayGain album gain value.

==== %replaygain_album_peak% ====
The ReplayGain album peak value.

==== %replaygain_album_peak_db% ====
The ReplayGain album peak value in decibels.

==== %replaygain_track_gain% ====
The ReplayGain track gain value.

==== %replaygain_track_peak% ====
The ReplayGain track peak value.

==== %replaygain_track_peak_db% ====
The ReplayGain track peak value in decibels.

=== Special fields ===

==== %filename% ====
The filename without directory and extension.

==== %filename_ext% ====
The filename with extension, but without the directory.

==== %directoryname% ====
The name of the parent directory only, not the complete path.

==== %last_modified% ====
The date and time the file was last modified. Eg: ''2005-12-22 00:04:10''

==== %path% ====
The complete path, including the filename and extension.

==== %_path_raw% ====
The path as URL including the protocol scheme.

==== %subsong% ====
The subsong index. The subsong index is used to distuingish multiple tracks in a single file, for example for cue sheets, tracker modules and various container formats.

==== %_foobar2000_version% ====
A string representing the version of foobar2000.

== Time and date functions ==

These functions are used to manipulate time/date strings, notably (but not limited to), [[Foobar2000:Titleformat_Playback_Statistics|those gathered]] by the [[Foobar2000:Components/Playback Statistics v3.x (foo playcount)|Playback Statistics component]].

=== $year(time) ===
Retrieves the year part (formatted as four digits) from a time/date string.

=== $month(time) ===
Retrieves the month part (formatted as two digits) from a time/date string.

=== $day_of_month(time) ===
Retrieves the day of month part (formatted as two digits) from a time/date string.

=== $date(time) ===
Retrieves the date part (formatted as YYYY-MM-DD) from a time/date string.

=== $time(time) ===
Retrieves the time part (formatted as HH:MM:SS or HH:MM) from a date/time string.

== Variable operations ==

Variables can be used to store strings and numbers. They cannot store truth values. They are best used to store intermediate results that you need multiple times. Variable names are not case-sensitive.

For example:
{| border="0" cellspacing="0" cellpadding="2"
! code
! output
|-
|<pre>$put(foo,bar)$char(10)
$get(foo)$char(10)
$get(Foo)$char(10)
$puts(foo,2000)$char(10)
$get(foo)$char(10)</pre>
| style="background-color:#EEF" |<pre>bar
bar
bar

2000</pre>
|}

=== $get(name) ===
Returns the value that was last stored in the variable ''name'', if the variable was not defined (yet), it returns nothing. The truth value returned by ''$get'' indicates if the variable ''name'' was defined and is a non-empty string.

=== $put(name,value) ===
Stores ''value'' in the variable ''name'' and returns ''value'' unaltered.

=== $puts(name,value) ===
Stores ''value'' in the variable ''name'' and returns nothing.

== Component-specific fields and functions ==

This section lists fields and functions which are specific to certain components. Unless otherwise stated, the fields and functions are only usable in the context of those components.

=== Now playing info ===

The following fields related to the currently playing item are only usable in certain locations outside of the playlist, e.g. in the status bar, the main window title and the copy command script.

==== %playback_time% ====
The elapsed time formatted as [HH:]MM:SS.

==== %playback_time_seconds% ====
The elapsed time in seconds.
Old version: <code>%_time_elapsed%</code>

==== %playback_time_remaining% ====
The time remaining until the track ends, formatted as [HH:]MM:SS.
Old version: <code>%_time_remaining%</code>

==== %playback_time_remaining_seconds% ====
The time remaining until the track ends, in seconds.
Old version: <code>%_time_remaining_seconds%</code>

=== Playlist-only fields ===

The following fields are only usable in playlist display formatting (i.e., the column title formatting patterns).

==== %isplaying% ====
"1" if file is currently playing, empty string otherwise.

==== %ispaused% ====
"1" if playback is paused, empty string otherwise.

==== %list_index% ====
A zero-padded playlist index of specified item. The first item is at index 1.

==== %list_total% ====
The number of items in the playlist.

==== %queue_index% ====
Index of the specified item in the playback queue. If the item has been queued multiple times, %queue_index% evaluates to the first index.

==== %queue_indexes% ====
List of indexes of the specified item in the playback queue. Same as %queue_index% unless the item has been queued more than once.

==== %queue_total% ====
Total amount of tracks in playback queue. Available only for queued tracks, for technical reasons.

=== Playlist text color ===

==== Dimmed and highlighted text ====

In the Default UI playlist, text color can be adjusted by enclosing it in angle-brackets. The only options are to make the text dimmer (mixing the default color with the background color) or brighter (mixing the default color with the highlight color):

* ''<text>'' – dim ''text''
* ''<<text>>'' – dimmer ''text''
* ''<<<text>>>'' – dimmest ''text''
* ''>text<'' – bright ''text''
* ''>>text<<'' – brighter ''text''
* ''>>>text<<<'' – brightest ''text''

==== Historical and Columns UI color functions ====

Prior to version 1.0, the default UI playlist supported the following color functions, which are still available in the Columns UI playlist:

===== $blend(color1,color2,part,total) =====
Returns a color that is a blend between ''color1'' and ''color2''. If ''part'' is smaller than or equal to zero, ''color1'' is returned. If ''part'' is greater than or equal to ''total'', ''color2'' is returned. Otherwise a blended color is returned that is ''part'' parts ''color1'' and ''total''-''part'' parts ''color2''. The blending is performed in the RGB color space.

===== $hsl() =====
Resets the text color to the default color.

===== $hsl(h,s,l) =====
Sets the color for text in the HSL color space. ''h'', ''s'' and ''l'' are the hue, saturation, and lightness of the color for unselected text. The color for selected text is set to the inverse color.
The ranges of ''h'', ''s'', and ''l'' are from 0 to 240; the function is designed to interpret those values in the same way as the standard Windows color dialog.

===== $hsl(h1,s1,l1,h2,s2,l2) =====
Sets the color for text in the HSL color space. ''h1'', ''s1'' and ''l1'' are the hue, saturation, and lightness of the color for unselected text. ''h2'', ''s2'' and ''l2'' are the hue, saturation, and lightness of the color for selected text.

===== $rgb() =====
Resets the text color to the default color.

===== $rgb(r,g,b) =====
Sets the color for text. ''r'', ''g'' and ''b'' are the red, green and blue component of the color for unselected text. The color for selected text is set to the inverse color.

===== $rgb(r1,g1,b1,r2,g2,b2) =====
Sets the color for text. ''r1'', ''g1'' and ''b1'' are the red, green and blue component of the color for unselected text. ''r2'', ''g2'' and ''b2'' are the red, green and blue component of the color for selected text.

===== $transition(string,color1,color2) =====
Inserts color codes into ''string'', so that the first character has ''color1'', the last character has ''color2'', and intermediate characters have blended colors. The blending is performed in the RGB color space. Note that color codes are additional characters that will also be counted by string manipulation functions. For example, if you need to truncate a string, you should do this before applying ''$transition''.

=== Album List ===

* [[Foobar2000:Titleformat_Album_List|Album List Title Formatting]]
* [[Foobar2000:Preferences:Album List|Preferences: Album List]]

=== Playback Statistics ===

The foo_playcount component adds a number of fields for playback statistics and ratings. The fields can be used anywhere track info can be displayed. See the documentation for details:
* [http://www.foobar2000.org/components/view/foo_playcount Playback statistics homepage]
* [[Foobar2000:Titleformat Playback Statistics|Playback statistics titleformat reference]]

=== Playlist Organizer ===

This component adds a number of fields to control the display of a list of playlists. See the documentation for details:
* [[Foobar2000:Components/Playlist Organizer (foo_plorg)#Nodes|Playlist Organizer: Nodes Title Formatting]]

=== Columns UI ===

This component replaces the Default UI framework, including the playlist. See the documentation for details:
* [http://yuo.be/columns.php Columns UI homepage]
* [http://yuo.be/wiki/columns_ui:config:global_variables Global variables reference]
* [http://yuo.be/wiki/columns_ui:config:colour_string Playlist colors reference]
* [http://yuo.be/wiki/columns_ui:config:playlist_switcher_titleformatting Playlist switcher reference]

== Additional Reading ==

* [[Foobar2000:Title Formatting Introduction|Introduction to titleformat scripts]]
* The file '''titleformat_help.html''' in your Foobar2000 directory, e.g. file:///C:/Program%20Files%20(x86)/foobar2000/titleformat_help.html

[[Category:foobar2000 Guides|Titleformat Reference]]

Foobar2000:Title Formatting Reference

2024-10-27T07:23:13Z

Case: /* Technical information fields */

{{sidebar foobar2000 title formatting}}
This article contains information about built-in title formatting functions and field references, plus additional documentation about fields and functions which can only be used in specific components or which are provided by specific components.

Please see [[Foobar2000:Title Formatting Introduction|Title Formatting Introduction]] for a general overview of title format syntax and its basic rules. The article [[foobar2000:Titleformat Examples|Titleformat Examples]] offers user-submitted examples of code for specific purposes; feel free to add your own if you think it can be of use to others.

For details of the query syntax, which uses some of these fields to find files for playlists, etc., see the [[Foobar2000:Query_syntax|Query Syntax]] article.

== Syntax ==

A title formatting script consists of any combination of literal text, field references, function calls, comments, and line break characters. The script always outputs a text string (which can be empty).

A '''comment''' is a line starting with two slashes, e.g. {{code|// this is a comment}}.

A '''field reference''' is a field name enclosed in percent signs, for example {{code|%artist%}}.

A '''function call''' starts with a dollar sign, followed by the function name and the parameter list. A parameter list can either be empty – denoted as {{code|()}} – or contain one or more parameters separated by commas, for example {{code|$abbr(%artist%)}}. A parameter can be literal text, a field reference, or another function call. Note that there must be no whitespace between the dollar sign and the function name, or the function name and the opening parenthesis of the parameter list.

Any other text is '''literal text'''. In literal text, the character {{code|%}}, {{code|$}}, {{code|[}}, {{code|]}}, or {{code|'}} (apostrophe/single quote) must be escaped by enclosing it in {{code|'}} (apostrophe/single quote) characters. For example, {{code|'['}} (a left bracket in single quotes) results in a literal {{code|[}} (left bracket). As a special case, {{code|<nowiki>''</nowiki>}} (two single quotes in a row) results in one single quote. In the playlist, {{code|<}} and {{code|>}} are also special; see [[#Dimmed and highlighted text|Dimmed and highlighted text]].

When the script is evaluated, the output string is assembled by evaluating the function parameters, function calls, and field references. Comments and line break characters (CR and LF/newline) are ignored; to output a line break, use {{code|$crlf()}}. Each field reference becomes the field's value, as a string. Each function becomes a string or number, and/or a truth value (not output) which can be used by another function.

'''Note: The interface for entering custom columns and grouping schemes for the Default UI playlist does not support line breaks; scripts must be written all on one line, without comments.'''

== Arithmetic functions ==

The functions in this section can be used to perform arithmetic on integer numbers. A string will be automatically converted to a number and vice versa. The conversion to a number uses the longest prefix of the string that can be interpreted as number. Leading whitespace is ignored. Decimal points are not supported. Examples:
* ''c3po'' → 0
* ''4.8'' → 4
* ''-12'' → -12
* ''- 12'' → 0

=== $add(a,b, ...) ===

Adds ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$add(a,b,...)'' is the same as ''$add($add(a,b),...)''.

=== $div(a,b) ===

Divides ''a'' by ''b'' and rounds down to an integer. If ''b'' evaluates to zero, it returns ''a''.

Can be used with an arbitrary number of arguments. ''$div(a,b,...)'' is the same as ''$div($div(a,b),...)''.

=== $greater(a,b) ===

Returns true, if ''a'' is greater than ''b'', otherwise false.

=== $max(a,b) ===

Returns the maximum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$max(a,b,...)'' is the same as ''$max($max(a,b),...)''.

=== $min(a,b) ===

Returns the minimum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$min(a,b,...)'' is the same as ''$min($min(a,b),...)''.

=== $mod(a,b) ===

Computes the remainder of dividing ''a'' through ''b''. The result has the same sign as ''a''. If ''b'' evaluates to zero, the result is ''a''.

Can be used with an arbitrary number of arguments. ''$mod(a,b,...)'' is the same as ''$mod($mod(a,b),...)''.

=== $mul(a,b) ===

Multiplies ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$mul(a,b,...)'' is the same as ''$mul($mul(a,b),...)''.

=== $muldiv(a,b,c) ===

Multiplies ''a'' and ''b'', then divides by ''c''. The result is rounded to the nearest integer.

=== $rand() ===

Generates a random number in the range from 0 to 232-1. Available only in sort-related contexts, such as the ''Edit → Sort → Sort by ...'' menu command.

=== $sub(a,b) ===

Subtracts ''b'' from ''a''.

Can be used with an arbitrary number of arguments. ''$sub(a,b,...)'' is the same as ''$sub($sub(a,b),...)''.

== Boolean functions ==

The functions in this section can be used to work with truth values (''true'' and ''false''), which have no explicit representation in titleformat scripts. They do not return a string or number value. You can use them for more complex conditions with ''$if'' and related functions.

Foobar does not have a concept of TRUE and FALSE in a programming language sense where 0 or empty string are considered FALSE and other values TRUE. Therefore there is no difference between numeric 0 and string representation '0' which both are considered as values, and being attached a boolean value FALSE. Apostrophes are only required to escape certain syntax characters. Values are treated as numbers during arithmetic operations like'' $add()''.

=== $and(expr, ...) ===

Logical And of an arbitrary number of arguments. Returns ''true'', if and only if all ''expr'' arguments evaluate to ''true''.

=== $or(expr, ...) ===

Logical Or of an arbitrary number of arguments. Returns ''true'', if at least one expression evaluates to ''true''.

=== $not(expr) ===

Logical Not. Returns the logical opposite of EXPR: ''false'', if ''expr'' is ''true'' and ''true'' if ''expr'' is false.

=== $xor(expr,...) ===

Logical Exclusive-or of an arbitrary number of arguments. Returns ''true'', if an odd number of arguments evaluate to ''true''.

Special case: ''$xor(expr1,expr2)'' returns ''true'', if EXPR1 or EXPR2 is ''true''. If both expressions are true, returns ''false''.

== Control flow functions ==

The functions in this section can be used to conditionally execute statements.

=== [...] (conditional section) ===

Evaluates the expression between ''['' and '']''. If it has the truth value ''true'', its string value and the truth value ''true'' are returned. Otherwise an empty string and ''false'' are returned.

Example: ''[%artist%]'' returns the value of the artist tag, if it exists. Otherwise it returns nothing, when ''artist'' would return "?".

=== $if(cond,then) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, ''false'' is returned.

Plain strings are FALSE. Field lookups and functions can introduce a boolean value of TRUE. 
Examples: 
1
<code>
#False:
$if(0,True,False)
# False:
$if('0',True,False)
# True or False:
[$add(%rating%,1)]
</code> 
The last one would display the value of %rating% plus one, if and only if %rating% is set for the track.

2
Ignore inserting the %album artist%, if it contains the word "various".
<code>
# Wrong:
$if([%album artist%=Various],,%artist%-)
# Good approach:
$if($stricmp(%album artist%,Various),,%artist%-)
</code>

=== $if(cond,then,else) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, the ''else'' part is evaluated and its value returned.

=== $if2(expr,else) ===

Like ''$if(expr,expr,else)'' except that ''expr'' is only evaluated once. In other words, if expression ''expr'' is true, ''expr'' is returned, otherwise the ''else'' part is evaluated and ''expr'' is returned as true.

=== $if3(a1,a2,...,aN,else) ===

Evaluates arguments ''a1'' ... ''aN'', until one is found that evaluates to ''true''. If that happens, its value is returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifequal(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is equal to ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifgreater(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is greater than ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $iflonger(str,n,then,else) ===

Compares the length of the string ''str'' to the number ''n'', if ''str'' is longer than ''n'' characters, the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $select(n,a1,...,aN) ===

If the value of ''n'' is between 1 and N, ''an'' is evaluated and its value returned. Otherwise ''false'' is returned.

== String functions ==

The functions in this section can be used to manipulate character strings.

=== $abbr(str) ===

Returns abbreviation of string ''str''. Words which begin with an alphanumeric character are shortened to the first character. Spaces and parentheses are stripped. Example:
* $abbr('This is a Long Title (12-inch version) [needs tags]') → TiaLT1v[needst

=== $abbr(str,len) ===

Returns abbreviation of ''str'', if ''str'' is longer than ''len'' characters, otherwise returns ''str''.

=== $ansi(str) ===

Converts string ''str'' to system codepage and back. Any characters that are not present in the system codepage will be removed / replaced. Useful for mass-renaming files to ensure compatibility with non-unicode-capable software.

=== $ascii(str) ===

Converts string ''str'' to ASCII. Any characters that are not present in ASCII will be removed / replaced.

=== $caps(str) ===

Converts first letter in every word of string ''str'' to uppercase, and all other letters to lowercase.

=== $caps2(str) ===

Converts first letter in every word of string ''str'' to uppercase, and leaves all other letters as they are.

=== $char(nbr) ===

Returns Unicode character of ''nbr''. You can search for characters and find the matching decimal number on this [http://www.fileformat.info/info/unicode/char/search.htm site].

=== $crc32(str) ===

Computes the CRC32 of the string ''str'' as a number. Intended for use in coloring scripts.

Example: $rgb($mod($crc32(%album%),256),128,128)

=== $crlf() ===

Inserts end-of-line marker (carriage return, line feed). Can be used to generate multiple lines in the output, for example for the tooltip of the system notification area ("systray") icon.

=== $cut(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $left(a,len). Negative numbers produce the entire string. Examples:
* ''$cut('abc123',3)'' → abc
* ''$cut('abc123',0)'' → (nothing)
* ''$cut('abc123',-1)'' → abc123

=== $directory(path) ===

Extracts only the directory name (not full path, ie given path as 'D:\music\jazz\filename.mp3', this will output 'jazz') from the file ''path''.

=== $directory(path,n) ===

Extracts directory name from the file ''path''; goes up by ''n'' levels.

=== $directory_path(path) ===

Extracts directory path from the file ''path''.
ie. given path as 'D:\music\jazz\filename.mp3', this will output 'D:\music\jazz'

=== $ext(path) ===

Extracts file extension from string ''path''; a file name or full path.

=== $filename(path) ===

Extracts file name from full ''path''.

=== $fix_eol(str) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by " (...)". Otherwise ''str'' is returned unaltered.

=== $fix_eol(str,indicator) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by ''indicator''. Otherwise ''str'' is returned unaltered.

=== $hex(int,len) ===

Formats the integer number ''int'' in hexadecimal notation with ''len'' digits. Pads with zeros from the left if necessary.

=== $insert(str,insert,n) ===

Inserts ''insert'' into ''str'' after ''n'' characters.

=== $left(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $cut(str,len). Negative numbers produce the entire string. Examples:
* ''$left('abc123',3)'' → abc
* ''$left('abc123',0)'' → (nothing)
* ''$left('abc123',-1)'' → abc123

=== $len(str) ===

Returns length of string ''str'' in characters.

=== $len2(str) ===

Returns length of string ''str'' in characters, respecting double-width character rules (double-width characters will be counted as two).

=== $longer(str1,str2) ===

Returns ''true'', if string ''str1'' is longer than string ''str2'', false otherwise.

=== $lower(str) ===

Converts string ''str'' to lowercase.

=== $longest(arg,...) ===

Returns the longest of its arguments. Can be used with an arbitrary number of strings.

=== $num(nbr,len) ===

Formats the integer number ''nbr'' in decimal notation with ''len'' characters. Pads with zeros from the left if necessary. ''len'' includes the dash when the number is negative. If ''nbr'' is not numeric, it is treated as zero. Examples:

* ''$num(123,5)'' → 00123
* ''$num(-123,5)'' → -0123
* ''$num(4.8,5)'' → 00004
* ''$num(A1,5)'' → 00000

=== $pad(str,len) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad(str,len,char) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len,char) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $padcut(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the right of ''str'' to make the result ''len'' characters long.

=== $padcut(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the right of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the left of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the left of ''str'' to make the result ''len'' characters long.

=== $progress(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with.

Example:''$progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'#','=')'' produces "====#===============", the # character is moving with playback position.

=== $progress2(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with. Produces different appearance than ''$progress''.

=== $repeat(expr,count) ===

Returns ''count'' copies of ''expr''. Note that ''expr'' is evaluated once before its value is used, so ''$repeat'' cannot be used for loops.

=== $replace(str,search,replace) ===

Replaces all occurrences of string ''search'' in string ''str'' with string ''replace''.

Can also be used with an arbitrary number of arguments. Note that ''$replace(str,search1,replace1,search2,replace2)'' is generally not the same as ''$replace($replace(str,search1,replace1),search2,replace2)''.

Example: ''$replace(ab,a,b,b,c)'' → "bc", ''$replace($replace(ab,a,b),b,c)'' → "cc"

=== $right(str,len) ===

Returns the first ''len'' characters from the right of string ''str''.

=== $roman(int) ===

Formats the integer number ''int'' in roman notation.

=== $rot13(str) ===

Performs [http://en.wikipedia.org/wiki/ROT13 ROT13] transformation to given string.

Example: ''$rot13('foobar2000')'' → "sbbone2000".

=== $shortest(str,...strN) ===

Returns the first shortest element of its arguments. Can be used with an arbitrary number of strings.

=== $strchr(str,char) ===

Returns position of first occurrence of character ''char'' in string ''str''.

Example: ''$strchr(abca,a)'' → 1

=== $strrchr(str,char) ===

Returns positions of last occurrence of character ''char'' in string ''str''.

Example: ''$strrchr(abca,a)'' → 4

=== $strstr(str1,str2) ===

Returns position of first occurrence of string ''str2'' in string ''str1''. Function is case-sensitive.

=== $strcmp(str1,str2) ===

Performs a case-sensitive comparison of the strings ''str1'' and ''str2''.

=== $stricmp(str1,str2) ===

Performs a case-insensitive comparison of the strings ''str1'' and ''str2''.

=== $stripprefix(str) ===

Removes ''A'' and ''The'' prefixes from string ''str''.

=== $stripprefix(str,prefix1,prefix2,...) ===

Removes the specified prefixes from string ''str''.

=== $substr(str,from,to) ===

Returns substring of string ''str'', starting from ''FROM''-th character and ending at ''TO''-th character.

=== $swapprefix(str) ===

Moves ''A'' and ''The'' prefixes to the end of string ''str''.

=== $swapprefix(str,prefix1,prefix2,...) ===

Moves the specified prefixes to the end of string ''str''.

=== $trim(str) ===

Removes leading and trailing spaces from string ''str''.

=== $tab() ===

Inserts one tabulator character.

=== $tab(count) ===

Inserts ''count'' tabulator characters.

=== $upper(str) ===

Converts string ''str'' to uppercase.

== Track info fields and functions ==

The functions and fields in this section can be used to access information about tracks.

=== Metadata fields and functions ===

Generally, metadata from the files (whether in tags or a cue sheet) is mapped directly to a field which can be referenced case-insensitively. For example, the first tag named ''URL'' can be referenced as ''%url%'', and the first standard comment tag can be referenced as ''%comment%''.

The following functions are also available for accessing metadata:

==== $meta(name) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ", " as separator.

Example: ''$meta(artist)'' → "He, She, They"

==== $meta(name,n) ====
Returns value of ''n''-th (0,1,2 and so on) tag called ''name''.

Example: ''$meta(artist,1)'' → "She"

==== $meta_sep(name,sep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator.

Example: ''$meta_sep(artist,' + ')'' → "He + She + They"

==== $meta_sep(name,sep,lastsep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator between all but the last two values which are concatenated with ''lastsep''.

Example: ''$meta_sep(artist,', ',', and ')'' → "He, She, and They"

==== $meta_test(...) ====
Returns ''1'', if all given tags exist, ''undefined'' otherwise.

Example: ''$meta_test(artist,title)'' → true

==== $meta_num(name) ====
Returns the number of values for the tag called ''name''.

Example: ''$meta_num(artist)'' → 3

=== Remapped metadata fields ===

The following fields have special remapped values to make writing title format scripts more convenient:

==== %album artist% ====
Name of the artist of the album specified track belongs to. Checks following metadata fields, in this order: "album artist", "artist", "composer", "performer". The difference between this and ''%artist%'' is that ''%album artist%'' is intended for use where consistent value across entire album is needed even when per-track artists values vary.

==== %album% ====
Name of the album specified track belongs to. Checks following metadata fields, in this order: "album", "venue".

==== %artist% ====
Name of the artist of the track. Checks following metadata fields, in this order: "artist", "album artist", "composer", "performer". For a SHOUTcast stream which contains metadata, it is the StreamTitle up to the first "-" character.

==== %discnumber% ====
Index of disc specified track belongs to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %totaldiscs% ====
Index of total discs specified tracks belong to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %track artist% ====
Name of the artist of the track; present only if ''%album artist%'' is different than ''%artist%'' for specific track. Intended for use together with ''%album artist%'', to indicate track-specific artist info, e.g. "%album artist% - %title%[ '//' %track artist%]". In this case, the last part will be displayed only when track-specific artist info is present.

==== %title% ====
Title of the track. If "title" metadata field is missing, file name is used instead. For a SHOUTcast stream which contains metadata, it is the StreamTitle after the first "-" character.

==== %tracknumber% ====
Two-digit index of specified track within the album. Available only when "tracknumber" field is present in track’s metadata. An extra '0' is placed in front of single digit track numbers (5 becomes 05) – otherwise the tracknumber field is returned unchanged (e.g. the following values remain as they are: 006, 05, 104, A3, two, -1, -).

==== %track number% ====
Similar to %tracknumber%, however single digit track numbers are not reformatted to have an extra 0.

==== %totaltracks% ====
Index of total tracks specified tracks belong to, within the album. Available only when "totaltracks" field is present in track’s metadata.

=== Technical information fields ===

==== %bitrate% ====
Bitrate of the track in kilobits per second. VBR files will show a dynamic display for currently played track (outside of the playlist).

==== %channels% ====
Number of channels in the track, as text; either "mono", "stereo" for 1 or 2 channels, respectively, otherwise a number followed by "ch", e.g. "6ch".

==== %channel_mask% ====
Description of the used audio channels in the track, e.g. "FL FR FC LFE SL SR".

==== %codec% ====
Name of codec used to encode the track, e.g. PCM, FLAC, MP3, or AAC. If exact codec name is not available, file extension is used. The Default UI's standard Codec column displays the same info, but sometimes adds details, e.g. "MP3 / VBR V2" or "AAC / LC".

==== %filesize% ====
The exact file size in bytes.
Old version: <code>%_filesize%</code>

==== %filesize_natural% ====
The approximate file size, automatically formatted in appropriate units such as megabytes or kilobytes, e.g. "8.49 MB"

==== %length% ====
The length of the track formatted as hours, minutes, and seconds, rounded to the nearest second.
Old version: <code>%_time_total%</code>

==== %length_ex% ====
The length of the track formatted as hours, minutes, seconds, and milliseconds, rounded to the nearest millisecond.

==== %length_seconds% ====
The length of the track in seconds, rounded to the nearest second.
Old version: <code>%_time_total_seconds%</code>

==== %length_seconds_fp% ====
The length of the track in seconds as a floating point number.

==== %length_samples% ====
The length of the track in samples.

==== %samplerate% ====
Sample rate of the track, in Hz.

=== Technical information functions ===

==== $info(name) ====
Returns value of technical information field called ''name''.

For convenience, the '''%__name%''' alias is also available.

Example: ''$info(channels)'' → 2

Here is an '''informative''' list of recognized fields. Some of these depend on the media file type being queried.

{| border="0" cellspacing="0" cellpadding="2"
! field name
! Description
|-
| colspan="2" style="background-color:#CCF"|'''General'''
|-
|codec
| style="background-color:#EEF"|'''Codec''' (''e.g.'' MP3)
|-
|codec_profile
| style="background-color:#EEF"|'''Codec Profile''' (''e.g.'' CBR)
|-
|samplerate
| style="background-color:#EEF"|'''Sample Rate''', in hertz (''e.g.'' 44100)
|-
|bitrate
| style="background-color:#EEF"|'''Bitrate''', in kilobits per second (''e.g.'' 320)
|-
|tool
| style="background-color:#EEF"|'''Tool''' used to produce the file, possibly guessed (''e.g.'' LAME3.97)
|-
|encoding
| style="background-color:#EEF"|'''Encoding''' lossiness (''e.g.'' lossy)
|-
|channels
| style="background-color:#EEF"|'''Channels''' count (''e.g.'' 2 <nowiki>[for stereo]</nowiki>)
|-
|bitspersample
| style="background-color:#EEF"|'''Bits Per Sample''' (''e.g.'' 16)
|-
|tagtype
| style="background-color:#EEF"|'''Tag Type''', comma-separated list of tag formats (''e.g.'' id3v2|apev2)
|-
|cue_embedded
| style="background-color:#EEF"|'''Embedded Cuesheet''' presence (''e.g.'' no <nowiki>[may be empty!]</nowiki>)
|-
|md5
| style="background-color:#EEF"|'''Audio MD5''' hash, if container defines it (''e.g.'' 1E24A910D91EF09A8CF403C9B6963961)
|-
|WAVEFORMATEXTENSIBLE_CHANNEL_MASK
| style="background-color:#EEF"|'''Channel mask''', channel layout of the track coded as hex (''e.g.'' 0x0003 for regular stereo)
|-
| colspan="2" style="background-color:#CCF"|'''Other'''
|-
|ENC_DELAY
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_delay''' value for gapless playback (''e.g.'' 576)
|-
|ENC_PADDING
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_padding''' value for gapless playback (''e.g.'' 1536)
|-
|MP3_ACCURATE_LENGTH
| style="background-color:#EEF"|MP3 duration (%length% etc.) takes into account LAME or iTunes gapless playback info (''e.g.'' yes)*
|-
|MP3_STEREO_MODE
| style="background-color:#EEF"|Stereo mode used in MP3 file (''e.g.'' mono, stereo, joint stereo, etc.)
|-
|VERSION
| style="background-color:#EEF"|'''Version''' of tool (''e.g.'' 3.99)
|-
|FLAGS
| style="background-color:#EEF"|'''Flags''' of tool (''e.g.'' 22)
|-
|channel_mode
| style="background-color:#EEF"|'''Channel Mode''', description of channels (note: this field was only used by obsolete foo_ac3. ''e.g.'' 3 front, 2 rear surround channels + LFE)
|}

<div style="font-size: 90%"><nowiki>*</nowiki> ''MP3_ACCURATE_LENGTH won't exist if gapless playback info isn't present or the file is not an MP3. The info can be in a LAME tag in the VBR header, or in an iTunSMPB ID3v2 comment tag. Gapless playback info is taken into account in .m4a files, but there's no special field to say so.''</div>

==== $channels() ====
The number of channels in text format.

Example: ''$channels()'' → "stereo"

==== %replaygain_album_gain% ====
The ReplayGain album gain value.

==== %replaygain_album_peak% ====
The ReplayGain album peak value.

==== %replaygain_album_peak_db% ====
The ReplayGain album peak value in decibels.

==== %replaygain_track_gain% ====
The ReplayGain track gain value.

==== %replaygain_track_peak% ====
The ReplayGain track peak value.

==== %replaygain_track_peak_db% ====
The ReplayGain track peak value in decibels.

=== Special fields ===

==== %filename% ====
The filename without directory and extension.

==== %filename_ext% ====
The filename with extension, but without the directory.

==== %directoryname% ====
The name of the parent directory only, not the complete path.

==== %last_modified% ====
The date and time the file was last modified. Eg: ''2005-12-22 00:04:10''

==== %path% ====
The complete path, including the filename and extension.

==== %_path_raw% ====
The path as URL including the protocol scheme.

==== %subsong% ====
The subsong index. The subsong index is used to distuingish multiple tracks in a single file, for example for cue sheets, tracker modules and various container formats.

==== %_foobar2000_version% ====
A string representing the version of foobar2000.

== Time and date functions ==

These functions are used to manipulate time/date strings, notably (but not limited to), [[Foobar2000:Titleformat_Playback_Statistics|those gathered]] by the [[Foobar2000:Components/Playback Statistics v3.x (foo playcount)|Playback Statistics component]].

=== $year(time) ===
Retrieves the year part (formatted as four digits) from a time/date string.

=== $month(time) ===
Retrieves the month part (formatted as two digits) from a time/date string.

=== $day_of_month(time) ===
Retrieves the day of month part (formatted as two digits) from a time/date string.

=== $date(time) ===
Retrieves the date part (formatted as YYYY-MM-DD) from a time/date string.

=== $time(time) ===
Retrieves the time part (formatted as HH:MM:SS or HH:MM) from a date/time string.

== Variable operations ==

Variables can be used to store strings and numbers. They cannot store truth values. They are best used to store intermediate results that you need multiple times. Variable names are not case-sensitive.

For example:
{| border="0" cellspacing="0" cellpadding="2"
! code
! output
|-
|<pre>$put(foo,bar)$char(10)
$get(foo)$char(10)
$get(Foo)$char(10)
$puts(foo,2000)$char(10)
$get(foo)$char(10)</pre>
| style="background-color:#EEF" |<pre>bar
bar
bar

2000</pre>
|}

=== $get(name) ===
Returns the value that was last stored in the variable ''name'', if the variable was not defined (yet), it returns nothing. The truth value returned by ''$get'' indicates if the variable ''name'' was defined and is a non-empty string.

=== $put(name,value) ===
Stores ''value'' in the variable ''name'' and returns ''value'' unaltered.

=== $puts(name,value) ===
Stores ''value'' in the variable ''name'' and returns nothing.

== Component-specific fields and functions ==

This section lists fields and functions which are specific to certain components. Unless otherwise stated, the fields and functions are only usable in the context of those components.

=== Now playing info ===

The following fields related to the currently playing item are only usable in certain locations outside of the playlist, e.g. in the status bar, the main window title and the copy command script.

==== %playback_time% ====
The elapsed time formatted as [HH:]MM:SS.

==== %playback_time_seconds% ====
The elapsed time in seconds.
Old version: <code>%_time_elapsed%</code>

==== %playback_time_remaining% ====
The time remaining until the track ends, formatted as [HH:]MM:SS.
Old version: <code>%_time_remaining%</code>

==== %playback_time_remaining_seconds% ====
The time remaining until the track ends, in seconds.
Old version: <code>%_time_remaining_seconds%</code>

=== Playlist-only fields ===

The following fields are only usable in playlist display formatting (i.e., the column title formatting patterns).

==== %isplaying% ====
"1" if file is currently playing, empty string otherwise.

==== %ispaused% ====
"1" if playback is paused, empty string otherwise.

==== %list_index% ====
A zero-padded playlist index of specified item. The first item is at index 1.

==== %list_total% ====
The number of items in the playlist.

==== %queue_index% ====
Index of the specified item in the playback queue. If the item has been queued multiple times, %queue_index% evaluates to the first index.

==== %queue_indexes% ====
List of indexes of the specified item in the playback queue. Same as %queue_index% unless the item has been queued more than once.

==== %queue_total% ====
Total amount of tracks in playback queue. Available only for queued tracks, for technical reasons.

=== Playlist text color ===

==== Dimmed and highlighted text ====

In the Default UI playlist, text color can be adjusted by enclosing it in angle-brackets. The only options are to make the text dimmer (mixing the default color with the background color) or brighter (mixing the default color with the highlight color):

* ''<text>'' – dim ''text''
* ''<<text>>'' – dimmer ''text''
* ''<<<text>>>'' – dimmest ''text''
* ''>text<'' – bright ''text''
* ''>>text<<'' – brighter ''text''
* ''>>>text<<<'' – brightest ''text''

==== Historical and Columns UI color functions ====

Prior to version 1.0, the default UI playlist supported the following color functions, which are still available in the Columns UI playlist:

===== $blend(color1,color2,part,total) =====
Returns a color that is a blend between ''color1'' and ''color2''. If ''part'' is smaller than or equal to zero, ''color1'' is returned. If ''part'' is greater than or equal to ''total'', ''color2'' is returned. Otherwise a blended color is returned that is ''part'' parts ''color1'' and ''total''-''part'' parts ''color2''. The blending is performed in the RGB color space.

===== $hsl() =====
Resets the text color to the default color.

===== $hsl(h,s,l) =====
Sets the color for text in the HSL color space. ''h'', ''s'' and ''l'' are the hue, saturation, and lightness of the color for unselected text. The color for selected text is set to the inverse color.
The ranges of ''h'', ''s'', and ''l'' are from 0 to 240; the function is designed to interpret those values in the same way as the standard Windows color dialog.

===== $hsl(h1,s1,l1,h2,s2,l2) =====
Sets the color for text in the HSL color space. ''h1'', ''s1'' and ''l1'' are the hue, saturation, and lightness of the color for unselected text. ''h2'', ''s2'' and ''l2'' are the hue, saturation, and lightness of the color for selected text.

===== $rgb() =====
Resets the text color to the default color.

===== $rgb(r,g,b) =====
Sets the color for text. ''r'', ''g'' and ''b'' are the red, green and blue component of the color for unselected text. The color for selected text is set to the inverse color.

===== $rgb(r1,g1,b1,r2,g2,b2) =====
Sets the color for text. ''r1'', ''g1'' and ''b1'' are the red, green and blue component of the color for unselected text. ''r2'', ''g2'' and ''b2'' are the red, green and blue component of the color for selected text.

===== $transition(string,color1,color2) =====
Inserts color codes into ''string'', so that the first character has ''color1'', the last character has ''color2'', and intermediate characters have blended colors. The blending is performed in the RGB color space. Note that color codes are additional characters that will also be counted by string manipulation functions. For example, if you need to truncate a string, you should do this before applying ''$transition''.

=== Album List ===

* [[Foobar2000:Titleformat_Album_List|Album List Title Formatting]]
* [[Foobar2000:Preferences:Album List|Preferences: Album List]]

=== Playback Statistics ===

The foo_playcount component adds a number of fields for playback statistics and ratings. The fields can be used anywhere track info can be displayed. See the documentation for details:
* [http://www.foobar2000.org/components/view/foo_playcount Playback statistics homepage]
* [[Foobar2000:Titleformat Playback Statistics|Playback statistics titleformat reference]]

=== Playlist Organizer ===

This component adds a number of fields to control the display of a list of playlists. See the documentation for details:
* [[Foobar2000:Components/Playlist Organizer (foo_plorg)#Nodes|Playlist Organizer: Nodes Title Formatting]]

=== Columns UI ===

This component replaces the Default UI framework, including the playlist. See the documentation for details:
* [http://yuo.be/columns.php Columns UI homepage]
* [http://yuo.be/wiki/columns_ui:config:global_variables Global variables reference]
* [http://yuo.be/wiki/columns_ui:config:colour_string Playlist colors reference]
* [http://yuo.be/wiki/columns_ui:config:playlist_switcher_titleformatting Playlist switcher reference]

== Additional Reading ==

* [[Foobar2000:Title Formatting Introduction|Introduction to titleformat scripts]]
* The file '''titleformat_help.html''' in your Foobar2000 directory, e.g. file:///C:/Program%20Files%20(x86)/foobar2000/titleformat_help.html

[[Category:foobar2000 Guides|Titleformat Reference]]

Foobar2000:Title Formatting Reference

2024-10-27T07:18:21Z

Case:

{{sidebar foobar2000 title formatting}}
This article contains information about built-in title formatting functions and field references, plus additional documentation about fields and functions which can only be used in specific components or which are provided by specific components.

Please see [[Foobar2000:Title Formatting Introduction|Title Formatting Introduction]] for a general overview of title format syntax and its basic rules. The article [[foobar2000:Titleformat Examples|Titleformat Examples]] offers user-submitted examples of code for specific purposes; feel free to add your own if you think it can be of use to others.

For details of the query syntax, which uses some of these fields to find files for playlists, etc., see the [[Foobar2000:Query_syntax|Query Syntax]] article.

== Syntax ==

A title formatting script consists of any combination of literal text, field references, function calls, comments, and line break characters. The script always outputs a text string (which can be empty).

A '''comment''' is a line starting with two slashes, e.g. {{code|// this is a comment}}.

A '''field reference''' is a field name enclosed in percent signs, for example {{code|%artist%}}.

A '''function call''' starts with a dollar sign, followed by the function name and the parameter list. A parameter list can either be empty – denoted as {{code|()}} – or contain one or more parameters separated by commas, for example {{code|$abbr(%artist%)}}. A parameter can be literal text, a field reference, or another function call. Note that there must be no whitespace between the dollar sign and the function name, or the function name and the opening parenthesis of the parameter list.

Any other text is '''literal text'''. In literal text, the character {{code|%}}, {{code|$}}, {{code|[}}, {{code|]}}, or {{code|'}} (apostrophe/single quote) must be escaped by enclosing it in {{code|'}} (apostrophe/single quote) characters. For example, {{code|'['}} (a left bracket in single quotes) results in a literal {{code|[}} (left bracket). As a special case, {{code|<nowiki>''</nowiki>}} (two single quotes in a row) results in one single quote. In the playlist, {{code|<}} and {{code|>}} are also special; see [[#Dimmed and highlighted text|Dimmed and highlighted text]].

When the script is evaluated, the output string is assembled by evaluating the function parameters, function calls, and field references. Comments and line break characters (CR and LF/newline) are ignored; to output a line break, use {{code|$crlf()}}. Each field reference becomes the field's value, as a string. Each function becomes a string or number, and/or a truth value (not output) which can be used by another function.

'''Note: The interface for entering custom columns and grouping schemes for the Default UI playlist does not support line breaks; scripts must be written all on one line, without comments.'''

== Arithmetic functions ==

The functions in this section can be used to perform arithmetic on integer numbers. A string will be automatically converted to a number and vice versa. The conversion to a number uses the longest prefix of the string that can be interpreted as number. Leading whitespace is ignored. Decimal points are not supported. Examples:
* ''c3po'' → 0
* ''4.8'' → 4
* ''-12'' → -12
* ''- 12'' → 0

=== $add(a,b, ...) ===

Adds ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$add(a,b,...)'' is the same as ''$add($add(a,b),...)''.

=== $div(a,b) ===

Divides ''a'' by ''b'' and rounds down to an integer. If ''b'' evaluates to zero, it returns ''a''.

Can be used with an arbitrary number of arguments. ''$div(a,b,...)'' is the same as ''$div($div(a,b),...)''.

=== $greater(a,b) ===

Returns true, if ''a'' is greater than ''b'', otherwise false.

=== $max(a,b) ===

Returns the maximum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$max(a,b,...)'' is the same as ''$max($max(a,b),...)''.

=== $min(a,b) ===

Returns the minimum of ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$min(a,b,...)'' is the same as ''$min($min(a,b),...)''.

=== $mod(a,b) ===

Computes the remainder of dividing ''a'' through ''b''. The result has the same sign as ''a''. If ''b'' evaluates to zero, the result is ''a''.

Can be used with an arbitrary number of arguments. ''$mod(a,b,...)'' is the same as ''$mod($mod(a,b),...)''.

=== $mul(a,b) ===

Multiplies ''a'' and ''b''.

Can be used with an arbitrary number of arguments. ''$mul(a,b,...)'' is the same as ''$mul($mul(a,b),...)''.

=== $muldiv(a,b,c) ===

Multiplies ''a'' and ''b'', then divides by ''c''. The result is rounded to the nearest integer.

=== $rand() ===

Generates a random number in the range from 0 to 232-1. Available only in sort-related contexts, such as the ''Edit → Sort → Sort by ...'' menu command.

=== $sub(a,b) ===

Subtracts ''b'' from ''a''.

Can be used with an arbitrary number of arguments. ''$sub(a,b,...)'' is the same as ''$sub($sub(a,b),...)''.

== Boolean functions ==

The functions in this section can be used to work with truth values (''true'' and ''false''), which have no explicit representation in titleformat scripts. They do not return a string or number value. You can use them for more complex conditions with ''$if'' and related functions.

Foobar does not have a concept of TRUE and FALSE in a programming language sense where 0 or empty string are considered FALSE and other values TRUE. Therefore there is no difference between numeric 0 and string representation '0' which both are considered as values, and being attached a boolean value FALSE. Apostrophes are only required to escape certain syntax characters. Values are treated as numbers during arithmetic operations like'' $add()''.

=== $and(expr, ...) ===

Logical And of an arbitrary number of arguments. Returns ''true'', if and only if all ''expr'' arguments evaluate to ''true''.

=== $or(expr, ...) ===

Logical Or of an arbitrary number of arguments. Returns ''true'', if at least one expression evaluates to ''true''.

=== $not(expr) ===

Logical Not. Returns the logical opposite of EXPR: ''false'', if ''expr'' is ''true'' and ''true'' if ''expr'' is false.

=== $xor(expr,...) ===

Logical Exclusive-or of an arbitrary number of arguments. Returns ''true'', if an odd number of arguments evaluate to ''true''.

Special case: ''$xor(expr1,expr2)'' returns ''true'', if EXPR1 or EXPR2 is ''true''. If both expressions are true, returns ''false''.

== Control flow functions ==

The functions in this section can be used to conditionally execute statements.

=== [...] (conditional section) ===

Evaluates the expression between ''['' and '']''. If it has the truth value ''true'', its string value and the truth value ''true'' are returned. Otherwise an empty string and ''false'' are returned.

Example: ''[%artist%]'' returns the value of the artist tag, if it exists. Otherwise it returns nothing, when ''artist'' would return "?".

=== $if(cond,then) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, ''false'' is returned.

Plain strings are FALSE. Field lookups and functions can introduce a boolean value of TRUE. 
Examples: 
1
<code>
#False:
$if(0,True,False)
# False:
$if('0',True,False)
# True or False:
[$add(%rating%,1)]
</code> 
The last one would display the value of %rating% plus one, if and only if %rating% is set for the track.

2
Ignore inserting the %album artist%, if it contains the word "various".
<code>
# Wrong:
$if([%album artist%=Various],,%artist%-)
# Good approach:
$if($stricmp(%album artist%,Various),,%artist%-)
</code>

=== $if(cond,then,else) ===

If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, the ''else'' part is evaluated and its value returned.

=== $if2(expr,else) ===

Like ''$if(expr,expr,else)'' except that ''expr'' is only evaluated once. In other words, if expression ''expr'' is true, ''expr'' is returned, otherwise the ''else'' part is evaluated and ''expr'' is returned as true.

=== $if3(a1,a2,...,aN,else) ===

Evaluates arguments ''a1'' ... ''aN'', until one is found that evaluates to ''true''. If that happens, its value is returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifequal(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is equal to ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $ifgreater(int1,int2,then,else) ===

Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is greater than ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $iflonger(str,n,then,else) ===

Compares the length of the string ''str'' to the number ''n'', if ''str'' is longer than ''n'' characters, the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.

=== $select(n,a1,...,aN) ===

If the value of ''n'' is between 1 and N, ''an'' is evaluated and its value returned. Otherwise ''false'' is returned.

== String functions ==

The functions in this section can be used to manipulate character strings.

=== $abbr(str) ===

Returns abbreviation of string ''str''. Words which begin with an alphanumeric character are shortened to the first character. Spaces and parentheses are stripped. Example:
* $abbr('This is a Long Title (12-inch version) [needs tags]') → TiaLT1v[needst

=== $abbr(str,len) ===

Returns abbreviation of ''str'', if ''str'' is longer than ''len'' characters, otherwise returns ''str''.

=== $ansi(str) ===

Converts string ''str'' to system codepage and back. Any characters that are not present in the system codepage will be removed / replaced. Useful for mass-renaming files to ensure compatibility with non-unicode-capable software.

=== $ascii(str) ===

Converts string ''str'' to ASCII. Any characters that are not present in ASCII will be removed / replaced.

=== $caps(str) ===

Converts first letter in every word of string ''str'' to uppercase, and all other letters to lowercase.

=== $caps2(str) ===

Converts first letter in every word of string ''str'' to uppercase, and leaves all other letters as they are.

=== $char(nbr) ===

Returns Unicode character of ''nbr''. You can search for characters and find the matching decimal number on this [http://www.fileformat.info/info/unicode/char/search.htm site].

=== $crc32(str) ===

Computes the CRC32 of the string ''str'' as a number. Intended for use in coloring scripts.

Example: $rgb($mod($crc32(%album%),256),128,128)

=== $crlf() ===

Inserts end-of-line marker (carriage return, line feed). Can be used to generate multiple lines in the output, for example for the tooltip of the system notification area ("systray") icon.

=== $cut(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $left(a,len). Negative numbers produce the entire string. Examples:
* ''$cut('abc123',3)'' → abc
* ''$cut('abc123',0)'' → (nothing)
* ''$cut('abc123',-1)'' → abc123

=== $directory(path) ===

Extracts only the directory name (not full path, ie given path as 'D:\music\jazz\filename.mp3', this will output 'jazz') from the file ''path''.

=== $directory(path,n) ===

Extracts directory name from the file ''path''; goes up by ''n'' levels.

=== $directory_path(path) ===

Extracts directory path from the file ''path''.
ie. given path as 'D:\music\jazz\filename.mp3', this will output 'D:\music\jazz'

=== $ext(path) ===

Extracts file extension from string ''path''; a file name or full path.

=== $filename(path) ===

Extracts file name from full ''path''.

=== $fix_eol(str) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by " (...)". Otherwise ''str'' is returned unaltered.

=== $fix_eol(str,indicator) ===

If ''str'' contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by ''indicator''. Otherwise ''str'' is returned unaltered.

=== $hex(int,len) ===

Formats the integer number ''int'' in hexadecimal notation with ''len'' digits. Pads with zeros from the left if necessary.

=== $insert(str,insert,n) ===

Inserts ''insert'' into ''str'' after ''n'' characters.

=== $left(str,len) ===

Returns first ''len'' characters from the left of the string ''str''. This function is the same as $cut(str,len). Negative numbers produce the entire string. Examples:
* ''$left('abc123',3)'' → abc
* ''$left('abc123',0)'' → (nothing)
* ''$left('abc123',-1)'' → abc123

=== $len(str) ===

Returns length of string ''str'' in characters.

=== $len2(str) ===

Returns length of string ''str'' in characters, respecting double-width character rules (double-width characters will be counted as two).

=== $longer(str1,str2) ===

Returns ''true'', if string ''str1'' is longer than string ''str2'', false otherwise.

=== $lower(str) ===

Converts string ''str'' to lowercase.

=== $longest(arg,...) ===

Returns the longest of its arguments. Can be used with an arbitrary number of strings.

=== $num(nbr,len) ===

Formats the integer number ''nbr'' in decimal notation with ''len'' characters. Pads with zeros from the left if necessary. ''len'' includes the dash when the number is negative. If ''nbr'' is not numeric, it is treated as zero. Examples:

* ''$num(123,5)'' → 00123
* ''$num(-123,5)'' → -0123
* ''$num(4.8,5)'' → 00004
* ''$num(A1,5)'' → 00000

=== $pad(str,len) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad(str,len,char) ===

Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $pad_right(str,len,char) ===

Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.

=== $padcut(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the right of ''str'' to make the result ''len'' characters long.

=== $padcut(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the right of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the left of ''str'' to make the result ''len'' characters long.

=== $padcut_right(str,len,char) ===

Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the left of ''str'' to make the result ''len'' characters long.

=== $progress(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with.

Example:''$progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'#','=')'' produces "====#===============", the # character is moving with playback position.

=== $progress2(pos,range,len,char1,char2) ===

Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with. Produces different appearance than ''$progress''.

=== $repeat(expr,count) ===

Returns ''count'' copies of ''expr''. Note that ''expr'' is evaluated once before its value is used, so ''$repeat'' cannot be used for loops.

=== $replace(str,search,replace) ===

Replaces all occurrences of string ''search'' in string ''str'' with string ''replace''.

Can also be used with an arbitrary number of arguments. Note that ''$replace(str,search1,replace1,search2,replace2)'' is generally not the same as ''$replace($replace(str,search1,replace1),search2,replace2)''.

Example: ''$replace(ab,a,b,b,c)'' → "bc", ''$replace($replace(ab,a,b),b,c)'' → "cc"

=== $right(str,len) ===

Returns the first ''len'' characters from the right of string ''str''.

=== $roman(int) ===

Formats the integer number ''int'' in roman notation.

=== $rot13(str) ===

Performs [http://en.wikipedia.org/wiki/ROT13 ROT13] transformation to given string.

Example: ''$rot13('foobar2000')'' → "sbbone2000".

=== $shortest(str,...strN) ===

Returns the first shortest element of its arguments. Can be used with an arbitrary number of strings.

=== $strchr(str,char) ===

Returns position of first occurrence of character ''char'' in string ''str''.

Example: ''$strchr(abca,a)'' → 1

=== $strrchr(str,char) ===

Returns positions of last occurrence of character ''char'' in string ''str''.

Example: ''$strrchr(abca,a)'' → 4

=== $strstr(str1,str2) ===

Returns position of first occurrence of string ''str2'' in string ''str1''. Function is case-sensitive.

=== $strcmp(str1,str2) ===

Performs a case-sensitive comparison of the strings ''str1'' and ''str2''.

=== $stricmp(str1,str2) ===

Performs a case-insensitive comparison of the strings ''str1'' and ''str2''.

=== $stripprefix(str) ===

Removes ''A'' and ''The'' prefixes from string ''str''.

=== $stripprefix(str,prefix1,prefix2,...) ===

Removes the specified prefixes from string ''str''.

=== $substr(str,from,to) ===

Returns substring of string ''str'', starting from ''FROM''-th character and ending at ''TO''-th character.

=== $swapprefix(str) ===

Moves ''A'' and ''The'' prefixes to the end of string ''str''.

=== $swapprefix(str,prefix1,prefix2,...) ===

Moves the specified prefixes to the end of string ''str''.

=== $trim(str) ===

Removes leading and trailing spaces from string ''str''.

=== $tab() ===

Inserts one tabulator character.

=== $tab(count) ===

Inserts ''count'' tabulator characters.

=== $upper(str) ===

Converts string ''str'' to uppercase.

== Track info fields and functions ==

The functions and fields in this section can be used to access information about tracks.

=== Metadata fields and functions ===

Generally, metadata from the files (whether in tags or a cue sheet) is mapped directly to a field which can be referenced case-insensitively. For example, the first tag named ''URL'' can be referenced as ''%url%'', and the first standard comment tag can be referenced as ''%comment%''.

The following functions are also available for accessing metadata:

==== $meta(name) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ", " as separator.

Example: ''$meta(artist)'' → "He, She, They"

==== $meta(name,n) ====
Returns value of ''n''-th (0,1,2 and so on) tag called ''name''.

Example: ''$meta(artist,1)'' → "She"

==== $meta_sep(name,sep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator.

Example: ''$meta_sep(artist,' + ')'' → "He + She + They"

==== $meta_sep(name,sep,lastsep) ====
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator between all but the last two values which are concatenated with ''lastsep''.

Example: ''$meta_sep(artist,', ',', and ')'' → "He, She, and They"

==== $meta_test(...) ====
Returns ''1'', if all given tags exist, ''undefined'' otherwise.

Example: ''$meta_test(artist,title)'' → true

==== $meta_num(name) ====
Returns the number of values for the tag called ''name''.

Example: ''$meta_num(artist)'' → 3

=== Remapped metadata fields ===

The following fields have special remapped values to make writing title format scripts more convenient:

==== %album artist% ====
Name of the artist of the album specified track belongs to. Checks following metadata fields, in this order: "album artist", "artist", "composer", "performer". The difference between this and ''%artist%'' is that ''%album artist%'' is intended for use where consistent value across entire album is needed even when per-track artists values vary.

==== %album% ====
Name of the album specified track belongs to. Checks following metadata fields, in this order: "album", "venue".

==== %artist% ====
Name of the artist of the track. Checks following metadata fields, in this order: "artist", "album artist", "composer", "performer". For a SHOUTcast stream which contains metadata, it is the StreamTitle up to the first "-" character.

==== %discnumber% ====
Index of disc specified track belongs to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %totaldiscs% ====
Index of total discs specified tracks belong to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

==== %track artist% ====
Name of the artist of the track; present only if ''%album artist%'' is different than ''%artist%'' for specific track. Intended for use together with ''%album artist%'', to indicate track-specific artist info, e.g. "%album artist% - %title%[ '//' %track artist%]". In this case, the last part will be displayed only when track-specific artist info is present.

==== %title% ====
Title of the track. If "title" metadata field is missing, file name is used instead. For a SHOUTcast stream which contains metadata, it is the StreamTitle after the first "-" character.

==== %tracknumber% ====
Two-digit index of specified track within the album. Available only when "tracknumber" field is present in track’s metadata. An extra '0' is placed in front of single digit track numbers (5 becomes 05) – otherwise the tracknumber field is returned unchanged (e.g. the following values remain as they are: 006, 05, 104, A3, two, -1, -).

==== %track number% ====
Similar to %tracknumber%, however single digit track numbers are not reformatted to have an extra 0.

==== %totaltracks% ====
Index of total tracks specified tracks belong to, within the album. Available only when "totaltracks" field is present in track’s metadata.

=== Technical information fields ===

==== %bitrate% ====
Bitrate of the track in kilobits per second. VBR files will show a dynamic display for currently played track (outside of the playlist).

==== %channels% ====
Number of channels in the track, as text; either "mono", "stereo" for 1 or 2 channels, respectively, otherwise a number followed by "ch", e.g. "6ch".

==== %codec% ====
Name of codec used to encode the track, e.g. PCM, FLAC, MP3, or AAC. If exact codec name is not available, file extension is used. The Default UI's standard Codec column displays the same info, but sometimes adds details, e.g. "MP3 / VBR V2" or "AAC / LC".

==== %filesize% ====
The exact file size in bytes.
Old version: <code>%_filesize%</code>

==== %filesize_natural% ====
The approximate file size, automatically formatted in appropriate units such as megabytes or kilobytes, e.g. "8.49 MB"

==== %length% ====
The length of the track formatted as hours, minutes, and seconds, rounded to the nearest second.
Old version: <code>%_time_total%</code>

==== %length_ex% ====
The length of the track formatted as hours, minutes, seconds, and milliseconds, rounded to the nearest millisecond.

==== %length_seconds% ====
The length of the track in seconds, rounded to the nearest second.
Old version: <code>%_time_total_seconds%</code>

==== %length_seconds_fp% ====
The length of the track in seconds as a floating point number.

==== %length_samples% ====
The length of the track in samples.

==== %samplerate% ====
Sample rate of the track, in Hz.

=== Technical information functions ===

==== $info(name) ====
Returns value of technical information field called ''name''.

For convenience, the '''%__name%''' alias is also available.

Example: ''$info(channels)'' → 2

Here is an '''informative''' list of recognized fields. Some of these depend on the media file type being queried.

{| border="0" cellspacing="0" cellpadding="2"
! field name
! Description
|-
| colspan="2" style="background-color:#CCF"|'''General'''
|-
|codec
| style="background-color:#EEF"|'''Codec''' (''e.g.'' MP3)
|-
|codec_profile
| style="background-color:#EEF"|'''Codec Profile''' (''e.g.'' CBR)
|-
|samplerate
| style="background-color:#EEF"|'''Sample Rate''', in hertz (''e.g.'' 44100)
|-
|bitrate
| style="background-color:#EEF"|'''Bitrate''', in kilobits per second (''e.g.'' 320)
|-
|tool
| style="background-color:#EEF"|'''Tool''' used to produce the file, possibly guessed (''e.g.'' LAME3.97)
|-
|encoding
| style="background-color:#EEF"|'''Encoding''' lossiness (''e.g.'' lossy)
|-
|channels
| style="background-color:#EEF"|'''Channels''' count (''e.g.'' 2 <nowiki>[for stereo]</nowiki>)
|-
|bitspersample
| style="background-color:#EEF"|'''Bits Per Sample''' (''e.g.'' 16)
|-
|tagtype
| style="background-color:#EEF"|'''Tag Type''', comma-separated list of tag formats (''e.g.'' id3v2|apev2)
|-
|cue_embedded
| style="background-color:#EEF"|'''Embedded Cuesheet''' presence (''e.g.'' no <nowiki>[may be empty!]</nowiki>)
|-
|md5
| style="background-color:#EEF"|'''Audio MD5''' hash, if container defines it (''e.g.'' 1E24A910D91EF09A8CF403C9B6963961)
|-
|WAVEFORMATEXTENSIBLE_CHANNEL_MASK
| style="background-color:#EEF"|'''Channel mask''', channel layout of the track coded as hex (''e.g.'' 0x0003 for regular stereo)
|-
| colspan="2" style="background-color:#CCF"|'''Other'''
|-
|ENC_DELAY
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_delay''' value for gapless playback (''e.g.'' 576)
|-
|ENC_PADDING
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_padding''' value for gapless playback (''e.g.'' 1536)
|-
|MP3_ACCURATE_LENGTH
| style="background-color:#EEF"|MP3 duration (%length% etc.) takes into account LAME or iTunes gapless playback info (''e.g.'' yes)*
|-
|MP3_STEREO_MODE
| style="background-color:#EEF"|Stereo mode used in MP3 file (''e.g.'' mono, stereo, joint stereo, etc.)
|-
|VERSION
| style="background-color:#EEF"|'''Version''' of tool (''e.g.'' 3.99)
|-
|FLAGS
| style="background-color:#EEF"|'''Flags''' of tool (''e.g.'' 22)
|-
|channel_mode
| style="background-color:#EEF"|'''Channel Mode''', description of channels (note: this field was only used by obsolete foo_ac3. ''e.g.'' 3 front, 2 rear surround channels + LFE)
|}

<div style="font-size: 90%"><nowiki>*</nowiki> ''MP3_ACCURATE_LENGTH won't exist if gapless playback info isn't present or the file is not an MP3. The info can be in a LAME tag in the VBR header, or in an iTunSMPB ID3v2 comment tag. Gapless playback info is taken into account in .m4a files, but there's no special field to say so.''</div>

==== $channels() ====
The number of channels in text format.

Example: ''$channels()'' → "stereo"

==== %replaygain_album_gain% ====
The ReplayGain album gain value.

==== %replaygain_album_peak% ====
The ReplayGain album peak value.

==== %replaygain_album_peak_db% ====
The ReplayGain album peak value in decibels.

==== %replaygain_track_gain% ====
The ReplayGain track gain value.

==== %replaygain_track_peak% ====
The ReplayGain track peak value.

==== %replaygain_track_peak_db% ====
The ReplayGain track peak value in decibels.

=== Special fields ===

==== %filename% ====
The filename without directory and extension.

==== %filename_ext% ====
The filename with extension, but without the directory.

==== %directoryname% ====
The name of the parent directory only, not the complete path.

==== %last_modified% ====
The date and time the file was last modified. Eg: ''2005-12-22 00:04:10''

==== %path% ====
The complete path, including the filename and extension.

==== %_path_raw% ====
The path as URL including the protocol scheme.

==== %subsong% ====
The subsong index. The subsong index is used to distuingish multiple tracks in a single file, for example for cue sheets, tracker modules and various container formats.

==== %_foobar2000_version% ====
A string representing the version of foobar2000.

== Time and date functions ==

These functions are used to manipulate time/date strings, notably (but not limited to), [[Foobar2000:Titleformat_Playback_Statistics|those gathered]] by the [[Foobar2000:Components/Playback Statistics v3.x (foo playcount)|Playback Statistics component]].

=== $year(time) ===
Retrieves the year part (formatted as four digits) from a time/date string.

=== $month(time) ===
Retrieves the month part (formatted as two digits) from a time/date string.

=== $day_of_month(time) ===
Retrieves the day of month part (formatted as two digits) from a time/date string.

=== $date(time) ===
Retrieves the date part (formatted as YYYY-MM-DD) from a time/date string.

=== $time(time) ===
Retrieves the time part (formatted as HH:MM:SS or HH:MM) from a date/time string.

== Variable operations ==

Variables can be used to store strings and numbers. They cannot store truth values. They are best used to store intermediate results that you need multiple times. Variable names are not case-sensitive.

For example:
{| border="0" cellspacing="0" cellpadding="2"
! code
! output
|-
|<pre>$put(foo,bar)$char(10)
$get(foo)$char(10)
$get(Foo)$char(10)
$puts(foo,2000)$char(10)
$get(foo)$char(10)</pre>
| style="background-color:#EEF" |<pre>bar
bar
bar

2000</pre>
|}

=== $get(name) ===
Returns the value that was last stored in the variable ''name'', if the variable was not defined (yet), it returns nothing. The truth value returned by ''$get'' indicates if the variable ''name'' was defined and is a non-empty string.

=== $put(name,value) ===
Stores ''value'' in the variable ''name'' and returns ''value'' unaltered.

=== $puts(name,value) ===
Stores ''value'' in the variable ''name'' and returns nothing.

== Component-specific fields and functions ==

This section lists fields and functions which are specific to certain components. Unless otherwise stated, the fields and functions are only usable in the context of those components.

=== Now playing info ===

The following fields related to the currently playing item are only usable in certain locations outside of the playlist, e.g. in the status bar, the main window title and the copy command script.

==== %playback_time% ====
The elapsed time formatted as [HH:]MM:SS.

==== %playback_time_seconds% ====
The elapsed time in seconds.
Old version: <code>%_time_elapsed%</code>

==== %playback_time_remaining% ====
The time remaining until the track ends, formatted as [HH:]MM:SS.
Old version: <code>%_time_remaining%</code>

==== %playback_time_remaining_seconds% ====
The time remaining until the track ends, in seconds.
Old version: <code>%_time_remaining_seconds%</code>

=== Playlist-only fields ===

The following fields are only usable in playlist display formatting (i.e., the column title formatting patterns).

==== %isplaying% ====
"1" if file is currently playing, empty string otherwise.

==== %ispaused% ====
"1" if playback is paused, empty string otherwise.

==== %list_index% ====
A zero-padded playlist index of specified item. The first item is at index 1.

==== %list_total% ====
The number of items in the playlist.

==== %queue_index% ====
Index of the specified item in the playback queue. If the item has been queued multiple times, %queue_index% evaluates to the first index.

==== %queue_indexes% ====
List of indexes of the specified item in the playback queue. Same as %queue_index% unless the item has been queued more than once.

==== %queue_total% ====
Total amount of tracks in playback queue. Available only for queued tracks, for technical reasons.

=== Playlist text color ===

==== Dimmed and highlighted text ====

In the Default UI playlist, text color can be adjusted by enclosing it in angle-brackets. The only options are to make the text dimmer (mixing the default color with the background color) or brighter (mixing the default color with the highlight color):

* ''<text>'' – dim ''text''
* ''<<text>>'' – dimmer ''text''
* ''<<<text>>>'' – dimmest ''text''
* ''>text<'' – bright ''text''
* ''>>text<<'' – brighter ''text''
* ''>>>text<<<'' – brightest ''text''

==== Historical and Columns UI color functions ====

Prior to version 1.0, the default UI playlist supported the following color functions, which are still available in the Columns UI playlist:

===== $blend(color1,color2,part,total) =====
Returns a color that is a blend between ''color1'' and ''color2''. If ''part'' is smaller than or equal to zero, ''color1'' is returned. If ''part'' is greater than or equal to ''total'', ''color2'' is returned. Otherwise a blended color is returned that is ''part'' parts ''color1'' and ''total''-''part'' parts ''color2''. The blending is performed in the RGB color space.

===== $hsl() =====
Resets the text color to the default color.

===== $hsl(h,s,l) =====
Sets the color for text in the HSL color space. ''h'', ''s'' and ''l'' are the hue, saturation, and lightness of the color for unselected text. The color for selected text is set to the inverse color.
The ranges of ''h'', ''s'', and ''l'' are from 0 to 240; the function is designed to interpret those values in the same way as the standard Windows color dialog.

===== $hsl(h1,s1,l1,h2,s2,l2) =====
Sets the color for text in the HSL color space. ''h1'', ''s1'' and ''l1'' are the hue, saturation, and lightness of the color for unselected text. ''h2'', ''s2'' and ''l2'' are the hue, saturation, and lightness of the color for selected text.

===== $rgb() =====
Resets the text color to the default color.

===== $rgb(r,g,b) =====
Sets the color for text. ''r'', ''g'' and ''b'' are the red, green and blue component of the color for unselected text. The color for selected text is set to the inverse color.

===== $rgb(r1,g1,b1,r2,g2,b2) =====
Sets the color for text. ''r1'', ''g1'' and ''b1'' are the red, green and blue component of the color for unselected text. ''r2'', ''g2'' and ''b2'' are the red, green and blue component of the color for selected text.

===== $transition(string,color1,color2) =====
Inserts color codes into ''string'', so that the first character has ''color1'', the last character has ''color2'', and intermediate characters have blended colors. The blending is performed in the RGB color space. Note that color codes are additional characters that will also be counted by string manipulation functions. For example, if you need to truncate a string, you should do this before applying ''$transition''.

=== Album List ===

* [[Foobar2000:Titleformat_Album_List|Album List Title Formatting]]
* [[Foobar2000:Preferences:Album List|Preferences: Album List]]

=== Playback Statistics ===

The foo_playcount component adds a number of fields for playback statistics and ratings. The fields can be used anywhere track info can be displayed. See the documentation for details:
* [http://www.foobar2000.org/components/view/foo_playcount Playback statistics homepage]
* [[Foobar2000:Titleformat Playback Statistics|Playback statistics titleformat reference]]

=== Playlist Organizer ===

This component adds a number of fields to control the display of a list of playlists. See the documentation for details:
* [[Foobar2000:Components/Playlist Organizer (foo_plorg)#Nodes|Playlist Organizer: Nodes Title Formatting]]

=== Columns UI ===

This component replaces the Default UI framework, including the playlist. See the documentation for details:
* [http://yuo.be/columns.php Columns UI homepage]
* [http://yuo.be/wiki/columns_ui:config:global_variables Global variables reference]
* [http://yuo.be/wiki/columns_ui:config:colour_string Playlist colors reference]
* [http://yuo.be/wiki/columns_ui:config:playlist_switcher_titleformatting Playlist switcher reference]

== Additional Reading ==

* [[Foobar2000:Title Formatting Introduction|Introduction to titleformat scripts]]
* The file '''titleformat_help.html''' in your Foobar2000 directory, e.g. file:///C:/Program%20Files%20(x86)/foobar2000/titleformat_help.html

[[Category:foobar2000 Guides|Titleformat Reference]]