DOCSEARCHbyAlgolia
Submit Docs

SPX Graphics Controller

repository·master·Indexed 19 days ago

https://github.com/tuomoku/spx-gc

A web-technology-based application for managing real-time HTML graphics in live production environments such as streaming, TV broadcast, and live events. Version 1.4.1 supports EBU OGraf file formats, layered outputs, and integration with video pipelines like OBS, vMix, and CasparCG. It features a hierarchical project and rundown structure, a plugin system for custom workflows, and Handlebars-based templating.

Tokens
3.4K
Snippets
6
Records
15
Agent score
65%

What's inside spx-gc

  1. Overview of SPX Graphics Controller

    master

    SPX Graphics Controller is an application designed to manage and play back real-time HTML graphics (such as lower thirds, titles, logos, and news tickers) for live productions. It runs locally or in the cloud and integrates with video pipelines that support HTML sources, including OBS, vMix, CasparCG, and many others.

    Key characteristics:

    • On-Premise: Can run without an internet connection.
    • File System Based: Uses a simple and robust architecture for data storage.
    • OGraf Compliant: Supports the EBU OGraf file format.
    • Extensible: Supports custom workflows via plugins and APIs.
    • Layered Outputs: Supports multiple layers of real-time graphics targeting different outputs.

  2. Plugin naming conventions in SPX-GC

    master

    When creating plugins in /ASSETS/plugins, follow these naming rules:

    • Plugin Name: The name of the plugin is derived directly from the folder name (e.g., a folder named spxSocial results in a plugin named spxSocial).
    • Exclusion Rule: Any folder name starting with an underscore (_) will be ignored by the loader (e.g., _spxSocialOldVersion will not be loaded).

  3. Understand SPX Project and Rundown Structure

    master

    SPX organizes content using a hierarchical structure stored in a dataroot folder:

    1. Projects: The top-level container for content.
    2. Rundowns: Each project can contain an unlimited number of rundowns (sequences of graphics items).
    3. Graphics Templates: Each project can contain multiple templates used to generate graphics.

    Settings and data for projects, rundowns, and templates are all managed within the dataroot directory.

  4. Compare SPX Open Source and Commercial Versions

    master

    SPX is available in several versions depending on your production needs:

    Open Source Version

    • Usage: You can clone the repository and use it freely.
    • Limitations: Does not contain all features or API functionalities found in commercial versions, but it has no watermarks or other usage limitations.
    • Installation: Refer to the official installation instructions.

    Commercial Versions

    • SPX Solo: A compiled, easy-to-install version for Windows, Mac, and Linux. Includes example graphics, plugins, and a launcher.
    • SPX Production: Targeted at professional live projects (events, sports, OB-productions) with advanced playout features.
    • SPX Broadcast: Targeted at TV broadcasters, featuring automation for 24/7 playout and integrations like MOS, NLE, and NRCS plugins.

  5. Create and structure an SPX-GC plugin

    master

    Starting from version 1.0.10, you can create plugins by adding subfolders to the /ASSETS/plugins directory. Each subfolder is treated as an individual plugin and is injected into the client side using <script> tags.

    Requirements

    To be recognized as a valid plugin, a folder must contain:

    1. init.js: The entry point for the plugin (refer to existing files in the repository for implementation patterns).
    2. A files/ subfolder: This directory must house the plugin's assets, including .html, .js, and .css files.
    /* Required folder structure */
