Scripting

OffShoot is built with extensibility in mind. Trigger your custom scripts on specific events in OffShoot, and you can run custom processes, other apps or integrate OffShoot into an existing workflow.

Getting started

OffShoot's Scripting feature on macOS accepts only AppleScript. It is of course possible to run other scripts written in other languages by using an intermediate script.

On Windows? Check the Scripting on Windows section.

Scripting is a powerful tool. Easy to learn, but even easier to screw up. Always test your script with disposable data, and then test again. And again.

OffShoot does not offer support or assume responsibility for problems with or due to examples or any other script.

If you’re new to scripting, find someone to help you out, or use the example scripts available here. Remember: you are solely responsible.

OffShoot defines 7 events:

  1. Checkpoint Issue

  2. DiskAdded

  3. DiskBusy

  4. DiskIdle

  5. DisksIdle

  6. DiskRemoved

  7. FileCopyCompleted

  8. OffShoot Started

Each event has its own set of unique parameters that you can use. To be able to use a parameter, you must first declare it, at the top of your script:

set theFolder to "{FileCopyCompleted_destinationPath}"

Want to check if you declared a parameter correctly? Return the value first, in one of three ways:

  • return theFolder to output into the Event Log

  • display alert "theFolder = " & theFolder

  • display notification with title "theFolder =" subtitle theFolder

When you download a script from this site or other sources, unpack the zip. Then open OffShoot, go to Preferences > Scripts, and select the event you want to add a script to. Click the Browse... button and find your script. From now on, OffShoot will attempt to run this script every time this event occurs.

If for some reason, the script no longer exists in the original location, OffShoot will not warn you about it.

Scripting on Windows

AppleScript is not possible on Windows, but Python is.

On Hedge 22.2.5 or older? Add a script via a Registry key: Computer\HKEY_CURRENT_USER\Software\Hedge

Key

Value

EventScriptDiskAdded

path to the script file

EventScriptDiskRemoved

path to the script file

EventScriptDiskBusy

path to the script file

EventScriptDiskIdle

path to the script file

EventScriptAllDisksIdle

path to the script file

EventScriptFileCopyCompleted

path to the script file

EventScriptCheckpointIssue

path to the script file

When your script does not get fired, check the hedge.log file for clues. The most common issue is that a script launcher is not found: ERROR Utilities.Python.PythonHelper - Required PyLauncher for running python scripts was not found in the registry at location 'HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Python\PyLauncher'

Example python script

import json
import argparse

# get arguments
parser = argparse.ArgumentParser()
parser.add_argument("jsonString", nargs='?', default="This script should be used with OffShoot, see: https://docs.hedge.video/hedge/features/automation/scripts")
args = parser.parse_args()

jsonString = str(args.jsonString.replace("\\\\", "/")) # normalize \\ paths to / 
jsonString = jsonString.replace("\\", "/")  # normalize \ paths to /

logFilePath = "C:\\temp\\log.txt"
f = open(logFilePath, "w")
f.write(jsonString)
f.close()

# initialize JSON object to do some interesting stuff
jsonObject = json.loads(jsonString)

Good to know

  • Timestamps are shown as YYYYMMDDHHMMSS.

  • Duration is in seconds, with six-digit precision.

  • Size is in bytes. To convert bytes to GBs, divide by 1024^3.

  • Script Events are logged in OffShoot's Event Log.

Last updated