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
- OGraf Template Editor: companion service for editing OGraf templates
- SuperFly.tv OGraf on GitHub
- SPX Graphics Controller: alternative broadcast graphics controller