TCP/IP & XML Exchange Protocol for communication with just:connect (2.0 and later) and just:in (2.0 and later)

Copyright © 2017 ToolsOnAir Broadcast Engineering GmbH.

This document is intended for 3rd party developers who may wish to integrate with ToolsOnAir’s Broadcast Suite and details the TCP/IP & XML protocol used by just:connect and just:in to exchange information. For example, in just:connect’s case a 3rd-party application can send and receive information about the schedule that is then sent on to just:out for playout. For just:in the 3rd-party application can control crash (immediate) recording, select presets and send a batch list for recording, and receive video and audio previews that can be displayed in a user interface if required. Note that this format is not that used directly by just:out and thus does not enable developers to integrate directly with just:out, bypassing just:connect. Direct communication with just:out is not currently supported by ToolsOnAir. As such, any 3rd party developer integrating with just:out will also require just:connect running on the network. For just:in there is no equivalent of just:connect, so the 3rd-party application does communicate directly with just:in.

This document is intended for developers familiar with the concepts of TCP/IP and XML, and with just:play, just:live, just:connect and/or just:in and just:in multi. It is recommended that developers first install those applications relevant to the proposed integration, read the relevant user manuals and familiarize themselves with the concepts and features of Broadcast Suite before reading this document.

There are several applications in Broadcast Suite and then can be broadly split into two classes of application:

• Engines are generally faceless applications (although they do have minimal interfaces containing status and diagnostic information) that are the workhorses of Broadcast Suite - they do the heavy lifting of playing out and ingesting video and audio.

• User Interfaces are the “windows” onto the engines allowing the user to controls the engine or engines running on the network. The communication between the engines and the user interfaces is network-based, meaning that the engine and the user interface must not be running on the same system - indeed, ToolsOnAir recommends generally that they do not run on the same system.

• just:out is the engine responsible for compositing video and graphics and sending the resulting frames to a video output card (e.g. AJA or BMD) that will then output an SDI signal.

• just:in is the engine responsible for ingesting one or more SDI signals attached to an input card or cards (e.g. AJA, BMD, Matrox) and writing these signals into a movie container (currently either QuickTime MOV or MXF). The frames can be written uncompressed in either 8-bit or 10-bit, or compressed by a specific codec (e.g. ProRes). A single just:in engine can, depending on the hardware available on the system, support more than one channel, where a channel is a single SDI signal that can be written to a file. The engine supports crash, batch and scheduled recording as well as VTR (Sony 9-pin) control.

• just:connect is the schedule "server" or "database" that also acts as a gateway between just:out and any 3rd-party applications transmitting schedule information. The 3rd-party application sends requests to just:connect and receives acknowledgments back depending on whether or not the request was successful. The basic unit of organization in just:connect is the channel, and a single instance of just:connect can manage several channels. As such, a 3rd-party applications does not simply establish contact with just:connect, but rather a specific channel managed by just:connect. In turn just:connect will establish connections with the just:out engine or engines assigned to the channel and forward relevant schedule information to the engines. Also any communication received just:out that is relevant for the 3rd-party application will be forwarded on to the application. The 3rd-party application will never itself communicate with just:out. Indeed, such direct communication would be complex for a 3rd-party application to manage due to the fact that each track in a channel may in fact be rendered by a different instance of just:out, and also by a redundant just:out, thus a single channel may have ten separate just:out engines running and a 3rd-party application would have to establish connections with all of them and ensure that each only received the relevant schedule information. By communicating just with just:connect, all of this complexity is removed from the 3rd-party application.

• just:play is the user interface intended for 24/7 scheduled playout. It communicates with just:connect to retrieve schedule information, displays that information for the user and sends requests to just:connect based on the user's actions (e.g. create a new playlist, insert or delete an item in a playlist). As all communication is network-based it is not necessary for just:play and just:connect to be running on the same system, they must simply be on the same network. Additionally several instances of just:play may be viewing the same channel at the same time. Any changes made by one just:play will be instantly reflected on all other instances.

• just:live is the user interface intended for live playout where just:out reacts as quickly as possible to user commands - generally within a few frames. Apart from the reactivity, the interface itself is organized differently to account for the different demands placed on an operator in a live situation as opposed to a pre-defined, scheduled operation. Otherwise all of the features of just:play described above hold true for just:live.

