zTunes

Version 1.1 - 14th May 2006

zTunes is a PHP-based remote web-interface for iTunes on Mac OS X. To use it you will need a Mac running OS 10.3 or later, iTunes 4.9 or later, and (optionally) Airfoil 2.0.1 or later for remote speaker control. You will also need to make some configuration changes to your Apache server (by editing httpd.conf, for which full instructions are given below).

zTunes is designed to allow you to control iTunes across your home or office network; it is not secure enough to be used on a public-facing server.

Features

zTunes has the basic features you would expect: track listings, playlists, shuttle controls and a now playing area. But it also has some rather cool additional features, including one that's missing from iTunes itself!

1. A Jukebox mode that lets multiple users add songs to a single playlist, which are then played in turn. If the Jukebox runs out of custom tracks it can randomly select them from the Library to keep the music playing indefinitely, and you can even define rules by which tracks are excluded from selection!
2. Live progress information is displayed in the now playing area (if the client web-browser supports XMLHttpRequest), which includes time elapsed/remaining, and an animated song pointer
3. The output code is proper semantic XHTML with CSS-driven design. The styles are designed not just for desktop browsers, but for "handheld" devices and "print" output as well; to optimize the layout there are also device-specific style sheets for the Sony PSP, PocketIE, and Opera Mobile. The XHTML itself, including all language data, is fully abstracted into templates.

Latest update

Version 1.1 updates the layout and output styling for better compatibility with small-screen devices:

• Improved "handheld" media styling for screen widths down to 240px
• New device-specific stylesheets for PocketIE, and for Opera Mobile including a mini version of the live song pointer!
• A change in the output source-order, to put the tracks table before the playlists, which improves usability when the output is serialized

There are also a few minor edits, and a complete changelog is included in the download zipfile.

Get the script

Download the zipfile [50K] and unzip it; you'll be left with a folder called ztunes. Copy this entire folder into Apache's root documents folder, which unless you've changed it, will be "/Library/WebServer/Documents/".

Once it's there you can get to it from any browser on your network, using the address "http://server/ztunes/" (where server is the name or IP address of the Mac; If you don't know its name or IP address you can find out from the Network pane in System Preferences. If the browser is on the same machine you can address it with "http://localhost/ztunes/").

But it won't work yet! First we have to configure the server.

Apache configuration changes

To make this run you will need to make some changes to your Apache configuration file, httpd.conf. If you're already familiar with editing this file, please skip straight to Step 1; if not, here's a quick precis on what to do:

How to edit httpd.conf

Open the Terminal application (which is in Applications/Utilities) and then logon as root by typing this:

su root

Then enter your root password (if you've never set a root password, go to Applications/Utilities and open Netinfo Manager, then in the Security menu select Set root password, and follow the instructions; remember what you put, because there's no way to retrieve it!)

Once you're logged-on as root you'll be able to save changes to httpd.conf. Open it using the pico text editor by typing this command:

pico /etc/httpd/httpd.conf

The pico editor is nice necause it has a menu strip at the bottom to remind you of the keystrokes. You can page down/up using Ctrl+V and Ctrl+Y, search for a string with Ctrl+W, and exit the editor with Ctrl+X. When you exit having made any changes, you'll be asked if you want to save them; press Y for "yes", then Enter to confirm the file name (there's no need to change the name, indeed, you musn't!)

Step 1. Enable PHP (if it isn't already)

Look for the following line in httpd.conf, in the section headed Dynamic Shared Object (DSO) Support:

#LoadModule php4_module libexec/httpd/libphp4.so

And uncomment it, by deleting the # at the beginning of the line. If it doesn't have a # at the beginning then PHP is already enabled - please skip to Step 2.

Then in the group of items immediately after that, look for this line:

#AddModule mod_php4.c

And do the same thing - uncomment it by deleting the # from the beginning.

Step 2. Set the User to you

Now look for the following code in httpd.conf:

#
User www
Group www

And replace the first "www" with your short username (the name you use to logon to the Mac); so for example, here's what mine says:

#
User cake
Group www

This is necessary in order for PHP's exec() function to be able to pass AppleScript commands to iTunes. The change gives server processes the same privileges as your username, so it would clearly be suicidal to do this on a public-facing web server. But on a home or office network machine, providing that you have a firewall between it and the internet (which you'd be frankly crazy not to have anyway), there shouldn't be a problem.

Step 3. Save and restart

Close and save httpd.conf , then restart Apache with this Terminal command:

/usr/sbin/apachectl restart

Now zTunes will be ready to rock and/or roll!

Script configuration

zTunes is configured and ready to go, but you may wish to customize it more precisely. The configuration file is called config.ini, and you can find it in the root ztunes folder. Here's a summary of what available:

lang_token

zTunes includes a language file for defining output text and HTML; you'll find it in the ztunes/templates/lang/ folder. This file has the name convention "lang-xx.ini", where "xx" is the two-letter language code you specify here.

hybrid_interface

Specify "yes" or "no" for whether to enable the scripting enhancements. In most cases you can leave this at the default setting of "yes", and progressive-enchancement will take care of the rest, for the majority of devices. However if you use a browser-based screenreader it's recommended that you set this to "no".

airfoil_speakers

Specify "yes" or "no" for whether to look for remote speakers controllable through Airfoil.

jukebox_name

Specify the name of the Jukebox playlist.

jukebox_autofill

Specify "yes" or "no" for whether the Jukebox playlist should auto-select tracks when it runs out ("yes"), or only to play tracks that were added manually ("no").

playlist_strlen

Specify to how many characters the string length of playlist names should be trimmed. This is helpful in avoiding overlong names which can cause the tables to be rendered too wide.

track_strlen

Specify to how many characters the string length of track names should be trimmed.

artist_strlen

Specify to how many characters the string length of artist names should be trimmed.

album_strlen

Specify to how many characters the string length of album names should be trimmed.

tracks_per_page

Specify how many tracks to show per page, in tracks listings and search results.

amazon_links

Specify "yes" or "no" for whether artist and album names are also Amazon search links.

amazon_region

If amazon_links is set to "yes", specify the TLD to use for generated links.

Credits

I'm much indebted to John Masone for his article Make your own iTunes Web Remote, from which I got the basic technique for addressing iTunes from PHP.