Support → Audio Hijack

Creating a script from start to finish

← Return to Audio Hijack’s 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:

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 its title. Type in an appropriate name: in our example, it’s “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 
   
   let url = 'https://www.example.com/';
   let filePath = '/Users/qdc/Desktop/tes t.txt';
   var cmd = 'xattr -w com.apple.metadata:kMDItemWhereFroms '
   
   cmd += app.shellEscapeArgument(url) + ' ';
   cmd += app.shellEscapeArgument(filePath) + ' ';
   
   let [status, stdout, stderr] = app.runShellCommand( cmd );
   

4. Connect your script to an event automation. Open the Session you desire to automate, click on the Scripting tab, and then click New Automation.

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

   

That’s it! Next go make some recordings with Audio Hijack, and watch them be automatically processed by our 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 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 very top. This tells Audio Hijack that this script is for the Recorder Stop event, and to only show it as available there. While it's optional, it's certainly recommended, but if you are writing a script for other event types (such as Session Stop) you should omit that line.

Next up, you’ll find the filePath = event.file.filePath line. The event object is a global object accessible to automation 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 its full path.

Now we move on to building a shell script command. Our final command will look something like this:

xattr -w com.apple.metadata:kMDItemWhereFroms 'https://www.example.com/' '/path/to/recording.mp3'

Of particular note here, is the shellArgEscape() function we define: the command arguments, both the URL and the file path, must be escaped. If we don’t do that, 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 accessible 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’s output, and a string containing the process stderr’s output. In the example script we do nothing with them, but an actual script can certainly use them to check if execution was successful.

← Return to Audio Hijack’s scripting center