Service: SPX Graphics Controller - EyevinnOSC/community GitHub Wiki

SPX Graphics Controller

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.

What it can do

  • 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.

Creating an instance

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}}"

Options

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.

Using the 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.

Resources

⚠️ **GitHub.com Fallback** ⚠️