opencream TV

One connection, 70 MB of guide data and Chromium 63: building opencream.tv

How I built a home screen and IPTV player for Samsung TVs that starts channels in about a second, runs on a 2019 browser engine and never checks a stream before playing it.

Matthias, . About 12 minutes.

opencream.tv is a free, open-source home screen for Samsung TVs from 2019 on, with a player for your own Xtream Codes IPTV login built in. It's GPL-3.0 and has no account and no analytics. It includes no channels: you bring a service you already pay for.

I built it because the home screen on my 2023 TV is mostly ads and rows I never asked for. My kids play on the Xbox, I watch YouTube and Netflix, and I wanted one calm screen for all of it, with live TV on the same screen instead of in a separate paid player app. Most of the code was written with Claude Code, and I'll get to what that was like at the end.

You can click through the real app in your browser (fictional channels), read the code on GitHub, or install it on your TV.

The opencream TV home screen with the app dock: Live TV, Movies, Series, streaming apps and console tiles.
The home screen this all started with.

A web app on a TV, and the Chromium 63 floor

Apps on Samsung TVs are web apps: a config.xml, some HTML and JavaScript, running in the TV's own web engine. opencream.tv declares required_version="5.0", which means Tizen 5.0 and up, the sets Samsung sold from 2019.

The catch is that a 2019 set runs Chromium 63, from late 2017. Newer TVs run much newer engines, but the app has to work on the oldest one it claims. So the code is plain ES5: no arrow functions, no let or const, no async, no template strings. There is no build step either. What's in the repo is what runs on the TV, and anyone can read it without a toolchain.

Before writing much, I checked every browser API the app uses against Chromium 63. Streaming fetch with a body reader, TextDecoder, String.prototype.normalize and IndexedDB were all there. The one real gap was AbortController, which arrived in Chrome 66.

A small compat.js covers it. It offers a canceller() and a fetchTimeout(). Where AbortController exists they are thin wrappers and a request really gets cancelled. On an old TV, the fetch races a timeout instead: the request finishes in the background and nobody reads it, but the caller gets its rejection on time. For the guide download, which is the one long request, reader.cancel() stops the stream either way.

To be honest about it: my TV has AbortController, so the fallback path has never run on a real old TV. Nobody with a 2019 or 2020 set has reported back yet. If you have one, a compatibility report would tell me whether it holds up.

AVPlay: let the TV's hardware do the work

On the TV, video goes through AVPlay, Samsung's API for the built-in hardware player. It decodes in hardware and plays raw MPEG-TS live streams and MKV files that a <video> element would refuse. In the browser demo a plain <video> stands in.

The lifecycle is short: open the URL, set the display rectangle to the full 1920 by 1080, attach the listeners, prepare asynchronously, then play (with a seek first when you resume a film). Stopping cleanly means checking the player's state before calling stop and close, because calling them in the wrong state throws.

The result is that a channel starts in about a second on my QN90C, which is what made the whole project feel worth it.

Audio and subtitle tracks come from the player too (getTotalTrackInfo(), switched with setSelectTrack), so the menu during playback lists what the stream really carries.

One more guard came out of a bad afternoon, which I'll describe below: if a live stream "ends" twice within 15 seconds of starting, the app treats it as an error and moves on, instead of reconnecting in a loop. A stream that ends right away is usually a placeholder from a server that won't serve you, or a dead channel.

The live TV guide over a playing channel, with now and next.
The guide over the picture. The channel is one of the demo's made-up ones.
The audio and subtitles menu during playback.
Audio and subtitle tracks come straight from the TV's player.

Accounts that allow one connection

Many IPTV subscriptions allow one connection at a time. The test account I develop against does, and that shaped more of the code than anything else.

The trap is innocent-looking. An app that checks a stream URL before handing it to the player, with a HEAD request or a quick probe, takes the one slot itself. The player then gets refused with HTTP 460, which on the TV shows up as an InvalidAccessError. The same happens if you test a stream on your laptop while the TV is playing.

So the rule in the code is: hand the provider's URL straight to AVPlay, let the player follow the redirect, and never probe. There's a comment saying so right above that line, with the date I found out.

That makes failover harder, because you can't ask a server whether it works without using your slot. The app works it out from the player instead. You can enter more than one server address. If the player fails on one, the app tries the next. If none of them plays the channel, the channel itself is down, so the app goes back to the first server and says "This channel is not available right now". After a failover it returns to the first server, usually the fastest, once that server has had five minutes to recover.

Two bugs here cost me an evening each. Zapping in the middle of a failover used to leave the app stuck on a server that refuses video. And re-entering the login in Settings used to drop the separate list of video servers, so playback went to servers that only send a two-second "restricted" placeholder. Both are fixed, and both are now comments next to the code they broke.

Getting my own TV blocked for an afternoon

On 31 October the test account's video servers stopped answering my TV, and only my TV, for about four and a half hours. My laptop on the same connection was fine. It lifted by itself. I never found out exactly what triggered it, but I'm fairly sure it was me.

