FMHYPlay

# FMHYPlay Android - Especificación Técnica Detallada

### 1. Identidad del Proyecto

- *Nombre:* FMHYPlay - *Repositorio:* `fmhyplay/android` - *Tipo:* Aplicación Android open-source, TV-first - *Licencia:* MIT - *Estado:* Activo, 19 releases, última versión 2.19.0 - *Web:* `fmhyplay.github.io/android/` - *Métricas del repo:* 368 stars, 22 forks, 5 watchers, 1 contribuidor principal - *Filosofía:* "Any streaming site, a real player" - Cualquier sitio, un reproductor de verdad.

*Definición funcional:* Es un cliente de navegación + reproductor. No es un agregador de contenido. No aloja, indexa ni distribuye video. Abre páginas web elegidas por el usuario en un WebView, detecta el flujo de video que la página inicia y lo transfiere a un reproductor nativo.

### 2. Stack Tecnológico

*Lenguajes:* - *Java 87.6%* - Lógica principal de la app, UI, reproductor, gestión de red y cast. - *JavaScript 8.7%* - Script de inyección en WebView (`assets/frame.js`) para inspección de DOM y comunicación bidireccional. - *Go 2.3%* - Helper de WARP, túnel WireGuard en userspace. - *Otros 1.4%* - Recursos, XML, scripts de build, docs.

*Sin Gradle:* Build con Java puro + herramientas SDK por línea de comandos. Esto reduce dependencias, hace el build más reproducible y el APK final más ligero.

*Tamaño final:* ∼11 MB por APK. Muy ligero para lo que hace.

*Requisitos mínimos:* - Android 8.0+ / API 26+ - Arquitecturas: arm64-v8a y armeabi-v7a (32-bit ARM) - Sin root requerido - Sin permiso de VPN (WARP es userspace)

*Herramientas de build:* - Android SDK Platform 34 + Build-Tools - JDK 17+ - Go + Android NDK (solo para compilar `warp/build.sh`) - Scripts: `warp/build.sh` + `./build.sh` - CI reproducible + releases firmados desde tag, con `SHA256SUMS.txt` para verificación.

### 3. Estructura del Repositorio .github/ - Workflows CI, build reproducible, releases assets/ - frame.js, recursos web inyectados en WebView docs/ - Documentación, guía de usuario, guía de build libs/ - Librerías nativas / dependencias empaquetadas res/ - Recursos Android: layouts TV/phone, drawables, strings i18n scripts/ - Scripts de automatización de build y release src/me/champdev/weblock/ - Código fuente principal Java test/ - Tests unitarios warp/ - Código Go para helper WARP + build.sh .gitignore README Esta estructura separa claramente: UI (res), lógica (src), bridge web (assets), red segura (warp) y automatización (scripts/.github).

### 4. Arquitectura de Ejecución - Pipeline de Reproducción

Este es el núcleo del sistema, en 5 fases:

*Fase 1: Carga en WebView* La página del sitio se carga en un WebView de Android. Se mantiene la navegación completa del sitio para que el usuario conserve catálogo, buscador, servidores y episodios.

*Fase 2: Inyección de `frame.js`* Un script JS se ejecuta en cada frame, incluyendo embeds cross-origin. Su función es: - Observar el DOM. - Leer listas de servidores y calidades que la página expone. - Exponer una interfaz de bridge para recibir clics desde el reproductor nativo. - Reportar cuando la página intenta iniciar un flujo.

*Fase 3: Detección de Stream* La app observa las peticiones del WebView buscando playlists HLS (.m3u8) y DASH (.mpd). Como algunos sitios ocultan la extensión, también hay detección por sniffing de primeros bytes del contenido descargado.

Tipos soportados: HLS, DASH, Live FLV. Si el stream no es reproducible, hace fallback a la página.

*Fase 4: Handover a ExoPlayer* Cuando se detecta un stream válido: 1. La página se pausa. 2. El stream se entrega a FMHYPlayer (ExoPlayer con decodificador por hardware). 3. Se reenvían los mismos headers que usó la página: `Referer`, `Origin` y `Cookies`. Esto es crítico porque muchos servidores validan esos headers para aceptar la reproducción. 4. Se muestra una pantalla de carga translúcida con título, paso actual y animación mientras se hace el handover.

