AppleScript

Script ClassicTunes with AppleScript, with example scripts and a complete reference to its dictionary of classes, properties, commands and enumerations.

ClassicTunes can be scripted with AppleScript. Scripts can see and edit the songs in your library, play music, sync, preview and back up iPods, sync other music players, look up covers and details online, and more. Anything you can script, you can also run from the Script menu, from Automator, or from another app.

To see the dictionary for yourself, open Script Editor and choose File › Open Dictionary…, then ClassicTunes.

#Before you start

• The first time a script from another app (such as Script Editor) talks to ClassicTunes, macOS asks whether that app may control ClassicTunes. Click OK. You can change your answer later in System Settings › Privacy & Security › Automation.
• Scripts work on the library that's open in ClassicTunes now. library name tells you which one that is.
• Commands that take a while (backing up an iPod, looking up covers for a whole library, importing a full iPod) keep the script waiting until they finish. AppleScript gives up waiting after two minutes unless you say otherwise, so wrap them in with timeout of … seconds, as the examples below do.

#Scripts only sync iPods set up with this library

A script can only sync an iPod that has already been synced with the library that's open, from inside ClassicTunes. This keeps a script from replacing the music on an iPod that belongs to another library, or one that's never been set up. If you ask a script to sync an iPod that isn't set up yet, it stops with the error "That iPod isn't set up with this library yet. Sync it once from ClassicTunes first." With no iPod named, sync syncs every connected iPod that belongs to this library, and skips the rest.

