This article will show you how to control Isadora on macOS using AppleScript.

Download the Examples

Please start by downloading isadora-example-applescripts.zip. You can find the download link at the bottom of this article.

Compatibility with Versions Earlier than Isadora 3.2 and Windows

With the release of Isadora 3.2, we reinstated some AppleScript functionality that was previously available in Isadora 2. Except for the broadcast value command, examples in this article will not work with versions of Isadora before version 3.2.

AppleScript is a macOS technology. Unfortunately, Windows has no equivalent system so these examples can only be run on macOS.

Examining an Application's AppleScript Commands & Features

One great feature of AppleScript's Script Editor is that it can show you the capabilities of any AppleScript compatible application. You just need to drag any scriptable application's icon onto the Script Editor application to open the app's "scripting dictionary".

If you drag the Isadora app onto the Script Editor icon, you'll see something like this:

This scripting dictionary lists the AppleScript elements (i.e., data objects) and the commands supported by the application.

For example, in Isadora's scripting dictionary, click "Isadora Suite" at the top left and look for the document element. You'll see that it has the following properties you can access:

  • name(text, r/o) : Its name.
  • modified(boolean, r/o) : Has it been modified since the last save?
  • file(file, r/o) : The document's file path; for unsaved files this will be empty
  • path(text, r/o) : The document's POSIX file path; for unsaved files this will be empty.

Consider the modified property as an example. You can see that it is a boolean value (true or false), and is read-only as indicated by "r/o". If you wanted to find out if the top document had been modified by the user, you could run the script:

tell application "Isadora"
 set isModified to the modified of document 1
end tell

We'll cover most of those commands below, but the ability to show the scripting dictionary is a great way to remind yourself of what an app can do when running a script in Script Editor.

Simple Tasks

Opening a File

This script will show a file dialog that allows you to choose an Isadora file and then tell Isadora to open it.

(When we say "Try this script" below, it means that you should copy the script into an empty Script Editor document, and choose Script > Run.)

Try this script:

set theFile to choose file with prompt "Please select an Isadora (.izz) file" of type {"izz"}
tell application "Isadora"
 open theFile
end tell

Closing a File

To Save and Close a File, try this script:

-- tell Isadora to close the top document after saving it
-- this only works if the file has been saved before; if you
-- haven't yet saved the file, it will show the save dialog
-- to the user!
tell application "Isadora"
 close document 1 saving yes
end tell

To Close a File Without Saving, try this script:

tell application "Isadora"
 close document 1 saving no
end tell

To Close a File, Asking the User if They Want to Save It, try this script:

-- if the document has been modified, then show the "do
-- want to save" dialog giving the user the option to save,
-- not save, or cancel.
-- if the document has not been modified, then it will be
-- closed without asking the user
tell application "Isadora"
 close document 1 saving ask
end tell

For a complete example that walks you through all three versions of the close statement, try the script close-file-with-options.scpt

Sending a Value to Isadora

An AppleScript can send a numeric or text value to a Listener actor in Isadora using the broadcast value command. In an Isadora document, add two Listener actors: one listening on channel 5, and another listening on channel 6. The second Listener's 'type' input should be set to 'text'. Then try these scripts:

-- broadcast the floating point value 3.1415 to any active Listener actor listening on channel 5
tell application "Isadora"
 broadcast value 3.1415 on channel 5
end tell
-- broadcast the text string "Hello World!' to any active Listener actor listening on channel 6
-- Note that the Listener actor's 'type' input needs to be set to 'text'
tell application "Isadora"
 broadcast value "Hello World" on channel 6
end tell

This command is incredibly powerful. By using Listener actors in your Isadora patch, you can have AppleScript control nearly anything inside of Isadora.

For an example of what is possible, open the script jump-to-scene-example.scpt from the examples you downloaded. This script shows AppleScript that can tell Isadora to jump from one scene to another using the broadcast value command.

Importing Media: Understanding Media Bins and Media Files

AppleScript can tell Isadora to import any media file that Isadora supports. To help you fully understand this, this section goes into detail about how you can access media bins and media files in Isadora via AppleScript. But, if you just want to see this feature in action, skip to the next section Importing Media: Making it Happen and try some concrete examples.

