OnTheAir Video

The OnTheAir Video action controls Softron OnTheAir Video through its REST API.

Use it to:

• Start, stop, pause, and navigate playback
• Control individual playlists and clips
• Run OnTheAir Video Actions
• Control Dynamic Graphics Overlay projects
• Update CG text, images, movies, and audio
• Start, stop, or resynchronize the scheduler
• Send custom REST API requests

The action runs in the background and is available on iPhone, iPad, and Mac.

Warning: Playback commands are sent immediately. A phrase can start, stop, or alter the currently playing output without additional confirmation.

Requirements

You will need:

• Action Phrase Core or higher
• A Mac running Softron OnTheAir Video
• Network access between your Action Phrase device and the OnTheAir Video Mac
• The OnTheAir Video REST API running and accessible
• A REST API user with sufficient permissions, unless authorization has been bypassed in OnTheAir Video

Some commands require additional OnTheAir Video features:

• CG commands require the Dynamic Graphics Overlay option.
• Scheduler and Join in Progress commands may require the appropriate traffic or scheduling options.
• Run OnTheAir Action requires an Action already configured in OnTheAir Video.

Available endpoints can vary between OnTheAir Video versions. The API documentation served by your copy of OnTheAir Video is the authoritative reference.

Enable and verify the REST API

On the Mac running OnTheAir Video:

1. Launch OnTheAir Video.
2. Open a browser.
3. Navigate to:

http://localhost:8081/api.html

If the page loads, the REST API is running. This page contains the API documentation for your installed version of OnTheAir Video.

For a remote device, replace localhost with the Mac's IP address or hostname:

http://192.168.1.50:8081/api.html

Softron uses the following default ports:

See Softron's REST API guide for more information.

Add the action

1. Create or edit a phrase in Action Phrase.
2. Add an action.
3. Select OnTheAir Video.
4. Enter the connection information for the OnTheAir Video Mac.
5. Configure authentication.
6. Leave Use Raw Request disabled.
7. Select a command.
8. Enter the parameters required by that command.
9. Save the phrase.

Connection settings

Enter a bare hostname or IP address when using the separate Port and Use HTTPS settings.

If Action Phrase and OnTheAir Video are running on the same Mac, you can use:

127.0.0.1

Do not use localhost or 127.0.0.1 from an iPhone, iPad, or a different Mac. On those devices, those addresses refer to the device itself.

Authentication

The action supports three authentication configurations.

Username and password

Enter the REST API user's Username and Password, and leave Access Token empty.

Before every command, Action Phrase sends an authorization request to:

PUT /authorize

OnTheAir Video returns a fresh token, which is added to the command as a token query parameter.

This is generally the most reliable option when tokens can expire or be replaced.

Access token

Enter an existing token in Access Token.

Action Phrase uses the token directly and does not send an authorization request before the command.

If an access token and username/password are all provided, the access token takes precedence.

No authentication

Leave the username, password, and access token empty only if authorization has been bypassed in OnTheAir Video.

Authorization settings and user permissions are managed in OnTheAir Video under its HTTP Server settings. Menu names may differ between versions.

Security: OnTheAir Video tokens are included in the request URL. Use HTTPS whenever requests travel over an untrusted network, and avoid exposing request URLs in logs.

HTTPS

OnTheAir Video supports HTTPS when a valid certificate is configured.

The certificate must be named:

tls_certificate.p12

For a standard OnTheAir Video installation, Softron documents the following location:

/Library/Application Support/Softron/OnTheAir Video/OnTheAir Video/Certificates/tls_certificate.p12

The certificate must be trusted by the device running Action Phrase. A self-signed certificate that is not trusted by the device can cause the connection to fail.

See Softron's HTTPS setup guide for complete instructions.

Test the connection

The OnTheAir Video action does not currently have a separate Test Connection button.

To verify the connection:

1. From the device running Action Phrase, open:

http://HOST:PORT/api.html

1. Confirm that the OnTheAir Video API page loads.
2. Configure a non-playout command such as Validate Playlist or Refresh Media Browser.
3. Trigger the phrase and confirm the result in OnTheAir Video.

Warning: Do not use Play, Stop, Skip, Delete, or scheduler commands for connection testing while the system is on air.

The action is designed to send control commands. It does not display the HTTP response or save response data into a variable.

Selecting playlists, clips, and CG items

Commands can target OnTheAir Video objects using the identifiers accepted by the endpoint.

Recent OnTheAir Video versions may also accept playlist names. Consult the api.html page served by your installed version.

Names containing spaces and other special characters are automatically URL-encoded.

Playback commands

These commands control the main OnTheAir Video playback state.

Playback position

The following commands can optionally start at a particular position:

• Play
• Playlist Play
• Clip Play

