# Shortcuts

> Every ClassicTunes action in the Shortcuts app, what each one takes and gives back, and the items you can pick from.

On macOS 13 Ventura and later, ClassicTunes adds its own actions to the Shortcuts app. You can play music, sync and back up iPods, choose what each iPod gets, add files to your library, look up covers and details, and more, all without opening ClassicTunes' window.

> **Note:** Shortcuts actions need macOS 13 or later. On macOS 12 Monterey, ClassicTunes works the same in every other way, and you can automate it with [AppleScript](https://classictunes.app/docs/applescript) instead.

## Find the actions

1. Open the Shortcuts app and create a new shortcut (or open one).
2. In the list of actions on the right, click **Apps**, then **ClassicTunes**. You can also search for an action by name, such as "Sync iPod".
3. Drag an action into your shortcut, or double-click it.

Actions work on the library that's open in ClassicTunes now. If ClassicTunes isn't running, Shortcuts opens it to carry them out.

## Things you can pick

Several actions ask for a track, playlist, iPod or music player. Shortcuts shows a list to choose from, and you can also pass one along from an earlier action.

| Kind | How you pick it | What it tells you |
|---|---|---|
| **Track** | Search by title, artist or album (up to 200 matches). Without a search, Shortcuts suggests the 50 songs you played most recently. | Name, Artist, Album, Kind (Song, Video or Audiobook), Duration (seconds), Play Count, Rating (stars), Plays on iPod Without Conversion, Explicit |
| **Playlist** | Every playlist in the library, or search by name. | Name, Smart |
| **iPod** | The iPods connected now. | Name, Model |
| **Music Player** | The music players (not iPods) connected now. | Name, Kind |

## Playback

| Action | What it takes | What it gives back |
|---|---|---|
| **Play Playlist** | A playlist, and **Shuffle** (off unless you turn it on). | Nothing |
| **Play Artist** | An artist (chosen from the library's artists), and **Shuffle**. Plays their albums, newest first, then songs they appear on. | Nothing |
| **Play Tracks** | One or more tracks. Plays them in the order given. | Nothing |
| **Play/Pause** | Nothing. Pauses if something is playing, or carries on if it's paused. | Nothing |
| **Start Playing** | Nothing. If nothing is loaded, plays what the Play key setting chooses (see [Settings](https://classictunes.app/docs/settings#play-key)); if something is paused, carries on. | Nothing |
| **Pause** | Nothing. | Nothing |
| **Next Track** | Nothing. | Nothing |
| **Previous Track** | Nothing. | Nothing |
| **Get Current Track** | Nothing. | The track playing or paused now, or nothing if none is |
| **Set Volume** | **Volume (0–100)**. | Nothing |
| **Set Audiobook Speed** | **Speed**, from 0.75 to 2 (1 is normal). | Nothing |

**Play Playlist** stops with "The playlist is empty." if there's nothing in it. **Play Artist** first looks for an artist with exactly that name, then for one whose name contains it, and stops with a message if there's no match. **Start Playing** stops with "There's nothing in the library to play." in an empty library.

## iPods and music players

| Action | What it takes | What it gives back |
|---|---|---|
| **Sync iPod** | An **iPod** (optional). Leave it empty to sync every connected iPod. | Nothing; it returns once the sync has started |
| **Preview iPod Sync** | An **iPod** (optional; the first connected iPod if empty). | A few sentences saying what a sync would add (and convert first), remove, which playlists change, and the space left afterward. Nothing on the iPod changes. |
| **Eject iPod** | An **iPod**. | Nothing |
| **Back Up iPod** | An **iPod** (optional; the first connected iPod if empty). Saves a snapshot of the whole iPod; only what changed since its last snapshot is copied. | The date and time of the snapshot |
| **Import Media from iPod** | An **iPod** (optional; the first connected iPod if empty). Adds everything on the iPod that isn't in the library yet. Nothing on the iPod changes. | How many items were added |
| **Sync Music Player** | A **Music Player** (optional). Leave it empty to sync every connected one. | Nothing |

> **Important:** Like AppleScript, **Sync iPod** only syncs an iPod that's already been synced with the open library from inside ClassicTunes. Otherwise it stops with "That iPod isn't set up with this library yet. Sync it once from ClassicTunes first." A first sync, or one that would remove a lot, still offers a snapshot in the app first (if that's turned on in **Settings › Backups**), and waits for your answer.

See [Syncing](https://classictunes.app/docs/syncing), [Preview Sync](https://classictunes.app/docs/preview-sync), [Snapshots](https://classictunes.app/docs/snapshots) and [Music players](https://classictunes.app/docs/music-players).

## Choosing what syncs

These actions change an iPod's or music player's Sync Options, just as if you'd changed them on its page. If you don't choose an iPod and exactly one is connected, they use that one; with several connected they stop with "Choose which iPod."

| Action | What it takes | What it gives back |
|---|---|---|
| **Choose Music to Sync** | **Entire Library** (on or off), **Artists**, **Albums** (each written "Artist — Album"), **Genres**, **Playlists**, and an **iPod** or a **Music Player**. | Nothing |
| **Set Fill Free Space** | **Fill With** (see below), and an **iPod** or a **Music Player**. | Nothing |
| **Choose Photos to Sync** | **All Photos** (on or off), **Albums** (by name), **Periods** (a year such as "2019", or a month such as "2019-07"), **Limit (GB, 0 for none)**, **Include Videos** (off unless you turn it on), and an **iPod**. | Nothing |

**Choose Music to Sync** replaces the music choices: anything you leave empty is no longer chosen. Turn on **Entire Library** to sync everything; otherwise the iPod gets the artists, albums, genres and playlists you give.

**Set Fill Free Space** chooses what tops up the iPod after the music you chose, like iTunes' Autofill. It's only used when the iPod syncs chosen music rather than the entire library. **Fill With** can be:

- **Off**
- **Songs You Haven't Played**
- **Highest Rated Songs**
- **Most Played Songs**
- **Recently Added Songs**
- **Random Albums**

**Choose Photos to Sync** finds albums by name in both the Photos app and ClassicTunes' own photo library. Periods that aren't a year or a year and month are ignored. See [Photos](https://classictunes.app/docs/photos).

## Your library

| Action | What it takes | What it gives back |
|---|---|---|
| **Add to ClassicTunes** | **Files** (songs, videos or folders), and **Fill In Missing Details** (off unless you turn it on). | How many items were added |
| **Import Playlist File** | A **Playlist File** (.m3u or .m3u8). | The new playlist |
| **Export Playlist** | A **Playlist**. | An .m3u8 file, which most music apps and players open |
| **Import Podcast Subscriptions** | An **OPML File** from another podcast app. | How many podcasts were added |
| **Export Podcast Subscriptions** | Nothing. | An OPML file named "ClassicTunes Podcasts.opml" |
| **Check for New Podcast Episodes** | **Download Them** (on unless you turn it off). Checks every podcast and downloads the episodes each show keeps for iPods. | How many new episodes were found |
| **Set Video Details** | A **Video**, its **Kind** (Movie, TV Show, Music Video or Home Video), and for a TV show its **Show**, **Season** and **Episode**. Details you leave empty aren't changed. | Nothing |

**Add to ClassicTunes** adds straight away, without the review window you see in the app. With **Fill In Missing Details** on, it looks the albums up on Apple and MusicBrainz and, where one clearly matches, fills in what the songs are missing and adds a cover if they have none. Details already in the files are never changed. Whether files are copied into the library follows **Settings › General › Adding songs**. See [Your library](https://classictunes.app/docs/library).

**Import Playlist File** adds songs whose files are on this Mac but not yet in the library, and finds the others by artist, title and length. See [Playlists](https://classictunes.app/docs/playlists) and [Podcasts](https://classictunes.app/docs/podcasts).

## Artwork and details

| Action | What it takes | What it gives back |
|---|---|---|
| **Find Missing Artwork** | **Tracks (all albums if empty)**. Looks online for covers of albums that have none, and adds one only where the title and artist clearly match. | How many albums got a cover |
| **Find Better Artwork** | **Tracks (all albums if empty)**. Looks online for larger copies of album covers, and replaces those where the same artwork is found larger. | How many albums improved |
| **Look Up and Replace Info** | **Tracks (albums missing details if empty)**, and **Add Covers to Albums Without One** (on unless you turn it off). Replaces album info (title, artist, year, genre, song titles and track numbers) only where the release clearly matches. A backup of your library's info is saved first. | How many albums changed |
| **Convert for iPods** | **Tracks**, **How** (see below), and **AAC Even for Lossless Songs** (off unless you turn it on). Tracks iPods already play are skipped. | How many tracks changed |

For tracks, these actions work on the albums the tracks belong to. **How** can be:

- **Convert Once, Replacing the File**
- **Convert at Every Sync**
- **Keep a Converted Copy for iPods**
- **Back to the Default**

See [Artwork](https://classictunes.app/docs/artwork) and [Tidying up](https://classictunes.app/docs/tidying-up).

## Settings, scrobbling and updates

| Action | What it takes | What it gives back |
|---|---|---|
| **Turn ListenBrainz Scrobbling On or Off** | **On** (on unless you turn it off). | Nothing |
| **Send Plays to ListenBrainz** | Nothing. Sends the plays waiting now, instead of shortly after each play or sync. | A sentence saying what happened |
| **Check for ClassicTunes Updates** | Nothing. Opens ClassicTunes and checks for a newer version, showing what's new and offering to install it. | Nothing |
| **Get ClassicTunes License Status** | Nothing. | A sentence saying who ClassicTunes is licensed to, or how many days are left in the trial |
| **Activate ClassicTunes License** | **License Key**. Activates it on this Mac (it needs an internet connection). | The same sentence, once activated |
| **Check ClassicTunes License** | Nothing. Checks now that the license is still active on this Mac (otherwise done about once a month). | The license status sentence |
| **Get ClassicTunes License Macs** | Nothing. | The names of the Macs the license is activated on |
| **Remove Mac from ClassicTunes License** | **Mac Name**, as **Get ClassicTunes License Macs** gives it. Frees that Mac's place. | Nothing |

Plays are only sent once a ListenBrainz account is set up in **Settings › Scrobbling**; until then, **Send Plays to ListenBrainz** stops with a message saying so. See [Scrobbling](https://classictunes.app/docs/scrobbling), [Updates](https://classictunes.app/docs/updates) and [Trial and License](https://classictunes.app/docs/licensing). After the trial, **Sync iPod** and **Sync Music Player** stop with a message saying the trial has ended.

## Siri and Spotlight

ClassicTunes suggests a few ready-made shortcuts, which you can run from Spotlight or by asking Siri, with no setup:

- "Sync my iPod with ClassicTunes" or "Sync ClassicTunes" (**Sync iPod**)
- "Back up my iPod with ClassicTunes" (**Back Up iPod**)
- "Start playing ClassicTunes" or "Play music in ClassicTunes" (**Start Playing**)
- "Play or pause ClassicTunes" (**Play/Pause**)
- "Next track in ClassicTunes" (**Next Track**)

## When an action can't run

An action that can't do what it's asked stops the shortcut with a message, for example:

- "No iPod is connected." or "No music player is connected."
- "That iPod isn't connected."
- "That playlist isn't in the library."
- "That isn't a video in the library." (from **Set Video Details**)
- "That file couldn't be read as a playlist."
- "This copy of ClassicTunes can't check for updates." (before ClassicTunes is released; see [Updates](https://classictunes.app/docs/updates))

## Example: preview, then sync

This shortcut shows you what a sync will change, then starts it:

1. **Preview iPod Sync** (leave **iPod** empty).
2. **Show Result**, with the preview from step 1.
3. **Sync iPod** (leave **iPod** empty to sync every connected iPod that belongs to this library).

**Sync iPod** returns as soon as the sync starts, so don't follow it with **Eject iPod**: the iPod is still syncing. To eject automatically when a sync finishes, turn on **Eject the iPod when a sync finishes** in **Settings › General › Syncing**.

For the same things from a script, see [AppleScript](https://classictunes.app/docs/applescript).