Start play
const url = 'https://example.com/api/v1/plays';const options = { method: 'POST', headers: {cookie: 'kivo_session=<kivo_session>', 'Content-Type': 'application/json'}, body: '{"workId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","versionId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","positionMs":1,"audioTrackId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","subtitleTrackId":"example","capabilities":{"file":{"containers":["example"],"trackSelection":true},"video":[{"codec":"example","delivery":["file"],"containers":["example"],"tags":["example"],"profiles":["example"],"maxLevel":1,"maxBitDepth":1,"maxWidth":1,"maxHeight":1,"maxFrameRate":1,"maxBitrateBps":1,"maxRefFrames":1,"interlaced":true,"anamorphic":true,"hdr":["hdr10"],"dolbyVision":[{"profile":1,"compat":[1],"el":true}],"doviFallback":true}],"audio":[{"codec":"example","delivery":["file"],"containers":["example"],"maxChannels":1,"maxSampleRate":1,"maxBitDepth":1,"profiles":["example"]}],"subtitles":[{"codec":"example","delivery":["file"],"containers":["example"]}]},"settings":{"localQuality":{"mode":"auto","maxBitrateBps":1,"bandwidthBps":1},"remoteQuality":{"mode":"auto","maxBitrateBps":1,"bandwidthBps":1},"directPlay":true,"burnSubtitles":true},"dialogueBoost":true}'};
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 \ --header 'Content-Type: application/json' \ --cookie kivo_session=<kivo_session> \ --data '{ "workId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "versionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "positionMs": 1, "audioTrackId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "subtitleTrackId": "example", "capabilities": { "file": { "containers": [ "example" ], "trackSelection": true }, "video": [ { "codec": "example", "delivery": [ "file" ], "containers": [ "example" ], "tags": [ "example" ], "profiles": [ "example" ], "maxLevel": 1, "maxBitDepth": 1, "maxWidth": 1, "maxHeight": 1, "maxFrameRate": 1, "maxBitrateBps": 1, "maxRefFrames": 1, "interlaced": true, "anamorphic": true, "hdr": [ "hdr10" ], "dolbyVision": [ { "profile": 1, "compat": [ 1 ], "el": true } ], "doviFallback": true } ], "audio": [ { "codec": "example", "delivery": [ "file" ], "containers": [ "example" ], "maxChannels": 1, "maxSampleRate": 1, "maxBitDepth": 1, "profiles": [ "example" ] } ], "subtitles": [ { "codec": "example", "delivery": [ "file" ], "containers": [ "example" ] } ] }, "settings": { "localQuality": { "mode": "auto", "maxBitrateBps": 1, "bandwidthBps": 1 }, "remoteQuality": { "mode": "auto", "maxBitrateBps": 1, "bandwidthBps": 1 }, "directPlay": true, "burnSubtitles": true }, "dialogueBoost": true }'Plays the version given, or the default one (PlayCreate), and
decides each track from the capabilities in the request; nothing is
stored per client.
The play shows which client it’s on by the caller’s session’s or API
key’s name. Over the user’s stream limit: 409 with code
streamLimit and the user’s plays in plays. When the server’s video
transcodes are all in use or its transcode disk is full: 503 with
code transcodeBusy and a reason (transcodeLimit,
storageFull); try again later. When nothing this client can play
can be made: 409 with code notPlayable and a reason.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
A UUIDv7.
Play this version. Default the version a chosen audio or
subtitle track belongs to; else the version the user last
played (UserState.versionId), while the work’s versions
list it; else the first of them.
Where to start on the version’s timeline. Default the resume position, or the beginning when the version is of another edition than the one the position is on.
An audio track’s id. Default: for an episode, the language
last chosen for its series; else the user’s audio language,
if the version has it; else the version’s default track.
Choosing a track for an episode remembers its language for the
series. Series memory applies when the user’s
rememberTracks is on (PlaybackPreferences).
A subtitle track’s id, or off. Default: for an episode,
the language and kind (forced, SDH, full or off) last chosen for
its series; else by the user’s subtitle mode and language
(PlaybackPreferences).
What this client plays, measured where it runs and corrected for
its platform’s known misreports. Facts only: choices the user makes
go in PlaybackSettings. Sent with every play; nothing is stored
per client.
Each list holds entries, and a track plays when any entry for its
delivery matches it: entries are alternatives, and every field of
an entry must hold. An absent field is no limit. Codec names are
ffmpeg’s codec_name, as Track.codec gives them. The server
ignores fields and enum values it doesn’t know rather than
refusing the request, and drops an entry left with no delivery.
object
Files it plays whole, the original or a download. Absent, it plays none.
object
Containers it plays, such as mkv, mp4, webm, ts, m2ts, mov, m4a, mp3, flac, ogg.
It plays any audio track inside a file, not only the default one, so choosing another audio track keeps the file. Default false.
One kind of video the client decodes.
object
Such as h264, hevc, av1, vp9, mpeg2video, vc1.
Where it decodes it, file or stream.
For file, the containers it decodes this in; other containers don’t match the entry.
For file, the codec tags it takes, such as hvc1, hev1, dvh1, dvhe.
Profiles as ffprobe prints them, such as High, Main 10, Profile 2.
The highest level, as the codec’s specification writes it, such as 4.1 or 5.1.
The decoder’s limit in bits per second. A quality the user picks goes in settings instead.
Whether it plays interlaced video. Default true.
Whether it plays video with non-square pixels. Default true.
The HDR formats it shows, of hdr10, hdr10plus and hlg; SDR always plays. An HDR10+ video matches hdr10.
The Dolby Vision profiles it shows.
A Dolby Vision profile a client shows. A video matches when its
profile is listed, with its base layer’s compatibility ID among
compat when that’s given.
object
The profile, 5, 7, 8 or 10.
The base layer compatibility IDs it shows, such as 1, 2, 4.
Whether it plays a video with an enhancement layer. Absent means it does.
Play a Dolby Vision video whose profile isn’t listed by its base
layer, when that layer matches hdr: profile 8.1 and 7 are
HDR10, 8.4 is HLG, 8.2 is SDR, and 10 is what its compatibility
ID says. Default false.
One kind of audio the client plays.
object
Such as aac, ac3, eac3, truehd, dts, flac, opus, mp3, alac.
Where it plays it, file or stream.
For file, the containers it plays this in.
The most channels that reach the output: decoded on the device, no more than its speakers or its own setting; passed through, as many as the receiver takes. Audio with more channels is transcoded to AAC with as many as the client’s AAC entry allows, at most 6; to stereo it’s mixed keeping dialogue clear.
Profiles as ffprobe prints them, such as LC, HE-AAC, Dolby TrueHD + Dolby Atmos.
A subtitle codec a client shows, and how. The server converts a
text subtitle to a text codec listed for a delivery. In the stream
that’s always WebVTT, the only text HLS carries. As an external
file it’s WebVTT too, where webvtt is listed, converted from
SubRip, WebVTT, mov_text or ASS as plain text, with styling beyond
italics, bold and underline dropped.
An ASS track stays ASS for a client that lists ass, and an
embedded one is burned in for a client that doesn’t. Image
subtitles are never converted; a client that can’t show one has it
burned in.
object
Such as webvtt, subrip, ass, mov_text, hdmv_pgs_subtitle, dvd_subtitle.
file read from the played file, stream a WebVTT rendition of
the HLS stream, external its own file. In picture-in-picture
or on AirPlay a client leaves out external.
For file, the containers it reads this from; other containers don’t match the entry.
The client’s playback settings, kept on the client.
object
The client’s quality on the server’s local networks.
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 client’s quality anywhere else, used instead of localQuality when the server counts the client as remote.
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.
Play files directly. Default true.
Always burn in subtitles. Default false.
Boost dialogue: the audio is encoded to AAC with the centre
channel raised and loud passages compressed, and the video is
copied. Default false. A play that can’t boost its dialogue
ignores it; PlayStarted.dialogueBoost says what the play does.
Responses
Section titled “Responses”The 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" } ]}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" } ]}