Pinnacle Systems AirSpeed 5000 User Manual

AirSpeed 5000 API Guide

information is governed by the applicable non-disclosure agreements. AirSpeed 5000 API Guide P/N: 9329- 65226-00 Rev A Date: 4/26/12

AirSpeed 5000 API Guide Page i

Contents

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

AirSpeed 5000 API Guide Page i

Contents

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

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

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

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

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

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

AirSpeed 5000 API Guide Page ii

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) (m ax 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 for matted STRING Time Code (HH:MM:SS:F F) (; 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 1

Channel Control and Command Basics

Controlli ng 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 2

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 3

Initialize

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

Attribute Parameters

Not applicable.

Return Tag Elements and Attributes

VER is the STRING value o f 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 4

GetConfigInfo

This command is used to ge t system configuration i nformation. <AMS><Configuration> <GetConfigInfo/> </Configuration></AMS>

Attribute Parameters

Not applicable.

Return Tag Elements and Attributes

N is the INT value of the nu mber of channels available.

<VidStandard>STANDARD</VidStandard>

STANDARD i s the system video standard.

<CompatibleVidStandards>STANDARD</CompatibleVidStandards>

STANDARDS are a list of compatible vid e o 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” 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 5

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 / Do wn / Cross convert. SWITCH – Swit ch the actual output standard.(on the fly)

Remarks

Not applicable.

AirSpeed 5000 API Guide Page 6

GetHardwareStatus

This command is used to ge t system hardware status. <AMS><Configuration> <GetHardwareStatus Verbose=”false”/> </Configuration></AMS>

Attribute Parameters

Verbose

This is an optional BOOL attrib ute. If this is true then the return error message “Ms g” 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 Verbo se= true then the description is verbose. I f HardwareStatus=OK then this tag is not returned.

Remarks

Not applicable.

AirSpeed 5000 API Guide Page 7

Disconnect

This command is used to disconnect the client from the server. <AMS><Configuration> <Disconnect /> </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 8

Transport Control Commands

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

AirSpeed 5000 API Guide Page 9

PlayCue

This command is used to cue a clip for playback. <AMS><TransportControl> <PlayCue ID=”ClipID” In=”TC” Out=”TC” AutoPlay=”false” ShowFirst=”true” EjectFirst=”true” TcRef=”REF” /> </TransportControl></AMS>

Attribute Parameters

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

This is an optional STRING attribute t o 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 a ttribute 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 attrib ute indic a ting if the system is to show the first frame on t he output cha nnel for the cued clip. The default is false.

EjectFirst

This is an optional BOOL attrib ute indic a ting if the system is to eject the cued clip if has not currently active. The default is false.

AutoPlay

This is an optional BOOL attrib ute indic a ting if the cued clip is to automatically start playing when the currently playing clip completes. If no clip is curr e ntly playing, then this fl ag 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 c hannel’s output video standard (Default ) REF = CLIP – Use the active clip’s video standard.

PlayList

This is an optional BOOL attrib ute indic a ting 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 ignor e d. 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 comma nd is issued while a clip playing.

AirSpeed 5000 API Guide Page 10

UnloadCuedClip

This command is used to unload a clip that is cued for playback. <AMS><TransportControl> <UnloadCuedClip/> </TransportControl></AMS>

Attribute Parameters

Return Tags

Not applicable.

Remarks

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

AirSpeed 5000 API Guide Page 11

LoadPlayList

This command is used to load an already created play list for playback. <AMS><TransportControl> <LoadPlayList Name=”Name” StartItem=”0” ShowFirst=”true” EjectFirst=”true” TcRef=”REF” UpdateToDisk=”true” /> </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 indica ting the item number to start playing from in the Play List. The default is 0 (first item).

ShowFirst

This is an optional BOOL attrib ute indic a ting 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

UpdateToDisk

This is an optional BOOL attrib ute indic a ting that changes made to load ed 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 comma nd is issued while a clip playing.

AirSpeed 5000 API Guide Page 12

CuePlayListItem

This command is used to cue a clip for play back in already loaded Play List. <AMS><TransportControl> <CuePlayListItem CueItem=”0” ShowFirst=”true” /> </TransportControl></AMS>

Attribute Parameters

CueItem

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

ShowFirst

This is an optional BOOL attrib ute indic a ting 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 comma nd is issued while a clip playing.

AirSpeed 5000 API Guide Page 13

RecordCue

This command is used to cue a clip for recording. <AMS><TransportControl> <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

This is a STRING attribute. This is the ID of t he c lip that is to be cued for recording If this attribute does not exist, the AirSpeed 5000 will auto matically assign a new ID.

Len

This is an optional STRING a ttribute TC length to record the clip . T he default (0) is to record until a STOP command is issued.

OverWrite

This is an optional BOOL attrib ute indic a ting if the clip already exists it may be deleted first. The default is false.

EjectFirst

This is an optional BOOL attrib ute indic a ting that the channel should be ejected before the cue is initiated. The default i s false;

TimeCodeSrc

This is an optional STRING attribute defining the record timecode sourc e . T he 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 14

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 i s currently in Play mode.

AirSpeed 5000 API Guide Page 15

+ 40 hidden pages