Three position formats are available:

Normally, only one position field should be provided. Leave all three empty to start at the normal playback position.

Playlist commands

All targeted playlist commands require Playlist Index or ID.

Warning: Delete Playlist Clips removes every clip from the selected playlist. Verify the playlist identifier before using this command.

Clip commands

Clip commands require:

• Playlist Index or ID
• Clip Index, Name, or ID

Warning: Delete Clip permanently removes the selected clip from the playlist.

Run an OnTheAir Video Action

Select Run OnTheAir Action to run an Action already configured in OnTheAir Video.

The Action must already exist on the target OnTheAir Video system, and the API user must have permission to run it.

Dynamic Graphics Overlay commands

Dynamic Graphics Overlay commands require the corresponding OnTheAir Video option.

Project commands

The supported range and meaning of Position depend on the OnTheAir Video version. Check the local api.html documentation.

CG item commands

These commands require:

• CG Project Index or ID
• CG Item Index or ID

File paths are interpreted by the Mac running OnTheAir Video. They must point to files or mounted volumes that are accessible from that Mac.

For example:

/Volumes/Graphics/Sponsor Logo.png

A file that exists only on the iPhone, iPad, or remote Action Phrase Mac cannot be loaded by OnTheAir Video.

Scheduler commands

The playlist path must be accessible from the OnTheAir Video Mac.

Warning: Starting, stopping, or resynchronizing the scheduler can affect automated playout immediately.

Media commands

Variables

Text and number parameters support Action Phrase variables using double braces:

{{variableName}}

For example, a CG text command could use:

Now Playing: {{programName}}

A clip identifier could use:

{{nextClip}}

Variables are resolved when the phrase runs.

Variables can also be used in raw paths and raw JSON bodies. The command and HTTP method selectors themselves cannot be replaced with template variables.

Raw REST requests

Enable Use Raw Request to call an endpoint that is not included in the built-in command list.

The following methods are supported:

• GET
• POST
• PUT
• PATCH
• DELETE

Configure:

Relative path example

/playback/current_item

The path is combined with the configured host, port, and protocol.

Dynamic Graphics Overlay example

Method:

PUT

Raw Path:

/playback/cg_projects/{{projectId}}/items/{{itemId}}

Raw JSON Body:

{
  "text": "{{lowerThirdText}}"
}

For POST, PUT, and PATCH requests, Action Phrase automatically sets:

Content-Type: application/json

Request bodies are not sent with GET or DELETE requests.

If authentication is configured, the token is automatically appended to the request URL. If the raw path already includes a token query parameter, Action Phrase preserves that token instead of adding a second one.

Security: A complete URL in Raw Path overrides the configured host. Because the access token may be appended to that URL, use complete URLs only for trusted OnTheAir Video servers.

Raw requests can call read endpoints, but the response body is not exposed as an Action Phrase variable.

Troubleshooting

The API documentation page does not load

Confirm that:

• OnTheAir Video is running.
• The host and port are correct.
• The HTTP server is enabled.
• The Mac's firewall permits incoming connections.
• Both devices are on networks that can communicate.
• You are not using localhost from a different device.

The phrase runs, but nothing happens

Check that:

• A command has been selected.
• Every required parameter has a value.
• The playlist, clip, project, or item identifier is correct.
• The API user has permission to execute the command.
• The installed OnTheAir Video version supports the endpoint.
• Authentication succeeded.

If a required field is empty, Action Phrase does not send the request.

The request is unauthorized

Verify the username, password, and user permissions in OnTheAir Video.

If using a pasted access token, obtain a fresh token and try again. A newer authorization may have replaced or invalidated the previous token.

If OnTheAir Video is configured to bypass authorization, leave all authentication fields empty.

An endpoint returns “Not Found”

API endpoints can change between OnTheAir Video versions. Open:

http://HOST:PORT/api.html

Compare the raw path with the documentation served by the installed application.

Softron recommends checking API compatibility when different OnTheAir Video versions are involved. See the OnTheAir Video release notes.

HTTPS does not connect

Confirm that:

• HTTPS is enabled in OnTheAir Video.
• The certificate is valid and has not expired.
• The certificate hostname matches the configured host.
• The certificate is trusted by the Action Phrase device.
• The HTTPS port is correct.

CG commands do not change the output

Confirm that:

• The Dynamic Graphics Overlay option is enabled.
• The CG project is open.
• The project and item identifiers are correct.
• The target item supports the value being changed.
• Referenced media files are accessible from the OnTheAir Video Mac.

A raw JSON body is ignored

Request bodies are only sent with POST, PUT, and PATCH. They are omitted from GET and DELETE requests.

Also confirm that the JSON is valid and that its property names match the API documentation for the installed OnTheAir Video version.