Retry play as transcode
const url = 'https://example.com/api/v1/plays/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/fallback';const options = { method: 'POST', headers: {cookie: 'kivo_session=<kivo_session>', 'Content-Type': 'application/json'}, body: '{"positionMs":1,"code":"mediaDecodeError","detail":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/plays/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/fallback \ --header 'Content-Type: application/json' \ --cookie kivo_session=<kivo_session> \ --data '{ "positionMs": 1, "code": "mediaDecodeError", "detail": "example" }'Ends the failed play and starts a new one at positionMs with the
same version and tracks, transcoding everything: nothing played
directly or copied, and a selected subtitle burned in rather than
drawn by the client. A video transcode that was on an accelerator is
on the CPU. Each track’s reason is fallback unless it already had
one. The client plays the returned play, and asks once per play.
When the failed play already transcoded everything on the CPU, it
ends and there’s nothing else to try: 409 with code noFallback.
The new play can be refused as a start is.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”A UUIDv7.
Request Bodyrequired
Section titled “Request Bodyrequired”object
What failed.
The player’s own error text, for the server log.
Responses
Section titled “Responses”The new play and where to fetch its media.
A play that started, and where to fetch its media. Media URLs are
relative to the API root (/api/v1/) and carry the play’s ID, which
is a credential: treat them like a token.
tracks says how every choice shows. A choice without a delivery
starts a new play at the current position with that track. Any
other shows as its delivery says, and a subtitle shown so is
reported in the heartbeat (PlayUpdate.subtitleTrackId), as is an
audio track chosen inside the file. Players show the play as
Direct Play when the video’s delivery is file, Direct Stream when
it’s stream without transcode, and Transcode with transcode.
object
A UUIDv7.
A UUIDv7.
A UUIDv7.
Where playback starts on the version’s timeline. Seek here once metadata has loaded (Safari ignores an earlier seek).
Whether the client is on a local network.
The stream’s bitrate, a video transcode’s target or else the source’s, when known.
The bitrate cap the server sets on the play whatever quality the client picks, when one applies. A quality above it can’t be chosen.
How a play’s media is fetched: file is the original, each part’s
url with range requests; stream is the HLS playlist at url.
For file, the first part; for stream, the multivariant playlist.
Every track of the version, and the subtitle choice off.
One choice of a play: a track of its version, or the subtitle choice
off, and how it shows.
object
A track’s id, or off.
A track’s type.
True for the tracks the play shows; absent otherwise.
Absent when choosing it starts a new play.
The codec it’s delivered as, such as hevc, aac or webvtt.
The video’s HDR as delivered; absent for SDR.
What a transcoded track becomes.
object
Video only; what encodes it, the accelerator’s name as GET /api/v1/accelerators gives it, such as Intel Quick Sync (QSV), or CPU.
Why the track isn’t delivered unchanged in the file, or why choosing it starts a new play, when there’s a reason to give.
The capability that failed: its field (such as maxLevel, codec
or containers), what the client declared, and what the track has.
object
The declared value, lists joined by commas; absent when the client declared none.
For file, the track’s stream index, to select it in the player.
For external, the file, relative to the API root.
For an ass subtitle delivered external, the URLs of the
fonts it uses, each once, relative to the API root:
GET /api/v1/fonts/{sha256}, cacheable for good. Load them
before drawing.
The version’s parts in order; positions are on their joined timeline.
object
For file delivery, the original.
object
The manifest, when ready.
object
The version’s markers on its timeline, in order.
A part of a video’s timeline a player offers to skip. An episode has intro, recap and credits markers, a movie credits only, any other video none. Each kind comes from an admin’s marker, else, for an episode, what the server found in its season’s audio and pictures, else the file’s own chapters (a chapter whose whole name is the marker’s: Intro, Opening Credits, OP; Recap, Previously On; Credits, End Credits, ED, where it belongs and as long as one lasts).
object
What a marker skips. A later server may add kinds; skip a marker of a kind you don’t know.
Where a marker comes from: the file’s chapters, the audio its episode shares with others in its season (and, for credits, its pictures), or an admin. A later server may add sources.
Set on final credits: nothing follows them to the video’s end but, perhaps, a next episode’s preview, so up next may appear at their start.
The quality the play applies: the request’s settings.quality,
or its settings.remoteQuality when the server counts the client
as remote. Absent means auto.
object
A quality pick: auto chosen from limits and measured bandwidth,
original with no cap, limit capped at maxBitrateBps.
For limit, from the fixed ladder.
For auto, the client’s last measured download rate from this server; the play stays below about 80% of it.
The play’s dialogue boost. Absent when the play can’t boost its dialogue: one without video or audio, or on a client without HLS. Switching it starts a new play at the same position.
object
Whether the play boosts its dialogue.
What the boost changes besides the dialogue, the same whether it’s on or off. Absent when nothing.
Example
{ "delivery": "file", "tracks": [ { "type": "video", "delivery": "file", "hdr": "hdr10", "reason": "containerUnsupported" } ], "markers": [ { "kind": "intro", "source": "chapter" } ], "quality": { "mode": "auto" }, "dialogueBoost": { "cost": "audioAsAac" }}The request is malformed or a field is invalid (code invalidRequest).
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}No valid session or API key (code unauthenticated), or a failed sign-in (code invalidCredentials).
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}No such resource, or the caller may not see it (code notFound).
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}The resource’s state doesn’t allow this; the code says why.
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}An admin stopped the play (code playEnded), with their message when they gave one.
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}default
Section titled “default”A server-side failure: 500 (code internal, or transcodeFailed
for a play’s media), or 503
for something unavailable (codes providerUnavailable and
transcodeBusy, for now; notConfigured, until an admin configures
it).
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}