User:Canar:Titleformat syntax guide

This article deals with the simple syntax; please see foobar2000:Tagscript for info on the script-like syntax.

So you want to learn how to use foobar2000's titleformatting syntax, eh? Well, then. Because I'm lazy, instead of writing "titleformatting scripts", I'm going to just use the abbreviation TfS.

Setting Up

I would recommend that while you're learning, you disable the Columns UI if you're using it. Use the Default User Interface, as it will immerse you fully in TfS. Columns UI is very complex, and learning to use TfS to configure it is difficult for advanced users, let alone new ones.

Next, familiarize yourself with the Properties dialog. You can access it by right-clicking on a playlist entry and then clicking "Properties". You can use the "Keyboard Shortcuts" page of the preferences to assign a key to the properties dialog, which will allow you to bring the dialog up with the press of a button.

In the Metadata tab, there should be a nice table with the headings "Name" and "Value", with several entries under the Value column. If there aren't any, you have a poorly tagged file. If you don't have well-tagged files, TfS is going to do nothing for you. TfS only works properly on well-tagged files. Therefore, if you're going to customize this element of foobar2000, you need all of your files to be consistently tagged. In other words, if you're not obsessive about perfect tagging, it's going to be hard to get your foobar to be as gorgeous as all of the screenshots you've seen, even if you use the Columns UI. I'm going on about this for a reason:

Proper tagging is the corner stone of making TfS look pretty.

For the purposes of this tutorial, I'm going to use the metadata from a random track I was listening to while writing it.

Metadata

Name	Value
Artist Name	Aphex Twin
Track Title	Donkey Rhubarb
Album Title	Donkey Rhubarb
Date	1995
Genre	Electronic
Track Number	01
Total Tracks	04
<PLAY COUNTER>	5

Incidentally, this is also an exceptional track, from a time period when Richard D. James was going from making very difficult, pretentious music to light, accessible music that was as complex as his pretentious efforts. But you probably don't care about that. The real reason I listed all that info is because it is an example of the metadata in a well-tagged file. What "well-tagged" means can often depend on your own preferences. For example, if you don't like the "Total tracks" entry, you don't need to add it to your files, nor do you need to include it in your TfS. You get to pick which tags you want to have on your files. Beware though, some components interact with particular fields and do not allow you to change which ones they use.

Most of the entries in the "Name" column are pretty self-explanatory. "<PLAY COUNTER>" is formatted the way it is because it is a true field name. Here we are encountering one of the new complexities of v0.9. foobar2000 v0.9 hides the true field names from you by default. Instead, it displays what the field is supposed to contain. It will place the true field names in angle brackets ("<" and ">"). At this point, please go to Preferences -> Advanced -> Display -> Properties dialog -> Properties dialog fields. Save the text somewhere else, then delete the text from foobar. For your reference, in case you mess something up, the default is

 Artist Name=ARTIST;Track Title=TITLE;Album Title=ALBUM;Date=DATE;Genre=GENRE;Composer=COMPOSER;Performer=PERFORMER;Album Artist=ALBUM ARTIST;Track Number=TRACKNUMBER;Total Tracks=TOTALTRACKS;Disc Number=DISCNUMBER;Total Discs=TOTALDISCS;Comment=COMMENT;

Now, when you open the properties dialog, you will see the true field names rather than the simplified field names. This will save you some confusion in upcoming steps.

Beginner Level

Go to the Title Formatting page in the Display section and select the Playlist tab. This will allow you to change what shows up in the playlist of the Default User Interface.

Enter the string: %artist% - %title% This is a simple script that will return Aphex Twin - Donkey Rhubarb as the text representing that playlist entry. In fact, any one of the field names, when surrounded by % characters, will return the text associated with that field.

As you'd expect then, %artist% - %discid% - %title% would return Aphex Twin - 1e05c304 - Donkey Rhubarb.

That's a kind of useless example though, because most people don't add DISCID fields to their files. So, for playlist entries without DISCID fields, that script will return Artist - ? - Title or something similar. This is kind of ugly, so let's make things a little more complex.

