Avid AirSpeed 5000 User guide

AirSpeed 5000 API Guide Page i

AirSpeed 5000 API Guide

This document contains confidential and proprietary information. Usage and dissemination of this

information is governed by the applicable non-disclosure agreements.

AirSpeed 5000 API Guide P/N: 9329- 65226-00 Rev A Date: 4/26/12

Contents

AirSpeed 5000 API Guide Page i

Table of Contents

OVERVIEW .................................................................................................................................................. 1

CHANNEL CONTROL AND COMMAND BASICS ................................................................................ 2

Formatting ....................................................................................................................................................... 2

Response .......................................................................................................................................................... 2

CONFIGURATION COMMANDS ............................................................................................................. 3

Initialize ........................................................................................................................................................... 4

GetConfigInfo ................................................................................................................................................. 5

GetHardwareStatus .......................................................................................................................................... 7

Disconnect ....................................................................................................................................................... 8

TRANSPORT CONTROL COMMANDS .................................................................................................. 9

PlayCue ......................................................................................................................................................... 10

UnloadCuedClip ............................................................................................................................................ 11

LoadPlayList ................................................................................................................................................. 12

CuePlayListItem ............................................................................................................................................ 13

RecordCue ..................................................................................................................................................... 14

Shuttle ............................................................................................................................................................ 16

Play ................................................................................................................................................................ 17

Continue ........................................................................................................................................................ 18

Record ........................................................................................................................................................... 19

Pause .............................................................................................................................................................. 20

Eject ............................................................................................................................................................... 21

Stop................................................................................................................................................................ 22

SetInOut ........................................................................................................................................................ 23

Jog ................................................................................................................................................................. 24

GoTo .............................................................................................................................................................. 25

SetRecordDur ................................................................................................................................................ 26

GetStatus ....................................................................................................................................................... 27

GetSystemStatus ............................................................................................................................................ 29

GetInputStatus ............................................................................................................................................... 30

GetTC ............................................................................................................................................................ 31

DATABASE CONTROL COMMANDS ................................................................................................... 32

GetClipList .................................................................................................................................................... 33

GetPlayLists .................................................................................................................................................. 34

GetPlayListInfo ............................................................................................................................................. 35

SetPlayListAttributes ..................................................................................................................................... 36

CreatePlayList ............................................................................................................................................... 37

DeletePlayList ............................................................................................................................................... 39

RenamePlayList ............................................................................................................................................. 40

AddClipToPlayList........................................................................................................................................ 41

RemoveClipFromPlayList ............................................................................................................................. 42

Transfer (to Interplay) ................................................................................................................................... 43

Create Proxy .................................................................................................................................................. 44

GetProxyStatus .............................................................................................................................................. 45

GetTransferStatus .......................................................................................................................................... 46

GetTransferList ............................................................................................................................................. 47

DeleteClip ...................................................................................................................................................... 48

Contents

AirSpeed 5000 API Guide Page ii

GetClipData ................................................................................................................................................... 49

SetClipData ................................................................................................................................................... 51

GetChangeList ............................................................................................................................................... 52

GetGenericTemplate...................................................................................................................................... 53

GetGenericTemplateIds ................................................................................................................................. 54

GetGenericDefaultTemplateId ...................................................................................................................... 55

AirSpeed 5000 API Guide Page 1

Overview

The AirSpeed 5000 API is a TCP/IP socket based protocol used to control and query the AirSpeed 5000 server. The commands

are sent and received using XML (Extensible Markup Language) formatting.

The following items apply:

• TCP/IP available ports (59451-59456) (max of 10 connections per port)

• XML Info: <?xml version="1.0" encoding="utf-8"?>.

• Only one XML command may be sent at a time.

• The major XML commands are formatted as tags “elements”.

• Many of the “element” commands have corresponding “attribute” data.

• All XML references to “TC” are the formatted STRING Time Code (HH:MM:SS:FF) (; if Drop Frame). Most attribute

type of “TC” will also allow the same attribute name with ‘i’ preceding it as an INT representation of the Time Code

“iTC”.

For example, “StartTime=TC” will also allow “iStartTime=iTC” represented as an INT.

