Here is everything you need to know about downloading and installing the AppleScripts from this site. Watch the short video or read the detailed step-by-step instructions and information below.
Prefatory Note About iTunes 12
iTunes 12.2 introduced a new "Share iTunes Library XML with other applications" setting in the "Advanced" tab of the Preferences panel [screenshot]. Make sure this setting is checkmarked before running any scripts. Some scripts may not work otherwise. I discuss this new setting below.
AppleEvent Sandboxing Introduced in Mojave
The first time a script runs in Mojave, you will be asked to allow it to have access to iTunes. More on this new Mojave security feature is below.
Check for Updates
Download the Doug's Check For Update applet to check if any of your current AppleScripts from this site have newer versions.
You Already Have AppleScript
AppleScript is part of the Mac OS so there's nothing to install except the script you'll download.
First-Timer? Prepare the Installation Location
AppleScripts for iTunes will be accessible from the iTunes Script menu when they have been installed in a special "Scripts" folderactually, installed in one or the other of two special "Scripts" folders. Whichever one you use depends on who'll be using the scripts. (NOTE: see the addendum just below about clean installations of macOS 10.12.)
• All Users
If you want an AppleScript for iTunes to be available for all user accounts on your machine you'll install it once in the "Scripts" folder located in your [startup disk]/Library/iTunes/ folder. This Library folder is often called the local Library folder. If there is no "Scripts" folder in the [startup disk]/Library/iTunes/ folder then create one.
• Single User
To make an AppleScript accessible for just a single user then you'll install it in the "Scripts" folder in that user's [username]/Library/iTunes/ folder. The user Library folder is hidden by default. One way to make it visible is to press and hold the Option key on your keyboard and select Go > Library from the Finder. (See this Macworld article describing how to keep the Library folder visible.) When the user Library is visible, navigate to the "iTunes" folder it contains. If there is no "Scripts" folder in the [username]/Library/iTunes/ folder then create one.
• Clean installations of macOS 10.12 and later may not create the "iTunes" folder in either "Library" folder. I've written about this here. Under these circumstances, you may have to also manually create the intermediate "iTunes" folder.
• In macOS 10.12, it may be that settings you have entered elsewhere prohibit using the Option key as the shortcut to reveal the Library item in the "Go" menu. If the Library folder does not display in the Finder's "Go" menu with the Option key pressed, try the Shift key (see this tip from Rob Griffiths).
The single-user installation is what I've been recommending since 2002. But considering the user Library visibility issue in modern Apple operating systems, the all-users installation may be easier.
Download and Install
Once you have found a script on the site that you'd like to use, click on the red download button in the top-right corner of its entry page:
(Older versions of the script may be available as direct downloads and will be listed in the "Info:" section on the entry page.)
A .zip file will be downloaded to your browser's "Downloads" folder. (You know where that is, right?) A .zip file is a compressed file which, by virtue of its compressed size, transfers fast and easy over the internet
Some users of security softwareIntego products, for examplehave reported that they cannot get the download link to work unless they temporarily turn the software off.
The .zip files from this site have been encoded using the Finder's "Create Archive"/"Compress" command. Most modern browsers will automatically un-zip the filethat is, extract the archived file/folder it contains. (Safari will even move the .zip file to the Trash after its contents have been un-archived.) However, if this is not the case, you merely need to double-click the .zip file for it to un-archive.
When the file is un-zipped, a .dmg file will be un-archived. A .dmg file is a Disk Image File. Some modern browsers may open this .dmg file automatically. In Safari, you can select the .dmg file from the Show Downloads button and double-click it. Otherwise, double-click the .dmg file in the Finder. It will mount in the Finder, like a CD-ROM disk or external drive:
To install the files/folders, drag the items from the disc image window to the "Scripts" folder you prepared (as described above). The .rtf/.rtfd file is the script's "Read Me" file and can be saved anywhere. But keeping it with the script in the "Scripts" folder is probably as good as any other location.
Finally, close the disk image window and unmount it (press the arrow button to the right of its name in the Finder's sidebar).
You can backup the .dmg file, if that's what you do with your downloads. Otherwise, you can Trash it.
AppleEvent Sandboxing (macOS 10.14 Mojave and later)
When you launch an AppleScript downloaded from this site for the first time you will see an alert like this:
This is a new layer of security which attempts to ensure that you are made aware when a script needs to access certain resources on your computer. In the case of scripts from this site, they will inform you that the script needs to interact with iTunes (and perhaps the Finder or other applications if so required). While this may seem self-evident (afterall, the name of this site is "Doug's AppleScripts for iTunes") it is certainly possible that a bad actor could convince you to launch a script that does not do what it says and instead does something else nefarious.
This alert will only appear once. If you happened to click "Don't Allow" and want to permit access for a particular app, head to System Preferences > Security & Privacy > Privacy > Automation, you will see the list of apps that use automation and which apps they target:
If necessary, put a checkmark next to the app you want to allow access to in the script's entry. Or you can uncheck an app if you suspect the listed AppleScript is up to some funny business.
Gatekeeper Security (OS X 10.7.5 and later)
Gatekeeper is a preventative security feature which allows you to limit the types of downloaded files that can be launched on your computer. Gatekeeper settings are accessible in System Preferences > Security & Privacy > General and provides these levels of "trustworthiness":
- Mac App Store apps only
- Mac App Store apps and Developer ID-signed apps (default)
- Any apps (pre-macOS 10.12 only)
A downloaded app (or script) that is not "trustworthy" enough will be prevented from launching, although it can ultimately be launched by right-clicking its icon in the Finder and selecting "Open" from the panel that appears.
Most scripts from this site are codesigned with an authorized developer ID. However, many are not signed at all. Be sure to familiarize yourself with how Gatekeeper works so your downloaded scripts launch without issue.
"Share iTunes Library XML with other applications" (iTunes 12.2 and later)
As of iTunes 12.2, the Advanced pane of iTunes Preferences has a setting to "Share iTunes Library XML with other applications":
The iTunes XML file is periodically updated by iTunes and allows third-party applications to access track and playlist information. Many of my scripts and apps need to access this file or they will not work very well. So, unless you are aware of a specific performance issue or have been told to do otherwise, please, leave this setting checkmarked.
According to this Apple support document, this setting is unchecked by default after installing iTunes 12.2 or later (such as you might during a clean install of the operating system).
Accessibility Considerations (OS X 10.9 and later)
This is less of an issue as of 2015 since I now avoid using "System Events" in distributed software.
As explained here, OS X 10.9 introduced an additional layer of security protection to prevent apps using the Accessibility API from having too much access. This specifically refers to an app or script using "System Events" to emulate button-presses, menu clicks, and other UI-related tasks. A small number of my scripts may oblige the system to ask your permission to control your machine. Inconveniently, this will happen when you first launch the script. It's best to click the "Open System Preferences" button in the alert and allow access. More details here.
Once the files have been installed they will be accessible in iTunes' Script menu:
This menu item will appear if the iTunes Scripts folder contains at least one AppleScript. (You may have to restart iTunes if scripts do not appear here right away.)
Some AppleScript files, such as applets and droplets, may not need to be installed in a "Scripts" folder. In these cases, you can install these AppleScripts wherever it is convenient to launch them or drag files to (in the case of droplets). A script's Read Me will have additional installation information.
Some AppleScripts have been posted for quite some time and I haven't always kept up with updating them. Non-Universal scripts that were compiled years ago on a PowerPC machine will not be able to run on a modern Intel machine until they have been re-compiled on an Intel machine. (Of course, whether or not these older scripts still work with current hardware and software is another matter.)
First, see if there is an updated version of the script(s) you are using. Otherwise, you can convert a PPC script to run on your Intel machine yourself:
- First, make a note of the file extension of the particular AppleScript. This is important. It will be "scpt", "scptd", or "app".
- Now, launch Script Editor (or AppleScript Editor on pre-OS X 10.10 systems) which is located in the /Applications/Utilities/ folder. Click on "Open..." in its "File" menu and navigate to the file of the AppleScript, select it and click the "Open" button. It will open in Script Editor. (The script will not open in Script Editor using the conventional means of double-clicking its icon in the Finder; it must be opened from the File menu.)
- Click on "Save" in the File menu. If the extension you made a note of a moment ago is "scpt" or "scptd", set the "File Format" popup to "Script". If the extension is ".app" then set it to "Application". Make sure "Run Only", "Show Startup", and "Stay Open" are un-checked (in some rare cases a file with an .app extension may need to be "Stay Open"; check if the code contains a section that begins with "on idle"; if so, checkmark "Stay Open").
- Click the "Save" button and quit Script Editor.
After the script has been saved on your machine's native platform, it will run correctly.
Like most applications, AppleScripts need to be updated on occasion. This can be due to updates and changes to iTunes itself, or because the author has discovered bugs or a better way to write the routines. In any case, AppleScripts from this site are occasionally updated. You can find the version number for a script in several places:
- In the file's "Get Info" window (only the most recently posted scripts)
- In the name of the downloaded .dmg file (or in the name of the downloaded "ƒ" folder used before I switched-over to .dmg deliveries).
- In the Description box of the actual script when opened in Script Editor
- In the title of the script's most current Read Me documentation
Download the Doug's Check For Update applet to check if any of your current AppleScripts from this site have newer versions.
Read Me Documentation
Not for nothin', but I put a lot of time into creating the Read Me document for each scriptthe accompanying .rtf, .rtfd or .pdf documentso it is to your advantage to read it and keep it handy for future reference. I know how people feel about Reading the Freaking Manual (and I do try to make the scripts I write as intuitive to use as possible), but it's pretty silly not to.
- The Read Me is available to view as an online PDF in your browser in the "Info" section of its entry.
- Each script's Read Me is named using the name of the script so it will be easy to find in the iTunes Scripts folder after installing.
- The Read Me contains information on using the script and its version history. It also contains some embedded links to helpful information and my RSS feeds. Additionally, it also contains the URL to the script's entry at this site, should you wish to return to the entry to check for an update or to recommend the script to someone.
I understand that I can't account for everyone's computer set-up. If you have any problems installing or using a script from this site, let me know. My contact info is in every Read Me. Otherwise, have fun!