Windows Media Player ATF Reference

This documentation is similar to the Winamp ATF Reference and the Foobar2000 Title Formatting Reference, as similar ATF systems are used there.

ATF determines how Windows Media Player should display metadata of media items, in various places in the user interface. Specific ATF strings can be manually edited in Windows Media Player Plus! settings.

ATF Usage

%blah% denotes a metadata field.

$blah() denotes a function call.

'' (single quotation marks) outputs raw text without parsing. For example, 'blah$blah%blah[]' will output the literal string and ignore the special characters ($, %, [ and ]).

[...] displays everything between the square brackets only if at least one of the fields referenced inside has been found. For example [%artist% - ] will show: "Artist - " only if the %artist% tag is populated, otherwise it will not show anything at all (including the hyphen and spaces).

Fields

In addition to the fields listed below, any Windows Media Player attribute can be used as a field, by surrounding the attribute name with percent signs (%). For the list of available Windows Media Player attributes, refer to the Attribute Reference at MSDN.

Example: %WM/Mood% returns the mood of the song.

%filename%

Returns the full path of the file. To display only the name and extension parts (without the leading path), use the $filepart function.

%folder%

Returns the containing folder.

%rating%

Returns the star rating as an integer from 1 to 5, if set. To display as stars or another character, use the $repeat function.

%playcount%

Returns the play count (the number of times the media item has been played), if the item is stored in the Media Library.

%artist%

Returns the (Contributing) Artist field.

%title%

Returns the Title field.

%album%

Returns the Album field.

%year%

Returns the Release Year field.

%genre%

Returns the Genre field.

%comment%

Returns the Comment field.

%tracknumber%

Returns the Track number with no padding, e.g. Track 1 will be displayed as 1.

To pad with zeros (01, 02...10, 11) use the $num or $lpad function.

%track%

Identical to %tracknumber%.

%albumartist%

Returns the Album Artist field.

%disc%

