About
TuneCam-O-Mat is a webcam-like application for use in combination with iTunes.
It gathers information about the current track in iTunes, creates a (custom) HTML or TEXT file containing this information and uploads this file to an FTP server or saves it on your disk. Again and again in predefined intervals.

TuneCam-O-Mat is 100% freeware and comes with no warrantees. It has been well tested and has shown no major problems. Results may vary.


Requirements
Mac OS X 10.2.3 or snappier
Installed BSD Subsystem
iTunes 3.0.1 or better
TextEdit 1.2 or better

Recomended: Broadband Internet Connection


How to start immediately?
When you start TuneCam for the first time it will open a panel where you can set the following preferences:

1. Select an interval in seconds for checking iTunes for the current track. The minimum value is 10 seconds. We suggest a check frequency between 30-60 seconds to lower processor load.

2. Enter your desired name for the file which finally will contain the exported info. Please avoid special characters for the filename as they will cause problems. Do not forget to add a proper suffix: If you want to create a HTML file then set the filename to "xxxx.html", if you want to create a TEXT file then set the filename to "xxxx.txt".

3. Choose if there should be Unix or Mac line breaks in the exported file. If you are going to use TuneCam for creating a text file that will for example be parsed by PHP scripts you should probably use Unix line breaks.

4. FTP Settings:
Before setting up your FTP options you should make sure you have the required information from your server or ISP. With this information you can easily fill out the settings. If you are behind a firewall make sure to select "Passive FTP".

TuneCam does NOT use the Keychain to save your password. We tried our very best to create a routine using the Keychain for the password-saving, but: Keychain Scripting is currently broken. You can create a key using AppleScript, but you can't request it afterwards. I mean you can request it, but you won't get an answer...which is quite...a bummer :) Therefore we are storing the password internally in a compiled script which is save enough for me. If this method does not satisfy your personal safety demands: DO NOT USE TuneCam!

5. Disk Settings:
Choose a folder so TuneCam knows where to save the local file.

Note: TuneCam now allows to upload the file to the server AND/OR save it to your disk. Progress.

The built-in templates of TuneCam were created for debugging purposes only and there is no guarantee that they will be available forever. If the traffic on our server will become too much due to the use of the templates we will definately take them down. Therefore we strongly encourage you to create your own templates.


Understanding TuneCam
To build your own templates you will have to know a little bit about how TuneCam works. Therefor I am explaining it to you. Join me on a short journey through TuneCam:

If you start TuneCam it will process the following steps every x seconds, where x is the value you have chosen in the preferences:

1. Determine status
First of all TuneCam detects which of the following states matches the current situation:

A: iTunes is active AND playing songs:
A.1: You are listening to a track located on your hard drive
A.2: You are listening to a track located on an Audio CD
A.3: You are listening to a track which is streamed over the (Inter-)Net
B: iTunes is active BUT playback is stopped/paused
C: iTunes is not running
D: You do not want iTunes to be monitored by TuneCam
E: A general error occured in the monitoring process (hopefully a seldom state...)

Based on the result of this investigation TuneCam selects the appropriate template to use in the next steps:

A.1: File Track
A.2: Audio CD Track
A.3: URL Track
B: Playback Stopped/Paused
C: Inactive iTunes
D: No Monitoring
E: General Error

(You will find these templates in the Template Preferences. Choose the menu item Template Preferences from the TuneCam menu in the menu bar.)

2. Gathering information

Now that TuneCam has detected the status quo it tries to find out more about it. To simplify matters let's say the status quo is that you are listening to a track located on your hard drive (file track). So TuneCam asks iTunes for almost every detail about the current track including weird information like its database ID or file size.
But alas, there are times when some of the gathered informations are "empty". That can happen because in every iTunes library there are tracks with incomplete information in their ID3 tag. Sometimes the album name is missing, sometimes even the title of the track. In those cases TuneCam can replace the "empty" information with a defined placeholder. For example you could insert Untitled track as the placeholder for the title information. Everytime a track has got a missing title information TuneCam will then insert Untitled track instead.

(You will find the Placeholders in the Template Preferences.)

Moreover TuneCam gathers various informations like the current time & date.
All this information is then temporarily stored in variables.

3. HTML-O-Mat

As you know special characters must be converted to HTML entities in order to be displayed correctly in a browser. For example the artist name Alizée must be converted to Alizée. If you want TuneCam can check the gathered information for special characters and do the conversion for you automatically. Just choose which information you want to be checked in the Template Preferences (the settings are available in the HTML Flags box).