• just:in multi is the interface intended for multi-channel ingest. It can control multiple channels coming from multiple instances of just:in on the network (e.g. two channels from one instance of just:in, two from another and a fifth channel from a 3rd instance of just:in). The user interface provides live feedback about the status of the channels (video and audio previews) and diagnostics about the systems on which the just:out engines are running (available memory, space on the storage systems and so on). The user can then start and stop recording, build and execute batch lists, control any connected video tape machines (VTR control) and view any pre-defined schedules due to be recorded.

A 3rd-party application integrating with Broadcast Suite can fall into one of two broad categories:

• As a complete replacement for one or more of the Broadcast Suite user interfaces (just:play, just:live and/or just:in multi). In this scenario it is likely that the 3rd-party application will itself provide a user interface and a means for the user to control the playout or ingest. Only just:connect and just:out (for playout) and/or just:in (for ingest) will be running on the network.

• As a faceless backend solution providing schedule information that the user will then view and potentially edit in just:play or just:live in addition to controlling the playout. Note that this strategy is only available for integration with just:connect. Due to the architecture of just:in, it is not possible to send information from a 3rd-party application to just:in that can then be viewed with the just:in multi user interface.

Any 3rd-party application has the same "status" in the Broadcast Suite as just:play, just:live or just:in multi. As outlined above, with just:play and just:live it is perfectly possible to have both the 3rd-party application and just:play / just:live running at the same time, connected to the same channel on just:connect. And just as with two instances of just:play or just:live editing the same channel, any 3rd-party application will receive full notification of any user actions in just:play or just:live, allowing it to stay fully synchronized. However, there are some additional requirements placed on a 3rd-party application in terms of the XML that it transmits if just:play or just:live are being used to view the schedule. Please refer to the sections on the “Schedule XML Format” for details of these requirements.

In either case it is highly recommended that a 3rd-party developer should first install Broadcast Suite (just:play, just:live and/or just:in) in order to familiarize themselves with the concepts and products described above. Further, just:play in particular can be a very useful tool to produce example schedule XML. For instance, if you want to see the schedule XML for a specific playlist it is possible to build the playlist in just:play and then export the playlist as a file which will then contain exactly the XML that just:connect would expect from a 3rd-party application wishing to create such a playlist. Please refer to the just:play user guide for full details on creating and exporting playlists.

Open

Once just:connect or just:in is started it will automatically broadcast a TCP service using Bonjour. External applications can use Bonjour services to discover the IP address and port used by just:connect or just:in, as follows:

There will also be a domain associated with the Bonjour service. In most cases this will simply be “.local”, but may be different depending on the specific network and DNS configuration. For example, a 3rd-party application wishing to connect to a specific just:connect channel should filter for Bonjour services with the type “_toaautomator._tcp.” and then check the service’s name against the wished-for channel name. As just:connect and just:in both support more than one channel simultaneously, it is possible that one instance of just:connect or just:in will broadcast several TCP services on the same IP address but with unique ports for each individual channel. Currently it is not possible to assign a channel a fixed port number so Bonjour is the only way to discover a channel's port. This may be addressed in a future release to allow integration with systems that do not support Bonjour directly such as Windows or Linux (although Bonjour services may also be available on these systems with additional software installed).

All communication between just:connect or just:in and 3rd-party applications uses plain UTF-8 encoded text. A zero byte is sent to indicate the end of a message. Most communication involves sending an XML document with a zero terminator at the end; however some basic commands are sent as simple text strings.

When connecting to just:connect or just:in an application will immediately receive the string "handshake" with a zero byte terminator. The application should immediately send back the same "handshake" string to complete the connection. Then the application should send three null-terminated strings to identify the application, as follows:

In addition to the handshake detailed above, applications connecting to just:connect must further identify themselves before the stream is fully available. To identify itself the application must send the following three null-terminated strings:

Notes:

• The “xxx” string following “host” should be the host name of the system running the application. For Mac OS X systems this should be the “Computer Name” defined in the “Sharing” System Preferences panel.

• The “ipv4” string should be followed by the standard format IPv4 address (e.g. 192.168.0.10) of the system running the application.

• The “yyy” string following “appID” should identify the application. This should normally be “just:play” for applications controlling a 24/7 unattended channel or “just:live” for applications controlling a live channel.

In addition to the handshake just:connect also requires a basic form of user authorization. Once the handshake is complete the 3rd-party application should send a string with the format "user xxx" where "xxx" is the name of the user wishing to connect to just:connect. The user name must be one of the names defined in the channel's list of users in just:connect. If the user is recognized by just:connect it will send back the string "authorized", after which just:connect is ready to receive commands from the application. If the user name isn't recognized just:connect will send the string "notAuthorized" and any further communication from the application will be ignored by just:connect.

