Platform tour · self-hosted IPTV, end to end
A high-performance native Kotlin player for Android TV — multi-playlist, live TV with a full EPG, movies and series — now joined by native Android and iOS mobile apps, a browser player as the no-install alternative, owner and staff dashboards, real Stripe checkout for licenses, an API that treats every device as a cryptographic identity, and a stream relay that reaches providers the datacenter can't. Deployed with one command onto a Cloudflare-edge + single-VPS stack with zero inbound ports.
Platforms
Architecture
Viewers enter through Cloudflare and a tunnel — the VPS never exposes a port. Content leaves through the relay's egress ladder, which picks the cheapest path a provider will actually answer: the VPS itself, a named proxy, or the customer's own TV acting as a courier.
User journey
The whole activation funnel is built to survive a non-technical customer on a hotel Wi-Fi — every step recovers, refreshes, or explains itself.
The landing page walks the TV install: free Downloader app, code
5210303, and the signed 4.8 MB APK arrives from the CDN. In a
browser? web.sarmaplayer.com — nothing to install at all.
The TV mints its hardware identity key and bootstraps in one round-trip: a device ID, a running trial entitlement, and a pairing code — before the user touches a button.
Scan the QR or type the short SP- code into the phone dashboard. The TV
polls until claimed and auto-mints a fresh code before the old one can expire —
nobody ever stares at a dead code.
Paste an Xtream login or M3U link. The server ingests and normalizes the catalog, and a TV guide is matched and attached automatically the moment the playlist is created.
D-pad zapping with now/next, a full EPG guide, Movies and Series with resume — streaming direct from the provider or through the relay, whichever policy says.
Trial ends → an activation code unlocks a license. New releases surface as a one-press self-update. And if setup ever fails, the diagnostics card names the exact fault and offers the fix — the same screen that let us repair a customer's TV from two photos.
The surfaces
Every app carries its own generated changelog and version tags, cut from conventional commits by the platform's own CLI.
Kotlin · Jetpack Compose TV · Media3 · minSdk 21 → SDK 35
Kotlin · Jetpack Compose · Media3 · Room · Play internal track
Swift · SwiftUI · AVPlayer + VLCKit dual engine · TestFlight
asc
React · Vite · Tailwind · hls.js + mpegts.js · i18next
Hono 4 · Drizzle ORM · Zod 4 · Better Auth · BullMQ · jose
Hono · undici ProxyAgent · ffmpeg remux · jose
eg claim
React SPA · Cloudflare Pages · sarmaplayer.com apex
React SPA · staff-only · Cloudflare Pages
TypeScript · zero runtime deps · local-only signing
sarma deploy production — all five services, watched and
health-verified
sarma release — bump, sign, upload, publish manifest, purge CDN, tag
sarma changelog — per-app versions and changelogs from conventional
commits
Pure-JVM core · OkHttp · kotlinx.serialization
Ingress · content pipeline
Xtream and M3U playlists are parsed server-side only — untrusted input never reaches a client. Normalized live/VOD/series catalogs are versioned and published; devices poll their active playlist's manifest.
When a provider geo-blocks the server, ingestion climbs a ladder ending with device-assisted fetch: the customer's own TV couriers the provider payload home over its residential connection.
BullMQ schedulers keep playlists fresh; a one-press refresh re-syncs list + guide together, with per-device auto-refresh cadence settings.
EPG platform
Provider EPG is unreliable, regional, and often simply missing — so SarmaPlayer runs its own canonical guide platform and maps playlists onto it.
Multi-source by design: public and BYO XMLTV feeds, curated per-region source sets (a seeded Balkan lineup of ~1,600 canonical channels from 11 feeds), plus a scraper engine that turns listing sites without any feed into XMLTV — same pipeline downstream, adapters per site.
Feeds normalize into one canonical channel space with priority ordering between
overlapping sources; ingestion runs as scheduled BullMQ workers with per-source
staleness tracking, operable from the CLI (sarma epg).
A matcher ladder binds messy playlist channels to canonical ones: exact
tvg-id first, then normalized fuzzy name matching —
179 channels auto-mapped on the first real customer playlist. Guides attach to
new playlists automatically at creation; owners can rebind per channel.
Schedulers keep every source current and every playlist's guide re-synced with it; devices get inline now / next on zap and a full grid guide, refreshed together with the playlist.
Egress · the streaming path
By default players stream straight from the provider — the platform stays out of the data path entirely.
Per device or playlist, streams route through the relay: credentials stay server-side, browsers get CORS-clean playback, and ffmpeg remuxes containers the web can't chew.
Operator-set, resolved device → playlist → default, and stamped into the signed stream token. Unknown proxy names log once and fall back to direct — config drift never kills a stream.
Identity & entitlements
A non-exportable EC P-256 key minted in the TV's secure hardware, with a defensive ladder (StrongBox → TEE named-curve → key-size → encrypted software key) so broken OEM crypto can never brick onboarding.
Devices prove possession via challenge → signed session (DPoP-style). Owners get manage sessions; browser accounts (email OTP / Google) auto-provision web devices. Pairing codes are short-lived and one-use.
Trials and licenses are ES256-signed certificates verified offline against the
platform JWKS — playback is fail-closed, and /ready refuses
deploys that can't serve keys.
A real Stripe Checkout flow sells a perpetual license — on success the license activates instantly on the device that paid, no polling or manual step.
Field-tested, remotely. A customer's Fire TV shipped a ROM missing two separate crypto APIs. The diagnostics card put the exact fault on screen, the customer sent two photos, and the self-update escape hatch delivered two targeted releases — device unbricked the same day, no remote access, no reinstall.
Operations
sarma deploy production builds and publishes API, relay and all three
SPAs, watches Coolify to completion, and health-verifies each surface. Android ships
via sarma release: signed build, R2 upload, manifest publish, CDN purge,
tag — then devices self-update.
60-second liveness heartbeats feed the operator census; devices report platform, distribution and app version at bootstrap. The onboarding failure card doubles as remote telemetry a customer can read aloud.
Develop-first branching with gated promotions, CI on every PR, migrations as an explicit pre-boot deploy step, nightly Postgres dumps to R2, and per-app changelogs generated from the commit history itself.
Tech index