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.

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

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:

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

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:

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:

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:

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

Thus a chained container node could be defined as follows:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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>

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>

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:

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

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.

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:

“toaName” attribute

“toaStart” attribute

“toaDuration” attribute

“toaNaturalDuration” attribute

“toaInPoint” attribute

“toaOutPoint” attribute

“toaFadeIn” attribute

“toaFadeOut” attribute

“toaAudioFade” attribute

“toaInvertFields” attribute

“toaColor” attribute

“toaContainerType” attribute

“toaContainerAutoDuration” attribute

“toaContainerLoop” attribute

“toaTrack” attribute

“toaNextAction” attribute

“toaTransparentFade” attribute

“toaInterfaceMode” attribute

“toaHasCustomInterface” attribute

“toaPlayLoop” attribute

“toaVolume” attribute

“toaLiveVolume” attribute

“toaScheduledDuration” attribute

“toaStopFrames” attribute

“toaStopFrameTime” attribute

“toaStopFrameStartTimes” attribute

“toaStopFrameEndTimes” attribute

“toaInfiniteLength” attribute

“toaScheduledDuration” attribute

“toaSyncPoint” attribute

“toaEventScript” attribute

“toaPlaybackSpeed” attribute

“toaPlaybackDeinterlace” attribute

“toaCodec” attribute

“toaCodecString” attribute

“toaAspectRatio” attribute

“toaDisplayWidth” attribute

“toaDisplayHeight” attribute

“toa4to3in16to9Conversion” attribute

“toa4to3in4to3Conversion” attribute

“toa16to9in4to3Conversion” attribute

“toa16to9in16to9Conversion” attribute

“toaAllowResync” attribute

“toaFieldOrder” attribute

“toaFrameRate” attribute

“toaHoldTime” attribute

“toaContainerLocked” attribute

“toaTextColor” attribute

“toaAudioTracks” attribute

“toaPaused” attribute

“toaPlayStatus” attribute

“toaAudioMapping” attribute

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.

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

<retRequestNode>
	<node class=”1” id=”xxx” >
		... schedule XML nodes (playlists etc.) ...
	</node>
</retRequestNode>

“requestInsert” message

<requestInsert parentId=”xxx” exists=”T” setStart=”T”>
	<node id=”yyy” />
</requestInsert>

<requestInsert parentId=”xxx” beforeId=”yyy” setStart=”T”>
	<node class=”2” id=”zzz”>
		...further XML schedule nodes (e.g. tracks, play nodes)
	</node>
</requestInsert>

<retRequestInsert>
	<node id=”xxx” ...>
		... schedule XML nodes (playlists etc.) ...
	</node>
</retRequestInsert>

“requestUpdate” message

<requestUpdate>
	<node class=”2” id=”xxx”>
		... schedule XML nodes (tracks, play nodes etc.)
	</node>
</requestUpdate>

<retRequestUpdate>
	<node class=”2” id=”xxx” >
		... schedule XML nodes (tracks, play nodes etc.)
	</node>
</retRequestUpdate>

“requestAttribute” message

<requestAttribute>
	<attribute key=”toaFadeIn” type=”2”>2.0</attribute>
	<node>xxx</node>
	<node>yyy</node>
</requestAttribute>

<retRequestAttribute success=”T”>
	<attribute key=”toaFadeIn” type=”2”>2.0</attribute>
	<node>xxx</node>
	<node>yyy</node>
</retRequestAttribute>

“requestRemoveAttribute” message

<requestRemoveAttribute node=”xxx” key=”toaFadeIn” />

<retRequestRemoveAttribute node=”xxx” key=”toaFadeIn” />

“requestDelete” message

<requestDelete>
	<id>xxx</id>
	<id>yyy</id>
</requestDelete>

<retRequestDelete>
	<id>xxx</id>
	<id>yyy</id>
</retRequestDelete>

“requestWarnings” message

<requestWarnings from=”1.1.2011 12:00:00:00” to=”1.1.2011 13:00:00:00” />

