amcp: avid machine control protocolresources.avid.com/supportfiles/attach/amcp system guide...

AMCP: Avid Machine Control Protocol

System Specifications Version 2.4

January 28, 2008

1. Introduction

This document defines the Avid Machine Control Protocol, AMCP. AMCP is the protocol used by the Avid iNEWS Newsroom Control System, NRCS, to communicate machine control information to the ControlAir broadcast control system. AMCP transmits information about rundowns, stories, events, and device configuration.

2. Revision History

Version 2.4 January 28, 2008 Adds optional Story Edit Update message for MOS Gateway servers only.

Version 2.3 February 02, 2004 Updates String Data Format; removes Multi-byte strings and defines Unicode encoding scheme. Corrects return values for Connection Request and Refuse Connection messages.

Version 2.2 February 7, 2003 Adds video channel information to Event Status message.

Version 2.1 May 24, 2001 Adds optional channel information to Start Load message for MOS Gateway servers only.

Version 2.0 June 15, 2000 Adds Style name fields to CG and Still Store events. Adds MOS event type.

Version 1.2 June 13, 1997 Initial Release.

3. Overview

AMCP is a socket-based, TCP/IP, asynchronous, master/slave protocol. The Newsroom Computer System acts as master and initiates conversations, the ControlAir system acts as slave, but can initiate messages in an already existing connection.

3.1 Roles

3.1.1 The Newsroom Host

The newsroom host drives the process. Prior to show time, a user, usually the producer starts a special process that begins tracking changes to a rundown. When instructed to do so, this process initiates a connection to the machine control host and transfers information about the show. The process continues to monitor any changes to the show and communicates those changes to the machine control host.

Copyright 2008 by Avid Technology, Inc.

The newsroom host opens a Berkeley style TCP socket to the machine control host and connects on port number 6825. Only one show may be transmitted on a given socket, to communicate information about multiple shows requires a new socket for each show.

The Avid iNEWS NRCS server is considered to be the reference implementation for the newsroom host side of AMCP.

3.1.2 The Machine Control Host

The machine control host is a computer that responds to messages from the news host about show rundowns along with the associated devices, stories, and events. It reports the status of items back to the newsroom host. The machine control host also provides facilities for a user interface and controls the various production devices.

The machine control host must listen on port 6825 and provide a separate handler for each connection.

The Avid ControlAir system is considered to be the reference implementation for the machine control side of AMCP.

3.2 New Features

3.2.1 Style Names for CG and Still Store Events

A new field has been added to the CG and Still Store Event messages in AMCP version 2.0. That field, a string, contains the name of the style that determines the format of a CG or Still Store event. The affected messages are Add Event and Replace Event. The style name field is used primarily for user information and is displayed on the CAWS.

3.2.2 MOS Devices and Events

A new event type, MOS, was added in AMCP version 2.0. These events are destined for devices that use the MOS protocol for remote control. MOS events are not sent to the Avid ControlAir system. Instead, they are sent to a different server process, the Avid iNEWS MOS Gateway server. Only MOS events are sent to the MOS Gateway.

This new server listens for connections on a port 6826. It may be on the same computer as the ControlAir server, but must be identified by a different name. Therefore, to run a MOS gateway and the Avid ControlAir server on the same computer, assign an alias name to the computer so it can be located on the network by two distinct names.

Production cues intended for MOS devices are not parsed or interpreted by the Avid iNEWS NRCS. Instead, they are entered into rundown stories by third-party plug-ins. The Avid iNEWS NRCS encapsulates these event requests in an AMCP message and sends them to the Avid MOS Gateway server, which communicates directly with the MOS devices using the MOS Protocol.

The affected messages are Initialize Rundown Data, Start Load, Add Event and Replace Event.

A MOS only message, Story Edit Update, was added in version 2.4.

3.3 Messages

The machine control host must respond to almost all messages it receives with a Ready To Receive message. There are two exceptions. The Establish Connection message requires either an Accept Connection or a Refuse Connection. The Disconnect message requires an Acknowledge Disconnect message to acknowledge that the connection will be closed. The Ready to Receive message is required by the Avid iNEWS NRCS host to enable ControlAir coexistence with legacy machine control systems.


If any message is malformed, or it generates some other error condition, a Ready To Receive message is sent followed by an Error Message describing the problem. If, for any reason, the machine control side finds that it is unable to continue the conversation, due to lack of resources, data corruption, or other catastrophic failure, it should send a ControlAir Abort message to the newsroom host. This usually means that human intervention is required to correct the problem before re-establishing the connection.

The high pressure environment of a television newsroom generally requires that problems be identified as soon as possible, therefore Avid recommends that the timeout for AMCP connections be set low. However, if there is a WAN in between the newsroom host and the machine control host, the timeout may need to be set longer. In the Avid iNEWS implementation, the timeout is configurable, with a default of 15 seconds.

Command Code Message Name Direction Additional data?

0x42 Establish Connection NRCS to CA yes

0x46 Initialize Rundown Data NRCS to CA yes

0x70 Start Load NRCS to CA MOS yes, else no

0x71 Add Story NRCS to CA yes

0x72 Add Event NRCS to CA yes

0x48 End-of-Load NRCS to CA no

0x4d Update Story Information NRCS to CA yes

0x75 Story Edit Update NRCS to MOSGW no

