Background

SPX Graphics Controller (SPX-GC for short) is an open-source graphics controller application for professional production teams working in live video productions for broadcast TV, streaming, or live events.

SPX Graphics' workflows revolve around the concept of reusable HTML graphics called "templates". A graphics operator uses SPX applications to load, manage, and play out graphics during live production. Similar systems in the industry are typically called "Character Generators" or "CGs" for short.

SPX Graphics is an ecosystem for HTML graphics and it all started with the release of the SPX-GC application in September 2020. After the release, Softpix Ltd was founded to develop and maintain the project.

At the time of this writing, there are tens of thousands of users of SPX around the world, businesses and organizations of all sizes are developing and using HTML graphics and have integrated it into a wide range of workflows and systems while enjoying the benefits of the open HTML based approach compared to closed, proprietary offerings still dominating the field of realtime graphics.

Purpose of this specification

This specification aims to help graphics developers in the adoption and integration of common graphics specifications into their work. It may be developing new software for creating graphics, managing assets, or playing out graphics.

We welcome any project that aims to utilize HTML-based graphics workflows to join the SPX movement, helping to grow and unify the HTML graphics workflows and practices. In the long run, a wide adoption of commonly used specifications will make development projects faster, systems integration easier, graphics design projects smoother and overall experience better, while offering growing business opportunities to everybody involved.

Template files

HTML template files (the graphics) can be created in any way and they follow a very typical html/CSS/JavaScript structure found in websites. One can consider each SPX graphics template to be "a mini website".

Image 1

<html>
    <head>
        <link rel="stylesheet" href="styles.css">
        <script src="js/spx_interface.js"></script>
        <script>
            window.SPXGCTemplateDefinition = {
                "description": "A minimal template",
                "webplayout": "10",
                "DataFields": [
                    {
                        "field" : "f0",
                        "ftype" : "textfield",
                        "title" : "A textline",
                        "value" : "Hello World"
                    },
                ]
            };
        </script>
    </head>
    <body>
        <div id="f0">DEFAULT TEXT</div>
    </body>
</html>

Code snippet: A minimal HTML template with a template definition

Each template has a JavaScript-based logic for controlling the playout of visual elements within the template. This follows CasparCG logic flow closely and because of that the templates must implement play(), stop(), update(), and next() -functions.

SPX templates most often have an external script library that implements these functions and they call helper functions runTemplateUpdate(), runAnimationIN() and runAnimationOUT() within the template, for easier implementation of template-specific functionality and animations.

Structure of the Template Definition

This specification is for VERSION 1 of the SPXGCTemplateDefinition.

Template definition is a JavaScript object variable within the HTML source code of the template and is bound to the window -object. See the below minimal example code snippet:

            window.SPXGCTemplateDefinition = {
                "description": "A minimal template",
                "webplayout": "10",
                "DataFields": [
                    {
                        "field" : "f0",
                        "ftype" : "textfield",
                        "title" : "A textline",
                        "value" : "Hello World"
                    },
                ]
            };

Conventions

Fields	The dynamically modifiable content of a template can be considered to consist of controls or fields. Each property has a field with a unique ID. By convention, these fields are given IDs incrementally, such as "f1", "f2", "f3", etc, but there is no technical reason or limitation in using any arbitrary alphanumeric ID to identify them.
F-Types	Each field is implemented using one of several alternatives, such as a text field, number, or a button. See section Reference for a list of f-types.

Reference

Metadata

F-type	Description	Example
`description`	Shown in the GUI to describe the template for the graphics operator.	`Lower third, left side`
`out`	How the graphics will behave after the IN-animation is completed. `none` for elements that automatically clears the screen once played. Works with numbers etc. `manual` The most typical option. Once played it stays on-screen and will need to be manually stopped. `< numeric >` After the numeric (millisecond) value the system stops the template. An automatic mode.	`manual`
`steps`	How many phases are there in the animation? For normal in-out templates, this is 1. For templates with 2 or more steps, the Continue button is activated.	`1`
`dataformat`	Relates to CasparCG workflow; some templates expect data in `json` or `xml` format. JSON is the default one.	`json`

Playout software may introduce additional properties for assigning servers, channels and layers.

Template field types

F-type	Description	Example
`hidden`	A variable that is not editable by the user. Value is used by the template and, title can be shown as static text in the GUI.	`Red color (#f00)`
`caption`	The value is shown in UI. Caption can be used to display texts to operators of the template.	`This template does not have editable values`
`textfield`	A typical single-line text input field.	`Firstname Lastname`
`dropdown`	A dropdown selector list. Options is an items array, each consisting of text (visible in the GUI) and the value. The default selection is defined as `value` and it must be one of the values in the items array. See the examples.	`"items":[ {"text": "Hundred", "value": 100}, {"text": "Dozen", "value": 12} ]`
`textarea`	A multiline text control that accepts return key for new lines.	`First line \n Second line`
`filelist`	A dropdown selector list for files of of given type extension in a configured folder-structure. If `assetfolder` path value starts with `"./"` the path is considered relative to the template root folder. This is useful for optional CSS styles or alternative images. See examples of both path styles.	`sport_logo.png, news_logo.png`
`divider`	A utility ftype to add a visual divider to a template. Can be used to create visual segments for ease of use.
`instruction`	Value can be used as a longer help text on the template but does not have any other functionality.	`Max 100 characters to the field below.`
`number`	Value is exposed as a number field in the template GUI.	`45`
`checkbox`	`Title` is used as a label in UI. Value is "0" or "1" when checked.	`[x] Show logo`
`color`	`Title` is used as a label in the GUI. Value is a valid CSS color string such as `rgb(255,0,0)` (full red) or `rgba(0,0,0,0.33)` (black with 33% opacity).	`rgba(255,255,255,1.0)`
`spacer`	Just an empty line to separate out sections. This can be used in very complex templates to visually separate control groups.	`(no parameters)`
`button`	A button that will execute a function in the system. `Title` used as a label and the `descr` property is for a description in the GUI for the graphics operator.

Examples

Future of the specification

Hello world! - Your first template

CasparCG Control Template

SPX renderer

SPX Configuration, general

SPX-GC Template Definition v1