The signer on air

An overlay is a web page that shows only the Signa signer, on a see-through background. Your graphics system shows it like any other web graphic; whatever you send to the overlay, it signs.

1. Create an overlay

POST/v1/overlays

One per output: a studio, a channel, a stream. Give it a name you will recognise, and choose whether it shows captions.

Field	Required	Details
`name`	No	Yours, to tell overlays apart. Default "Overlay".
`captions`	No	`true` (default) shows what is being signed in a line under the signer; `false` shows the signer alone. You can change it later.

POST /v1/overlays

curl -X POST https://api.usesigna.org/v1/overlays \
  -H "Authorization: Bearer $SIGNA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Studio A", "captions": true}'

Response

{
  "success": true,
  "payload": {
    "id": "5f0c2b8e-…",
    "name": "Studio A",
    "captions": true,
    "url": "https://www.usesigna.org/overlay/5f0c2b8e-…#ovt_…",
    "token": "ovt_…"
  }
}

Keep the link

The url is the overlay page, and it is shown only now. The part after # lets a screen watch the overlay (nothing more: it can't sign or spend). If it leaks, delete the overlay and create another.

2. Put the page on screen

Add the link to your graphics system as a web or HTML source, at your output's size (1920 × 1080 for HD). The signer stands in the page; place and scale the source where you want the signer on screen. Step-by-step for each system: Studio systems.

Options go in the query string, before the #:

Option	Default	Details
`captions=0` or `captions=1`	The overlay's setting	Hide or show the caption line on this screen only, whatever the overlay's setting says.
`bg=00ff00`	None	A solid background instead of a see-through one, for systems that key out a colour (chroma key).
`shirt, skin, hair, pants`	Signa defaults	The signer's colours, hex without `#`, as for videos.
`gender, age`	`male, adult`	As for videos.

Example

https://www.usesigna.org/overlay/5f0c2b8e-…?shirt=1e3a8a&captions=0#ovt_…

3. Send it something to sign

POST/v1/overlays/:id/sign

The same body as /v1/sign. The caption appears at once and the signer starts on the first word within about a second, on every screen showing the overlay. Send the next piece when you like: it queues behind what is being signed.

POST /v1/overlays/:id/sign

curl -X POST https://api.usesigna.org/v1/overlays/$OVERLAY_ID/sign \
  -H "Authorization: Bearer $SIGNA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Mwiriwe", "from": "rw", "to": "rsl"}'

The answer says how many words were signed and how many screens were watching: {"words": 1, "watchers": 2}. Zero watchers means nothing has the page open.

POST/v1/overlays/:id/clear

Takes the caption off the screen, for example between stories.

4. Or sign live

For a live programme, stream the studio audio to a live session with the overlay's id in the start message, and every word heard is signed onto the overlay as it is settled:

{"type": "start", "lang": "rw", "token": "sk_live_…", "overlay": "5f0c2b8e-…", "to": "rsl"}

A ready-made bridge from a studio feed: Live from the studio.

In your own website

An overlay works in any web page too: put its link in an iframe, next to your video player or article, and sign onto it from your server or with a client token.

<!-- The signer in your own web page: the overlay link in an iframe. -->
<div style="position: relative; width: 360px; aspect-ratio: 3 / 4;">
  <iframe
    src="https://www.usesigna.org/overlay/OVERLAY_ID?bg=0b1220#ovt_…"
    style="position: absolute; inset: 0; width: 100%; height: 100%; border: 0;"
    allow="autoplay"
    title="Sign language"
  ></iframe>
</div>

Changing an overlay

PUT/v1/overlays/:id

Send only what changes: name, captions or both. Every screen showing the overlay follows straight away, without reloading, so you can turn captions off for one programme and on again for the next.

PUT /v1/overlays/:id

curl -X PUT https://api.usesigna.org/v1/overlays/$OVERLAY_ID \
  -H "Authorization: Bearer $SIGNA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"captions": false}'

Lost the link?

We keep only a fingerprint of an overlay's link, so it can't be shown again. POST /v1/overlays/:id/link makes a new one (in the answer's url); screens on the old link stop showing the overlay.

Managing overlays

	Endpoint
List your overlays	`GET /v1/overlays`
Change name or captions	`PUT /v1/overlays/:id`
Make a new link (the old one stops working)	`POST /v1/overlays/:id/link`
Delete one (its pages go blank)	`DELETE /v1/overlays/:id`

Up to 20 screens can show one overlay at once. A screen that loses its connection reconnects by itself and carries on from the next word.

← Signing on TV Live from the studio →