0x4b Replace Event NRCS to CA yes

0x73 Delete Story NRCS to CA no

0x49 Delete Event NRCS to CA no

0x4a Reorder Stories NRCS to CA yes

0x44 Verify Connection NRCS to CA no

0x74 Request Event Status NRCS to CA no

0x5a Disconnect NRCS to CA no

0x43 Accept Connection CA to NRCS no

0x5b Refuse Connection CA to NRCS no

0x45 Verify Connection CA to NRCS no

0x45 Ready To Receive CA to NRCS no

0x43 Acknowledge Disconnect CA to NRCS no

0x4e Event Status CA to NRCS yes

0x5d Error Messages CA to NRCS yes

0x5e ControlAir Abort CA to NRCS yes


4. Protocol

4.1 Data Formats

AMCP uses the following data formats. All numeric data is in Network, i.e. Big-Endian, order:

String (variable length - minimum 2 bytes):

All AMCP string data will be in the following format: an unsigned short integer containing the size, in bytes, of the string (including a terminating null), followed by a null-terminated string of the correct size. An empty String is represented with a size of zero: no string follows. String characters may be 8-bit, unsigned values or Unicode values encoded as UTF16LE. Only one type of string format may be used for any connection. Unicode strings should not include a BOM. The type of characters used in the string is determined from the Establish Connection message.

Binary (variable length - minimum 2 bytes):

The binary data type is similar to the string data type except no restrictions are made on the contents. An empty binary datum is represented with a size of zero. The current versions of AMCP do not use this data type.

Time (4 bytes): All AMCP durations will be sent in the following format: 4 BCD (binary-coded decimal) bytes representing time in frames, seconds, minutes and hours, i.e. FFSSMMHH. All four bytes must be filled in, e.g. a one minute and 30 second duration is represented as 0x00 0x30 0x01 0x00. An empty time value is represented with four 0xFF bytes. Impossible time data will generate an AMCP_ERR_TIME error.

Byte Data (1 byte): An 8-bit, unsigned value (0x00 - 0xFF) stored in one byte.

Numeric Data (2 or 4 byte integers):

Numeric data can be sent as short integers, two bytes (16-bit) long, or long integers, four bytes (32-bit) long. All numeric values must be passed in network (Big-Endian) order, i.e. msb, lsb for two-byte short integers and msw-msb, msw-lsb, lsw-msb, lsw-lsb for four-byte long integers. There is no provision for sending floating point numbers.

4.2 Message Format

All AMCP messages contain a 16-byte message header. Some also contain additional data of variable-length. The format of a message header is the same for all commands. The format of the additional data, if required, depends on the command. Simple messages will be complete with the transmission of the header.

Message header format:

Header:

Data length (two-byte number):

Length of the message data which follows header. Zero when no data follows.

Version Code (one byte): Constant value that identifies the version number of this message. The version of AMCP described by this document uses the version code 0x25.


Command Code (one byte): Identifies the command type.

Event ID (four-byte number):

Unique event identifier. Zero if this message does not reference an event.

Story ID (four-byte number):

Unique story identifier. Zero if this message does not reference a story.

Parameter (four-byte number):

Optional parameter for this message. Zero if this message does not require a parameter.

The following errors can result from data in a message header:

AMCP_ERR_BAD_VERSION Version code is not 0x22 (version 2.0) or 0x21 (version 1.2).

AMCP_ERR_BAD_COMMAND The command code is not recognized.

AMCP_ERR_EVENT_ID The event ID is not unique or it doesn’t exist.

AMCP_ERR_STORY_ID The story ID is not unique or it doesn’t exist.

AMCP_ERR_FORMAT The message is malformed and the receiving host is unable to parse it. May also result if the version code does not match the data format.

4.3 Message List

4.3.1 NRCS to ControlAir:

Establish Connection

Header:

Data length: Length of the message data which follows header.

Command Code: 0x42

Event ID: Zero.

Story ID: Zero.

Parameter: byte 1 - reserved

byte 2 - reserved

byte 3 - NRCS type

0x01 – Avid iNEWS NRCS

0x02-0x7f - reserved

0x80-0xff - other

byte 4 - string type

0x01 – ASCII (8-bit)

0x02 – reserved

0x03 – reserved


0x04 – UTF16LE

0x05-0xff – undefined

NRCS requests a connection to the ControlAir server. One component of the ControlAir system, the AMCP module, handles all messages related to this play list. It verifies that a message is a valid Connection Request, extracts Rundown/Lineup data from the message, signs-in with the ControlAir controller and returns an Accept Connection message. In the event of an error condition, a Refuse Connection message is returned instead.

After the NRCS receives an Accept Connection message, it immediately sends an Initialize Rundown Data message containing the Device Manager configuration information required for this show.

The NRCS Type is used to enable or disable certain AMCP features to ensure compatibility with different NRCS types. NRCS types up to 0x7f are reserved for Avid iNEWS NRCS. Other types will be assigned as needed. Values of 0x80 through 0xff may be used by non-Avid systems.

The string type specifies what kind of strings is used by the system. Not all implementations work with all string types.

Data:

AMCP Version Number (string):

The version number string is for display purposes and error messages. The header version code will be used to guarantee that the message format used by the NRCS is compatible with the receiving AMCP module.

Rundown/Lineup Name (string):

The name of the NRCS rundown/lineup queue (or equivalent).