The “TC” STRING will be searched for first, and if found, the “iTC” should not be sent. It will be ignored.

• There are three command categories (Configuration, Transport and Database).

• STANDARD is the video standard name. Valid names are:

SD_NTSC_4x3_29_970

SD_PAL_4x3_25_000

HD_1920x1080i_29_970

HD_1920x1080i_25_000

HD_1280x720p_59_940

HD_1280x720p_50_000

Note: All references to VITC also pertain to ancillary time code (ATC) as well.

AirSpeed 5000 API Guide Page 2

Channel Control and Command Basics

Controlling an AirSpeed 5000 server via API begins with establishing a connection to the server. The available connection ports

are 59451 – 59456 for channels 1-6 respectively. There can be up to 5 separate connections per port. Multiple connections on the

same port will run synchronously, with only one command processed at a time.

If no data is received on the AirSpeed 5000 server for 60 seconds, then the connection will automatically be closed by the

AirSpeed 5000 server.

Each connection port (59451-59456) will default to a corresponding channel number (1-6). Only ports with corresponding

channels that have hardware connected will be activated.

Note: Some Transport commands such as Play Cue, and Record Cue take longer to process than Status commands.

Formatting

All commands are formatted using XML data packets with the following major tags.

<?xml version="1.0" encoding="utf-8"?>

<AMS><Configuration></Configuration></AMS> Configuration commands

<AMS><TransportControl></TransportControl></AMS> Transport Control commands

<AMS><DatabaseControl></DatabaseControl></AMS> Database Commands

Note: The terminating XML tag “</AMS>” will not be followed by a NULL.

Note: The client can only send one of the major tags at any one time.

Response

All XML commands will respond when the command is completed with the following:

<AMS><Reply Status=”STATUS” Msg=”MESSAGE” ErrNum=”N” /></AMS> Message response

The STRING attribute “Status” is the Reply Status

OK – No error

ERROR – Error Occured

WARNING – Warning

The STRING attribute “Msg” contains the warning or error message. This attribute will not exist if the “Status” = “OK”.

The INT attribute “ErrNum” contains an error value, along with the description of the error in the “Status” attribute. The

attribute “ErrNum” will not exist if the “Status” = “OK”

1 – Command Error

2 – System Error

3 – XML format error

4 – System BUSY

Note: Many commands will send additional tagged information along with the OK response

AirSpeed 5000 API Guide Page 3

Configuration Commands

The Airspeed 5000 API provides several convenience commands for requesting configuration information from the AirSpeed

5000. These commands are defined as the major tag <Configuration> and are typically sent during the initialization sequence, but

may be sent at any time.

AirSpeed 5000 API Guide Page 4

Initialize

This command is used to verify the connection between the client and the server, and retrieve information about the channel.

</Configuration></AMS>

Attribute Parameters

Not applicable.

Return Tag Elements and Attributes

VER is the STRING value of the current version of AirSpeed 5000

The INT attribute “ChnNum” is the channel number being controlled.

The BOOL attribute “CanRecord” is true if this is a record channel, else false.

Remarks

This command can be used to verify communication with the channel.

AirSpeed 5000 API Guide Page 5

GetConfigInfo

This command is used to get system configuration information.

</Configuration></AMS>

Attribute Parameters

Not applicable.

Return Tag Elements and Attributes

N is the INT value of the number of channels available.

<VidStandard>STANDARD</VidStandard>

STANDARD is the system video standard.

<CompatibleVidStandards>STANDARD</CompatibleVidStandards>

STANDARDS are a list of compatible video standards delimited by ‘;’.

BOOL is true if drop frame, false if not drop frame.

