Creating custom scripts

1. Introduction#

Scripts allow you to automate tasks and extend workflows with your custom adjustments. Scripts are capable of editing metadata, trigger external processes outside Silverstack, and many more.

The following content will provide you guidance on how to create your first custom script and introduce you to the basic concepts of scripting in Silverstack. Related articles that you should be aware of, are the script editor, metadata adjustment scripts and post step scripts. There is also an in-depth technical documentation for developers and technical users available.

1.1 Script types and contexts#

You can append scripts to workflows at two different locations, either as part of the register step or as post step to any job. We also refer to these two locations as contexts. Both serve different purposes and the mandatory entry points differ, too. Therefore, it is important to be aware of the context you are working in. You can identify or change the context of a script by two characteristics:

• The script’s entry point / function
• The context tag

The function that acts as an script’s entry point, defines the available variables and how the script is executed, e.g. for each clip / asset (ingest) or per job (post step). The context tag allows you to choose where a script should be loaded. For example, if you wrote a script that should only be available in the register step, you can set the tags accordingly:

• For a single context: — sst: ingest
• For multiple contexts: — sst: ingest, post-step

The metadata adjustment scripts that can be applied in the register step, are meant mainly to add or adjust metadata for clips while ingesting them in the library.Ingest scripts must have a function called onStampVideo and additionally may have a function onStampAudiothat only applies to audio clips. If you only want to adjust metadata for audio clips, just keep the onStampVideo function empty.

Post step scripts can be appended to any activity in the workflow (besides the registration activity).Not only do they allow you to adjust metadata but they also give you the opportunity to trigger external processes after job execution, such as sending emails or accessing the file system trough running external scripts using os.execute. Generally speaking, they act as a custom plugin for your workflow and are much more versatile than the metadata adjustment scripts. You can identify these script types by the function onFinish and context tag post-step.

1.2 Storage locations#

Efficient workflows require both reproducibility and the use of preconfigured templates. That’s why Silverstack relies on a hierarchical storage system for its scripts:

• Default
• Project
• Shared

The default category contains scripts that are provided by Pomfort. You can use the scripts out of the box or as starting point to develop your own versions. The project location will be the main directory for you to work with since it’s meant to contain project-specific scripts that require reproducibility across time, e.g. to ensure that an archived project and its scripts still create the same output at a later point and cannot be altered accidentally. In contrast, the shared location can be accessed by all Silverstack projects and supports you maintaining consistent workflows across projects. Be aware that changes in the shared scripts will affect all projects.

2. Creating scripts#

In what follows, we will guide you through the process of creating a workflow with custom scripts. We assume that you are already familiar with the workflow process, otherwise we recommend to read the article on how to configure workflows. Let’s assume your task is to offload a camera card and you would like to add additional metadata during ingest and as soon as the offload is finished, you would like to create a mail draft as a confirmation of the successful offload that you can check before sending it.

2.1 Custom metadata adjustment script#

Click the Offload button to start the workflow configuration window with an offload workflow. In the “Register in Library” activity, click the + Add Lua Script button and navigate to Project > New…In the following save dialog, you can enter a name and click Save to create a new script. By default, the script is empty, so you need to click the Edit button to start editing the script in the script editor.It is possible to have the workflow configuration and script editor window open at the same time, so you can easily check your workflow’s settings while editing the script.Let’s start with adding the basic entry point function:

function onStampVideo(videoClip)end

To keep things simple, the script should set the clips’ location value to “Munich” (feel free to take any other value). You can look up any available function in the API reference file. To access it, navigate to the script editor’s toolbar, click the reference button and it will open the markdown reference file where you can search for “location”. You will find a getter and setter function that you can use for the script:

local location = videoClip:metadata():getLocation() if location == nil then videoClip:metadata():setLocation(“Munich”)end

Basically, the script is checking if the clips already have an existing location value and if that’s not the case, it will add the value “Munich” to the metadata field “Location”. In order to apply the changes to the script, click Cmd-S to save it.

2.2 Post step scripts#

In the next step, we show you how you can communicate with external applications such as macOS Mail. Select the backup activity and similarly to the previous step, click the + Add Post Step button to load the script “Create Email Draft.lua” from the default category. At this point, you can decide if you would like to adjust the script to match your desired email account or if you would like to continue with the example configuration. (in that case, skip the next paragraph).

To adjust the script, you can click the pink Edit button to open it in the script editor. Since a default script cannot be changed, you need to duplicate it into either the project or shared location. That can be achieved by selecting the appropriate script in the script browser on the left where you must right-click the script to open its context menu. Within the menu, you can click the duplicate option and select the desired storage location. In the resulting save dialog, you can enter a name for the duplicated script. Now, you may enter a new email address at the top section of the script and save it. Back in the workflow configuration window, you need to load your newly created script by deleting the old post step and creating new one for the new script. That’s it.

You are now ready to start the workflow. After the offload finishes, the application calls onFinish and the script first checks whether the job was successful – only then it continues. Next, it builds the email content (recipient, subject, and a short message) and optionally inserts a bit of context from the offload, such as the working path or the number of processed assets. The text is then encoded into a mailto: URL so it can be safely passed to macOS. Finally, the script uses the open command to hand that URL to the system, which opens a new draft in your default mail application for review and sending.

3. Help and troubleshooting#

All available functions of Silverstack’s API are placed in the global sst namespace. As a result, you can view the help with the following commands:

• Show help with sst.help()
• Show help for type “Folder” with sst.help(sst.Folder)

If you are looking for further (technical) details and help, we recommend checking the technical documentation on GitHub where you can also find latest updates for script examples.

Some functions can throw exceptions. You can identify these functions by the declaration throws at the end of the function, for example here: Metadata:setCameraIndex(String) throws

There is no need to handle these functions differently from others. If scripts throw an error, they will be passed to the associated instance and you will see an error message in the workflow configuration window, the jobs view or the script editor, depending on your current execution context. For metadata adjustment scripts, the validation runs immediately in-place and the workflow configuration window will show any error as soon as it occurs.