git.sesse.net Git - casparcg/blob - source/commands.rst

   1 ########\r
   2 Commands\r
   3 ########\r
   4 \r
   5 ********\r
   6 amcp 2.0\r
   7 ********\r
   8 \r
   9 The Advanced Media Control Protocol (AMCP) is the main communication protocol used to control and query CasparCG Server 2.0.\r
  10 \r
  11 * All communication is presumed to be encoded in UTF-8.\r
  12 * Each command has to be terminated with both a carriage return and a linefeed character. For example:\r
  13         * \r\n\r
  14         * <CR><LF>\r
  15         * <0x0D><0x0A>\r
  16         * <13><10>\r
  17 * The whole command string is case insensitive.\r
  18 * 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.\r
  19 \r
  20 =======================\r
  21 Backwards Compatibility\r
  22 =======================\r
  23 \r
  24 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.\r
  25 \r
  26 ----------------\r
  27 Breaking Changes\r
  28 ----------------\r
  29 \r
  30 * The ''CLEAR'' command will also clear any visible template graphic in the specified container.\r
  31 \r
  32 =================\r
  33 Special sequences\r
  34 =================\r
  35 \r
  36 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.\r
  37 Valid sequences:\r
  38 \r
  39 * \\" Quotation mark\r
  40 * \\\\ Backslash\r
  41 * \\n New line  \r
  42 \r
  43 These sequences apply to all parameters, it doesn\'t matter if it\'s a file name or a long string of xml-data.\r
  44 \r
  45 =====================\r
  46 Command Specification\r
  47 =====================\r
  48 \r
  49 Commands are documented as regular expression with the extension of {} which indicate default values for optional parameters.\r
  50 \r
  51 ----------------\r
  52 Basic Commands\r
  53 ----------------\r
  54 \r
  55 ^^^^^^\r
  56 LOADBG\r
  57 ^^^^^^\r
  58 Loads a producer in the background and prepares it for playout.\r
  59 If no layer is specified the default layer index will be used.\r
  60 \r
  61 Syntax:: \r
  62 \r
  63         LOADBG \r
  64                 (?<video-channel>\d+)\r
  65                 (-(?<layer>\d+))?{0}\r
  66                 (?<producer>[\d\w]+) \r
  67                 (\r
  68                         (?<transitions>CUT|MIX|PUSH|WIPE|SLIDE) \r
  69                         (?<duration>\d+)\r
  70                         (?<tween>(linear|easein|and-more))?{LINEAR}\r
  71                         (?<direction>LEFT|RIGHT)?{RIGHT}\r
  72                 )?{CUT 0}\r
  73                 (?<auto>AUTO)?{}\r
  74                 (?<parameters>.*)?{}\r
  75                 \r
  76 Example::\r
  77 \r
  78         LOADBG 1-1 MY_VIDEO PUSH 20 easeinesine LOOP SEEK 200 LENGTH 400 AUTO FILTER hflip \r
  79                 \r
  80 ^^^^\r
  81 LOAD\r
  82 ^^^^\r
  83 Loads a producer to the foreground and displays the first frame.\r
  84 If no layer is specified the default layer index will be used.\r
  85 \r
  86 Syntax:: \r
  87 \r
  88         LOAD\r
  89                 (?<video-channel>\d+)\r
  90                 (-(?<layer>\d+))?{0}\r
  91                 (?<producer>[\d\w]+) \r
  92                 (\r
  93                         (?<transitions>CUT|MIX|PUSH|WIPE|SLIDE) \r
  94                         (?<duration>\d+)\r
  95                         (?<tween>(linear|easein|and-more))?{LINEAR}\r
  96                         (?<direction>LEFT|RIGHT)?{RIGHT}\r
  97                 )?{CUT 0}\r
  98                 (?<auto>AUTO)?{}\r
  99                 (?<parameters>.*)?{}\r
 100         \r
 101 Example::       \r
 102 \r
 103         LOAD 1-1 MY_VIDEO PUSH 20 easeinesine LOOP SEEK 200 LENGTH 400 AUTO FILTER hflip \r
 104         \r
 105 ^^^^\r
 106 PLAY\r
 107 ^^^^    \r
 108 Moves producer from background to foreground and starts playing it. If a transition (see LOADBG) is prepared, it will be executed.\r
 109 If additional parameters (see LOADBG) are provided then the provided producer will first be loaded to the background.\r
 110 If no layer is specified the default layer index will be used.\r
 111 \r
 112 Syntax::\r
 113 \r
 114         PLAY\r
 115                 (?<video-channel>\d+)\r
 116                 (-(?<layer>\d+))?{0}\r
 117                 (?<producer>[\d\w]+) \r
 118                 (\r
 119                         (?<transitions>CUT|MIX|PUSH|WIPE|SLIDE) \r
 120                         (?<duration>\d+)\r
 121                         (?<tween>(linear|easein|and-more))?{LINEAR}\r
 122                         (?<direction>LEFT|RIGHT)?{RIGHT}\r
 123                 )?{CUT 0}\r
 124                 (?<auto>AUTO)?{}\r
 125                 (?<parameters>.*)?{}\r
 126         \r
 127 Example::\r
 128 \r
 129         PLAY 1-1 MY_VIDEO PUSH 20 easeinesine LOOP SEEK 200 LENGTH 400 AUTO FILTER hflip \r
 130         PLAY 1-1\r
 131         \r
 132 ^^^^^\r
 133 PAUSE\r
 134 ^^^^^\r
 135 Pauses foreground clip.\r
 136 \r
 137 Syntax::        \r
 138 \r
 139         PAUSE \r
 140                 (?<video-channel>\d+)\r
 141                 (-(?<layer>\d+))?{0}    \r
 142 \r
 143 Example::\r
 144 \r
 145         PAUSE 1-1\r
 146         \r
 147 ^^^^^\r
 148 STOP\r
 149 ^^^^^\r
 150 Removes foreground clip. If no layer is specified the default layer index will be used.\r
 151 \r
 152 Syntax::        \r
 153 \r
 154         STOP \r
 155                 (?<video-channel>\d+)\r
 156                 (-(?<layer>\d+))?{0}    \r
 157 \r
 158 Example::\r
 159 \r
 160         STOP 1-1\r
 161 \r
 162 ^^^^^\r
 163 CLEAR\r
 164 ^^^^^\r
 165 Removes both foreground and background clips. If no layer is specified then all layers in the specified video-channel are cleared.\r
 166 \r
 167 Syntax::        \r
 168 \r
 169         CLEAR \r
 170                 (?<video-channel>\d+)\r
 171                 (-(?<layer>\d+))?{0}    \r
 172 \r
 173 Example::\r
 174 \r
 175         CLEAR 1-1\r
 176                 \r
 177 ^^^^^^\r
 178 CALL\r
 179 ^^^^^^\r
 180 Calls a producers specific function.\r
 181 \r
 182 Syntax::\r
 183 \r
 184         CALL \r
 185                 (?<video-channel>\d+\r
 186                 (-(?<layer>\d+))?{0}    \r
 187                 (?<function>[\d\w]+) \r
 188                 (?<parameters>.*)?{}\r
 189 \r
 190 Example::\r
 191 \r
 192         CALL 1-1 SEEK 400\r
 193                 \r
 194 ^^^^\r
 195 SWAP\r
 196 ^^^^\r
 197 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.\r
 198 \r
 199 Syntax::\r
 200 \r
 201         SWAP \r
 202                 (?<video-channel1>\d+)\r
 203                 (-(?<layer1>\d+))?              \r
 204                 (?<video-channel2>\d+)\r
 205                 (-(?<layer2>\d+))? \r
 206 \r
 207 Example::\r
 208 \r
 209         SWAP 1-1 1-2\r
 210         SWAP 1-0 2-0            \r
 211                 \r
 212 ^^^\r
 213 ADD\r
 214 ^^^\r
 215 Adds consumer to output.\r
 216 \r
 217 Syntax::\r
 218 \r
 219         ADD \r
 220                 (?<video-channel1>\d+) \r
 221                 (?<consumer>[\d\w]+) \r
 222                 (?<parameters>.*)\r
 223         \r
 224 Example::\r
 225 \r
 226         ADD 1 FILE output.mov CODEC DNXHD\r
 227         ADD 1 DECKLINK DEVICE 1\r
 228                 \r
 229 ^^^^^^\r
 230 REMOVE\r
 231 ^^^^^^\r
 232 Removes consumer from output.\r
 233 \r
 234 Syntax::\r
 235 \r
 236         REMOVE \r
 237                 (?<video-channel1>\d+) \r
 238                 (?<consumer>[\d\w]+) \r
 239                 (?<parameters>.*)\r
 240 \r
 241 Example::\r
 242 \r
 243         REMOVE 1 FILE \r
 244         REMOVE 1 DECKLINK DEVICE 1