NRCS Name (string):

The network name of the NRCS machine.

The following errors are possible responses:

AMCP_ERR_BAD_ VERSION The AMCP version is not recognized or supported by the receiving program; some older versions of ControlAir do not support newer features.

AMCP_ERR_BAD_NRCS The NRCS type is not recognized.

AMCP_ERR_BAD_STRING The string type is not recognized.


Initialize Rundown Data Message

Header:


Command Code: 0x46

Event ID: Zero

Story ID: Zero

Parameter: Play list sequence number.

After the NRCS receives an Accept Connection message, it immediately sends an Initialize Rundown Data message containing the Device Manager configuration information required for this show. The data portion will contain the Rundown Data listed below followed by the device data for each device associated with this rundown. Device data can be appended in any order, but must contain the correct number of fields for the device type.

The play list sequence number is used to put play lists in the proper order. Lower numbered shows preceded higher numbered ones.

Improper data can generate an AMCP_ERR_DATA error.

Rundown Data:

Device Count (byte):

The number of Device Managers that will be used by this rundown; must be at least one. The configuration information for each of these Device Managers follows in any order. The device type determines the length of the data required.

Show Quit Time (time - four bytes):

Optional. If used, this field specifies a duration that the NRCS rundown will be active. It will be added to the current time to establish the quit time for the show. If the connection with the NRCS is lost, the ControlAir server will preserve the rundown play list until this time is reached. Can be used to prevent an interruption in playback due to network problems. If unused, the field must contain four 0xFF bytes.

Display Format (string):

The Display Format contains all the textual data that will be displayed on the CAWS with the story. It must be a valid Avid NSML Form description and must contain all the fields that are to be displayed on the CAWS. Field data will be included in the Add Story and Update Story Information messages.

Video Device Data:

Device Type (byte): 0x01

Event Status Update Filtering (byte): A bit mask to indicates what level of event status the NRCS will report for this particular device:

0x00 - no status

0x01 - error status only

0x02 - include event availability status

0x04 - include event play status

Method of channel assignment (byte): Indicates how channel assignments will be made:


0x00 - Video device assigns channels

0x01 - NRCS assigns channel

0x02 - Device Manager assigns channel

0x03 - CAWS assigns channel

Device Name (string): Unique device name. Must match name of video device manager configured on the ControlAir server.

Character Generator Data:



0x00 - no status




Reserved (byte) Zero

Device Name (string): Unique device name. Must match name of character generator device manager configured on the ControlAir server.

Template Drive Name/Number (string): Name or number of the drive where template messages used by this show are stored on the character generator.

Template Directory Name (string): Name of directory where template messages used by this show are stored on the character generator.

Message Drive Name/Number (string): Name or number of the drive where the device manager must record newly created CG messages.

Message Directory Name (string): Name of directory where the device manager must record newly created CG messages.

Still Store Data:



0x00 - no status




Reserved (byte) Zero


Device Name (string): Unique device name. Must match name of still store device manager configured on the ControlAir server.

Image Drive Name/Number (string): Name or number of drive where still images used by this show are stored on the still store.

Image Directory Name (string): Name of directory where still images used by this show are stored on the still store.

Stack/List Name/Number (string): Name or number of a stack or play list where the device manager will record a list of still images for recall.

MOS Device Data:



0x00 - no status



0x04 - include event play status.

Reserved (byte).: Zero.

Device Name (string): Unique device name. Must match name of MOS device manager configured on the MOS Gateway server.


Start Load

Header:

Data length: Length of the message data which follows header for MOS servers only. Otherwise zero.

Command Code: 0x70

Event ID: Zero.

Story ID: Zero.

Parameter: Download sequence number

The Start Load message signals the beginning of a play list download. The purpose of delimiting a playlist download is to accommodate certain devices that need to receive all their playlist information at once. A download begins with a Start Load, is followed by a series of Add Story and Add Event messages, and ends with an End-of-load message. No other messages are allowed between the start and the end. If a different message is received, an AMCP_ERR_BAD_COMMAND error will be generated.

The End-of-load message must have the same sequence number as the corresponding Start Load.

After the End-of-load message is received, stories and events may be added, deleted, or modified in any order.

Data:

MOS Channel Information (string):

This field applies only to connections made to the Avid MOS Gateway server. Some MOS devices require channel information at the start of load. That channel information is passed with the Start load message. The Channel Information string may be empty. If not empty it contains MOS roChannel data in MOS protocol format. (New in version 2.1.)

Add Story

Header:


Command Code: 0x71

Event ID: Zero.

Story ID: Unique story identifier.

Parameter: Unique story identifier of the story that precedes this one in the play list. A value of zero indicates that this is the top story in the play list.

The Add Story message includes story information and may be followed by one or more Add Event messages containing event data. Stories are inserted into the play list after the story specified in the message header (or at the top of the play list if the previous story indicator is zero).


After load is complete, i.e. an End-of-load message was received, the Add Story message will add new stories to the existing play list.

It is an error to add a story whose ID number is not unique. It is also an error to add a story whose preceding story does not exist. In both cases the Add Story should be ignored and an AMCP_ERR_STORY_ID error sent back to the newsroom host.

Data:

Story Name/Title (string):

The story name or title is displayed on the CAWS. It is not necessary for it to be unique within a play list, but this would help avoid operator confusion. The ControlAir system identifies stories by their Story ID and will not confuse two stories with the same name.

