The heart of Now Playing's exporting feature is the template file, and this section attempts to give all the needed information for creating one. This section is somewhere between a reference and a tutorial, hopefully more down-to-earth and understandable than most "technical specifications" documents, but still covering everything.

The template files packaged with Now Playing can and should be used as a reference that demonstrates the various aspects of template files. Since they are essentially just text files, they can be viewed and edited in Notepad. I have also included instructions for syntax highlighting in UltraEdit. In case that last sentence needs clarification, syntax highlighting is a text editor function that lets you see different types of keywords in different colors for legibility, and UltraEdit is an excellent text editor that has syntax highlighting. 

Once you get everything going and set up your own Now Playing page, please send me an e-mail with a link and, if you want, a copy of the template files. I would like to build a library of template sets for users to download, and links to the best pages, like a "hall of fame" sort of thing.

Go to:
   What does Now Playing do with template files?
   What is a legal template file?
   Regular tags
   Conditionals
   Loops
   Control tags
   Syntax highlighting in UltraEdit

What does Now Playing do with template files?

Whenever Now Playing is called upon to export information (this can be timer-based, on track change or on demand, depending on the values entered in the configuration dialog; realtime exporting, archiving and HTML playlist all use the same template syntax), it performs the following actions:

1. A template files is chosen, based on the type of exporting and, for realtime exporting, QCD's play state: playing (or paused) or stopped.
2. The chosen file is scanned for special QCD tags, each of which is replaced with the actual value it represents.
3. Some tags are control tags for the plugin, like conditionals and loops.
4. The target file is written (the template file is not changed).
5. The file may be uploaded to a website (realtime exporting only).

In this section we will not concern ourselves with item 5, and since items 1 and 4 are pretty straightforward, we are left with items 2 and 3.

There are four types of QCD tags: regular tags, conditionals, loops and control tags. These will be discussed in detail.

What is a legal template file?

Simply put, any file is a legal template file as far as Now Playing is concerned. Anything that is not identified as a QCD tag is passed along as part of the data. Keep in mind, however, the following points:

