Sottotitoli per il televisore che hai già

A che cosa serve

Uno spettatore, un televisore, e un buco che la sottotitolazione televisiva non copre.

Le emittenti italiane sottotitolano alcuni programmi e altri no. Il telegiornale in diretta, le finestre regionali, lo sport, i talk show, quasi tutto il pomeriggio: arrivano senza sottotitoli, oppure con sottotitoli così in ritardo da descrivere una frase diversa da quella sullo schermo. Per chi ci sente poco è la differenza fra guardare la televisione e guardare delle persone che muovono la bocca.

HearAble nasce esattamente per quel caso: sottotitolare quello che c'è adesso, in italiano, sul televisore stesso — non su un telefono, non su un tablet appoggiato allo schermo, e senza chiedere allo spettatore di imparare niente oltre a un tasto.

Tre vincoli hanno deciso tutto quello che viene dopo.

• Non deve rompere il televisore. Il decoder ha un solo sintonizzatore terrestre. Se sottotitolare costa un sintonizzatore, o si prende un tasto del telecomando, o fa sparire l'immagine, lo spettatore ci perde più di quanto ci guadagni.
• Deve girare in casa. Nessun servizio di riconoscimento nel cloud, nessun account, nessun caricamento di quello che una persona guarda nel suo salotto.
• Si deve poter usare premendo un tasto. Lo spettatore preme F4. Tutto il resto — svegliare il riconoscitore, collegarsi, smontare tutto, spegnere dopo — è un problema del sistema.

Il saluto, come appare sul televisore. Quattro secondi, poi il primo sottotitolo vero lo sostituisce.

La prima domanda: da dove viene l'audio?

Tutto quello che sta a valle è ordinario. Tirare fuori l'audio pulito del programma da un decoder chiuso, senza pagare pegno, è la parte che è stata inventata.

Un riconoscitore ha bisogno dell'audio del programma. Le strade ovvie sono state provate, e ciascuna chiedeva un prezzo che il progetto non poteva pagare.

Il tap sul demux

Il ricevitore monta uno stack DVB Hisilicon ed espone l'API DVB standard di Linux. Enigma2 tiene aperti ventiquattro filtri PID su demux0 mentre mostra un canale; quello di HearAble è il venticinquesimo. È solo userspace — nessun modulo kernel, nessuna immagine modificata, niente di persistente.

# tutto il meccanismo, in cinque chiamate
open("/dev/dvb/adapter0/demux0", O_RDWR | O_NONBLOCK)
DMX_SET_BUFFER_SIZE   1 MiB
DMX_SET_PES_FILTER    pid    = <il PID audio scelto dallo spettatore>
                      input  = DMX_IN_FRONTEND
                      output = DMX_OUT_TSDEMUX_TAP
                      flags  = DMX_IMMEDIATE_START
read()                pacchetti MPEG-TS da 188 byte

Le tre modalità di uscita sono state provate sul box vero invece che dedotte dall'header, e la differenza conta: DMX_OUT_TS_TAP si apre senza errori e consegna zero byte — manda al device dvr, non a questo descrittore. DMX_OUT_TAP funziona a 127,3 kbit/s con il primo dato dopo 0,27 s. DMX_OUT_TSDEMUX_TAP funziona a 132,8 kbit/s con il primo dato dopo 0,03 s, e ha vinto su quel numero.

Le scelte che l'hanno formato

Quattro decisioni spiegano quasi tutto l'aspetto del sistema, ognuna con la misura che ha dietro — una scelta di progetto senza un numero è una preferenza.

Il riconoscitore gira sulla CPU, e non c'è nessuna GPU

Nemotron 3.5 ASR Streaming 0.6B, quantizzato q8_0, su NeMo-Speech.cpp. Una GPU è più veloce in pura portata, ma sotto ritmo — alimentata al passo con cui l'audio arriva davvero, che è l'unica modalità che conti per la diretta — il suo vantaggio crolla da 5,7× a 2,2×, perché non può sovrapporre lavoro che non ha ancora ricevuto. Un N95 senza ventola arriva a un fattore di tempo reale di 0,4848 su trenta minuti di televisione vera senza averne una.

Il governor, non il compilatore

Nessuna riga di codice di calcolo è tarata per questa macchina. La velocità viene da una riga di sysfs: il riconoscitore lavora a raffiche di circa 105 ms ogni 160, e intel_pstate in powersave non vede mai una raffica abbastanza lunga da salire di frequenza.

Il ritardo di pubblicazione è zero

