From CasparCG Wiki

Communication

The Advanced Media Control Protocol (AMCP) is the main communication protocol used to control and query CasparCG Server.

• All communication is presumed to be encoded in UTF-8.
• Each command has to be terminated with both a carriage return and a linefeed character. For example:
  • \r\n
  • <CR><LF>
  • <0x0D><0x0A>
  • <13><10>
• The whole command string is case insensitive.
• Since the parameters in a command is separated by spaces, you need to enclose the parameter with quotation marks if you want it to contain spaces.

Backwards Compatibility

The AMCP 2.0 protocol implementation is mostly backward compatible with the previous CasparCG 1.7.1 AMCP Protocol and CasparCG 1.8.0 AMCP Protocol. This is achieved by providing default values for parameters used by the AMCP 2.0 protocol.

Breaking Changes

The CLEAR command will also clear any visible template graphic in the specified container.

Special sequences

Since bare quotation marks are used to keep parameters with spaces in one piece, there has to be another way to indicate a quotation mark in a string. Enter special sequences. They behave as in most programming languages. The escape character is the backslash \ character. In order to get a quotation mark you enter \" in the command.

Valid sequences:

• \" Quotation mark
• \\ Backslash
• \n New line

These sequences apply to all parameters, it doesn't matter if it's a file name or a long string of XML data.

Return Codes

Information

• 100 [action] - Information about an event.
• 101 [action] - Information about an event. A line of data is being returned.

Successful

• 200 [command] OK - The command has been executed and several lines of data are being returned (terminated by an empty line).
• 201 [command] OK - The command has been executed and a line of data is being returned
• 202 [command] OK - The command has been executed

Client Error

• 400 ERROR - Command not understood
• 401 [command] ERROR - Illegal video_channel
• 402 [command] ERROR - Parameter missing
• 403 [command] ERROR - Illegal parameter
• 404 [command] ERROR - Media file not found

Server Error

• 500 FAILED - Internal server error
• 501 [command] FAILED - Internal server error
• 502 [command] FAILED - Media file unreadable

Command Specification

Required Value

[my_value_name:my_type,my_type2]

Required value with one of the comma-separated types my_typex.

Examples: A required value for transition which can be either CUT, MIX, PUSH or WIPE.

[transition:CUT,MIX,PUSH,WIPE]
>> CUT
<< CUT

A required value for video_channel which must a signed integer.

[video_channel:int] 
>> 1
<< 1

Optional Expression

{my_expr|my_default_expr}

Optional expression where my_def_expr is used if no expression is provided. If |my_def_expr is not provided then it is assumed to evaluate to |"".

Examples: An optional expression which will be evaluated to -0 if not provided.

{[layer:int]|-0} 
>> -2
<< -2	
>> 
<< -0

An optional expression will be evaluated to an emptry string if not provided.

{[tween:string]} 
>> easeinsine
<< easeinsine
>>
<<

Basic Commands

LOADBG

LOADBG [channel:int]-[layer:int] [clip:string] {[loop:LOOP]} {[transition:CUT,MIX,PUSH,WIPE,SLIDE] [duration:uint] 
{[tween:string]|linear} {[direction:LEFT,RIGHT]|RIGHT}|CUT 0} {SEEK [frame:uint]} {LENGTH [frames:uint]} 
{FILTER [filter:string]} {[auto:AUTO]}

Loads a producer in the background and prepares it for playout. If no layer is specified the default layer index will be used.

clip will be parsed by available registered producer factories. If a successfully match is found, the producer will be loaded into the background.

If a file with the same name (extension excluded) but with the additional postfix _a is found this file will be used as key for the main clip.

loop will cause the clip to loop.

When playing and looping the clip will start at frame.

When playing and loop the clip will end after frames number of frames.

auto will cause the clip to automatically start when foreground clip has ended (without play). The clip is considered "started" after the optional transition has ended.

Examples:

