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.
Downloads and repository
Section titled “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.
The CLI is also on npm as @ligr/cli.
Use Issues and support to choose where to report a problem or request a feature.
How it fits together
Section titled “How it fits together”- You write the graphic and keep a manifest next to it. See The manifest.
- Your graphic answers the overlay over
postMessagewith theligr.gfx.v1protocol. The overlay sends match data, control variable values, theme variables and external data. See Data binding. - You create a theme, create the graphic in it, upload the files, and record the bundle. See Push and publish.
- 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 runtime
Section titled “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.
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.
| 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 | The dashboard code viewer, the overlay preview, 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
Section titled “Beta status”Graphics creation is in beta. This is what beta means today:
- You create the theme with
npx @ligr/cli graphic theme createorPOST /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.v1protocol, 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 carriesx-beta: "true"in the OpenAPI document. See Beta endpoints. - The
@ligrsystems/graphics-sdkand@ligr/clipackages ship as0.xversions. - Test every graphic on the preview overlay of a test match before you use it on air.
What you need
Section titled “What you need”- A theme your organization owns. Create it with
npx @ligr/cli graphic theme create. - An API key with the
themes:writescope. See Authentication. - Node 22 or later and a browser.
- Optionally,
@ligrsystems/graphics-sdk: a browser implementation ofligr.gfx.v1with callbacks for data and visibility. - The
@ligr/clipackage: theligrcommand. Itsligr graphiccommands scaffold, validate, push and publish a graphic.
Install
Section titled “Install”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.
npx @ligr/cli graphic init my-graphiccd my-graphicnpm installnpm run buildTo 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.
npm install https://github.com/ligrsystems/graphics-packages/releases/download/v0.6.2/ligrsystems-graphics-sdk-0.6.2.tgznpm i -D @ligr/cliSize limits
Section titled “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 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.