/ASSETS/plugins/
└── <plugin-name>/
    ├── init.js
    └── files/
        ├── plugin.js
        ├── plugin.css
        └── plugin.html

  6. Generate template-specific CSV files

    master
    To generate template-specific example.csv files, click the CSV export button within a template in the SPX interface. The system will automatically populate the ASSETS/csv/ folder with these files, which serve as templates for your data exports.

  7. SPX Socket.io Communication Protocol

    master

    The SPX server uses Socket.io for real-time communication between the server, controllers, and renderers.

    Client to Server Messages (SPXMessage2Server)

    Clients can send messages to the server using the SPXMessage2Server event. The data.spxcmd field determines the action:

    • identifyClient: Sets the client's name (data.name).
    • saveToLog: Sends a log message to the server (data.level, data.fileref, data.message).
    • command-name-here: Placeholder for custom commands.

    Server to Client Messages

    • SPXMessage2Client: The server broadcasts messages to all clients. This is used for commands like clientLostNotification (sent when a client disconnects) and notifyMultipleControllers (sent when the number of connected controllers changes).
    • SPXWebRendererMessage: A specific event used by Web Renderers to relay messages to the server.

  8. Run the SPX Graphics Controller server

    master

    The SPX Graphics Controller is a professional live graphics solution. You can start the server using Node.js. You can optionally provide a specific configuration file as an argument.

    Basic usage:

    node server.js [config.json]
    node server.js [config.json]

  9. Configure SPX GC with PM2 using ecosystem.config.js

    master

    The project can be managed using PM2 with an ecosystem.config.js file. This allows you to define multiple instances (apps) of the Graphics Controller, each running a specific script with its own configuration file passed as an argument.

    Each application object in the apps array requires:

    • name: A unique identifier for the instance (e.g., 'GC1').
    • script: The entry point file for the controller (e.g., 'server.js').
    • args: The path to the specific JSON configuration file for that instance (e.g., 'config.json').
    module.exports = {
  apps : [
    {
    'name': 'GC1',
    'script': 'server.js',
    'args': 'config.json'
    },
    {
      'name': 'GC2',
      'script': 'server.js',
      'args': 'config2.json'
      }
  ]
};

  11. Handlebars helpers in SPX templates

    master

    The SPX server uses Handlebars for templating and provides several custom helpers to assist with UI generation and data manipulation within templates:

    • max5(data): Returns the data as a string, capped at a maximum value of 5.
    • DataToJSONString(data): Converts JSON data into an encoded JSON string (useful for storing arrays in hidden form fields).
    • ifValue(a, b, options): A conditional helper that executes the block if String(a) === String(b).
    • ifValueMatch(value, compareTo, A, B): Returns value A if value == compareTo, otherwise returns B.
    • itemCount(arr): Returns the length of an array.
    • ifGreater(a, b, options): Executes the block if a > b.
    • generateDataFormatOptions(currentDataformat): Generates HTML <option> elements for data format selection (json or xml).
    • generateCasparCgPlayoutOptions(currentServer): Generates HTML <option> elements for CasparCG server selection based on the configuration.
    • GenerateOpenFolderCommands(): Generates HTML anchor tags for opening data or template folders (currently only supported on Windows).
    • GenerateCustomControls(arr): Generates an HTML table of custom UI controls (buttons, togglebuttons, or selectbuttons) based on an array of control objects.
    • GeneratePlayoutInfo(...): Generates a formatted HTML string displaying playout configurations (CasparCG, WebPlayout, etc.).
    • generateFileList(requestType): Generates an HTML list of templates or files (e.g., for CSV selection).
    • generateTemplateList(currentShow): Generates an HTML list of available templates for a specific show.
    • generateTimestamp(epoch): Converts an epoch timestamp into a locale date/time string (e.g., "31.12.2021 17:45").
    • generateButtonColorClasses(currentValue): Generates HTML <option> elements for color accent selection.
    • generateOutOptions(currentOut): Generates HTML <option> elements for output timing options (e.g., manual, none, 1000, 2000, etc.).
    • generateWebPlayoutOptions(currentLayer): Generates HTML <option> elements for WebPlayout layer selection.
    • generateResolutionOptions(resolutionOption): Generates HTML <option> elements for resolution selection (HD, 4K, AUTO).
    • localPreviewSize(cssSizeValue): Returns '1920' if the input contains 'vw', '1080' if it contains 'vh', otherwise returns the input.
    • getHostID(): Returns the unique hardware ID (global.pmac).
    • hookLoadControllerPlugins(): Generates <script> tags to load plugin init.js files from the ASSETS/plugins directory.
    • injectNewlines(jsonString): Replaces \n with `

    ` for textarea compatibility.

    • lang(str): Wrapper for the spx.lang translation helper.
    • prettyfyBreadcrumb(str): Replaces underscores and hyphens with spaces.
    • myStringify(obj): Returns a formatted, pretty-printed JSON string.
    • nameFromTemplatePath(filepath): Returns the prettified name of a template from its file path.
    • allowOpeningFolder(): Returns the string 'disabled' if the configuration forbids opening folders, otherwise returns an empty string.
    • shortifyUIstrings(str): Wrapper for spx.shortifyName.
    • OpenChromeCheck(): Returns an HTML checkbox input for the launchBrowser configuration.
    • playButtonClass(onair): Returns CSS class bg_red if onair is true, otherwise bg_green.
    • playButtonText(onair): Returns the localized string for 'stop' if onair is true, otherwise 'play'.
    • playIconClass(onair): Returns CSS class playTrue if onair is true, otherwise playFalse.
    • ShowDemoLoginInfo(): Generates an HTML table displaying demo login credentials from the configuration.
    • ShowVersion(): Returns the current application version.
    • DropdownOptionsLANG(): Generates HTML <option> elements for the language selection dropdown.
    • PopulateFilelistOptions(...): Generates HTML <option> elements for file selection within a specific asset folder.
    • ServerStatus(): Generates HTML dropdowns showing the status and connection options for configured CasparCG servers.
    • DetectCustomContentPackages(): Checks for the existence of spx-content-repo.txt in the assets folder and returns an indicator div if content is specified.

  12. Create a standard button with button()

    master

    The button(options) function creates a standard SPX button component wrapped in a flexbox container. It includes a description label on the left and a styled button on the right. You can customize the button's text, color, and provide a tooltip that appears on hover.

    Options:

    • description (string): The text displayed on the left side of the button.
    • caption (string): The text displayed on the button itself. Defaults to 'Click' if not provided.
    • color (string): The color theme for the button. Valid values are: red, blue, green, grey, gray, black, white, orange, yellow.
    • overToolTip (string): The text displayed in a tooltip when the user hovers over the component.
    import * as UI from "../spxgc_lib/ui.js";

const myButton = UI.button({
  description: 'Execute Task',
  caption: 'Run',
  color: 'green',
  overToolTip: 'This will start the process'
});

document.body.appendChild(myButton);