User:Canar:Titleformat syntax guide

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.

Getting Started

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.

Now you have two choices. I recommend that you 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.

My example would now look like this.

Metadata

Name	Value
<ARTIST>	Aphex Twin
<TITLE>	Donkey Rhubarb
<ALBUM>	Donkey Rhubarb
<DATE>	1995
<GENRE>	Electronic
<TRACKNUMBER>	01
<TOTALTRACKS>	04
<PLAY COUNTER>	5

Alternately, you can look at that list and convert between the simplified and true field names in your head. This is a little trickier, but it's doable!

Either way, from here on, I will only refer to the true field names. Forget all that simplified stuff.

Fields

Basic Fields

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. TfS is not case-sensitive.

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

Empty Fields

As for playlist entries without TRACKNUMBER fields, that script will return Artist - ? - Title. Now let's make things a little more complex. In these situations, it'd be nice if we can just drop the field 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%[ - %tracknumber%] - %title. This will return entries formatted like Aphex Twin - 01 - Donkey Rhubarb if TRACKNUMBER 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 confusing very quickly. Be sure you test as you go to make sure things behave as you expect them to.

Field Remappings

Field names will always work to refer to their contents if there is any content. However, there are some cases where a field doesn't have to contain data to return something. There are three such categories: field remappings, technical information, and special fields.

Field remappings are defined using TfS, but they involve functions, which I haven't explained yet. Remappings are pretty easy to explain though, and if you ponder it a little, it may give you some insight into the workings of functions. %album artist% will return the ALBUM ARTIST field if it exists. If it doesn't, foobar2000 will look in the ARTIST field, then the COMPOSER field, and finally the PERFORMER field. The first one in which it finds data will get returned. If nothing is found, it will return a question mark unless wrapped in square brackets.

%title% is a unique remapping in that it never returns a question mark. If there is no TITLE field, it will return the filename instead.

Field remappings are a major new feature in Titleformat scripts. Their introduction caused some backwards-incompatibility with v0.8 scripts. If you've got some old v0.8 script you want to port over, be aware of them. They got me.

Default UI Tricks

Before Columns UI tabulated things nicely, the default UI developed tricks to simulate

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