Working with Actions (Secondary Events) in OnTheAir Video 4.2 or later

!! IMPORTANT NOTES - read me

• This feature requires "Actions", which are only available in OnTheAir Video, not in OnTheAir Video Express.
• This article pertains to OnTheAir Video 4.2 or later, if you are using version 4.1 or earlier, check this article.

What are actions?

An Action in OnTheAir Video is a what is sometimes called "Secondary Event". The secondary event can be happening in OnTheAir Video itself, or outside of OnTheAir Video. This is what allows you to, for example:

• in OnTheAir Video:
  • Control a project of the Dynamic Graphics Overlay (Requires the DGO option): start/stop a ticker, lower third, clock. Or modify a text item, image or video link... etc... Read more...
  • Control a video router: change crosspoints on a Blackmagic-Design VideoHub or Ross router. 
  • Output a SCTE trigger (Requires the CC option): send a SCTE35 trigger an the SDI output. Read more...
• Outside of OnTheAir Video:
  • Control a project in OnTheAir CG Server: start/stop a ticker, lower third, clock. Or modify a text item, image or video link... etc... Read more...
  • Change the status of the outputs of GPICommander
  • Start/stop recording in MovieRecorder
  • And many more things. As an action is an AppleScript, you can basically control any application that is AppleScriptable... even send an email for example.

Adding actions 

To add an action, select a clip in your playlist, then show the Inspector and select the "Timeline" pane. 

To add an action on a clip, first scrub in the preview above at the moment you want the action to be triggered and then click on the + icon. This will create something like this:

With the following info:

• The checkmark/cross: tells if there is a problem with the Action. If you see a cross there, check the "possible errors" section below.
• Position: is the moment at which the action will be triggered. Make sure to check the "Relative to" column. The "Relative positions" are explained below.
• Actions/Parameter: There you will select the action that you want to do, and its parameters. See below for the different types of actions.

Relative positions 

An Action can be triggered at any moment of a video file. You can then select wether you want that the position value shown is "relative to":

• Before Start: This happens when clips are chained and we prepare the next one. This allows to control video routers in a clean way. It usually happens 8 seconds before the next clip. If the clip is not playing in chain, but you force to start it (if you double-click, press play, etc...), we will wait for 1 second to receive the confirmation that the action was successfully performed. Typical usage: When controlling a video router, this allows for the switching action to be completed before we start playing a live (otherwise you would see a few flash frames at the beginning).
• Start: The position indicated is relative to the beginning of the clip, whatever in point is set. This is the kind of action that will never move depending on the in point. So it means that if your in point is after the action position, it won't be triggered. A Red Cross will show up in such cases. Typical usage: this type of position is used for lower third for example, where you want a lower third graphics element to be played at the exact position, whatever the in point of the clip may be.
• In Point: The position indicated is relative to the in point. This means that the action will move depending on the in point that you set. If no in point is set, the position will be relative to the start of the clip. Typical usage: this is used if you want an action to be triggered all the time at the beginning of the clip, or after 20 seconds for example, and this whatever the in point may be.
• Out Point: The position indicated is relative to the out point. This means that the action will move depending on the out point that you set. If no out point is set, the position will be relative to the end of the clip. Typical usage: this is used if you want an action to be triggered all the time at the end of the clip, or 20 seconds before the clip stops playing for example, and this whatever the out point may be.
• End: The position indicated is relative to the end of the clip, whatever out point is set. This is the kind of action that will never move depending on the out point. So it means that if your out point is before the action position, it won't be triggered. A Red Cross will show up in such cases. Typical usage: this type of position is used for lower third for example, where you want a lower third graphics element to be played at the exact position, whatever the out point of the clip may be.

Going To / Moving Actions 

When you select an action you can click on any of these 2 buttons:

• Go To Action Position: will move your playhead to where the action will be triggered.
• Move Action To Current Position: will change the position value to match the current position, and "relative to" setting. Note that you can also enter a TC value manually in the Position column.

Types of Actions

At the time of writing (but we'll add more over time), here are some of the ones that we support:

• ATEM:
  • Change the input used as program output, with or without transition (will do a TAKE or a CUT)
  • Start a macro
• AppleScript
  • Start an AppleScript (see below)
• GPI
  • Trigger a GPI output (Pulse, On or Off). Make sure to select the GPI to use in "Settings > Triggers > GPI Commander"
• Graphics
  • Start/Stop a project of the Dynamic Graphics Overlay option. Configure this in "Settings > Graphics"
• MIDI
  • Output a note or other to the MIDI device selected in "Settings > Triggers > MIDI"
• Playback
  • Performs playback actions, such as play next clip, stop playback, pause. 
• Routers
  • Control video routers from Ross Ultrix or Blackmagic-Design Videohub
• SCTE
  • Trigger SCTE-35 events on the output

Depending on the type of action you have selected, you will see different icons in your playlist:

Setting parameters

Once you have selected your action, you can edit its parameters. For each parameter, you will also see a "After Delay (ms)" option. This allows you to define a delay between the moment the action is triggered and when it is effectively triggered. This is useful if you have an action running at the start of a clip, but need to delay a little bit the action before it's actually done.

About AppleScript Actions

Before OnTheAir Video 4.2, the only actions available were AppleScripts. It is still possible to use these AppleScripts in OnTheAir Video 4.2 and they work the same way.

HOW to create the AppleScripts?

They must be formatted in a certain way. Basically all you have to do, is to add an "On Action" at the beginning, and "End Action" at the end of the script, so it would look like this (to play a DGO project in OnTheAir Video):

on action(Parameter)
    tell application "OnTheAir Video"
        tell project "LowerThird"
            play
        end tell
    end tell
end action

Note that the "Parameter" variable is what can be sent from OnTheAir Video. So you can write one script, and do different things depending on what you set in the "Parameter" field in the OnTheAir Video inspector.

We have sample AppleScripts that you can download, and you should start from there. Check the articles above which provide you some sample AppleScripts. Don't hesitate to contact us if you have questions. While we won't be able to write all the AppleScripts for you, we can give you some recommendations.

Where should I save these AppleScripts?

Actions should be placed in the following folder (if using OnTheAir Video): 

/Library/Application Support/Softron/OnTheAir Video/OnTheAir Video/Actions

If you are using the "multi" version of OnTheAir Video, there will be one folder per "channel":

/Library/Application Support/Softron/OnTheAir Video/OnTheAir Video 1/Actions
/Library/Application Support/Softron/OnTheAir Video/OnTheAir Video 2/Actions
....

About the AppleScript authorisation

When working with AppleScripts, and controlling other software, macOS sometimes requires you to authorise the script to control the software, for obvious security reasons. If you don't authorise it beforehand, macOS will show a warning the first time the script is executed. As this can cause issues during production, we have added a way to force the authorisation. 

For this, go in "OnTheAir Video > Preferences > Actions", you will see the list of Actions that you have saved in the Actions folder explained above. And a "Authorise" button next to it. What this will do is that it will execute the script, so you may want to be careful with this, and maybe have one "authorisation" script that will not actually do anything...

Possible errors or warnings

There are 2 possible errors or warnings on a clip:

• A Red Cross: means that the action will not be triggered. Either because for example an in point has been set and the action was before that in point, or there is another error such as an AppleScript file that is missing.
• A Yellow Arrow: means that the action will be triggered, although it was set just a little bit before the in or after the out point, but we have a tolerance that will force it to be triggered. This allows for an action to be triggered if it's just a few frames off for example.

When you see a Red Cross or the Yellow Arrow before an action, hover with your mouse on the warning, and you should see the explanation: