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.

Software and user guides described in this document are protected by Copyright.

No reproduction, distribution or use in whole or in part of any content is permitted without prior authorization of ToolsOnAir Broadcast Engineering GmbH.

Any use, for any purpose, not allowed in the terms of the license is strictly forbidden.

ToolsOnAir Broadcast Engineering GmbH uses reasonable efforts to include accurate, complete and current information in this document, however, ToolsOnAir Broadcast Engineering GmbH does not warrant that the content herein is accurate, complete, current, or free of technical or typographical errors. ToolsOnAir Broadcast Engineering GmbH reserves the right to make changes and updates to any information contained within this document without prior notice.

ToolsOnAir Broadcast Engineering GmbH shall not be responsible for any errors or omissions contained in this document, and in particular ToolsOnAir Broadcast Engineering GmbH shall not be liable for special, indirect, consequential, or incidental damages, or damages for lost profits, loss of revenue, or loss of use, arising out of or related to the information contained in this document, whether such damages arise in contract, negligence, tort, under statute, in equity, at law or otherwise.

Overview

Document and protocol scope

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.

The Broadcast Suite applications

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.

Engine applications

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.

User Interface applications

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.

Integration strategies

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.

Diagram showing communication routes between 3rd-party and Broadcast Suite applications

Dotted lines indicate optional communication routes.

Communication with Broadcast Suite

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:

Application	Bonjour Service	Bonjour Name
just:connect	_toaautomator._tcp.	The name of the channel as defined in just:connect (e.g. “My Channel”)
just:in	_toajustin._tcp.	The system host name of the machine on which just:in in running (e.g. “My-Mac-Pro”)

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:

Application	Direction	Data
just:connect / just:in	Sends	“handshake\0”
Application	Receives	“handshake\0”
Application	Sends	“handshake\0”

Application identification in just:connect

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:

Application	Direction	Data
Application	Sends	“host xxx\0”
Application	Sends	“ipv4 a.b.c.d\0”
Application	Sends	“appID yyy\0”

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.

User authorisation in just:connect

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:

Application	Direction	Data
Application	Sends	“user user_name\0”
just:connect	Receives	“user user_name\0”
just:connect	Sends	“authorized\0”
Application	Receives	“authorized\0”

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:

- (NSString *)sha1Digest
{
	unsigned int i;
	unsigned char digest[SHA_DIGEST_LENGTH];
	const char *string = [self UTF8String];
	SHA1((const unsigned char *)string, strlen(string), digest);
	NSMutableArray *array = [NSMutableArray array];
	for (i = 0; i < SHA_DIGEST_LENGTH; i++) {
		[array addObject:[NSString stringWithFormat:@"%02x", digest[i]]];
	}
	return [array componentsJoinedByString:@""];
}

The full sequence in this case would be:

Application	Direction	Data
Application	Sends	“user user_name\0”
just:connect	Receives	“user user_name\0”
just:connect	Sends	“passwordRequired"
Application	Receives	“passwordRequired”
Application	Sends	“password xxxxx” (SHA1 digest)
just:connect	Receives	"password xxxxx"
just:connect	Sends	“authorized\0”
Application	Receives	“authorized\0”

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

Channel locking in just:in engine

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.

Heartbeat 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).

Playout schedule XML format

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:

<node>
	<attribute>...</attribute>
	<attribute>...</attribute>
	<resource>...</resource>
	<node>
		<attribute>...</attribute>
		<attribute>...</attribute>
		...
	</node>
</node>

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

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:

Class	Name	Definition
0	Project	Reserved for internal use, do not use.
1	Day	Defines all of the playlists for a single day in the schedule.
2	Playlist	Defines a logical block of items to play.
3	Graphic Track	A graphic track can only contain play nodes with Composition Builder or Quartz Composer files. Several graphic tracks may be defined for a given channel, and they are rendered in the order specified in just:connect.
4	Video Track	A video track can only contain play nodes with QuickTime movie files. Currently just:connect and just:out only support a single video track per channel.
5	Play	Defines a single item to play in a playlist. Depending on the parent track type can define a Composition Builder file, Quartz Composer file or QuickTime movie file as its resource.
6	Trigger	Defines a “stop frame” trigger for a Composition Builder or Quartz Composer graphic. As such, this type of node should only be a child for a play node with a graphic resource.
7	Real-time Playlist / Folder	A special type of playlist or folder used to group nodes for “live” situations. See the section on “Live Playout” for more details.
8	Real-time Play	A special type of play node used for “live” situations See the section on “Live Playout” for more details.

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

Value	Definition
0x00000001	Node is chained (starts immediately after the previous node ends). Is relevant for playlist and play nodes.
0x00000008	Immediate play. The node should be played as soon as possible (the earliest frame available). Is relevant in “live” situations. See the section on “Live Playout” for more details.
0x00000010	Immediate cue. The node should be cued (the first frame of the node, without playing any further frames) as soon as possible (the earliest frame available). Is relevant in “live” situations. See the section on “Live Playout” for more details.

Thus a chained container node could be defined as follows:

<node id="1234" class="2" flags="1">...</node>

Note that if the value of "flags" is zero this attribute may be omitted in the XML as the default value of flags is zero.

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.

Note that the order in which the track nodes are defined in the schedule XML is irrelevant as just:connect uses the "trackId" attribute to send the track's contents to the just:out engine assigned to the track and the render order is defined by the channel itself, not the order that the tracks appear in the schedule.

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

<node id=”99” class=”4” trackId=”v0”>

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:

<node id=”REALTIME_PLAY” class=”8” reference=”RESOURCE” trackId=”v0”>

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.

The <attribute> tag

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:

<attribute key="xxx" type="y" flags="z">value</attribute>

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:

Value	Name	Definition
0	String	A single UTF-8 encoded string.
1	Integer	A 32-bit integer value.
2	Double	A double (floating point) value.
3	Bool	A true / false boolean value.
4	Index	An integer value from a list of possible values.
5	Dictionary	Reserved for future use, do not use.
6	Array	An array of double or timecode values.
7	Timecode	A timecode value, with or without date.
8	Color	An RGBA color value.

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:

Value	Name	Definition
0x00000001	Read only	The attribute will be displayed in just:play or just:live, but disabled so that the user cannot alter the value.
0x00000002	Input port	Set to indicate that the attribute represents an input port value for a Composition Builder or Quartz Composer graphic file. In this case the attribute’s key must match exactly the input port’s key as published in Composition Builder or Quartz Composer and the attribute’s type the input port’s expected data type.
0x00000004	Track Control	Set to indicate that the attribute represents an infinite graphic track control setting (whether or not an infinite graphic track is enabled or disabled while the node is playing out). In this case the attribute’s key should have the prefix “toaInfiniteTrack” with the track ID appended (e.g. “g0”, “g1” etc.) For example, assuming that the graphic track with the ID “g0” is defined in just:connect as being an infinite graphic track then an attribute with the key “toaInfiniteTrackg0” would specify whether or not the graphic on this track would be displayed or not. The attribute must be a Boolean attribute with “yes” or “true” specifying that the infinite graphic will be disabled and “no” or “false” that the infinite graphic will be enabled (this is also the default value if the attribute is omitted). This type of attribute is valid for class 2 (Playlist) and class 5 (Play) nodes.
0x00000008	Hidden	Set to indicate that the attribute should not be displayed by just:play or just:live for editing by the user.
0x00000010	Custom Interface Input Port	Used in combination with the “Input Port” flag to indicate that the input port in question is a port controlled by a “custom interface” within just:live (an HTML-based interface displayed in a separate window). Such attributes are not displayed by just:live in its inspector. Instead, a “Custom Interface” group is added to the inspector with a button that displays the custom interface when clicked by the user. Please refer to the just:live user guide for further details on custom interfaces.
0x00000020	Metadata	Set to indicate that the attribute is metadata for the node. This is simply a hint for just:play and just:live to display all metadata attributes together in a separate group.

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.

Note that if the value of "flags" is zero this attribute may be omitted in the XML as the default value of flags is zero.

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:

<attribute key=”myInputKey” type=”0” flags=”2” name=”Title” category=”Input Port”>Hello World</attribute>

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”.

String attributes

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

<attribute key="xxx" type="0">Hello World</attribute>

Integer attributes

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

<attribute key="xxx" type="1">1000</attribute>

Double attributes

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:

<attribute key="xxx" type="2">3.14</attribute>

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:

<attribute key="xxx" type="2"><max>100.0</max><value>3.14</value></attribute>

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

<attribute key="xxx" type="2"><min>0.0</min><max>100.0</max><value>3.14</value></attribute>

Note that the minimum and maximum values are optional and are only relevant if the schedule is to be presented to the user for further editing in, for example, just:play or just:live. In this case when the attribute is displayed in the inspector the user’s entry can be validated against the given range of values to ensure that invalid values are never sent to just:out.

Boolean attributes

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:

<attribute key="xxx" type="3">T</attribute>

Index attributes

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:

<attribute key="xxx" type="4">1</attribute>

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

<values>
	<string>Name for value 0</string>
	<string>Name for value 1</string>
	<string>Name for value 2</string>
</values>
<max>2</max>
<value>1</value>

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:

<attribute key="xxx" type="4">
	<values>
		<string>Zero</string>
		<string>One</string>
		<string>Two</string>
	</values>
	<max>2</max>
	<value>1</value>
</attribute>

Note that defining value names for an index attribute is optional and only relevant if the schedule is to be presented to the user for further editing in, for example, just:play or just:live. In this case when the attribute is displayed in the inspector a drop-down list is displayed from which the user can select the required value. Such a list with strings is obviously easier for the user than having to enter the correct number.

Dictionary attributes

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

Array attributes

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]:

<attribute key="xxx" type="6">
	<array>
		<double>0.0</double>
		<double>1.0</double>
		<double>2.0</double>
		<double>3.0</double>
		<double>4.0</double>
	</array>
</attribute>

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]

<attribute key="xxx" type="6">
	<array>
		<timecode>00:10:00:00</timecode>
		<timecode>00:20:00:00</timecode>
		<timecode>00:30:00:00</timecode>
	</array>
</attribute>

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:

<attribute key="xxx" type="7">22:30:00:00</attribute>

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:

<attribute key="xxx" type="7">1.4.2009 22:30:00:00</attribute>

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:

<attribute key="xxx" type="7">1.4.2009 180000</attribute>

Note that time codes are always assumed to be in the time zone "local" to the channel itself (i.e. the system time where just:out is running) and in the correct frame rate for the channel (i.e. 25 fps, 29.97 fps, 30 fps etc). Time codes are not further verified by just:connect or just:out, it is the responsibility of the sending application to verify that the time codes are correct.

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):

<attribute key="xxx" type="8">#ff0000ff</attribute>
<attribute key="xxx" type="8">1.0,0.0,0.0,1.0</attribute>

The <resource> tag

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:

Value	Type	Definition
0	QuickTime Movie	The text of the <resource> tag defines the name of movie file.
1	Composition Builder / Quartz Composer Graphic	The text of the <resource> tag defines the name of the Quartz Composer or Composition Builder file.
2	Live Input	Defines that the live SDI input signal should be displayed. Note that the output card must be correctly configured (e.g. the downstream keyer activated for an AJA card) and a valid SDI signal connected to the card’s input for this function to work correctly. The text of the <resource> tag is ignored in this case.
3	Image	A special form of Quartz Composer graphic, a still image “wrapped” in a pre-defined QTZ file. The text of the <resource> tag defines the name of the still image (JPEG, TIFF or PNG format).
4	Graphic Movie	A special form of Quartz Composer graphic, a QuickTime movie file “wrapped” in a pre-defined QTZ file and rendered on a graphic track instead of the video track. The text of the <resource> tag defines the name of movie file.
5	Gap	Intended to intentionally insert gaps into a video track if this is desired. Normally all video play nodes must be chained, and this excludes the possibility of gaps between movie files. Inserting a play node with a “gap” resource allows such a gap to be inserted between two play nodes with movie resources. The text of the <resource> tag is ignored in this case.
6	JavaScript Event	An event that when triggered will compile and execute the JavaScript fragment defined by the "toaEventScript" key on the node.
7	Graphic based on TOA graphic template	The text of the <resource> tag defines the name of the "TOA Graphic" template.
8	Graphic Movie based on TOA graphic template	A special form of a "TOA Graphic", a QuickTime movie file “wrapped” in a pre-defined TOA graphic file and rendered on a graphic track instead of the video track. The text of the <resource> tag defines the name of movie file.
9	Placeholder	A special "placeholder" node used to mark a place within a playlist that will be filled by a movie at a later date. If the placeholder is not replaced by a movie (resource type 0) before the node's start time, then nothing will be played out.
10	Audio	The text of the <resource> tag defines the name of audio file.
11	Workflow	The text of the <resource> tag defines the name of onCore workflow project file.

For example, to define a Quicktime resource with the filename "Hello.mov":

<resource type="0">Hello.mov</resource>

To define a Composition Builder resource with the filename "World.composition":

<resource type="1">World.composition</resource>

To switch to live input (i.e. the live SDI input attached to the AJA or BMD card's input):

<resource type="2"/>

Relative and absolute resource files and repository folders

just:out must be configured with one or more video repository folders and one or more graphic repository folders. As such, any files specified by <resource> tags can be relative to these folders. For example, the tag...

<resource type="0">Hello.mov</resource>

...will cause just:out to search each of the video repository folders until it finds a file with the name “Hello.mov”. Note that just:out will not search any sub-folders in the repository folders for the file. You can, however, specify folder names relative to any repository folder. For example, the tag...

<resource type="0">Folder/Hello.mov</resource>

...will cause just:out to search in all video repository folders for a sub-folder with the name “Folder” and, if found, for a file is this sub-folder with the name “Hello.mov”.

Note that if the file with the same name exists in multiple repository folders then just:out searches the repository folders in the order specified in the just:out System Preferences pane and will take the first file found.

For type 0 resources the video repository folder(s) will be searched by just:out, for type 1, 3 and 4 the graphic repository folder(s) will be searched.

It is also valid to specify an absolute filename with the “/” character at the start of the filename. For example:

<resource type="0">/Volumes/Video/Hello.mov</resource>

In this case just:out will ignore all repository folders and use the file specified.

Note that if the file does not exist, just:out will not search additionally in its repository folders. Regardless of relative or absolute, it is the responsibility of the 3rd-party application to ensure that all resources transmitted in the schedule are available to just:out at the scheduled playout time.

Attribute key names

The <attribute> tag's "key" attribute defines which of the node’s properties is defined by the attribute tag. Some attributes are required, others are optional, depending on the class of node. All of the valid attributes keys are defined below. The table headings for each attribute key have the following meanings:

Attribute Type	The type of data expected for the attribute, one of the types described in the preceding section (String, Integer, Double, Boolean, Array, Index, Timecode or Color).
Definition	Information about the purpose of the attribute.
Required For Node Class	Which classes of node require this attribute in order for just:connect and just:out to correctly process the node.
Optional For Node Class	Which classes of node may optionally use this attribute, but where the presence of the attribute is not critical for just:connect and just:out (for example, where there is a default setting, or where the attribute is only informational).
Required for UI	Some optional attributes are only then required when the user wishes to view and/or edit the schedule uses ToolsOnAir’s user interfaces (just:play or just:live). If the 3rd-party application integrating with Broadcast Suite also provides a user interface, then it may not be necessary to use just:play or just:live at all. In this case, any attributes marked as optional for a specific node class but also marked as required for UI can be completely omitted when sending schedules to just:connect. However, if the 3rd-party application is only a faceless backend product with no user interface and it is intended that the user should use just:play or just:live to view or edit the schedules then all attributes marked as required for UI must be sent by the application to just:connect. Failure to do so will result in unexpected behavior in just:play or just:live, up to and including software crashes. Note also that optional attributes that are marked as not required for UI will not be available for editing by the user in just:play or just:live if they are not specified by the 3rd-party application. Any attributes intended to be edited by the user in just:play or just:live must always be transmitted by the application even if they are optional and not specifically required for the UI.

“toaName” attribute

Attribute Type	String
Definition	Defines the name of the node. The name is informational only (for example, for display in just:play or just:live) and is not used directly by just:out.
Required For Node Class	None
Optional For Node Class	2 (Playlist), 5 (Play)
Required for UI	Yes

“toaStart” attribute

Attribute Type	Timecode (including date information)
Definition	Specifies when the node will start to play out.
Required For Node Class	1 (Day), 2 (Playlist), 5 (Play), 6 (Trigger)
Optional For Node Class	5 (Play)
Required for UI	Yes

Note that this attribute is specified as required and optional for node class 5 (Play). This is due to the difference between scheduled and live playout. The start timecode is required for all play nodes in scheduled playout, but should not be specified when transmitting a play node intended for live playout. Please refer to the section on “live playout” for further details.

“toaDuration” attribute

Attribute Type	Timecode (excluding date information)
Definition	Defines how long the node will be played out for.
Required For Node Class	2 (Playlist), 5 (Play), 6 (Trigger)
Optional For Node Class	None
Required for UI	Yes

“toaNaturalDuration” attribute

Attribute Type	Timecode (excluding date information)
Definition	Defines the “natural duration” of the node, or the original duration of the media specified for the node. For example, for a play node with a QuickTime movie as its resource, this would be the full length of the media in the movie file, for a Composition Builder graphic it is the length of the timeline as specified by the user. This information is required for a user interface where the user can alter the duration of the node by, for example, adjusting the in- and out-points of a movie. In this case the duration of the node specified by the “toaDuration” attribute may be shorter than the natural duration of the media. Therefore any interface editing such a node must know the natural duration to ensure that the duration doesn’t violate the media’s natural duration (a movie’s duration can never be longer than the natural duration, a Composition Builder or Quartz Composition graphic with stop frames can never have a duration shorter than the natural duration).
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	Yes

“toaInPoint” attribute

Attribute Type	Timecode (excluding date information)
Definition	Defines the in-point, or the starting frame within a QuickTime movie file.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	Yes

Optional for play nodes with QuickTime movie resources, invalid for all other resource types. If not specified, the movie will begin playing from the first frame in the file.

“toaOutPoint” attribute

Attribute Type	Timecode (excluding date information)
Definition	Defines the out-point, or the final frame within a QuickTime movie file to be played out. The duration is calculated as the out-point minus the in-point.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	Yes

Optional for play nodes with QuickTime movie resources, invalid for all other resource types. Note that just:play and just:live incorrectly treat the out-point as “exclusive” - in other words, the out-point specifies the first frame not to be played out instead of the last frame to be played out as in most video editing software.

“toaFadeIn” attribute

Attribute Type	Double
Definition	Defines how long, in seconds, the QuickTime movie file should fade in (either from black or from transparent over the live SDI input, depending of the value of the “toaTransparentFade” attribute). If not specified the default value is zero, meaning no fade in (instant cut from either the previous movie or live input).
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Optional for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaFadeOut” attribute

Attribute Type	Double
Definition	Defines how long, in seconds, the QuickTime movie file should fade out (either to black or to transparent over the live SDI input, depending of the value of the “toaTransparentFade” attribute). If not specified the default value is zero, meaning no fade out (instant cut to either the next movie or live input).
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Optional for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaAudioFade” attribute

Attribute Type	Boolean
Definition	Defines whether or not a QuickTime movie's audio should fade in and/or out with the movie's fade in/out settings (see “toaFadeIn” and “toaFadeOut” attributes). If omitted the default value of "false" or "no" meaning that the audio will not fade (will cut instantly in/out even if a movie fade in/out is specified). If the movie does not fade in or out (both the above attributes are omitted or have values of "0") then this attribute is also irrelevant.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Optional for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaInvertFields” attribute

Attribute Type	Boolean
Definition	Defines whether or not a QuickTime movie's interlaced fields should be inverted. This may in some rare cases be useful if a movie's field order is incompatible with the channel's settings (for example, playing a PAL DV formatted file on a standard PAL SD channel). If omitted the default value of "false" or "no" meaning that the fields will be left in the order in the QuickTime media. Obviously this attribute is also irrelevant for progressive display modes.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Optional for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaColor” attribute

Attribute Type	Color
Definition	Specifies the color used to draw the node in just:play and just:live. Colors may be usefully assigned by the 3rd-party application to indicate the contents or type of node. For example, playlist nodes might be assigned colors thematically (film, news, ad break etc.). There are no preset colors defined in Broadcast Suite, so the 3rd-party application may assign any color to any node. However, it is recommended that colors be tested within just:play or just:live to ensure that the results are readable (for example, certain colors may result in text overlays, such as the node’s name, being difficult for the user to read).
Required For Node Class	None
Optional For Node Class	2 (Playlist), 5 (Play)
Required for UI	Yes

“toaContainerType” attribute

Attribute Type	Index
Definition	Defines how a playlist is started. Valid values are: 0 for timed meaning that the playlist is started at the timecode specified by the “toaStart” attribute, even if this meaning that the preceding playlists are “clipped” or cut short by the playlist. The start time is “fixed” and will never be changed by just:connect, even when preceding playlists are changed. Note that this can lead to gaps between playlists, and it is the responsibility of the 3rd-party application to ensure that such gaps do not occur (unless this is desired). 1 for chained meaning that the timecode specified by the “toaStart” attribute is “floating” and can be automatically moved up or down by just:connect when the preceding playlists are changed. In this case the playlist always starts when the preceding playlist ends, so if the preceding playlist’s duration is shorted then this playlist’s start time will be moved up in the schedule, and inversely the start time will be moved down in the schedule when the preceding playlist’s duration is lengthened.
Required For Node Class	2 (Playlist)
Optional For Node Class	None
Required for UI	Yes

“toaContainerAutoDuration” attribute

Attribute Type	Boolean
Definition	Defines whether or not just:connect should automatically set the playlist’s duration to the exact duration of all movie play nodes on the playlist’s video track. If omitted, or if specified as “no” or “false”, then just:connect will always use the playlist duration specified by the “toaDuration” attribute. This can potentially lead to a playlist being “under” (i.e. too little video material resulting in a gap at the end of the playlist) or “over” (one or more of the movies will be either partially played out (“clipped”) or not played out at all (“skipped”). It is the responsibility of the 3rd-party application to ensure that playlists are not “under” or “over”, unless this is actually desired.
Required For Node Class	None
Optional For Node Class	2 (Playlist)
Required for UI	No

“toaContainerLoop” attribute

Attribute Type	Integer
Definition	Defines how many times a playlist will be looped. The total duration that a playlist is on air is then determined by the node’s duration as specified by the “toaDuration” attribute multiplied by this attribute. For a non-looped playlist it is however required to specify the attribute with a value of 1. Omitting this attribute will lead to the playlist not being played out at all.
Required For Node Class	2 (Playlist)
Optional For Node Class	None
Required for UI	Yes

“toaTrack” attribute

Attribute Type	String
Definition	The track ID (e.g. “v0”, “g0”. “g1” etc.) used by just:live when the node is loaded from the workbench to the timeline to specify on which track the node will run. The value should be valid for the resource type specified by the play node (i.e. “v0” for a movie, “g0”, “g1” etc. for any type of graphic resource). This attribute is not used by just:connect or just:out, so it can be safely omitted if just:live is not being used by the user to view the schedules.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	Yes

Only valid for class 5 (Play) nodes scheduled for live playout. Please refer to the section on “live playout” for further details.

“toaNextAction” attribute

Attribute Type	Index
Definition	Defines the action taken by just:out when the play node finishes playing out. The following values are defined: 0 = do nothing, or stop. Nothing further will be played out on the current node’s track until the 3rd-party application or just:live issues a play command. 1 = play next. Assuming that another play node is scheduled on the track on which the current node is playing, it will be immediately started (i.e. “chained” to the current play node). 2 = cue next. Assuming that another play node is scheduled on the track on which the current node is playing, its first frame will be cued on the track without actually playing the node. In order to actually play the next node the 3rd-party application or just:live must issue a play command. 3 = hold last. For a video clip, holds the final frame of the video indefinitely until a “next” command is issued, after which nothing will be played out (equivalent to the “stop” action). 4 = reload. The current play node is “reloaded” on the track, meaning that when the 3rd-party application or just:live issues a play command for the track the current node will play out again, instead of the next scheduled play node on the track. 5 = re-cue. Identical to the “reload” end action, but additionally the first frame of the play node’s media will be displayed on the track. 6 = hold and cue next. Identical to the “hold last” action, except that the last frame will only be held for the time specified by the “toaHoldTime” attribute, after which the next item on the track will automatically be cued. 7 = hold and play next. Identical to the “hold last” action, except that the last frame will only be held for the time specified by the “toaHoldTime” attribute, after which the next item on the track will automatically be played out. If omitted the default value of 0 (do nothing, stop) will be used by just:out.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Only valid for class 5 (Play) nodes scheduled for live playout. Please refer to the section on “live playout” for further details.

“toaTransparentFade” attribute

Attribute Type	Boolean
Definition	The “toaFadeIn” and “toaFadeOut” attributes can be used to specify that a movie is faded in from black or out to black. In a live situation with a live SDI signal attached to the video card and downstream keying enabled, it is possible to cross-fade a QuickTime movie from and to the live SDI signal by fading the QuickTime movie from fully transparent to fully opaque and then back again. This can be achieved by specifying this attribute with “yes” or “true”. If omitted, the default value of “no” or “false” will be used by just:out, meaning that if a fade is specified it will be from/to black. If no fade in or out is specified for the play node then this attribute is ignored by just:out.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Only valid for class 5 (Play) nodes scheduled for live playout. Optional for play nodes with QuickTime movie resources, invalid for all other resources types. Please refer to the section on “live playout” for further details.

“toaInterfaceMode” attribute

Attribute Type	Integer
Definition	Defines the default “interface” mode used by just:live when the folder is selected in just:live. Valid values are: 0 = list view. This is the standard workbench table where play nodes are displayed as a list with columns of data. 1 = grid view. This is the grid view where play nodes are displayed as a grid of large thumbnails. If omitted just:live will use the default value of 0 (list view) to display the folder’s contents.
Required For Node Class	None
Optional For Node Class	7 (Real-time Playlist / Folder)
Required for UI	No

“toaHasCustomInterface” attribute

Attribute Type	Boolean
Definition	Defines whether a play node has a “custom interface” associated with it. If specified as “yes” or “true” then just:live or just:play will display the custom interface automatically when the node starts playing out.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	Yes

Valid for class 5 (Play) nodes with a Composition Builder or Quartz Composer graphic file resource and a custom interface. Can be safely omitted by the 3rd-party application if there is no custom interface for the play node. Required for all play nodes with custom interface. Please refer to the just:live user guide for further details on custom interfaces.

“toaPlayLoop” attribute

Attribute Type	Boolean
Definition	Used in live playout to loop individual play nodes. When this attribute is specified with “yes” or “true” the play node will loop endlessly until it is removed from the schedule completely or a command such as “skip” is issued on the track on which the node is playing.
Required For Node Class	5 (Play)
Optional For Node Class	None
Required for UI	Yes

Only valid for class 5 (Play) nodes scheduled for live playout. Please refer to the section on “live playout” for further details.

“toaVolume” attribute

Attribute Type	Double
Definition	Specifies a value between 0.0 and 1.0 at which to play the node’s audio media. A value of 0.0 means that the node’s audio media is “mute” (not heard at all) while a value of 1.0 means that the node’s audio media is played at full volume (exactly as recorded in the media). The volume is scaled linearly, so a value of 0.5 means that the node’s audio media will be played at exactly half the normal volume. If omitted just:out will use the default value of 1.0 (full volume).
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Optional for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaLiveVolume” attribute

Attribute Type	Double
Definition	Specifies a value between 0.0 and 1.0 at which to play the live SDI input’s audio while the node is playing. In live playout just:out will normally play the audio from the live SDI input at full volume if no QuickTime movie is currently playing and then mute the live SDI input’s audio while a QuickTime movie is playing. However, under certain circumstances a user may wish to mix the live input audio with the QuickTime media’s audio, or even play out a movie file with its audio muted and keep the live SDI input’s audio playing. A value of 0.0 means that the live SDI input’s audio media is “mute” (not heard at all) while a value of 1.0 means that the live SDI input’s audio media is played at full volume. The volume is scaled linearly, so a value of 0.5 means that the live SDI input’s audio media will be played at exactly half the normal volume. If omitted just:out will use the default value of 0.0 (muted). Amongst others, the following combinations are possible: “toaVolume” at 1.0 and “toaLiveVolume” at 0.0. This is the default case meaning that only the audio from the movie will be heard at normal (full) volume. “toaVolume” at 0.0 and “toaLiveVolume” at 1.0. Here the QuickTime movie will be seen on the output signal, but with the audio from the live SDI input. The QuickTime movie’s audio will not be heard. “toaVolume” at 1.0 and “toaLiveVolume” at 0.5. Here the QuickTime movie will be seen and heard at normal (full) volume mixed with the audio from the live SDI input, but with the volume on the live SDI input reduced to 50%.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Only valid for class 5 (Play) nodes scheduled for live playout. Optional for play nodes with QuickTime movie resources, invalid for all other resources types. Please refer to the section on “live playout” for further details.

“toaScheduledDuration” attribute

Attribute Type	Timecode (excluding date information)
Definition	This attribute is never sent to just:connect, but may be sent back to the 3rd-party applications for class 5 (Play) nodes. When present for a play node this attribute indicates the original scheduled duration for the node as sent by the 3rd-party application, and it may differ from the actual duration specified by the “toaDuration” attribute, which will be the actual duration the node was on air. The 3rd-party application can use this attribute compared with the “toaDuration” attribute to check for nodes that were “under” (ended early) or “over” (on air longer than originally planned).
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

“toaStopFrames” attribute

Attribute Type	Double Array
Definition	This attribute must be sent for all class 5 (Play) nodes with Composition Builder or Quartz Composer graphic files that contain stop frames. The size of the array must equal the number of stop frames, and each entry in the array should be the original time in seconds of each stop frame relative to the graphic’s timeline in ascending order. This information can then be used by just:play when the duration of the play node is lengthened or shortened in order to recalculate the stop frame times. Note that this attribute is in addition to the class 6 (Trigger) nodes that the play node must also have (i.e. for each stop frame in a graphic the play node should have one trigger child node and one entry in this attribute’s array.
Required For Node Class	5 (Play)
Optional For Node Class	None
Required for UI	Yes

“toaStopFrameTime” attribute

Attribute Type	Timecode (excluding date information)
Definition	This attribute must be sent for all class 6 (Trigger) nodes, and there must be one such child node for each stop frame in a Composition Builder or Quartz Composer graphic files defined by a class 5 (Play) node. This attribute defines the time in seconds relative to the graphic file’s timeline at which the stop frame should be “triggered” or released. This time may be different to the time originally specified in the file if the play node’s duration has been lengthened, but it should never be earlier than the original value specified in the file as this may lead to unexpected results (e.g. a stop frame not being released at all). The stop frame’s original time is specified in the “toaStopFrames” attribute on the play node itself.
Required For Node Class	6 (Trigger)
Optional For Node Class	None
Required for UI	Yes

“toaStopFrameStartTimes” attribute

Attribute Type	Timecode Array (including date information)
Definition	When just:out is playing out a class 5 (Play) node that defines a Composition Builder or Quartz Composer graphic file with stop frames, each stop frame will be automatically “held” indefinitely until either the 3rd-party application or just:live issues a command to release the stop frame. Whenever a stop frame is reached and held, just:out will send a “stopFrameNode” message and just:connect will forward to all connected clients, including the 3rd-party application. It is the application’s responsibility to do two things: Maintain this attribute for the play node. For each “stopFrameNode” message received, the application should add the timecode sent from just:connect to this timecode array. The array should grow with each stop frame message sent, finally reaching a size equalling the number of stop frames in the graphic file when the final stop frame is released. Send a response back to just:connect updating the attribute for the node. Please refer to the “Communication Protocol” section for full details on the “stopFrameNode” message.
Required For Node Class	5 (Play)
Optional For Node Class	None
Required for UI	Yes

Only valid for class 5 (Play) nodes scheduled for live playout. Please refer to the section on “live playout” for further details.

“toaStopFrameEndTimes” attribute

Attribute Type	Timecode Array (including date information)
Definition	This is a sister attribute to the “toaStopFramesStartTimes” attribute. When just:out is playing out a class 5 (Play) node that defines a Composition Builder or Quartz Composer graphic file with stop frames, each stop frame will be automatically “held” indefinitely until either the 3rd-party application or just:live issues a command to release the stop frame. Once released, just:out will release the stop frame and just:connect will forward a “triggerNode” message to all connected clients, including the 3rd-party application. It is the application’s responsibility to do two things: Maintain this attribute for the play node. For each “triggerNode” message received, the application should add the timecode sent from just:connect to this timecode array. The array should grow with each stop frame message sent, finally reaching a size equalling the number of stop frames in the graphic file when the final stop frame is released. Send a response back to just:connect updating the attribute for the node. Please refer to the “Communication Protocol” section for full details on the “triggerNode” section.
Required For Node Class	5 (Play)
Optional For Node Class	None
Required for UI	Yes

Only valid for class 5 (Play) nodes scheduled for live playout. Please refer to the section on “live playout” for further details.

“toaInfiniteLength” attribute

Attribute Type	Boolean
Definition	The attribute can be used to flag a “live input” clip as “infinite”. Such a clip is given a scheduled duration, but the clip will be played out indefinitely (i.e. with an infinite duration) until the client application send an “unblockTime” message. When just:out receives such a message, it will release the “infinite live input” clip and immediately play out any following events (video and/or graphic clips), and just:connect will reschedule all playlists following the “infinite live input” clip to reflect the actual duration that the clip was on air relative to its original scheduled duration. Please refer to the section on the <resource> tag for details on scheduling a live input clip.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

“toaScheduledDuration” attribute

Attribute Type	Timecode
Definition	This timecode attribute can be used to indicate the original scheduled duration of a playlist item (e.g. movie), as opposed to the actual duration played out. For example, if the “jump to next clip” feature is used in just:play, the clip currently on air will have this attribute set with the original scheduled duration of the clip, and the “toaDuration” attribute will be shortened to the actual duration that the clip was on air. When this attribute is present it can be used to calculate the difference between the scheduled and actual on air duration for the playlist item, and the result can be displayed as useful information for the user, in this case how much time was “skipped” over in the current playlist.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

“toaSyncPoint” attribute

Attribute Type	Timecode
Definition	This timecode attribute can be used to mark a playlist with a “sync point”. The purpose of a sync point is to display to the user the difference between the actual currently scheduled starting time for the playlist (i.e. the “toaStart” attribute) and the “sync point” time. For example, a playlist may be scheduled to start at exactly 19:00:00:00, and also has a “sync point” attribute specifying 19:00:00:00. The user will then see that the playlist will begin exactly as scheduled by the sync point. However, if the playlist is a chained playlist and something changes in the preceding playlists (clips inserted or deleted) then the playlist’s start time as indicated by the “toaStart” attribute will change, but the sync point timecode will not. Thus the difference between the timecodes can be calculated and displayed to the user to indicate how much time difference there currently is between the sync point (desired start time for the playlist) and the time that the playlist will actually being playing. This gives the user the chance to further adjust the preceding playlists in order to reduce or eliminate the difference between the times and get the playlist back “on time” or “in sync” with the sync point.
Required For Node Class	None
Optional For Node Class	2 (Playlist)
Required for UI	No

“toaEventScript” attribute

Attribute Type	String
Definition	This string attribute contains a full script event in JavaScript that will be compiled and executed by just:out at the timecode specified by the item’s “toaStart” attribute. A JavaScript event may create and use instances of any of the ToolsOnAir plugins, such as those to control video routers, GPI switches, HTTP requests, sockets and so on. Full discussion of the plugins available and the possibilities offered by JavaScript events is beyond the scope of this document, please contact ToolsOnAir directly for more information on developing JavaScript events. Note that a play node with this attribute may also specify a <resource> tag with a reference (for example) to the original event script file, but that the script not be read from the referenced file but instead always compiled from the text specified by this attribute.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

“toaPlaybackSpeed” attribute

Attribute Type	Index
Definition	This optional attribute can be used to control the playback speed of a video in just:out, using the basic slow-motion feature (frames are duplicated, not blended or interpolated). The following values are valid when defining this attribute: 0 = 100% (normal playback speed) 1 = 75% 2 = 66% 3 = 50% 4 = 33% 5 = 25% Note that the item’s duration (“toaDuration” attribute) is not automatically adjusted for slow motion playback speeds, so when specifying this attribute the “toaDuration” should also be adjusted according to take account of the fact that the item will be playing out more slowly.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Optional for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaPlaybackDeinterlace” attribute

Attribute Type	Boolean
Definition	This attribute is used in combination with the “toaPlaybackSpeed” to indicate whether or not frames should be de-interlaced when playing back in slow-motion. The default value should this attribute be omitted is “NO” or false, meaning that frames will not be de-interlaced. When using the slow-motion feature it is strongly recommended that you test your material before going on air to see if de-interlacing is necessary or not in slow-motion.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Optional for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaCodec” attribute

Attribute Type	Integer
Definition	This attribute specifies the codec used to encode the item’s video media in the standard Quicktime “4CC” format (four ascii characters encoded into a 32-bit integer value).
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

“toaCodecString” attribute

Attribute Type	String
Definition	This attribute specifies the full name of the codec used to encode the item’s video media. Note that this attribute is purely informational for the user (for example will be displayed in just:play or just:live) but does not affect the item in any way when playing out.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Optional for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaAspectRatio” attribute

Attribute Type	Index
Definition	This attribute should always be specified for play items that reference Quicktime movies and specifies the aspect ratio of the video media. The following values are valid: 0 = Unknown aspect ratio (or not one of the following values) 1 = 4:3 aspect ratio 2 = 16:9 aspect ratio Note that the aspect ratio is not necessarily related to the encoded pixels, but rather the aspect ratio that the video media should be ultimately displayed in. For example, video may be encoded in 720x576 pixels (4:3) but actually displayed in 16:9 (1024x576).
Required For Node Class	5 (Play)
Optional For Node Class	None
Required for UI	No

Required for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaDisplayWidth” attribute

Attribute Type	Integer
Definition	This attribute specifies the width in pixels of the video media as it should ultimately be displayed to the user, i.e. taking the aspect ratio into account. For example, a video natively encoded with 720x1024 pixels but with the aspect ratio specified as 16:9 (“toaAspectRatio” attribute with a value of 2) should have this attribute specified as 1024 instead of 720.
Required For Node Class	5 (Play)
Optional For Node Class	None
Required for UI	No

Required for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaDisplayHeight” attribute

Attribute Type	Integer
Definition	This attribute specifies the width in pixels of the video media as it should ultimately be displayed to the user, i.e. taking the aspect ratio into account. In most cases this will only affect the width of the video as specified by the “toaDisplayWidth” attribute, but this attribute should also be included for completeness.
Required For Node Class	5 (Play)
Optional For Node Class	None
Required for UI	No

Required for play nodes with QuickTime movie resources, invalid for all other resources types.

“toa4to3in16to9Conversion” attribute

Attribute Type	Index
Definition	This attribute can be used to specify the aspect ratio conversion that should be applied to a vide clip that is specified as having a 4:3 aspect ratio (by the “toaAspectRatio”) when the engine output is set to a 16:9 aspect ratio. The following values are valid for this attribute: 0 = Full Frame. 1 = Pillar Box. 2 = Scale. 3 = V-Stretch. Note that this attribute is optional and if not specified then the default conversion specified in just:out’s preferences will be applied. By specifying this attribute the default conversion can be overridden on an item-by-item basis.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Required for play nodes with QuickTime movie resources in 4:3 format, invalid for all other resources types.

“toa4to3in4to3Conversion” attribute

Attribute Type	Index
Definition	This attribute can be used to specify the aspect ratio conversion that should be applied to a vide clip that is specified as having a 4:3 aspect ratio (by the “toaAspectRatio”) when the engine output is set to a 4:3 aspect ratio. The following values are valid for this attribute: 0 = Play 4:3. 1 = V-Stretch. 2 = Scale. 3 = V-Squeeze to Letterbox. 4 = H-Stretch. Note that this attribute is optional and if not specified then the default conversion specified in just:out’s preferences will be applied. By specifying this attribute the default conversion can be overridden on an item-by-item basis.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Required for play nodes with QuickTime movie resources in 4:3 format, invalid for all other resources types.

“toa16to9in4to3Conversion” attribute

Attribute Type	Index
Definition	This attribute can be used to specify the aspect ratio conversion that should be applied to a vide clip that is specified as having a 16:9 aspect ratio (by the “toaAspectRatio”) when the engine output is set to a 4:3 aspect ratio. The following values are valid for this attribute: 0 = Full Frame. 1 = Letterbox. 2 = Scale. 3 = H-Stretch. Note that this attribute is optional and if not specified then the default conversion specified in just:out’s preferences will be applied. By specifying this attribute the default conversion can be overridden on an item-by-item basis.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Required for play nodes with QuickTime movie resources in 4:3 format, invalid for all other resources types.

“toa16to9in16to9Conversion” attribute

Attribute Type	Index
Definition	This attribute can be used to specify the aspect ratio conversion that should be applied to a vide clip that is specified as having a 16:9 aspect ratio (by the “toaAspectRatio”) when the engine output is set to a 16:9 aspect ratio. The following values are valid for this attribute: 0 = Play 16:9. 1 = H-Stretch. 2 = Scale. 3 = H-Squeeze To Pillarbox. 4 = V-Stretch. Note that this attribute is optional and if not specified then the default conversion specified in just:out’s preferences will be applied. By specifying this attribute the default conversion can be overridden on an item-by-item basis.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Required for play nodes with QuickTime movie resources in 4:3 format, invalid for all other resources types.

“toaAllowResync” attribute

Attribute Type	Boolean
Definition	This optional attribute can be used to specify whether or not just:out may re-sync its master and reference timecodes when the playlist finishes playing out. (This assumes that just:out is configured when a reference timecode source such as LTC.) In this case, a number of frames may be either added at the end of the playlist (after the last movie item in the playlist) or a number of frames clipped from the end of the playlist, depending on whether the master timecode is ahead of or behind the reference timecode. Ideally, assuming that the playlists are relatively short and the drift between the master and reference timecodes small, there should therefore be not difference between the two timecodes after the end of each playlist. The default value if this attribute is not specified for a playlist is NO or false, meaning that the timecodes will not be synchronized by just:out even if there has been drift between the two while the playlist was on air.
Required For Node Class	None
Optional For Node Class	2 (Playlist)
Required for UI	No

“toaFieldOrder” attribute

Attribute Type	Index
Definition	This attribute specifies the field order of the video material as it was encoded. The following values are valid for this attribute: 0 = Upper Field. 1 = Lower Field. 2 = Progressive. Note that this attribute is purely informational for the user (for example will be displayed in just:play or just:live) but does not affect the item in any way when playing out.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Optional for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaFrameRate” attribute

Attribute Type	Index
Definition	This attribute specifies the frame rate of the video material as it was encoded. The following values are valid for this attribute: 0 = 23.98 FPS. 1 = 24 FPS. 2 = 25 FPS. 3 = 29.97 FPS. 4 = 30 FPS. 5 = 50 FPS. 6 = 59.94 FPS. 7 = 60 FPS. 8 = Unknown (other) frame rate. Note that this attribute is purely informational for the user (for example will be displayed in just:play or just:live) but does not affect the item in any way when playing out.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Required for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaHoldTime” attribute

Attribute Type	Timecode
Definition	This attribute should be specified when the “last action" specified by the “toaNextAction” attribute is either “Hold and cue next” or “Hold and play next”. In this case, this attribute specifies hold long the final frame from the video clip should be held on air for before the next item is automatically either cued or played out.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

Required for play nodes with QuickTime movie resources, invalid for all other resources types.

“toaContainerLocked” attribute

Attribute Type	Boolean
Definition	Specify YES to lock the playlist or NO (the default value if this attribute is omitted) to unlock the playlist. A locked playlist cannot be edited at all, meaning items cannot be added or deleted from the playlist, items within the playlist cannot be edited (e.g. in- or out-point changed, re-ordered), and functions such as split or merge playlists cannot be executed.
Required For Node Class	None
Optional For Node Class	2 (Playlist)
Required for UI	No

“toaTextColor” attribute

Attribute Type	Color
Definition	Specifies an optional color to use as the default color for the item when displaying it in the workbench and/or timeline. If not specified then the default text color will be used. This attribute can be useful for highlighting certain items, for example it is used in just:play to highlight missing files after refreshing a playlist.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

“toaAudioTracks” attribute

Attribute Type	Integer
Definition	Metadata specifying the number of audio tracks in the video item. This is informational only, and will be displayed in the user interface. Note if this attribute is not specified then the user will be informed that video has no audio, so it is recommended that this attribute is included for all video items that contain audio.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

“toaPaused” attribute

Attribute Type	Timecode
Definition	If the item has been paused (function only available for just:live channels), then this attribute specifies the timecode at which the item was paused. The timecode is relative to the "toaStart" attribute that specifies the timecode at which the item was started, so the difference between the two timecodes specifies the frame at which the item was paused. Once the item is started again, this attribute will be removed.
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

“toaPlayStatus” attribute

Attribute Type	Integer
Definition	For scheduled items in just:play, this attribute specifies the item's current playing status. The status is automatically updated by just:out and just:connect as an item is played out, and the status is reflected in just:play's user interface. Can be one of the following values: 0 = Pre-roll: The item is being pre-rolled in just:out's buffer and cannot be skipped or deleted at this stage. 1 = Cued: The item is on-air and cued on the first frame. 2 = Playing: The item is on-air and playing. 3 = Paused: The item is on-air and paused. 4 = Finished: The item was played out and has now finished. Note that if this attribute is not specified, then the item is assumed to be scheduled in the future (neither on-air or aired).
Required For Node Class	None
Optional For Node Class	5 (Play)
Required for UI	No

“toaAudioMapping” attribute

Attribute Type

Array (double values)

Definition

Optional audio mapping that can specify the mapping from the input audio channels in a file to the output audio channels. If specified, should be an array of double values with two values for each audio channel, split into 2 "sets" of values. The first "set" of values specify the audio mapping for available channels in the input, the second "set" of values specify the audio mapping for unavailable channels in the input.

For example, if you want to specify audio mappings for 2 channels, the array should have 4 values. The first 2 values in the array is the "available set" and the second 2 values is the "not available set". If you want to specify audio mappings for 4 channels, the array should have 8 values (two sets of 4 values), and so on.

Mappings are specified in output order, and the values are zero-based indexes from the input. In all cases, a negative value means "play nothing".

For example, a basic "stereo" mapping would be as follows (array values 0, 1, -1 -1):

Array index	Meaning	Value	Description
0	Output channel 0 mapping if input channel 0 is available	0	On output channel 0, play input channel 0 if available
1	Output channel 1 mapping if input channel 1 is available	1	On output channel 1, play input channel 1 if available
2	Output channel 0 mapping if input channel 0 is not available	-1	On output channel 0, play nothing if input channel 0 is not available
3	Output channel 1 mapping if input channel 1 is not available	-1	On output channel 1, play nothing if input channel 1 is not available

In this scenario, playing a mono input file would result in audio only on the first output channel (channel 0), because channel 1 is not available on the input, so the "not available" mapping is used and in this case it is -1 (play nothing). The following mapping would map a mono input to stereo (array values 0, 0, -1, -1):

Array index	Meaning	Value	Description
0	Output channel 0 mapping if input channel 0 is available	0	On output channel 0, play input channel 0 if available
1	Output channel 1 mapping if input channel 1 is available	0	On output channel 1, play input channel 0 if available
2	Output channel 0 mapping if input channel 0 is not available	-1	On output channel 0, play nothing if input channel 0 is not available
3	Output channel 1 mapping if input channel 1 is not available	-1	On output channel 1, play nothing if input channel 1 is not available

Here, on both output channels 0 and 1,channel 0 from the input will be selected (assuming it is available), so a mono input would be played on both outputs (assuming stereo output).

However, using this mapping an input with stereo would still be played out in "mono" (albeit on both outputs), because channel 1 on the input is not mapped to any of the outputs and will therefore never be played out. If you wanted to play a stereo file in stereo but still map a mono input to stereo on the output you can use the "input unavailable" values to achieve this (array values 0, 1, -1, 0):

Array index	Meaning	Value	Description
0	Output channel 0 mapping if input channel 0 is available	0	On output channel 0, play input channel 0 if available
1	Output channel 1 mapping if input channel 1 is available	1	On output channel 1, play input channel 1 if available
2	Output channel 0 mapping if input channel 0 is not available	-1	On output channel 0, play nothing if input channel 0 is not available
3	Output channel 1 mapping if input channel 1 is not available	0	On output channel 1, play input channel 0 if input channel 1 is not available

Here input channel 0 will be played on output channel 0, and input channel 1 on output channel 1 if available, otherwise input channel 0. So stereo input (channels 0 and 1 both available) would play out stereo on outputs 0 and 1, but in the case of a mono input (only channel 0 available), then the input channel 0 would be played on output channels 0 and 1.

Note that if this attribute is not specified, then the "standard" audio mapping is used that simply passes all input channels directly to the output channels.

Required For Node Class

None

Optional For Node Class

5 (Play)

Required for UI

No

24/7 scheduled & live playout

The are two basic modes of operation supported by just:connect and just:out:

24/7 scheduled playout

24/7 scheduled playout allows for items to be scheduled in advance, often up to several days and just:connect feeds each just:out engine with a rolling schedule for the next 1-2 hours. The media items in the schedule are loaded “just in time” by just:out and then automatically discarded once played out.

The basic node structure for a 24/7 schedule is as follows:

Day
- Playlist
  - Track
    - Play
      - Trigger
    - Play
    - Play
    - Play
  - Track
    - Play
    - Play

In other words, the schedule is split logically into days, each day is split into one or more playlists, each playlist has one or more tracks and each track has one or more play nodes. The play nodes define what is actually played (e.g. a video or a quartz graphic file) while the track nodes define in which order the play nodes are rendered by just:out. Playlist nodes and the play nodes that they contain always define their start times and durations, and are always stored in play order (playlists in order in which they are played during the day, play nodes in the order they are played in the playlist). Trigger nodes are used to define when triggers are sent to a Composition Builder or Quartz Composer graphic file to release (trigger) a stop frame.

Live playout

For live playout the node structure is fundamentally different than the 24/7 scheduled structure due to the very different requirements of the two scenarios. For live playout it is important that relatively few resources are pre-loaded and therefore available for instant playout, and that the user is free to jump around the rundown. Although a rough running order may be defined for a given event or show, the nature of live playout is much more fluid and free-form compared to 24/7 scheduled playout. Reflecting this, the node structure for live playout is as follows:

Real-time root playlist / folder
- Real-time contents playlist / folder
  - Real-time folder
    - Play
    - Play
  - Real-time folder
    - Play
    - Play
- Real-time schedule folder
  - Real-time play
  - Real-time play
  - Real-time play

The top levels of this structure are fixed: there is always a root class 7 (Real-time playlist / folder) that has two child real-time playlist / folder nodes. The first of these children is always the "contents" folder, the second the "schedule" folder. The "contents" folder must have at least one child real-time playlist / folder node, although it may have more than one. These are logical folders to allow the user to organize the contents or running order of the show, and these are the nodes that just:live displays as a list of folders. Each of these nodes can have one or more play nodes and these nodes represent resources or media (QuickTime movies, Composition Builder or Quartz Composer graphic files) that the user can then select for playout. Once such a play node is sent to just:connect it will be immediately sent to the appropriate just:out engine which will then pre-load the media so that it can be played out at any time within the minimum possible latency. In order to actually play out one of these nodes a reference to it is added to the "schedule" folder. Rather than a copy of the play node, this special real-time play node simply refers to the play node in the "contents" folder by it's ID and the track on which the node should be played out. As such, the "schedule" folder can also be seen as a running order. When a client application (just:live or a 3rd-party application) sends a command to play the next item on a given track, just:out will take the next available real-time play node assigned to the given track.

In order to play out a given media for live playout, a 3rd-party application must take the following steps:

Either take an existing real-time playlist / folder or create a new folder under the "contents" real-time folder node.
In this folder insert a new play node with the relevant resource type.
Insert a new real-time play node under the "schedule" real-time folder node that references the new play node's ID and places it on the desired track.
Send a message to play the next available item on the given track.

The actual XML required for these steps is detailed in the previous sections.

Please note that switching just:connect to the live playout mode is a “one-shot” process - it currently cannot be switched back to 24/7 playout without quitting and restarting just:connect. Therefore, if you are planning to mix 24/7 and live playout and want to avoid having to quit and restart just:connect on a regular basis, you will need to plan the architecture carefully.

Two possible workarounds for the problem are:

Have a single instance of just:connect running on the network with two channels defined: one for 24/7 playout and a second for live playout. The 3rd-party application must split the communication between the two channels. All 24/7 schedules are sent to the 24/7 channel and all live schedules to the live channel.
Similar to the above workaround, but with the two channels completely separated on two instances of just:connect.

In both cases, there will be at least two resulting SDI signals: one from the just:out assigned to the 24/7 scheduled playout channel and another from the just:out assigned to the live playout channel. These signals must then be sent to a mixer so that only the currently relevant signal is sent to broadcast.

Playout communication protocol

A previously described, the underlying communication protocol used by just:connect is TCP/IP. Specifically, a message is defined as a series of UTF-8 encoded characters terminated by a zero byte. Once a zero byte is detected in the incoming stream, just:connect will then interpret and act on the message. Equally, just:connect will send out messages to all connected client applications (including a 3rd-party application) in the same way, so any application must buffer bytes coming over the socket until a zero byte is detected, then interpret the buffered bytes as a UTF-8 string.

There are two basic classes of messages sent and received by just:connect:

Plain text: These are simple strings with a fixed prefix that may or may not include additional parameters. Any parameters follow the prefix “command” string and a space character.
XML: More complex messages tend to be sent as fully-formed XML documents. Such messages will always begin with the “<“ character (and no plain text message will have this character in the prefix), so any message with this as the first character can be parsed as XML.

In addition there are three broad types of message sent and received by just:connect:

24/7 Schedule: These messages relate specifically to 24/7 scheduled playout.
Live: These messages relate specifically to live playout.
General: These messages either do not relate specifically to 24/7 or live playout, or are equally valid for both.

Finally, some messages are sent by the 3rd-party application to just:connect while others are sent by just:connect to all connected applications. In either case, some messages require a response from the receiver while others do not. The following sections describe all of the messages including their class, type and response expected, if any.

“requestNode” message

Class	XML
Type	24/7 Schedule
Sent By	Client (just:play, 3rd-party application)
Definition	This message is sent by the client to request the class 1 (Day) node for a specific day in the schedule. It is the responsibility for just:connect to manage all day nodes and the responsibility of the client to manage the day’s contents. As such, a client must never send a day node directly to just:connect, but must request it instead. Once received the client application can use the day node’s ID to send requests to just:connect to insert playlists for the day, for example. The root tag has the “date” attribute to specify the date / timecode of the day being requested. This is in the timecode format described for timecode attributes (including date information). An example request for the day node for 1.1.2011 would be as follows: <requestNode date=”1.1.2011 00:00:00:00” />
Response	The response from just:connect is also XML as follows: <retRequestNode> <node class=”1” id=”xxx” > ... schedule XML nodes (playlists etc.) ... </node> </retRequestNode> The response is “deep”: all of the day node’s descendants (playlists, tracks, play nodes etc.) are included. As such, this message can be used to request the entire current schedule for a given day.

“requestInsert” message

Class	XML
Type	General
Sent By	Client (just:play, just:live, 3rd-party application)
Definition	This is a general-purpose node insertion message. It can be used to insert new nodes into the schedule, or move existing nodes within the schedule. The root tag has one required and three optional attributes: The “parentId” attribute is required and specifies the ID of the node under which the node being transmitted should be inserted (its parent node). The “beforeId” attribute optionally defines where in the parent node’s list of children the new node should be inserted. When specified, it must be the ID of one of the parent node’s children and the node will be inserted immediately before this node. When not specified the new node is simply appended to the parent (will be the last child node). The “exists” attribute is an optional boolean flag (“F” for false, “T” for true) to indicate whether the node already exists in the schedule and it therefore simply being moved in the schedule (“T”), or is new in the schedule (“F”). When omitted, the default value of “F” is used, meaning that the node is new. The “setStart” attribute is an optional boolean flag (“F” for false, “T” for true) to indicate whether the node’s start time should also be automatically calculated. If omitted the default value of false means that the start time will not be set and should therefore be included in the message. A value of true means that just:connect will attempt to calculate the best possible start time for the node. This may be useful when inserting a chained playlist into the schedule. Instead of having to calculate the correct start time for the playlist the 3rd-party application can simply set this attribute to true and let just:connect calculate the time based on the other playlists already in the schedule. The root tag should then contain at least one child <node> tag to specify the node or nodes to insert or move in the schedule (multiple nodes are simply represented by multiple child <node> tags). If the “exists” attribute is true to indicate that existing nodes are being moved, then each child <node> tag should simply have the “id” attribute set to indicate the node to be moved in the schedule. For example, the following message... <requestInsert parentId=”xxx” exists=”T” setStart=”T”> <node id=”yyy” /> </requestInsert> ...would move the existing node with the ID “yyy” to the parent node with the id “xxx”, and because the “beforeId” attribute is omitted from the message the node will be the last child node. The node’s start time will also be updated based on the new parent’s start time and its child nodes. If the “exists” attribute is false then the entire contents of the node (inclusive all attributes and descendant nodes) must be included in the message. For example, the following message... <requestInsert parentId=”xxx” beforeId=”yyy” setStart=”T”> <node class=”2” id=”zzz”> ...further XML schedule nodes (e.g. tracks, play nodes) </node> </requestInsert> ...will insert a new class 2 (Playlist) node with the ID “zzz” under the node with the ID “xxx” immediately before the child node with ID “yyy”. The node’s start time will also be updated based on the new parent’s start time and its child nodes. The playlist node should be fully specified in the message (tracks nodes, play nodes etc.).
Response	The response from just:connect is also XML as follows: <retRequestInsert> <node id=”xxx” ...> ... schedule XML nodes (playlists etc.) ... </node> </retRequestInsert> The response is “deep”: all of the day node’s descendants (playlists, tracks, play nodes etc.) are included. This may be useful in case just:connect has altered anything while inserting the node into the schedule. For example, if the <requestInsert> message specifies the “setStart” attribute as true, then the response will include the node’s “toaStart” attribute allowing the sender to read the start time assigned to the node by just:connect. The response will include one <node> tag under the root tag for each <node> tag sent in the original request.

“requestUpdate” message

Class	XML
Type	24/7 Schedule
Sent By	Client (just:play, 3rd-party application)
Definition	This message is sent by the client to completely update (replace) an existing node in the schedule with the node specified in the message. It is a potentially very powerful message, able even to completely replace a class 1 (Day) node, thus setting the entire schedule for a day with a single message. The root tag in this message does not define any attributes. It should have one or more child <node> tags, each of which defines the node to update / replace via the “id” attribute. All of the IDs specified in these <node> tags should already exist in the schedule. In addition, the “class” attributes specified for the <node> tags should also match the classes of the existing nodes in the schedule, otherwise the results will be undefined (e.g. replacing a class 1 (Day) node with a class 5 (Play) node would certainly lead to unexpected results). The following XML will replace the existing class 2 (Playlist) node with the ID “xxx” with the contents specified in the message: <requestUpdate> <node class=”2” id=”xxx”> ... schedule XML nodes (tracks, play nodes etc.) </node> </requestUpdate> It is important to note that when updating a class 1 (Day) node, just:connect will automatically assign new unique IDs to all descendent nodes (but not the day node itself). Therefore, the client sending this message must be careful to parse the response from just:connect in order to update any internal IDs with the new node IDs assigned by just:connect. Otherwise, future messages from the client relating to descendants of the day node will result in errors as the IDs would not be found in the schedule.
Response	The response from just:connect is also XML as follows: <retRequestUpdate> <node class=”2” id=”xxx” > ... schedule XML nodes (tracks, play nodes etc.) </node> </retRequestUpdate> The response is “deep”: all of the day node’s descendants (playlists, tracks, play nodes etc.) are included. Please read the note above in the message definition regarding changed node IDs that just:connect may return in its response.

“requestAttribute” message

Class	XML
Type	General
Sent By	Client (just:play, just:live, 3rd-party application)
Definition	This message is sent by the client to completely update (replace) an attribute on an existing node in the schedule. The root tag in this message defines a single optional attribute: The “continuous” attribute is a boolean flag where “F” for false defines a single, one-shot update of the attribute and “T” for true defines an update that is part of continuous stream of updates for the attributes. A good example of a continuous update is where the attribute is being controlled via a “slider” in the user interface where the user drags the slider left and right or up and down to quickly and continuously change the value of the attribute. Specifying the continuous flag in this situation is important as it delays certain updates sent from just:connect to just:out, thus making the updates to the attribute more responsive. Once the user finishes updating the attribute (e.g. releases the mouse button used to drag the slider in the user interface), the client should resend this message one last time with the final attribute value and the “continuous” attribute set to “F” in order to ensure that the full update is then sent by just:connect to just:out. If omitted then the default value of “F” is used by just:connect. The root tag in the message should have a single child <attribute> tag specifying the attribute to update and one or more <node> tags specifying the node(s) on which the attribute should be updated. Specifying more than one <node> tags allows the same attribute to be set on multiple nodes in the schedule with a single message (for example, if the user interface allows the user to select multiple items and then set an attribute, a single “requestAttribute” message can be sent by the client). The text of each <node> tag defines the ID of the node on which to update the attribute. In each case a node with the given ID must already exist in the schedule. The following example sets the “toaFadeIn” attribute to a value of 2.0 on the nodes with the IDs “xxx” and “yyy”: <requestAttribute> <attribute key=”toaFadeIn” type=”2”>2.0</attribute> <node>xxx</node> <node>yyy</node> </requestAttribute> Note that this message can also be used to add a new attribute to a given node as well as updating an existing attribute. If the specified attribute does not exist for one of the given nodes, it will be automatically added to the node’s attributes.
Response	The response from just:connect is also XML as follows: <retRequestAttribute success=”T”> <attribute key=”toaFadeIn” type=”2”>2.0</attribute> <node>xxx</node> <node>yyy</node> </retRequestAttribute> The “success” attribute is a boolean value where “T” for true indicates that the attribute was successfully updated on the requested nodes and “F” for false indicates that the attribute was not updated as requested. This is most likely where the updated value would cause some kind of conflict in the schedule (e.g. setting the duration of a movie play node to be longer than the movie’s natural duration). In this case the client should check the value of the <attribute> tag in the response as this will contain the actual value set on the requested nodes.

“requestRemoveAttribute” message

Class	XML
Type	General
Sent By	Client (just:play, just:live, 3rd-party application)
Definition	This message is sent by the client to remove a given attribute from a node in the schedule. The root tag in this message defines two mandatory attributes: The “node” attribute is the ID of the schedule node from which the attribute should be removed. The node with the given ID must already exist in the schedule. The “key” attribute is the key name of the attribute to remove (e.g. “toaFadeIn”, “toaFadeOut”). The following example removes the “toaFadeIn” attribute from the nodes with the ID “xxx”: <requestRemoveAttribute node=”xxx” key=”toaFadeIn” /> Note that the client sending this message must take care not to remove attributes required for the correct functioning of just:connect and/or just:out. For example, removing the “toaStart” or “toaDuration” attributes on schedule nodes will lead to undefined behavior such as just:out playing out nodes at incorrect times.
Response	The response from just:connect is also XML as follows: <retRequestRemoveAttribute node=”xxx” key=”toaFadeIn” /> As such it simply confirms the removed attribute, allowing all clients to update their internal schedule information to reflect the change. Note that if the node specified in the original message is not found then no response will be sent by just:connect.

“requestDelete” message

Class	XML
Type	General
Sent By	Client (just:play, just:live, 3rd-party application)
Definition	This message is sent by the client to delete a node or nodes from the schedule. The root tag defines no attributes and should have one or more <id> tags with the text of each <id> tag defining the ID of one node in the schedule to be removed. The following example removes the nodes ID “xxx” and “yyy”: <requestDelete> <id>xxx</id> <id>yyy</id> </requestDelete> Note that this is a very powerful message as it is possible to remove everything up to and including a class 1 (Day) node. Care should therefore be taken by the client when sending this message to ensure that only nodes that are really no longer required in the schedule are removed.
Response	The response from just:connect is also XML as follows: <retRequestDelete> <id>xxx</id> <id>yyy</id> </retRequestDelete> As such it simply confirms the removed node(s), allowing all clients to update their internal schedule information to reflect the change. Note that if the node specified in the original message is not found then that node’s <id> tag will not be included in the response sent by just:connect.

“requestWarnings” message

Class	XML
Type	24/7 Schedule
Sent By	Client (just:play, 3rd-party application)
Definition	This message is sent by the client to request any warnings in the 24/7 schedule such as gaps at the end of a playlist or between two playlists. The root tag of the message defines two mandatory attributes: The “from” attribute is in the timecode format (including date information) from where the schedule should be checked for warnings. The “to” attribute is in the timecode format (including date information) up to where the schedule should be checked for warnings. The following example checks for warnings in the schedule between 12:00 and 13:00 on the 1.1.2011: <requestWarnings from=”1.1.2011 12:00:00:00” to=”1.1.2011 13:00:00:00” />
Response	The response from just:connect is also XML as follows: <retRequestWarning> <warning>Gap at 12:30:00:00</warning> </retRequestWarning> Assuming that a warning is found it will be sent as the text of the <warning> tag. If no warnings are found in the schedule between the time specified by the “from” and “to” attributes the response will simply not include any <warning> tags, for example: <retRequestWarning />

“requestRealTimeContainer” message

Class	XML
Type	Live
Sent By	Client (just:live, 3rd-party application)
Definition	This message has two purposes: Switches just:connect and all just:out engines assigned to the specific channel from “24/7 scheduled” playout to “live” playout, and returns the root class “7” (Real-time playlist / folder) node that the client can then use to manage the live playout (inserting play nodes to the contents / workbench folder, then loading the nodes to the schedule playlist). Pre-load a live “show” of real-time folder and play nodes. In order to simply set just:connect in the “live” mode, send the simple message... <requestRealTimeContainer /> ...and to pre-load a complete live show... <requestRealTimeContainer> <node class=”7” id=”xxx”> ...further Schedule XML nodes </node> </requestRealTimeContainer> In this case the schedule XML nodes must conform to the “live show” structure: Class 7: Real-time Folder (Root) Class 7: Real-time Folder (Contents) Class 7: Real-time Folder (Folder) Class 5: Play Class 5: Play Class 7: Real-time Folder (Schedule) Class 8: Real-time Play Class 8: Real-time Play Please refer to the “Live Playout” section for full details on the live schedule XML schema.
Response	The response from just:connect is also XML as follows: <retRequestRealTimeContainer> <node class=”7” id=”xxx”> ...further Schedule XML nodes </node> </retRequestRealTimeContainer> Note that the response is “deep”: it includes the entire current live schedule. If the client has sent the simple form of the message to create the real-time nodes, then the response will include three class 7 nodes: the root real-time playlist with two children. The first child is always the “contents” playlist and the second the “schedule” playlist. The client application can then use the IDs of these real-time playlist nodes to manage the live schedule by adding folders and play nodes to the “contents” playlist (pre-loading contents) and then class 8 (Real-time Play) nodes to the “schedule” playlist to schedule the pre-loaded contents for actual playout. Please refer to the “Live Playout” section for full details on the live schedule XML schema.

“requestFormat” message

Class	Plain Text
Type	General
Sent By	Client (just:play, just:live, 3rd-party application)
Definition	This message is sent by the client to request the channel’s broadcast format. It is important for the client application to know the channel’s format when calculating timecodes for the schedule. The message is sent without any parameters: requestFormat
Response	The response from just:connect is also plain text with a single parameter: retReuestFormat SD PAL The string after “retRequestFormat” plus a space character specifies the broadcast format. This can be one of the following: SD PAL SD NTSC SD NTSC 23.98 HD 720p50 HD 720p60 HD 1080i25 HD 1080i29.97 HD 1080i30 HD 1080p24 HD 1080p23.98 HD 720p24 HD 720p23.98 HD 720p59.94

“requestTracks” message

Class	Plain Text
Type	General
Sent By	Client (just:play, just:live, 3rd-party application)
Definition	This message is sent by the client to request the channel’s tracks. It may be useful for the client application to know what tracks are defined for the given channel. For example, the client application may want to allow the user to select which track an item will be rendered on, and obviously it is important that the user only be presented with a valid list of tracks to select from. The message is sent without any parameters: requestTracks
Response	Unusually the response to this plain text message is sent in XML in the following format: <retRequestTracks> <track> <identifier>g0</identifier> <name>Graphic 1</name> <master>local._toaengine._tcp.Some-Mac-Pro</master> <slave>local._toaengine._tcp.Another-Mac-Pro</master> </track> <track> <identifier>v0</identifier> <name>Video 1</name> <master>local._toaengine._tcp.Some-Mac-Pro</master> <slave>local._toaengine._tcp.Another-Mac-Pro</master> </track> </retRequestTracks> The response includes one or more <track> tags, each representing a track defined for the channel. Each <track> tag has an <identifier> tag where the tag text is the track’s ID and a <name> tag where the tag text is the track’s human readable name (the name that should be presented to the user in any user interface). Finally, the <track> tag has a <master> tag that defines the Bonjour name of the master system running just:out to render the track and, optionally, a <slave> tag that defines the Bonjour name of the slave (redundant) system running just:out to render the track. Multiple tracks can be assigned to the same master and slave just:out systems. Note that the tracks are defined in reverse-render-order. In other words, the last <track> tag will be the first track rendered (the bottom layer) and is most often the video track. Further tracks will be rendered bottom-up over another.

“playtrack” message

Class	Plain Text
Type	Live
Sent By	Client (just:live, 3rd-party application)
Definition	This message is sent by the client to request that the next available item scheduled on the specified track be played out starting at the next available frame. The next available item is defined as the first class 8 (Real-time Play) node under the “schedule” real-time playlist / folder node where the “toaTrack” attribute matches the specified track. The message is sent with a single parameter which is the ID of the track. For example, to play the next available video item on the video track with the identifier “v0” the message would be... playtrack v0 Note that this message will have no effect if an item is already playing on the specified track. However, if an item is cued on the specified track this message will start the item playing.
Response	This message produces no immediate response from just:connect. However, assuming that an item is scheduled for playout on the specified track then a “playingNode” message will be sent by just:connect when the item begins playing out.

“cuedtrack” message

Class	Plain Text
Type	Live
Sent By	Client (just:live, 3rd-party application)
Definition	This message is sent by the client to request that the next available item scheduled on the specified track be cued at the next available frame. The next available item is defined as the first class 8 (Real-time Play) node under the “schedule” real-time playlist / folder node where the “toaTrack” attribute matches the specified track. The message is sent with a single parameter which is the ID of the track. For example, to cue the next available video item on the video track with the identifier “v0” the message would be... cuedtrack v0 Note that this message will have no effect if an item is already playing or is cued on the specified track.
Response	This message produces no immediate response from just:connect. However, assuming that an item is scheduled for playout on the specified track then a “playingNode” message will be sent by just:connect when the item is cued.

This message is only valid for movie nodes on a video track.

“nexttrack” message

Class	Plain Text
Type	General
Sent By	Client (just:play, just:live, 3rd-party application)
Definition	This message is sent by the client to request two actions: Any item currently playing on the specified track should be ended at the first possible frame, and... The next available item scheduled on the specified track be played out starting at the next available frame. The next available item is defined as the first class 8 (Real-time Play) node under the “schedule” real-time playlist / folder node where the “toaTrack” attribute matches the specified track. The message is sent with a single parameter which is the ID of the track. For example, to play the next available video item on the graphic track with the identifier “g0” the message would be... nexttrack g0 Note that the two actions outlined above are completely independent of each other, meaning that one action does not depend on the other action to be valid. For example, sending this message when nothing is currently playing on the specified track will simply result in the next available item on the track being played out, as if a “nexttrack” command had been sent. Conversely, when an item is currently playing but no further items are scheduled for the specified track then the currently playing item will be stopped immediately and nothing played on the track, as if a “skiptrack” message had been sent.
Response	This message produces no immediate response from just:connect. However, one or two messages may be sent by just:connect after a short delay: Assuming that an item is currently playing on the specified track then a “finishedNode” message will be sent by just:connect when the item has finished playing out. Assuming that another item is scheduled for playout on the specified track then a “playingNode” message will be sent by just:connect when the item beings playing out.

“skiptrack” message

Class	Plain Text
Type	General
Sent By	Client (just:play, just:live, 3rd-party application)
Definition	This message is sent by the client to request that the item currently playing on the specified track be stopped at the next possible frame. This will result in nothing playing at all on the specified track. The message is sent with a single parameter which is the ID of the track. For example, to stop playing the current video item on the video track with the identifier “v0” the message would be... skiptrack v0 Optionally it is possible to override the playing item’s “next action” by sending a different next action with the command with the following format: skiptrack v0 n Where “n” is an integer value specifying the next action to apply after skipping the currently playing item. The next action values are identical to those specified by the “toaNextAction” attribute, as follows: 0 = do nothing, or stop. Nothing further will be played out on the current node’s track until the 3rd-party application or just:live issues a play command. 1 = play next. Assuming that another play node is scheduled on the track on which the current node is playing, it will be immediately started (i.e. “chained” to the current play node). 2 = cue next. Assuming that another play node is scheduled on the track on which the current node is playing, its first frame will be cued on the track without actually playing the node. In order to actually play the next node the 3rd-party application or just:live must issue a play command. 3 = hold last. For a video clip, holds the final frame of the video indefinitely until a “next” command is issued, after which nothing will be played out (equivalent to the “stop” action). 4 = reload. The current play node is “reloaded” on the track, meaning that when the 3rd-party application or just:live issues a play command for the track the current node will play out again, instead of the next scheduled play node on the track. 5 = re-cue. Identical to the “reload” end action, but additionally the first frame of the play node’s media will be displayed on the track. 6 = hold and cue next. Identical to the “hold last” action, except that the last frame will only be held for the time specified by the “toaHoldTime” attribute, after which the next item on the track will automatically be cued. 7 = hold and play next. Identical to the “hold last” action, except that the last frame will only be held for the time specified by the “toaHoldTime” attribute, after which the next item on the track will automatically be played out.
Response	This message produces no immediate response from just:connect. However, assuming that an item is currently playing on the specified track then a “finishedNode” message will be sent by just:connect when the item has finished playing out.

“playingNode” message

Class	XML
Type	General
Sent By	just:connect
Definition	This message is sent by just:connect to all connected clients whenever a class 5 (Play) or class 8 (Real-time Play) node begins playing out. The client can use this message to synchronize its internal schedule (by storing the timecode when the item starts playing out) and/or providing status information to the user in a user interface. The message is formatted as follows: <playingNode id=”xxx”> <audioTracks>2</audioTracks> <timecode>1.1.2011 12:00:00:00</timecode> <nodeUID>yyy</nodeUID> <trackID>v0</trackID> </playingNode> The “id” attribute on the root tag identifies the ID of the node being played out. The tag text of the <audioTracks> tag defines how many audio tracks the item has (valid for QuickTime movie media items) and the <timecode> tag’s text defines the starting time of the item in the timecode attribute format (with date information). The <nodeUID> specifies the UID of the node playing (may be different to “id” for live nodes, as “id” is the “content” node UID and <nodeUID> is the “scheduled” node UID). The <trackID> tag specifies the identifier of the track on which the item is playing.
Response	When the client receives this message and it is currently managing a live playout schedule it should immediately send a “requestAttribute” message back to just:connect reflecting the start time. For example: <requestAttribute> <attribute key=”toaStart” type=”7”>1.1.2011 12:00:00:00</attribute> <node>xxx</node> </requestAttribute> This acknowledges to just:connect that the client has received and accepted the node’s start time.

“finishedNode” message

Class	XML
Type	General
Sent By	just:connect
Definition	This message is sent by just:connect to all connected clients whenever a class 5 (Play) or class 8 (Real-time Play) node finishes playing out. The client can use this message to synchronize its internal schedule and/or providing status information to the user in a user interface. The root tag of the message defines three attributes: The “id” attribute defines the ID of the node that finished playing out. The “replay” attribute defines a boolean value of “T” for true if the item will be replayed immediately (i.e. it is looped) or “F” for false if the item will not be replayed (it has completely finished playing out). The “skipped” attribute defines a boolean value of “T” for true if the item was skipped (finished earlier that originally scheduled due to a user-initiated action) or “F” for false if the item finished playing out normally as originally scheduled. The “trackID” attribute identifies the track on which the node was playing out. An example message is a follows... <finishedNode id=”xxx” replay=”F” skipped=”F” trackID=”v0”> <timecode>30.4.2012 12:30:00:00</timecode> </finishedNode>
Response	When the client receives this message and it is currently managing a live playout schedule and the replay attribute is “F” for false, it should immediately send the following messages back to just:connect: A “requestDelete” message to remove the class 8 (Real-time Play) node referencing the node that finished playing out (i.e. with the reference ID equal to the “id” attribute in the original message) from the real-time “schedule” playlist / folder. A “requestRemoveAttribute” message for the “toaStart” attribute key on the node that finished playing out. A “requestRemoveAttribute” message for the “toaStopFrameStartTimes” attribute key on the node that finished playing out. A “requestRemoveAttribute” message for the “toaStopFrameStopTimes” attribute key on the node that finished playing out. For example, the <finishedNode> message described above sends the node ID “xxx”. Assuming that the class 8 (Real-time Play) node referencing this node in the real-time “schedule” playlist / folder has the ID “yyy” the correct response messages would be: <requestDelete> <id>yyy</id> </requestDelete> <requestRemoveAttribute node=”xxx” key=”toaStart” /> <requestRemoveAttribute node=”xxx” key=” toaStopFrameStartTimes” /> <requestRemoveAttribute node=”xxx” key=” toaStopFrameStopTimes” />

“stopFrameNode” message

Class	XML
Type	General
Sent By	just:connect
Definition	This message is sent by just:connect to all connected clients whenever a class 5 (Play) or class 8 (Real-time Play) node with a Composition Builder or Quartz Composer graphic file resource reaches a stop frame. The client can use this message to synchronize its internal schedule (by storing the timecode when the stop frame was reached) and/or providing status information to the user in a user interface. The message is formatted as follows: <stopFrameNode id=”xxx”> <timecode>30.4.2012 00:00:00:20</timecode> </stopFrameNode> The “id” attribute on the root tag identifies the ID of the node being played out on which the stop frame was reached. The <timecode> tag’s text defines the timecode when the stop frame was reached in the timecode attribute format (with date information).
Response	When the client receives this message and it is managing a live playout schedule it should save the timecode in the node’s “toaStopFrameStartTimes” array and send a “requestAttribute” message for the “toaStopFrameStartTimes” attribute key back to just:connect to update the attribute. For example... <requestAttribute> <attribute key="toaStopFrameStartTimes" type="6"> <array> <timecode>00:00:00:20</timecode> </array> </attribute> <node>xxx</node> </requestAttribute>

“triggerNode” message

Class	XML
Type	General
Sent By	just:connect
Definition	This message is sent by just:connect to all connected clients whenever a class 5 (Play) or class 8 (Real-time Play) node with a Composition Builder or Quartz Composer graphic file resource is released from a stop frame (i.e. continues playing out). The client can use this message to synchronize its internal schedule (by storing the timecode when the stop frame was released) and/or providing status information to the user in a user interface. The message is formatted as follows: <triggerNode id=”xxx”> <timecode>00:00:00:30</timecode> </triggerNode> The “id” attribute on the root tag identifies the ID of the node being played out on which the stop frame was released. The <timecode> tag’s text defines the timecode when the stop frame was reached in the timecode attribute format (with date information).
Response	When the client receives this message and it is managing a live playout schedule it should save the timecode in the node’s “toaStopFrameEndTimes” array and send a “requestAttribute” message for the “toaStopFrameEndTimes” attribute key back to just:connect to update the attribute. For example... <requestAttribute> <attribute key="toaStopFrameEndTimes" type="6"> <array> <timecode>00:00:00:30</timecode> </array> </attribute> <node>xxx</node> </requestAttribute>

“heartbeat” message

Class	Plain Text
Type	General
Sent By	just:connect
Definition	just:connect will forward heartbeat message from all connected just:out engines to the client application (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 just:out’s time and optionally display this information to the user (the current timecode and/or the mere fact the just:out is sending heartbeats to the client). The message is formatted as follows: heartbeat 12:30:00:30 Note that additional diagnostics information may be appended by just:out after the timecode. This information can be simply ignored by 3rd-party applications.
Response	No response is expected to this message.

“engineLost” message

Class	XML
Type	General
Sent By	just:connect
Definition	just:connect will send this message to all connected client when contact to a given system previously running just:out is lost. The message is formatted as follows: <engineLost>Some-Mac-Pro</engineLost> The root tag text specifies the name of the system running just:out to which contact has been lost.
Response	No response is expected to this message.

“unblockTime” message

Class	Plain Text
Type	24/7 Schedule
Sent By	Client (just:play, 3rd-party application)
Definition	This command is sent by the client application to release an “infinite live input” clip and continue playing any events following the live clip as soon as possible. The message is sent without any parameters as follows: unblockTime
Response	just:connect will respond with at least the “unblockedTime” message with the exact timecode at which the time was “unblocked” (i.e. at which any events following the “infinite live input” clip began playing). This response is also plain text with the timecode (including date information) following the message, as follows: unblockedTime 1.1.2011 1000 In addition, depending this message will result in at least one “finishedNode” message (for the infinite live input clip itself) and potentially one or more “playingNode” messages, one for each event the begins playing out as a result of the infinite live input clip being released (e.g. a video clip and one or more graphic clips).

Playout example scenarios

How do I load a graphic and then set an input port?

To actually load a Composition Builder or Quartz Composer graphic in order to play it out you will need to send a different set of messages depending on whether you are operating in 24/7 scheduled playout or live playout.

In both cases you first need to send a “requestInsert” message containing a class 5 (Play) node to define the graphic file you wish to play out.

For 24/7 scheduled playout you would need to send the play node as part of a playlist by either inserting the node into an existing playlist or sending a new playlist. The following example sends a playlist scheduled on 9.12.2010 and assumes that the class 1 (Day) node for 9.12.2010 has the ID “xxx”...

<attribute key="toaName" type="0">New Playlist</attribute>

<node id="56202871-D71C-4416-9EEC-4AC3D58B0E43" class="5">

<attribute key="toaDuration" type="7">75</attribute>

<attribute key="toaStopFrames" type="6" flags="1">

<array>

<double>1.500000</double>

</array>

</attribute>

<attribute key="toaNaturalDuration" type="7" flags="1">75</attribute>

<attribute key="Component_2_Font_Name_1" type="0" flags="8194" name="Font_Name_1_Text">MyriadPro-Regular</attribute>

<attribute key="Component_2_Font_Size_1" type="2" flags="12290" name="Font_Size_1_Text">

<value>40.000000</value>

<min>1.000000</min>

</attribute>

<attribute key="Component_2_Color" type="8" flags="2" name="Color_Text">#000000ff</attribute>

<attribute key="toaHasCustomInterface" type="3" flags="9">F</attribute>

<attribute key="toaStart" type="7">9.12.2010 1530000</attribute>

<attribute key="toaColor" type="8">#00</attribute>

<attribute key="toaName" type="0">TOA Lower Third 1280x720</attribute>

<attribute key="Component_2_Justification" type="4" flags="16386" name="Justification_Text">

<value>0</value>

<max>2</max>

<values>

<string>Left</string>

<string>Center</string>

<string>Right</string>

</values>

</attribute>

<attribute key="Component_2_Text" type="0" flags="4098" name="Text_Text">Insert Name Here</attribute>

<node id="1DFCD636-0B48-4E7A-9D76-41E17C3F93DE" class="6">

<attribute key="toaStart" type="7">9.12.2010 1530037</attribute>

<attribute key="toaStopFrameTime" type="7" flags="1">0</attribute>

</node>

<resource type="1">TOA World News/TOA Lower Third 1280x720.composition/Composition.qtz

</resource>

</node>

</node>

</node>

</requestInsert>

The actual class 5 (Play) node that defines the graphic file is highlighted in bold above. There are several things to note:

The <resource> tag has the “type” attribute set to “1” to indicate a Composition Builder / Quartz Composer resource.
As the graphic file in the example has a single stop frame the “toaStopFrames” attribute is defined with an array of double values, in this case a single value. Additionally there is a single class 6 (Trigger) child node defined for the stop frame.
In addition to the standard attributes (those with the “toa” prefix in the key attribute) there are also several “input port” attributes, one for each input port published by the graphic file. These are the attributes with the “Component_” prefix in the key attribute. These attributes always have the “2” bit set in the “flags” attribute to indicate an input port.
There are several different types of input port defined, such as text (string), color, double and index.

In terms of 24/7 scheduled playout, this is enough to bring the graphic file on air at the scheduled time. For live playout you must insert the same play node into one of the real-time playlist / folders under the “contents” real-time playlist / folder. Assuming that such a folder has the ID “xxx” you would send the following:

<node id="56202871-D71C-4416-9EEC-4AC3D58B0E43" class="5">

<attribute key="toaDuration" type="7">75</attribute>

<attribute key="toaStopFrames" type="6" flags="1">

<array>

<double>1.500000</double>

</array>

</attribute>

<attribute key="toaNaturalDuration" type="7" flags="1">75</attribute>

<attribute key="Component_2_Font_Name_1" type="0" flags="8194" name="Font_Name_1_Text">MyriadPro-Regular</attribute>

<attribute key="Component_2_Font_Size_1" type="2" flags="12290" name="Font_Size_1_Text">

<value>40.000000</value>

<min>1.000000</min>

</attribute>

<attribute key="Component_2_Color" type="8" flags="2" name="Color_Text">#000000ff</attribute>

<attribute key="toaHasCustomInterface" type="3" flags="9">F</attribute>

<attribute key="toaColor" type="8">#00</attribute>

<attribute key="toaName" type="0">TOA Lower Third 1280x720</attribute>

<attribute key="Component_2_Justification" type="4" flags="16386" name="Justification_Text">

<value>0</value>

<max>2</max>

<values>

<string>Left</string>

<string>Center</string>

<string>Right</string>

</values>

</attribute>

<attribute key="Component_2_Text" type="0" flags="4098" name="Text_Text">Insert Name Here

</attribute>

<node id="1DFCD636-0B48-4E7A-9D76-41E17C3F93DE" class="6">

<attribute key="toaStopFrameTime" type="7" flags="1">0</attribute>

</node>

<resource type="1">TOA World News/TOA Lower Third 1280x720.composition/Composition.qtz

</resource>

</node>

</requestInsert>

Note that the class 5 (Play) node itself is identical to that sent in the 24/7 scheduled example except that the “toaStart” attributes are missing as the start time will be assigned by just:out when a “playtrack” or “nexttrack” message is received.

Once loaded for live playout, the node still needs to be scheduled and then played. Assuming that the “schedule” real-time playlist / folder node has the ID “yyy”, the following message would schedule the previously loaded play node:

</requestInsert>

Now the play node with the ID “56202871-D71C-4416-9EEC-4AC3D58B0E43” is scheduled for immediate playout. Finally, issue a “playtrack” message for the track on which the node has been scheduled, in this case “g0”:

playtrack g0

The graphic should now be playing out. Regardless of whether 24/7 scheduled playout or live playout, once a graphic is on air a message can be sent at any time to change the value of one of the input ports using the “requestAttribute” message. For example...

<attribute key="Component_2_Color" type="8" flags="2" name="Color_Text">#ff0000ff</attribute>

<node>56202871-D71C-4416-9EEC-4AC3D58B0E43</node>

</requestAttribute>

...would set the node’s attribute with the key “Component_2_Color” to the value “#ff0000ff” (red color). As this attribute is marked as an input port attribute and the graphic associated with the node is on air the published input port with the key “Component_2_Color” to the value specified in the message.

In this way the contents of a graphic can be updated at any time, even when the graphic is currently playing on air.

Ingest communication protocol

In just:in the 3rd-party application talks directly to one or more instances of just:in engine. Each just:in engine in turn may have one or more channels, which are identified by the channel attribute in each message that is sent to or received from the engine. Other than just:connect, just:in only uses XML messages for communication. There are two classes of message:

Messages sent from the client (just:live multi or the 3rd-party application) to just:in engine. In most cases just:in engine will send back a response to the client.
Messages pushed from just:in engine to the client (just:live multi or the 3rd-party application).

“requestChannels” message

Sent By	Client (just:in multi, 3rd-party application)
Definition	This message is sent by the client to request all channels of a given just:in engine. Sent as: <requestChannels />
Response	just:in engine will respond with one message for each channel separately as shown below: <foundChannel channel=”example channel” name=”examplehost.local”> <lock>0</lock> <channelIdentifier></channelIdentifier> </foundChannel> The “channel” attribute is the unique identifier for the channel. The client must use this identifier when sending any messages to just:in engine related to the channel. The “name” attribute defines the human-readable name of the channel and should be used by the client when displaying information about the channel in its user interface. The text of the “lock” tag can be 0 or 1, where 0 means that the channel is available for use by the client and 1 if it is not available (currently locked by another client). The text of the “channelIdentifier” contains the current owner of the channel if it is locked. If the “lock” value is 0, the value of “channelIdentifier” is empty. A client can use this information to display information to the user (e.g. who currently has the channel locked).

“requestLock” message

Sent By	Client (just:in multi, 3rd-party application)
Definition	A client sends this message to either request a lock on a channel (in order to use the channel to record, for example), or to release a channel that it had previously locked. The message is sent as follows: <requestLock channel=”example channel”> <lock>1</lock> <channelIdentifier>example client</channelIdentifier> </requestLock> The text of the “lock” tag should be “1” to request that the channel be locked or “0” to request that the channel be released. When locking a channel the client should also send a human-readable name of the application locking the channel in the text of the “channelIdentifier” tag. This is the name that will be sent back to clients by just:in engine is response to the “requestChannels” message and may be displayed by clients in their user interfaces.
Response	just:in engine will respond with the following message: <retConfirmLock channel=”example channel” name=”examplehost.local”> <lock>1</lock> <channelIdentifier>example client</channelIdentifier> </retConfirmLock> The text of the “lock” tag can be “0” or “1”, where “1” means that the channel is locked and “0” that the channel is unlocked. The client must interpret the locked status in order to check whether or not its request was successful. For example, if the request was to lock a channel and the response has a locked status of “1” then the request was successful, whereas a locked status of “0” would indicate that the channel was not successfully locked. The text of the “channelIdentifier” contains the current owner of the channel if it is locked. If the “lock” value is 0, the value of “channelIdentifier” is empty. A client can use this information to display information to the user (e.g. who currently has the channel locked). Note that this response is sent to all connected clients so each client has an up-to-date list of which channels are currently locked or unlocked. A client might use this information to display a “live” list of channels that is automatically updated whenever a channel is locked or unlocked, even by another client.

“requestSettingFileNames” message

Sent By	Client (just:in multi, 3rd-party application)
Definition	This message asks the engine for all setting files that are available for the given channel. These setting files are created in just:in engine’s System Preferences pane and are saved in the folder: /Library/Application Support/ToolsOnAir/Just In/ *.justin For example: <requestSettingFileNames channel=”example channel” /> The root tag of the message defines the “channel” attribute which must specify the identifier of the channel for which the presets are being requested. This is the channel identifier sent as a response to the “requestChannels” message.
Response	just:in engine will respond with the following message: <retRequestSettingFileNames channel=”example channel” name=”examplehost.local”> <name enabled=”0”>first.justin</name> <name enabled=”1”>second.justin</name> ... <name enabled=”1”>last.justin</name> </retRequestSettingFileNames> The “channel” attribute on the root tag is the identifier of the channel and is the same as that sent in the request. The “name” attribute on the root tag is the channel’s human-readable name. Each preset file for the channel is represented by one <name> tag in the response. The text of the <name> tag is the name of the preset including the “.justin” file extension. Client applications wishing to display the presets (e.g. in a list from which the user can select one) should consider stripping this file extension before displaying the name. In addition each <name> tag representing a preset can an “enabled” attribute which can have the values “0” or “1”. If the value is “1” the setting matches the current engine settings (e.g. the correct frame rate), and is therefore loadable. If the value is “0” the setting doesn’t correspond with the current engine settings and must not be loaded. It may be displayed to the user in a list, but should be disabled so that user cannot select it.

“requestLoadSetting” message

Sent By	Client (just:in multi, 3rd-party application)
Definition	This message asks the engine to load the specified setting: <requestLoadSetting channel=”example channel”>example setting name</requestLoadSetting> The root tag of the message defines the “channel” attribute which must specify the identifier of the channel for which the presets are being requested. This is the channel identifier sent as a response to the “requestChannels” message. The text of the root tag should specify the name of the preset to load without the “.justin” file extension. As such it should match one of the names sent in response to the “requestSettingFileNames” messages, except that those names are sent with the “.justin” extension and must be stripped before sending the name for this message.
Response	just:in engine will load the specified setting and when it loads successfully it will respond with the following message: <retLoadedSetting channel=”example channel” name=”examplehost.local” filename=”/Library/Application Support/ToolsOnAir/Just In/example setting name.justin”> <codec>DV - PAL</codec> <aspectratio>0</aspectRatio> <tvnorm>0</tvnorm> <audiochannels>0</audiochannels> <timecodesource>0</timecodesource> <container>0</container> <framerate>2500</framerate> <videowidth>720</videoWidth> <videoheight>576</videoheight> <TOACompressionComponent> <name>Apple DV - PAL</name> <compressionString>1685480304</componentString> </TOACompressionComponent> <cliplength>02:00:00:00</cliplength> </retLoadedSetting> The “channel” attribute on the root tag is the identifier of the channel and is the same as that sent in the request. The “name” attribute on the root tag is the channel’s human-readable name. The “filename” attribute on root tag contains the full path of the file from which the presets were loaded. The <codec> tag’s text is the human-readable name of the codec defined in the present. The <aspectratio> tag’s text is “0” for 16:9, and “1” for 4:3. The <tvnorm> tag’s text is “0” for PAL, “1” for NTSC, “2” for HD PAL and “3” for HD NTSC. The <audiochannels> tag’s text is “0” for 2, “1” for 4 and “2” for 8 audio channels. The <timecodesource> tag’s text is “0” for Computer Time, “1” for RS422 VTR, “2” for FireWire VTR, 3 for LTC over audio and “4” for Miranda Little Red LTC. The <container> tag’s text is “0” for QuickTime, “10” for MXF GC, “11” for MXF D10 and “12” for MXF XDCAM. The <framerate> tag’s text is the preset’s frame rate multiplied by 100 (e.g. 2500 for PAL 25 fps). The <videowidth> and <videoheight> tags’ text represent the size in pixels of a video frame. The <TOACompressionComponent> tag is a wrapper of a QuickTime Component. It contains both the name of the codec in the <name> tag’s text and its component subtype as an integer value in the <compressionString> tag’s text (the example shows ‘dvcp‘). The <cliplength> tag’s text is the maximum container length in SMPTE timecode format that is set in just:in engine’s System Preferences pane.

“requestDestinationSettingFileNames” message

Sent By	Client (just:in multi, 3rd-party application)
Definition	This message is sent by the client to request all destination presets for a given channel. The destination presets are created in just:in engine’s System Preferences pane. The destination presets are stored in the folder: /Library/Application Support/ToolsOnAir/Just In/ *.destination The message is sent as follows: <requestDestinationSettingFileNames channel=”example channel” /> The root tag of the message defines the “channel” attribute which must specify the identifier of the channel for which the presets are being requested. This is the channel identifier sent as a response to the “requestChannels” message.
Response	just:in engine will respond with: <destinationPresets channel=”example channel” name=”examplehost.local”> <preset>first.destination</preset> <preset>second.destination</preset> ... <preset>last.destination</preset> </destinationPresets> The “channel” attribute on the root tag is the identifier of the channel and is the same as that sent in the request. The “name” attribute on the root tag is the channel’s human-readable name. Each destination preset file for the channel is represented by one <preset> tag in the response. The text of the <preset> tag is the name of the preset including the “.destination” file extension. Client applications wishing to display the presets (e.g. in a list from which the user can select one) should consider stripping this file extension before displaying the name.

“requestLoadDestinationSetting” message

Sent By	Client (just:in multi, 3rd-party application)
Definition	This message is sent by the client to request loading the specified destination preset. The message is sent as follows:. <requestLoadDestinationSetting channel=”example channel”> <presetName>exampleDestinationPreset</presetName> </requestLoadDestinationSetting> The root tag of the message defines the “channel” attribute which must specify the identifier of the channel for which the presets are being requested. This is the channel identifier sent as a response to the “requestChannels” message. The text of the root tag should specify the name of the destination preset to load without the “.destination” file extension. As such it should match one of the names sent in response to the “requestDestinationSettingFileNames” messages, except that those names are sent with the “.destination” extension and must be stripped before sending the name for this message.
Response	just:in engine will load the destination preset and return the following response: <returnLoadedDestinationSetting channel=”example channel” name=”examplehost.local”> <justinDestinationPreset name=”exampleDestinationPreset”> <hirespath>/path/to/hires</hirespath> <lowrespath>/path/to/lowres></lowres> <xmlExportpath>/path/to/xmlExport</xmlExportpath> </justinDestinationPreset> <pathnotwritable>/path/not/writable</pathnotwritable> ... </returnLoadedDestinationSetting> The “channel” attribute on the root tag is the identifier of the channel and is the same as that sent in the request. The “name” attribute on the root tag is the channel’s human-readable name. The <justinDestinationPreset> has the “name” attribute identifying the name of the destination preset that has been loaded. This name matches the name sent in the request. The <hirespath> tag’s text defines the path where the full-resolution movie files will be written. The <lowrespath> tag’s text defines the path where any proxy files will be written, assuming they are enabled for the current preset. The <xmlExportpath> tag’s text defines the path where any XML metadata files will be written, assuming they are enabled for the current preset. The paths are internally checked for writability, so when one or more paths are not writable the answer will contain additional <pathnotwritable> tags (count depends on how many paths are not writable) with the path(s) that are not writable.

“requestFilename” message

Sent By	Client (just:in multi, 3rd-party application)
Definition	This message asks the engine to write the specified filename, for example: <requestFilename channel=”example channel”>exampleName.mov</requestFilename> The root tag of the message defines the “channel” attribute which must specify the identifier of the channel for which the presets are being requested. This is the channel identifier sent as a response to the “requestChannels” message. The text of the root tag specifies the requested filename.
Response	just:in engine will respond with the following message: <retRequestFilename channel=”example channel” name=”examplehost.local” didChange=”F”> exampleName.mov </retRequestFilename> The “channel” attribute on the root tag is the identifier of the channel and is the same as that sent in the request. The “name” attribute on the root tag is the channel’s human-readable name. The “didChange” on the root tag can be either “F” (false) or “T” (true). It indicates if the requested filename was changed by the engine. This may occur if the requested filename already exists at the current destination. In any case the root tag’s text specifies the filename that will actually be used by the engine when recording. This will be the same as the filename sent in the request if “didChange” is “F”, or different if “didChange” is “T”.

“requestRecording” message

Sent By	Client (just:in multi, 3rd-party application)
Definition	This message asks the engine start or stop recording. The message is sent as: <requestRecording channel=”example channel”>exampleName.mov</requestRecording> The root tag of the message defines the “channel” attribute which must specify the identifier of the channel for which the presets are being requested. This is the channel identifier sent as a response to the “requestChannels” message. The text of the root tag specifies the requested filename. Just as with the “requestFilename” message the “requestRecording” message should include the requested filename for the recoding. The message does not included a recording status (e.g. start or stop recording), as this is simply inferred by the current status of the channel. If the channel is not currently recording then this message will start a recording, while if the channel is already recording this message will stop the recording. It is up to the client sending the message to appropriately balance this message (once to start recording, again to stop recording).
Response	The response from just:in engine will depend on whether the request has started a recording or stopped a recording. When starting a recording just:in engine will send two responses to this message. The first response will be a “retRequestFilename” message to indicate the filename that will actually be recorded (which may be different to the filename actually requested). Please refer to the “requestFilename” description for full details on this response. Then a second response will be sent: <recordingStatus channel=”example channel” name=”examplehost.local”> <rec>1</rec> <hours>10</hours> <minutes>0</minutes> <seconds>0</seconds> <frames>0</frames> </recordingStatus> The <rec> tag’s text specifies “1” to indicate that recording started. The message carries the exact timecode the recording started in the <hours>, <minutes>, <seconds> and <frames> tags. When a recording was stopped the response from the engine is as follows: <recordingStatus channel=”example channel” name=”examplehost.local”> <rec>0</rec> <hours>10</hours> <minutes>0</minutes> <seconds>0</seconds> <frames>0</frames> <TOAMovieWriterFrameCount>250<TOAMovieWriterFrameCount> <TOAMovieWriterClipname>/full/path/to/clip.mov</TOAMovieWriterClipname> <TOAMovieWriterFirstSplit>1</TOAMovieWriterFirstSplit> <TOAMovieWriterSplitted>1</TOAMovieWriterSplitted> <TOAMovieWriterStartTime>*do not use</TOAMovieWriterStartTime> <TOAMovieWriterPreviousClipname>previous.mov</TOAMovieWriterPreviousClipname> <TOAMovieWriterLastSplit>1<TOAMovieWriterLastSplit> </recordingStatus> The <rec>, <hours>, <minutes>, <seconds>* and <frames> are the same as with the start recording response, except that the text of the <rec> tag is “0” because the recording was ended. Refer to the section below on “Movie file chunking” for details on the <TOAMovieWriterClipname>, <TOAMovieWriterFirstSplit>, <TOAMovieWriterSplitted> and further tags.

Movie file chunking

Due to restrictions in the QuickTime file format it is not possible to write files longer than a few hours. Therefore just:in places a restriction on the maximum length (duration) that it will write to a QuickTime movie. Once this limit is reached the movie file will be automatically closed and a new file opened. This process is referred to as “chunking”. For example, if the maximum clip length specified in just:in engine’s System Preferences pane is specified as one hour and a client starts recording on a channel and then stops after exactly 2.5 hours the result will be three movie files or “chunks”: two at exactly an hour in length and a third at half an hour. These chunks can then be joined together seamlessly either in just:play / just:out or in a video editing application such as FInal Cut Pro.

Due to this chunking process it is possible that just:in engine will send more than one “recordingStatus” message to the client while recording. When each chunk is complete one “recordingStatus” message will be pushed to the client (i.e. sent without the client having sent a specific message or request to just:in engine), and then a final “recordingStatus” message will be sent in response to the “requestRecording” message sent by the client to stop the recording.

There are several tags in the “recordingStatus” message related to the chunking, as follows:

The <rec> tag’s text is “1” to indicate that the recording is still ongoing and has not yet finished or “0” if the recording has finished.
The <TOAMovieWriterFrameCount> tag’s text specifies the number of video frames in the chunk just completed.
The <TOAMovieWriterClipname> tag’s text specifies the filename of the chunk completed. Obviously this will change from chunk to chunk.
The <TOAMovieWriterFirstSplit> tag’s text is “1” to indicate that this is the first chunk in the recording or “0” for all following chunks.
The <TOAMovieWriterSplitted> tag’s text is “1” to indicate that the movie writer itself created this chunk because the maximum clip length was reached, or “0” if the chunk split was in response to a user action.
The <TOAMovieWriterStartTime> tag is for internal use and is not intended for 3rd-party applications.
The <TOAMovieWriterPreviousClipname> tag’s text is the filename of the previous chunk in the recording, assuming that the value of the <TOAMovieWriterFirstSplit> is “0”. Otherwise this is the first chunk and this tag is not valid.
The <TOAMovieWriterLastSplit> tag’s text is “1” to indicate that this is the final chunk in the recording or “0” if more chunks can be expected.

For example, a status message push by just:in engine to the client when finishing one chunk will be as follows...

<recordingStatus channel=”example channel” name=”examplehost.local”>
	<rec>1</rec>
	...
	<TOAMovieWriterFrameCount>250<TOAMovieWriterFrameCount>
	<TOAMovieWriterClipname>/full/path/to/clip.mov</TOAMovieWriterClipname>
	<TOAMovieWriterFirstSplit>1</TOAMovieWriterFirstSplit>
	<TOAMovieWriterSplitted>1</TOAMovieWriterSplitted>
	<TOAMovieWriterStartTime>***do not use***</TOAMovieWriterStartTime>
	<TOAMovieWriterPreviousClipname>previous.mov</TOAMovieWriterPreviousClipname>
	<TOAMovieWriterLastSplit>0<TOAMovieWriterLastSplit>
</recordingStatus>

...while the message for a final chunk in a recording would be...

<recordingStatus channel=”example channel” name=”examplehost.local”>
	<rec>0</rec>
	...
	<TOAMovieWriterFrameCount>250<TOAMovieWriterFrameCount>
	<TOAMovieWriterClipname>/full/path/to/clip#2.mov</TOAMovieWriterClipname>
	<TOAMovieWriterFirstSplit>0</TOAMovieWriterFirstSplit>
	<TOAMovieWriterSplitted>1</TOAMovieWriterSplitted>
	<TOAMovieWriterStartTime>***do not use***</TOAMovieWriterStartTime>
	<TOAMovieWriterPreviousClipname>/full/path/to/clip.mov</TOAMovieWriterPreviousClipname>
	<TOAMovieWriterLastSplit>1<TOAMovieWriterLastSplit>
</recordingStatus>

“masterTimecode” message

Sent By	Server (just:in engine)
Definition	This message is sent every time the timecode changes (i.e. once per video frame) as follows: <masterTimecode channel=”example channel” name=”examplehost.local”> <hours>10</hours> <minutes>0</minutes> <seconds>0</seconds> <frames>0</frames> <source>0</source> </masterTimecode> The “channel” attribute on the root tag is the identifier of the channel for which this message is being sent. The “name” attribute on the root tag is the channel’s human-readable name. The <source> tag’s text is “0” for Computer Time, “1” for RS422 VTR, “2” for FireWire VTR, 3 for LTC over audio and “4” for Miranda Little Red LTC. The <hours>, <minutes>, <seconds> and <frames> tags’ text define the current timecode. The client receiving this message may choose to display this timecode in its user interface for example.
Response	This message does not require a response from the client.

“previewImage” message

Sent By	Server (just:in engine)
Definition	This message is sent when a new preview frame is available <previewImage channel=”example channel” name=”examplehost.local”> <previewData>data</previewData> <is16to9>0</is16to9> </previewImage> The “channel” attribute on the root tag is the identifier of the channel for which this message is being sent. The “name” attribute on the root tag is the channel’s human-readable name. The <previewData> tag’s text (shown as “data” above) is a base64 encoded 320x240 JPEG image. A client receiving this message can send the text through a base64 decoder and the resulting bytes to a JPEG decoder in order to display the resulting image in its user interface, for example. The <is16to9> tag’s text specifies “0” if the preview image has a 4:3 aspect ratio or “1” if the preview image has a 16:9 aspect ratio. Note that in both cases the image will be 320x240 but the client receiving this message can choose to respect this value when displaying the preview image.
Response	This message does not require a response from the client.

“audioMasterLevels” message

Sent By	Server (just:in engine)
Definition	This message is sent when a new audio levels are available as follows: <audioMasterLevels channel=”example channel” name=”examplehost.local”> <dbValue>-10.923123</dbValue> ... <dbValue>-inf</dbValue> </audioMasterLevels> The “channel” attribute on the root tag is the identifier of the channel for which this message is being sent. The “name” attribute on the root tag is the channel’s human-readable name. For each audio channel one <dbValue> tag will be sent in the message. The tag’s text is the value in dBu from -inf to 0. The number of <dbValue> entries is always 8 regardless of the number of audio channels currently being ingested. The client receiving this message can use the information to provide the user with a visualization of the audio levels coming in on the channel.
Response	This message does not require a response from the client.

“canRecord” message

Sent By	Server (just:in engine)
Definition	This message is sent once a second to indicate whether the engine is ready to record or not. <canRecord channel=”example channel” name=”examplehost.local”> <rec>0</rec> </canRecord> The “channel” attribute on the root tag is the identifier of the channel for which this message is being sent. The “name” attribute on the root tag is the channel’s human-readable name. The <rec> tag’s text value is “0” while the engine is not ready to record, or “1” if it is ready to record. The client receiving this message may reflect this status by, for example, enabling or disabling a “record” button for the channel in its user interface.
Response	This message does not require a response from the client.

“engineMemoryData” message

Sent By	Server (just:in engine)
Definition	This message is sent once a second to provide the client with information about the system’s current memory usage, for example: <engineMemoryData channel=”example channel” name=”examplehost.local”> <freeRam>6485114880</freeRam> <usedRam>2099990528</usedRam> <appRam>419320230</freeRam> </engineMemoryData> The “channel” attribute on the root tag is the identifier of the channel for which this message is being sent. The “name” attribute on the root tag is the channel’s human-readable name. The <freeRam> and <usedRam> tags’ text are values in bytes. The value of <freeRam> is the machine’s free and inactive memory and that of <usedRam> the active and wired memory. The sum of the <freeRam> and <usedRam> values is the total physical memory size of the machine on which just:in engine is running. The value of <appRam> defines how much memory just:in engine itself is currently using in bytes.
Response	This message does not require a response from the client.

“engineDiskData” message

Sent By	Server (just:in engine)
Definition	This message is sent once a second to provide the client with information about available disk space on the storage on which the high-resolution capture path folder is found. The message is as follows: <engineDiskData channel=”example channel” name=”examplehost.local”> <freeDiskSpace>1456356245</freeDiskSpace> <totalDiskSpace>2663432343</totalDiskSpace> </engineDiskData> The “channel” attribute on the root tag is the identifier of the channel for which this message is being sent. The “name” attribute on the root tag is the channel’s human-readable name. The <freeDiskSpace> and <totalDiskSpace> tags’ text define values in bytes. Note that Mac OS X 10.6.x uses a 10^3 base when calculating disk space (e.g. Finder) whereas just:in multi and just:in engine display these values using a 2^10 base. This means that the values specified in TB or GB in Finder and just:live multi / engine will be differ.
Response	This message does not require a response from the client.

“engineBufferStatus” message

Sent By	Server (just:in engine)
Definition	This message is sent once a second to inform the client about the engine’s video buffer. It is the same data just:in engine uses in its diagnostics window. The message is as follows: <engineBufferStatus channel=”example channel” name=”examplehost.local”> <bufferStatus>0.95</bufferStatus> </engineBufferStatus> The “channel” attribute on the root tag is the identifier of the channel for which this message is being sent. The “name” attribute on the root tag is the channel’s human-readable name. The <bufferStatus> tag’s text is a double value between “0” and “1”, where “0” indicates a full and “1” an empty buffer. If the client receiving this message wants to visualize this metric for the user then a value of “0” is very bad (the buffer is full when, for example, the storage system is too slow to write the data) and “1” is very good.
Response	This message does not require a response from the client.

“dropFrameCount” message

Sent By	Server (just:in engine)
Definition	This message is sent once a second to inform the client about any frames dropped during recording. It is sent as follows: <dropFrameCount channel=”example channel” name=”examplehost.local”> <dfCount>0</dfCount> </dropFrameCount> The “channel” attribute on the root tag is the identifier of the channel for which this message is being sent. The “name” attribute on the root tag is the channel’s human-readable name. The <dfCount> tag’s text indicates how many frames where dropped during recording. After stopping recording the count will be automatically reset to 0, so the value is only valid for the current recording.
Response	This message does not require a response from the client.

Ingest example scenarios

How do I start / stop recording on a channel?

Assuming that the 3rd-party application is connected to an engine via TCP/IP, the sequence of messages required to start recording on a channel and then stopping is as follows:

Action	Message sent by client	Response from just:in engine
Discover available channels	requestChannels	A list of available channels
Lock desired channel	requestLock	The lock status of the channel
Discover channel’s presets	requestSettingFileNames	A list of preset filenames
Load the desired preset	requestLoadSetting	Information about the loaded preset
Discover channel’s destination presets	requestDestinationSettingFileNames	A list of destination preset filenames
Load the desired destination preset	requestLoadDestinationSetting	Information about the loaded preset
Request start recording	requestRecording	Confirmation on recording status
Request stop recording	requestRecording	Confirmation on recording status
Release the channel (optionally)	requestLock	The lock status of the channel

The message flow would be as follows:

Client sends to just:in engine:

...and receives the following message...

<lock>0</lock>

</foundChannel>

...meaning that the channel with the identifier “channel1” is available and not currently locked / in use by another client. If the client then wishes to lock this channel is would send the following message:

<lock>1</lock>

<channelIdentifier>My Application</channelIdentifier>

</requestLock>

The channel identifier is the same as that from the “foundChannel” message and the <lock> tag indicates that the channel should be locked. The <channelIdentifier> tag specifies the name of the 3rd-party application locking the channel that will be displayed by all other clients on the network. The response, assuming the channel is successfully locked, would be...

<lock>1</lock>

<channelIdentifier>My Application</channelIdentifier>

</retConfirmLock>

Now that the client has confirmation that the channel is locked it can start to use the channel. First it must discover and select a preset by sending the message...

...with the response...

<name enabled=”1”>setting.justin</name>

</retRequestSettingFileNames>

Assuming that the client wishes to load the preset with the name “setting.justin” it must then send the message:

<requestLoadSetting channel=”channel1”>setting</requestLoadSetting>

Note that the “.justin” file extension has been removed from the name sent in the above message. Assuming the preset has been successfully loaded the response from just:in engine would be...

<codec>DV - PAL</codec>

...

</retLoadedSetting>

The client may choose to display some of the information related to the preset returned in the response to the user. Next the client must discover the channel’s destination presets by sending the message:

...to which the response from just:in engine might be...

<preset>setting.destination</preset>

</destinationPresets>

Assuming that the client wishes to load the preset with the name “setting.destination” it must then send the message:

<requestLoadDestinationSetting channel=”channel1”>setting</requestLoadDestinationSetting>

Note that the “.destination” file extension has been removed from the name sent in the above message. Assuming the destination preset has been successfully loaded the response from just:in engine would be...

<hirespath>/path/to/hires</hirespath>

...

</justinDestinationPreset>

</returnLoadedDestinationSetting>

The client may choose to display some of the information related to the destination preset returned in the response to the user.

Now the channel is fully configured and ready to start recording. To start the recording to a movie file with the name “recording,mov” the client would send the following message:

<requestRecording channel=”channel1”>recording.mov</requestRecording>

...to which the response would be two messages...

recording.mov

</retRequestFilename>

<rec>1</rec>

...

</recordingStatus>

The first message confirms the filename and indicates that it was not changed by just:in engine. In other words, the recording will be made to the exact filename requested by the client. The second message indicates that the channel is now records.

To stop the recording the client sends another “requestRecording” message as follows:

<requestRecording channel=”channel1”>recording.mov</requestRecording>

...to which the response would be...

<rec>0</rec>

...

</recordingStatus>

The recording is now finished and the movie file closed. The channel itself is also now free to initiate another recording at any time. Alternatively, if the client is now finished with the channel it should release (unlock) it so that other clients can use the channel. To do this it would send the following message...

<lock>1</lock>

</requestLock>