Il tap legge il flusso che entra nel ricevitore, quindi corre 64 ms davanti all'immagine — misurato leggendo due orologi nello stesso istante, AUDIO_GET_PTS contro il PTS del pacchetto che il filtro PID sta consegnando. Non c'è niente da compensare, e infatti non si compensa niente.

La trascrizione è portabile

Gli stessi sorgenti, compilati su un'architettura diversa con un compilatore diverso e kernel SIMD diversi, producono una trascrizione identica bit per bit: le stesse 74 parole, WER 0,00 %. Niente nella catena dipende dalla macchina su cui gira, ed è per questo che l'appliance si è potuta scegliere per consumo e prezzo invece che per compatibilità.

Come sta insieme

Due macchine, un cavo privato, due piccoli protocolli che vanno in direzioni opposte.

La divisione è voluta. Il decoder è un apparecchio chiuso con un kernel 4.4 e non ha spazio per un modello di riconoscimento; il mini PC ha la potenza ma non sa disegnare sul televisore. Ciascuno fa quindi l'unica cosa che può: il box preleva e dipinge, il mini PC ascolta e riconosce.

Il lato decoder

Un plugin Enigma2, circa duemila righe, che fa quattro mestieri: preleva, rilancia l'audio, dipinge, e sveglia l'altra macchina.

Hardware

Octagon SF8008 V3 Supreme Combo (Hisilicon), un sintonizzatore DVB-T2/C su frontend1, un DVB-S2X su frontend0

Immagine

openATV 7.5.1, Linux 4.4.35, Enigma2

Plugin

/usr/lib/enigma2/python/Plugins/Extensions/HearAbleOSD, caricato a WHERE_SESSIONSTART

In ascolto su

:8770 — /hearable (WebSocket, sottotitoli in ingresso) e /control (HTTP, controllo del relay)

Stato persistente

/etc/enigma2/hearable_look.json, hearable_sync.json, hearable_wol.json

Disegnare su un televisore

Il pannello è una skin Enigma2 costruita a runtime, e quasi ogni sua riga racchiude un difetto trovato su uno schermo vero.

Il pannello è due righe di testo bianco centrato su una banda nera all'85 % di opacità, ciascuna alta circa il 7,5 % dello schermo, attaccate, appoggiate al 7 % dal bordo inferiore per restare dentro l'area sicura a qualsiasi dimensione. Quella geometria viene dalla pratica televisiva, non da quello che ci stava: si legge come un blocco solo dall'altra parte della stanza. La tela dell'OSD è 1280 × 720 anche su un servizio HD, ed è una trappola che va detta: disporre la banda in coordinate 1080p la manda sotto il bordo dello schermo.

Che cosa può cambiare lo spettatore

Una modifica si applica subito: il dialogo viene distrutto e ricreato, invece di richiedere un riavvio di Enigma2 che farebbe sparire l'immagine.

Il telecomando

Tre tasti, e nient'altro tolto a Enigma2.

HearAble parte spento a ogni avvio. Lo stato non è persistito di proposito: i sottotitoli sono una cosa che si chiede, e un box che torna da un black-out già disegnando sullo schermo è un box che ha deciso al posto dello spettatore.

Allo spegnimento. La versione compare qui perché è l'unico posto dove uno spettatore senza terminale può leggerla.

Il relay: mandare l'audio senza mandare il programma

Un progetto precedente mandava tutto il contenitore — video compreso — e chiedeva alla macchina ricevente di tenere una copia identica bit per bit del file, così da ricostruire la posizione del decoder confrontando un fotogramma preso dal suo schermo. È insostenibile su una macchina piccola, e inutile per la diretta.

Il relay manda invece solo la traccia audio scelta, ancora compressa: 26 kB/s di MPEG-TS prodotti da un processo ffmpeg fuori da Enigma2, così un ricevitore lento o assente non può mai bloccare l'interfaccia.

• È il relay a connettersi verso di noi. Il mini PC sta in ascolto e si annuncia nel suo poll di controllo. È questo che permette al flusso di partire esattamente da dove si trova lo spettatore, ed è il motivo per cui un ricevitore assente non costa niente al decoder: nessun processo avviato, nessuna porta tenuta aperta.
• Il flusso dice da dove comincia. -c copy sa posizionarsi solo su un confine di contenitore, quindi il relay parte circa 0,65 s prima della posizione chiesta. I primi pacchetti di ogni epoca vengono sondati per il loro timestamp e l'eccesso viene scartato lato ricevitore: entrambe le parti conoscono un timestamp vero, quindi la differenza si butta via invece di correggerla con un anello di retroazione.
• Un ricevitore che smette di chiedere sparisce dopo un TTL di 8 s, e il relay si ferma da solo.

