From 20d28e80a5c861a9d5f449ea911ab75b4f37ad0d Mon Sep 17 00:00:00 2001 From: Jef Date: Tue, 24 Sep 2024 14:54:57 +0200 Subject: Initial community commit --- Src/Winamp/resource/atf.htm | 1097 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1097 insertions(+) create mode 100644 Src/Winamp/resource/atf.htm (limited to 'Src/Winamp/resource/atf.htm') diff --git a/Src/Winamp/resource/atf.htm b/Src/Winamp/resource/atf.htm new file mode 100644 index 00000000..2bfa5720 --- /dev/null +++ b/Src/Winamp/resource/atf.htm @@ -0,0 +1,1097 @@ + + + + +Winamp - Advanced Title Formatting (ATF) Documentation + + + + + + + + + + +
+ +
+ +
+
Advanced Title Formatting
+
+
+ +
+
+ +
+
+ +
+ +
+
+
Table of Contents
+
+ + +
+
+ +

Winamp ATF Reference

+
+

Below is an extract of the Winamp supported ATF functionality.
+ATF determines how Winamp should display metadata in the Playlist window and Main window songticker. +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.

+
+ +

ATF Usage

+
+

%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 ($,%,[,]).

+ +

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

+ +

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.

+ +

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.

+ +

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.

+ +

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.

+ +

Functions

+
+

Notes: Be careful about spaces after commas. $if(%title%, Has A Title, +Has No Title) will display
“ Has A Title” (note leading +space)
not “Has A Title”.
The proper form should be +$if(%title%,Has A Title,Has No Title).

+ +

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.

+ +

Logic Operations

+
+ +

$and

+
+

– Removed –
Parameters: (%a%, %b%) – The fields +to check if populated.
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.

+ +

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.

+ +

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: TODO: (a1, +a2)
Returns: TODO: +a1
Example: TODO: $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.
+Examples: $abbr(%album%) converts Album name of eg. “Final Fantasy VI” to “FFVI”.
+$abbr(Advanced Title Formatting,10) writes “ATF”.
+$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: +$null()
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.

+ +

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.

+ +

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.

+ +

Others. (TODO)

+
+
$select

$tab

$crlf

$char
+ +

Examples

+
+

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

+ +

Standard ATF syntax

+

Syntax: [%artist% - ][%album% - ][$num(%track%,2) - ]$if2(%title%,$filepart(%filename%))
+Example: Pink Floyd - Animals - 02 - Dogs

+

+ +
+

+ +

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 kbps ]  *****

+

+ +
+

+ +
+ +
+ +

+
+
+
+
+ +
+
+
+
+ +
+
+
+
+ +
+
+ +

+ + \ No newline at end of file -- cgit