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.
This feature requires an OffShoot Pro license.
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.
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.
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}"
Do you 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 Settings > Scripting, 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 located in C:\Users\<your-user-name>\AppData\Roaming\Hedge 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'
Try (Re)installing Python with the official installer and make sure to enable Use admin privileges.
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.
The Event Log logs all OffShoot events in one central spot. You can open the Event Log through the menu or with Command-Shift-L. It is persistent, limited to 1000 lines, and is first-in-first-out.
Fires when a new disk is added to your Mac. Everything that shows up as a disk in OffShoot, including virtual drives, network mounts, and disk images, triggers this event.
Fires when all disks become idle. When all file transfers have finished for instance.
28/09/2020, 14:08 - All Disks idle: {
}
Transfers Added
Fires when transfers are added.
Example
File Copy Completed
Fires when a single transfer completes.
This event fires for all transfer end states (Success, Failed, Warnings, Canceled, and Stopped). Make sure to check the FileCopyCompleted_state variable in your script.
Example
set FileCopyCompleted_state to "{FileCopyCompleted_state}"
if FileCopyCompleted_state is not "Success" then return false
Copying a source to two destinations will fire two separate File Copy Completed events, plus three Disk Idle events.
All set values are returned as Strings. In case of FileCopyCompleted_sourceInfo a JSON object is returned as a String. To use it in AppleScript, you can use the following code:
set FileCopyCompleted_sourceInfo to "{FileCopyCompleted_sourceInfo}"
set FileCopyCompleted_sourceInfoRecord to run script (do shell script ("echo " & FileCopyCompleted_sourceInfo's quoted form & " | sed -E 's/\"([^\"]+)\"[[:space:]]*:[[:space:]]*/|\\1|:/g' | tr -d '\\n\\r'"))
display alert |Location| of FileCopyCompleted_sourceInfoRecord
display alert |Counter| of FileCopyCompleted_sourceInfoRecord
display alert |Source Name| of FileCopyCompleted_sourceInfoRecord