LOADBG 1-1 MY_VIDEO PUSH 20 easeinesine LOOP SEEK 200 LENGTH 400 AUTO FILTER hflip

LOADBG 1 MY_FILE PUSH 20 EASEINSINE

LOADBG 1-1 MY_FILE SLIDE 10 LEFT

LOADBG 1-0 MY_FILE

See Animation Types for supported values for tween. See [1] for supported values for filter.

Note: Filters are currently only supported by some producers (FFMPEG and Decklink). Use deinterlace or deinterlace_bob as short-hands for deinterlacing filters.

LOAD

LOAD [video_channel:int]{-[layer:int]|-0} {"additional parameters"} 

Loads a clip to the foreground and plays the first frame before pausing. If any clip is playing on the target foreground then this clip will be replaced.

Examples:

LOAD 1 MY_FILE

LOAD 1-1 MY_FILE

Note: See LOADBG for additional details.

PLAY

PLAY [video_channel:int]{-[layer:int]|-0} {"additional parameters"}

Moves clip from background to foreground and starts playing it. If a transition (see LOADBG) is prepared, it will be executed.

If additional parameters (see LOADBG) are provided then the provided clip will first be loaded to the background.

Examples:

PLAY 1 MY_FILE PUSH 20 EASEINSINE

PLAY 1-1 MY_FILE SLIDE 10 LEFT

PLAY 1-0 MY_FILE

Note: See LOADBG for additional details.

PAUSE

PAUSE [video_channel:int]{-[layer:int]|-0}

Pauses foreground clip.

Examples:

PAUSE 1

PAUSE 1-1

STOP

STOP [video_channel:int]{-[layer:int]|-0}

Removes foreground clip.

Examples:

STOP 1

STOP 1-1

CLEAR

CLEAR [video_channel:int]{-[layer:int]}

Removes all clips (both foreground and background). If no layer is specified then all layers in the specified video_channel are cleared.

Examples:

CLEAR 1

CLEAR 1-1

CALL

CALL [video_channel:int]{-[layer:int]|-0} [param:string]

Calls method on the specified producer with the provided param string.

Examples:

 CALL 1 LOOP

CALL 1-2 SEEK 25

SWAP

SWAP [channel1:int]{-[layer1:int]} [channel2:int]{-[layer2:int]}

Swaps layers between channels (both foreground and background will be swapped). If layers are not specified then all layers in respective video_channel will be swapped.

Examples:

SWAP 1 2

SWAP 1-1 2-3

ADD

ADD [video_channel:int] [parameters:string]

The string clip will be parsed by available registered consumer factories. If a successful match is found a consumer will be created and added to the video_channel.

Examples:

ADD 1 DECKLINK 1

ADD 1 BLUEFISH 2

ADD 1 SCREEN

ADD 1 AUDIO

ADD 1 FILE test.mov

REMOVE

REMOVE [video_channel:int] [parameters:string]

Removes an existing consumer from video_channel.

Examples:

REMOVE 1 DECKLINK 1

REMOVE 1 BLUEFISH 2

REMOVE 1 SCREEN

REMOVE 1 AUDIO

REMOVE 1 FILE test.mov

Data Commands

The DATA commands are convenient to use when you have large datasets that might not be available at broadcast-time. DATA allows you to store a dataset on the CasparCG Server and assign it to a much shorter name. This name can then be used to recall the data when displaying a template graphic.

DATA STORE

DATA STORE [name:string] [data:string]

Stores the dataset data under the name name.

Example:

DATA STORE my_data "Some useful data"

DATA RETRIEVE

DATA RETRIEVE [name:string] [data:string]

Returns the data saved under the name name.

DATA LIST

DATA LIST

Returns a list of all saved datasets.

Template Graphics Commands

Commands that are sent to Flash templates.

Template Data

Data to templates is sent as xml, formatted as follows:

