Leica Florian Robert

<< Back to projects

TvIt — case study

Role: Concept and development. Year: 2022.

Website: tvit.leicaflorianrobert.dev

A personal project born from a need of my own: an IPTV list of the free-to-air Italian TV channels, read from the broadcasters' own sources, with the TV guide. To watch with any player or straight in the browser.

You are viewing this case study with the Legacy engine. To see it as it was designed, enable native rendering below.

A list that didn't exist

It all started in the living room. I watched TV with an Nvidia Shield TV, an Android box, and an IPTV app: all I needed was a list of Italian channels that worked. The ones I found stopped working after a few days, or never worked at all.

Unable to find a reliable one, I decided to write it myself.

No private content: only the channels the broadcasters already stream publicly on their websites.

From hometv to TvIt

The first version, in 2019, was called hometv and was written in TypeScript. It did its job, but over time the special cases multiplied: channels changing address, sources answering in different ways, checks to repeat every night.

In 2022 I rewrote it from scratch in Laravel: faster, and with queues, job scheduling, an HTTP client and tests out of the box, exactly what I needed to handle every exception properly. That's how TvIt was born.

How the broadcasters do it

At first I knew nothing about how a live TV stream works. To find out I did a bit of reverse engineering: I opened the broadcasters' websites with the browser's developer tools and followed, one by one, the requests of their players.

I found out that the video address isn't in the page. The player first asks a broadcaster's service where the live stream is, and gets a temporary address, with a token that expires shortly, pointing to the CDN that serves the video. The video itself isn't a single file but an .m3u8 playlist of small segments a few seconds long, which the player downloads one after the other (HLS).

Once I understood the mechanism, I replicated it. In the list every channel points to TvIt; when a player opens it, TvIt makes the same request the broadcaster's player would make and redirects it to the address it just got. The video comes straight from the broadcaster's CDN, without going through my server.

There's one more advantage: since the list points to TvIt and not to the broadcasters, when a broadcaster changes something it's enough to fix TvIt, and the list saved in the players keeps working.

From the list to the website

The original idea was just the list. Then I wanted a website to watch the channels in the browser, with the TV guide next to them, and that's where the real problems came in.

I solved them one at a time, with passion and patience, and enjoyed doing it.

• CORS. Some broadcaster services don't let the browser read their responses from another site. TvIt makes the request in the browser's place and passes on only the final CDN address, which the browser can open.
• The server is outside Italy. Some broadcasters block requests from abroad, and my server isn't in Italy. That's why TvIt almost never downloads the video but sends the player back to the broadcaster, which serves it to the viewer; channels available only in Italy are marked on the site with a small flag.
• Addresses that expire. For some channels the address lasts a few minutes: TvIt asks for it again at every start, instead of writing it down once and for all.
• Broadcasters that change. CDNs, addresses and pages change without notice. Each time it's back to the developer tools, finding the right request again and updating TvIt.

The guide, written by hand

The programme guide (EPG) doesn't come from an API: it's read from the schedule pages, channel by channel, every night at 3. I wrote the scraper by hand, without AI, studying the code of the pages and deciding what to take: times, title, category, description and image.

The schedule pages change their structure every now and then. That's why, if the scraper no longer finds any programme, it stops and reports it, instead of leaving the guide empty without anyone noticing.

Used by others too

• 65 stars and 4 forks on GitHub: my most followed repository, a sign that many people use the list.
• More stable than other lists: when a channel stops working, it's fixed in one place, and every player can watch it again.
• The web player, handy when travelling without your own player at hand.
• The list and the guide update themselves, with no manual work.

What it left me

TvIt is a side project, and it always has been. Yet it has given me great satisfaction: the biggest result isn't the stars, but having fun building it, discovering how streaming really works and getting past, one after the other, obstacles I didn't even know were ahead of me at the start.