TYPE = 1 (GEN1, 2 (GEN2).

MODE = “Standalone”, “Team” or “Interplay”.

BOOL is true if proxy recording is enabled, false if proxy recording is not enabled.

BOOL is true if transfer engine is enabled for auto transfers, else false.

<ChnInfo

</ChnInfo>

“ChnInfo” contains a list of “Channel” Tags.

There is one Channel Tag returned for each Channel.

The INT attribute “Num” is the actual channel number.

The STRING attribute “VidStandard” is the channel video standard.

AirSpeed 5000 API Guide Page 6

The STRING attribute “Name” is the name of the channel.

The STRING attribute “VitcPlay” is the VITC playback line number

The BOOL attribute “ProxyRecordingEnabled” is “true” if proxy recording is enabled.

The STRING attribute “VitcRecord” is the VITC record line number.

The STRING attribute “OutputFormatBehavior” is the output format behavior:

FIXED – No format conversions.

UDX – Up / Down / Cross convert.

SWITCH – Switch the actual output standard.(on the fly)

Remarks

Not applicable.

AirSpeed 5000 API Guide Page 7

GetHardwareStatus

This command is used to get system hardware status.

</Configuration></AMS>

Attribute Parameters

Verbose

This is an optional BOOL attribute. If this is true then the return error message “Msg” is to be verbose. The default is

false.

Return Tag Elements and Attributes

<HardwareStatus>STRING</HardwareStatus>

STRING is “OK” if there are no errors, “ERROR” if there are errors.

<Msg>STRING</Msg>

STRING is a description of the hardware error, if Verbose=true then the description is verbose. If HardwareStatus=OK

then this tag is not returned.

Remarks

Not applicable.

AirSpeed 5000 API Guide Page 8

Disconnect

This command is used to disconnect the client from the server.

</Configuration></AMS>

Attribute Parameters

Not applicable.

Return Tag Elements and Attributes

Not applicable.

Remarks

If the command is successful, it will send the normal “OK” response and then the server will immediately disconnect from the

client. The client will have to reestablish socket communication to control the channel.

AirSpeed 5000 API Guide Page 9

Transport Control Commands

These commands are used to control the transport for the selected channel.

AirSpeed 5000 API Guide Page 10

PlayCue

This command is used to cue a clip for playback.

</TransportControl></AMS>

Attribute Parameters

ID

This is a required STRING attribute. This is the ID of the clip that is to be cued for playback.

In

This is an optional STRING attribute to set the beginning TC location for the clip play. The default is to cue to the

beginning of the clip.

Out

This is an optional STRING attribute to set the end TC location for the clip play. The default is to play to the end of the

clip.

ShowFirst

This is an optional BOOL attribute indicating if the system is to show the first frame on the output channel for the cued

clip. The default is false.

EjectFirst

This is an optional BOOL attribute indicating if the system is to eject the cued clip if has not currently active. The default

is false.

AutoPlay

This is an optional BOOL attribute indicating if the cued clip is to automatically start playing when the currently playing

clip completes. If no clip is currently playing, then this flag is ignored. The default is false.

TcRef

This is an optional STRING attribute indicating if the time code calculations are to be referenced on the Output

channel’s video standard, or the clips video standard. The default is OUTPUT

REF = OUTPUT – Use the channel’s output video standard (Default)

REF = CLIP – Use the active clip’s video standard.

PlayList

This is an optional BOOL attribute indicating that the ID is the name of a sequence to be loaded. If this is set to true then

the attributes “In” and “Out” are ignored. The default is false.

Return Tags

Not applicable.

Remarks

This command puts the channel in Play mode, if it is currently in Record mode.

The ShowFirst=”true” attribute will not take affect if the PlayCue command is issued while a clip playing.

AirSpeed 5000 API Guide Page 11

UnloadCuedClip

This command is used to unload a clip that is cued for playback.

</TransportControl></AMS>

Attribute Parameters

Return Tags

Not applicable.

Remarks

This command will unload a clip that is cued for play back.

AirSpeed 5000 API Guide Page 12

LoadPlayList

This command is used to load an already created play list for playback.

</TransportControl></AMS>

Attribute Parameters

Name

This is a required STRING attribute. This is the Name of the Play List to be readied for playback.

StartItem

This is an optional INT attribute indicating the item number to start playing from in the Play List. The default is 0 (first

item).

ShowFirst

This is an optional BOOL attribute indicating if the system is to show the first frame on the output channel for the cued

clip. The default is false.

EjectFirst

This is an optional BOOL attribute indicating if the system is to eject the cued clip if has not currently active. The default

is false.

TcRef

This is an optional STRING attribute indicating if the time code calculations are to be referenced on the Output

channel’s video standard, or the clips video standard. The default is OUTPUT

REF = OUTPUT – Use the channel’s output video standard (Default)

REF = CLIP – Use the active clip’s video standard.

UpdateToDisk

This is an optional BOOL attribute indicating that changes made to loaded play list will be updated to disk. The default

is true.

Return Tags

Not applicable.

Remarks

This command puts the channel in Play mode, if it is currently in Record mode.

The ShowFirst=”true” attribute will not take affect if the PlayCue command is issued while a clip playing.

AirSpeed 5000 API Guide Page 13

CuePlayListItem

This command is used to cue a clip for play back in already loaded Play List.

</TransportControl></AMS>

Attribute Parameters

CueItem

This is an optional INT attribute indicating the item number to cue in the Play List. The default is 0 (first item).

ShowFirst

This is an optional BOOL attribute indicating if the system is to show the first frame on the output channel for the cued

clip. The default is false.

Return Tags

Not applicable.

Remarks

The play list will automatically cue the next event as it plays the Play List Sequence. This command is only required to change

the next cued item.

The ShowFirst=”true” attribute will not take affect if the PlayCue command is issued while a clip playing.

AirSpeed 5000 API Guide Page 14

RecordCue

This command is used to cue a clip for recording.

<RecordCue ID=”ClipID” Name=”Clip Name” Len=”TC” OverWrite=”false”

EjectFirst=”false” TimeCodeSrc=”SYSTEM” />

<RecordTemplate>template</RecordTemplate>

<ProxyTemplate>template</ProxyTemplate>

<DestinationTemplate>template</DestinationTemplate>

</TransportControl></AMS>

Attribute Parameters

ID

This is a STRING attribute. This is the ID of the clip that is to be cued for recording

If this attribute does not exist, the AirSpeed 5000 will automatically assign a new ID.

Len

This is an optional STRING attribute TC length to record the clip. The default (0) is to record until a STOP command is

issued.

OverWrite

This is an optional BOOL attribute indicating if the clip already exists it may be deleted first. The default is false.

EjectFirst

This is an optional BOOL attribute indicating that the channel should be ejected before the cue is initiated. The default is

false;

TimeCodeSrc

This is an optional STRING attribute defining the record timecode source. The default is SYSTEM; Options are:

SYSTEM: Use the AirSpeed 5000 System setting

NONE: No Timecode Source, starts at 0

TOD: Timecode source is Time of Day

VITC: Timecode source is VITC

AirSpeed 5000 API Guide Page 15

Passed Tags

RecordTemplate

This is an optional STRING tag containing the record template XML data. This TAG will be formatted as a CDATA

section:

ProxyTemplate

This is an optional STRING tag containing the proxy record template XML data. This TAG will be formatted as a

CDATA section:

DestinationTemplate

This is an optional STRING tag containing the destination template XML data. This TAG will be formatted as a

CDATA section:

Return Tags

<ID>ClipID</ID>

The STRING tag ID is name of the clip cued for recording

Remarks

This command puts the channel in Record mode if it is currently in Play mode.

AirSpeed 5000 API Guide Page 16

Shuttle

This command is used to shuttle an active clip.

</TransportControl></AMS>

Attribute Parameters

Speed

This is an optional FLOAT attribute indicating play speed. The allowable speed ranges are (-10.0 to 10.0) A negative

value will play in reverse. The default is 1.0 indicating play forward at normal speed.

Return Tags

Not applicable

Remarks

Not applicable.

AirSpeed 5000 API Guide Page 17

Play

This command is used to play the cued item. If nothing is cued, this command will return an error.

</TransportControl></AMS>

Attribute Parameters

Speed

This is an optional FLOAT attribute indicating play speed. The allowable speed ranges are (-10.0 to 10.0) A negative

value will play in reverse. The default is 1.0 indicating Play Forward at normal speed.

StartTime

This is an optional STRING attribute for the start time TC (time of day). The default is to start immediately.

Return Tags

Not applicable.

Remarks

Not applicable.

Page is loading ...

Avid AirSpeed 5000 User guide

Avid AirSpeed 5000 User guide

Related papers

Other documents