Subtitles

Send a recording or a video, get timed subtitles back: as SRT for editors and players, VTT for the web, or JSON for your own code. On their own, or as the script for signing.

The request

POST/v1/subtitles

A multipart form:

Field	Required	Details
`file`	Yes	The recording or video: MP3, WAV, M4A, AAC, OGG, WebM, MP4, MOV, MKV… Up to 100 MB and one hour. Only the sound is used.
`lang`	No	What is spoken: `rw` (default), `en`, `fr`, `sw`, `ja`.
`format`	No	In the query string or the form: `json` (default), `srt` or `vtt`.

POST /v1/subtitles

curl "https://api.usesigna.org/v1/subtitles?format=srt" \
  -H "Authorization: Bearer $SIGNA_KEY" \
  -F file=@amakuru.mp4 \
  -F lang=rw \
  --output amakuru.srt

Big video files

Only the sound is needed. For a long programme, send just its audio and the upload is a fraction of the size: ffmpeg -i programme.mxf -vn -ac 1 -ar 16000 programme.m4a.

The response

With format=srt or vtt you get the file itself. With json:

{
  "success": true,
  "payload": {
    "lang": "rw",
    "duration": 94.32,
    "text": "Muraho neza … Mwiriwe",
    "cues": [
      { "start": 0.84, "end": 3.12, "text": "Muraho neza" },
      { "start": 3.9, "end": 6.4, "text": "…" }
    ]
  }
}

Field	Details
`duration`	Seconds of audio in the file
`text`	Everything that was said, in one string
`cues`	The subtitles: `start` and `end` in seconds, and `text` on at most two lines of 42 characters

How the timing works

Signa listens for the pauses in the recording, splits it there, and transcribes each piece. Each subtitle takes its time from where its piece sits in the recording, so subtitles change when the speaker pauses, the way a person would subtitle it. A speaker who never pauses is split at their quietest moments, and no subtitle stays up longer than about eight seconds.

Subtitles and signs

To sign a recording as well, send the subtitles' text to /v1/sign cue by cue, and play each cue's signs at its start. Signing a show from its subtitles walks through it.

Billing

Subtitles count the length of the audio, in minutes, as subtitle time on your usage. Signing their text afterwards counts its characters, as usual.