CloudStream plugins¶
Kino 0.9.54. Kino can install the plugins of a CloudStream repository without anyone writing a Kino plugin: each plugin the person picks is converted, on the device, into a Kino plugin that talks to a complement, a separate app where the CloudStream code runs. This page covers how people add them, how each part maps, and where it stops. It is useful if you maintain a CloudStream repository, or want to know why a converted plugin behaves differently from a hand-written one. You need none of it to write your own plugin.
How people add them¶
- In Ajustes ▸ Plugins, "Agregar plugin", the person pastes the repository's address: the URL of its
repo.json(an object withpluginLists) or of aplugins.json(the plugin list itself). Thecloudstreamrepo://…andhttps://cs.repo/?…links repositories are shared with work too (Kino reduces them to thehttpsURL of the JSON), and so does the repository's short code. - The address must be
https, on a public host (neverhttp, a local IP,localhostor a home network name), with no user name or password, end in.jsonand be at most 500 characters. If it is not a CloudStream repository, Kino tries Nuvio and a Kino plugin, as with any pasted address. - Kino reads the
repo.json(up to 1 MB, at most 10pluginLists; one broken list does not sink the others) and opens a picker with its plugins (up to 2000): name, types, language, version and author, with filters by type (Película, Serie, Anime, En vivo) and by language, and a "Buscar por nombre" field. Installable plugins come first, then the ones in Spanish (es, anyes-*ores_*, and alsomx,latandlatino, as many repositories write them), then by name. - A plugin that cannot be installed is dimmed with the reason:
- "Usa torrents: Kino no los permite": any plugin that declares the
Torrenttype among itstvTypes, even when it also lists movies or series. It is never installed or offered as a source, and an installed one that starts declaring it is switched off with that reason instead of being updated. - "Desactivado por su autor":
status: 0in the list. - "Dirección no válida": an
internalNameoutside^[A-Za-z0-9._-]{1,64}$or aurlthat is not publichttps.
- "Usa torrents: Kino no los permite": any plugin that declares the
- A plugin marked
NSFWintvTypesinstalls only behind the app's 18+ code, like an adult Stremio addon: while that code is locked the picker does not offer it, and everything it shows is marked 18+. - "Agregar" downloads the
.cs3, hands it to the complement to learn which sources it registers, generates the Kino plugin and opens the usual consent sheet. Each CloudStream plugin becomes its own Kino plugin, in Ajustes ▸ Plugins like any other, and the repository stays in the "Repositorios de CloudStream" list under its own name (therepo.json'sname). "Quitar" on a repository asks first and does not uninstall its plugins: they stay and keep updating.
With a short code¶
In the same box, the person can type a repository's short code, as in CloudStream: only letters,
digits, _, - and ! (at most 64 characters; an address is never a code). A code that starts with
! is a py.md link (!abc is https://py.md/abc); any other is a cutt.ly link (abc is
https://cutt.ly/abc).
- Kino asks the shortener once, with no cookies or credentials and 10 s at most, and does not follow the redirect: it only reads where it points. No other page of the shortener is opened.
- That target is checked like an address pasted by hand (also when it is a
cloudstreamrepo://link): it must be a publichttpsURL, with no user name or password, ending in.json. If not, "Ese código lleva a una dirección que Kino no abre…" ("That code leads to an address Kino doesn't open: only https repositories outside the home network."). - Before reading anything from the repository, Kino shows the address the code leads to so the person confirms it: "¿Abrir este repositorio?" ("Open this repository?"), the URL, and "Ábrelo solo si confías en quien te pasó el código." ("Open it only if you trust whoever gave you the code."). Only "Abrir" ("Open") goes on as in step 3.
- An unknown code says "That code doesn't lead to any CloudStream repository. Check that it's spelled right."; offline, or when the shortener fails, "Couldn't look up the code. Check your connection and try again." (each in the app's language).
- Neither the code nor its target goes to the logs.
The complement¶
CloudStream code never runs inside Kino. It runs in a separate app, the CloudStream complement, which has no internet permission: everything a plugin asks of the network is carried out by Kino, which decides what is allowed. The first time, Kino offers to install it ("Instalar complemento"): it downloads it for the person from the same servers as its own updates, checks that it is Kino's copy (package, version, sha256 and signature), and the system asks for permission to install it. Kino also says when a new version is out ("Actualizar complemento").
When it is missing, outdated, or the installed one is not Kino's, the player, the source search and the episode list do not say "no está disponible": they say what is wrong ("Necesitas el complemento de CloudStream", "Actualiza el complemento de CloudStream", "El complemento instalado no es el de Kino") with a button that opens the complement sheet.
A CloudStream plugin's requests:
- go to any public host over
https, on every redirect hop (at most 10); neverhttp, never an invalid certificate, never the local network. That is why the consent sheet says so in red, like a plugin with"streamHosts": "any"; - are capped per operation: 250 requests, a 1 MB request body and a 5 MB response; 15 s per request by default, 30 s at most;
- carry no credentials from one origin to another;
- if the plugin opens a hidden page (its WebView), only during a call the person started, under the
same rules as the hidden browser:
https, never the local network.
The repository's address never goes into logs, errors or telemetry: the plugin's id is a hash.
What the conversion builds¶
Each installed plugin is a generated Kino plugin: a manifest plus one JavaScript adapter shared by all,
whose calls go to kino.cloudstream (only these generated plugins have it;
a hand-written one never does). The generated manifest:
id:cloudstream-<name>-<hash>(at most 40 characters), stable across devices, derived from the repository and theinternalName.version:1.<converter revision>.<the entry's version>(the revision is 4 today, so1.4.N): it moves when the repository entry or Kino's adapter changes.apiVersion8,"streamHosts": "any"and the capabilitiessearch,episodes,resolveanddownload, plushomeandbrowsewhen a source has a main page, andchannelswhen one listsLive.- The entry's description, ending in "(CloudStream,
)".
How each part maps:
| CloudStream | Kino |
|---|---|
Each source's search |
Kino's search (a source that lists only Live is not asked: its channels are searched in En vivo). When one source fails the others go on. |
Main page (mainPage), up to 12 sections per source |
Rows on Home and in the plugin's section. Each row of a section is its own row with its own "Ver más", which pages that row only. A broken section never hides the others. |
load |
The title page: synopsis (plot), poster, backdrop, genres (tags), year, rating and runtime, through details for a movie and episodes().series for a series. |
The title's ids (imdb, tmdb, mal, anilist, kitsu) |
Handed to Kino, which describes the title with TMDB, AniList and the person's meta plugins, like any other. Without ids, Kino searches TMDB by name and year (with kino.tmdb) and takes an id only on one exact match of the same year. An 18+ title is never searched. |
Types Movie, AnimeMovie, Documentary |
movie |
TvSeries, Anime, OVA, Cartoon, AsianDrama, Others, or no type |
series |
Music, Audio |
music (apiVersion 8, see Music and podcasts) |
Podcast, AudioBook |
podcast |
Live |
En vivo channels: each main page section is a category, with paging and search. |
NSFW |
A movie marked 18+, only in an NSFW plugin; any other plugin drops it. |
| Any other type | Dropped. |
loadLinks |
The Stream: only public https addresses of type VIDEO, M3U8 or DASH (never torrents or magnets), without repeats, ranked by quality (at equal quality, HLS first). The first one plays and up to 8 more become alternatives, named in the Servidor menu. Up to 20 headers per link and 30 subtitles. |
A title listed as a movie that has a single episode (an NSFW title, a mislabelled series) plays its
first one. The adapter keeps the load answer of the last few titles for a few minutes, so the page
and the "Reproducir" right after it cost one call.
A plugin's settings¶
Some CloudStream plugins bring a settings screen of their own (the one the plugin's gear opens in CloudStream). In Kino it is in Ajustes ▸ Plugins, the plugin's "Gestionar" ▸ "Ajustes del plugin" ("Plugin settings"):
- Only on a phone or a tablet. On a TV the entry does not appear.
- Only when the complement said, while loading the installed version, that the plugin has settings, and while the complement is ready.
- The screen is the plugin's own: the complement shows it over Kino, one at a time ("Some settings are already open"). When it is saved, Kino reads again what it shows from that plugin.
- The values live in the plugin's storage (
kino.storage), so they sync to the person's other devices like the rest of its state. - When something goes wrong, the plugin's card says so: "This plugin's settings failed", "The plugin didn't answer", "This plugin isn't compatible with the companion" or "Couldn't open the settings. Try again".
Limits that differ from a hand-written plugin¶
- List calls (
search,home,browse,episodes,details) get 45 s (timeoutsMs.cloudstreamListincontract.json) instead of the usual 15 or 20 s: they go through the complement, which may start cold, and then the site. - The
.cs3is downloaded up to 20 MB and, when the repository publishesfileHash(sha256-<64 hex>), it must match: otherwise "El archivo del plugin no coincide con el del repositorio". - A plugin the complement cannot load, or that brings no source Kino can use, is not installed, and nothing is left half-done.
Updates¶
Kino reads the repository again on every update check. When the entry has the same version, the same
fileHash (when there is one) and the converter is the same, there is nothing to do; otherwise the whole
install runs again with the new .cs3 and applies, or waits for the person's approval when it reaches
further, like any update. Also:
status: 0switches the installed plugin off with "Desactivado por su autor".- An entry that starts declaring
Torrentswitches it off with "Usa torrents: Kino no los permite"; it is never updated into. - When the repository no longer lists the plugin (or cannot be read), the installed version keeps working with the adapter it was installed with.
On the person's other devices¶
The repository list and the installed plugins sync both ways, like any plugin. What does not travel is
the file: each device downloads its own copy of the .cs3 from the repository, and the receiving
device waits until it has the complement to install it.
For CloudStream repository maintainers¶
- Publish everything over
httpson a public host: therepo.json, eachplugins.json, each.cs3and itsiconUrl. None of it may be onhttpor a local IP. - Declare
tvTypeshonestly: Kino uses them to filter, to decide what goes to Home and what to En vivo, and to refuse. A singleTorrentkeeps the whole plugin out, even when it also has movies or series;NSFWputs it behind the 18+ code. - Set the plugin's
language: the picker filters by language and puts Spanish first (es,es-MX,es-419,mx,latorlatinocount as Spanish). - Publish
fileHash(sha256-…) and raiseversionon every change: that is what Kino compares to find an update. - When you can, give the title's ids in
load(IMDb, TMDB, MAL, AniList, Kitsu): with them Kino shows TMDB's and AniList's synopsis, cast and score without guessing. - Return
VIDEO,M3U8orDASHlinks with aqualityand a clearname: it is their label in the Servidor menu. - Use
status: 0to withdraw a plugin: it is switched off on the devices that already have it. - You can publish a cutt.ly short code for your repository (or a py.md one, typed with a
leading
!): its redirect must lead straight to yourrepo.json'shttpsURL (or to acloudstreamrepo://link), because Kino never follows a second redirect of the shortener. - If your plugin has a settings screen, people open it in Kino from a phone or a tablet, never from a TV: make the plugin work with its default values.