<retRequestWarning>
	<warning>Gap at 12:30:00:00</warning>
</retRequestWarning>

<retRequestWarning />

“requestRealTimeContainer” message

<requestRealTimeContainer />

<requestRealTimeContainer>
	<node class=”7” id=”xxx”>
		...further Schedule XML nodes
	</node>
</requestRealTimeContainer>

<retRequestRealTimeContainer>
	<node class=”7” id=”xxx”>
		...further Schedule XML nodes
	</node>
</retRequestRealTimeContainer>

“requestFormat” message

“requestTracks” message

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

“playtrack” message

“cuedtrack” message

“nexttrack” message

“skiptrack” message

“playingNode” message

<playingNode id=”xxx”>
	<audioTracks>2</audioTracks>
	<timecode>1.1.2011 12:00:00:00</timecode>
	<nodeUID>yyy</nodeUID>
	<trackID>v0</trackID>
</playingNode>

<requestAttribute>
	<attribute key=”toaStart” type=”7”>1.1.2011 12:00:00:00</attribute>
	<node>xxx</node>
</requestAttribute>

“finishedNode” message

<finishedNode id=”xxx” replay=”F” skipped=”F” trackID=”v0”>
	<timecode>30.4.2012 12:30:00:00</timecode>
</finishedNode>

<requestDelete>
	<id>yyy</id>
</requestDelete>

<requestRemoveAttribute node=”xxx” key=”toaStart” />

<requestRemoveAttribute node=”xxx” key=” toaStopFrameStartTimes” />

<requestRemoveAttribute node=”xxx” key=” toaStopFrameStopTimes” />

“stopFrameNode” message

<stopFrameNode id=”xxx”>
	<timecode>30.4.2012 00:00:00:20</timecode>
</stopFrameNode>

<requestAttribute>
	<attribute key="toaStopFrameStartTimes" type="6">
		<array>
			<timecode>00:00:00:20</timecode>
		</array>
	</attribute>
	<node>xxx</node>
</requestAttribute>

“triggerNode” message

<triggerNode id=”xxx”>
	<timecode>00:00:00:30</timecode>
</triggerNode>

<requestAttribute>
	<attribute key="toaStopFrameEndTimes" type="6">
		<array>
			<timecode>00:00:00:30</timecode>
		</array>
	</attribute>
	<node>xxx</node>
</requestAttribute>

“heartbeat” message

“engineLost” message

<engineLost>Some-Mac-Pro</engineLost>

“unblockTime” message

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

<requestInsert parentId=”xxx”>

<node id="FCA96D93-5EB5-40DE-8D96-BB0BEFAEAA25" class="2">

<attribute key="toaColor" type="8">#808080ff</attribute>

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

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

<attribute key="toaContainerType" type="4">0</attribute>

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

<attribute key="toaContainerLoop" type="1">1</attribute>

<attribute key="toaContainerAutoDuration" type="3" flags="1">F</attribute>

<node id="E90DBB38-097D-4D5D-A8E3-BB349AA73C29" class="3" trackId="g0">

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

<requestInsert parentId=”xxx”>

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

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 parentId=”yyy”>

<node id=”zzz” class=”7” reference=”56202871-D71C-4416-9EEC-4AC3D58B0E43” trackId=”g0” />

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

<requestAttribute>

<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

<requestChannels />

<foundChannel channel=”example channel” name=”examplehost.local”>
	<lock>0</lock>
	<channelIdentifier></channelIdentifier>
</foundChannel>

“requestLock” message

<requestLock channel=”example channel”>
	<lock>1</lock>
	<channelIdentifier>example client</channelIdentifier>
</requestLock>

<retConfirmLock channel=”example channel” name=”examplehost.local”>
	<lock>1</lock>
	<channelIdentifier>example client</channelIdentifier>
</retConfirmLock>

“requestSettingFileNames” message

<requestSettingFileNames channel=”example channel” />

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

“requestLoadSetting” message

<requestLoadSetting channel=”example channel”>example setting name</requestLoadSetting>

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

