Service: OGraf Rendering Server - EyevinnOSC/community GitHub Wiki

OGraf Rendering Server

OGraf Rendering Server (serviceId superflytv-ograf-server) is an open source broadcast graphics server from SuperFly.tv. It serves HTML-based graphics templates and exposes a REST API for controlling on-air graphics in live production workflows, compatible with CasparCG, OBS and other HTML-renderer clients. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance with up to 10 GiB of storage per instance. License: MIT.

This page also covers two companion services: OGraf Template Editor (eyevinn-ograf-editor) and SPX Graphics Controller (tuomoku-spx-gc).

What it can do

  • Upload graphics templates through the API and render them in response to API calls.
  • Suit lower-thirds, scoreboards and other live graphics automation.
  • Store graphics templates locally or in an S3-compatible bucket (MinIO, AWS S3 and others).

Creating an instance

S3 storage is optional. If you use it, create the bucket (for example a MinIO instance) first and store the credentials as service secrets with create-service-secret (serviceId: "superflytv-ograf-server"), for example s3accesskeyid and s3secretaccesskey. Then call create-service-instance with serviceId: "superflytv-ograf-server". The instance name must be alphanumeric and at most 20 characters.

Minimal example:

{ "name": "mygfx" }

With S3 storage:

{
  "name": "mygfx",
  "S3GraphicsUrl": "https://my-bucket.s3.eu-west-1.amazonaws.com/graphics/",
  "S3AccessKeyId": "{{secrets.s3accesskeyid}}",
  "S3SecretAccessKey": "{{secrets.s3secretaccesskey}}",
  "S3Region": "eu-west-1"
}

Wait with wait-for-service-ready (or get-instance-status) and read the URL with describe-service-instance.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric/underscore only, at most 20 characters.
S3GraphicsUrl No string Base URL of the graphics assets in S3-compatible storage, for example https://my-bucket.s3.eu-west-1.amazonaws.com/graphics/. Lets the server load graphics from cloud storage instead of local storage.
S3EndpointUrl No string Endpoint URL of a custom S3-compatible service such as MinIO, for example https://myminio.example.com. Leave out for AWS S3.
S3AccessKeyId No string, sensitive Access key ID for the S3 storage.
S3SecretAccessKey No string, sensitive Secret access key for the S3 storage.
S3Region No string Region of the S3 bucket, for example eu-west-1.

Pass the two S3 credentials as {{secrets.NAME}} references; a reference must be the entire field value. Overwriting a secret does not restart a running instance.

Using the instance

The OGraf REST API is at the instance URL. It lets you upload templates, list available graphics and control rendering:

# List available graphics templates
curl https://mygfx.superflytv-ograf-server.auto.prod-se.osaas.io/api

# Upload a template
curl -X POST https://mygfx.superflytv-ograf-server.auto.prod-se.osaas.io/api/graphic \
  -H "Content-Type: application/json" \
  -d '{"id": "lowerthird", "url": "https://my-bucket.s3.amazonaws.com/graphics/lowerthird.html"}'

OGraf Template Editor options

OGraf Template Editor (serviceId eyevinn-ograf-editor, page) is a companion service for designing broadcast graphics templates with drag-and-drop, real-time previews and code customization. Source: Eyevinn/ograf-editor. Create it with create-service-instance; it has no dependencies.

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric/underscore only, at most 20 characters.

SPX Graphics Controller options

SPX Graphics Controller (serviceId tuomoku-spx-gc, page) is an alternative controller for HTML graphics in OBS, vMix and similar tools. License: MIT. Source: TuomoKu/SPX-GC. Its S3EndpointUrl option can be associated with a MinIO instance (minio-minio) over the internal network; create the MinIO instance first if you use it.

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric/underscore only, at most 20 characters.
Username No string Username for SPX authentication. With a password, users must log in. If a username is set and the password is blank, the app asks for a login policy on first launch. Stored in SPX config.json.
Password No string, sensitive Password for SPX authentication, stored encrypted in config.json. Pass as {{secrets.NAME}}.
S3TemplatesUrl No string S3 bucket URL or path for HTML graphics templates (normally the ASSETS/templates folder).
S3ProjectsUrl No string S3 bucket URL or path for SPX projects and rundowns (normally the DATAROOT folder).
S3PluginsUrl No string S3 bucket URL or path for SPX plugins (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 or path for JSON data files used for data-driven graphics.
S3EndpointUrl No string Endpoint of an S3-compatible service such as MinIO. If unset, standard AWS S3 endpoints are used.
S3AccessKeyId No string, sensitive Access key ID for the S3 storage.
S3SecretAccessKey No string, sensitive Secret access key for the S3 storage.
S3Region No string Region of the S3 buckets, for example us-east-1.

CLI usage

# Without S3 storage
npx -y @osaas/cli create superflytv-ograf-server mygfx

# With S3 storage
npx -y @osaas/cli create superflytv-ograf-server mygfx \
  -o S3GraphicsUrl="https://my-bucket.s3.eu-west-1.amazonaws.com/graphics/" \
  -o S3AccessKeyId="{{secrets.s3accesskeyid}}" \
  -o S3SecretAccessKey="{{secrets.s3secretaccesskey}}" \
  -o S3Region="eu-west-1"

Resources