Display Text (string):

The Display Text contains all the textual data that will be displayed on the CAWS with the story. It must be a valid Avid NSML Field description and should contain all the fields defined in the rundown Display Format section of the Initialize Rundown Data message. Fields not defined in the Display Format will be ignored.

Add Event

Header:


Command Code: 0x72

Event ID: Unique event identifier.

Story ID: Story identifier. Story must have been previously added to play list.

Parameter: Unique event identifier of the event which precedes this one in the story. A value of zero indicates that this is the top event in the story.

The Add Event message contains event data. It will place a new event into a story's event list at a location specified in the message. The story must be created before events are placed in its event list.

It is an error condition for any event message to reference a non-existent story. Other error conditions are a non-unique ID number and non-existent preceding event. Any of these conditions will result in an AMCP_ERR_EVENT_ID error sent back to the newsroom host.

If an event references a device name that was not included in the Initialize Rundown message, an AMCP_ERR_DEVICE error is generated.

It is an error to name a Device Manager that was not included in the rundown’s list of devices.

Break Event Data:

Event Type (byte): 0x01 - Break Event

Channel Assignment (byte): 0x00 - N/A

Device Manager Name (string): Name of device for this event. Must match name of video device manager configured on the ControlAir server.

Break Duration (time - four bytes): An optional duration for the break event. If unused, the field must contain four 0xFF bytes.


Video Event Data:

Event Type (byte): 0x02 - Video Event

Channel Assignment (byte): The channel assignment for this event, ignored if the NRCS does not assign channels for this device. The physical device determines the highest channel value.

0x00 - None or N/A

0x01 - Channel A

0x02 - Channel B

0x03 - Channel C, etc. . . .


Media (Tape/Clip) ID (string): Name or number that identifies the video event on the device.

Video Duration (time - four bytes): The duration of the video event. If unused, the field must contain four 0xFF bytes.

Offset from beginning of media (time - four bytes):

A start position offset from the beginning of a video event. May not be applicable to all video devices. If unused, the field must contain four 0xFF bytes.

Character Generator Event Data:

Event Type (byte): 0x03 - Character Generator Event


0x00 - None or N/A

0x01 - Channel A

0x02 - Channel B



Trigger Count (byte): Number of play triggers required to complete the play of this event. For most events, this must be one. Some animation sequences may require multiple triggers to complete. (The CAWS cursor will not advance to the next event until the Play key is pressed by the number of Trigger Count times.)

Message Address (string): Name or number that identifies where the CG event was/will be recorded on the Character Generator.

Template Address (string): Name or number of the template message used for this event. Empty if the message was pre-recorded on the CG.


Effect Name (string): Name of playback effect that may be associated with this event (optional).

CG Text (string): Zero or more text fields plus termination string. Each field of CG text is sent as a separate string. Blank fields are represented with a string containing only spaces. The sequence must be terminated with one additional empty string.

Style Name (string): Name of the style that describes the format of this event (optional). This field is primarily used for CAWS display. (New in version 2.0.)

Still Store Event:

Event Type (byte): 0x04 - Still Store Event


0x00 - None or N/A

0x01 - Channel A

0x02 - Channel B




Image Address (string): Name or number that identifies the location of the still image on the Still Store.

Preset Name/Number (string): Name or number of a preset style used for this event (optional).



MOS Event:

Event Type (byte): 0x05 - MOS Event (New in version 2.0)


MOS Device Name (string): Name of device for this event. Must match name of MOS device configured on the MOS Gateway server.


MOS Item (string): MOS item created by ActiveX control.

End-of-Load

Header:

Data length: Zero.

Command Code: 0x48

Event ID: Zero.

Story ID: Zero.

Parameter: Download sequence number

An End-of-load message is sent to signal the end of the download. All subsequent event messages are updates to the play list. Some devices, which cannot handle dynamic play list updates, may only be loaded once, upon the receipt of this message.

An AMCP_ERR_ILLEGAL_END error will be sent if an End-of-load message is sent without first sending the corresponding Start Load.

Update Story Information

Header:


Command Code: 0x4D

Event ID: Zero.


Parameter: Zero.

An Update Story Information message contains only the text information that will be displayed on the CAWS. No changes are made to any of the events in the story's event list. The story must already exist in the play list.

It is an AMCP_ERR_STORY_ID error to update a story whose ID is not part of the playlist.

Data:

Story Name/Title (string):

The story name or title is displayed on the CAWS. It is not necessary for it to be unique within a play list, but this would help avoid operator confusion. The ControlAir identifies stories by their Story ID and will not confuse two stories with the same name.

Display Text (string):

The Display Text contains all the textual data that will be displayed on the CAWS with the story. It must be a valid Avid NSML Field description and should contain all the fields defined in the rundown Display Format. Fields not defined in the Display Format will be ignored.

Story Edit Update Header:


Data length: Zero

Command Code: 0x75

Event ID: Zero


Parameter: Zero

A Story Edit Update message indicates the specified story has been edited. It is sent regardless of whether or not any events contained in its event list are changed, and always after all other messages resulting from the story edit have been sent. This message applies only to connections made to the Avid MOS Gateway server.

It is an error condition for a Story Edit Update message to reference a non-existent story. An AMCP_ERR_STORY_ID would be sent.

