Skip to content

Graphics SDK

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.

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. The CLI is also on npm as @ligr/cli. Use Issues and support to choose where to report a problem or request a feature.

  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. LIGR supplies those controls.

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.

Your code can use these browser features:

  • 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 that you create from a blob: URL.
  • Rendering libraries that run in a browser, for example Three.js, PixiJS, Rive, Lottie and GSAP.

The frame allows scripts only. localStorage, IndexedDB and document.cookie throw a SecurityError, and the browser refuses a worker script that loads from a bundle file. A library that needs one of these features does not work in the frame.

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.

PageWhat it covers
Quick startFrom an empty folder to a graphic on an overlay
The ligr.gfx.v1 protocolEvery message the overlay sends and accepts
The manifestThe runtime, the control variables and the validation rules
Data bindingMatch, control variable, theme, image and data source values inside a graphic
ExpressionsThe expression language, the $d, $v, $t, $u and $x context, and the helpers
Bundle rulesFiles, paths, fonts, size limits and the file name rules
Push and publishCreate, upload, record, publish, and the theme version
Test and troubleshootThe dashboard code viewer, the overlay preview, the checklist before hand-over, and the symptoms table
Issues and supportCode graphics feedback, bug reports, feature requests, and general app support

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

  • You create the theme with npx @ligr/cli graphic theme create or POST /v2/themes. It appears on the Themes page of the dashboard and in the competition theme picker as soon as you create it. Your organization can own up to five themes.
  • The dashboard cannot create a theme today. An owner or admin of your organization can edit an owned theme, publish a theme version and activate a version in the dashboard: Themes → Library → Edit. The CLI and REST do the same. Use the dashboard to assign the theme 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 theme or code graphics 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 @ligr/cli packages ship as 0.x versions.
  • Test every graphic on the preview overlay of a test match before you use it on air.
  • A theme your organization owns. Create it with npx @ligr/cli graphic theme create.
  • An API key with the themes:write scope. 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 @ligr/cli package: the ligr command. Its ligr graphic commands scaffold, validate, push and publish a graphic.

Scaffold a graphic with the CLI. npx @ligr/cli runs the CLI without an install. The scaffold adds both packages with exact GitHub release URLs to its package.json. Keep your lockfile in Git. The npm package and the release archives are public. Downloads need no npm account or GitHub authentication.

Terminal
npx @ligr/cli graphic init my-graphic
cd my-graphic
npm install
npm run build

To install the ligr command, run npm i -g @ligr/cli. ligr-graphic is the old name. npx ligr-graphic <command> still runs ligr graphic <command> and prints a deprecation notice. Replace ligr-graphic <command> with ligr graphic <command>.

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.6.2/ligrsystems-graphics-sdk-0.6.2.tgz
npm i -D @ligr/cli
LimitValue
One bundle10 MiB
One file5 MiB
One protocol message1 MB

A bundle over the limit is refused with BUNDLE_TOO_LARGE. The details[] array names each file over 5 MiB, and the bundle total when it is over 10 MiB. See Errors for CODE_GRAPHIC_INVALID, BUNDLE_TOO_LARGE and BAD_USER_INPUT.

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