Back to blog
GuidaTV: una guida TV italiana che registra sul NAS

GuidaTV: una guida TV italiana che registra sul NAS

November 21, 2026 guida-tv, pvr, nas, docker, self-hosted, xmltv, nodejs, claude, codex, ai, opensource opensource

Le app che mostrano la guida TV non mancano, iPhone compreso. Alcune permettono di aprire le app ufficiali delle emittenti per guardare un programma in streaming. Nessuna, che io sappia, permette di registrarlo. Così ho costruito GuidaTV: una guida TV dei canali italiani che gira a casa mia e salva le registrazioni sul NAS. In pratica, un PVR (personal video recorder) fatto in casa.

L’ho sviluppata con l’aiuto di Claude e Codex, usandoli come due colleghi che si controllano a vicenda: uno scrive, l’altro critica. Il codice sorgente è su GitHub.

Griglia oraria della Guida TV su desktop

Cosa fa

  • Guida completa: scarica i palinsesti (Rai, Mediaset, Sky, Superguida) con iptv-org/epg, li converte in XMLTV e li aggiorna all’avvio e due volte al giorno.
  • Viste utili: Adesso, Griglia oraria, ricerca e filtri per Cinema, Serie TV e News. Il numero di canale del digitale terrestre determina l’ordine.
  • Diretta: il pulsante ▶ apre lo stream in VLC o nell’app che preferisci, oppure il sito ufficiale dell’emittente.
  • Registrazioni: dalla scheda di un programma, Registra prenota la cattura con margini personalizzabili (di default 2 minuti prima e 10 dopo). Sono previste la registrazione di una serie intera, la prenotazione per orario e la gestione delle sovrapposizioni.
  • Sul NAS: il servizio cattura in MPEG-TS, salva audio e video in MP4 senza ricodificarli e trasferisce il file sulla condivisione SMB. Se il trasferimento fallisce, riprova da solo.
  • Su qualsiasi dispositivo: è una web app senza login, quindi si usa da LAN o via Tailscale. Su iPhone basta “Aggiungi a schermata Home” per averla come un’app.
Vista Adesso e scheda del programma

Programmi in onda nella vista Adesso su desktop

Scheda delle qualifiche del GP del Portogallo su desktop

Su iPhone

Programmi in onda nella vista Adesso su iPhone Griglia oraria della Guida TV su iPhone Scheda delle qualifiche del GP del Portogallo su iPhone

Come funziona

Sono due container Docker: epg scarica i palinsesti e genera il file XMLTV, web è un server Node senza framework che lo tiene in memoria, espone le API e serve una interfaccia in JavaScript puro, senza build. L’ultima guida valida resta in un volume, quindi l’app funziona anche se una sorgente è momentaneamente irraggiungibile.

Per provarla:

test -e .env || cp .env.example .env
docker compose up -d --build

Poi si apre http://127.0.0.1:8085. La guida parte anche senza NAS; per registrare serve configurare la condivisione SMB nel file .env. Tutti i dettagli sono nel README.

Le registrazioni funzionano solo per i canali con uno stream diretto utilizzabile: gli stream ufficiali in chiaro di Mediaset, TV2000 e Warner Bros. Discovery, più Rai e TV8 abilitabili a parte. La disponibilità dipende dalle emittenti, che possono limitare gli stream geograficamente o oscurare alcuni programmi. Il progetto è pensato per uso personale.

English overview

GuidaTV is a self-hosted TV guide for Italian television that can also record programmes to your NAS, making it a home-made PVR. Most TV guide apps, on iPhone included, only show the schedule, and some open the broadcasters’ official streaming apps. None that I know of can record.

I built it with Claude and Codex. It fetches Italian listings as XMLTV, shows a live “now” view and a schedule grid with search, and lets you schedule single programmes or whole series. Recordings are captured as MPEG-TS, remuxed to MP4 without re-encoding and moved to an SMB share. It is a plain web app that works from your LAN or over Tailscale, and installs on an iPhone home screen. The interface is in Italian, and the bundled channels and recording integrations are specific to Italian broadcasters. See the README on GitHub for details.