Service: SPX Graphics Controller - EyevinnOSC/community GitHub Wiki
SPX Graphics Controller (serviceId tuomoku-spx-gc, SPX-GC) is an open source (MIT) live production graphics system for broadcast and streaming. It lets you create, manage and control HTML-based on-screen graphics (lower thirds, fullscreen overlays, countdown timers, tickers and more) from a web browser without specialist hardware. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance with up to 10 GiB of storage per instance. Source: TuomoKu/SPX-GC.
- Manage HTML graphics in projects and rundowns (playlists) and play them out in sequence or on demand.
- Design and test HTML graphics templates.
- Render graphics as a transparent overlay in OBS, vMix and similar tools.
- Store templates, projects, media, plugins and JSON data in S3-compatible storage such as MinIO.
- Protect the controller with a username and password.
No other service is required. To keep templates, projects and media in cloud storage, create a MinIO instance (serviceId minio-minio) first and confirm it is running.
Store the password as a service secret with create-service-secret on serviceId tuomoku-spx-gc, then call create-service-instance with serviceId: "tuomoku-spx-gc":
{
"name": "mygraphics",
"Username": "admin",
"Password": "{{secrets.spxpassword}}"
}With S3 storage, add for example:
{
"S3EndpointUrl": "http://<minio-endpoint>",
"S3AccessKeyId": "{{secrets.s3key}}",
"S3SecretAccessKey": "{{secrets.s3secret}}",
"S3TemplatesUrl": "s3://<bucket>/templates",
"S3ProjectsUrl": "s3://<bucket>/projects",
"S3MediaUrl": "s3://<bucket>/media"
}Wait for the instance to be running (wait-for-service-ready) and use describe-service-instance to get the URL. If you set neither username nor password, SPX-GC opens without a login prompt. If you set a username but leave the password blank, the application asks you to configure a login policy on first launch.
CLI equivalent:
osc create tuomoku-spx-gc mygraphics \
-o Username="admin" \
-o Password="{{secrets.spxpassword}}"| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Alphanumeric, at most 20 characters. |
| Username | No | string | Username for SPX authentication. With a password, users must log in to access the application. |
| Password | No | string, sensitive | Password for SPX authentication, used with Username. Stored encrypted in SPX's config.json. |
| S3TemplatesUrl | No | string | S3 bucket URL or path for the HTML graphics templates (normally the ASSETS/templates folder). |
| S3ProjectsUrl | No | string | S3 bucket URL or path for projects and rundowns (normally the DATAROOT folder). |
| S3PluginsUrl | No | string | S3 bucket URL or path for plugins and extensions (normally ASSETS/plugins). |
| S3MediaUrl | No | string | S3 bucket URL or path for media assets such as images and videos (normally ASSETS/media). |
| S3JsonUrl | No | string | S3 bucket URL for JSON data files used for data-driven graphics and external data integration. |
| S3EndpointUrl | No | string | Custom S3-compatible endpoint, for example MinIO or DigitalOcean Spaces. If not set, standard AWS S3 endpoints are used. |
| S3AccessKeyId | No | string, sensitive | Access key ID for the S3 storage. Used together with S3SecretAccessKey. |
| S3SecretAccessKey | No | string, sensitive | Secret access key for the S3 storage. |
| S3Region | No | string | Region of the S3 buckets, for example eu-west-1. |
Sensitive options (Password, S3AccessKeyId, S3SecretAccessKey) should be service secrets passed as {{secrets.NAME}} as the whole field value. Changing a secret later does not restart a running instance.
Open the instance URL in a browser. The main views are:
- Projects: organise graphics per show or production.
- Rundown: a playlist of graphic items played out in sequence or on demand.
- Template Editor: design and test HTML graphics templates.
- Playout: send graphics to the renderer output, typically a browser source in OBS or vMix.
To create a graphic: create or open a project, add a rundown entry and assign an HTML template, fill in the template fields (for example name, title, image) and press Play.
To integrate with OBS, add a Browser Source pointing to https://<your-instance-url>/renderer/. The page receives play and stop commands from the controller and renders the active graphic as a transparent overlay.