4. Filling the template

At this point the most important thing in the whole process happens: The combination between the appropriate template and the gathered information. I call it the wedding night. But how does it work in detail? Here comes the enlightment: Search & Replace. TuneCam searches for certain tags (called TuneCam Tags) in the template and replaces them with the gathered information. It's that simple. To illustrate this strategy here is an example:
As arranged above you are listening to a track which is located on your hard drive. Let's say it's In the Meantime from Sherrie Austin. So, following the example, TuneCam gathered Sherrie Austin as the artist information and In the Meantime as the title information. If TuneCam now finds the TuneCam Tag <tc>artist</tc> in the template it replaces it with Sherrie Austin, and if it finds the TuneCam Tag <tc>title</tc> it replaces it with In the Meantime.
You may read the above paragraph twice.

5. Saving temporary files

When TuneCam is finished with the above step of filling the template with information it writes the filled template one after another in two temporary files, one containing Mac line breaks, one containing Unix line breaks. If, for any reason, you want to have a look at those files, they are located here (you have to open the TuneCam application package in the Finder to find them):

Mac Line Breaks: /TuneCam.app/Contents/Resources/Mac/
Unix Line Breaks: /TuneCam.app/Contents/Resources/Unix/

6. Exporting the file

If step 5 was successful TuneCam tries to export one of the temporary files, namely uploading it to a FTP server or/and saving it to a chosen folder on your hard drive. If an error occurs in this process it gets logged in the Error Log.

(You will find the Error Log in the Tools menu in the menu bar.)


The Track Info Phrase
A specialty of TuneCam is its Track Info phrase. What is a Track Info phrase? It is a full sentence informing your visitors about what you are listening to including a) title, b) artist and c) album information. Here is an example of a complete Track Info phrase:

I am currently listening to "In the Meantime" by Sherrie Austin from the album "Followin' a Feelin'".

There are almost no limits for you in creating Track Info phrases, give your fancy full scope, but always take into consideration: You can only integrate a) title, b) artist and c) album information into your Track Info phrase, nothing more, nothing less. Open the Template Preferences and you will find the Phrases box where you can set the Track Info phrase to match your needs.
But why there are 7 different types of the Track Info in the preferences? Because, as told before, in every iTunes library there are tracks which have incomplete informations in their ID3 tag. But TuneCam once more can react dynamically to rescue the situation. Imagine you are listening to a track which has a missing album information. Under normal circumstances TuneCam then would build a Track Info phrase like:

I am currently listening to "In the Meantime" by Sherrie Austin from the album "".

Or, if you are using a placeholder like Unknown album for the album information:

I am currently listening to "In the Meantime" by Sherrie Austin from the album "Unknown album".

That is nonsense. Therefore you can define phrases for cases, where not all "members" of the TIIT (Track Info Information Triangle -> Title, Artist & Album information) are available. And after all there are 7 cases .
So to follow the example, TuneCam detects the missing album information and decides to use the phrase entered for this case (-> Track Info: Title, Artist):

I am currently listening to "In the Meantime" by Sherrie Austin.

The Track Info phrase is only available for the File Track and the Audio CD Track template.

IMPORTANT: For special resaons, which to explain would go beyond this ReadMe, it is NOT possible to activate HTML conversion for the Track Info phrase.


Building your own templates
In order to fully customize TuneCam you will have to build seven templates: Each for every state TuneCam can differ between. As you might understand we cannot show you how to build all the seven templates in detail. But we will build one template together so that you get the idea.
The template we are going to build will be HTML and it will be a File Track template, used in those cases where you are listening to a track located on your hard drive. Please make sure that you added the proper suffix (".html") to the filename in the General Preferences of TuneCam. To follow the instructions you will need:

Ingredients:
1. a text editor (we recommend BBEdit Lite)
2. TuneCam
3. TextEdit

First thing we do is creating a file containing a basic HTML structure which then will be upgraded step by step. Open the text editor of your choice, create a new TEXT document and paste the following text into it:

<html>
<head>
<title>My TuneCam</title>
</head>
<body>
</body>
</html>

Now we have a very basic HTML document with no content. The next step is to fill this "empty" document in a way that it finally will inform people about what you are listening to.

Open TuneCam and select the menu item Tag List in the Tools menu in the menu bar. A document called TuneCam Tags will be opened in TextEdit. This document is extremely helpful and that is exactly why we wrote it. It contains all the TuneCam Tags available and lists them seperately for each template. At this time have a closer look at the tags listed for the File Track template as we are going to use a lot of them in the next steps.

