Creating a script from start to finish

← Scripting Center

In this article, we will go over the basic steps for creating and using a Script in Audio Hijack. Our example script will show the basics of writing a 'Recording Stop' script, that processes recording files as they are completed. So let's get started making our script:

Scripting Library Window

1. First, from the 'Window' menu, select 'Script Library'. With the 'Script Library' open, click the 'Users Scripts' tab, as that is where custom scripts are created and stored.

2. Now, click 'New Script', to create a new empty script. Select the newly created script (named 'New Script'), then click the 'Pencil' edit button next to it's title. Type in an appropriate name, in our example, 'Set Recording XAttrs'

3. Type your script in the script editor. Here is our example script:

// set the "Where From" URL that appears in the Finder's Get Info window
// #needsFile 

function shellArgEscape (arg) { return `'${arg.replace(/'/g, `'\\''`)}'`; }

let url = 'https://www.example.com/';
let filePath = event.file.filePath;
var cmd = 'xattr -w com.apple.metadata:kMDItemWhereFroms '

cmd += shellArgEscape(url) + ' ';
cmd += shellArgEscape(filePath) + ' ';
let [status, stdout, stderr] = app.runShellCommand( cmd );

4. Connect your script to an event automtion. Open the Session you desire to automate, click on the 'Scripting' tab, click "New Automation".

Then, select the event you want the script to be triggered by, in our example, we want the "Recording Stop". Finally, select the script itself in the "Run" popup.

Scripting Library Window

5.That's it! Next go make some recordings with Audio Hijack, and watch them be automatically processed by our Set Recording XAttrs script.


While that entails all the 'basic' steps of creating and hooking up a script in Audio Hijack, let's walk through it and see some of the finer details of how it works.

The basic purpose of the example script, is to add MacOS Metadata tags, to recording files, as those files are created. In particular, it adds a "Where From" URL, that is visible in the Finder's Get Info window. Although this is a rather contrived thing to do, it serves as good example of how to write "Recording Stop" scripts and how to hand files to external shell scripts.

The first notable part of the script is the "// #needsFile" comment, at the top. This tells Audio Hijack that this script is for the "Recorder Stop" event top, and to only show it as available there. It is entirely optional, and if you are writing a script for other event types (such as "Session Stop") should be omitted.

Next up, you'll see "filePath = event.file.filePath". The "event" object is a global object accessible to Automotion scripts. It contains context-specific information, and in this case, it contains a "file" object because we are a "Recording Stop" script. The file object has variable properties, but the one we care about here, is it's full path.

Now we move on to building a shell script command. Our final command, will look sometihng like: "xattr -w com.apple.metadata:kMDItemWhereFroms 'https://www.example.com/' '/path/to/recording.mp3' ". Of particular note here, is the shellArgEscape() function we define, because we must escape both the URL and the file path. If we don't, things like file paths with spaces in them will generate invalid shell commands, and the script will fail to run (or worse).

Finally, we execute the command with app.runShellCommand: "let [status, stdout, stderr] = app.runShellCommand( cmd );". Like the "event" variable, "app" is a global variable accesible to all scripts, with some helpful properties and methods defined on it.

The result of runShellCommand is an array of 3 items, the unix process result code, a string containing the process stdout output, and a string containing the process stderr output. In the example script we do nothing with them, but an actual script can certainly use them to check if execution was successful.