CasparCG Server

From CasparCG Wiki

Jump to: navigation, search

PLEASE NOTE: This document is a work-in-progress.

Image:CasparCG_Server.jpg

  1. Input: Producers read, render and play content such as videos, animations, images and audio to a frame (and/or audio) buffer, known as a layer.
  2. Transform: The Mixer Module takes the layers from one or several producers and performs various video and audio transformations such as color transforms, de-interlacing, scaling, transitions, image adjustments and audio adjustments on each layer before compositing them together (and optionally re-interlace them.)
  3. Output: Consumers then receive the composited frames and displays them on a specified output, for example a window on the computer monitor or an SDI card.

All functionality is controlled via network commands sent with the AMCP Protocol, either by the CasparCG Client Software, or by your own custom software or a command prompt.



Contents

System Requirements

  • Intel processor capable of using SSSE3 instructions. While AMD processors probably work, CasparCG Server has only been tested on Intel processors.
  • Windows 7 (64-bit) strongly recommended. CasparCG Server has also been used successfully on Windows 7 (32-bit) and Windows XP SP2 (32-bit only.)
    • NOT SUPPORTED: Windows 8, Windows 2003 Server and Windows Vista.
  • A graphics card (GPU) capable of OpenGL 3.0 is required. We strongly recommend that you use a separate graphics card, and avoid using the built-in GPU that exists in many CPUs, since your performance will suffer.
  • For NewTek TriCaster iVGA support, please download and install the following driver: NewTek iVGA driver

* Make sure you turn off Windows' Aero theme and ClearType font smoothing as they have been known to interfere with transparency in Flash templates, and can also cause problems with Vsync when outputting to computer screens.

File:adjust-for-best-performance.png

Recommended settings in Windows

System Recommendations

CasparCG Server runs on a multitude of old and new PC hardware, and has been tested and used with several brands and models without any problems.



Recommendations

Since we've created CasparCG Server mainly for our own productions, it might be interesting to know what we normally buy when we need to add to our 50+ CasparCG playout machines.

Our current standard configuration (updated in May 2013)

Notes

The OS is installed on the standard 7200 rpm hard drive that comes with the system.

Media is placed on a software RAID-0 of the two SSDs.

We use DeckLink 4K Extreme cards for a few reasons:

  • Bluefish cards are really nice and have a great API, but they are more expensive.
  • DeckLink Quad' cards needs to be configured for separate fill and key output in CasparCG Server, while the DeckLink 4K Extreme cards automatically output the alpha as key to SDI.
  • DeckLink 4K Extreme support 1080p50 (if you use one channel for fill and one for key) which the Quads don't.
  • Most of our HD machines use DeckLink HD Extreme 3D (some use Bluefish Technologies Fury, and new machines are now being deployed with the DeckLink 4K Extreme cards) o we've tested them in production and know that there aren't any nasty bugs in the drivers, and we can swap cards without changing configuration.

We've previously bought HP Z400 XE (6-core W3680 @ 3.33GHz with 6 GB RAM (KK788EA)) which are no longer available. Before that, we tested HP Z210 workstations, but a bug in the hardware/drivers prevented the machine from running both PCI-e lanes at 16x at the same time.

We've also tried the OCZ RevoDrive 3 X2 PCI-E X4 SSD 480 GB but they were instable (Windows would suddenly loose the drive) and the real speed was only half of the specification.

Make sure you turn off the default Aero theme in Windows as it interferes with the OpenGL operation of CasparCG Server!

Processors

CasparCG Server is tested and optimized for Intel Processors.

CasparCG Server takes advantage of multi-threading, running the producers and consumers in their own threads. A multi-core CPU is highly recommended.

The Adobe Flash component is single-threaded, meaning that CPU clock speed should be prioritized over more CPU cores; i.e. a 4-core 3.2 GHz CPU is preferable to an 8-core 3.0 GHz of the same CPU family. If you are playing several Flash templates you can run several instances of Adobe Flash Player and thereby gain multi-processor performance.

Make sure that your CPU and motherboard combination supports enough PCI-lanes, e.g. Desktop Sandy Bridge processors (i.e. not the Server versions) only supports 16 PCI-lanes, which does not run more than one 1080p HD channel.

RAM

4 GB RAM (or more for 64-bit systems.) While CasparCG Server 2.0 is a 32-bit program, the fact that more RAM is available to the OS will improve the storage access of repeat readings through the built-in cache of the OS.

Storage

Keep the OS and the CasparCG media on separate drives. If you plan to play and transition between any pre-rendered QuickTime movie files, the media drive for SD material should be at least a single SATA/300 SSD.

For HD video files we recommend striped (RAID0) SSD drives supporting SATA/600. PCI-E to SATA/600 cards seem to work fine if your system doesn't have SATA/600. We've had good experiences with Highpoint's RAID cards, less so with using the built-in RAID controllers of motherboards. Our current HD servers store all media content on fast SSDs.

If you use a video codec that creates smaller files (often without alpha support,) your storage performance requirements can drop significantly.

Graphics Card (GPU)

CasparCG Server 2.0 requires OpenGL 3.0, so we encourage you to plan you hardware specifications with this consideration.

CasparCG Server is developed and tested on NVIDIA Quadro graphics cards. Other chipset may work, but have not been tested.

Chassis

We recommend using chassis with several PCI-e slots, to enable the use of several video cards.

OS

We recommend Windows 7 64-bit (any flavor.) While CasparCG Server 2.0 is currently a 32-bit program (v2.1 and later will require 64-bit), the fact that more RAM is available to the OS will improve the storage access of repeat readings through the built-in cache of the OS.

Make sure you turn off the default Aero theme in Windows as it interferes with the OpenGL operation of CasparCG Server!

Forums users have reported that CasparCG Server 2.0 runs without issue on Windows 8 provided Aero is turned off.


SDI and HDMI Cards

An SDI card

You can have multiple video output cards in the same machine and address them independently. You can also mix DecklLink and Bluefish cards in the same machine, if you wish.

Please note: If you don't need to output SDI, HD-SDI or HDMI signals, you can use the Screen Consumer to play content to play content directly to your monitor(s), without any special video output card.


Table of supported video cards


Bluefish Technologies

The current release of the CasparCG Server supports the Bluefish444 SDK from Bluefish Technologies and should work with all the manufacturer's cards. It has been tested and used with the following cards:

  • DeepBlue LT
  • Fidelity
  • Epoch Horizon

All cards from Bluefish Technologies should be able to output separate fill and key to SDI.

Please see the Table of supported video cards.


Bluefish Card Configuration

The Bluefish Feature App that can be downloaded from Bluefish Technologies doesn't have all the features needed to set up the SDI output correctly. Make sure you download the drivers provided with the SDK which will let you choose scaling and color spaces.

When installing the driver, make sure you also install the ASIO driver and Symmetry.

BlackMagic Design / DeckLink

Please see the Table of supported video cards.

The current release of the CasparCG Server's DeckLink Consumer uses the DeckLink SDK and should support all output cards from Blackmagic Design.

If you want to play out with separate fill and key channels, you need to look for a card that has both A-SDI Out and B-SDI Out in the connection diagram/technical specs. You must also check the SD/HD capabilities of the B-channel (which is used for key output.)

The Blackmagic Design DeckLink HD Extreme 3D (discontinued) and DeckLink 4K Extreme cards are the only cards from BMD that output separate fill and key to SDI in CasparCG Server in HD in perfect sync. One HD Extreme 3D/4K Extreme will output one HD-SDI channel of fill and one HD-SDI channel of key. Output separate fill and key to HDMI from these cards is not supported. If you need to get synchronized, separated fill and key output via HDMI, you will need to add external SDI-to-HDMI converters.


Outputting fill and key on other BMD cards requires you to "manually" configure CasparCG Server to output an additional channel as "key-only" which cannot be fully guaranteed to stay in perfect sync, due to forces beyond our reach (the DeckLink API.)

Genlock

Genlock is used to synchronize a signal to a common reference signal. It is supported for SDI and HD-SDI output from the Bluefish consumer and the DeckLink consumer.


Please see the Table of supported video cards.

Downloads

The current stable release of CasparCG Server, along with the official CasparCG Client, example alternative clients, sample videos and templates can always be found on the download page:

http://casparcg.com/download/

An automatic build server maintains pre-built versions of the latest CasparCG Server and Client source code at the address below, please note that these latest releases may have bugs, may crash or not conform to documentation as expected.

http://builds.casparcg.com/

Source Code

The source code can be found in our public source code repository.

Getting Started

CasparCG Server Installation

1. Check that your system meets the System requirements.

2. Unzip and place the CasparCG Server folder anywhere you like.

3. Install Microsoft Visual C++ 2010 Redistributable Package"' from http://www.microsoft.com/download/en/details.aspx?id=5555

4. Install "Flash Player 10.3.183.11" from the "Flash Player Installation" folder.

5. Make sure to disable the default Aero theme in Windows, as it interferes with CasparCG Server's OpenGL features.

6. Configure the server settings in the "casparcg.config" text file.

7. Start the "CasparCG.exe" program.

8. Connect to the server from a client software, such as the separate download, CasparCG Client 2.x.

CasparCG Server Configuration

All configuration of CasparCG Server is done in the text file caspar.config which can be edited in any text editor. If you want to change the location (for example to a faster disk) you just change the paths in the casparcg.config file.

Use the \ character in front of any special character, so that C:\CasparCG\ is written C:\\CasparCG\\

At the bottom of the casparcg.config file you will find comments which document additional settings.