Assuming that the user is recognized the sequence would be as follows:

If the user has a password set in just:connect, then just:connect will respond with “passwordRequired”. In this case the client must respond with the SHA1 digest of the user’s password. If the password matches then just:connect will respond with “authorized”, or if the password is incorrect with “notAuthorized”. The digest should be formatted as 20 hexadecimal bytes, as shown in the following code snippet:

The full sequence in this case would be:

As TCP/IP communication is socket based, terminating a session with just:connect is as simple as closing the underlying socket.

As opposed to just:connect, just:in engine does not have any user authorization. However, before using a channel the client must first lock it. A client can discover channels by sending the “requestChannel” message to just:in engine. From the list of available channels the client can then request locks on one or more channels by sending the “requestLock” message.

Please refer to the “Ingest communication protocol” section for a full description of these messages.

Both just:connect and just:in will send heartbeat messages to all connected client applications (including the 3rd-party application). A heartbeat message is a plaintext message with the prefix “heartbeat”, then a space character and then the current timecode in standard SMPTE timecode format (00:00:00:00). The client application can use this timecode to synchronize its internal time with the engine’s time and optionally display this information to the user (the current timecode and/or the mere fact that the engine is sending heartbeats to the client).

The schedule held by just:connect is defined by a tree-structure of nodes with different “classes” of node used to represent logical structure in the schedule. In addition to a class, or type, each node has a number of attributes or metadata. For each class of node there are some mandatory attributes and some optional attributes.

In XML, the schedule is represented by three tags:

• The <node> tag is the fundamental tag in the structure and defines a single node. A node can represent a day, a playlist, a track, an item to play out or a trigger to a stop frame on a Composition Builder or Quartz Composer graphic file.

• The <attribute> tag defines one attribute (or property or metadata) on a node.

• The <resource> tag defines a node’s resource, or media, such as a QuickTime movie or a Composition Builder or Quartz Composer graphic file.

Child nodes are represented by <node> tags nested in the parent's <node> tag. Each <node> tag can have any number of child <attribute> tags. This gives the following structure:

Each "node" tag contains nested <attribute> tags to define properties, <node> tags to define child nodes and, optionally, one <resource> tag to define the node's resource (movie file, Composition Builder or Quartz Composer file).

The node tag is used to define a node in the tree and has three required attributes:

The "id" attribute is a string that defines a unique identifier for the node. Every node defined in the schedule must have a completely unique ID identifying it. It is the responsibility of the 3rd-party application communicating with just:connect to assign and manage node IDs.

The "class" attribute is an integer that defines the class, or type of node being defined. The following values are defined:

The “flags” attribute is a bit-mask of the following values:

Thus a chained container node could be defined as follows:

In addition to the three required attributes described above, all "track" nodes (with class="3" or class="4") has a further required attribute:

The "trackId" attribute is a string that defines both the content of the track and its position in the render sequence. The format is a letter followed by a number. The letter "v" defines a video track while "g" defines a graphic track. The number is a zero-based index whereby tracks with lower values are rendered first, putting them at the "back" of the composited frame.

Under normal circumstances the following tracks are defined (in render order): "v0", "g0", "g1", "g2", "g3". This gives a single video track in the background with 4 graphic tracks rendered on top.

Thus a track node containing video play nodes to be rendered on the video track “v0” would be defined as:

The class attribute of “4” defines a video track, and the trackId of “v0” defines the actual logical video track.

Nodes of class “8” (real-time play) also have two additional attributes:

The “reference” attribute defines the ID of the play node that should be played out. This play node must have already been loaded into the real-time “workbench” or “contents” playlist.

The “trackId” defines the track on which the play node should be played out. Standard values are “v0” for the video track and “g0”, “g1”, “g2” and “g3” for the graphic tracks.

For example, in order to schedule the play node with the ID “RESOURCE” on the track “v0” the node would be defined as:

For full details on how play nodes are loaded, referenced and played out in a live situation please see the section on “Live Playout” later in this document.

Not to be confused with XML tag attributes, the <attribute> tag defines an attribute, or property for a node. As with the node tag the attribute tag has three required attributes in the following format:

The "key" attribute is a string that defines which of the node's properties is being defined. The values are described in detail later in this section.

The "type" attribute is an integer that defines what kind of property is being defined, one of the following values:

The individual attribute types are described in full detail later in this section.

