Quiblo — a free, open source IPTV player for Android and Android TV

Orientation

What Quiblo is, what it deliberately is not, why we licensed it the way we did, and what we learned building it. Start here if you have never seen it before.

• What Quiblo isA free, open-source Android IPTV client that plays playlists you supply yourself.
• Licence and legal postureWhy GPLv3 and not GPLv2 or AGPL, and the position we take on content.
• Terms of useWhat Quiblo is, what you are responsible for, and where your data goes. The page the app links to.
• Scope and principlesWhat we decided once and stopped relitigating, and the rules the code is held to.
• What we learnedThree episodes that left permanent marks on the code, and why the guards you will find are there.

Using Quiblo

Installing it, pointing it at a source, and what every screen and setting actually does. Written for someone holding the app, not reading the code.

• DownloadsWhich APK to take, how to check it is the one we published, and what a pre-release means.
• Release notesEvery version of Quiblo and what it added, newest first — including the alpha that is not on the releases page yet.
• Getting startedInstall the APK, add a playlist or an account, and start watching.
• Who is watchingLocal profiles: separate favourites and resume points, a guest that leaves nothing behind, and no PIN.
• The phone appBrowsing, searching, favourites, the player and its gestures.
• The television appA ten-foot interface driven by a remote: the focus model, the key maps, the player, and what differs from the phone.
• Settings referenceEvery setting, what it changes, and where it is stored.
• When something looks wrongThe failures we see most, and how to tell an app bug from a provider one.

Architecture

How the code is arranged and why. The layering, the module map, the path data takes from a provider to the screen, and the four subsystems worth understanding on their own.

• OverviewLayers, the dependency rule, and the build-time check that makes a second frontend cheap.
• Module referenceEvery Gradle module, what belongs in it, and what must not.
• How data reaches the screenThe browse path in detail, and the two performance defects that lived in it.
• SearchThe one question that ignores the division the rest of the app is built on, and why it asks it once.
• The databaseEleven schema versions, why favourites are their own table, and how identity survives a refresh.
• The source layerThe protocol abstraction, the M3U parser, the Xtream client, and the guards that keep an account alive.
• The playerMedia3 behind an interface, what that interface buys, and the stutter that came from one retry policy.
• The television frontendHow :app-tv is put together, the focus defects that shaped it, and the shake that took five attempts.
• Metadata and artworkTwo optional third-party features, and the rules that keep them from becoming a liability.

Engineering practice

How we build, test, measure, accept and release — and the conventions we hold a change to.

• Build and toolingGradle convention plugins, the quality gates, and the one command that matters.
• TestingWhat is tested, what deliberately is not, and how to write a test that holds.
• PerformanceWhat has been measured, on what, and the numbers worth comparing against.
• AcceptanceBinary criteria, a definition of done, and a sweep that records what was actually observed.
• ReleasingA merge to main is a release: what that automates, what it refuses to automate, and the trap that makes a test build unshippable.
• ContributingBranching, commits, and the standard a change is held to.
• GlossaryThe vocabulary, in one place.

How this was built

The method rather than the product: what an agent did well here, what it got wrong, and what caught each mistake. Written from the record, so every claim can be checked in the repository.

• How this was builtMost of this code was written by a model. Every serious defect was caught by something else — here is the list, and where to check it.
• Working with agents on this codebaseThe practical half: what gets written down, what belongs in CI instead, and the failure modes to expect.
• What it costNineteen sessions, ten days, and the number nobody expects: fresh input was 38,307 tokens against 2.71 billion cache reads.

Code reference

A package-by-package reference: 13 packages and 111 documented types, each with what it is for and what it must not be used for. Written by hand rather than generated, because the useful half of a reference is the half a generator cannot reach.

• Packages and classes Start here to find a class, or read it straight through in dependency order.

Common questions

Is Quiblo free?

Yes. Quiblo is free software under the GPLv3, with no paid tier, no advertising and nothing paywalled. Every feature is in the build everybody gets.

Does Quiblo come with channels?

No. Quiblo ships with no channels, no films and no way to find any, and this project will not help you find a provider. It is a player, in the same category as VLC: you supply an M3U playlist or an Xtream Codes account that you already have.

What playlists does Quiblo support?

M3U and M3U8 playlists, either from a URL or a file on the device, and Xtream Codes accounts. It plays HLS, DASH, raw MPEG-TS and progressive MP4 or MKV.

Does Quiblo work on Android TV?

Yes. There is a separate television build with its own interface driven entirely by a remote, alongside the phone and tablet build. Both are in every release.

Does Quiblo track me?

No. There is no account, no telemetry and no server of ours anywhere in the path. Quiblo makes no network request to any host you did not configure yourself.

Where do I download Quiblo?

From the releases page on GitHub. Each release carries two APKs — one for phones and tablets, one for Android TV and Google TV — and they are signed with the same key.