Replace Event

Header:


Command Code: 0x4B

Event ID: Event identifier. Event must have been previously added to story.


Parameter: Zero

The Replace Event message contains event data. It will replace an existing event in a story's event list with the new data contained in the message. Both the story and the referenced event must exist. The Replace Event message must not be used to change the type of an event or the Device Manager to which it is assigned. If it is necessary to change either of those attributes, first delete the event and then add the new event. All other attributes of an event may be changed with this message. An illegal Replace Event will result in an AMCP_ERR_DATA error.

It is an AMCP_ERR_EVENT_ID error to replace an event that is not part of the story.

Break Event Data:

Event Type (byte): 0x01 - Break Event



Break Duration (time - four bytes): An optional duration for the break event. If unused, the field must contain four 0xFF bytes.

Video Event Data:

Event Type (byte): 0x02 - Video Event



0x00 - None or N/A

0x01 - Channel A

0x02 - Channel B



0x00 - None or N/A

0x01 - Channel A

0x02 - Channel B



Media (Tape/Clip) ID (string): Name or number that identifies the video event on the device.

Video Duration (time - four bytes): The duration of the video event. If unused, the field must contain four 0xFF bytes.

Offset from beginning of media (time - four bytes):

A start position offset from the beginning of a video event. May not be applicable to all video devices. If unused, the field must contain four 0xFF bytes.

Character Generator Event Data:

Event Type (byte): 0x03 - Character Generator Event


0x00 - None or N/A

0x01 - Channel A

0x02 - Channel B



Trigger Count (byte): Number of play triggers required to complete the play of this event. For most events, this must be one. Some animation sequences may require multiple triggers to complete. (The CAWS cursor will not advance to the next event until the Play key is pressed by the number of


Trigger Count times.)

Message Address (string): Name or number that identifies where the CG event was/will be recorded on the Character Generator.

Template Address (string): Name or number of the template message used for this event. Empty if the message was pre-recorded on the CG.


CG Text (string): Zero or more text fields plus termination string. Each field of CG text is sent as a separate string. Blank fields are represented with a string containing only spaces. The sequence must be terminated with one additional empty string.


Still Store Event:

Event Type (byte): 0x04 - Still Store Event


0x00 - None or N/A

0x01 - Channel A

0x02 - Channel B




Image Address (string): Name or number that identifies the location of the still image on the Still Store.

Preset Name/Number (string): Name or number of a preset style used for this event (optional).




MOS Event:

Event Type (byte): 0x05 - MOS Event (New in version 2.0)



MOS Item (string): MOS item created by ActiveX control.

Delete Story Header:

Data length: Zero

Command Code: 0x73

Event ID: Zero


Parameter: Zero

A Delete Story message removes the specified story, including all the events contained in its event list, from the play list.

It is an error condition for a Delete Story message to reference a non-existent story. An AMCP_ERR_STORY_ID would be sent.

Delete Event

Header:

Data length: Zero

Command Code: 0x49



Parameter: Zero

A Delete Event message removes the specified event from a story's event list. Both the story and the referenced event must exist. Otherwise, an AMCP_ERR_EVENT_ID or AMCP_ERR_STORY_ID will be sent.

Re-order Stories

Header:


Command Code: 0x4A


Event ID: Zero

Story ID: Zero

Parameter: Number of stories in the playlist.

A Re-order Stories message changes the order of stories in a play list. It contains a list of Story IDs in the new order. The list must contain one instance of the Story ID for each story in the play list; it must not contain duplicate entries or IDs for stories not in the play list. If a re-order request fails to meet these requirements, it will not be executed and an error message will be returned.

It is an AMCP_ERR_DATA error if the number of stories in the reorder list is different than the number of stories in the playlist.

Data:

Story ID List (list of four-byte Story Ids)

A list containing one Story ID for each story in the play list. The order of IDs in the list is the new order of stories in the play list.

Verify Connection

Header:

Data length: Zero

Command Code: 0x44

Event ID: Zero

Story ID: Zero

Parameter: Zero

An optional polling message may be sent during idle periods to verify that the connection is still active and that the ControlAir server is still accepting data. This message will be acknowledged with a Ready to Receive, but no other action will be taken.

Request Event Status

Header:

Data length: Zero

Command Code: 0x74



Parameter: Zero, or non-zero to get status for all events in a playlist.

ControlAir returns individual event status asynchronously whenever the event's status changes at the device. The NRCS may optionally send a Request Event Status message to get the current status of any play list event. Current status for the event is obtained from the appropriate Device Manager. The response to this message is an Event Status message for the requested event from ControlAir.

If the EventID and StoryID are both zero, and the parameter is non-zero, then an Event Status message is returned for every event in the playlist.


If EventID, StoryID, and the parameter are all zero, an AMCP_ERR_DATA message will result.

Disconnect

Header:

Data length: Zero.

Command Code: 0x5A

Event ID: Zero.

Story ID: Zero.

Parameter: Zero.

A Disconnect message indicates that the NRCS no longer wishes to maintain the play list on the ControlAir server. The network connection to the NRCS will be closed. If/when the CAWS is also disconnected, the play list will be cleared from the device and removed from the ControlAir server.

4.3.2 ControlAir to NRCS:

Accept Connection

Header:

Data length: Zero

Command Code: 0x43

Event ID: Zero

