Graphics SDK

Beta

The Graphics SDK, the ligr-graphic CLI and the theme and code graphics REST routes are in beta. You create the theme your graphics live in, up to five per organization. The protocol, the manifest and the REST shapes can change between minor versions. Report code graphics, SDK, and CLI bugs, concerns, or feature requests through GitHub Issues. For app, account, or page problems, use LIGR support. See Issues and support for the scope of each channel.

A code graphic is a graphic you write yourself in HTML, CSS and JavaScript. The LIGR overlay loads it in a transparent frame over the video, sends it live match data, and tells it when to show and when to hide. It runs beside the Rive graphics in the same theme, and operators drive it from the same control room.

For native .riv, .rev, or RML project imports, use Rive graphics. Native Rive playback does not use this browser SDK or the ligr.gfx.v1 protocol.

LIGR supplies the match data. You build a static browser bundle, push it over REST, and publish it. The platform does not require a framework or the SDK. Plain HTML, Canvas, WebGL and browser libraries use the same protocol.

Downloads and repository

The public graphics repository hosts SDK and CLI releases and scoped GitHub Issues. It is a distribution repository. The implementation source remains in a private repository. Download versioned package archives from Releases without a GitHub or npm account. Use Issues and support to choose where to report a problem or request a feature.

How it fits together

1. You write the graphic and keep a manifest next to it. See The manifest.
2. Your graphic answers the overlay over postMessage with the ligr.gfx.v1 protocol. The overlay sends match data, control variable values, theme variables and external data. See Data binding.
3. You create a theme, create the graphic in it, upload the files, and record the bundle. See Push and publish.
4. You publish a graphic version, then a theme version that holds it. Overlays render the active theme version.

Operators show and hide a code graphic the same way as any other graphic. Automation and the graphics commands endpoint drive it by its control variables. You write none of that. You only build the bundle.

The runtime

The overlay is a GPU-accelerated Chromium browser. On a LIGR stream, LIGR runs that browser on the encoder and composites its output over the video. On a vision mixer, the browser source of the mixer renders the same page. Your graphic runs in an iframe inside that page. The iframe has the width and height of your manifest. The overlay scales the iframe to fit the output and keeps its aspect ratio. A 1920 x 1080 graphic fills a 16:9 output at any resolution.

Everything the browser offers is available to your code:

• WebGL 1 and 2, WebGPU, and Canvas 2D for GPU-driven rendering.
• CSS animations and transforms, and the Web Animations API.
• WebAssembly and Web Workers.
• Any rendering library that runs in a browser: Three.js, PixiJS, Rive, Lottie, GSAP.

The overlay renders at the frame rate of the stream. Keep every frame under 16 ms at 60 fps. A graphic that stalls the page stalls every other graphic on the overlay.

A vision mixer browser source runs on the browser of that mixer. Check its Chromium version before you rely on WebGPU there.

Pages

Page	What it covers
Quick start	From an empty folder to a graphic on an overlay
The ligr.gfx.v1 protocol	Every message the overlay sends and accepts
The manifest	The runtime, the control variables and the validation rules
Data binding	Match, control variable, theme, image and data source values inside a graphic
Expressions	The expression language, the $d, $v, $t, $u and $x context, and the helpers
Bundle rules	Files, paths, fonts, size limits and the file name rules
Push and publish	Create, upload, record, publish, and the theme version
Test and troubleshoot	ligr-graphic dev, the local harness, the checklist before hand-over, and the symptoms table
Issues and support	Code graphics feedback, bug reports, feature requests, and general app support

Beta status

Graphics creation is in beta. This is what beta means today:

• You create the theme with npx ligr-graphic theme create or POST /v2/themes. Once activated, it appears on the Themes page of the dashboard and in the competition theme picker like any other theme. Your organization can own up to five themes. A plan-level cap and pricing are on the roadmap.
• The dashboard cannot create, edit or activate an owned theme yet. Use the CLI or REST for theme versions, and the dashboard to assign it to a competition and to operate it.
• The ligr.gfx.v1 protocol, the manifest and the theme and code graphics REST routes can change between minor versions. The changelog lists every change.
• Every response from a beta route carries X-Ligr-Beta: true, and the operation carries x-beta: "true" in the OpenAPI document. See Beta endpoints.
• The @ligrsystems/graphics-sdk and @ligrsystems/graphics-cli packages ship as 0.x versions.
• Test every graphic on the preview overlay of a test match before you use it on air.

What you need

• A theme your organization owns. Create it with npx ligr-graphic theme create.
• A write API key. See Authentication.
• Node 22 or later and a browser.
• Optionally, @ligrsystems/graphics-sdk: a browser implementation of ligr.gfx.v1 with callbacks for data and visibility.
• The @ligrsystems/graphics-cli package: the ligr-graphic command that scaffolds, runs, validates, pushes and publishes a graphic.

Install

Scaffold a graphic with the CLI. The scaffold adds both packages with exact GitHub release URLs to its package.json. Public package downloads need no npm account or GitHub authentication. Keep your lockfile in Git.

Terminal

npx --package=https://github.com/ligrsystems/graphics-packages/releases/download/v0.3.0/ligrsystems-graphics-cli-0.3.0.tgz ligr-graphic init my-graphic
cd my-graphic
npm install
npm run build
npm run dev

The default scaffold uses plain HTML, CSS and JavaScript. Framework templates are optional examples, not platform requirements. To add the optional runtime to an existing project, install the package and call createGraphic.

Terminal

npm install https://github.com/ligrsystems/graphics-packages/releases/download/v0.3.0/ligrsystems-graphics-sdk-0.3.0.tgz
npm install --save-dev https://github.com/ligrsystems/graphics-packages/releases/download/v0.3.0/ligrsystems-graphics-cli-0.3.0.tgz

Size limits

Limit	Value
One bundle	10 MiB
One file	5 MiB
One protocol message	1 MB

A bundle over the limit is refused with BUNDLE_TOO_LARGE. The details[] array names the files. See Errors for CODE_GRAPHIC_INVALID, BUNDLE_TOO_LARGE and INVALID_ASSET_PATH.

Note

hide is a reserved control variable. LIGR adds it to every code graphic and sets it when the overlay shows or hides your graphic. Never declare it in your manifest.

The SDK function createGraphic() starts a code-graphic runtime listener. It does not create a stored Rive graphic through REST.