To enhance our basic document we are adding an overview about the title, artist and album using the tags you just discovered in the TuneCam Tags document:

<html>
<head>
<title>My TuneCam</title>
</head>
<body>
<br>
Title: <tc>title</tc>
<br>
Artist: <tc>artist</tc>
<br>
Album: <tc>album</tc>
<br>
</body>
</html>

Don't be frightened by the <br>-tags, they're the HTML equivalent for ¶, it inserts a single carriage return. The red marked tags are the TuneCam Tags which will be later replaced with the info gathered by TuneCam.
Now save this document as a text file in your text editor, then switch to TuneCam and open the Template Preferences. Here you will find the Templates box where you choose the menu item File Track from the popup button and then hit the Import button. You are being asked to locate the text file you want to use for your File Track template. Choose the one we just created together. After TuneCam successfully loaded the text file close the panel, start TuneCam and go listen to a track in iTunes for a while which is located on your hard drive. Why for a while? Because TuneCam will not immediately write infos to the file but after the time you have chosen as the checking interval in the General Preferences.
Depending on your settings made in the General Preferences undertake any necessary measures to view the file created by TuneCam in the browser of your choice. If everything went fine it will now look something like this in your browser (depending on what you are listening to:)


Title: What I Have to Do
Artist: Flaw
Album: Through The Eyes


That's great. But as you might admit it could be better. And that's why we continue enhancing the document. Switch to the text editor and open the text file we created so far. Now we are adding a timestamp, showing date and time of your iTunes session, and we are adding a phrase, informing your visitors a little bit more lettered about what you are currently listening to.

<html>
<head>
<title>My TuneCam</title>
</head>
<body>
<br>
<br>
<tc>iso_date</tc>
<br>
<br>
<br>
Title: <tc>title</tc>
<br>
Artist: <tc>artist</tc>
<br>
Album: <tc>album</tc>
<br>
<br>
<br>
<tc>info_phrase</tc>
</body>
</html>

Once again save this experimental document, import the text file as a File Track template in TuneCam and go listen to track located on your hard drive in iTunes. Then, when you view the file created by TuneCam it will look something like that (provided you did not mess up the phrases in the Template Preferences yet what we will do next...):

2002-12-29, 03:11:47 (GMT+0100)

Title: My Hero
Artist: Foo Fighters
Album: The Colour & the Shape

I am currently listening to My Hero by Foo Fighters from the album The Colour & the Shape.

Wow. A basic website informing people about what you are currently listening to. And you just fully understood how to build your own templates: Create a document and cleverly integrate the tags based on which template you are going to build.


Monitoring or No Monitoring...
What is this checkbox for which you can find in the main window of TuneCam?

What happens if you play around with it, if you uncheck it? Well, the little "M" stands for "Monitoring" and the checkbox itself is for toggling the so called "Monitoring Status" on and off. Imagine you are in a crazy mood and you want to listen to some kind of music nobody would expect you to listen to. With TuneCam you can keep your dirty little secret. Just uncheck the checkbox and TuneCam will stop monitoring iTunes for the current track and export the No Monitoring template. This way you can listen to your hidden tracks without loosing your face. Just, for example, tell the world that the iTunes library is currently under maintenance (using the No Monitoring template) while your happily listening to The Kiss.


FAQ
Q: I created a template on my own but TuneCam does not replace the tags! What's wrong???
A: First make sure that you used the appropriate tags for the template. Moreover some text and web editors (for example Adobe GoLive) are breaking tags apart:

WRONG: TuneCam cannot recognize the tag within the template!
<html>
<head>
<title>My TuneCam</title>
</head>
<body>
<tc>
artist</tc>
</body>
</html>

RIGHT: TuneCam can recognize the tag within the template!
<html>
<head>
<title>My TuneCam</title>
</head>
<body>
<tc>artist</tc>
</body>
</html>

Q: I created my own templates but I somehow messed them up and I now want to install the built-in ones. How to do that?
A: If you open the application package of TuneCam you will find a folder named LifeBoat containing a copy of the built-in templates.


Q: Sometimes the GUI of TuneCam doesn't react responsively. What's wrong?
A: If TuneCam is just in the process of creating a document it cannot react to your clicking on buttons. It is not multi-threaded. Just wait for the process to be finished. Then TuneCam will continue to react on your button-clicking.


December 2002
Martin Michel