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
- 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, , <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.
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.
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.
| sequence | result |
| \” | 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.
Channels are referred to using a one-based index. That is, the first channel is Channel 1 and so on.
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.
| Parameter | valid values | Comment |
| transition | Cut (default), Mix, Push, Slide, Wipe | The type of transition |
| duration | 0 (default) - 65535 | The length of the transition in frames |
| direction | Right / Fromleft (default), Left / Fromright | Push, slide and wipe needs a direction |
| border | filename / #aarrggbb | Push, slide and wipe can have a border |
| border-width | 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.
Data to templates is sent in xml. The xml is formated like this:
<templatedata> <componentdata id="f0"> &lt;data id=&quot;text&quot; value=&quot;Niklas P Andersson&quot;&gt;&lt;/data&gt; </componentdata> <componentdata id="f1"> &lt;data id=&quot;text&quot; value=&quot;Developer&quot;&gt;&lt;/data&gt; </componentdata> <componentdata id="f2"> &lt;data id=&quot;text&quot; value=&quot;Providing an example&quot;&gt;&lt;/data&gt; </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="\&quot;f0\&quot;">&lt;data id=&quot;\&amp;quot;text\&amp;quot;&quot; value=&quot;\&amp;quot;Niklas&quot;&gt;&lt;/data&gt; </componentdata><componentdata id="\&quot;f1\&quot;">&lt;data id=&quot;\&amp;quot;text\&amp;quot;&quot; value=&quot;\&amp;quot;developer\&amp;quot;&quot;&gt;&lt;/data&gt;</componentdata><componentdata id="\&quot;f2\&quot;">&lt;data id=&quot;\&amp;quot;text\&amp;quot;&quot; value=&quot;\&amp;quot;Providing&quot;&gt;&lt;/data&gt; </componentdata></templatedata>"
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.
Syntax DATA RETRIEVE name
Returns the data saved under the name name.
Syntax DATA LIST
Returns a list of all saved data sets.
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.
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.
Syntax VERSION
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.
Syntax BYE
Disconnects from the server.
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. |
| 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.) |
| 400 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 |
| 500 FAILED | Internal server error |
| 501 [command] FAILED | Internal server error |
| 502 [command] FAILED | Media file unreadable |