Broadcast Suite Communication Protocol
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
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>
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:
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.
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:
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”.
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:
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 |
“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 |
“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 |
“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 |
“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 |
“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 |
“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 |
“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:
|
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 |
“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:
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 |
“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 |
“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:
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 |
“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 |
“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 |
“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:
|
Required For Node Class | None |
Optional For Node Class | 5 (Play) |
Required for UI | No |
“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:
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 |
“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:
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 |
“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 |
“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 |
“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 |
“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 |
“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 |
“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 |
“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 |
“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 |
“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 |
“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 |
“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 |
“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 |
“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 |
“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):
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):
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):
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
- Play
- Track
- Play
- Play
- Track
- Playlist
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 folder
- Real-time schedule folder
- Real-time play
- Real-time play
- Real-time play
- Real-time contents playlist / folder
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
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 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 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>
|
“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 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 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:
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:
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:
|
“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. |
“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:
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:
|
“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:
|
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:
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:
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”...
<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&quo