The "flags" attribute is an integer bit-mask containing any of the following values:

In addition the flag bits 12-15 (0x00001000 to 0x0000F000) can be used to specify logical ordering of attributes when they are displayed by just:play or just:live. Attributes are sorted numerically according the values specified in these order bits, and then attributes with the same order bits are sorted alphabetically by name.

In addition to the required attributes the tag also has two optional attributes:

The "name" attribute defines a human-readable label for the attribute (as opposed to the "key" attribute" which may not be meaningful to the user).

The "category" attribute defines a category, or group, of attributes to which the attribute belongs.

Both this attributes are only relevant if the schedule will be presented to a user in just:play or just:live, and if the attribute in question is a custom attribute (not one of the standard attribute keys described later in this section). The "name" attribute will be used when displaying the attribute's value to the user and attributes of the same category will be grouped together in the user interface (a “group” in inspector). A 3rd-party application sending custom (non-standard) attribute keys where the user is expected to view the schedule in just:play or just:live should always transmit names and categories for such attributes. It is never required to send names or categories for any of the standard attribute keys described in this document as they are pre-defined within just:play and just:live. Equally, if the 3rd-party application has its own user interface and the schedules transmitted to just:connect will not be viewed or edited with just:play or just:live then the name and categories can be safely omitted.

For example, a string attribute used to set an input port on a Quartz Composer graphic with the port key “myInputKey” would be defined as:

Here the attribute’s key matches the input port’s key, the type is “0” for a string attribute and flags is “2” to indicate an input port attribute. If displayed in just:play or just:live the attribute will be in the “Input Port” inspector group with the label “Title” and a text entry field with the initial value “Hello World”.

The tag's text defines the attribute's string value, as in "Hello World" in the following example:

The tag's text defines the attribute's integer value, as in the value "1000" in the following example:

There are two possible formats for a double attribute. In the basic format the tag's text simply defines the attribute's double value, as in the value "3.14" in the following example:

However, it is also possible to define a minimum and/or maximum value for the attribute by defining <min> and/or <max> child tags. In this case the value itself is defined as the text of a <value> tag.

For example, to define the attribute with a value of "3.14" and a maximum value of "100.0" use the following:

To additionally define a minimum value of "0.0", use the following:

The tag's text defines the attribute's boolean value with "F" representing "false" or "no" and "T" representing "true" or "yes". The following example defines a "true" attribute:

Index attributes define an integer value from a range of values with optional names defined for each value that may be presented to the user in the form of a list to select from. There are two possible formats for this attribute. In the basic form the tag's text simple defines the attribute's integer value, as in the value "1" in the following example:

To define a list of values the following tags are defined:

Where the <string> tags define a list of names for the values (note that index attributes are always zero-based), the <max> tag's text defines the maximum value allowed and the <value> tag's text defines the currently selected value for the attribute. The following example defines an index attribute with the names "Zero", "One" and "Two" where "One" is currently selected:

Not supported in the current build of Broadcast Suite, please do not use.

Broadcast Suite allows arrays of either double or timecode values. The following example defines an array of 5 double values with the values [0.0, 1.0, 2.0, 3.0 and 4.0]:

The following example defines an array of timecode values with the values [00:10:00:00, 00:20:00:00 and 00:30:00:00]

Timecode attributes

The text of this attribute defines a time code and, optionally, a date. The basic time code only format uses the standard SMPTE "hh:mm:ss:ff" (hours, minutes, seconds and frames) format, as in the following example that defines a time code of 22:30, or 10:30 PM:

When a date is also included it must be in the format "dd.mm.yyyy" without any spaces and should precede the time code followed by a space, for example:

Additionally, it is valid to specify the timecode part as a simple integer, which in this case is the number of frames elapsed since midnight. For example, at 25 fps there are 90000 frames per hour (25 * 60 * 60), so in order to specify a timecode of 02:00 AM the correct value would be 180000 (90000 * 2 hours elapsed since midnight). For example:

Color attributes

The tag's text defines a color with RGBA components in one of two possible formats. The first format is in hexadecimal with a leading "#" character ("web" style). The second format defines the components as floating-point values between 0.0 and 1.0 separated by commas. In both cases the components are defined in the order red, green, blue and alpha. For example, both the following would define a red color with an alpha value of 1.0 (i.e. opaque):

All class 5 (Play) nodes must define a single <resource> tag to define the type of resource or media to be played out by the node.

The tag has a single “type” attribute to indicate the type of resource with the following values: