Subtitles

List the fonts a file carries

Authorisation

Bearer token or API key · Session cookie · Cast ticket

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Serve an embedded font

Authorisation

Bearer token or API key · Session cookie · Cast ticket

• 200Success. font/* ·
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Serve a subtitle track

A sidecar by name or an embedded stream by index, converted to WebVTT (or ASS for the styled renderer). offsetMs shifts every cue.

Authorisation

Bearer token or API key · Session cookie · Cast ticket

• 200Success. text/vtt · string
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Remove a fetched subtitle

A subtitle fetched and kept with the server’s own files goes, file and all, with its timing correction; the film’s transcript follows. Whoever fetched it, for a week, or an admin. Never a track in the film, a file beside it, or subtitles Collectoh made (DELETE /subtitles/generations/{id}).

Authorisation

Bearer token or API key · Session cookie

• 204Done; no body.
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. FORBIDDEN: the caller neither fetched it nor is an admin application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 409CONFLICT: the subtitle was not fetched and kept with the server’s files application/json · ErrorEnvelope

Serve a stretch of a picture subtitle track

For a player that draws Blu-ray (PGS) and DVD (VobSub) subtitles itself (P7-11), so the picture is never converted for them: the packets of the track between from and to (milliseconds on the video’s clock, ten minutes at most), and those before from that what shows then was built from. A short header (CIS1, its length, JSON with the codec and, for VobSub, the palette and frame size), then each packet as its time and duration (little-endian doubles), its length and its bytes, then an end record of the same shape whose time is NaN and whose bytes are JSON: {"cut":true} when a cap (4,096 packets, 32 MB) stopped the stretch short — ask again from the last packet’s time. The track’s timing correction is applied. Read through the Matroska cues where the file has them, so the film itself is not read.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/octet-stream ·
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: the stretch is longer than ten minutes, or ends before it starts application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 415MEDIA_UNSUPPORTED_CODEC: the track is text, or a picture subtitle in a file of its own beside the film application/json · ErrorEnvelope
• 500TRANSCODE_FAILED: FFmpeg could not read the track out of a file that is not Matroska application/json · ErrorEnvelope
• 503TRANSCODE_LIMIT_REACHED: FFmpeg is already reading two such tracks and eight more stretches wait for it application/json · ErrorEnvelope

Read a track’s sync offset

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · SubtitleSync
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Auto-sync a track to the audio

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Set a track’s sync offset

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 200Success. application/json · SubtitleSync
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Clear a track’s sync offset

Authorisation

Bearer token or API key · Session cookie

• 204Done; no body.
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Fix a track’s timing from the speech, within my allowance

As POST /items/{id}/subtitles/{streamId}/sync: one use of today’s allowance for anyone but an admin, given back when it is refused before the soundtrack is heard (no such track, nothing in it to read), not after.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 429RATE_LIMITED: today’s allowance is spent application/json · ErrorEnvelope

Set a track’s timing by hand

As PUT /items/{id}/subtitles/{streamId}/sync, for anyone the server lets use subtitle tools.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 200Success. application/json · SubtitleSync
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Put a track back to its own timing

As DELETE /items/{id}/subtitles/{streamId}/sync, for anyone the server lets use subtitle tools.

Authorisation

Bearer token or API key · Session cookie

• 204Done; no body.
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Download a found subtitle

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 201Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Download a found subtitle, within my allowance

As POST /items/{id}/subtitles/download, for anyone the server lets use subtitle tools: one use of today’s allowance, given back if the download fails. Anyone but an admin fetches only what a search of theirs found for the film in the last half hour, with the language and SDH flag the provider gave it — whatever the body says — never as a forced track, kept with the server’s own files, never beside the media.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 201Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: no search of the caller’s found that subtitle for the film application/json · ErrorEnvelope
• 429RATE_LIMITED: today’s allowance is spent application/json · ErrorEnvelope

Search the providers for subtitles, within my allowance

As GET /items/{id}/subtitles/search, for anyone the server lets use subtitle tools. Spends nothing, but needs a use left today. Anyone but an admin searches one at a time, at most 30 times an hour, by the film’s own identifiers and title — query, another title, is an admin’s — with forced subtitles left out whatever forced says (theirs are never kept as forced), and what a search finds is what they may fetch for the film for half an hour.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. FORBIDDEN: someone other than an admin searches by another title (details.by: title) application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 429RATE_LIMITED: today’s allowance is spent, a search of theirs is still going, or they searched 30 times this hour application/json · ErrorEnvelope
• 502PROVIDER_UNAVAILABLE: no subtitle provider is configured or it is down application/json · ErrorEnvelope

Make subtitles from the speech

Queues a film, an episode or a video to be heard by the local speech model: its soundtrack (the default one unless said), in the language it is spoken in (as the soundtrack says unless said), written as spoken or translated into English. 202 with the new request; 200 with the one already waiting or running for the same file, language and task. One use of today’s allowance for anyone but an admin, given back if it fails before anything is heard, or is cancelled before it starts or by somebody else. A film with subtitles a person made in that language is refused unless an admin sends force.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 202Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 409CONFLICT: Collectoh has made these already with the model chosen now, or the film has subtitles a person made in that language (details.reason: subtitled) application/json · ErrorEnvelope
• 429RATE_LIMITED: today’s allowance is spent application/json · ErrorEnvelope

List the subtitles asked to be made for an item

Each request to make subtitles from the speech: how far it has got, how long it has left on this server, how many wait before it, and the subtitle it made. A season’s or a show’s are its episodes’.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Search a provider for subtitles

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 502PROVIDER_UNAVAILABLE: no subtitle provider is configured or it is down application/json · ErrorEnvelope

Stop the rest of a season or a selection

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Make subtitles for a season, a show or a selection

An admin’s: each film, episode and video named, and each episode of a season or a show named, queued to be heard after anything asked for by itself, waiting while anyone streams. Those with subtitles a person made in that language are left alone (subtitled) unless force. With dryRun, only how many it would be and how long they would take on this server.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 202Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

Cancel a request, or remove the subtitles it made

Whoever asked, or an admin: a request waiting or running is cancelled; one finished has its subtitle removed; one that failed or was cancelled is forgotten.

Authorisation

Bearer token or API key · Session cookie

• 204Done; no body.
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Read what I may do with subtitles

Whether the caller may find, fetch, sync and make subtitles, why not when not, and how much of today’s allowance is left; and the speech model subtitles are made with, how long a minute of soundtrack takes on this server, and the languages it hears.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope