PLEASE MAKE A DONATION! CONTRIBUTE TO THE FURTHER DEVELOPMENT OF THIS SITE AND ITS AUTHOR!

WINAMP HELP

Winamp for Windows Documentation

Winamp is the best, freeware media player that allows you to play most audio formats (including Internet Radio Stations) and video. Winamp works with portable media players, allows you to rip and burn CDs, has a built-in media library, graphic equalizer and visualizations. With the advanced plug-in mechanism, you have the possibility to increase its functionality. Thanks to skins Winamp can look and behave as you like...


Advanced Title Formatting


1. ATF Usage

The global ATF string can be manually edited via the Titles page in the Winamp Preferences. The default ATF string in Winamp is: [%artist%-]$if2(%title%,$filepart(%filename%)

This will be displayed as: Artist - Title if the Artist and Title metadata fields are populated in the file tags, otherwise it will just display the filename instead.


  • %blah% - denotes a metadata field.
  • $blah() - denotes a function call.
  • [] - means "don't display unless metadata was found".
  • ‘ ’ - (single quotation marks) outputs raw text without parsing.

    eg. ‘blah$blah%blah[]’ which will output all the string and ignore the special characters ($,%,[,])


2. Fields

Note: Fields are defined by various components within Winamp. Some are specific to the Media Library (%rating%, %playcount%), some are provided by Winamp (%filename%, %folder%). In most cases, however, the input plugin provides the fields. Some input plugins provide a greater variety of fields than others. For example, the Windows Media plugin (in_wm, Winamp 5.12+), will provide values for ANY field in the form %WM/*% (see the extended attributes section of View File Info on any wma/wmv/asf file for examples).


2.1 Provided by Winamp


%filename%

Returns the full path of the file. To display the filename only, use the $filepart function..


%folder%

Returns the containing folder. [Winamp 5.2+ Only]


2.2 Provided by ML


%rating%

Returns the track rating as an integer from 1 to 5, if set. To display as stars or another character, use the $repeat function. [Winamp 5.2+ Only]


%playcount%

Returns the playcount (number of times track has been played), if the file is stored in the Media Library database. [Winamp 5.2+ Only]


2.3 Provided by ML or input plugin

For the fields listed below, info is taken from ML only if the file is present in the ML database and if the following option is checkmarked:

Prefs (Ctrl+P) > Media Library > Local Media > ‘Use Library title information for Playlist Item Formatting’

In all other cases, the info is provided by the input plugin (if the respective input plugin supports the field).

Most of these are straightforward and are taken from the standard file tags, and therefore don't require any additional explanatory notes.


%artist%

Returns the Artist field.


%title%

Returns the Title field.


%album%

Returns the Album field.


%year%

Returns the Year field.


%genre%

Returns the Genre field.


%comment%

Returns the Comment field.


%tracknumber%

Returns the TrackNumber with no padding, eg. Track 1 will be displayed as 1.
To pad with zeros, eg. 01, 02...10, 11, use the $num or $lpad function.


%track%

Same as %tracknumber%


%albumartist%

Returns the Album Artist field. [Winamp 5.3+ Only]


%disc%

Returns the Disc No. tag, if available, eg. 1/2 (Disc #1 of a 2CD set).


%composer%

Returns the Composer field.


%publisher%

Returns the Publisher (Record Label) field. [Winamp 5.3+ Only]


%streamtitle%

Returns the Streaming Title for streams, if one exists.


%bitrate%

Returns the Bitrate (will use average bitrate for vbr).


%length%

Returns length of the track in miliseconds. For a formatted track length, use: $div(%length%,60000):$num($div($mod(%length%,60000),1000),2)


%type%

Returns 1 for video, 0 for audio. [Winamp 5.2+ Only]


%vbr%

Returns 1 for VBR(Variable Bitrate) audio, 0 for CBR(Constant Bitrate) audio.


%category%

Returns the Category field. [Winamp 5.55+ Only]


%producer%

Returns the (record or film) Producer field. [Winamp 5.57+ Only.]


%director%

Returns the (film) Director field, mainly used for videos. [Winamp 5.57+ Only.]


2.4 Provided by input plugin

The fields listed below may not work for all file formats.


%trackartist%

Returns the Track Artist field (equivalent to Artist), if different to Album Artist. [Winamp 5.3+ Only]


%mood%

Returns the Mood field. [Winamp 5.3+ Only]


%bpm%

Returns the BPM (Beats Per Minute), if data/field exists. [Winamp 5.3+ Only]


%key%

Returns the Key field (eg. E Minor), if it exists. [Winamp 5.3+ Only]


%lyricist%

Returns the Lyricist field. [Winamp 5.3+ Only]


%conductor%

Returns the Conductor field. [Winamp 5.3+ Only]


%tool%

Returns the Encoded/Tool (software used to rip/encode track) field, eg. Winamp 5.34. [Winamp 5.3+ Only]


%family%

Returns the filetype's Family, eg. M4A returns: MPEG-4 Audio File Format [Winamp 5.5+ Only]


%encoder%

Returns the Encoder, eg. LAME 3.97 [Winamp 5.3+ Only]


%ISRC%

International Standard Recording Code, or ISO 3901 (Info) [Winamp 5.3+ Only]


%replaygain_track_gain%

Returns the ReplayGain Track Gain value (eg. -3.16 dB), if it exists. [Winamp 5.3+ Only]


%replaygain_album_gain%

Returns the ReplayGain Album Gain value, if it exists. [Winamp 5.3+ Only]


%replaygain_track_peak%

Returns the ReplayGain Track Peak value, if it exists. [Winamp 5.3+ Only]


%replaygain_album_peak%

Returns the ReplayGain Album Peak value, if it exists. [Winamp 5.3+ Only]


%gain%

Returns the Gain value, if it exists. [Winamp 5.3+ Only]


3. Functions

Notes: Be careful about spaces after commas.

$if(%title%, Has A Title, Has No Title) will display “ Has A Title” (note leading space), notHas A Title”.

The proper form should be $if(%title%,Has A Title,Has No Title).



3.1 Control Flow


[...]

Conditional section


$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 a1... aN contains a valid, non-empty field, the value is evaluated and returned, otherwise the else parameter is used.

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

$decode

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

    cN or else. A switch/case function, which determines which bN parameter is equal to a and returns the corresponding cN 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)

Winamp 5.2+ Only


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

Winamp 5.2+ Only


$iflonger

  • Parameters: (a1, x1, then, else)
  • Returns:

    Compares whether the length of 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)

Winamp 5.2+ Only


$IfStrEqual2

  • Parameters: (A, B, then, else)
  • Returns:

    If A = B do then else do else

  • Example: $IfStrEqual2(%year%,2007,New!:,Old:)
  • Example: $IfStrEqual2(%type%,1,'(Video)','(Audio)')

Winamp 5.2+ Only


$IfStrEqual

  • Parameters: (A, B, then)
  • Returns:

    If A = B do then else nothing

  • Example: $IfStrEqual(%year%,2007,New!:) will print “New!” if the media was published in 2007.

Winamp 5.2+ Only


3.2 Logic Operations


$and

– Removed –

  • Parameters: (%a%, %b%)
  • Returns:

    1 if the fields %a% and %b% are populated. An empty string if not.(?????)

  • Example: $if($and(%artist%,%title%),Has both artist and title,One field is missing)

Winamp 5.2+ Only


3.3 Arithmetic Operations


$mod

  • Parameters: (x1, x2)
  • Returns:

    remainder of a division of x1 by x2

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

Winamp 5.2+ Only


$div

  • Parameters: (x1, x2)
  • Returns:

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

  • Example: $div(60,10)

Winamp 5.2+ Only


$mul

  • Parameters: (x1,x2,...,xn) - List of numbers to multiply.
  • Returns:

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

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

Winamp 5.2+ Only


$muldiv

  • Parameters: (x1, x2, x3)
  • Returns:

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

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

Winamp 5.2+ Only


$sub

  • Parameters: (x1,x2,...,xn) - List of numbers to subtract
  • Returns:

    x1 - x2 - ... - xn. The result of x2...xn subtracted from x1.

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

Winamp 5.2+ Only


$add

  • Parameters: (x1,x2,...,xn) - List of numbers to add
  • Returns:

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

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

Winamp 5.2+ Only


$greater

  • Parameters: (x1, x2) - Two numbers to compare
  • Returns:

    1 if x1 is greater than x2, otherwise nothing. Similar in use to $ifgreater()

  • Example: $greater(3,2) – note does not appear to work within a $if() function.

Winamp 5.2+ Only


$max

  • Parameters: (x1,...,xn) - List of numbers to compare
  • Returns:

    The largest number in the arguments supplied

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

Winamp 5.2+ Only


$min

  • Parameters: (x1,...,xn) - List of numbers to compare
  • Returns:

    The smallest number in the arguments supplied

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

Winamp 5.2+ Only


3.4 String Operations


$lower

  • Parameters: (a1)
  • Returns:

    lower case of a1

  • Example: $lower(%title%)

$upper

  • Parameters: (a1)
  • Returns:

    upper case of a1

  • Example: $upper(%title%)

$replace

  • Parameters: (a1, a2, a3)
  • Returns:

    a1 with all occurences of a2 replaced by a3

  • Example: $replace(dum,u,o) writes “dom”.

Winamp 5.2+ Only


$left

  • Parameters: (a1, x1)
  • Returns:

    the first x1 characters of a1

  • Example: $left(%title%)

Winamp 5.2+ Only


$right

  • Parameters: (a1, x1)
  • Returns:

    the last x1 characters of a1

  • Example: $right(%title%)

Winamp 5.2+ Only


$len

  • Parameters: (a1)
  • Returns:

    the number of characters of a1

  • Example: $len(%artist%)

Winamp 5.2+ Only


$substr

  • Parameters: (a1, a2)
  • Returns:

    TODO: a1

  • Example: $substr()

Winamp 5.2+ Only


$strstr

  • Parameters: (a1, a2)
  • Returns:

    index of first occurence of string a2 in a1

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

Winamp 5.2+ Only


$strrchr

  • Parameters: (a1, a2)
  • Returns:

    index of last occurence of character a2 in a1

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

Winamp 5.2+ Only


$strlchr

  • Parameters: (a1, a2)
  • Returns:

    index of first occurence of character a2 in a1

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

Winamp 5.2+ Only


$strchr

  • Parameters: (a1, a2)
  • Returns:

    index of first occurence of character a2 in a1

  • Example: $strchr(aacbbabb,a) returns “1” (same as $strlchr() ??).

Winamp 5.2+ Only


$shortest

  • Parameters: (a1, a2)
  • Returns:

    a1 or a2 based on which has the shorter length.

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

$longest

  • Parameters: (a1, a2)
  • Returns:

    a1 or a2 based on which has the greater length.

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

$abbr

  • Parameters: (a1, x1)
  • Returns:

    a1 abbreviated.

  • Example: $abbr(%album%) converts Album name of eg. “Final Fantasy VI” to “FFVI”.
  • Example: $abbr(Advanced Title Formatting,10) writes “ATF”.
  • Example: $abbr(%album%,10) writes abbreviated Album name, only if longer than 10 char's. x1 is optional. If defined, a1 will only be abbreviated when its length exceeds x1 char's.

$padcut

  • Parameters: (a1, x2)
  • Returns:

    a1 padded with spaces or cut off, resulting in a string of x2 characters

  • Example: $padcut(%artist%,15)

$cut

  • Parameters: (a1, x2)
  • Returns:

    a1, cut off after the x2th character

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

$pad

  • Parameters: (string, num, padstr)
  • Returns:

    string padded to at least num chars, with spaces by default, or specify a character (or repeating string) as padstr.

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

$lpad

  • Parameters: (string, num, padstr)
  • Returns:

    string padded to at least num chars on the left, with spaces by default, or specify a character (or repeating string) as padstr.

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

Winamp 5.2+ Only


$trim

  • Parameters: (a1)
  • Returns:

    a1 without any leading or trailing spaces

  • Example: $trim(%artist%)

Winamp 5.2+ Only


$repeat

  • Parameters: (a1, x1)
  • Returns:

    a1 repeated x1 times.

  • Example: $repeat(*,%rating%)
    ($fill() performed this function in Winamp 5.2 and was removed after 5.21.)

$caps

  • Parameters: (a1)
  • Returns:

    lower case of a1, with first letter of each word in upper case

  • Example: $caps(%artist%)

$caps2

  • Parameters: (a1)
  • Returns:

    a1, with first letter of each word in upper case

  • Example: $caps2(%artist%)

$fileext

  • Parameters: (a1)
  • Returns:

    file extension of a1

  • Example: $fileext(%filename%)

$filepart

  • Parameters: (a1)
  • Returns:

    filename of a1 (i.e. without the leading path)

  • Example: $filepart(%filename%)

$filename

  • Parameters: (a1)
  • Returns:

    filename of a1 (i.e. without the leading path)

  • Example: $filename(%filename%)

$directory

  • Parameters: (a1, x1)
  • Returns:

    directory name of a1, after going up by x1 levels

  • Example: $directory(%filename%,2)
    The above example will output “Music” if the full path of the file is “C:\Music\Artist - Album\Song.mp3”. x1 is optional, default is 1.

Winamp 5.2+ Only


$split

  • Parameters: (a, token, which)
  • Returns:

    Splitting of disc and/or track strings, eg. to show "1" instead of "1/11"

  • Example: [$num(%track%,2)$IfStrNotEqual($split(%track%,/,1),,/$num($split(%track%,/,1),2))]

Winamp 5.5+ Only


$ext

  • Parameters: (a1)
  • Returns:

    file extension of a1

  • Example: $ext(%filename%)

Winamp 5.2+ Only


$hex

  • Parameters: (x1, x2)
  • Returns:

    x1 formatted as hexidecimal to x2 number of digits, padded to the left with zeros.

  • Example: $hex(%tracknumber%,4)

Winamp 5.2+ Only


$dec

  • Parameters: (x1, x2)
  • Returns:

    x1 zero padded to the left to form a x2 digit number.

  • Example: $dec(%tracknumber%,5)

Winamp 5.2+ Only


$num

  • Parameters: (x1, x2)
  • Returns:

    x1 zero padded to the left to form a x2 digit number.

  • Example: $num(%tracknumber%,5)

Winamp 5.2+ Only


$null

  • Parameters: Any number of parameters
  • Returns:

    Nothing

  • Example: Does absolutely nothing. It is useful mainly in places where a parameter is required, but you want an empty string.

Winamp 5.2+ Only


$PathLPart

  • Parameters: (a1, x1)
  • Returns:

    The first x1 levels of a1

  • Example: $PathLPart(%filename%,2)
    The above example will output “C:\Music” if the full path of the file is “C:\Music\Sonic Youth - Daydream Nation\01 - Teen Age Riot.mp3”.

Winamp 5.3+ Only


$PathRPart

  • Parameters: (a1, x1)
  • Returns:

    The last x1 levels of a1

  • Example: $PathRPart(%filename%,2)
    The above example will output “Sonic Youth - Daydream Nation\01 - Teen Age Riot.mp3” if the full path of the file is “C:\Music\Sonic Youth - Daydream Nation\01 - Teen Age Riot.mp3”.

Winamp 5.3+ Only


$PathLTrim

  • Parameters: (a1, x1)
  • Returns:

    a1 minus the first x1 levels of a1

  • Example: $PathLTrim(%filename%,1)
    The above example will output “Music\Sonic Youth - Daydream Nation\01 - Teen Age Riot.mp3” if the full path of the file is “C:\Music\Sonic Youth - Daydream Nation\01 - Teen Age Riot.mp3”.

Winamp 5.3+ Only


$PathRTrim

  • Parameters: (a1, x1)
  • Returns:

    a1 minus the last x1 levels of a1

  • Example: $PathRTrim(%filename%,1)
    The above example will output “C:\Music\Sonic Youth - Daydream Nation” if the full path of the file is “C:\Music\Sonic Youth - Daydream Nation\01 - Teen Age Riot.mp3”.

Winamp 5.3+ Only



3.5 Variables


$puts

  • Parameters: (name, value)
  • Returns:

    Stores value to the named variable name. It may be later retrieved using $get(name). Use $put() to store a value and also return the value with the one function.

  • Example: $puts(artist_title,%artist%-%title%)

Winamp 5.2+ Only


$put

  • Parameters: (name, value)
  • Returns:

    value. Stores value to the named variable name. It may be later retrieved using $get(name). Use $puts() to store a value without returning it.

  • Example: $put(artist_title,%artist%-%title%)

Winamp 5.2+ Only


$get

  • Parameters: (name)
  • Returns:

    value of name variable previously set by a $put() or $puts() function

  • Example: $get(artist_title)

Winamp 5.2+ Only



3.6 System Info


$systime_second

  • Parameters: TODO: (a1, a2)
  • Returns:

    TODO: a1

  • Example: TODO: $systime_second()

Winamp 5.2+ Only


$systime_minute

  • Parameters: TODO: (a1, a2)
  • Returns:

    TODO: a1

  • Example: TODO: $systime_minute()

Winamp 5.2+ Only


$systime_hour

  • Parameters: TODO: (a1, a2)
  • Returns:

    TODO: a1

  • Example: TODO: $systime_hour()

Winamp 5.2+ Only


$systime_day

  • Parameters: TODO: (a1, a2)
  • Returns:

    TODO: a1

  • Example: TODO: $systime_day()

Winamp 5.2+ Only


$systime_month

  • Parameters: TODO: (a1, a2)
  • Returns:

    TODO: a1

  • Example: TODO: $systime_month()

Winamp 5.2+ Only


$systime_year

  • Parameters: TODO: (a1, a2)
  • Returns:

    TODO: a1

  • Example: TODO: $systime_year()

Winamp 5.2+ Only


3.7 Others


$select


$tab


$crlf


$char


4. Examples

[ .... ] - displays contents of brackets only if at least one of the fields referenced inside has been found.

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


4.1 Standard ATF syntax

Syntax: [%artist% - ][%album% - ][$num(%track%,2) - ]$if2(%title%,$filepart(%filename%))

Example: Pink Floyd - Animals - 02 - Dogs


4.2 Advanced ATF syntax

Syntax:

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

$IfStrNotEqual(%artist%,$if2(%albumartist%,%artist%),[%artist%-])

[$if2(%title%,$filepart(%filename%))][$if($fileext(%filename%),'   [  ',)]

[%year%  |  ][$fileext(%filename%) ][$if(%bitrate%, '|'  ,)][%bitrate% 'kbps' ]

[$if($fileext(%filename%),']',)][   $repeat(*,%rating%) ]


Returns: AlbumArtist -Album-##-Artist -Title  [ Year | Ext | Bitrate ]  StarRating
if AlbumArtist is different to TrackArtist, otherwise shows Standard format.


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