Story ID: Zero

Parameter: Zero

When ControlAir has received and validated an NRCS connection request, successfully created a new play list, and established a network connection to the NRCS, it returns an Accept Connection message.

Refuse Connection

Header:

Data length: Zero

Command Code: 0x5B

Event ID: Zero

Story ID: Zero

Parameter: Status code for the reason connection request was rejected.

0x11 - Unsupported AMCP version (AMCP_ERR_BAD_VERSION)

0x22 - Unknown NRCS type (AMCP_ERR_BAD_NRCS)


0x14 - Unsupported string type (AMCP_ERR_BAD_STRING)

0x03 - ControlAir system error, needed resources unavailable

ControlAir has received an NRCS Connection Request and was unable to accept it. This error might occur if the NRCS was using an unsupported AMCP version or if the NRCS type was not supported by this ControlAir system. ControlAir may also refuse a connection if the available memory or other system resources are unavailable. For performance reasons, some future limit may be placed on the number of concurrent connections allowed.

Ready to Receive

Header:

Data length: Zero

Command Code: 0x45

Event ID: Zero

Story ID: Zero

Parameter: Zero

The machine control host sends this message in reply to every type of message except for the Establish Connection and Disconnect messages. It means that the sending host has completed processing the previous message and is ready to receive the next message.

Acknowledge Disconnect

Header:

Data length: Zero.

Command Code: 0x43

Event ID: Zero.

Story ID: Zero.

Parameter: Zero.

When ControlAir receives a Disconnect request, it returns an Acknowledge Disconnect message and closes the network connection to the NRCS. Note that the Acknowledge Disconnect message has the same command code value as the Accept Connection message. The reason for this is to allow the Avid iNEWS NRCS host to enable ControlAir coexistence with legacy machine control systems.

Event Status

Header:


Command Code: 0x4E




Parameter: Status code

0x00 - Unknown Status

0x01 - Event Unavailable

0x02 - Event Available

0x03 - Event Standby

0x04 - Event Cueing

0x05 - Event Cued

0x06 - Event Tension Released (Tape only)

0x07 - Event Play Requested

0x08 - Event Playing (on-air)

0x09 - Event Paused

0x0A - Event Stopped

0x0B - Event Rewinding (Tape only)

0x0C-0x7F - reserved

0x80-0xFE - available for other status codes

0xFF - Event in Error Condition

Individual event status is returned asynchronously whenever the Device Manager detects that the event’s status has changed. Event status will also be returned in response to a Request Event Status message from the NRCS. ControlAir does not report status for Break Events.

An event has an “unknown” status from the time it is first added to a playlist until a device manager reports a status for it. Once a device manager processes an event, it will report a status other than “unknown”. If the event cannot be found or created, that status will be “unavailable” or “error”, as appropriate.

Data:

Event Type (byte):

The type of this event:

0x02 - Video Event

0x03 - Character Generator Event

0x04 - Still Store Event

0x05 - MOS Event

Video Duration (time - four bytes):

The duration of a video event. If a video event is playing, the time remaining is returned. If unused, the field must contain four 0xFF bytes.

Channel Assignment (byte):

The channel assignment for this event. The channel may have been over-ridden by the CAWS. The physical device determines the highest channel value. (New in version 2.2.)

0x00 - None or N/A


0x01 - Channel A

0x02 - Channel B


Channel Name (string):

CAWS display name of channel for this event. Channel names are set by the device manager. String will be empty if the channel assignment field is N/A. (New in version 2.2.)

Error/Warning Messages

Header:


Command Code: 0x5D

Event ID: Event identifier. May be included for messages that concern specific events.

Story ID: Story identifier. Must be included whenever the Event ID is.

Parameter: byte 1 - reserved

byte 2 - error type

0x01 - protocol error

0x02 - machine control system error

0x03 - error generated by the user interface

0x04 - error generated by a device

byte 3 - command code

byte 4 - error code

A Device Manager or CAWS may send pre-formatted text messages to the newsroom host for display on the system console and/or users workstation or terminal. The error type designates which part of a machine control system generated the error. If the error is in response to a specific AMCP message, the command code is set to that of the offending message. The error code in byte 4 is only used for protocol errors. See section 4.4 for a list of AMCP errors.

Event, device and story information may be formatted into the strings along with CAWS, device-specific or device-generated messages. The newsroom host should add a time-stamp and Device Manager name to the messages as appropriate. All other pertinent information must be included in the message text.

Two separate strings follow the DM/CAWS name; either may be empty. If the first string is not empty, the newsroom host should display it on the system console. (For Avid iNEWS NRCS, the console string should be in English.) If the second string is not empty, the newsroom host should display it on the workstation or terminal of the user who performed the play list download and/or other users as appropriate. (For Avid iNEWS NRCS, user messages are user-definable strings in any language.)

Data:

Device Manager Name (string):

Name of device manager, CAWS, or machine control host that created the messages.


Console Error/Warning Message (string):

This message must be displayed on the newsroom host system console.

User Error/Warning Message(string):

This message must be displayed on the workstation or terminal of the user who performed the play list download and/or other users as appropriate.

ControlAir Abort

Header:


Command Code: 0x5E

Event ID: Zero

Story ID: Zero

Parameter: Zero