Novice Level

So DISCID isn't a common tag. Therefore, it'd be nice if we can just drop it altogether without leaving an ugly question mark in its place. So, if you'd like to have text displayed only if a field is present, there are ways to do that.

Enter the string:

%artist%[ - %discid%] - %title. This will return entries formatted like Aphex Twin - 1e05c304 - Donkey Rhubarb if DISCID is present and Aphex Twin - Donkey Rhubarb if it's not.

The little square brackets look inside themselves for a %field%. If that field contains text, their contents will be printed. If that field is empty, everything between the brackets will be omitted. They can be nested for complex scripts, but watch out! Things can get complex very quickly. Be sure you test as you go to make sure things behave as you expect them to.

(insert information about tech fields and non-standard fields here)

Intermediate Level

(information about functions to be inserted here)

Default UI Tricks

(information about $tab() and things here)

Proficient Level

(introduce use of variables)

Advanced Level

(complex scripting tricks like advanced use of $meta, alternate scripting interface)

Complex Example Script

Here is the script I use for spamming now-playing information to #noise on freenode:

$puts(BTRT,$div($mul(%_filesize%,8),%_length_seconds%))
$puts(BTRT,$if2(%__bitrate%kbps,$ifgreater($len($get(BTRT)),4,$div($get(BTRT),1024)kbps,$get(BTRT)bps)))
$puts(RG,$left(%__replaygain_track_gain%,$add($strchr(%__replaygain_track_gain%,.),2))db)
$puts(SEP,$select($add($mod($rand(),5),1),||,'//',\\,>>,**))

$puts(DEF,

//title/artist stuff
//-=-=-=-=-=-=-=-=-=-
$if(%title%,
$get(SEP) ''%title%'' [by %artist% [feat. %featuring% ]])

$if(%rating%,'('Rating: $select(%rating%,Useless,Mediocre,Decent,Good,Excellent,Transcendent)')' )



//album/date/tracknumber stuff
//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
//check to see that tracknumber's greater than
$if($and(%album%%date%%tracknumber%,$and($greater(%tracknumber%,0),$greater(100,%tracknumber%))),

//core album/date/tracknumber info
$get(SEP) [$if(%album%,%date%:,date:%date%)]
[%album%]
$if($and(%album artist%,$not($stricmp(%album artist%,%artist%))),'('%album artist%')')
[$if(%album%%date%,/)[%disc%.]$num(%tracknumber%,2)] )

//if artist and/or title aren't present, print path info instead
$if($not($and(%artist%,%title%)),$if($stricmp($left(%_path_raw%,7),'http://'),%_path_raw%,$get(SEP) $directory(%_path%)\%_filename_ext% ))

//genre/codec info (assert: will always have codec info?)
//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
$get(SEP) 
[<$meta_sep(genre,/)> ]
$codec()
$if(%__mod_channels%,'('%__mod_channels% chan'nels)')
$if($or($and(%_length%,%_filesize%),%__bitrate%),@$get(BTRT)
$if($and($stricmp($codec(),MP3),$not(%__extrainfo%)),'(cbr)'))
$if(%__replaygain_track_gain%,@$get(RG)) 


//status bar (enabled via display > show dynamic info)
//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
$if($and(%_time_elapsed_seconds%,%_time_total_seconds%),$get(SEP) $progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'['%_time_elapsed%']','='))


)

$select(1,
//1 - default
//2 - Mix .NFO release
//3 - np list
//4 - html version
//5 - caps default

/me $lower($get(DEF))

,

$num(%tracknumber%,2). $if(%album artist%,%artist% - )%title%[ feat. %featuring%] {%_length%}

,

''%title%'' by %artist% '('%album%')'

,

<li>%artist% - %title% {%_length%}</li>

,

/me $get(DEF)

)

For the metadata given, it returns the following:

/me // 'donkey rhubarb' by aphex twin // 1995:donkey rhubarb/01 // <electronic> musepack@150kbps@-6.31db