*Fase 5: Control Bidireccional* El reproductor no es pasivo. Sus botones envían clics de vuelta a la página vía `frame.js`: - Cambiar servidor -> clic en el botón de servidor del sitio. - Cambiar calidad -> clic en el botón de calidad del sitio. - Cambiar episodio -> clic en el episodio en la lista del sitio. - Cambiar Sub/Dub -> clic en el control correspondiente.

La página cambia, genera un nuevo stream, y el nuevo stream vuelve a ExoPlayer por el mismo pipeline. El usuario nunca vuelve a la página.

### 5. FMHYPlayer - Reproductor Nativo

*Motor:* ExoPlayer con decodificador por hardware.

*UI - Dos grupos de botones:* - *Izquierda:* Anterior, Siguiente, Episodios - *Derecha:* Calidad, Audio, Sub/Dub, Servidores, Subtítulos, Más, Cast, Pantalla completa - Los menús abren como panel lateral. - La selección actual se muestra bajo el título. - En TV, el botón con foco muestra su nombre.

*Funciones de reproducción:* - *Resume:* Guarda posición cada 10 segundos. Al volver, reanuda donde lo dejaste en cualquier sitio o servidor. Botón Restart. - *Calidad:* Lista con framerate (ej. 1080p60), pistas de audio y subtítulos, velocidad y modos de zoom. - *Volume Boost:* Hasta +12 dB. - *Dialog Boost:* Realce de voces, desactivado por defecto, activable en Settings o en el reproductor. - *Skip:* Intro, recap y créditos con datos de TheIntroDB y AniSkip. Botón Next episode en créditos. Opción en Settings para skip automático. - *Episodios:* Strip inferior con stills y nombres mientras se reproduce. Anterior/Siguiente + autoplay del siguiente. - *Sub/Dub:* Para anime, recordado por sitio. - *Precisión de episodio:* Abre el episodio exacto directamente en 34 sitios de TV y 22 sitios de anime. En el resto, pulsa el episodio en la lista del sitio.

*Subtítulos:* - Fuente: OpenSubtitles, en cualquier idioma. - Conversión para que cada script se muestre correctamente. - Recordados por título. - Auto-subtítulos opcionales en tu idioma. - Auto-sync: alinea el archivo con el habla. - Personalización: tamaño, posición, color, fondo y timing.

*Debug Overlay (Más > Debug overlay, off por defecto):* Panel en borde derecho, refresco cada 1 segundo, con: Resolución, framerate, codec, decoder (hardware/software), bitrate video/audio, velocidad de red, buffer, frames mostrados y perdidos, tipo de stream, host, tiempo de apertura del video y memoria.

*Móvil:* - Picture-in-Picture. - Mantener lado derecho/izquierdo para 2x. - Respeta bloqueo de rotación + botón Full screen. - Swipe para brillo y volumen. - Doble toque para saltar 10s.

*Navegación rápida:* - Back to Home en 1 paso desde el reproductor (móvil: botón casa, TV: Más > Home) y desde web (móvil: casa arriba derecha, TV: Menú > Back to home) o manteniendo Back 3 segundos en cualquier pantalla.

### 6. Módulo de Cast

*Objetivo:* El móvil como mando, la TV como pantalla.

*Modos:*

*a) TV con FMHYPlay (Recomendado)* La TV reproduce el stream ella misma, con headers y cookie del sitio, WARP, bloqueo de anuncios y subtítulos. Funciona incluso cuando FMHYPlay está cerrado en la TV.

*b) Chromecast / Google TV / TVs con Cast integrado* Sin app en la TV. El móvil hace relay del stream para que los sitios lo acepten.

*c) DLNA / UPnP (Samsung, LG, Sony, Kodi y otros)* Mismo relay. Mejor rendimiento con MP4 y TS, ya que no todas las TVs reproducen HLS.

*Controles desde el móvil:* Play, pausa, seek, ±10s y volumen de TV (las teclas de volumen del móvil también funcionan).