In the Avid implementation, if the AMCP module loses contact with the ControlAir controller, it will notify the NRCS of that failure. The AMCP module will send the appropriate error messages to the NRCS console and users. It is likely, in such a case, that human intervention will be necessary before continuing.

Two separate strings follow the module name; either may be empty. If the first string is not empty, the NRCS must display it on the system console. If the second string is not empty, the NRCS must display it on the workstation or terminal of the user who performed the play list download and/or other users as appropriate.

Data:

AMCP Module Name (string):

Identifies the AMCP module as the source of the messages.

Console Error/Warning Message (string):

This message must be displayed on the NRCS system console.

User Error/Warning Message(string):

This message must be displayed on the workstation or terminal of the user who performed the play list download and/or other users as appropriate.

4.4 Protocol Errors

This is a complete list of the various errors that can be generated by improper protocol messages.

Code Error

0x11 AMCP_ERR_BAD_VERSION

0x12 AMCP_ERR_BAD_COMMAND

0x13 AMCP_ERR_FORMAT

0x14 AMCP_ERR_BAD_STRING


0x21 AMCP_ERR_TIME

0x22 AMCP_ERR_BAD_NRCS

0x23 AMCP_ERR_PARAMETER

0x31 AMCP_ERR_DEVICE

0x32 AMCP_ERR_ILLEGAL_END

0x33 AMCP_ERR_STORY_ID

0x34 AMCP_ERR_EVENT_ID

0x35 AMCP_ERR_DATA


5. Glossary

CAServer - The ControlAir server program. It stores all device and event information and status, routes messages between ControlAir clients and regulates which workstations may control which devices.

CART - A reference to a video tape playback system. While CART is an abbreviation for tape cartridge, most current CART machines actually play Beta or digital format tape cassettes.

Channel - A distinct, broadcast quality video output. Most, but not all production devices have two or more channels. Dual channels may be used in a Preview/Program (on-air) mode or in an alternating fashion. Video servers or CART machines may have more than two channels.

CG - See character generator.

CG Template - A character generator file that contains fields for text insertion. A template also includes formatting information about the length, location, font, color, and style of the added text. It may also contain background images and effects instructions. Some character generators call them “tab” files.

Character Generator - A production device designed to format, record, and display text and graphics as video images. Many provide dual-channel video outputs. Some can produce complex playback effects or animation. Abbreviated as CG.

ControlAir broadcast control system – A System, comprised of hardware and software that automates control room functions by taking machine control requests from a Newsroom Computer System, in the form of playlists, and by taking playback commands from a control workstation and routing them to the appropriate device managers that control the production devices. Abbreviated as CA.

ControlAir Workstation - The graphical user interface used to control play back of machine control events. It displays playlists received from the ControlAir server and provides the means for an operator to control the events in a playlist on the appropriate production devices. Abbreviated as CAWS.

Device Manager - The ControlAir customized interface to a specific production device. It will create or validate individual machine control events on the device and control the real-time playback of those events.

Effect - See playback effect.

Event - See machine control event.

Event Duration - The playing length of an event. All video events have a duration associated with them. Most CG or SS events will stay on-air until cleared or replaced; however, there may be a duration associated with the playback effect used to take these events to air. ControlAir stores duration in hours, minutes, seconds and frames and can support either NTSC (30 frame/second) or PAL (25 frame/second) frame rates.

Machine Control Event - A directive associated with a story in a playlist, that describes some media, such as a video, still, or super, and a production device that can play that media, such as a video server, still store, or character generator. An event contains enough information for a device manager to build or validate the necessary media on the device.

Media ID - A unique identifier which can be used to access a machine control event on a production device. ControlAir treats this Id as an alphanumeric string, but some NRCS or device limitations could restrict the ID for a given device or device type to a numeric value.

MOS Event - Production cues intended for MOS devices are not parsed or interpreted by the Avid iNEWS NRCS. Instead, they are entered into rundown stories by third-party plug-ins. The Avid iNEWS NRCS sends MOS event requests to the Avid MOS Gateway server, which communicates directly with the MOS devices using the MOS Protocol.

MOS Device - A Media Object Server is any of several production devices that allow remote control by a Newsroom Computer System using the MOS Protocol. The most common types of production devices to use the MOS protocol are video servers, audio servers, broadcast automation servers and still stores. The


Avid iNEWS NRCS can control MOS devices by using AMCP to encapsulate and send MOS event requests to the Avid MOS Gateway server, which communicates directly with the MOS devices using the MOS Protocol.

MOS Protocol – The Media Object Server Protocol is an open-standard, TCP/IP based protocol used by several production devices to allow remote control by a Newsroom Computer System.

Newsroom Computer System - A computer system that automates news gathering and the production of news broadcasts. One function of that automation is the creation of playlists containing machine control events for the ControlAir server. Abbreviated as NRCS.

Playback Effect - A transition of a video image from one state to another triggered by play request at the CAWS. Simple effects include fading, dissolving, or wiping one image into another. Complex effects might include tumbling or animating text and images into position. Most effects have a speed or time element that determines the duration of the transition.

Playlist - A list of machine control events sent from an NRCS to the ControlAir server for the purpose of playback to air. A ControlAir playlist can contain events for any device it controls, grouped by the containing NRCS story. See Rundown.