Paths Configuration

File:RootFolder.png

To tell the CasparCG Server where to look for media files, change the following paths in the configuration file.

You can change these paths to any path you'd like, for example a fixed path such as L:\\CasparCG\\ or \\\\my-server\\ or even a relative path (calculated from the Server's EXE file) such as Media sub-folder\\' Please note: All paths should be terminated with a backslash (meaning that it should be entered as \\.

We recommend that you place your media and templates files locally, on a fast disk that is not the same disk used for the operating system.


log-path: Path to folder with all logs.

media-path: CasparCG Server will look in the media folder (and its sub folders) for videos, audio and images files.

template-path: CasparCG Server will look in the templates folder (and its subfolders) for Flash templates.

template-host: Path to Flash TemplateHost files.

data-path: Path to folder where "data" is read from and written to. CasparCG Server will look in the data folder (and its sub folders) for data loaded by Flash templates.

 <paths>
    <media-path>C:\\casparcg\\_media\\</media-path>
    <log-path>C:\\casparcg\\_log\\</log-path>
    <data-path>C:\\casparcg\\_data\\</data-path>
    <template-path>C:\\casparcg\\_templates\\</template-path>
    <template-host>cg.fth.20</template-host>
 </paths>

log

Available in version 2.1.0 onwards. Allows a remote client to monitor the Caspar CG Server log by connecting to the defined port, if added to the config file in the controllers section as shown below (other controllers not shown.

<controllers>
 ...
 <tcp>
  <port>3250</port>
  <protocol>LOG</protocol>
 </tcp>
</controllers>

Implemented by hellgore in this commit

diagnostics

The diagnostics window can be opened using the AMCP command DIAG

Graphs option determines whether the diagnostics window will display graphs or not.

<diagnostics>
 <graphs>true [true|false]</graphs>
</diagnostics>

See graph descriptions for more information about interpreting diagnostic graphs.

Auto-Mode

CasparCG Server 2.0 supports automatic real-time conversion of video-files encoded in other video modes than the channel is running.

Note: Auto-mode is highly dependent on that the clips are encoded correctly with frame-rate and interlacing meta-data.

 <auto-mode>[true|false]</auto-mode>

Buffering

buffer-depth

  <consumers>
     <buffer-depth>[2..]</buffer-depth>
  </consumers>

Buffer depth configures the depth of CasparCG Server's consumer buffers. Lower buffer-depth will decrease frame latency, however the software will be less tolerant to performance spikes.

Different consumers have different minimum buffer-depths to function properly. The buffer-depth setting should be set to the highest depth of any of the used consumers.

It is recommended (but not required) to use a buffer-depth of 2 frames over minimum.


Minimum buffer depth for different consumers
Bluefish 2
Decklink 3
Decklink + emb audio 4
Decklink + low-latency 2
Decklink + emb audio low-latency 3
Screen 2
Audio 3

pipeline-tokens

<pipeline-tokens>[2..]</pipeline-tokens>

The number of tokens that can be active in the rendering pipeline. Currently the pipeline has two parallel stages so for maximum performance you should have 2 tokens. Adding more than 2 tokens can provide buffering for hiding performance spikes. Each token causes a delay of 1 frame, so setting it to 25 causes the pipeline to render at maximum performance (since >=2) and then adds 23 frames of extra buffering.

Setting pipeline-tokens to 1 for a channel reduces the delay from input to output by 1 frame. Please note that reducing the delay/buffering can have impact on performance and spike tolerance.

Channels Configuration

The resolution and frame rate of the channel must be specified.

 <channels>
   <channel>
     <video-mode> PAL [PAL|NTSC|576p2500|720p2398|720p2400|720p2500|720p29.976|720p30|720p5000|720p5994|720p6000|1080p2398|1080p2400|1080p2500|1080p2997|1080p3000|1080p5000|1080i5000|1080p5994|1080i5994|1080p6000|1080i6000|2160p2398|2160p2400|2160p2500|2160p2997|2160p30] </video-mode>
     <consumers>
     </consumers>
   </channel>
 </channels>

Please note that the 4K (3840x2160) support requires CasparCG Server 2.0.4 or later.

Video Formats

These formats are supported in a channel, and can be configured either in the caspar.config file or via the SET command.

See also: Table of supported video cards


Video Format

(Parameter)    

Frame Rate     Field order     Resolution (square pixels)     Resolution (non-square pixels) Notes
PAL 50i Upper/Odd 1024x576 720x576
NTSC 59.94i Lower/Even 720x540 720x486
576p2500 25p Progressive 1024x576 Not supported by output cards from BlackMagic Design
720p2398 23.976p Progressive 1280x720 Not supported by output cards from BlackMagic Design
720p2400 24p Progressive 1280x720 Not supported by output cards from BlackMagic Design
720p2500 25p Progressive 1280x720
720p2997 29.976p Progressive 1280x720 Not supported by output cards from BlackMagic Design
720p3000 30p Progressive 1280x720 Not supported by output cards from BlackMagic Design
720p5000 50p Progressive 1280x720
720p5994 59.94p Progressive 1280x720
720p6000 60p Progressive 1280x720
1080p2398 23.976p Progressive 1920x1080
1080p2400 24p Progressive 1920x1080
1080p2500 25p Progressive 1920x1080
1080p2997 29.976p Progressive 1920x1080
1080p3000 30p Progressive 1920x1080
1080p5000 50p Progressive 1920x1080
1080i5000 50i Upper/Odd 1920x1080
1080p5994 59.94p Progressive 1920x1080
1080i5994 59.94i Upper/Odd 1920x1080
1080p6000 60p Progressive 1920x1080
1080i6000 60i Upper/Odd 1920x1080
2160p2398 23.976p Progressive 3840x2160 4K support requires CasparCG Server 2.0.4 or later.
2160p2400 24p Progressive 3840x2160 4K support requires CasparCG Server 2.0.4 or later.
2160p2500 25p Progressive 3840x2160 4K support requires CasparCG Server 2.0.4 or later.
2160p2997 29.976p Progressive 3840x2160 4K support requires CasparCG Server 2.0.4 or later.
2160p3000 30p Progressive 3840x2160 4K support requires CasparCG Server 2.0.4 or later.

Consumers Configuration

Consumer configuration lives within the consumers section of a channels configuration.

<channel>
 <consumers>
 ..
 </consumers>
</channel

<decklink>

Please note: This applies to all supported cards from BlackMagic Design, not just their DeckLink product range.

 <decklink>
    <device>[1..]</device>
    <embedded-audio>false [true|false]</embedded-audio>
    <latency>default [normal|low|default]</latency>
    <keyer>external [external|internal|default|external_separate_device]</keyer>
    <key-only>false [true|false]</key-only>
    <buffer-depth>3 [1..]</buffer-depth>
    <key-device>device + 1 [1..]</key-device>
 </decklink>

From v2.0.7 Beta 2 onwards, it is possible to use a separate Decklink device (note that this could be a separate device on the same physical card) to produce a key signal if required, prior to this version, a Decklink card with a separate key facility (such as the HD Extreme) was required. To use another device as a key signal, set <key-device> to the device to be used to output a key signal, and set <keyer> to external_serparate_device.


<bluefish>

 <bluefish>
   <device>[1..]</device>
   <embedded-audio>false [true|false]</embedded-audio>
   <key-only>false [true|false]</key-only>
 </bluefish>

<screen>

 <screen>
   <device>[0..]</device>
   <aspect-ratio>default [default|4:3|16:9]</aspect-ratio>
   <stretch>fill [none|fill|uniform|uniform_to_fill]</stretch>
   <windowed>false [true|false]</windowed>
   <key-only>false [true|false]</key-only>
   <auto-deinterlace>true [true|false]</auto-deinterlace>
   <vsync>false [true|false]</vsync>
   <name>[Screen Consumer]</name>
   <borderless>false [true|false]</borderless>
 </screen>
<name>

Allows the title bar label to be changed, if not, Caspar CG will generate one containing information about the channel and its format.

<borderless>

Windows title bar and border around the window will no longer be visible, this is most useful for developers writing applications to run on the same machine as Caspar CG Server where the screen consumer can then be embedded into the application.

<newtek-ivga>

Allows the NewTek TriCaster series of vision mixers to receive input from Caspar CG via network (note, from v2.0.7 Beta 2 onwards, driver also required, see System Requirements)

<newtek-ivga>
  <channel-layout>stereo [mono|stereo|dts|dolbye|dolbydigital|smpte|passthru]</channel-layout>
  <provide-sync>true [true|false]</provide-sync>
</newtek-ivga>

<file>

<file>
 <path></path>
 <vcodec>libx264 [libx264|qtrle]</vcodec>
 <separate-key>false [true|false]</separate-key>
</file>

<stream>

The below is an example usage for the streaming consumer configuration, there are no defaults for this consumer (note, from v2.0.7 Beta 2 onwards)

<stream>
 <path>udp://localhost:5004</path>
 <args>-vcodec libx264 -tune zerolatency -preset ultrafast -crf 25 -format mpegts -vf scale=240:180</args>
</stream>




Certain configuration elements applicable to multiple consumers are explained below in a little more detail.

<device>

Chooses which device to use if you have several of the same kind. Devices identified by Caspar are listed at the top of the console on start-up (not that this will not be displayed if Caspar is set to log warnings and above only) with a number in square brackets next to them. This number is the device number that should be used here.

<device>[1..]</device>

<embedded-audio>

Turning on embedded audio for a channel adds a delay of 1 frame. Default is false.

<embedded-audio>false [true|false]</embedded-audio>

<latency>

Setting latency to low for a channel reduces delay by 1 frame. Can have impact on performance and spike tolerance.

<latency>default [normal|low|default]</latency>        

<system-audio>

Enables output through the default audio device of your hardware. This should be applied to the <consumers> section, not to an individual consumer, for instance:

<consumers>
 <screen>
  ..
 </screen>
 <system-audio>false [true|false]</system-audio>
</consumers>

Configuration Examples

How to enable the Screen Consumer

Open the casparcg.config in a text editor and use the following node for consumers:

 <consumers>
 	<screen/>
 </consumers>

How to enable the DeckLink Consumer

To get video in and key output, open casparcg.config in a text editor and use the following node for consumers:

<consumers>
	<decklink/>
</consumers>





Configuring Vision Mixers

It's important that you set up your vision mixer (also called video switcher or production switcher) to correctly apply the key signal that CasparCG Server outputs. Unfortunately, different manufacturers use different terminology for the DSK (down-stream keying.)

You generally want to use content with pre-multiplied against black (also know as linear or additive) alpha / key since content played by the Flash Producer is always pre-multiplied against black. You also want to avoid modifying the key signal in the vision mixer, so keep the settings for clip, gain, opacity/density to their defaults.

Grass Valley Configuration

On Thomson Grass Valley vision mixers / switchers, the correct keying settings are as follows:

  • Mode: Additive Key
  • Size: Off
  • Position: Off
  • Gain: 100.0 %
  • Clip: 50.0 %
  • Opacity: 100.0 %


Correctly configured DSK keying for CasparCG on a Grass Valley vision mixer / switcher



Sony Configuration (newer)

On newer Sony vision mixers / switchers, the correct keying settings are as follows:

  • Key Type: Linear
  • Mode: Clean Mode
  • Key Fill: Key Bus
  • Clip: 0.00
  • Gain: 0.00
  • Density: 100.00


Correctly configured DSK keying for CasparCG on a Sony vision mixer / switcher

Sony Configuration (older)

On older Sony vision mixers / switchers (DVS-7250,) the correct keying settings are as follows:

  • Key Type: Clean
  • Clip: 0.00
  • Gain: 30.00
  • Density: 100.00


Correctly configured DSK keying for CasparCG on a Sony vision mixer / switcher

Blackmagic Design ATEM Configuration

Image:BMD_ATEM.png

  • Connect both fill and key SDI outputs from your SDI card to the inputs on the Blackmagic Design ATEM production switcher.
  • In the software control panel, open "Downstream Key 1" panel on the right.
  • In the Fill Source and Key Source dropdowns, select the applicable inputs and check the "Pre Multiplied Key" checkbox. The ATEM should now be correctly configured for DSK 1.

Vision Mixers supporting only straight alpha

In CasparCG 2.0.4 there is experimental support for outputting straight alpha instead of pre-multiplied against black alpha.

It is enabled in the configuration under the channel:

<channel>
  <straight-alpha-output>true</straight-alpha-output>
  <consumers>
  </consumers>
</channel>

Please see MIXER STRAIGHT_ALPHA_OUTPUT command for information about how to change this setting in real-time, overriding the configuration.

Note that although straight alpha output is enabled, the material (videos, stills etc) played out by CasparCG still has to be pre-multiplied against black.


Channels

A CasparCG Server's channels can be compared to as a pipeline that starts with one or several input modules (called "producers") and ends with an output (called a "consumer.")

Layers

Each channel can contain up to 9,999 layers of content (with both fill and key/alpha) such as video, Flash templates, , Audio, Flash_Templates, images and colors, rendered by one of the producers. layers that can then be reorganized, restaked, animated and changed in realtime in CasparCG Server's Mixer module.

The bottom-most layer is layer 0 and layer 9999 is the top-most layer.

If you load content into a layer that already contains something, that content is replaced.

Producers (Input Modules)

A producer is a CasparCG Server module for input and rendering of media content such as video, animations, images and audio. Each producer has different capabilities.

A producer listens for commands and data sent from a client controller, then loads and renders that media as a separate content layer into the Mixer Module and sends it to a consumer that displays that media in a variety of ways.


Flash Producer

Image:Flash_Producer.jpg

The Flash Producer uses Adobe’s Flash Player to play Content_/_Media#SWFs including full control over all dynamic content. You can even load multiple Flash files as layers that is stacked and composited by the CasparCG Server Mixer module and can then be controlled independently from a client program. Several Flash Player instances can also be loaded to get around the single-threaded nature of the current Flash Player.

Please see the AMCP commands section for a complete reference of the AMCP commands used to control this module.


Supported Media

  • .ft Flash template (a SWF that has gone through the TemplateGenerator.)
  • .ct A zip-compressed folder that contains a Flash template together with media and XML data.
  • .swf A regular SWF file.

File Path

All files played by this producer must be placed in the root folder (by default C:\CasparCG\) or in a user-created sub folder.

Interlacing

In the current version of CasparCG Server, if the criteria for rendering with fields is met the Flash Producer will always renders with fields (interlacing.)

By changing the frame rate in the Flash Document properties inside Adobe's Flash Professional to twice the normal rate, the Flash Producer and a consumer will output interlaced dynamic output.

Criteria for Rendering with Fields

When the Flash Producer is launched, it communicates with the consumer and receives three settings that is then used to setup the rendering:

  • Whether the consumer is set to either progressive or fields-based rendering.
  • What resolution the consumer is set to output.
  • What frame rate the consumer is set to output.

Diagnostics

flash[template-host | video-mode]
Graph Description Scale
frame-time Time spent rendering the current frame. fps/2
tick-time Time between rendering two frames. fps/2
param The latest invoked Flash command. -
late-frame Frame was not ready in time and was skipped. -
sync Synced time between rendering two frames. fps/2


TemplateHost

The TemplateHost is Flash Player instance(s) that load and play Flash templates inside CasparCG Server.

Each CasparCG channel loads all the Flash templates in the same instance of a TemplateHost. That instance of the TemplateHost can then play multiple Flash layers (not to be confused with channel layers.)


Hosting

The TemplateHost loads the templates into a container and keep track of the different layers. There are also logic that handles the layers, e.g it’s possible to load a template into a currently occupied layer (like LOADBG). The Load command tries to cast the loaded file as an ICasparTemplate, and if it fails, it currently uses the DefaultTemplateAdapter assuming it is a 1.6 version of the template.

Commands

The commands that are received from the CasparCG Server are handled by any of the command classes. The corresponding command class is instantiated and put into the command queue which makes sure that a command is finished before the execution of the next command.

CasparCGComponents

A CasparCG component is a module that can receive data from a client (via the server). In the current version, the only included component is the CasparTextField which is a wrapper for the normal TextField class in flash which implements the CasparComponent interface. The dynamic textfields are automatically converted to CasparTextFields when the template is generated by the template generator, this is done by injecting a frame script:

registerComponent(new CasparTextField(f0));

The idea was to make it easy for developers to create custom CasparCG components, but the process of creating components for the Flash IDE is quite inconvenient and we have only created one of these components so far, the CasparImage component.

It is however very easy to create code based custom components. You only have to implement the ICasparComponent interface, and then call registerComponent and passing your instance to make it work. The registerComponent tells the ComponentDataBuffer (which stores data for instances that are not yet instantiated) that the component is ready to receive data. The data is then passed to the components SetData function as xml. This is normally not the current workflow, often developers override the SetData function in the document class and manually parse and populate their elements.

Metadata

One really nice feature with the current version is that the template has the possibility to store metadata which can be accessed with the info <template name> command in the server. If you use the CasparTextfield or the CasparImage, metadata is automatically stored inside the template like this:

<template version="2.0.0" authorName="Andreas Jeansson" authorEmail="andreas.jeansson@somebroadcaster.se" templateInfo="Template info goes here" originalWidth="1920" originalHeight="1080" originalFrameRate="50">
 <components>
   <component name="CasparTextField">
     <property name="text" type="string" info="String data"/>
   </component>
   <component name="CasparImage">
     <property name="text" type="string" info="URL to the image to load (.png, .jpg, .gif)"/>
     <property name="x" type="number" info="X position offset"/>
     <property name="y" type="number" info="Y position offset"/>
     <property name="scale" type="number" info="The scale of the image (in percent)"/>
     <property name="mirrorX" type="boolean" info="If true the image is mirrored in the x axis"/>
     <property name="mirrorY" type="boolean" info="If true the image is mirrored in the y axis"/>
     <property name="opacity" type="number" info="The opacity of the image (in percent)"/>
     <property name="rotation" type="number" info="The rotation of the image (in degrees)"/>
     <property name="bitmap" type="string" info="URL to the image to load (.png, .jpg, .gif)"/>
   </component>
 </components>
 <keyframes>
   <keyframe name='outro'/>
 </keyframes>
 <instances>
   <instance name="f0" type="CasparTextField"/>
   <instance name="image1" type="CasparCGImage"/>
   <instance name="f1" type="CasparTextField"/>
 </instances>
</template>

This makes it possible for a client to create a custom interface for each template which makes much more user friendly to work with a template.

There is in theory a way to expose this information even from code based custom components, but it is not really convenient.

Communication

The commands from the server are sent via the external interface and are handled as described above. Some commands return data, and this data is also returned via the external interface. There are also some events where the TemplateHost calls the server, this is when there is an error in the host or in the template (which will be displayed in the log by the CasparCG Server) and when there are no templates loaded (which will make the server kill the flash player and instantiate a new one the next time a template is added). There is also the traceToLog function which makes it possible to write arbitrary data from the template to the CasparCG log file. The data flow from CasparCG Server to template and back could be describes as this:

SetData command example:

Server --ExternalInterface--> TemplateHost --SetDataCommand instance --> ExternalCommandsBuffer --> template SetData function

TraceToLog example:

Template TraceToLog function --CasparTemplateEvent --> TemplateHost --ExternalInterface--> Server --> CasparCG Server log

To fully understand the architecture it is necessary to dive into the source files which can be found in the source code repository.


Wish list for the future

Here are some points that should be investigated and hopefully implemented in the future versions.

Performance:

  • Investigate if we could use the gpu for rendering in some way
  • Optimize code
  • Check the possibility to load each template into a separate worker
  • Investigate if we could find a way to boost the performance on the template rendering inside the TemplateHost (e.g. forcing bitmap caching on all templates or maybe using blitting). I don’t know what possibilities we have to affect the rendering on a low level.
  • Investigate if there is any gains in using AIR
  • Integrating the Adobe Scout in the template creation process

Workflow:

  • Make it possible to create a template without using the template generator, which would remove the need to use Flash professional.
  • Make it easier for designers to create dynamic templates
  • Simplify the use of custom components

Compatibility:

  • Adding support for swf files and make it possible to call public functions by using the invoke command
  • Keeping the compatibility for 1.7 - 2.0 templates (ft-files) and .ct files

Architectural:

  • Automatically generated meta data without the template generator
  • Make the TemplateHost convert the xml into native flash types that is defined by the component, removing the need for xml-parsing.
  • Removing the Mixer since it is no longer needed
  • Removing the support for 1.6 templates
  • Rebuild the template to template communication (CommunicationManager) and maybe move this logic to the server (which would make it possible to easily implement template to client communication).
  • Separating the TemplateHost from the template (in the current version they are very dependent).
  • Investigate if the .ct logic should be moved to the server

FFmpeg Producer

Image:FFmpeg_Producer.jpg

Supported Media

The FFmpeg Producer can play all media that FFmpeg can play, which includes many QuickTime video codec such as Animation, PNG, PhotoJPEG, MotionJPEG, as well as H.264, FLV, WMV and several audio codecs as well as uncompressed audio.

The FFmpeg Producer can also play from direct show devices such as USB cameras connected to the server.

Please see the AMCP commands section for a complete reference of the AMCP commands used to control this module.

File Path

All files played by this producer must be placed in the _Media sub folder, by default C:\CasparCG\_Media

Transitions Between Videos

You can play two simultaneous video files from disk to the same consumer during any of the built-in transitions such as mix, wipe, push and slide of a user-selectable number of frames. If your video files have alpha channel (key) those will work as well.

Sending FFmpeg-specific parameters

The FFmpeg producer supports “libavfilter” filters through the FILTER parameter in the LOADBG command.

File Naming

Even though most producers support Unicode characters, there are some limitations in the FFmpeg Producer that causes media not to be found if it contains less common characters and even spaces. This can be avoided by always enclosing file names in quotation marks when they are being sent in AMCP commands, or by avoiding them when naming the files.

Recommended: Show-Titles_A_03_Upper_Alpha.mov

Can cause problems in FFmpeg Producer if commands are not enclosed in quotation marks: Show Titles A 03 Upper Alpha.mov

Diagnostics

ffmpeg[filename | video-mode | file-frame-number / file-nb-frames]
Graph Description Scale
frame-time Time spent decoding the current frame. fps/2
buffer-count Number of input packets buffered. 100
buffer-size Size of buffered input packets. 64MB
underflow Frame was not ready in time and is skipped. N/A
seek Input has seeked N/A

AMCP Command

The general format of the AMCP command is:

PLAY <channel>-<layer> <resource> <parameters> ...

channel is the output channel on which to play the resource.

layer is the channel layer on which to play the resource.

resource is a resource identifier. This can be a filename, or a URI like specification such as "dshow://video=Some Camera" which will open the USB camera 'Some Camera' connected to the CasparCG server.

AMCP Parameters

LOOP

{LOOP}

If this parameter is sent with either LOADBG, LOAD, PLAY or CALL, the file will automatically loop.

Example:

PLAY 1-1 MOVIE LOOP

SEEK

SEEK [frames:int]

Currently only supported for video files, not audio files.

If this parameter is sent with either LOADBG, LOAD, PLAY or CALL it sets the start of the video file, in frames. This producer will instantly start playing at this point.

Example:

PLAY 1-1 MOVIE SEEK 100 LOOP

START

START [frames:int]

Introduced in CasparCG Server 2.1. Currently only supported for video files, not audio files.

Sets the start of the file in milliseconds. This point will be used as the starting point while looping.

Example:

PLAY 1-1 MOVIE START 100 LOOP

LENGTH

LENGTH [frames:int]

Currently only supported for video files, not audio files.

Sets the end point (the last frame that will be played or the end loop point.)

Example:

PLAY 1-1 MOVIE LENGTH 100

FILTER

FILTER [libavfilter-parameters:string]

Configures which libavfilter will be used.

Example:

PLAY 1-1 MOVIE FILTER hflip:yadif=0:0

A complete list of filters and a description of their purpose can be found here http://libav.org/libavfilter.html#Video-Filters

AMCP Functions

LOOP

LOOP [loop:0|1]

Sets whether file will loop or not.

Returns the value of LOOP after the command has completed.

Examples:

CALL 1-1 LOOP 1

Enables the looping on 1-1.

CALL 1-1 LOOP

Queries the parameter value, without changing it.

SEEK

SEEK [frames:int]

Seeks in the file.

Currently only supported for video files, not audio files.

Syntax:

Returns nothing. Example:

CALL 1-1 SEEK 200

START

START [frames:int]

Introduced in CasparCG Server 2.1. Currently only supported for video files, not audio files.

Sets the start of the file. This point will be used while looping.

Example:

CALL 1-1 START 100

LENGTH

 LENGTH [frames:int]

Introduced in CasparCG Server 2.1. Currently only supported for video files, not audio files.

Sets the end of the file.

Example:

CALL 1-1 LENGTH 100P

Image Producer

Image:Image_Producer.jpg

The Image Producer displays bitmap images with and without alpha channel.

Please see the AMCP commands section for a complete reference of the AMCP commands used to control this module.


Image Files

  • All files played by this producer must be placed in the media sub folder, by default C:\CasparCG\media
  • CasparCG uses the FreeImage Library to handle image files so in theory will handle all file formats listed on the FreeImage feature page.

Images are not scaled, so must be created in the same resolution as the current consumer, for example 720x576 for PAL SD, 1280x720 or 1920x1080 for HD if they are intended to fill the screen. If the resolution of the image specified is larger than the current consumer the image will be shrunk to fit.

Example usage

Directly outputting an image

The below command will play the image test_image on channel 1, layer 2

PLAY 1-2 test_image

Preloading an image

As with video files, an image can be loaded in advance using the LOADBG command, the below command will load the image test_image on channel 1, layer 2

LOADBG 1-2 test_image

The image can then be output by sending the command

PLAY 1-2




Image Scroll

Can be used with the LOADBG, LOAD and PLAY commands.

MY_FILE SPEED [speed:int] BLUR [blur:int] PREMULTIPLY PROGRESSIVE

The Image Scroll displays bitmap images with and without alpha channel in the same manner as the Image Producer but also scrolls the image if it is larger than the consumer resolution. This feature was released in CasparCG Server 2.0.3.

AMCP Parameters

SPEED
SPEED [speed:int]

Specifies the speed in pixels per frame/field, negative numbering will reverse the scroll direction.

Example: If the Caspar consumer, is set to an output format of 1920 x 1080 and we have an image with a resolution of 1920 x 4000 in our media folder called test_scroll, the image can be made to scroll vertically from bottom to top on channel 1 layer 2 at 5 pixels per frame speed by entering:

PLAY 1-2 test_scroll SPEED 5

If we wish to scroll the image from top to bottom, we can do this by putting a negative speed entry in, the command below does exactly the same as the one above but will scroll the image down the screen instead of up at 5 pixels per frame speed.

PLAY 1-2 test_scroll SPEED -5
BLUR
BLUR [blur:int]

Specifies how much motion blur should be applied to the image. Make sure that you give CasparCG Server enough time to process the image; we recommend you use this with LOADBG.


Example:

PLAY 1-2 test_scroll SPEED 5 BLUR 50
PREMULTIPLY
PREMULTIPLY

Premultiplies images with straight alpha channel against black. Example:

PLAY 1-2 test_scroll PREMULTIPLY
PROGRESSIVE
PROGRESSIVE

When using an interlaced video format, Caspar will use field rate motion based on the speed value, if progressive frame based motion is desirable then Caspar's default behaviour can be adjusted by adding this argument onto the command.

Example:

PLAY 1-2 test_scroll SPEED 5 PROGRESSIVE

Recommendations for smooth scrolling

  • For interlaced video formats always use an even speed value (2, 4, 8, 10 etc). The reason for this is that otherwise the image will loose half of its vertical resolution while scrolling. This is only important when scrolling vertically though (credit rolls for example.)
  • For interlaced video scrolling vertically, avoid thin horizontal and sharp details, because it will flicker during scrolling.
  • Apply a slight motion blur in the direction where the image is supposed to be scrolled, this will reduce the flickering effect but loose some detail. This can be done by CasparCG Server on loading the image via the BLUR parameter but it will add to the load time (filtering speed is related to the number of pixels to blur.) Another way of doing it is to apply a directional blur into the image itself, for example the "Motion Blur" filter in Photoshop.
  • Images are sometimes stored with straight alpha by image editors. If so the PREMULTIPLY parameter must be given in order for CasparCG Server to perform as expected when rendering.
  • For progressive video formats the speed value can have uneven values or even values without a problem with vertical resolution.
  • Don't use decimal speed values unless 1 pixel per frame/field is too fast, because the brightness of details in the image might appear to change when the image is placed with subpixel accuracy between two pixels.

Examples of scrolling commands

If you are using the video format 1080i5000 and have created a bitmap image with the exact width of 1920 pixels (and a height more than 1080 pixels) called cred_1080.tga you can write:

PLAY 1 cred_1080 SPEED 6

...or if the TGA image is not stored with premultiplied alpha:

PLAY 1 cred_1080 SPEED 6 PREMULTIPLY

If you get too much interline jitter during scrolling of sharp details you can add a BLUR value of, for example, 4 pixels:

PLAY 1 cred_1080 SPEED 6 PREMULTIPLY BLUR 4

If you want a film-like, choppy motion, but keep the same total scrolling duration (since the movement now occurs only 25 times per second instead of 50 times per second) the speed is doubled to appear to scroll in the same speed:

PLAY 1 cred_1080 SPEED 12 PREMULTIPLY BLUR 4 PROGRESSIVE


If the performance overhead of the motion blur is to high to be able to start the credits on time, consider doing a LOADBG in good time before and then just PLAY when the time comes:

LOADBG 1 cred_1080 SPEED 12 PREMULTIPLY BLUR 4 PROGRESSIVE
PLAY 1

For horizontal crawler/ticker, the same techniques applies, but the image file needs to be exactly 1080 pixels high instead of 1920 pixels wide.

Color Producer

Image:Color_Producer.jpg

The Color Producer generates a solid RGB color as fill and a grayscale value as key. The purpose of the producer is mainly to be used as an output test.

Please see the AMCP commands section for a complete reference of the AMCP commands used to control this module.


AMCP Parameters

To trigger the color output, send a hash tag # followed by the hexadecimal value of each of the fill channels in the order blue, green and red followed by the value of the key (optional). There are many online colour pickers available to help you select a colour, ColorPicker.com is one of these, Adobe Photoshop and GIMP can also display hexadecimal values. It should be noted that all of these sites allow you to choose RGB hex values but not the key or alpha as they're largely designed for website development.

To get a full field white background on channel 1:

PLAY 1 #FFFFFF

To get a solid blue with a fully white key:

PLAY 1 #FF0000FF

As with other producers, you can produce a color on a specific layer by appending the layer number to the channel, the below command put full field white on layer 2 of channel 1

PLAY 1-2 #FFFFFF

DeckLink Producer

Image:DeckLink_Producer.jpg

The Decklink producer allows video sources to be input from BlackMagic Design cards and used as CasparCG Server layers so that CasparCG Server's Mixer can then be used to manipulate the layer. Note that the DeckLink Producer is separate from the DeckLink Consumer which can be used to output from Caspar as HD/SD SDI or HDMI.

Please see the Table of supported video cards.

Please see the AMCP commands section for a complete reference of the AMCP commands used to control this module.


Supported Devices

The current release of the CasparCG Server's DeckLink Consumer uses the DeckLink SDK and should support all BlackMagic Design cards. Please note that the only certain cards support synced output of simultaneous fill and key to SDI. Please see the Table of supported video cards.

Multiple cards can be used inside a PC, the computer's specification will determine how many cards can be supported.

PSD Producer

The PSD Producer is a producer that can read the Adobe Photoshop .psd fileformat. This can be used to create templated graphics similar to the Flash Producer, but with a few big differences.

Differences compared to the Flash Producer

  • All compositing is done internally in caspars own mixer.
  • Easy to reference and embed other media
  • Authoring is done straight in Photoshop.
  • No programming required / possible.

Usage

  • All layers in the .psd document are preserved and treated separately by the caspar mixer.
  • Layers that are hidden are ignored
  • The opacity and position of a layer is preserved and animatable (via the video timeline feature in Adobe Photoshop)
  • All blend modes, with the exception of 'dissolve', are supported and influences media playing on other video layers
  • strokes on shape layers are ignored
  • only solid color is supported as fill for shape layer
  • Text layers
    • Text layers are by default exposed as text fields.
    • Properties of text layers that are preserved are:
      • Rotation and non-uniform scaling
      • Font, font size, font variation (bold, italic etc)
      • Color
      • Tracking
    • Example of properties that are ignored:
      • Shearing
      • Faux bold, faux italic, superscript etc.
      • Per character horizontal and vertical scaling
  • Masks
    • Bitmap masks are ignored
    • clipping masks are ignored
    • Vector masks (and shape layers) that consists of a single ortogonal rectangle are treated as clip-rectangles.
    • Vector masks (and shape layers) that consists of a single four cornered polygon can be treaded as corners in a perspective transformation (see "cornerpin" below).
    • Vector masks (and shape layers) that contains smooth curves are ignored.
  • Groups
    • Groups a preserved and gets an extra responsibility in that it can be used to contain the effects of dynamic text-layers.
    • All kinds of masks on groups are ignored
  • 3D
    • None of the 3D features are supported yet

Dynamic content

In order to control how layers behave in response to dynamic data, they can be tagged with special keywords. These tags have to be placed within square brackets in the beginning of the layer name. Multiple tags are separated by a comma and/or a whitespace. Ex. "[dynamic] f0" or "[producer, resizable] glow_loop loop"

Available tags

dynamic
This tag indicates that the content of the layer is dynamic and can be changed runtime. The layer name (excluding the tags section) is treated as a variable name that can be assigned data in the save was as data is sent to a Flash Producer (i.e. with the AMCP CG command). This is the default for text layers, but can be explicitly specified to indicate which text layer in a group that should be the "master" layer that other layers adapt to. Only one master layer is allowed in each group / the root layer list. If theres is any ambiguity, the topmost layer is used.
Please see CG command.
(This only makes sense on text layers for now. Can't be combined with static, movable or resizable)
static
This is to indicate that a text layer should be treated as static content.
(only makes sense on text layers. Can't be combined with dynamic)
movable
Indicates that the layer should move in response to a dynamic layer growing or shrinking
(can't be combined with dynamic or resizable)
resizable
Indicates that the layer should grow or shrink in response to a dynamic layer growing or shrinking. If this tag is applied to a layer with a vector mask, it's the mask that's resized instead of the bitmap.
(can't be combined with dynamic or movable)
producer
With this tag the layer acts as a placeholder for a dynamically loaded caspar producer. The layer name (excluding the tags section) is treated as a parameter to the AMCP Load-command. It is recomended to use a shape layer or a vector mask to define the area in which the content is to be rendered. Without an explicit vector mask (or shape layer) the bounding box of the layer's bitmap-data is used to define the area.
cornerpin
This tag only makes sense with the producer tag and indicates that the corners of the layer mask should be treated as the corners of a perspective transformation in the Mixer.
Please see MIXER PERSPECTIVE command.
(can't be combined with resizable)

If you specify incompatible tags on a layer, the later one (the rightmost) gets precedence.

Route Producer

Provides a way of routing frames from other producers from one channel or layer to a layer on another channel.

AMCP Command

There are two commands that can be used for routing layers and channels. The ROUTE command, and the normal PLAY / LOAD / LOADBG commands.

PLAY [destinationchannel:int]{-[destinationlayer:int]} [route://][sourcechannel:int]{-[sourcelayer:int]}

Where:

channel-layer is the destination channel and layer.

source channel - source layer is the source channel and layer to be routed through to the destination.

Note that the "route://" is optional (but preferred), and if omitted will route the source layer to the <channel>-<layer>.

PLAY [sourcechannel:int]{-[sourcelayer:int]} [route://[destinationchannel:int]

The command above can be used to route the "source channel" through to another channel-layer.

Framerate Producer

Provides a way of adjusting the playback speed of particular channels. Available in server version 2.1 builds after 7/3/16

AMCP Command

CALL [channel:int]{-[layer:int]} FRAMERATE {[frame:int]} {INTERPOLATION [interpolation:BLEND, BLEND_ALL]}
  • Frame integer if supplied will cause the specified channel/layer to be played back at the supplied framerate.
  • Interpolation if supplied will choose how additional frames (if speed is less than channel framerate) will be created, BLEND will use the current and next frame, BLEND_ALL will use the previous, current and next frame.

Mixer (Transform/Compositing Module)

Image:Mixer.jpg

The Mixer module is where content from one (or several) producers is stacked, transformed and composited before being sent to one or several consumers.

Please see the AMCP Mixer commands section for a complete reference of the AMCP commands used to control this module.


Compositing

All media played by any producers can be composited (stacked on top of each other) using either the media's built-in in alpha channel or by using the alpha channel of another media file (for example: using one video to cut a whole in another video.) The layers are numbered from 0 upward, with layer 0 as the bottom-most layer in the composite.


Transforms

The MIXER module can perform a number of real-time transforms to individual layers, by using the GPU.

Position

The position of each layer can be set individually, and this value can also be automatically animated. This is a real-time effect, calculated on the GPU.

Please see MIXER FILL command.

Scaling

The scale of each layer can be set individually in both X and Y axis, and this value can also be automatically animated. This is a real-time effect, calculated on the GPU.

Please see MIXER FILL command.

Rotation

Rotation is supported through the MIXER ROTATION command from version 2.0.7 stable.

Image Adjustments

The MIXER module can perform a number of real-time adjustments to layers, by using the GPU.

Blend Modes

Every layer in the Mixer module can be set to a blend mode over than the default Normal mode, similar to applications like Photoshop. Some common uses are to use screen to make a all the black image data become transparent, or to use add to selectively lighten highlights.

Please see MIXER BLEND command and the supported Blend Modes.

Opacity

The alpha channel of each layer can be set to a specific opacity value in order to change the transparency. The value can also be automatically animated. This is a real-time effect, calculated on the GPU.

Please see MIXER OPACITY command.

Brightness

The brightness of the content (RGB) of each layer can be adjusted in real-time on the GPU. The value can also be automatically animated.

Please see MIXER BRIGHTNESS command.

Saturation

The color saturation of the content (RGB) of each layer can be adjusted in real-time on the GPU. The value can also be automatically animated.

Please see MIXER SATURATION command.

Contrast

The contrast of the content (RGB) of each layer can be adjusted in real-time on the GPU. The value can also be automatically animated.

Please see MIXER CONTRAST command.

Levels

The RGB levels of the content of each layer can be adjusted in real-time on the GPU. The values can also be automatically animated.

Please see MIXER LEVELS command.

Masking

You can mask the alpha channel of each layer by scaling and clipping it, creating a rectangular mask.

The values can also be automatically animated, which can be useful to introduce an animation to a static layer such as an image, or to animate the alpha of a video loop to create an in- and out-animation.

Please see MIXER CLIP command.

Generating Alpha Channel from Other Layer

The alpha channel of each layer is by default generated by each producer, using the embedded alpha channel of the content. You can override this and generate the transparency of a layer by using the alpha channel of another layer. That layer can be of any type, so you could generate the alpha channel from a Flash template, a video file (preferably a video file with an embedded alpha channel) or a bitmap image.

The position and scale values of the layer generating the alpha can also be automatically animated, which can be useful to introduce an animation to a static layer such as an image, or to animate the alpha of a video loop to create an in- and out-animation.

Please see MIXER KEYER command.


Chroma keying

An approximate color (currently green or blue) can be used as transparency of a layer, when the image lacks alpha channel information. This allows for video/still footage taken using a green/blue screen to be keyed above other material.

Please see MIXER CHROMA command.


Audio Adjustments

Audio Volume

The audio volume of each layer played by the FFmpeg Producer (video and audio, but not Flash) can be adjusted in real-time. The value can also be automatically animated.

Please see MIXER VOLUME command.

Master Volume

The audio volume of an entire channel can be adjusted in real-time (scaling the layer volumes accordingly).

Please see MIXER MASTERVOLUME command.


Blend Modes

Every layer in the Mixer module can be set to one of these blend modes. Some common uses are to use screen to make a all the black image data become transparent, or to use add to selectively lighten highlights.

  • Normal (default)
  • Lighten
  • Darken
  • Multiply
  • Average
  • Add
  • Subtract
  • Difference
  • Negation
  • Exclusion
  • Screen
  • Overlay
  • Soft_Light
  • Hard_Light
  • Color_Dodge
  • Color_Burn
  • Linear_Dodge
  • Linear_Burn
  • Linear_Light
  • Vivid_Light
  • Pin_Light
  • Hard_Mix
  • Reflect
  • Glow
  • Phoenix
  • Contrast
  • Saturation
  • Color
  • Luminosity

Animation Types

The following list specifies all supported tweens. You can also see a preview of the animation types.

  • linear (default)
  • easenone
  • easeinquad
  • easeoutquad
  • easeinoutquad
  • easeoutinquad
  • easeincubic
  • easeoutcubic
  • easeinoutcubic
  • easeoutincubic
  • easeinquart
  • easeoutquart
  • easeinoutquart
  • easeoutinquart
  • easeinquint
  • easeoutquint
  • easeinoutquint
  • easeoutinquint
  • easeinsine
  • easeoutsine
  • easeinoutsine
  • easeoutinsine
  • easeinexpo
  • easeoutexpo
  • easeinoutexpo
  • easeoutinexpo
  • easeincirc
  • easeoutcirc
  • easeinoutcirc
  • easeoutincirc
  • easeinelastic
  • easeoutelastic
  • easeinoutelastic
  • easeoutinelastic
  • easeinback
  • easeoutback
  • easeinoutback
  • easeoutintback
  • easeoutbounce
  • easeinbounce
  • easeinoutbounce
  • easeoutinbounce

Consumers (Output Modules)

Image:Consumers.jpg


Consumer is the term used for the output modules that take the rendered media such as video, animations, images and audio that was input in one or several producers and then transformed and composited in the Mixer module module. A consumer adjusts each frame from the Mixer Module for a specified output, for example a window on the computer monitor, an SDI video output or to a file on disk.




Screen Consumer

The Screen Consumer outputs to either a window or fullscreen to one or several computer monitors attached directly to the hardware running the CasparCG Server software.

How to Use

Open the casparcg.config in a text editor and enter the following node for consumers:

 <consumers>
 	<screen/>
 </consumers>

Bluefish Consumer

An SDI card

Outputs the playing media on to video cards from Bluefish Technologies with full SDI support for all SD and HD resolutions, frame rates, pixel aspect ratios, including support for separate fill and key channels + audio.


Multiple Cards

You can install multiple Bluefish cards in a single machine. Each card will be addressed with a unique ID, making it possible have several independent outputs from one server.

Automatic Conversion of Output Levels

To comply with broadcast standards such as CCIR 601 and Rec. 709 the 0-255 RGB levels rendered by the producers is automatically converted to the correct broadcast format (for example a range of 16-235) by the Bluefish Consumer based on the setting in the Bluefish Feature App.

Genlock

Genlock is supported with this consumer.

Audio

Audio can either be played out by the default Windows audio device, or embedded in the SDI output.

DeckLink Consumer

The CasparCG Server's DeckLink Consumer

Outputs the playing media on to DeckLink video cards with full SDI and/or HDMI support for SD and HD resolutions, frame rates, pixel aspect ratios, including support (depending on the card's capabilities) for separate fill and key output and embedded or separate audio.

How to Use

To get video in and key output, open casparcg.config in a text editor and use the following node for consumers:

<consumers>
	<decklink/>
</consumers>

Multiple Cards

Support for multiple DeckLink cards were introduced in CasparCG Server 2.0.

Automatic Conversion of Output Levels

To comply with broadcast standards such as CCIR 601 and Rec. 709 the 0-255 RGB levels rendered by the producers is automatically converted to the correct broadcast format (for example a range of 16-235) by the DeckLink Consumer, based on the card settings.

Genlock

Genlock is supported with this consumer.

Notes

The DeckLink Consumer was added in CasparCG Server version 1.8.

Disk Consumer

CasparCG Server's Disk Consumer

The Disk consumer records a CasparCG Server channel to a local disk. It uses FFmpeg to encode video, so if you are familiar with FFmpeg you will feel somewhat at home with the commands.

The encoding will take advantage of multi-core CPUs.

Time code is currently not supported.

Make sure you have QuickTime installed.

Some formats, such as MXF, can be played back while it is still being recorded.

Changing -r (rate) during recording will not enable slow motion playback, it will just enable transcoding, e.g. 50p to 25p.

To start the disk consumer you need to send the following command:

ADD 1 FILE myfile.mov

...where the file extension will decide the container format and appropriate codec.

To stop the recording you simply type:

REMOVE 1 FILE

The default, and recommended format is a MOV-wrapped H.264 which uses the highly optimized libx264 encoder. You can of course also choose what codec to encode to. The disc consumer tries to mimic the commandline arguments used by FFmpeg, see [1] for more options.

Some of the available options are:

-f // container format
-vcodec // vicdeo codec
-pix_fmt // pixel_format
-r // video framerate
-s // size
-b // video bitrate
-acodec // audio codec
-ar // audio samplerate
-ab // audio bitrate
-ac // audio channels
SEPARATE_KEY // causes a separate file to be recorded with the _A suffix added
             // containing only the alpha channel of the output.

For DNxHD, ProRes, DV and H.264 codecs we have already provided high quality default parameters. Though you can of course also specify other codecs (see the -vcodec option in ffmpeg), and the corresponding options (see the FFmpeg documentation):

ADD 1 FILE myfile.mov -vcodec dnxhd
ADD 1 FILE myfile.mov -vcodec prores
ADD 1 FILE myfile.mov -vcodec dvvideo
ADD 1 FILE myfile.mov -vcodec libx264 [-preset ultrafast -tune fastdecode -crf 5]


Recording Video Codec Examples

To record the input from a DeckLink video input, start playing the DeckLink on the channel, and then ingest the channel:

PLAY 1-1 DECKLINK DEVICE 1
ADD 1 FILE foo.mov

To record the raw video without any compression (around 5 GB/min. of 1080i50 video):

ADD 1 FILE foo.avi -vcodec rawvideo

Recording the video with ffvhuff compression (around 2.5 GB/min. of 1080i50 video.) This video file can be played back by CasparCG Server and VLC while it is still being recorded.

ADD 1 FILE foo.avi -vcodec ffvhuff

Recording two separate files foo.mov and foo_a.mov complementing each other (one contains fill and the other key) frame by frame:

ADD 1 FILE foo.mov SEPARATE_KEY

Triggering

GPI

Support for triggering via GPIO / GPI / GPO is available through the cross-platform CasparCG Client 2.x. It is not built-in to the CasparCG Server.

You will need a physical interface to receive and send the triggers.

We have tested and used two options, Arduino and IoCore.

GPI via IoCore

When using an IoCore, please download the IoCore backup file (IoCore.xml) from our code repository: http://casparcg.svn.sourceforge.net/viewvc/casparcg/tools/cpp/gpio/trunk/

GPI via Arduino

When using the Arduino, you need to use our custom firmware for Arduino from our code repository: http://casparcg.svn.sourceforge.net/viewvc/casparcg/tools/cpp/gpio/trunk/arduino_gpio_controller/

PBus2

Support for PBus2 triggering via a separate middleware client has been tested, but not released to the public.

Diagnostics

See Server Configuration > diagnostics for configuration information.

Note: The middle dashed line indicates "real-time", thus no "time" graphs should exceed that line.

video_channel
mix-time

Time spent mixing the video streams, this include GPU image rendering and CPU audio mixing.

If this graph exceeds the "real-time" graph then the GPU is most likely a bottleneck.

output-time

Time spent sending the frame to the consumers, this time includes both consumer frame processing time and synchronization.

produce-time

Time spent rendering the video-streams, note that asynchronous producers (such as the flash-producers) are not included here.

tick-time

Time spent on one frame. This shows the total time spent on a frame, including processing and synchronization.

This graph should be on the "real-time" line, with minor spikes which are hidden through buffering.

ffmpeg
buffer-count

Number of packets in the file read buffer.

buffer-size

Total size of packets in the file read buffer.

frame-time

Time spent rendering frames.

seek

Displayed when the producer seeks. Usually while looping.

underflow

Displayed when producer does not receive enough data from the file, usually due to disc performance bottlenecks.

Protocols

CasparCG Server makes use of two protocols for communication, the AMCP protocol is used for control and can also respond to query commands to get information about what the server is currently doing. The OSC protocol provides status information about what is happening on particular layers of the CasparCG Server output.

Please see the Communication Protocol page for more information on communicating with CasparCG Server.

License

Image:gplv3-127x51.png The CasparCG Server is licensed under the GNU General Public License version 3.

Credits

People who have contributed significantly to the CasparCG project:

  • Niklas Andersson
  • Jonas Hummelstrand
  • Andreas Jeansson
  • Thomas R. Kaltz III
  • Peter Karlsson
  • Niklas Lundén
  • Robert Nagy
  • Helge Norberg
  • Andy Mace
  • Olle Soprani
  • Jesper Stærkær

Change Log

The most up to date change logs for CasparCG Server can be found on the GitHub repository in CHANGES.txt

CasparCG Server 2.0.3 Stable

2.0.3 was released December 7, 2012

New Features since 2.0.3 Alpha

  • Stage: Fixed dead-lock that can occur with multiple mixer tweens
  • AMCP
    • DATA STORE now supports creating folders of path specified if they does not exist.
    • DATA REMOVE command was added.

CasparCG 2.0.3 Alpha

New Features since 2.0 Stable

  • General
    • Data files are now stored in UTF-8 with BOM. Latin-1 files are still supported for backwards compatibility.
    • Commands written in UTF-8 to log file but only ascii characters to console.
    • Added supported video formats:
      • 720p2398 (not supported by DeckLink cards)
      • 720p2400 (not supported by DeckLink cards)
      • 1080p5994
      • 1080p6000
      • 720p30 (not supported by DeckLink cards)
      • 720p29.976 (not supported by DeckLink cards)
  • CLK
    • CLK protocol implementation can now serve more than one connection at a time safely.
    • Added timeline support to the CLK protocol.
    • Refactored parts of the CLK parser implementation.
  • Consumers
    • Consumers on same channel now invoked asynchronously to allow for proper sync of multiple consumers. This means improved frame-synchronization when using SDI cards that don't have "internal key" functionality, that is; all BMD cards except the "DeckLink HD Extreme 3D" which already does fill+key output in sync.
    • System audio consumer no longer provides sync to caspar
    • Screen Consumer:
      • Support for multiple screen consumers on the same channel
      • No longer spin-waits for vsync
      • Now de-interlaces to two separate frames, e.g. 50i will no longer be converted to 25p but instead to 50p for smooth playback of interlaced content.
      • Decklink consumer now logs whether a reference signal is detected or not.
  • Producers
    • New Image scroll functionality: automatically scroll bitmap images horizontally or vertically (perfect for title scrolls and pre-made tickers!) with additional motion blur parameter.
      • Field-rate motion instead of frame-rate motion with interlaced video formats. This can be overridden by giving the PROGRESSIVE parameter.
      • SPEED parameter now defines pixels per frame/field instead of half pixels per frame. The scrolling direction is also reversed so SPEED 0.5 is the previous equivalent of SPEED -1. Movements are done with subpixel accuracy.
      • Fixed incorrect starting position of image.
      • Rounding error fixes to allow for more exact scrolling.
      • Added support for motion blur via a new BLUR parameter
      • Added PREMULTIPLY parameter to support images stored with straight alpha.

CasparCG Server 2.0 Stable

2.0 was released March 23, 2012.

New Features since 2.0b3

  • Stability and performance fixes.
  • Changed File Consumer semantics to more closely follow FFmpeg (see forums).
  • Added File Consumer options, -r, -acodec, -s, -pix_fmt, -f and more.
  • Added vsync support to Screen Consumer.

Known issues

  • NTSC support not fully tested, please provide feedback on how it works with things like drop-frame, 3:2 pulldown, audio sync etcetera.
  • Swapping clips between channels with different video formats is not supported.
  • De-interlacer does not automatically start for space transforms in the mixer.
  • Flash audio is always output to the default Windows audio-device.

CasparCG Server 2.0b3

2.0b3 was released December 12, 2011.

New Features since 2.0b1

  • The new File Consumer can render videos and graphics to disk, in all the formats that FFmpeg supports. Great for transcoding, or for adding subtitling or logos. Or why not use for an automatic lower-third-generator that spits out animated name signs for your NLE editors?
  • Support for Apple ProRes QuickTime codec, both encoding and decoding.
  • 24-bit audio support for Bluefish cards.
  • Simplified server configuration.
  • Updated audio-pipeline for native NTSC support. Previous implementation did not fully support NTSC audio and could cause incorrect behavior or even crashes.
  • Low latency mode on the DeckLink cards is enabled by default, and graphs can now be displayed for the card’s buffer can be displayed.
  • Improved color accuracy in the DeckLink Producer by avoiding unnecessary conversion to BGRA.
  • Screen Consumer
  • Automatically de-interlaces interlaced input.
  • PAL SD preset has been changed to widescreen.
  • Can now be closed.
  • Interpolation artifacts when running non-square video modes have been addressed.
  • FFmpeg Producer
  • Fixed missing alpha for (RGB)A formats when de-interlacing.
  • Updated buffering to work better with files with long audio/video interleaving.
  • Seekable while running and after reaching EOF. CALL 1-1 SEEK 200.
  • Enable/disable/query looping while running. CALL 1-1 LOOP 1.
  • Fixed bug with duration calculation.
  • Fixed bug with fps calculation.
  • Improved auto-transcode accuracy.
  • Improved seeking accuracy.
  • Fixed bug with looping and LENGTH.
  • Updated to newer FFmpeg version.
  • Fixed incorrect scaling of NTSC DV files.
  • Optimized color conversion when using YADIF de-interlacing filters.
  • Flash Producer
  • Releases the Flash Player when it’s empty.
  • Uses native resolution TemplateHosts.
  • TemplateHosts are now chosen automatically as default. The TemplateHost with the corresponding video mode name is now chosen.
  • Uses square pixel dimensions.
  • The Mixer
  • Bug in alpha with blend modes fixed.
  • Automatic de-interlacing for MIXER FILL commands.
  • AMCP Protocol
  • When possible, commands will no longer wait for rendering pipeline. This reduces command execution latencies, especially when sending a lot of commands in a short timespan.
  • Fixed CINF command.
  • ADD/REMOVE no longer require subindex, e.g. “ADD 1 SCREEN” / “REMOVE 1 SCREEN” instead of “ADD 1-1 SCREEN” / …
  • PARAM is now renamed CALL.
  • STATUS command is replaced by INFO.
  • The INFO command has been extended:
  • INFO (lists channels).
  • INFO 1 (channel info).
  • INFO 1-1 (layer info).
  • INFO 1-1 F (foreground producer info).
  • INFO 1-1 B (background producer info).
  • INFO TEMPLATE mytemplate (template meta-data info, e.g. field names).
  • CG INFO command has been extended.
  • CG 1 INFO (template-host information, e.g. what layers are occupied).
  • Channel: The SET MODE now reverts back to old video-mode on failure.
  • Diagnostics
  • Improved graphs plus more status information added.
  • Now prints configuration into log at startup.
  • Use the same log file for the entire day, instead of one per startup as previously.
  • Diagnostics window is now closable.

Known issues

  • Embedded SDI audio does not work with Bluefish Epoch cards.
  • Key-only output to the File Consumer is not supported.

CasparCG Server 2.0b1

2.0b1 was released September 9, 2011.

New Features since 2.0a1

  • Real-time GPU-accelerated Blending Modes between layers. Supports Add, Overlay, Screen, Multiply and many more.
  • Real-time GPU-accelerated Image adjustments on all playing media (including Flash templates.) Change Brightness, Saturation, Contrast and Levels on the fly!
  • Support for FFmpeg-filters such as yadif de-interlacer (optimized in CasparCG for full multi-core support,) De-noising, Dithering, Box Blur and many more. See http://ffmpeg.org/libavfilter.html for more info.
  • The Decklink Consumer now uses external key by default.
  • The Decklink Consumer now has 32-bit embedded-audio support.
  • The Decklink Producer now has 32-bit embedded-audio support.
  • LOADBG command now has AUTO feature which automatically plays background clip when foreground clip has ended.
  • STATUS command for layers.
  • MIX transition now work with transparent clips.
  • Freeze on last clip frame.
  • Producer and Consumer buffering are now configurable.
  • Now possible to configure Flash template-hosts for different video-modes. Previously they were always hosted in HD.
  • Added auto transcoder which automatically transcodes video into compatible format for the channel.
  • The Screen Consumer now automatically de-interlaces when receiving interlaced content.
  • Added an Image Scroll Producer that will automatically scroll a large bitmap in the specified direction and speed. Great for credit rolls!
  • Reduced memory requirements.
  • Removed 99% of “warm up lag” which occurred when playing the first media clip after the server has started.
  • Memory support increased from standard 2 GB to 4 GB on 64-bit Win 7 OS.
  • Added support for multiple DeckLink cards in FullHD (1080p50).

CasparCG Server 2.0a

  • 2.0a released June 23, 2011.
  • 2.0a Patch 1 released June 24, 2011.

New features since 1.8.0b4

  • Play NTSC, PAL and HD output with progressive, and upper-field and lower-field interlacing to all supported video cards.
  • Use multiple video cards and cards with several outputs, supporting both Bluefish and DeckLink cards.
  • Now works on Windows 7, Windows Vista and Windows XP.
  • Better performance by taking advantage of all your processors (fully multi-threaded,) and moving many operations to the graphics card.
  • Stack multiple videos, Flash graphics and images in any order and output (both fill and key) to one or several video cards and screens. You can even swap the stacking-order in real-time!
  • Generate key (alpha) from separate files (video, Flash and images) with support for non-alpha-capable codecs, such as H.264. You can even generate key (alpha) from different media types, for example using a Flash template to cut out a part of a video file. (GPU accelerated)
  • Play many types of bitmap images with the new Image Producer which replaces the TGA Producer.
  • The new Screen Consumer replaces the Fullscreen Consumer and the GDI Consumer and supports both fullscreen and windowed output at different resolutions. (GPU accelerated)
  • Scale, move, mask and change the opacity and video gain of one or several clips with the new real-time Mixer. Use a number of animation types for professional results. (GPU accelerated)
  • Display all available channels (with content such as videos, images, Flash templates and colors) in a scaled-down grid. (GPU accelerated)
  • Use input video+audio fed into DeckLink video cards just like any other media type.
  • Select a custom loop in-point for video files.
  • Pause both videos and Flash graphics.
  • All video transitions can now be animated with a number of animation types.
  • Fully interlaced video transitions (previously they were only progressive, even when running in interlaced mode.)
  • Audio is now mixed during video transitions.
  • Audio levels can be changed in real-time using gain.
  • Embedded SDI audio support with both Bluefish and DeckLink video cards.
  • Monitor the performance with graphs in the new Diagnostics window.
  • Video, audio and image files can now be placed in sub folders, just like Flash files.
  • Smoother animations and better interlacing in the Flash Producer.
  • Blend modes (Add, Screen, Multiply any many more) between layers. (GPU accelerated)
  • Image adjustments such as Opacity/Transparency, Gain and Levels on playing media. (GPU accelerated)
  • Automatic scaling if the playing media doesn't match the output. (GPU accelerated)
  • No installer required, all configuration is now done in an XML text file instead of in the Windows Registry.
  • Consumers can now be added and removed at run-time, without having to restart the Server.
  • Swap producers between layers and channels during run-time.
  • Asynchronous file I/O with improved buffering.
  • Parallel decoding of audio and video.
  • Real-time commands viewable in the new Console window.
  • Improved logging with full exception details, and a new log file for every server start.
  • Backwards-compatible AMCP protocol supporting all new Server features.
  • Find out the running version of the CasparCG Server and the TemplateHost via a network query.
  • DeckLink output is now using the card's hardware clock.
  • BlueFish drivers are now loaded on-demand, making it possible to have a single Server application.
  • Per-sample mixing between source and destination clips during video transitions.
  • The Flash Producer now uses DirectDraw access, resulting in improved performance.
  • All new GPU-accelerated internal pipeline with the following functions all being done on the GPU:
    • Compositing
    • Color space transforms (rgba, bgra, argb, yuv, yuva, yuv-hd, yuva-hd).
    • Interlacing
    • Per-layer image-transforms: opacity, gain, scaling, clipping, transform
    • The Color Producer
  • Major code refactoring for improved readability and maintainability. 66% of legacy code removed.
  • Rewritten to take advantage of common standardized libraries instead of custom solutions.
  • Work done to facilitate cross-platform porting (the greatest challenge for full platform-independence being the Flash Producer.)
  • Video, audio and image files can now be placed in sub folders, just like Flash templates.
  • Smoother animations and better interlacing in the Flash Producer.
  • Outputs (Consumers) can now be added and removed at run-time, without having to restart the server.
  • Swap producers between layers and channels during run-time.
  • Parallel decoding of audio and video.
  • Real-time commands viewable in the new Console window.
  • Improved logging with full exception details, and a new log file for every server start.
  • Backwards-compatible AMCP protocol supporting all new server features.
  • Find out the running version of the CasparCG Server and the TemplateHost via a network query.
  • DeckLink output is now using the card’s hardware clock.
  • Bluefish drivers are now loaded on-demand, making it possible to have a single Server application.
  • Per-sample mixing between source and destination clips during video transitions.
  • The Flash Producer now uses DirectDraw access, resulting in improved performance.
  • All new GPU-accelerated internal pipeline with the following functions all being done on the GPU: Compositing, Color space transforms (RGBA, BGRA, ARGB, YUV, YUVA, YUV-HD, YUVA-HD), Interlacing, Per-layer image-transforms: opacity, gain, scaling, clipping, transform, plus the Color Producer.
  • Work done to facilitate cross-platform porting.
  • Real-time GPU-accelerated Blending Modes between layers. Supports Add, Screen, Multiply and many more.
  • Added an Image Scroll Producer that will automatically scroll a large bitmap in the specified direction and speed. Great for credit rolls!
  • Support for FFmpeg-filters such as yadif de-interlacer (optimized in CasparCG for full multi-core support,) Denoising, Dithering, Box Blur and many more.
  • Parallel decoding of audio and video.
  • Auto transcoder which automatically transcodes video and audio into compatible format for the channel.
  • The Screen Consumer now automatically de-interlaces when receiving interlaced content.
  • Per-sample mixing between source and destination clips during video transitions.
  • The Flash Producer now uses DirectDraw access, resulting in improved performance.
  • Video, audio and image files can now be placed in sub folders, just like Flash templates.
  • Smoother animations and better interlacing in the Flash Producer.
  • Outputs (Consumers) can now be added and removed at run-time, without having to restart the server.
  • Swap producers between layers and channels during run-time.
  • Real-time GPU-accelerated Image adjustments on all playing media (including Flash templates.) Change Brightness, Saturation, Contrast and Levels on the fly!
  • DeckLink output is now using the card’s hardware clock.
  • Bluefish drivers are now loaded on-demand, making it possible to have a single Server application.
  • The Decklink Consumer now uses external key by default and has 32-bit embedded-audio support.
  • The Decklink Producer now has 32-bit embedded-audio support.
  • MIX transition now work with transparent clips.
  • Freeze on last frame of video clips enabled by default.
  • Producers’ and Consumers’ buffering are now configurable.
  • Flash template-hosts configurable for different video-modes. Previously they were always hosted in HD.
  • Reduced memory requirements.
  • Removed 99% of “warm up lag” which occurred when playing the first media clip after the server has started.
  • Memory support increased from standard 2 GB to 4 GB on 64-bit Win 7 OS.
  • Real-time commands viewable in the new Console window.
  • Improved logging with full exception details, and a new log file for every server start.
  • Backwards-compatible AMCP protocol supporting all new server features.
  • Find out the running version of the CasparCG Server and the TemplateHost via a network query.
  • Major code refactoring for improved readability and maintainability. 66% of legacy code removed.
  • Rewritten to take advantage of common standardized libraries instead of custom solutions.

CasparCG Server 1.8.0b4

New Features

  • Support for DeckLink SDI and HDMI cards.
  • The Fullscreen Consumer now uses OpenGL 2.0 and can play and scale output from both the Flash Producer and the FFmpeg Producer (or a composite of both) to a computer monitor.

Fixed Issues

  • Many bug fixes.

Known Problems

  • No support for NTSC resolutions or frame rates.
  • Interlaced output from the Flash Producer cannot currently be set to lower/even field order.
  • All video files with DV codecs are automatically shifted 1 pixel up by the automatic field dominance switcher function. This results in interlaced DV videos being played as if they had upper/odd field dominance. Progressive clips are only affected by the pixel shift but are otherwise played correctly.
  • The field dominance cannot be set on a per-clip basis, resulting in problems where interlaced video files with lower/odd field dominance that aren't using a DV codec is played incorrectly.
  • Genlock/synchronization with DeckLink cards is still untested.
  • Only PAL SD resolutions supported on DeckLink cards.
  • Only one DeckLink card per machine supported.
  • When using the real-time scaling via the FFmpeg Producer, the key signal is never scaled along with the fill, resulting in an all-white key signal.
Personal tools