Upload a subtitle / caption track

POST

/assets/{id}/subtitle-tracks

• Local development behind nginx (port 8088 by default)

Upload a subtitle file (SRT / SSA / ASS / SUB / VTT) for this asset. The conversion worker normalises the file to WebVTT and inserts an asset_subtitle_tracks row. Returns 202 immediately; the track appears in the list endpoint when the conversion job completes (typically <1 second for text-based sources).

IDX (DVD bitmap) uploads return 501 Not Implemented — bitmap OCR requires a capability add-on not present in the standard runtime.

Returns 422 when the asset’s renderable kind doesn’t support subtitles.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Request Body ^required

object

lang

required

RFC 5646 language tag (e.g. “en”, “en-US”). “und” accepted for sidecar files with no inferable language.

string

label

Optional human-readable label. Empty string default.

string

source_format

required

string

Allowed values: vtt srt ssa ass sub idx

content

required

Subtitle file contents (UTF-8 text for vtt/srt/ssa/ass/sub).

string

Responses

202

Track conversion queued.

One WebVTT subtitle track attached to an asset. NOT a first-class asset; rides along with its parent in the Asset.subtitle_tracks array. Tracks are uniquely identified by (asset_id, lang) — re-uploading the same lang replaces the existing row rather than creating a duplicate.

object

lang

required

RFC 5646 / BCP 47 language tag (e.g. “en”, “en-US”, “ja”, “fr-CA”). The sentinel value “und” is reserved for sidecar files that matched by basename but had no inferrable language segment.

string

label

Optional human-readable label (“English (US)”, “Forced”, “Director’s commentary”). Empty string when not provided; never null.

string

file_hash

required

CAS hash of the stored WebVTT file.

string

source_format

required

The format the track was uploaded in. The conversion worker stores WebVTT regardless; tracking the source lets operators re-convert if a converter bug surfaces.

string

Allowed values: vtt srt ssa ass sub idx

confidence

required

1.0 for text-based sources (deterministic conversion). <1.0 for OCR’d bitmap sources like IDX (DVD subtitles). UI MAY surface a warning banner below 0.8.

number format: float

<= 1

created_at

string format: date-time

400

Malformed request

object

error

required

Human-readable error summary

string

Example

the request could not be completed

401

Authentication required, missing, or invalid

object

error

required

Human-readable error summary

string

Example

the request could not be completed

Example

{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed

422

Request shape is valid but the action doesn’t apply (e.g. subtitles on a non-video/audio asset).

object

error

required

Human-readable error summary

string

Example

the request could not be completed

501

Format requires a capability add-on not present.