Why I moved a TV app's source contract into JavaScript plugins on QuickJS

Yonto Player talks to a media server, or to a folder, through one interface: ContentSourceAdapter. The rule itself is covered in the opening post of the series. This…

Yonto Player talks to a media server, or to a folder, through one interface: ContentSourceAdapter. The rule itself is covered in the opening post of the series. This one is about what sits behind the interface, and how it changed. The short version is that the source contract started out as an HTTP API, moved into the app as JavaScript plugins, and is now the way every Jellyfin, Plex and Emby source works.

I will say why, what a plugin looks like, and what running JavaScript inside a TV app costs. It started as an HTTP contract The first idea was a contract in JSON. A source is anything that can answer a few questions: what categories do you have, what is in this one, tell me about this title, search for this.

That is written down as contracts/content-source-http.md in the plugins repo, with schemas beside it, and an HTTP adapter in the app speaks it to a hosted service. It works, and it is still there for anyone who wants to run a service of their own. But it has a cost for the most common case.

To read a Jellyfin server I would need a service in the middle that talks Jellyfin on one side and my contract on the other, and someone has to run it. Every field a media server renames becomes a fix in that service and then a deployment. The idea that changed it: keep the contract's JSON shapes as the one definition, and make the transport an implementation detail. HTTPS to a service is one transport.

A call into a JavaScript engine inside the app is another. The code that turns the JSON into the app's titles, details and playback options is shared and knows about neither. Once that was true, the sources that model somebody else's system had no reason to be Kotlin. A Jellyfin or Emby server has its own idea of what an item is, and that idea changes on the server's schedule, not mine.