A script's sync is still careful in the same ways as a sync you start in the app. Before an iPod's first sync, or a sync that would remove a lot, ClassicTunes offers a snapshot first (if that's turned on in Settings › Backups), and the sync waits until you answer in the app.

#Example scripts

#Sync your iPod and eject it when it's done

tell application "ClassicTunes"
    if (count of iPods) is 0 then return "No iPod is connected."
    set myIPod to iPod 1
    sync myIPod
    delay 2
    repeat while syncing of myIPod
        delay 5
    end repeat
    eject myIPod
end tell

sync returns as soon as the sync has started, so the script checks syncing until it's finished. If ClassicTunes asks about taking a snapshot first, syncing stays false until you answer, so answer before the script moves on.

To sync every connected iPod that belongs to this library, use sync on its own:

tell application "ClassicTunes" to sync

#Play a playlist

tell application "ClassicTunes"
    play playlist "Bedtime"
    set sound volume to 40
end tell

#See what a sync would do before you run it

tell application "ClassicTunes"
    set myIPod to iPod 1
    with timeout of 600 seconds
        set report to preview sync myIPod
    end timeout
end tell
display dialog report buttons {"Cancel", "Sync Now"} default button "Sync Now"
tell application "ClassicTunes" to sync myIPod

preview sync works out what syncing would add, convert, remove and change, without changing anything on the iPod, and returns it as a few sentences.

#Find tracks

tell application "ClassicTunes"
    -- Names of your highly rated jazz songs
    get name of every track whose genre is "Jazz" and rating ≥ 80

    -- Songs you've never played, added in the last 30 days
    set newSongs to every track whose played count is 0 and date added > ((current date) - 30 * days)

    -- Give every Blink-182 song five stars
    set rating of (every track whose artist is "Blink-182") to 100
end tell

#Back up an iPod before changing it

tell application "ClassicTunes"
    with timeout of 7200 seconds
        set takenAt to back up iPod 1
    end timeout
end tell
display notification "Snapshot taken " & (takenAt as text)

The first snapshot of a full iPod can take an hour; later ones only copy what changed.

#Add a folder of music and fill in missing details

set newMusic to POSIX file "/Users/Shared/New Music"
tell application "ClassicTunes"
    with timeout of 1800 seconds
        set added to import newMusic with filling in missing details
    end timeout
end tell
display dialog (added as text) & " songs added."

#Choose the music an iPod syncs

tell application "ClassicTunes"
    set myIPod to iPod 1
    set syncs entire library of myIPod to false
    set chosen artists of myIPod to {"Radiohead", "Björk"}
    set chosen albums of myIPod to {"Miles Davis — Kind of Blue"}
    set chosen playlists of myIPod to {"Running"}
    set fill free space of myIPod to unplayed songs
end tell

#Reference

ClassicTunes' dictionary has the Standard Suite that most Mac apps share (open, close, quit, count, exists, windows and so on), and the ClassicTunes Suite, described here.

Types in the tables: text, integer (a whole number), real (a number that can have decimals), boolean (true or false), date, file, and list of text. Properties marked read-only can be read but not set.

#application

ClassicTunes itself. These properties and elements are used inside tell application "ClassicTunes".

#Elements

You can refer to them by number (iPod 1), by name (playlist "Bedtime"), by id (track id "…"), or with whose (every track whose artist is "Prince"). All four are read-only: scripts can change tracks and playlists, but not add or delete them.

#Properties

The application also responds to play: play on its own carries on with what's paused, or starts the first song in the library if nothing is playing.

#track

A song, video or audiobook in the library. Changes you make to a track's details are written into its file's tags, as they are when you edit them in Get Info, and go to iPods at their next sync. Setting a text property to "" clears it.

Tracks respond to play. play track 3 plays one track; play (every track whose album is "Abbey Road") plays all of them in order, as one queue.

#playlist

A playlist or smart playlist.

Playlists respond to play (an empty playlist gives the error "The playlist is empty.") and export.

#iPod

A connected iPod.

The choices you set here are the same ones as on the iPod's page under Sync Options, and they're saved with the open library. Setting any of them when the iPod isn't connected gives the error "That iPod isn't connected."

iPods respond to sync, preview sync, back up, add to library and eject.

#music player

A connected music player that isn't an iPod, set up with iPod › Set Up a Music Player… (for example a Shanling Q2, a Tangara, a Rockbox player or an SD card).

Music players respond to sync and eject. Unlike iPods, a music player doesn't have to belong to the open library to be synced by a script.

#Commands

#play

Plays a track, several tracks, or a playlist, or carries on with what's paused.

play [track, list of tracks or playlist]

• With a track: plays it.
• With several tracks (play (every track whose …)): plays them in order, as one queue.
• With a playlist: plays its tracks in order.
• On its own: carries on if something is paused, or starts the first song in the library if nothing is playing.

#pause

Pauses playback.

#playpause

Plays if paused, pauses if playing.

#start playing

Starts what Settings › General › Play key › Play chooses for this library (carry on where you left off, shuffle all songs, a playlist, recently added, or your current audiobook), or carries on if something is paused.

#stop

Stops playback.

#next track

Skips to the next track.

#previous track

Goes back to the previous track.

#sync

Syncs an iPod (or every connected iPod) that's already set up with this library, or syncs a music player.

sync [iPod or music player]

• With an iPod: syncs it, if it belongs to the open library.
• With a music player: syncs it.
• On its own: syncs every connected iPod that belongs to the open library.

sync returns straight away; check the iPod's syncing property to see when it's finished. A first or large iPod sync asks about a snapshot in the app first. Errors: "No iPod is connected.", "That iPod isn't set up with this library yet. Sync it once from ClassicTunes first.", and "None of the connected iPods are set up with this library yet. Sync them once from ClassicTunes first."

#preview sync

Works out what syncing the iPod would do, without changing anything on it.

preview sync iPod

Result: text. A few sentences: what's added (and converted first), what's removed, the playlists that change, and the space left afterward (or how much more is needed). Podcast episodes still to download are counted, not downloaded.

#back up

Saves a snapshot of the whole iPod. Only what changed since its last snapshot is copied.

back up iPod

Result: date. When the snapshot was taken. A first snapshot of a full iPod can take an hour, so use a long timeout.

#add to library

Copies everything on the iPod into the library: its songs, videos and audiobooks with their covers, play counts, ratings and other details, its playlists (On-The-Go and smart ones too), and its podcasts as subscribed shows. Songs already in the library are left as they are. Nothing on the iPod changes.

add to library iPod

Result: integer. How many items were added (songs, videos, audiobooks and podcast episodes). A full iPod takes a while, so use a long timeout.

#eject

Ejects an iPod or music player.

eject iPod or music player

If the iPod is busy (for example, Finder has a window open on it), the script gets an error saying what to do.

#import

Adds files or folders to the library.

import file or list of files [with filling in missing details]

• An .m3u or .m3u8 playlist file becomes a playlist; its songs that aren't in the library yet are added.
• An OPML file subscribes to the podcasts it lists.
• Files are copied into the library or left where they are, as Settings › General › Adding songs › Copy files into the library when adding them says. Scripts add straight away, without the window that shows what will be added.

Result: integer. How many items were added (songs, or podcasts for an OPML file).

#export

Saves a playlist as an .m3u8 file, which most music apps and players open.

export playlist to file

set destination to POSIX file "/Users/Shared/Road Trip.m3u8"
tell application "ClassicTunes" to export playlist "Road Trip" to destination

#export podcasts

Saves your podcast subscriptions as an OPML file, which other podcast apps import.

export podcasts to file

Result: integer. How many podcasts were saved.

#check for new episodes

Checks every podcast for new episodes and, unless told not to, downloads the episodes each show keeps for iPods.

check for new episodes [downloading boolean]

Result: integer. How many new episodes were found. Many podcasts take a while, so use a long timeout.

#find missing artwork

Looks online (Apple and MusicBrainz) for covers of albums that have none, and adds a cover only where the title, artist and year clearly match.

find missing artwork [track or list of tracks]

Result: integer. How many albums got a cover.

#find better artwork

Looks online for larger copies of album covers, and replaces a cover only where the same artwork is found larger.

find better artwork [track or list of tracks]

Result: integer. How many albums got a better cover. Checking many albums takes a while, so use a long timeout.

#look up and replace info

Looks albums up on Apple and MusicBrainz, and replaces their info (title, artist, year, genre, song titles and track numbers, in the files too where their format allows) only where the release clearly matches: most of the album's songs, by the same artist. A backup of the library's info is saved first.

look up and replace info [track or list of tracks] [adding covers boolean]

Result: integer. How many albums were changed.

#convert for iPods

Sets how iPods get tracks they can't play as they are, or converts them once. Tracks iPods already play are skipped.

convert for iPods track or list of tracks [how iPod conversion] [as AAC boolean]

Result: integer. How many tracks were changed.

tell application "ClassicTunes"
    convert for iPods (every track whose iPod compatible is false) how kept copy
end tell

#send scrobbles

Sends the plays waiting to ListenBrainz now. They're otherwise sent shortly after each play or sync.

Result: text. A sentence saying what happened. With no account set up, it says so.

#check for updates

Checks for a newer version of ClassicTunes, showing what's new and offering to install it. In a copy of ClassicTunes that can't update, it gives an error saying so. See Updates.

#activate license

Activates a license key on this Mac and returns a sentence saying who it's licensed to. It needs an internet connection. If the key is wrong, canceled, or already in use on two Macs, it gives an error saying so.

activate license "CT-XXXXX-XXXXX-XXXXX-XXXXX"

#deactivate license

Deactivates the license on this Mac, freeing its place for another Mac. See Trial and License.

#check license

Checks with classictunes.app now that the license is still active on this Mac, and returns a sentence saying whether ClassicTunes is licensed. ClassicTunes otherwise does this by itself about once a month. If this Mac was removed from its license, or the license was refunded, syncing stops; if there's no internet connection, nothing changes.

#license macs

Returns the names of the Macs this Mac's license is activated on, this one included. It needs an internet connection.

license macs -- {"Mac Studio", "MacBook Air"}

#remove license mac

Removes another Mac from this Mac's license, by its name as license macs lists it, freeing its place for a new Mac: for one that's lost, sold or no longer used. It stops syncing when it next checks its license. To free this Mac's place, use deactivate license instead.

remove license mac "MacBook Air"

After the trial, sync gives an error saying the trial has ended.

#Enumerations

#media kind

#video kind

#fill choice

#iPod conversion

#player state

#Errors scripts can get