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. 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. It's a good idea when starting out to keep the iTunes scripting definition (sdef) handy. Click AppleScript Editor's Window > Library menu and click on "iTunes" in the list; even easier: drop iTunes' icon on AppleScript Editor's icon and the sdef will open up. The sdef displays a list of object classes and events that are 'scriptable in iTunes.



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 a list of references 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}

But you'd never use a reference to a track like this. You would assign it to a variable. You can operate on each track in the list of items in selection by iterating through the list using a repeat block. Below, each track is assigned to the variable aTrack on each iteration:

tell application "iTunes"

if selection is not {} then -- there ARE tracks selected...

set mySelection to selection

repeat with aTrack in mySelection

log (get name of aTrack)

end repeat

end if

end tell

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 current playlist

set aTrack to track i of current playlist

tell aTrack to set track number to i

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:

log (get name of thePlaylist)

repeat with i from 1 to (count tracks of thePlaylist)

log (get name of track i of thePlaylist)

end repeat

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