Returns the Set field, if available, e.g. 1/2 (disc #1 of a 2 CD set).

%composer%

Returns the Composer field.

%publisher%

Returns the Publisher field.

%bitrate%

Returns the bit rate, in kilobits per second. For variable bit rate (VBR) files, the average bit rate is returned.

%length%

Returns the length in milliseconds. For a formatted length, use %lengthf%.

%lengthf%

Returns the length, formatted as minutes:seconds.

%type%

Returns 1 for video, 0 for audio, or an empty string for other media types (such as pictures).

Use %MediaType% to query for other media types.

%vbr%

Returns 1 for variable bit rate (VBR) files, or 0 for constant bit rate (CBR) files.

%category%

Returns the Subgenre (category) field.

%trackartist%

Returns the (Contributing) Artist field, but only if it differs from the Album Artist field. Returns an empty string if both fields contain the same value. Requires Windows Media Player Plus! 2.0 or higher.

%mood%

Returns the Mood field.

%bpm%

Returns the Beats per minute field.

%key%

Returns the Key field.

%lyricist%

Returns the Lyricist field.

%conductor%

Returns the Conductor field.

%ISRC%

Returns the International Standard Recording Code or ISO 3901.

Functions

Note: be careful with spaces after commas: $if(%title%, Has A Title, Has No Title) will display " Has A Title" (note the leading space) instead of "Has A Title". The proper form is $if(%title%,Has A Title,Has No Title).

Control Flow

[...]

Conditional section (not really a function), see #ATF Usage.

$if

Parameters: (a, then, else)

Returns: If a contains at least one valid, non-empty field, then is evaluated and returned, otherwise the else parameter is. Note that $if(A,A,B) is equivalent to $if2(A,B).

Example: $if(%artist%,Has an artist tag,Has no artist tag)

$if2

Parameters: (a, else)

Returns: If a contains a valid, non-empty field, a is evaluated and returned, otherwise the else parameter is.

Example: $if2(%album%,no-album)

$if3

Parameters: (a1, ..., aN, else)

Returns: If one of the a1...aN parameters contains a valid, non-empty field, that parameter is evaluated and returned, otherwise the else parameter is.

Example: $if3(%artist%,%filename%,%album%,no field)

$decode

Parameters: (a, b1, c1, ..., bN, cN, else)

Returns: Parameter ci or else. A switch/case function, which determines which bi parameter is equal to a and returns the corresponding ci parameter. If none are matched, it returns the final parameter else.

Example: $decode($fileext(%filename%),MP3,MPEG-1 Layer 3,MP4,MPEG-4 Container,Other)

$ifgreater

Parameters: (x1, x2, then, else)

Returns: Compares the integer numbers x1 and x2, if x1 is greater than x2, then is evaluated and its value returned. Otherwise, the else part is evaluated and its value returned.

Example: $ifgreater(%rating%,2,Highly rated song,Not highly rated song)

$iflonger

Parameters: (a1, x1, then, else)

Returns: Checks if string a1 is longer than x1 characters. If a1 is longer, the then part is evaluated and its value returned. Otherwise, the else part is evaluated and its value returned.

Example: $iflonger(%title%,15,A long title,A short title)

$IfStrEqual

Parameters: (A, B, then)

Returns: If string A equals string B (case insensitive), the then part is evaluated and its value returned. Nothing is returned if the strings are different.

Example: $IfStrEqual(%year%,2006,New!) will return "New!" if the media was released in 2006.

$IfStrEqual2

Parameters: (A, B, then, else)

Returns: If string A equals string B (case insensitive), the then part is evaluated and its value returned. Otherwise, the else part is evaluated and its value returned.

Example: $IfStrEqual2(%type%,1,'(Video)','(Audio)')

$IfStrNotEqual

Parameters: (A, B, then)

Returns: If string A is different from string B (case insensitive), the then part is evaluated and its value returned. Nothing is returned if the strings are equal.

Example: $IfStrNotEqual(%type%,1,Not a video)

Arithmetic Operations

$mod

Parameters: (x1, x2)

Returns: Remainder of a division of x1 by x2.

Example: $mod(21,8) returns 5.

$div

Parameters: (x1, x2)

Returns: x1 / x2. Result of a division of x1 by x2.

Example: $div(60,10)

$mul

Parameters: (x1, x2, ..., xn): list of numbers to multiply

Returns: x1 * x2 * ... * xn. The supplied numbers multiplied.

Example: $mul(7,8,3,4)

$muldiv

Parameters: (x1, x2, x3)

Returns: x1 * x2 / x3. x1 multiplied by x2, divided by x3. Result is rounded to nearest integer.

Example: $muldiv(10,6,3) returns 20.

$sub

Parameters: (x1, x2, ..., xn): list of numbers to subtract

Returns: x1 - x2 - ... - xn. The result of the sum of x2...xn, subtracted from x1.

Example: $sub(25,1,3,2,3)

$add

Parameters: (x1, x2, ..., xn): list of numbers to add

Returns: x1 + x2 + ... + xn. The addition of all the supplied numbers.

Example: $add(2,3,%playcount%,%rating%)

$max

Parameters: (x1, ..., xn): list of numbers to compare

Returns: The largest of the supplied numbers.

Example: $max(7,8,3,4)

$min

Parameters: (x1, ..., xn): list of numbers to compare

Returns: The smallest of the supplied numbers.

Example: $min(7,8,3,4)

$greater

Parameters: (x1, x2): two numbers to compare

Returns: 1 if x1 is greater than x2, otherwise nothing. Similar in use to the $ifgreater function. Note: does not work within a $if function.

Example: $greater(3,2)

String Operations

$lower

Parameters: (a1)

Returns: Lower case of string a1.

Example: $lower(%title%)

$upper

Parameters: (a1)

Returns: Upper case of string a1.

Example: $upper(%title%)

$replace

Parameters: (a1, a2, a3)

Returns: String a1 with all occurrences of string a2 replaced by string a3.

Example: $replace(dum,u,o) returns "dom".

$left

Parameters: (a1, x1)

Returns: The first x1 characters of string a1.

Example: $left(%title%)

$right

Parameters: (a1, x1)

Returns: The last x1 characters of string a1.

Example: $right(%title%)

$len

Parameters: (a1)

Returns: The number of characters in string a1.

Example: $len(%artist%)

$substr

Parameters: (a1, x1, x2)

Returns: The substring of string a1, starting from the x1-th character and ending at the x2-th character. The first character in a string has index 1.

Example: $substr(aacbbabb,2,6) returns "acbba".

$strstr

Parameters: (a1, a2)

Returns: The index of the first occurrence of string a2 in string a1. The first character in a string has index 1.

Example: $strstr(aacbbabb,ab) returns 6.

$strlchr

Parameters: (a1, a2)

Returns: The index of the first occurrence of character a2 in string a1. The first character in a string has index 1.

Example: $strlchr(aacbbabb,a) returns 1.

$strrchr

Parameters: (a1, a2)

Returns: The index of the last occurrence of character a2 in string a1. The first character in a string has index 1.

Example: $strrchr(aacbbabb,a) returns 6.

$strchr

Identical to $strlchr.

$shortest

Parameters: (a1, a2)

Returns: String a1 or string a2, based on which has the shorter length.

Example: $shortest(%album%,%folder%)

$longest

Parameters: (a1, a2)

Returns: String a1 or string a2, based on which has the greater length.

Example: $longest(%album%,%folder%)

$abbr

Parameters: (a1, x1)

Returns: Abbreviated version of string a1. Parameter x1 is optional. If defined, string a1 will only be abbreviated when its length exceeds x1 characters.

Examples:

$abbr(%album%) converts Album title of e.g. "Final Fantasy VI" to "FFVI".
$abbr(Advanced Title Formatting,10) returns "ATF".
$abbr(%album%,10) returns abbreviated Album title, only if longer than 10 characters.

$padcut

Parameters: (a1, x1)

Returns: String a1 padded with spaces or cut off, resulting in a string of exactly x1 characters.

Example: $padcut(%artist%,15)

$cut

Parameters: (a1, x1)

Returns: String a1, cut off after the x1-th character.

Example: $cut(%comment%,15) returns the first 15 characters of the Comment field.

$pad

Parameters: (a1, x1, a2)

Returns: String a1, padded to at least x1 characters, with spaces by default, or specify a character (or repeating string) as a2.

Example: $pad(%artist%,40), or $pad(%artist%,40,.) to pad with periods.

$lpad

Parameters: (a1, x1, a2)

Returns: String a1, padded to at least x1 characters on the left, with spaces by default, or specify a character (or repeating string) as a2.

Example: $lpad(%tracknumber%,3), or $lpad(%tracknumber%,3,0) to pad zeros in front.

$trim

Parameters: (a1)

Returns: String a1, without any leading or trailing spaces.

Example: $trim(%artist%)

$repeat

Parameters: (a1, x1)

Returns: String a1, repeated x1 times.

Example: $repeat(*,%rating%)

$caps

Parameters: (a1)

Returns: Lower case of string a1, with the first character of each word in upper case.

Example: $caps(%artist%)

$caps2

Parameters: (a1)

Returns: String a1, with the first character of each word in upper case. The case of all other characters is preserved.

Example: $caps2(%artist%)

$fileext

Parameters: (a1)

Returns: The file extension of filename a1.

Example: $fileext(%filename%)

$ext

Identical to $fileext.

$filepart

Parameters: (a1)

Returns: The name and extension parts of filename a1 (i.e. a1 without the leading path).

Example: $filepart(%filename%)

$filename

Identical to $filepart.

$directory

Parameters: (a1, x1)

Returns: The directory name of filename a1, after going up by x1 levels. Parameter x1 is optional, the default is 1.

Example: $directory(C:\Music\Artist - Album\Song.mp3,2) will return "Music".

$split

Parameters: (a1, a2, x1)

Returns: Splits string a1 into tokens, by using character a2 as a separator, and returns the x1-th token. This can be useful for splitting disc and/or track strings, e.g. to show "1" instead of "1/11".

Example: $num(%track%,2)$IfStrNotEqual($split(%disc%,/,1),,/$num($split(%disc%,/,1),2)) will show the track number, and include the first part of the Set field (the disc number), if not empty.

$hex

Parameters: (x1, x2)

Returns: x1, formatted as hexadecimal to x2 number of digits, padded to the left with zeros.

Example: $hex(%tracknumber%,4)

$num

Parameters: (x1, x2)

Returns: x1, zero padded to the left to form a number of x2 digits.

Example: $num(%tracknumber%,5)

$dec

Identical to $num.

$null

Parameters: Any number of parameters.

Returns: Nothing at all. This function can be useful when a parameter is required, but you want an empty string.

Example: $null()

System Info

$systime_second

Parameters: None.

Returns: The seconds component of the current time.

Example: $systime_second()

$systime_minute

Parameters: None.

Returns: The minutes component of the current time.

Example: $systime_minute()

$systime_hour

Parameters: None.

Returns: The hours component of the current time.

Example: $systime_hour()

$systime_day

Parameters: None.

Returns: The days component of the current date.

Example: $systime_day()

$systime_month

Parameters: None.

Returns: The months component of the current date.

Example: $systime_month()

$systime_year

Parameters: None.

Returns: The years component of the current date.

Example: $systime_year()

Examples

Standard ATF syntax

Syntax:

[%artist% - ][%album% - ][$num(%track%,2) - ]%title%

Example: Pink Floyd - Animals - 02 - Dogs

Advanced ATF syntax

Syntax: (split over multiple lines to improve readability)

[$if2(%albumartist%,%artist%) - ][%album% - ][$num(%track%,2) - ]
$IfStrNotEqual(%artist%,$if2(%albumartist%,%artist%),[%artist% - ])
[%title%]
[$if($fileext(%filename%),'   [  ',)]
[%year%  |  ][$fileext(%filename%) ][$if(%bitrate%, '|'  ,)][%bitrate% 'kbps' ]
[$if($fileext(%filename%),']',)]
[   $repeat(*,%rating%) ]

Returns: <Album Artist> - <Album> - ## - <Artist> - <Title> [ <Release Year> | <Extension> | <Bit rate> ] <Star rating> (if Album Artist equals Artist, the Artist field is not shown).

Example: Various - Arcana - 01 - Tripswitch - Calabi Yau [ 2006 | mp3 | 205 kbps ] *****

Advanced Title Formatting

Windows Media Player ATF Reference

ATF Usage

Fields

%filename%

%folder%

%rating%

%playcount%

%artist%

%title%

%album%

%year%

%genre%

%comment%

%tracknumber%

%track%

%albumartist%

%disc%

%composer%

%publisher%

%bitrate%

%length%

%lengthf%

%type%

%vbr%

%category%

%trackartist%

%mood%

%bpm%

%key%

%lyricist%

%conductor%

%ISRC%

Functions

Control Flow

[...]

$if

$if2

$if3

$decode

$ifgreater

$iflonger

$IfStrEqual

$IfStrEqual2

$IfStrNotEqual

Arithmetic Operations

$mod

$div

$mul

$muldiv

$sub

$add

$max

$min

$greater

String Operations

$lower

$upper

$replace

$left

$right

$len

$substr

$strstr

$strlchr

$strrchr

$strchr

$shortest

$longest

$abbr

$padcut

$cut

$pad

$lpad

$trim

$repeat

$caps

$caps2

$fileext

$ext