Playlist Reserve - The ControlAir server prevents conflicting playback requests from multiple CAWS machines by requiring a CAWS to reserve both the playlist and associated production devices prior to enabling playback commands on the CAWS. After the playlist has been broadcast, the reserving CAWS must release the list to enable the reserving of another playlist on the devices in use. A password-controlled override feature is available to permit the transfer of control to another CAWS if necessary.

Producer - The producer is responsible for the content of a show. He/she makes decisions about what stories belong in a show and may also change the contents or order of a show during broadcast.

Production Cue - Entry in an NRCS story containing the information required to create machine control events, such as video clips, stills, and supers, in a ControlAir playlist.

Production Device - Generic term for the various machines that produce the video components of a news broadcast. ControlAir currently supports machines in the categories of video server, tape players, still stores and character generators. For ControlAir to control a production device, that machine must provide some means of remote computer control through a serial or network connection.

Rundown - An NRCS group or list of stories that comprise a news broadcast. The NRCS provides the ControlAir with a name or title for the rundown, which is then used on the CAWS to identify the playlist that is derived from that rundown. Often called a Line-up or Running Order.

Running Order – See rundown.

Release Playlist - See playlist reserve.

Reserve Playlist - See playlist reserve.

SS - See still store.

Still - A single frame of video formatted and recorded on a still store for on-air display.

Still Store - A production device designed to format, record, and display still video images. Many provide dual-channel video outputs. Some can produce complex playback effects. Abbreviated as SS.

Story - An NRCS file that contains the information necessary to bring a news story to air. It includes a script for the anchor to read, as well as accounting data and prompter instructions. It may also contain ControlAir production cues.

Super - A character generator event, i.e. CG text and/or graphics “superimposed” over the on-air image. It may have been pre-recorded on the CG or could be built by the ControlAir device manager from a CG template and text included in the playlist event. Some stations use the term “font” instead.

Video Server - A computerized system designed to record and/or play high resolution digitized video to/from magnetic storage, e.g. hard disk. The video is sometimes stored in a compressed format on disk.


Copyright and Disclaimer

Product specifications are subject to change without notice and do not represent a commitment on the part of Avid Technology, Inc.

The software described in this document is furnished under a license agreement. You can obtain a copy of that license by visiting Avid's

Web site at www.avid.com. The terms of that license are also available in the product in the same directory as the software. The software

may not be reverse assembled and may be used or copied only in accordance with the terms of the license agreement. It is against the law

to copy the software on any medium except as specifically allowed in the license agreement.

No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying

and recording, for any purpose without the express written permission of Avid Technology, Inc.

Copyright © 2008 Avid Technology, Inc. and its licensors. All rights reserved. Printed in USA.

Attn. Government User(s). Restricted Rights Legend

U.S. GOVERNMENT RESTRICTED RIGHTS. This Software and its documentation are “commercial computer software” or “commercial

computer software documentation.” In the event that such Software or documentation is acquired by or on behalf of a unit or agency of the

U.S. Government, all rights with respect to this Software and documentation are subject to the terms of the License Agreement, pursuant

to FAR §12.212(a) and/or DFARS §227.7202-1(a), as applicable.

Trademarks

888 I/O, Adrenaline, AirPlay, AirSPACE, AirSPACE HD, AirSpeed, AniMatte, AudioSuite, AudioVision, AutoSync, Avid, Avid DNA,

Avid DNxcel, Avid DNxHD, AVIDdrive, AVIDdrive Towers, Avid Mojo, AvidNet, AvidNetwork, AVIDstripe, Avid Unity, Avid Unity ISIS, Avid

ISIS, Avid Xpress, AVoption, AVX, CamCutter, ChromaCurve, ChromaWheel, DAE, D-Fi, D-fx, Digidesign, Digidesign Audio Engine,

Digidesign Intelligent Noise Reduction, DigiDrive, Digital Nonlinear Accelerator, DigiTranslator, DINR, DNxchange, D-Verb, Equinox,

ExpertRender, FieldPak, Film Composer, FilmScribe, FluidMotion, HIIP, HyperSPACE, HyperSPACE HDCAM, IllusionFX,

Image Independence, Intraframe, iS9, iS18, iS23, iS36, LaunchPad, Lo-Fi, Magic Mask, make manage move | media, Marquee, Matador,

Maxim, MCXpress, Media Composer, MediaDock, MediaDock Shuttle, Media Fusion, Media Illusion, MediaLog, Media Reader,

Media Recorder, MEDIArray, MediaShare, Meridien, MetaSync, MissionControl, NaturalMatch, Nearchive, NetReview, NewsCutter, Nitris,

OMF, OMF Interchange, OMM, Open Media Framework, Open Media Management, ProEncode, Pro Tools, QuietDrive, Recti-Fi,

RetroLoop, rS9, rS18, Sci-Fi, Softimage, Sound Designer II, SPACE, SPACEShift, SpectraGraph, SpectraMatte, Symphony, Trilligent,

UnityRAID, Vari-Fi, Video Slave Driver, VideoSPACE, and Xdeck are either registered trademarks or trademarks of Avid Technology, Inc.

in the United States and/or other countries.

iNEWS, iNEWS ControlAir, and Media Browse are either registered trademarks or trademarks of iNews, LLC.

All other trademarks contained herein are the property of their respective owners.

AMCP System Specifications v2.4 • 28 January 2008


amcp: avid machine control protocolresources.avid.com/supportfiles/attach/amcp system guide...

Documents