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
httpd.conf, for which
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.
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!
- 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!
Live progress information is displayed in the
now playingarea (if the client web-browser supports
XMLHttpRequest), which includes time elapsed/remaining, and an animated song pointer
- 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.
Version 1.1 updates the layout and output styling for better compatibility with small-screen devices:
"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
ztunes. Copy this entire folder into Apache's root
documents folder, which unless you've changed it, will be
Once it's there you can
get to it from any browser on your network, using the address
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
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
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
and then logon as root by typing this:
Then enter your root password (if you've never set a root password,
Applications/Utilities and open
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
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
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:
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
# 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
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:
Now zTunes will be ready to rock and/or roll!
zTunes is configured and ready to go,
but you may wish to customize it more precisely.
The configuration file is called
and you can find it in the root
Here's a summary of what available:
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
"xx"is the two-letter language code you specify here.
"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"for whether to look for remote speakers controllable through Airfoil.
Specify the name of the Jukebox playlist.
"no"for whether the Jukebox playlist should auto-select tracks when it runs out (
"yes"), or only to play tracks that were added manually (
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.
Specify to how many characters the string length of track names should be trimmed.
Specify to how many characters the string length of artist names should be trimmed.
Specify to how many characters the string length of album names should be trimmed.
Specify how many tracks to show per page, in tracks listings and search results.
"no"for whether artist and album names are also Amazon search links.
amazon_linksis set to
"yes", specify the TLD to use for generated links.
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.