Two things were happening at once. The reconnect loop I described above was hammering away at streams that ended instantly. And the app was rebuilding its search index far too often. The reason was small and stupid: a settings row that only changed the look was built as a "toggle", and every toggle invalidated the search index. A full rebuild means hundreds of list requests to the provider.

The fixes are now written down in the repo as "rules learned the hard way":

  • Settings that only change the look are "choice" rows, never toggles.
  • Never change the version part of the index key. It rebuilds every list.
  • Index builds go one category at a time, with a 250 ms pause between categories, or 1.5 s while something is playing.
  • If every server fails during a build, stop the whole build, instead of knocking on every server for hundreds of categories.

The general lesson: rate limits and anti-flood rules are part of the API, even when nobody writes them down. On a TV you can't see a 429 coming, you just find that your channels stopped working.

Searching 31,000 programmes on a TV

Search was the feature I wanted most and the one that looked impossible. The provider has no search API, and the full lists are far too big to download for each query. So the TV keeps its own index in IndexedDB: channels are refreshed every hour (event channels get renamed daily), films and series once a day, and the programme guide every eight hours.

The guide is the heavy part. On the test account it's about 70 MB of XMLTV for roughly 8,000 channels, covering about 24 hours ahead. Loading that into memory as one string on a TV is not an option.

So the TV stream-parses it: fetch, then body.getReader(), then a TextDecoder in streaming mode. As chunks arrive, the parser scans the buffer for </programme>, cuts out each complete block, and keeps it only if its channel is one you actually have and the programme hasn't ended yet. If the buffer ever grows past 1 MB without a closing tag, the junk gets dropped, because no real programme is that long. The first byte has 20 seconds to arrive and the whole download 30 minutes.

For each programme the index keeps the title, a normalised copy of the title, the channel's guide id, start and stop, and the first 300 characters of the description.

The search itself is simple on purpose. Every word you type must match the start of a word in the title, after both sides are lowercased and run through NFD normalisation with the accents stripped. Results come in a fixed order: channels first, then guide programmes (title matches before description matches, on now or starting soonest first), then films, then series. HD, FHD and 4K copies of the same channel share one guide id, so a programme shows up once.

On my QN90C that's about 31,000 programmes, and a search takes 0.1 to 0.2 seconds. I don't know yet what a 2019 set does with it, and I'm not going to claim it until someone tells me. Partial results become searchable while the index builds, every ten categories, so the first search after install doesn't wait for the whole thing.

Search results for kite across a channel, guide programmes, a film and a series.
One search across channels, the guide, films and series. All channels in these pictures are fictional.

Installing without a store, and letting an agent do it

Samsung's store doesn't take apps like this, so installing means Developer Mode on the TV and a signed package sent from a computer on the same network. That's the weakest part of the whole project, and I've tried to make it as painless as I can.

The easy path is Apps2Samsung, the community installer. The public .wgt package is unsigned on purpose, and Apps2Samsung signs it with your own certificate. opencream.tv was added to its catalog on 2 November. Every package in that catalog gets a security scan, and the report lists every host the code talks to. It takes about 20 minutes.

The other path is a coding agent. The repo has an AGENTS.md that walks Claude Code or Codex through the install: check the computer, have you turn on Developer Mode (Apps, then 1 2 3 4 5 on the remote, then your computer's IP), find the TV on port 26101, install Samsung's command-line tools, have you sign in to create a Samsung certificate for your TV, then build and install.

The rules at the top of that file matter more than the steps. The agent must never print, log, commit or paste your IPTV login. Before it asks for the login, it has to tell you that whatever you type passes through your AI provider, and that you can skip it and type it on the TV instead. And it may not install anything without saying what it is and where it comes from.

Before every public build a small script also scans the package to make sure no household config ends up in it. The test login has lived on the same disk as the code the whole time, and I didn't want to trust my memory with that.

Working with Claude Code on real hardware

Claude Code wrote most of this app. It kept to the ES5 rule, and it drove the TV directly: building, installing, reading logs from a small log server on my Mac, and pressing remote keys over the network to test a flow.

What I had to catch was the kind of thing you only learn from the TV itself. The stream probe looked like good practice and broke playback. The toggle that rebuilt everything looked harmless. And anything visual had to be judged on the TV from the sofa, not from a screenshot.

The habit that helped most: every failure becomes a dated rule, either in the docs or as a comment next to the code it protects. The agent reads those on the next session, and so does the next person who opens the repo.

What's not done

  • The Home button. The remote's Home button still opens Samsung's home. On Tizen 8, the only project I found that remaps it needs root first, and I won't ship a home screen that asks you to root your TV. The workaround: set the TV to start in the last app you used, and put opencream.tv first in Samsung's app row. Then Home and OK gets you back.
  • M3U playlists. Xtream Codes only for now. M3U is next.
  • More TVs. It's tested on exactly one TV, a 2023 QN90C on Tizen 8.

That last one is where you can help. If you own a Samsung TV from any year since 2019, a compatibility report is worth more to me than a star. The compatibility page lists what's confirmed so far.


Next up are M3U support and more tested TVs. The install guide and the code are both public. opencream.tv is made by opencream.ai, my small studio in France. It's free and stays free.

Try the demo Install guide