Support → Audio Hijack

A complete scripting API reference for Audio Hijack

← Return to Audio Hijack’s scripting center

Notes About Scripting

Execution Environment

All Scripts in Audio Hijack are run on MacOS's built in JavaScript engine, the same one as used by Safari. Furthermore, all scripts are executed on the main thread, such that long loops or slow operations may block the user interface.

Audio Hijack provides two global objects, app and console, which provide services as documented in the API reference. As well, scripts executing in response to Session Events, have a third globally accessible event object that provides context-specific information.

Executing External Programs

Audio Hijack provides two methods to interface with external programs, app.runShortcut() and app.runShellCommand().

Note that both of these methods will block the main thread of Audio Hijack, so take appropriate measures if invoking slow or long-running processes.

As well, be aware of properly escaping strings when using runShellCommand(), things like file names with spaces will need escaping.

API Reference

#!/usr/local/bin/php

app #

Properties

recordings #

array of recordings, for all Sessions

runningSessions #

array of running sessions

sessions #

array of all sessions

Methods

sessionWithName(name) #

find a session by name

showSessionsWindow() #

show the Sessions window

stopAllSessions() #

stops all sessions

bringToFront() #

bring Audio Hijack to the front, above other apps

quit() #

quit Audio Hijack

runShellCommand(command) #

run a shell script (blocks main thread), returns (result code, stdout, stderr)

shellEscapeArgument(text) #

returns text in a suitable format for passing to runShellCommand

runShortcut(shortcutName, text) #

run a shortcut in Shortcuts.app with text as input

---

console #

Properties

Methods

log(message) #

write message to the log. All messages will appear in Console.app.

error(message) #

write error message to the log. All error messages will appear in Console.app.

dialog(message) #

display an alert dialog, and write to log

clear() #

clear the log

---

event #

Properties

eventType #

string containing the type of event that occurred

the event types may be:
-fileDidEnd,
-sessionWillStart,
-sessionDidStop,
-sessionDidIdle,
-timerWillStart,
-timerDidStop,
-runScriptShortcut,
-runScriptTextShortcut,
-runNow

session #

for session events, contains the session object

file #

for fileDidEnd event, contains file object

Methods

---

session #

Properties

name #

session name, settable

blocks #

array of all blocks

recordings #

array of recordings made by this session

running #

session running boolean, settable

runTime #

session running time, in seconds

windowShown #

boolean, settable, show or hide the session's window

Methods

start() #

starts session

stop() #

stops session

blockWithName() #

Find a block by name. The name must match the name shown on the block, including case. The first matching block found is returned. Setting your own name on a block, by editing the popover title, is a good idea to match specific blocks accurately. Some blocks, by default, show a different name in their popover title - only the name shown on the block will match.

showWindow() #

show the session's window

quitApplicationSources() #

quits any apps set within Application blocks

---

file #

Properties

fileName #

name of the file

filePath #

full path to the file

isPlaying #

is playing

creationDate #

creation date

modificationDate #

modification date

displayDate #

displayable date

displayName #

displayable name

displayTime #

displayable duration

fileSize #

file size, in bytes

fileTime #

duration, in seconds

briefDescription #

brief description

fullDescription #

full description

tags #

A dictionary of tags in the recording

The dictionary will contain all of the tags set on this Recording. Tags that haven't been set are omitted.
The available Tag keys are:
-"album"
-"artist"
-"title"
-"comment"
-"genre"
-"albumArtist"
-"year"
-"track"
-"trackCount"
-"disc"
-"discCount"

Methods

startPlaying() #

Start Playing

stopPlaying() #

Stop Playing

pausePlaying() #

Pause Playing

togglePlayPaused() #

Toggle between Playing or Paused

showInInspector() #

show in Inspector

addToMusic() #

add to Music.app (or iTunes.app)

openInEditor() #

open in audio editor

openInApp(path) #

open using the application at path

revealInFinder() #

reveal in Finder

removeFromList() #

remove from Recording list

sendToTrash() #

move to the Trash

renameFile(newName) #

rename the file

The correct file extension is added automatically, it does not need to be provided.
If a file with the new name already exists, a number will be appended.

moveFile(newPath) #

move the file to a new location

- If the path is to a folder, the file will be moved to the new folder keeping its current name.
- If the path includes a file name, the new name will be used.
- If a file already exists at the new path, a number will be appended.
- A file extension correct for the recording will be added if it isn't provided.

updateTags(tagsDictionary) #

Update tags saved into the recording

Any tags provided in the dictionary will be saved to the recorded file. Existing tags are unchanged unless they are being replaced. Numerical fields expect a number or a string that will convert to a number. The file’s ‘tags’ dictionary is also a valid dictionary for calling updateTags().
The dictionary keys for tags are:
- "album"
- "artist"
- "title"
- "comment"
- "genre"
- "albumArtist"
- "year"
- "track"
- "trackCount"
- "disc"
- "discCount"

---

block #

Properties

name #

name of block, settable

type #

string indicating the type of the block

disabled #

boolean, settable, enable or disable block

Methods

---

recorder #

Properties

fileName #

file name, settable, can include %tokens

folderPath #

path to recording folder, settable

fileTime #

duration of current recording

tags #

A dictionary of the tags that are set in the recorder block

Methods

updateTags(tagsDictionary) #

set the tags that will be used for the next recording. Tags can include %tokens to be subsituted. Any changes won't apply to a recording that is already in progress. You can update tags directly to finished files instead

Any tags provided in the dictionary will be saved to the recorded file. Existing tags are unchanged unless they are being replaced. Numerical fields expect a number or a string that will convert to a number. The file’s ‘tags’ dictionary is also a valid dictionary for calling updateTags().
The dictionary keys for tags are:
- "album"
- "artist"
- "title"
- "comment"
- "genre"
- "albumArtist"
- "year"
- "track"
- "trackCount"
- "disc"
- "discCount"

---

switch #

Properties

switchPosition #

value "A" or "B", settable

Methods

switchToA() #

switch to A

switchToB() #

switch to B

---

← Return to Audio Hijack’s scripting center