### 7. Módulo de Navegación y Descubrimiento

*Home:* - Continue watching - Favorites - Contenido de tu país primero (por idioma, desde TMDB) - Luego New y Popular para Movies, TV y Anime (desde Cinemeta y Kitsu) - Side rail en TV, bottom tabs en móvil - Pull to refresh - Trailers en páginas de títulos

*Búsqueda Unificada:* Un solo buscador para películas, series, canales IPTV y sitios. Por escritura o por voz.

*Directorio de Sitios:* Sigue las listas FMHY. Abre la página propia del título en ∼70 sitios y busca en el resto, luego abre el match. Anime abre solo en sitios de anime.

*Extras de navegación:* - Añadir tu propio sitio. - Barra de direcciones opcional. - Páginas oscuras. - Cursor para mando de TV con estilos divertidos y útiles. - Pop-ups que son links reales abren en la misma pestaña (Back vuelve). Pop-up ads se descartan. Diálogos tipo "Join our Discord" se cierran solos.

### 8. Módulo IPTV

*Fuente principal:* iptv-org, más de 11,000 canales públicos, agrupados por categoría y país, con logos.

*Lógica:* - Check en background que oculta canales offline. - Canales de tu país y sus categorías primero. - En el reproductor: Canal +/-, Anterior/Siguiente y strip de canales para moverte dentro de la categoría.

*Playlists personalizadas:* - Playlist propia .m3u / .m3u8 - Un solo link de stream .m3u8 - Login Xtream Codes - Portal Stalker (MAC address) - Cada playlist tiene su propia fila.

*Filtros y organización:* - Filtros de Categoría e Idioma en cada lista. - Pins: guarda una lista con sus filtros (ej. India · News · Hindi) como su propia fila. - Favoritos con corazón. - Los canales aparecen también en la búsqueda unificada.

### 9. Módulo de Red, Privacidad y Seguridad

*WARP Integrado (Cloudflare):* - Túnel WireGuard en userspace, implementado en Go. - Solo para el tráfico de la app, no para todo el sistema. - Sin permiso VPN, sin root. - Direcciones LAN quedan directas, no pasan por el túnel. - Log de WARP para compartir cuando falla.

*Bloqueo:* - Bloqueo por dominio de anuncios, trackers y pop-ups. - Bloqueo de redirecciones. - Sin cuenta FMHYPlay. - Sin analítica, sin telemetría. - Actualizaciones desde releases del repositorio, buscadas cada hora y en cada boot (incluso con app cerrada), con What's new antes de instalar.

*Integraciones de terceros (ver THIRD_PARTY.md):* - TMDB, Cinemeta, Kitsu para metadatos. - TheIntroDB, AniSkip para skip. - OpenSubtitles para subtítulos. - iptv-org para IPTV. - Simkl y PunchPlay para tracking opcional. - Cloudflare WARP para red.

### 10. Internacionalización

Idiomas soportados: Inglés, Hindi, Español, Portugués, Indonesio, Árabe (RTL) y Alemán. Se toma del idioma del teléfono o TV.

### 11. Formatos de Distribución

- *FMHYPlay-TV-vX.Y.Z.apk:* Android TV, Google TV, Fire TV, boxes. Añade entrada en launcher TV. - *FMHYPlay-Android-vX.Y.Z.apk:* Teléfonos y tablets. - Firmados con la misma clave, por lo que las actualizaciones se instalan sobre la versión anterior. - Verificación con `SHA256SUMS.txt` del release.

### 12. Resumen de Ingeniería

FMHYPlay es un ejemplo de ingeniería minimalista pero muy eficaz: - *Ligero* porque evita Gradle y usa Java puro. - *Potente* porque delega la reproducción a ExoPlayer hardware. - *Inteligente* porque no intenta replicar el catálogo de los sitios, sino que los usa como fuente y toma el control solo de la reproducción. - *Respetuoso* porque no pide cuenta, no hace tracking y su red es aislada por app.

Es una arquitectura de *bridge*: WebView para descubrir, JS para controlar, ExoPlayer para reproducir, Go para tunelizar, y Java para orquestar todo con UI TV-first.

---