Svegliare l'altra macchina

Premere F4 manda un magic packet Wake-on-LAN sul link privato — in broadcast su 10.77.0.255, porte 9 e 7, ripetuto fino a quindici volte ogni venti secondi, che dà una finestra di cinque minuti. Tempo di risveglio misurato da spento via software: 32,0 s, tre cicli su tre.

Il lato mini PC

Un box N95 senza ventola in cui nessuno entra: si sveglia quando glielo si chiede, riconosce, e si spegne da solo quando il televisore smette di parlare.

Hardware

T9 Plus, Intel N95 — 4 core / 4 thread, 800 MHz – 3,40 GHz, L1d 128 KiB · L2 2 MiB · L3 6 MiB, 15 GiB di RAM

SIMD

sse4_2, avx, avx2, fma, f16c, bmi2, avx_vnni

Sistema

Debian 13 trixie, Linux 6.12.107

Modello

Nemotron 3.5 ASR Streaming 0.6B, q8_0, 741 548 352 byte, sha256 a5c435f2…f429ae

Runtime

NeMo-Speech.cpp a 4f96762, ggml, solo CPU — nella macchina non c'è GPU e non ne serve

Rete

enp1s0 = 10.77.0.2 statico, cavo privato verso il decoder. Wi-Fi solo per la manutenzione

Che cosa l'ha resa davvero veloce

Nessuna riga di codice di calcolo è stata ottimizzata per questa macchina. La velocità è venuta da una riga di sysfs.

Le quattro unit che ne fanno un apparecchio

Spegnersi da solo

Il watchdog fa due domande e per agire gli servono entrambe le risposte: c'è qualcosa attaccato alla porta audio (letto da /proc/net/tcp sulla porta 9010), e il decoder sta ancora guardando (il suo /api/powerstate, con ripiego sul ping)? Senza sessione audio fa partire un timer — venti minuti di default, tre quando il decoder è andato in standby, entrambi in /etc/default/hearable — e spegne la macchina. Una sessione che torna lo annulla.

La conseguenza pratica è che lo spettatore al mini PC non pensa mai. Compare quando si preme F4 e sparisce qualche minuto dopo che il televisore è tornato silenzioso.

L'anello di stato

Il case ha un anello RGB su un ponte seriale CH340. Il protocollo è una trama da cinque byte — 0xFA, modo, luminosità, velocità, checksum — a 10 000 baud, con luminosità e velocità invertite rispetto a quello che verrebbe da pensare.

Sopravvivere alla rete

L'unico difetto vero trovato dalla campagna di torture da mezz'ora era nel ricevitore audio, e solo un cavo staccato fisicamente lo ha fatto emergere: un timeout di socket veniva ingoiato con continue, quindi una connessione morta restava in mano per sempre — diciotto respawn, tre socket semiaperti, 80 kB non letti. Ora il ricevitore rinuncia dopo 15 s di silenzio e imposta SO_KEEPALIVE con 10 s di inattività, 5 s di intervallo e 3 sonde.

Sottotitola anche quello che riproduci dal box

Un film dallo storage del ricevitore passa dalla stessa catena — nessun componente in più, nessun secondo percorso di codice.

La diretta è il caso difficile ed è quello di cui ha parlato tutta questa pagina. Ma il relay è un secondo lettore di quello che il decoder sta riproducendo: il demux per la diretta, il file per un file. In entrambi i casi manda avanti solo la traccia audio scelta, compressa, da un punto più avanti rispetto allo spettatore. Il ricevitore vede source_type: file invece di dvb nella risposta di controllo, e tira dritto.

FILE_STALE_SUBTITLES: 0 su tutta la corsa: niente di precedente a una pausa, a un salto o a un cambio di file è mai stato dipinto dopo. Una regressione alla v1.2.0 aveva già chiuso lo stesso percorso.

Misurato con il film sullo storage USB del box (/media/hdd). Un NVMe o un disco interno è lo stesso percorso per HearAble — legge quello che Enigma2 sta riproducendo e lo storage non lo tocca mai — ma non è stato misurato e qui non viene affermato.

I due protocolli

Piccoli di proposito, separati di proposito, e ciascuno con una regola che decide tutto il resto.

Sottotitoli: hearable-enigma2/1

Un WebSocket persistente che porta un oggetto JSON per frame di testo. Il produttore si connette verso l'esterno, il renderer sta in ascolto. Niente TLS e niente autenticazione: il confine di fiducia è il cavo privato.

