CasparCG 1.8.0 AMCP Protocol

From CasparCG Wiki

Jump to: navigation, search

Document history

  • 1.7 2009-04-15 Niklas P Andersson
  • 1.7.1 2010-03-08 Niklas P Andersson
  • 1.8.0 2010-04-07 Niklas P Andersson


Advanced Media Control Protocol - AMCP

  • 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. (\r\n, <CR><LF>, <0x0D><0x0A> or <13><10>, whichever your programming language likes best).
  • The whole command string is case insensitive.
  • And 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.

Change Log

The AMCP Protocol has not been updated or modified at all between version 1.7.1 and 1.8.0. However, since 1.8.0 is the first public release of the source code for CasparCG, the version number has been bumped up to 1.8.0.

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. Thay behave as in most programming languages. The escape character is backslash (’\’). In order to get a quotation mark you enter \”. The full list of valid sequences is just below.




Quotation mark.




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.


Channels are referred to using a one-based index. That is, the first channel is Channel 1 and so on.

Play-out commands


Syntax LOAD channel file [loop]

LOAD loads and prepares a clip for playout. Load stops any currently playing clip and displays the first frame of the new clip. Supply the LOOP parameter if you want the clip to loop.


Syntax LOADBG channel file [loop] [transition] [duration] [direction] [border] [border-width]

LOADBG loads and prepares a clip for playout in the background. It does not affect the currently playing clip in anyway. This is how you prepare a transition between to clips. Supply the LOOP parameter if you want the clip to loop.



valid values



Cut (default), Mix, Push, Slide, Wipe

The type of transition


0 (default) - 65535

The length of the transition in frames


Right / Fromleft (default), Left / Fromright

Push, slide and wipe needs a direction


filename / #aarrggbb

Push, slide and wipe can have a border


0 (default) - 65535

The width of the border if it’s not an image


Syntax PLAY channel

Starts the playout on a channel. If a transition is prepared it will execute and then the new clip will keep playing.


Syntax STOP channel

Stops the playout on a channel. Nothing is done to prevent flickering if the channel is operating in a fields-based videomode.


Syntax CLEAR channel

Stops the playout if running and removes anything visible (by loading an transparent black frame). Please note that this DOES NOT AFFECT any template graphics that happens to be visible.

Template data


Data to templates is sent in xml. The xml is formated like this:


<componentData id="f0">

<data id="text" value="Niklas P Andersson" /> </componentData>

<componentData id="f1">

<data id="text" value="Developer" />


<componentData id="f2">

<data id="text" value="Providing an example" />



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>"

DATA commands

The DATA commands are convenient to use when you have large data sets that might not be available at broadcast-time. DATA allows you to store a data set 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.


Syntax DATA STORE name data

Stores the data set data under the name name.



Returns the data saved under the name name.



Returns a list of all saved data sets.

Commands for template graphics

Syntax CG channel command [parameters]

CG commands


Syntax CG channel ADD layer template [play-on-load] [data]

Example CG 1 ADD 10 svtnews/info 1

Prepares a template for displaying. It won’t show until you call CG PLAY (unless you supply the play-on-load flag, which is simply a ‘1’. ‘0’ for “don’t play on load”). data is either inline xml or a reference to a saved dataset. Please see the Template data / Format section above for a complete example with data.


Syntax CG channel REMOVE layer

Removes the visible template from a specific layer.


Syntax CG channel CLEAR

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.


Syntax CG channel PLAY layer

Plays / displays the template in the specified layer


Syntax CG channel STOP layer

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.


Syntax CG channel NEXT layer

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


Syntax CG channel GOTO layer label

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


Syntax CG channel UPDATE layer data

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


Syntax CG channel INVOKE layer method

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

Commands for statistics and status


Syntax CINF filename

Returns information about a mediafile


Syntax CLS

Lists all mediafiles


Syntax TLS [folder]

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



Returns the version of the server.


Syntax INFO [channel]

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

Misc commands


Syntax BYE

Disconnects from the server.

Return codes

1xx (Informational)

These return codes are reserved for future use as parts of a client-to-client status update system. The idea is to facilitate monitoring from a client by means of sending a command, for example MONITOR. This could be used to keep a client up to date on, for example, which clips are loaded on a monitored server.

100 [action]

Information about an event.

101 [action]

Information about an event. A line of data is being returned.

2xx (Successful)

202 [command] OK

The command has been executed

201 [command] OK

The command has been executed and a line of data is being returned

200 [command] OK

The command has been executed and several lines of data are being returned (terminated by an empty line.)

4xx (Client error)


Command not understood

401 [command] ERROR

Illegal channel

402 [command] ERROR

Parameter missing

403 [command] ERROR

Illegal parameter

404 [command] ERROR

Media file not found

5xx (Server error)


Internal server error

501 [command] FAILED

Internal server error

502 [command] FAILED

Media file unreadable

Personal tools