<templateData>
	<componentData id="f0">
		<data id="text" value="Niklas P Andersson" /> </componentData>
	<componentData id="f1">
		<data id="text" value="Developer" />
	</componentData>
	<componentData id="f2">
		<data id="text" value="Providing an example" />
	</componentData>
</templateData>

The node under each componentData is sent directly into the specified component. This makes it possible to provide completely custom data to templates. The data-nodes in this example is just the way the default CasparCG textfield wants its data. More information about this will be provided with the tools and ActionScript classes required to build your own templates.

A complete call to CG ADD (see below), correctly escaped and with the data above would look like this:

CG 1 ADD 0 "demo/test" 1 "<templateData><componentData id=\"f0\">
<data id=\"text\" value=\"Niklas P Andersson\">
</data> </componentData><componentData id=\"f1\">
<data id=\"text\" value=\"developer\">
</data></componentData><componentData id=\"f2\">
<data id=\"text\" value=\"Providing an example\"></data> </componentData></templateData>"

CG ADD

CG [video_channel:int]{-[layer:int]|-0} 
ADD [flash_layer:uint] [template:string] [play-on-load:0,1] [data]

Prepares a template for displaying. It won't show until you call CG PLAY (unless you supply the play-on-load flag, 1 for true). Data is either inline xml or a reference to a saved dataset.

Examples:

CG 1 ADD 10 svtnews/info 1

CG REMOVE

CG [video_channel:int]{-[layer:int]|-0} REMOVE [flash_layer:uint]

Removes the visible template from a specific layer.

CG CLEAR

CG [video_channel:int]{-[layer:int]|-0} CLEAR [flash_layer:uint]

Clears all layers and any state that might be stored. What this actually does behind the scene is to create a new instance of the Adobe Flash player ActiveX controller in memory.

CG PLAY

CG [video_channel:int]{-[layer:int]|-0} PLAY [flash_layer:uint]

Plays and displays the template in the specified layer.

CG STOP

CG [video_channel:int]{-[layer:int]|-0} STOP [flash_layer:uint]

Stops and removes the template from the specified layer. This is different than REMOVE in that the template gets a chance to animate out when it is stopped.

CG NEXT

CG [video_channel:int]{-[layer:int]|-0} NEXT [flash_layer:uint]

Triggers a "continue" in the template on the specified layer. This is used to control animations that has multiple discreet steps.

CG GOTO

CG [video_channel:int]{-[layer:int]|-0} GOTO [flash_layer:uint] [label:string]

Jumps to the specified label in the template on the specified layer.

CG UPDATE

CG [video_channel:int]{-[layer:int]|-0} UPDATE [flash_layer:uint] [data:string]

Sends new data to the template on specified layer. Data is either inline xml or a reference to a saved dataset.

CG INVOKE

CG [video_channel:int]{-[layer:int]|-0} GOTO [flash_layer:uint] [method:string]

Calls a custom method in the document class of the template on the specified layer. The method must return void and take no parameters.

Mixer Commands

MIXER KEYER

MIXER [video_channel:int]{-[layer:int]|-0} KEYER {keyer:0,1|0}

If keyer equals 1 then the specified layer will not be rendered, instead it will be used as the key for the layer above.

Examples:

MIXER 1-0 KEYER 1

MIXER BLEND

MIXER [video_channel:int]{-[layer:int]|-0} BLEND {[blend:string]|normal}

If keyer equals 1 then the specified layer will not be rendered, instead it will be used as the key for the layer above.

Examples:

MIXER 1-1 BLEND OVERLAY

See Blend Modes for supported values for blend.

MIXER OPACITY

MIXER [video_channel:int]{-[layer:int]|-0} VIDEO OPACITY [opacity:float] {[duration:uint] {[tween:string]|linear}|0 linear}

Changes the opacity of the specified layer.

Examples:

>> MIXER 1-0 OPACITY 0.5 25 easeinsine

See Animation Types for supported values for tween.

MIXER BRIGHTNESS

MIXER [video_channel:int]{-[layer:int]|-0} BRIGHTNESS [brightness:float] {[duration:uint] {[tween:string]|linear}|0 linear}