• For all but the most adventurous, there should never be a need for the template file to be a binary file.
• If all QCD tags were to be removed from the file and replaced with static values, a legal source file in some language (or plain text, if that was the intention) should result.
• Adhering to the principles given here (there really aren't that many) is recommended, it could save you some big debugging headaches when adding to your template in the future.

Regular tags

Regular tags are called that for a reason: they are, well, regular. Nothing can go wrong with regular tags: every place a regular tag appears in the template file, the corresponding [correct at exporting time] value will appear in the exported (output) file. If there is no value (or the value is an empty string), the tag is simply ignored.

The full list of regular tags:

Conditionals

Conditionals enclose a certain part of the template file, so that only if the conditions are met, this part of the file will be used, and otherwise it will be disregarded. When Now Playing encounters a conditional that is not met, from that point on everything in the template file is ignored until the closing tag is encountered. When Now Playing encounters a conditional that is met, it is ignored and the file is read normally. When Now Playing encounters the closing tag with no unmet conditionals pending, it is ignored as well.

When multiple conditionals are encountered, they must all be met for the data to be used. However, multiple conditionals should be used with extreme caution, as a single closing tag will invalidate all pending conditionals.

Regular conditionals:

All regular tags may be used in the form of a conditional. All you need to do is take the regular tag and add "ONLYIF_" or "ONLYIFNOT_" in the middle. Everything that comes after a regular conditional - including all tags that are not themselves conditionals - will only be used in the exporting process if the condition is met. Examples: anything after a <QCD_ONLYIF_ALBUM> tag will only be used if the album field is not empty; anything after a <QCD_ONLYIFNOT_PLTRACKS> will be used only if there are no tracks in the playlist.

Special conditionals:

Special conditionals are unique in that they refer to a property that can't be defined on its own with a regular tag; their effect, however, is similar to that of other conditionals. All special conditionals are of the form <QCD_ONLYIF_*> and <QCD_ONLYIFNOT_*>, the "*" being replaced by any of the following values, for when the corresponding situations exist or not:

Closing tag:

The closing tag for all conditionals is <QCD_ONLYIF>. Whenever the closing tag is encountered, all conditionals are invalidated and the template is read as normal, until another conditional (not the closing conditional) is encountered.

Loops

Loops define a certain action to be performed on everything that is within the loop. Loops are opened with a "loop start" tag and closed with a "loop end" tag. There are currently two loop types, playlist loops and escape loops.

General loop rules:

1. All regular tags and conditionals can be used inside a loop.
2. Control tags cannot be used inside a loop.
3. One loop type can be used inside another loop type (i.e. an escape loop inside a playlist loop) in a nested fashion.
4. Behavior is undefined when a loop is used inside another loop of the same type.

Playlist loop:

The playlist opening tag <QCD_PLAYLIST_START> and the playlist closing tag <QCD_PLAYLIST_END> form a loop similar to the "for" loop in most programming languages. Now Playing takes whatever is between these two tags, and duplicates it as many times as there are playlist tracks, each time using a different track as "current". For example, take the following code: "<QCD_PLAYLIST_START><QCD_TRACK> <QCD_PLAYLIST_END>"; the output of this would be the names of all the tracks in the playlist, in playlist order, with a single space between the names. Note: sample rate, bitrate and number of channels cannot be gathered for tracks that are not currently playing, and therefore should not be used in a playlist loop; if/when this information becomes available in QCD, Now Playing will be updated to retrieve this information.

Escape loop [v2.0 and up]:

The escape loop is formed between the opening tag <QCD_ESCAPE_START> and the closing tag <QCD_ESCAPE_END>. Some characters are considered special characters in scripting languages; to display these characters correctly, it is required to precede these characters with a \ (backslash) in a process called escaping; these characters are: \ (backslash), " (double-quote), ' (single-quote). Within an escape loop, any of these characters, if appearing in the output file, will be escaped. Note: control tags can be used inside an escape loop, as an exception to the rule that control tags cannot be used inside loops.

Control tags

Control tags are used for special operations that relate to settings in Now Playing, unlike other tags, which relate to the information from QCD. They work just like regular tags, but they cannot be used as conditionals or in loops (unless otherwise noted in the loop definition).

Timers:

There are three timers, <QCD_REFRESH> (frequency [in seconds] of timed exporting), <QCD_PLSECS> (seconds remaining in playlist) and <QCD_TRSECS> (seconds remaining in track). These tags are meant to be placed in the REFRESH field of a HTML META tag, telling the HTML file when to refresh itself.

The two <QCD_*SECS> tags are useful only if tracks are generally listened to in full, so the HTML file doesn't refresh every few seconds in anticipation of a track change. When these tags are encountered, the relevant remaining time is added to the setting in "miscellaneous" to create a number of seconds, and this value is inserted to the output file; anyone with the web page open will get automatic refreshes only when a new track begins.

If tracks are manually changed often (skipping to another track without letting the current track play through), the <QCD_*SECS> tags should not be used; a relatively short timer is preferable in these cases - best to use <QCD_REFRESH>, which ensures refreshes at the same rate that the file is being generated.

Note: when a CD is first inserted, QCD reports "New Disc" as album name until the real name can be obtained via a library plugin; therefore, if Now Playing identifies "New Disc" as album name and a <QCD_*SECS> tag is encountered, the value of <QCD_REFRESH> is used instead of the relevant remaining time; this is to ensure that the incorrect album name is not displayed on the HTML page for the entire track or album duration. 

Visualization dimension tags [v2.0 and up]:

There are three visualization dimension tags, <QCD_VISWIDTH> (width of active visualization window), <QCD_VISHEIGHT> (height of active visualization window) and <QCD_VISMAXSQR> (the smaller of the first two values, or the largest square that will fit in the visualization window). These tags are to support resizing cover art images to fit the visualization window, when a plugin to support displaying HTML in the visualization window becomes available (there is a plugin of this type in development by one of QCD's plugin developers). A template file, "cover_art_tmpl.txt", is supplied to display cover art in a visualization window (with the aforementioned plugin), and it should be used as playing template and stop template, to be visible whether the player is playing or stopped.

Random image [v1.1 and up]:

The <QCD_RNDIMAGE> tag is meant for HTML backgrounds, but can be used for any purpose. When encountered, this tag is replaced with a randomly selected image filename with a GIF or JPG extension (without the path) from the folder entered in the configuration dialog.

Using random images for HTML backgrounds: If the images are in the same folder as the exported file, the HTML "body" tag (in the template file) should look like this: <body background="<QCD_RNDIMAGE>">. If the images are in a different folder, full or relative paths (URL style) can be used to precede the tag.

Note: If your exported page is uploaded to a website, you must mirror your random image folder on the website, since the web server can't see your local folder.

Archive file [v2.0 and up]:

The <QCD_ARCHIVEFILE> tag returns the filename (without the path) of the current file being archived. This tag exists so the archiving TOC can include web links to the archiving pages for each album. This tag is valid only in the TOC template.

Syntax highlighting in UltraEdit

Syntax highlighting is an important programmer's aid. What it means is that when you're editing code, commands will be in one color, numbers in another, etc. This makes it a lot easier to see if you made a typing mistake, or to decipher blocks of code. Each programming language has different keywords of course, so any text editor that offers syntax highlighting must provide the ability to modify and add to the data file.

To make a long story short, below are instructions on how to get syntax highlighting for QCD/Now Playing template files with UltraEdit, an excellent text editor. The instructions assume your target file will be HTML, but it can be added to any other language as well. I am also assuming there's enough room in UE for another language syntax, but if there isn't then you probably know what you're doing anyway.

1. Open wordfile.txt in the UltraEdit folder.
2. Copy the entire HTML section (so we don't change the original), and paste to the end of the file.
3. Change the name "HTML" in the first line of the pasted section to "QCD/NP"
4. Change the language number (after the /L) to one that is available.
5. Add the following lines at the end of the section:

   /C3"Loop Tags"
   <QCD_PLAYLIST_START> <QCD_PLAYLIST_END> <QCD_ESCAPE_START> <QCD_ESCAPE_END>
   /C4"Reg/Ctrl Tags"
   <QCD_TRACK> <QCD_ARTIST> <QCD_ALBUM> <QCD_TRACKNO> <QCD_TIME> <QCD_FORMAT> <QCD_REFRESH> <QCD_NEXTTRACK> <QCD_NEXTARTIST> <QCD_NEXTALBUM> <QCD_NEXTTRACKNO> <QCD_NEXTFORMAT> <QCD_NEXTTIME> <QCD_PLTRACKS> <QCD_PLTIME> <QCD_COVER> <QCD_TRELAPSED> <QCD_TRREMAIN> <QCD_PLELAPSED> <QCD_PLREMAIN> <QCD_DISPLAYTIME> <QCD_PLSECS> <QCD_TRSECS> <QCD_RNDIMAGE> <QCD_FILENAME> <QCD_FULLPATH> <QCD_SAMPLERATE> <QCD_SAMPLERATEK> <QCD_BITRATE> <QCD_CHANNELS> <QCD_SKINNAME> <QCD_VISWIDTH> <QCD_VISHEIGHT> <QCD_VISMAXSQR>
   ** <QCD_QLIB:
   /C5"Conditionals"
   <QCD_ONLYIF>
   ** <QCD_ONLYIF_ <QCD_ONLYIFNOT_

6. Make sure C3 (color) is not used already for HTML files. It isn't now, but UltraEdit may use it in the future.
7. In UltraEdit, go to Advanced -> Configuration -> Syntax Highlighting -> Language: QCD/NP and set which colors you want to use for each tag type.

That's it! You should now be a template wiz. Well OK, maybe not. I'd be happy to assist, just e-mail me.