Hydrogenaudio Knowledgebase - User contributions [en]

Pre-emphasis

2018-06-19T16:34:40Z

92.62.53.27: Changed ""audiophile quality filter" in cddemph description to "80-bit floating point for processing" for more specific info. Info about 80-bit floating point taken from https://rutracker.org/forum/viewtopic.php?t=4854775

'''Pre-emphasis''' is the first part of a noise reduction technique in which a signal's weaker, higher frequencies are boosted before they are transmitted or recorded onto a storage medium. Upon playback, a '''de-emphasis''' filter is applied to reverse the process. The result is a higher signal-to-noise ratio (SNR); the original frequencies are restored, but noise that was introduced by the storage medium, transmission equipment, or analog/digital conversions is quieter than it would have been if no filtering had been done. Pre- and de-emphasis can be collectively referred to as just '''emphasis'''.

Emphasis was sometimes used in digital storage media in the late 1970s through early 1980s, including on a small percentage of [[Compact Disc Digital Audio|audio CD]]s. Emphasis is akin to Dolby noise reduction for tapes, or the RIAA equalization curve for vinyl records.

==Pre-emphasis on audio CD==
Some early digital recording & playback equipment, including CD players, used 14-bit converters, even though they were dealing with 16-bit audio. Some also used noisy "brick wall" filters to remove frequencies higher than the Nyquist frequency (22050 Hz). The resulting noise introduced by these converters and filters could be made relatively quiet by using pre-emphasis: boosting the signal (especially the higher frequencies) in the recording before it was put onto CD, and embedding flags in the disc's subcode to tell a CD player to apply de-emphasis on playback. Some CD players even had a de-emphasis button that could be used to manually apply de-emphasis, but now it's just a built-in feature of the analog outputs of nearly all dedicated audio CD players. By the late 1980s, pre-emphasis stopped being used because reliable 16-bit DACs with oversampling and other technologies minimized the conversion & filtering noise without the need for pre-processing the recording.

Most major-label CDs with pre-emphasis were manufactured in Japan in the early and mid-1980s. Relatively recent forum posts indicate that pre-emphasis is still used on newly manufactured CDs by some indie labels, mainly for classical titles.

A pre-emphasis flag for each track is normally stored in the subcode along with the audio data. It's also supposed to be stored in the table of contents (TOC), but many CDs have TOCs that say there's no pre-emphasis when in fact the subcode says there is. There are also some CDs which people believe were mastered with pre-emphasis, but which have no pre-emphasis flags set at all.

==Pre-emphasis on audio CD in computers==
CD drives in computers aren't exactly like regular CD players.

Some drives, especially older internal drives on desktop/tower PCs, have analog audio outputs which connect directly to a soundcard via a special cable. In this situation, the drive's own DAC is converting the CD's audio data into analog signals, and the OS or soundcard provide a "CD" volume control specifically for this signal. When audio is being fed to the soundcard this way, or listened to through a headphone connector on the drive itself, then the drive is ''probably'' doing its own de-emphasis.

Most OSes and drives nowadays, by default, instead use a digital interface to send the raw audio data straight from the disc, through the drive's regular connectors (IDE/ATAPI, SCSI, USB, whatever) and into the operating system, which passes it along to whatever program needs it. This is the only method used in DAE (digital audio extraction). During playback, the soundcard's DAC is converting the CD's audio data into analog signals, and the volume control for it is usually just the Wave volume control, as is used for most other sounds originating inside the computer. The soundcard usually has no ability to do de-emphasis, and even if it could, it has no access to info about the presence of pre-emphasis, because it's just being fed the waveform data, not the disc's subcode.

In other words, even though a CD drive may be capable of detecting pre-emphasis flags in the disc's subcode and/or TOC, this information is usually completely ignored when sending audio data through the digital interface. So when you play a CD through your computer, or use CD ripping software to get the audio content, you're probably getting the pre-emphasized audio data. Since it has not been de-emphasized, it will probably sound too "bright" and/or hissy (although your audio equipment or your damaged ears may keep you from noticing). Therefore you may want to do de-emphasis processing yourself.

===De-emphasis processing===
De-emphasis was designed to be performed in the analog domain by physical electrical components. However, digital audio data can be mathematically manipulated to simulate the effect of analog signal processing, sometimes with a greater degree of accuracy than is possible with physical components, depending on the method used.

There are various methods for applying digital de-emphasis, each with pros & cons. They all basically amount to turning down the upper midrange & treble with a special EQ curve that bottoms out at about -10 dB @ 20+ kHz. This can be done during playback with a simple equalizer setting, or processing extracted audio data before or after it is written to files. The biggest problems with these methods (as with any digital signal processing) are precision, accuracy, and noise. Forum posts indicate EQs in media players tend to be very inaccurate and noisy; a filter designed specifically for de-emphasis is preferable.

Some CD ripping software will detect pre-emphasis flags in the subcode (if the drive supports it) and can apply a digital de-emphasis filter:
* '''iTunes''' (Mac OS & Windows) - recent versions detect pre-emphasis in subcode and apply de-emphasis automatically for both playback and ripping.
* '''Windows Media Player''' (Windows) - recent versions detect pre-emphasis in subcode and apply de-emphasis automatically, but just for playback, not ripping.
* '''cdda2wav''' (multi-platform) - a command-line app (part of the cdrtools package) which can be invoked with a <code>-T</code> parameter to apply de-emphasis as it rips; e.g. <code>cdda2wav -D 0,0,0 -B -T</code> (first use <code>cdda2wav -scanbus</code> to figure out the right device values for the <code>-D</code> option).

Some audio processing software can apply a de-emphasis filter to already-extracted audio (files on disk), producing new files:
* '''cddeemph''' (Windows) - processes multiple WAV files using 80-bit floating point for processing. http://rutracker.org/forum/viewtopic.php?t=4854775;

* '''WaveEmph''' (Windows) - processes one WAV file at a time, and can optionally apply a volume gain at the same time. Note: after unzipping, right-click on the .exe and set Win98 compatibility before running it for the first time.
* '''SoX''' (multi-platform) - a command-line app which can be invoked with a <code>deemph</code> parameter to apply a de-emphasis filter; e.g. <code>sox input.wav output.wav deemph</code>.

Some audio software can apply a de-emphasis filter during playback or conversion:
* '''foobar2000''' (Windows) - this media player can be configured to use any of the plug-ins below.
** [http://www.hydrogenaudio.org/forums/index.php?showtopic=99394 foo_dsp_deemph and foo_deemph] are two versions of the same filter. They will apply the SoX de-emphasis algorithm only during playback or conversion of specially tagged files. Use the DSP version if you want to process lossy files or you want to control where in the DSP chain the processing occurs. Otherwise, use the post-processing version, which will automatically apply during playback and ReplayGain-scanning of specially tagged, lossless, 44.1 KHz files. It will also apply during conversion of such files, if "Enable decode postprocessing" is checked in the converter setup.
** [http://www.foobar2000.org/components/view/foo_dsp_effect foo_dsp_effect] is a multi-effect DSP and postprocessor which can be configured to apply de-emphasis during playback and conversion of specially tagged files. It will also apply during conversion of such files if "Enable decode postprocessing" is checked in the converter setup. Only enable one option, though (the DSP or the postprocessing).
** [http://www.hydrogenaudio.org/forums/index.php?showtopic=85106 foo_dsp_convolver] is an unofficial "convolver" DSP which can transform audio based on "impulse" files. It's possible to configure it to do de-emphasis by using [http://www.hydrogenaudio.org/forums/index.php?showtopic=76191 a special impulse file] (or [http://www.hydrogenaudio.org/forums/index.php?showtopic=67376&view=findpost&p=620372 a simpler one]) and auto level adjust disabled. ([http://www.foobar2000.org/components/view/foo_convolve foo_convolve] is the official convolver component, but with these impulses isn't ideal because it outputs slightly more samples than were input.)

WaveEmph, SoX, and all of the foobar2000 plug-ins have been tested and produce nearly identical output. The differences are minuscule and inaudible.<ref>http://www.hydrogenaudio.org/forums/index.php?showtopic=99394&view=findpost&p=824194</ref><ref>http://www.hydrogenaudio.org/forums/index.php?showtopic=99394&view=findpost&p=824806</ref>

==Pre-emphasis in cue sheets==
Pre-emphasis can be specified in a [[cue sheet]] using <code>FLAGS PRE</code>. This will tell the CD burning software to set the pre-emphasis flags in the subcode and TOC of a CD to be burned.

==External links==
;The following threads & articles contain useful information:
* http://www.stevehoffman.tv/forums/showthread.php?t=88541
* http://web.archive.org/web/20090324083651/http://www.rogernichols.com/EQ/EQ-2003-07-08.htm
* http://www.digital-inn.de/exact-audio-copy-english/19034-pre-emphasis-use-eac.html
* http://www.dsprelated.com/showmessage/2587/1.php
* http://www.hydrogenaudio.org/forums/index.php?showtopic=38312&view=findpost&p=338577
* http://club.myce.com/f57/will-clarity-quality-copied-cds-remain-exactly-same-64708/#post400909

== Software to made de-emphasis ==
cddeemph tool
* http://rutracker.org/forum/viewtopic.php?t=4854775
* http://letitbit.net/download/14992.1be051993ba100ce9cb7ae8d4e9c/cddeemph.rar.html
* http://vip-file.com/downloadlib/129389504892840400-14992.1be051993ba100ce9cb7ae8d4e9c/cddeemph.rar.html

== References ==
<references/>

[[Category:Signal Processing]]

Foobar2000:Components 0.9/FFmpeg Decoder Wrapper (foo input ffmpeg)

2017-11-03T17:11:32Z

92.62.53.27: Added info about about "Additional arguments" field

{{fb2k}}
=Description=

The FFmpeg Decoder Wrapper allows you to play any FFmpeg-supported audio format through foobar2000. You need standalone FFmpeg binaries (ffmpeg.exe, ffprobe.exe) on your system in order to use it.

=Drawbacks=

No embedded cuesheet support.

Not sample accurate seeking and length reporting.

=Usage=
Before using, you must configure the component for use with specific decoders.

The decoder list comes pre-populated with most common format configurations; however all of them are unchecked by default.

The per-decoder configuration page consists of four fields:
===Format name===
The name you wish to refer to the format by - shown in open file dialog etc.
===File type mask===
A wildcard-pattern that defines what files should be fed to this decoder.

Example: *.TAK for TAK files.

Multiple patterns may be specified per one decoder, delimited by semicolon.

This is intentionally kept separate from "format name" to allow alternate extensions and prefix extensions.

You can also specify protocols, e.g. rtmp://* - or combine file types and protocols, e.g. http://*.m3u8

===Additional arguments===
Additional command-line arguments for ffmpeg. The extra arguments are injected before -i %s. To inject arguments after -i %s, include -i %s in arguments, -i %s will not be inserted again.[https://hydrogenaud.io/index.php/topic,114855.msg946957.html#msg946957]

===Write tag types===
Tag types to write to when the user attempts to edit tags on the file.

'''USE WITH CAUTION''' - this feature may damage your files if used incorrectly; enable only after checking file format specifications for the file format you're dealing with!

You do not need to enable this to read tags from your files, the component will attempt to read popular tag types (ID3v1/v2, APEv2) from your files regardless of this setting.

Use the bottom editbox of the preferences page to specify folder containing your FFmpeg binaries - ffmpeg.exe and ffprobe.exe are required. If your FFmpeg binaries are present in %PATH%, there's no need to do so.

=Link=
* [http://www.foobar2000.org/components/view/foo_input_ffmpeg Official Website]

Foobar2000:Title Formatting Reference

2017-07-07T22:20:26Z

92.62.53.27: /* $strstr(str1,str2) */

{{fb2k}}
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. ''// this is a comment''.

A '''field reference''' is a field name enclosed in percent signs, for example ''%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 ''()''—or contain one or more parameters separated by commas, for example ''$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 ''%'', ''$'', ''['', '']'', or ''''' (apostrophe/single quote) must be escaped by enclosing it in ''''' (apostrophe/single quote) characters. For example, '''[''' (a left bracket in single quotes) results in a literal ''['' (left bracket). As a special case, '''''' (two single quotes in a row) results in one single quote. In the playlist, ''<'' and ''>'' are also special; see [[#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 ''$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 2<sup>32</sup>-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:

False: $if(0,True,False)
False: $if('0',True,False)
True or False: [$add(%rating%,1)]

The last one would display the value of %rating% plus one, if and only if %rating% is set for the track.

=== $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 its value returned.

=== $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 directory name 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''.

=== $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) ===

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

=== $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 ''x'' 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_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.

=== $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(srt,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() ===

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) ===

Finds first occurrence of character ''char'' in string ''str''.

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

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

Finds last occurrence of character ''char'' in string ''str''.

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

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

Finds 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 ''srt2''.

=== $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, It"

==== $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 + It"

==== $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 It"

==== $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).

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

=== 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>)
|-
|channel_mode
| style="background-color:#EEF"|'''Channel Mode''', description of channels (''e.g.'' 3 front, 2 rear surround channels + LFE)
|-
|__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)
|-
| 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)
|}

<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_track_gain% ====
The ReplayGain track gain value.

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

=== 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]]