External resolver apps¶
Everything else in this guide runs inside Kino's sandbox: a plugin reads a site, a JSON API or your own server and hands Kino a URL. Some sources cannot be turned into a URL that way. They need a real program on the device: a download engine, a media pipeline that converts a format the phone cannot decode, a helper that speaks a protocol the sandbox has no access to. Kino does not contain such programs and does not know how any of them works. Instead it has a small open protocol: a plugin names what it found, and an independently-installed Android app, an external resolver, turns it into something Kino can play.
This page is for three readers: the plugin author who wants to use a resolver, the developer who wants to
build one, and anyone who needs to know what to expect. It needs "apiVersion": 11 (Kino 0.9.66) and the
externalResolve capability.
What it is, and what it is not¶
- It is one extra hop in the life of a
resolve(): your plugin answers{ external: { protocol, ref } }instead of aurl; Kino handsprotocolandrefto an installed app that says it handlesprotocol; that app answers with the same kind of object a plugin answers with (url,headers,subtitles,mime... plusmediaandportable); Kino plays that. - It is not a way to reach another app in general, a plugin API or a back door around the host rules: Kino
never sends the app anything but
protocolandref, never widens your plugin's approved hosts because of it, and the app never learns which plugin, title or person it is serving beyond what you put inref. - It is not part of Kino. Kino's own code never branches on the value of
protocol, and there is no registry of names: a protocol name is a string a plugin and a resolver agree on by convention (my-protocolin the examples). Who builds the resolver, how it gets its content and whether you may use it for yours is between you and its author. - It is not guaranteed to exist. Nothing says an app is installed (what to expect).
Who does what¶
| Piece | Does | Never does |
|---|---|---|
| Your plugin | Finds the title, produces an opaque ref, answers { external: { protocol, ref } } (and may name the app: resolver, or the manifest's externalResolver). |
See the app, its answer or how it played. |
| Kino | Finds the app, asks the person once, binds it, shows live progress with Cancelar, validates the answer with the same rules as a plugin's, plays it (and casts it), shows the person a readable error. | Interpret ref, widen your hosts, retry a failure the app explained, ask an app for a download, a preload or a background refresh. |
| The resolver app | Does the real work, keeps its own server alive while the player reads, answers onResult / onError, may say why a later request failed. |
Run in Kino's sandbox or talk to your plugin. |
The flow, step by step¶
plugin resolve("title-42") -> { external: { protocol: "my-protocol", ref: "<opaque>", resolver?: "com.example.resolver" } }
Kino finds an app declaring "my-protocol"; first time: asks the person (Permitir / No permitir)
Kino binds the app's service -> IExternalResolver.resolve("my-protocol", "<opaque>", callback)
app onProgress(40, "Preparando...") ... Kino shows "Abriendo con <app>" with a bar and Cancelar
app onResult(json) or onError(code, message) (exactly one; Kino's own limit is 120 s for the whole call)
Kino validates json like a plugin answer, unbinds right away, plays the url
player reads the url while the app keeps serving (a foreground service)
- The answer.
externalcan be the wholeresolve()answer (thenurlmay be left out) or one entry of a Stream'salternatives, next to a concrete{ url }copy or a lazy{ ref }one (labelled and lazy copies).protocolis 1 to 64 characters froma-z 0-9 . _ -;refis 1 to 2048 characters with no control characters;resolveris an Android package name. A plugin belowapiVersion11, or one that does not declareexternalResolve, hasexternalignored and fails like an answer with nourl. A malformedexternalis dropped, never half-read. - Finding the app. An installed app is a candidate when its manifest declares a
<service>with the actioncom.arkiv.player.action.RESOLVE_EXTERNALand a<meta-data android:name="com.arkiv.player.meta.RESOLVER_PROTOCOLS" android:value="my-protocol,another">namingprotocol. Whenresolver(or the manifest'sexternalResolver.package) is set, only that app is a candidate; if it is not installed, Kino says so, or offers its download (below). - Consent. The first time, the person is asked, naming your plugin and the app, and told the app is not
Kino's. The answer is stored per (plugin, protocol, app), applies from then on and can be revoked in
Ajustes, in the "Fuentes externas" section. With more than one candidate and no
resolver, the person picks ("Elige qué aplicación usar") and the pick is remembered as the same decision; Kino asks again only when it becomes ambiguous. A "no" is remembered too: that title then says "No autorizaste resolver este contenido con ...". This is the only consent: your plugin's own install sheet does not change forexternalResolve. - Binding and the call. Kino binds the service and calls
resolve(protocol, ref, callback). One call at a time per binding. The app answers with any number ofonProgress(percent, message)and then exactly one ofonResult(json)/onError(code, message). - Progress. Kino shows the latest
onProgresslive:percent0 to 100 as a bar (anything else means "indeterminate"),messageas one short line (whitespace collapsed, control characters dropped, cut at 80 characters; blank shows Kino's own "Buscando..."). The person can press Cancelar or leave the player: Kino callscancel(), unbinds and ignores anything the app sends afterwards. - The deadline. Past 120 s Kino calls
cancel()and reportstimeout. - The result.
onResult's JSON is validated by the same code that validates a plugin'sresolve()answer. It differs only in hosts (below), in that DRM is refused and that a secondexternalinside it isbad_response: one hop, never a chain. - After the answer. Kino unbinds at once. The app has to keep itself alive (a foreground service) for as long as the player reads from the URL. If it has to refuse a later request it says why in a response header (errors).
What a resolver app can do¶
Anything that ends in a URL Kino can play, for example:
- Serve content it fetches as the player reads it. A helper that downloads while you watch and answers with a URL on its own server on the device (the loopback case).
- Convert what the device cannot open. A 10-bit video, an unusual container or an audio codec nobody decodes can be answered as an HLS of 8-bit H.264 and AAC, produced on demand, so the player still gets picture and sound.
- Add tracks.
subtitlesandaudioTracksin the answer, or, for an HLS, renditions the manifest itself lists (#EXT-X-MEDIA). - Describe the file.
mediasays what the file holds, so Kino can show it and use it as a hint. - Offer a universal copy for TVs.
portable. - Explain failures in a sentence the person reads, before the answer (
onError) and after it (X-Resolver-Error).
Things it cannot do: change your plugin's approved hosts, ask the person for anything through Kino, reach other plugins, return DRM, or be asked outside a person pressing play.
The answer¶
onResult carries the same JSON shape as a plugin's resolve() answer:
| Field | Notes |
|---|---|
url |
The video. Required. See Hosts below. |
mime, headers, subtitles, audioTracks, durationMs, expiresInSeconds |
As for a plugin; subtitles and audio track URLs are checked like url. |
media |
Optional, advisory: what the file holds (below). |
portable |
Optional: a universal HLS copy of the same video (below). |
drm, external |
Refused (bad_response). |
Hosts. The url came from the app, not from your plugin, so your declared hosts do not apply: any public
host is accepted, over https or http, for the video, its subtitles and audio tracks and everything its
manifest names while it plays; never an address on the home network, a local name or a private IP. That
allowance belongs to this one playback and is never added to your plugin's approved hosts; Kino never asks the
person to widen them for it.
The loopback origin¶
An app that has the content locally may answer with the URL of its own server on the device:
http://127.0.0.1:<port>/..., plain http, host exactly 127.0.0.1, port 1024 or higher, no credentials. That
one origin, taken from this very answer, is accepted for that playback (never localhost, another address,
IPv6, https on loopback or a low port; a redirect from elsewhere into it is refused). Put an unguessable token
in the path: any app on the device can reach loopback. The server should answer GET and HEAD with Range
(a player seeks with it).
media¶
Optional and advisory, and a plugin's own resolve() answer may carry the same object (see
The Stream rules). Every field is optional and cleaned: one-line text cut at 120
characters (codec/container 40, language 20), numbers clamped, at most 16 tracks and 4 notes; an object
with nothing usable left is dropped, never an error.
"media": {
"title": "Movie.mkv", "sizeBytes": 1234567890, "container": "matroska,webm",
"video": { "codec": "h264", "profile": "High 10", "width": 1920, "height": 1080, "fps": 23.976, "bitDepth": 10, "hdr": false },
"audio": [ { "codec": "eac3", "channels": 6, "language": "eng", "title": "Original", "default": true } ],
"subtitles": [ { "codec": "subrip", "language": "eng", "title": "", "text": true } ],
"converted": true, "notes": ["no decoder for H.264 High 10 on this device"]
}
The tracks are the file's, whether or not the app converted them for the player (converted). Kino logs a
summary (codecs and counts, never a title or a note), carries media to the player and may use it as a hint
when it decides how to cast. It never trusts it for anything that could harm the person. Showing it to the
person is not built yet.
portable¶
{ "url": "...", "mime": "application/x-mpegURL" }: a universal version of the same video, which the app
can make on demand and any TV receiver plays: HLS, H.264 8-bit up to 1080p, stereo AAC, its audio tracks and
text subtitles as HLS renditions. It must cost nothing until something reads it. It is checked like url; a
non-HLS mime, or a URL that fails the checks, drops the portable and keeps the rest of the answer. It is
ignored next to DRM or request signing. The phone's own player never uses it.
Errors the person reads¶
| When | What the app sends | What the person sees |
|---|---|---|
| Before the answer | onError(code, message), code one of unavailable, timeout, cancelled, unsupported, bad_response, other (anything else is read as other) |
"No se pudo resolver este contenido (code): message." The message is the app's own sentence, cleaned to one line of at most 120 characters and shown as the app's words, so keep it short and plain. |
| After the answer, when its server cannot serve a request | An HTTP 4xx/5xx with the header X-Resolver-Error: <code>; <message> (ASCII, at most 120 characters) |
The player's error line "La aplicación que ofrece este video dijo: message", and Kino does not retry it. Only this origin's responses are read this way. |
| Kino's own failures | Nothing | Only the code: "No se pudo resolver este contenido (unavailable)" when the app cannot be bound, timeout past 120 s, bad_response for a JSON that fails the checks. Their English detail goes to the log, never the screen. |
| No app, a denial, the picked app gone | Nothing | "Este contenido necesita una aplicación externa que no tienes instalada.", "No autorizaste resolver este contenido con ...", "La aplicación que elegiste ya no está instalada." |
Casting a resolver's title¶
A TV can never reach 127.0.0.1, so a title from a resolver is never handed to a TV by its own URL. Kino serves
it through its own cast proxy on the phone, which reads the resolver's origin and gives the TV a token URL on
the local network (Sending to the TV). That means:
- the app's server must answer
GETandHEADwithRange; every read through the proxy reaches it as an ordinary request (so it keeps an idle timer alive); - an HLS answer is rewritten for the receiver, renditions included (
#EXT-X-MEDIAaudio and WebVTT subtitles), and a progressive file goes the way any plugin file does (the proxy, or the phone's remux when the cast method asks for it); - when the title's own route would need a conversion, or
mediasays the video is not something a receiver takes as it is (not H.264, deeper than 8 bits, above 1080p, HDR, a DTS or TrueHD main audio) and the stream is not already a conversion, Kino casts the app'sportablecopy instead, when it offered one. The phone keeps playing the title itself; - a title with DRM, request signing, a live channel or music never uses
portable.
This is covered by Kino's tests with a fake resolver and was tried on one real Chromecast (a TV's built-in one): a direct H.264
file, a converted HLS with audio and subtitle renditions (seeking from the phone works) and a portable copy of an HEVC file all play.
DLNA was tried on one real LG webOS TV, which lists no HLS in its formats yet plays it: Kino sends it the HLS playlist as it is, and both a converted HLS with audio and subtitle renditions and a muxed portable copy reached playing, with the real duration and a position that advances (pause and resume from the phone work). The "continuous MPEG-TS" route Kino uses for a TV that cannot play HLS does not play on that TV, so keep an HLS answer for it. Not tried: sending a plain progressive file from the first byte (one attempt stalled at the TV), seeking from the TV, other renderers, and confirming the picture on the screen. Also untried: an app that survives the phone's
screen turning off.
What to expect¶
- Maybe no app is installed. Your plugin is not told. The person reads "Este contenido necesita una
aplicación externa que no tienes instalada." (or, when your manifest names the app with an
apk, is offered to download it). Say in your description that your plugin needs it, and give it a real fallback when you can: aurlyour own code can produce, withexternalkept to one of severalalternatives. - Only while the person plays. Never for a preload, a background refresh or a download: an externally-resolved title says it can only be played ("Este contenido lo abre una aplicación externa: solo se puede reproducir.").
- 120 seconds for the whole call, one hop only, DRM never.
- Every app is the person's choice, not yours. They can say no, pick another, or revoke later.
- You never learn which app handled it, or how. Either the stream plays, or
resolvefails like any other failure. - Offering the download. When your manifest's
externalResolverhas anapk(urlon a GitHub release asset or an archive.org file,sha256, optionallabel) and the app is missing, Kino shows a sheet: it can download it from GitHub, checks the file has exactly thatsha256(otherwise it is deleted and nothing is offered) and hands it to Android's installer, which asks the person as for any app. Kino does not check who signed it and has not reviewed it; the sheet says so. - Other ways to get the app.
externalResolvermay also say"fdroid": true(the samepackageis listed in F-Droid: Kino opens the F-Droid client for exactly that package, or its page on f-droid.org, or says what to search for) and/or"downloader": { "code": "..." }(3 to 10 digits: a code of the Downloader app that sideloads on a TV; Kino only shows it, with a button to open Downloader when it is installed, and installs nothing itself on that path). All three are optional and independent, Kino offers only what is declared for exactly thatpackage, and the sheet leads with the buttons on a phone and with the code on a TV. Be honest with your users: the official F-Droid client has no real Android TV support (it does not appear in the TV's launcher and some screens cannot be reached with a remote), so for a TV the Downloader code or theapkis the practical route. Kino has not verified a particular F-Droid client build against this link on a real device. - The app for a computer. If your resolver also runs on a computer,
externalResolvermay carry"desktop": { "windows": { "url": "...", "sha256": "..." }, "linux": { ... }, "macos": { ... } }: each a GitHub release asset (a zip, see "Desktop transport" in the resolver protocol) and thesha256its bytes must have. Kino on a computer reads only the entry for its own system and never yourapk; Kino on Android never readsdesktop. Same rules as theapk: Kino downloads it from GitHub, checks thesha256(otherwise it is deleted and nothing is installed) and has not reviewed what is in it. A system you leave out simply has no app offered.
Using a resolver from your plugin¶
- Manifest:
"apiVersion": 11,"externalResolve"incapabilitiesand, to name the app,externalResolver:
{
"apiVersion": 11,
"capabilities": ["search", "home", "resolve", "externalResolve"],
"externalResolver": {
"package": "com.example.resolver",
"apk": { "url": "https://github.com/example/resolver/releases/download/v1.0.0/resolver.apk", "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "label": "My Resolver" }
}
}
hosts is still the set of sites your code reaches (your catalog), not what the resolver reaches. A
manifest must name at least one, even if the plugin does no networking.
2. resolve(ref) answers the hand-off:
export async function resolve(ref) {
const entry = CATALOG[ref];
if (!entry) throw kino.error("not_found", "ya no está");
return { external: { protocol: "my-protocol", ref: entry.reference } }; // add resolver: "com.example.resolver" to force that app
}
- Several copies (qualities, releases): as
alternatives, each{ label, ref }lazy copy resolved by your ownresolveand answeringexternalagain, or an entry{ external, label }directly (labelled and lazy copies). The person moves to the next copy when one fails. - Test offline with the kit:
node sdk/run.mjs . resolve <ref>applies Kino's output rules, so you see whether yourexternalsurvives (it is ignored withoutapiVersion11 and the capability) and howmediaandportablecome out. The kit cannot run a resolver app: to see the whole hand-off you need the app installed on a device (Test it locally).
Building a resolver¶
The other side is an Android app with one bound service. The contract is small:
package com.arkiv.player.resolver.contract;
interface IExternalResolver {
/** protocol: 1..64 chars [a-z0-9._-]+. ref: 1..2048 chars, opaque. At most one resolve() in flight per binding. */
oneway void resolve(String protocol, String ref, IExternalResolverCallback callback);
/** Best effort: whatever resolve() is running ends with onError("cancelled", ...). */
oneway void cancel();
}
interface IExternalResolverCallback {
/** Zero or more times. percent: -1 = indeterminate, else 0..100. message: shown verbatim, trusted only as display text. */
oneway void onProgress(int percent, String message);
/** Exactly one of onResult/onError ends a resolve() call. */
oneway void onResult(String resultJson);
/** code: one of "unavailable","timeout","cancelled","unsupported","bad_response","other". */
oneway void onError(String code, String message);
}
Declare the service so Kino finds it:
<service android:name=".MyResolverService" android:exported="true" android:foregroundServiceType="dataSync">
<intent-filter><action android:name="com.arkiv.player.action.RESOLVE_EXTERNAL" /></intent-filter>
<meta-data android:name="com.arkiv.player.meta.RESOLVER_PROTOCOLS" android:value="my-protocol" />
</service>
In short: implement resolve(protocol, ref, callback) off the binder thread (answer fast with progress, end with
exactly one onResult or onError), keep your server alive in a foreground service while the player reads,
answer Range and HEAD, put an unguessable token in your URLs, answer an unservable request with an HTTP
error and a readable X-Resolver-Error: <code>; <message>, and return the same URL when the same content is
resolved again (a player that still holds the old URL must not be left on a dead one). The protocol is open:
nothing checks who signed your app, and anyone may implement it. The full wire-level contract, with every limit,
is resolver-contract/PROTOCOL.md in Kino's source repository.
Security model¶
- The protocol is open: nothing checks who signed the other app, and anyone may implement it. The person's per-app consent, and Android's own install prompt, are the trust decisions.
- Kino sends the app only
protocolandref, and only after consent. - The app's text reaches the screen only as one cleaned, bounded line; its codes are whitelisted.
- Its URLs pass the plugin-answer checks; the only local address ever accepted is the one loopback origin of that answer, for that playback, for the first request (never as a redirect target).
- DRM and chains are refused; a failure is never retried once the app has explained it.
FAQ¶
Can my plugin check that a resolver is installed? No. Kino tells the person; your plugin is not told. Ship a fallback.
Does the resolver see my plugin's settings or secrets? No. It receives protocol and ref, nothing else.
Can one ref serve several apps? Only by convention: ref is yours and the protocol name is a string you
share with whoever builds the app. Name the app in externalResolver when only one will do.
Why is the url allowed to be http://127.0.0.1:...? Because an app that serves the content from the
device has to; it is accepted for that one answer, with an unguessable path token in it, and for nothing else.
Will it cast? Through Kino's proxy: Chromecast and DLNA yes for an HLS answer (each tried on one real receiver) (above).
Where do I see what media said? In Kino's log, as a one-line summary. A screen for it is not built yet.