Look at Isadora's scripting dictionary as described above in the section Examining an Application's AppleScript Commands & Features.

Start by dropping the Isadora app on the Script Editor icon to open Isadora's scripting dictionary. Then scroll down to find the document element in the "Isadora Suite". You'll see that it says:

ELEMENTS

contains media bins; contained by application.

This tells you that an Isadora document contains one or more media bins. What's a media bin? Those are the items you see in the Media View in an Isadora document that hold the media files.

Click on the words "media bins" in the scripting dictionary to jump to the description of the Media Bins element. You'll see this:

media bin n [inh. item] : A media bin.

ELEMENTS

contains media files; contained by documents.

PROPERTIES

name (text) : The name of the bin

media type (text, r/o) : The media type of the bin

From this we can tell that the media bin has two properties we can examine – the bin's name and its media type – and that a bin contains another element called media files. The media files element is a list of all media files contained in the bin.

For a demonstration of how you can access the media bins and their files, open the Isadora file "Example With Media.izz". Then try this script:

tell application "Isadora"
 get the media files of media bin 1 of document 1
end tell

You'll see an AppleScript list enclosed in curly brackets appear in the result view, with each item describing the entire hierarchy of where each media file comes from:

{media file 1 of media bin 1 of document "Example With Media.izz" of application "Isadora", media file 2 of media bin 1 of document "Example With Media.izz" of application "Isadora"}.

Perhaps not so useful, except to show that you are indeed getting a list with every media file in that bin.

With "Example With Media.izz" still open, this script might be a bit more interesting:

tell application "Isadora"
 get the name of every media file in media bin 1 of document 1
end tell

The result view in Script Editor will show the names of the three media files in the Video Files bin, which is the first bin in the Media View:

{"Pupil JPEG.mov", "Swirling Pattern.mp4"}

Importing Media: Making it Happen

In the simplest form you can import some media files using the following script:

set the_files to choose file "Choose one or more files to import" with multiple selections allowed
tell application "Isadora"
 import media to document 1 from the_files
end tell

You'll pick the files using the "Open File" dialog shown by the choose file command, and then Isadora will import them into the top document. If one of the files you choose is not a media file or a media file that Isadora doesn't recognize, you'll get an error like this:

error "Isadora got an error: One or more files were not imported because they are a media type Isadora doesn't understand." number -1703 to item

set the_files to choose file "Choose one or more files to import" with multiple selections allowed
tell application "Isadora"
 import media to media bin "Video Files" of document 1 from the_files
end tell

In this case, you can only import media files that are appropriate for the specified bin. In the script above, we identified the bin by its name ("Video Files"). Since we know that this bin can only accept video files, if you run this script and choose a PNG image instead of a movie, you'll get an error like this:

error "Isadora got an error: One or more files were not imported because they are not the right media type. (Only Video Files can be accepted by the bin named 'Video Files'.)" number -1703 to item

To help make all of this clear, we've prepared a couple of example scripts.

import-to-document.scpt shows how to import several files, a single file, or files chosen with an "Open File" dialog.

import-to-bin.scpt shows how to import several pictures, a single picture, or pictures chosen with an "Open File" dialog. This script also allows you to purposely import the file into the wrong bin or a bin that doesn't exist so that you'll see the script errors that occur when you do so.

Automatically Launching and Quitting Isadora

For long-term installations, sometimes you want to automatically launch Isadora at a certain time of day and then quit at a later time. The script launch-quit-isadora-on-schedule.scpt does exactly this. We won't go into a detailed explanation here, because there are plenty of comments in the script, but the main thing you need to change is the launch time and quit time by changing these two lines:

set launch_time to CreateTimeInSeconds(9, 0, 0)
set quit_time to CreateTimeInSeconds(17, 0, 0)

The times passed to CreateTimeInSeconds() are given in hours, minutes, and seconds since midnight in the 24-hour format (e.g., the second line above specifies 5PM = 17:00:00). Just open the script, set the times, and give it try.