CasparCG HTML Producer Basics

I recently started working with my school system to deploy a standardized broadcast studio at several locations. Part of any broadcast studio is a playout system (to play recorded videos, intros, outros, etc), and a character generator to create text titles/animations. Sometimes these are two separate things, sometimes they're combined, but they're almost always very expensive, and price is a problem for schools.

Enter CasparCG, the open-source broadcast video playout server originally written as in-house software for Sweden's SVT TV Network. It supports playout and character generation, and it handles realtime text templates with Adobe Flash. This is fine as long as you are familiar with Flash, but Flash is highly proprietary and often not the best solution.

Luckily, CasparCG's developers recently introduced a new templating engine that uses HTML/CSS/JS. It's powerful, but poorly documented, and it took me an hour or so to reverse engineer other peoples' templates to figure out how it works. To save you the trouble, I've documented what I found below.

Functions

CasparCG requires a few global functions in every HTML template. These correspond to commands in CasparCG's well-known AMCP protocol. Even if they're empty, you must define these, or you'll get an error.

play()

This is pretty self-explanatory; this function should start "playing" whatever your animation is. It takes no arguments, and is called after update(String).

stop()

This function should immediately stop your animation. CasparCG will call this function and instantly stop showing your template.

next()

This should gracefully stop your animation. For example, if you had a looping graphic, calling next() should finish the current loop, then gracefully stop it. The idea is that you can stop the template without an abrupt, unprofessional cut.

update(String)

This function is called before anything else. It takes one argument: a string of data. By default, the data is XML, but if you check "Send as JSON" in CasparCG client, you'll have a much easier time parsing it in JavaScript. This XML/JSON will contain any key/value pairs you've configured in the template data. For example, if I configured the template like this in CasparCG client:

template data.png

Since "Send as JSON" is enabled, CasparCG will call update("{"f0":"Here come dat HTML template"}"). Note that it is not parsed JSON; the argument is a string that must be parsed with JSON.parse() before it's usable.


I plan to make a longer guide later on, but I wanted to "fill in the holes" in existing documentation just to get people started. If you know how to animate webpages and you know basic JavaScript, you should be able to use this guide as a reference to start building your own HTML templates.