Changes the brightness of the specified layer.

Examples:

>> MIXER 1-0 BRIGHTNESS 0.5 25 easeinsine

See Animation Types for supported values for tween.

MIXER SATURATION

MIXER [video_channel:int]{-[layer:int]|-0} SATURATION [saturation:float] {[duration:uint] {[tween:string]|linear}|0 linear}

Changes the saturation of the specified layer.

Examples:

>> MIXER 1-0 SATURATION 0.5 25 easeinsine

See Animation Types for supported values for tween.

MIXER CONTRAST

MIXER [video_channel:int]{-[layer:int]|-0} CONTRAST [contrast:float] {[duration:uint] {[tween:string]|linear}|0 linear}

Changes the contrast of the specified layer.

Examples:

>> MIXER 1-0 CONTRAST 0.5 25 easeinsine

See Animation Types for supported values for tween.

MIXER LEVELS

MIXER [video_channel:int]{-[layer:int]|-0} LEVELS [min_input:float] [max_input:float] [gamma:float] [min_output:float] [max_output:float] {[duration:uint] {[tween:string]|linear}|0 linear}

Changes the contrast of the specified layer.

Examples:

>> MIXER 1-0 LEVELS 0.1 0.1 1.0 0.9 0.9 25 easeinsine

See Animation Types for supported values for tween.

MIXER FILL

MIXER [video_channel:int]{-[layer:int]|-0} FILL [x:float] [y:float] [x-scale:float] [y-scale:float] {[duration:uint] {[tween:string]|linear}|0 linear}

Scales the video stream on the specified layer.

Examples:

>> MIXER 1-0 FILL 0.25 0.25 0.5 0.5 25 easeinsine

See Animation Types for supported values for tween.

MIXER CLIP

MIXER [video_channel:int]{-[layer:int]|-0} CLIP [x:float] [y:float] [x-scale:float] [y-slace:float] {[duration:uint] {[tween:string]|linear}|0 linear}

Masks the video stream on the specified layer.

Examples:

• >> MIXER 1-0 CLIP 0.25 0.25 0.5 0.5 25 easeinsine

See Animation Types for supported values for tween.

MIXER GRID

MIXER [video_channel:int] GRID [resolution:uint] {[duration:uint] {[tween:string]|linear}|0 linear}

Creates a grid of video streams in ascending order of the layer index, i.e. if resolution equals 2 then a 2x2 grid of layers will be created.

Examples:

>> MIXER 1 GRID 2

See Animation Types for supported values for tween.

MIXER VOLUME

MIXER [video_channel:int]{-[layer:int]|-0} VOLUME {opacity:float} {[duration:uint] {[tween:string]|linear}|0 linear}

Changes the volume of the specified layer.

Examples:

>> MIXER 1-0 AUDIO GAIN 0.5 25 easeinsine

See Animation Types for supported values for tween.

MIXER CLEAR

MIXER [video_channel:int]{-[layer:int]|-0} CLEAR

Reset all transformations.

Examples:

>> MIXER 1 CLEAR

>> MIXER 1-1 CLEAR

See Animation Types for supported values for tween.

Query Commands

CINF

CINF [filename:string]

Returns information about a mediafile.

CLS

• CLS

Lists all mediafiles.

TLS

• TLS {folder:string|./}

Lists all templates. Lists only templates in the specified folder, if provided.

VERSION

• VERSION {[component:SERVER,FLASH,TEMPLATEHOST]|SERVER}

Returns the version of specified component.

INFO

• INFO [video_channel:int]

Returns information about the channels on the server. Use this without parameters to check how many channels a server has.

STATUS

• STATUS [video_channel:int]-[video_layer:int]

Returns status for the specified layer.

Misc Commands

DIAG

Syntax:

• DIAG

Opens the diagnostics window.

BYE

Syntax:

• BYE

Disconnects from the server.