Commonly Used iTunes Objects 1 2 3 

Objects, Elements & Properties

Every thing in iTunes is an AppleScript object: playlist, track, source, etcetera. Every object can be defined by its relationship to its container: a track is in a playlist which is in a source which is in the application iTunes (that Jack built). This relationship is called a hierarchy because it defines relationships based on rank.

The top object--or root object, depending on your perspective--is the application—iTunes itself. If you look in iTunes AppleScript Dictionary (you don't buy this dictionary at Barnes & Noble; you access it from Script Editor's Window > Library menu; even easier: drop iTunes' icon on Script Editor's icon and the dictionary will open up), you will see a list of object classes and events.



For example, the application object has several elements and properties. The elements are other objects contained by application. Each element may also be a container for still other objects and properties. The properties can contain values that affect the object. You can get or set the value of a property, usually with a number, string, or boolean true or false.

In AppleScript, you access the property of an object, like the name of a particular track in a particular playlist, like this:

tell application "iTunes"
	name of track 1 of library playlist 1
end tell

Or like this:

tell application "iTunes"
	tell library playlist 1
		tell track 1
			name
		end tell
	end tell
end tell

It will depend on the script you are writing, what properties you want to access, and at what level of the hierarchy they are located. (See the section on playlists for more in-depth playlist scripting information.)

Below are some of the more commonly used object, elements, and properties and example syntax. I've left out the stuff that seems pretty obvious.

Application objects and properties

player state

This application property will tell you what iTunes is doing and will return one of these values: stopped, playing, paused, fast forwarding, or rewinding.

tell application "iTunes"
	if player state is stopped then play
end tell

current track and current playlist

If iTunes is playing or paused, these objects exist.

tell application "iTunes"
	if player state is playing then
		set myTrack to current track
	end if
end tell

tell application "iTunes"
	if player state is playing or player state is paused then
		set myPlaylist to current playlist
		set view of front window to myPlaylist
	end if
end tell

tell application "iTunes"
	if player state is not stopped then
		set myAlbum to (get album of current track)
	end if
end tell

selection

The selection object is an element of application as well as browser window and playlist window. It returns a list of references to the tracks selected.

tell application "iTunes"
	selection
end tell

The above returns something like this:

{file track id 4542 of user playlist id 4539 of source id 33, file track id 4543 of user playlist id 4539 of source id 33, file track id 4544 of user playlist id 4539 of source id 33, file track id 4545 of user playlist id 4539 of source id 33}

Once you have the selection, you can operate on the items it contains:

tell application "iTunes"
	if selection is not {} then -- there ARE tracks selected...
		set sel to a reference to selection
		repeat with aTrack in sel
			log (get name of aTrack)
		end repeat
	end if
end tell

In the snippet above I have set the variable "sel" to a reference to the selection. In this way, "sel" is a pointer to the selection object, not a variable filled with track references. This makes it much more manageable in scripts, and speedier, too!

player position

If iTunes is playing or paused, the player position is the current point in the current track in seconds:

tell application "iTunes"
	if player state is paused then
		set this_paused_moment to player position
	end if
end tell

fixed indexing

By setting fixed indexing to true before working with any tracks the sort order of the tracks will not be change during any AppleScript tasks you perform, which otherwise could really mess things up. Set it before any work on a lot of tracks:

tell application "iTunes"
	set oldfi to fixed indexing
	set fixed indexing to true
	repeat with i from 1 to count tracks of user playlist "Favorite Tracks"
		set aTrack to track i of user playlist "Favorite Tracks"
		set name of aTrack to (aTrack's artist & " - " & aTrack's name)
	end repeat
	set fixed indexing to oldfi
end tell

An excellent example of a problem without fixed indexing: if your script deletes tracks, the indexing of the tracks may change with each deletion. By setting fixed indexing, the indexing stays, well, fixed until the AppleScript is finished. Good to re-set fixed indexing afterwards, too.

Window properties

The browser window (main iTunes window) and playlist window objects inherit properties of the window object. The window object uses all the "usual" window properties (bounds, closeable, collapseable, position, etc). Additionally, browser window and playlist window share a selection property (discussed above) and a view property. The view of the browser window is a reference to the playlist selected in the Source pane. The view of the playlist window is the reference to the playlist in that window.

I generally use view like this:

tell application "iTunes"
	set thePlaylist to view of front window
	-- for example:
	display dialog (name of thePlaylist) & " is selected."
end tell

Since the "front window" is almost always a playlist or browser window, it works out. Strictly scripting, however, I should probably use "view of front browser window".

The browser window also has the minimized property, which you can get or set with a boolean true or false. This enables you to shrink the iTunes window down to the small player window:

tell application "iTunes"
	set minimized of front browser window to true
end tell

Playlist properties

For the most part, most of the playlist classes share the same properties listed in the dictionary under playlist. Obviously, there are differences: an audio CD playlist can't contain an URL track (hmm, maybe that isn't obvious) and a library playlist doesn't contain a composer property like the audio CD playlist does.

duration

Returns the total length in seconds of all songs in the playlist:

tell application "iTunes"
	set total to duration of playlist "Mom's Favorites"
	if total is less than (2 * hours) then
		display dialog "Still need more songs!"
	end if
end tell

shuffle

The shuffle property accepts a boolean true or false. This is actually a pretty cool property. By switching it on and off you get the same affect as option-clicking the shuffle button a bunch of times. So setting it to just on or off once is only one dynamic. I use it like this to get a great shuffle (although there is argument about this at virtually every iTunes board I'm aware of):

tell application "iTunes"
	tell myPlaylist -- whatever it is
		repeat 5 times
			set shuffle to false
			set shuffle to true
		end repeat
	end tell
end tell

Read more on playlists and tracks.

Encoder stuff

current encoder

The current encoder is an application property that returns a reference to the encoder you have currently selected in iTunes Importing Preferences. Once you have that, you can get its name and format. You can also set a new current encoder.

Here's how to have the user select a new encoder:

tell application "iTunes"
	set myOptions to (get name of every encoder)
	repeat with j from 1 to (count of myOptions)
		if name of current encoder is item j of myOptions then
			copy name of current encoder to encoder_backup
			exit repeat
		end if
	end repeat
	set myNewEncoder to (choose from list myOptions with prompt ¬
		"Choose new encoder" default items ((get name of current encoder) as list) ¬
		without multiple selections allowed and empty selection allowed) as string
	if myNewEncoder is "false" then error number -128
	set current encoder to encoder myNewEncoder
	-- do stuff
	-- re-instate original encoder
	set current encoder to encoder encoder_backup
end tell

The script Quick Convert uses a routine like this.

If you need to select an encoder without human help, for example, the AAC encoder:

tell application "iTunes"
	set preferred_encoder to current encoder
	set available_encoders to (name of encoders)
	repeat with anEnc in available_encoders
		if format of encoder anEnc is "AAC" then
			set current encoder to encoder anEnc
			exit repeat
		end if
	end repeat
	-- do stuff
	-- re-instate original encoder
	set current encoder to preferred_encoder
end tell