User:Canar:Titleformat syntax guide

Note 1: Tagz is not an official name.

Note 2: The information in this article is outdated. Please see Titleformat Introduction and Titleformat Reference for information on titleformatting in foobar2000 v0.9.

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 Tagz, eh? Well, then.

Setting Up

The first thing to do is to disable the Columns UI. Use the Default User Interface, as it will immerse you fully in Tagz. Columns UI is very complex, and learning to use Tagz to configure it is difficult for advanced users, let alone new ones.

Next, familiarize yourself with the Properties dialog, which pops up when you right click on a playlist entry.

In the Metadata group box, there should be many items of the form:

FIELD = text

If there aren't any, you have a poorly tagged file. If you don't have well-tagged files, Tagz is going to do nothing for you. Tagz scripts only work 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-compulsive 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 belaboring this point for a reason:

Proper tagging is the corner stone of making good-looking Tagz scripts.

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

ARTIST = Aphex Twin

ALBUM = Donkey Rhubarb

TRACKNUMBER = 01/04

DATE = 1995

GENRE = Electronic

DISCID = 1e05c304

TITLE = Donkey Rhubarb

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.

Here, already, we see that I'm a little obsessive about tagging. I've likely used the freeDB masstagger to grab the information about this EP, because the TRACKNUMBER information is in the format "xx/yy", where xx is the track number and yy is the total number of tracks on the disc. There's also the DISCID field, which generally also indicates use of the freeDB masstagger.

So, let's begin our Tagz adventure.

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