Come Trasformare la Tua TV di Casa in una Piattaforma Web con WebHomeTV

Chiunque abbia provato a configurare un media center su Android TV o su un TV box si sarà probabilmente imbattuto nell'ecosistema TVBox e FongMi. Si tratta di popolari player open-source in grado di caricare contenuti attraverso script Python e JavaScript. Presentano però un problema: l'interfaccia della schermata home è strettamente legata al layout standard a griglia di app. Modificare il layout o integrare un feed di raccomandazioni personalizzato senza ricompilare l'intero APK è semplicemente impossibile.

Lo sviluppatore fish2018 ha deciso di seguire un approccio diverso e ha creato il repository webhtv (WebHomeTV). Il progetto è basato sulla codebase di FongMi ma cambia radicalmente il concetto stesso di schermata home. Ora la schermata home è una pagina web a tutti gli effetti, costruita con HTML, CSS e JS che comunica con Android attraverso un bridge JS integrato e le API native dell'app.

Cosa C'è All'Interno e Come Funziona

Essenzialmente, si tratta di un'app Android ibrida per smartphone e TV. All'interno lavorano insieme due layer. Da un lato rimangono i parser di contenuti familiari (Spider/CSP), mentre dall'altro si avviano un contesto Chromium e un server web locale per renderizzare layout personalizzati.

Puoi costruire qualsiasi frontend, posizionarlo sul tuo server o sulla memoria del box, e da lì controllare la ricerca, chiamare il video player, verificare la disponibilità dei link e sincronizzare la cronologia di visione.

Cosa Rende Interessante Questo Progetto

Gli sviluppatori hanno progettato un SDK nativo per il contesto del browser. Quando il frontend viene caricato all'interno della WebView dell'app, ottiene accesso a un oggetto con metodi per interagire con l'hardware e il sistema operativo. La pagina web può inviare autonomamente richieste di rete cross-domain bypassing le regole CORS, richiedere la cronologia di visione, utilizzare il proxy di sistema e passare gli stream video direttamente al video player interno. Se la griglia delle categorie standard diventa noiosa, puoi costruire un frontend in stile dashboard interattiva cinematografica o come terminale testuale.

Un'attenzione particolare merita il sistema integrato di verifica dei link per cloud storage e il motore di ranking intelligente per le fonti. L'app verifica la validità delle cartelle condivise sui popolari servizi di file hosting direttamente out of the box. Allo stesso tempo, il sistema tiene traccia del tasso di successo delle ricerche e della riproduzione per ogni sito collegato. Nel tempo, le fonti più veloci e stabili salgono automaticamente più in alto nella lista dei risultati.

Controllare tutto questo con un telecomando non è sempre comodo, quindi nel'app è integrato un pannello di amministrazione. Se esegui WebHomeTV sulla tua TV e apri l'indirizzo /m in un browser sul tuo computer o smartphone, si apre un pannello di controllo web. Attraverso di esso puoi configurare comodamente le fonti, passare i token di autorizzazione, caricare script di estensione personalizzati e visualizzare i log del video player.

Se hai diversi TV box e telefoni a casa, non dovrai regolare manualmente la configurazione su ogni dispositivo. La sincronizzazione sulla rete locale è implementata all'interno: impostazioni, cronologia di visione, cookie di autorizzazione e segnalibri vengono trasferiti tra i client in un paio di clic. Per i dispositivi remoti, puoi configurare un relay intermedio in Go, Rust, Cloudflare Workers o Vercel.

Architettura e Librerie Native

Il contenuto tecnico del repository appare serio. Non si tratta affatto di una semplice facciata sopra il MediaPlayer Android di sistema.

L'app è costruita con Java 21 e Android SDK 37 (compileSdk 37, minSdk 24). Il codice supporta due flavor: mobile per touchscreen e leanback per il funzionamento con telecomando.

La parte più interessante è nascosta nel motore del player. Gli autori non si sono limitati al ExoPlayer standard e hanno integrato un MPV profondamente personalizzato basato su C/C++. All'interno utilizza build fresche di FFmpeg (n8.0.3), libplacebo e curl con supporto HTTP/2. Per l'output video su Android 15, hanno utilizzato una combinazione di Vulkan e MediaCodec tramite AImageReader e Android Hardware Buffer, che rende possibile decodificare lo stream video direttamente nella memoria GPU senza copie di frame non necessarie.

Oltre a MPV, il progetto include un fork di Media3 (versione 1.11.0-alpha01-fongmi) con patch personalizzate. Ad esempio, una patch aggiunge un handler WebSocket ad alte prestazioni per commenti online e sottotitoli con supporto alle code e limiti di frame rate.

Compilazione da Sorgenti

Se vuoi compilare il progetto da solo, avrai bisogno di un Android SDK preparato con NDK 28.2.13676358 e JDK 21. Il repository contiene già librerie precompilate .so, quindi non dovrai ricompilare MPV e FFmpeg da zero alla prima build.

Il processo di compilazione da console appare standard:

git clone https://github.com/fish2018/webhtv.git
cd webhtv
echo "sdk.dir=$ANDROID_HOME" > local.properties
bash gradlew :app:assembleMobileArm64_v8aDebug :app:assembleLeanbackArm64_v8aDebug

I file APK finiti vengono posizionati in directory in app/build/outputs/apk/. Il repository contiene anche script nella cartella scripts/ che verificano l'integrità degli header ELF e ricompilano i bridge JNI se necessario.

Kit per Sviluppatori e Strumenti AI

Nella cartella webhome-devkit gli autori hanno condiviso un toolkit completo per creare le tue schermate home personalizzate. Ci sono template di layout pronti all'uso, esempi di estensioni per iniettare codice JS nelle pagine web e documentazione per lavorare con l'SDK.

Un dettaglio interessante: gli sviluppatori hanno aggiunto un set di regole pronte (skills) per assistenti AI. Puoi collegarli a Cursor, Claude o altri editor di reti neurali per generare automaticamente nuovi moduli e parser per WebHomeTV attraverso prompt.

A Chi Sarà Utile Questo Progetto

Se stai scrivendo pet project per Android TV o vuoi creare un hub multimediale personalizzato per uso domestico, WebHomeTV ti fornirà una base pronta all'uso e potente. Non devi scrivere decoder, gestori di richieste di rete e gestione degli eventi del telecomando da zero. Costruisci semplicemente una pagina web ordinata e collegala all'SDK nativo.

Il progetto si è rivelato specifico ma estremamente ben pensato. Risolve il problema di lunga data dei player TV monolitici, dando agli sviluppatori web piena libertà nella creazione di interfacce per schermi grandi.