Non mandare mai la trascrizione cumulativa. Un subtitle_state porta le due righe da mostrare e nient'altro; il validatore rifiuta esplicitamente una trascrizione progressiva, perché mandarla renderebbe traffico e memoria quadratici nella durata della sessione. E il produttore non aspetta mai. Gli ACK sono osservativi: un renderer lento costa freschezza del sottotitolo, mai contropressione sulla catena di riconoscimento. C'è esattamente uno stato in attesa, e uno più nuovo lo sostituisce.

Audio: hearable-audio-relay/1

Due canali in direzioni opposte, perché un ricevitore lento non possa mai bloccare Enigma2.

La richiesta di controllo è anche l'annuncio e il battito: il ricevitore dice dove vuole l'audio, quanto anticipo vuole, e quanto è risultato avanti rispetto allo spettatore. Questi ultimi due sono numeri diversi e non vanno confusi: uno è una richiesta, l'altro è una misura.

Dove va quel secondo

Il sottotitolo arriva circa un secondo dopo la parola pronunciata. Quasi tutto è il riconoscitore che decide, ed è una scelta, non un incidente.

Misurato da capo a fondo: p50 1,072 s fra l'audio consumato e lo stato di sottotitolo emesso (n = 1461, p05 0,893 s). Ricostruito dalle impostazioni in uso:

Più di metà di quel secondo è spesa a non mostrare qualcosa che potrebbe essere sbagliato. Lo stabilizzatore aspetta che una parola sia confermata, e la coda non confermata non si mostra affatto. Un sottotitolo più veloce che si riscrive davanti a chi legge è peggio di uno più lento che sta fermo — e per un lettore che dal testo dipende, invece di darci un'occhiata, è molto peggio.

Che cosa non è finito, e che cosa non è mai stato misurato

Scritto come lacuna invece che omesso in silenzio, perché una misura mancante che sembra un risultato è la cosa più costosa di questo progetto.

Che cosa invece ha ricevuto risposta

• Il Wake-on-LAN sopravvive a un taglio di corrente. Tutto quello che si sapeva sul risveglio del mini PC era misurato da spento via software, con l'alimentatore che teneva viva la scheda di rete. Staccata fisicamente la corrente a entrambe le macchine, il mini PC si è acceso lo stesso 6,4 minuti dopo il decoder — quando è stato premuto F4 — con gli orologi delle due macchine allineati entro un secondo e il pulsante di accensione mai toccato.
• Il tap sul demux non costa un sintonizzatore. Trenta zap fra multiplex diversi, trenta successi, nessun servizio perso.
• La catena sopravvive a essere attaccata. Diciannove guasti iniettati, diciannove riprese senza intervento; trenta minuti di disturbo deliberato con zero chunk persi e zero sottotitoli stantii.

Come è stato costruito

Di una persona, con un modello come assistente allo sviluppo, e ogni fase passata da test e misure.

HearAble è di Nunzio Raciti, costruito con Claude (il modello Opus di Anthropic) come assistente allo sviluppo. Lui ha posto l'obiettivo e i vincoli, ha preso ogni decisione di progetto, possiede l'hardware e ha fatto le prove che contavano di più; Claude ha scritto codice, test e strumenti di misura sotto la sua direzione.

La divisione si vede nei risultati. Diversi difetti che contano non li ha trovati un test, ma la persona che usava la cosa vera:

Niente è andato avanti su un'opinione

246 test automatici, tutti eseguibili senza un decoder in stanza: il protocollo sul filo, il renderer lato ricevitore col rifiuto per epoca e sequenza, lo stabilizzatore, le regole di commit, i caricatori di configurazione, la disciplina degli orologi, e la coerenza della versione fra pacchetto e plugin.

Gate costruiti apposta per tutto ciò che richiede hardware vero — il gate LAN, la sessione dal vivo, il ciclo di vita dell'interfaccia, i cicli di avvio, il Wake-on-LAN, il timer di inattività, il lettore di file, una matrice di guasti da diciannove casi. Ognuno produce un verdetto e un blocco leggibile a macchina, non un log da interpretare.

Rapporti di campagna con ogni riga etichettata MEASURED, DERIVED o NOT_MEASURED, così una lacuna non può mai essere letta come un risultato.

Verdetti a cui è permesso dire di no. Due indagini sono state chiuse dai numeri che le hanno chiuse, e un gate che produce troppe poche prove dichiara NON_MISURATO invece di passare sul nulla.