I have a laptop in one room and my main computer in another. My music is all on the other computer, which is plugged directly into my stereo via an M-Audio FireWire Audiophile. Sometimes, I feel like controlling iTunes from the laptop. There are tools that will do this, but they require opening up remote scripting or similar technologies on the host computer. I prefer a nice, simple interface that I can use via the already-existing SSH command line.

My first attempt at this involved a Perl script that called an AppleScript, waited for the script to finish, and then operated on files that the script left behind. This worked fine for play and for pause, but was very unreliable for finding and playing tracks based on various criteria.

Several weeks ago, I ran across appscript. This is a Python module that brings scriptability down directly into Python. It makes extensive use of Python’s strengths, and it is extremely useful. However, the documentation for it is extraordinarily sparse. It’s great that the help is built in, but the built-in help is also decidedly hit-or-miss. You have to guess where something is in order to get the help for it.

Each object has a .help() method attached to it. For example, after installing appscript, start up pythonw (you need to use pythonw rather than python so that Python can attach to the GUI) and type:

You can also do “help(appscript)”. And you may find “help(appscript.specifier)” useful. There is very little otherwise in the way of documentation. This is very much for Python programmers who don’t like the Applescript way. Those of us who do like Applescript but want a solid command-line scripting environment will have to muddle through.

Methods and properties appear to be the same as in the dictionary that ScriptEditor shows, with spaces replaced with underscores.

If you want a value of a property, you need to append it with “()”: both properties and actions appear to be functions. I suspect that “()” is shorthand for the “.get()” method on the object.

If you don’t want the value, but plan on getting another value off of it later, you probably do not want to use “()” or “.get()”. Doing so may give you a huge, time-consuming list. For example, if you want the third track, you do not want to do:

If there are 10,000 tracks in your playlist, this will grab them all and will be noticeably slow. If you really only want the third track, just do:

The help will often look something like this, from iTunes.play.help():

Terminology for play command Command: play(...) -- play the current track or the specified track or file.
[Reference] -- item to play
[once=Boolean] -- If true, play this track once and then stop.

The “Reference” is the object on which this method rests: you don’t have to provide it. The remaining options need to be specified by name. So you can call play as “object.play()”, as “object.play(once=True)’, or as “object.play(once=False)”.

Finally, some of the lists you get back start at 0 and some start at 1.

Command-line iTunes controller

This seemed perfect for implementing my iTunes command line. And, in fact, it was. But it took a lot of work to figure out everything I needed to know.

Before I get into how it works, here are a few examples of what it does:

itunes
SLOW RIDE (8:14)
Foghat (Fool For The City, 1975)
****

itunes --extended
SLOW RIDE (8:14)
Foghat (Fool For The City, 1975)
Genre: Hard Rock
Last Played: 2006-03-06 06:58:55
Playcount: 12
Remaining Time: 7:32
****

itunes --upcoming 5
3 - Tuesday Morning by Chris Reed and the Anime Raiders on Something Positive Thanks (4:41)
4 - Overture by Orchestra on George M! (3:35)
5 - Hindustan by Bing Crosby and Rosemary Clooney on fancy meeting you here (2:52)
6 - Take It Anyway You Want It by Pat Benatar on Precious Time (2:49)
7 - Hot And Bothered by Combustible Edison on The Impossible World (3:17)

302: itunes --find lola
Found 2 tracks in A-List
1199 - Whatever Lola Wants by Ella Fitzgerald on Ella Sings Broadway (3:15)
4802 - Whatever Lola Wants by Cashmere Jungle Lords on Southern Barber Supply (2:34)

Whenever the command results in a list, the number on the left is an index. I can play the Ella Fitzgerald tune above, for example, using “itunes --index 1199”.

How does it work?

I couldn’t figure out how to subclass a track, so I ended up writing basically a filter class to it, called “smarterTrack”.

This class requires a “track” object when it is created. Then, I added the basic functionality I needed to duplicate the track, such as:

Some text items need to be encoded to utf_8 or Python will have trouble displaying them on the terminal. Since they are Python strings, I used their built-in “encode” method:

The appscript module contains some useful constants in appscript.k. For example, If you want to know the current state, you can use:

isPlaying = iTunes.player_state() == appscript.k.playing

For missing values, there is appscript.k.MissingValue. Some tracks don’t yet have values for some fields, such as the last played time if a track has never been played.

One other trick is that iTunes stores a song’s rating as a number from 0 to 100. If you want to display the number of stars in the same manner that iTunes does, you need to divide a song’s rating by 20. Here, I do that division and then take advantage of Python’s ability to multiple strings:

Show track info

The default action for this script is to show information about the current track. This is handled by the “bug” method on the smarterTrack class.

I can then display the bug in a script using this code:

Find

One of the most useful parts of this script is its ability to find and possibly play a specific track. To find a song, you may need to look in the main library. The current library generally will not contain all songs. Finding the main library is not quite what it should be. There ought to be a “library_playlist” property on iTunes. It’s in Applescript, but I can’t find it in appscript. The hack is simply to get the list of all playlists and then get the first one. Currently, the first playlist is the main library. Note that this is one of those lists that starts at 1 rather than 0.

playlist = iTunes.playlists[1]

If you want the current playlist, the easiest way to get it is probably to get the playlist that the current track is playing in:

playlist = self.track.container()

When you search, you have to search within a playlist.

appscript.k contains constants that you’ll need to do things such as search in a specific field, such as the song title, artist name, or album name.

This script takes -f "text to search for" and -w "where to search": album name, track title, or song name. If no “where” is specified, the script searches everywhere.

For example:

itunes -f "having fun tonight" -w "album"

will show me all of the songs on any album whose title contains the phrase “having fun tonight”.

Sending the “where” to iTunes means using appscript.k.artists, appscript.k.albums, appscript.k.songs, or, if searching everywhere, appscript.k.all.

Now that we know where to search, it is time to do the search. That’s pretty easy: it’s just one line of code, a call to iTunes.search(). The search method needs to know the playlist in which to search, the text to search for, and the track fields to search in.

The script will, if no tracks are found in the current playlist, then go ahead and search the main library.

Now we have either found something or not. If we found only one song and we’ve requested playback (the default), the script calls .play(foundTrack) to play that track. Otherwise, it displays the bug for that track. If the search found multiple songs, a line of information, including the index number, is displayed for each found track.

Interesting issues

Administrative accounts can run this script and get access to the GUI even if they are not the currently-logged-in account. They’ll need to run the script using sudo, and can then control the currently-running iTunes.

If no one is logged in, however, accessing iTunes from an administrative account will start up iTunes as root. ITunes will set up an iTunes folder in the root home directory (/var/root) and will attempt to run through the setup process that iTunes always goes through the first time you open it. You won’t want to do that. That would open your computer up to some major hacking, as any hack-laden media file that iTunes was convinced into running would run as root on your system.