“requestDestinationSettingFileNames” message

<requestDestinationSettingFileNames channel=”example channel” />

<destinationPresets channel=”example channel” name=”examplehost.local”>
	<preset>first.destination</preset>
	<preset>second.destination</preset>
	...
	<preset>last.destination</preset>
</destinationPresets>

“requestLoadDestinationSetting” message

<requestLoadDestinationSetting channel=”example channel”>
	<presetName>exampleDestinationPreset</presetName>
</requestLoadDestinationSetting>

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

“requestFilename” message

<requestFilename channel=”example channel”>exampleName.mov</requestFilename>

<retRequestFilename channel=”example channel” name=”examplehost.local” didChange=”F”>
	exampleName.mov
</retRequestFilename>

“requestRecording” message

<requestRecording channel=”example channel”>exampleName.mov</requestRecording>

<recordingStatus channel=”example channel” name=”examplehost.local”>
	<rec>1</rec>
	<hours>10</hours>
	<minutes>0</minutes>
	<seconds>0</seconds>
	<frames>0</frames>
</recordingStatus>

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

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

<masterTimecode channel=”example channel” name=”examplehost.local”>
	<hours>10</hours>
	<minutes>0</minutes>
	<seconds>0</seconds>
	<frames>0</frames>
	<source>0</source>
</masterTimecode>

“previewImage” message

<previewImage channel=”example channel” name=”examplehost.local”>
	<previewData>data</previewData>
	<is16to9>0</is16to9>
</previewImage>

“audioMasterLevels” message

<audioMasterLevels channel=”example channel” name=”examplehost.local”>
	<dbValue>-10.923123</dbValue>
	...
	<dbValue>-inf</dbValue>
</audioMasterLevels>

“canRecord” message

<canRecord channel=”example channel” name=”examplehost.local”>
	<rec>0</rec>
</canRecord>

“engineMemoryData” message

<engineMemoryData channel=”example channel” name=”examplehost.local”>
	<freeRam>6485114880</freeRam>
	<usedRam>2099990528</usedRam>
	<appRam>419320230</freeRam>
</engineMemoryData>

“engineDiskData” message

<engineDiskData channel=”example channel” name=”examplehost.local”>
	<freeDiskSpace>1456356245</freeDiskSpace>
	<totalDiskSpace>2663432343</totalDiskSpace>
</engineDiskData>

“engineBufferStatus” message

<engineBufferStatus channel=”example channel” name=”examplehost.local”>
	<bufferStatus>0.95</bufferStatus>
</engineBufferStatus>

“dropFrameCount” message

<dropFrameCount channel=”example channel” name=”examplehost.local”>
	<dfCount>0</dfCount>
</dropFrameCount>

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:

The message flow would be as follows:

Client sends to just:in engine:

<requestChannels />

...and receives the following message...

<foundChannel channel=”channel1” name=”channel1.local”>

<lock>0</lock>

<channelIdentifier></channelIdentifier>

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

<requestLock channel=”channel1”>

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

<retConfirmLock channel=”channel1l” name=”channel1.local”>

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

<requestSettingFileNames channel=”channel1l” />

...with the response...

<retRequestSettingFileNames channel=”channel1” name=”channel1.local”>

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

<retLoadedSetting channel=”channel1” name=”channel1.local” filename=”/Library/Application Support/ToolsOnAir/Just In/setting.justin”>

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

<requestDestinationSettingFileNames channel=”channel1” />

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

<destinationPresets channel=”channel1” name=”channel1.local”>

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

<returnLoadedDestinationSetting channel=”channel1” name=”channel1.local”>

<justinDestinationPreset name=”setting”>

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

<retRequestFilename channel=”channel1” name=”channel1.local” didChange=”F”>

recording.mov

</retRequestFilename>

<recordingStatus channel=”channel1” name=”channel1.local”>

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

<recordingStatus channel=”channel1” name=”channel1.local”>

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

<requestLock channel=”channel1”>

<lock>1</lock>

</requestLock>