hls-restream-proxy
Proxy inverso ligero en Python para retransmitir flujos HLS, inyectando cabeceras HTTP necesarias (User-Agent, Referer) y gestionando tokens expirados. Ideal para servidores de medios autoalojados como Jellyfin.
Ficha actualizada 18 sept 2026, 20:48 · upstream 27 abr 2026, 21:57 · release sin release detectada
Qué es hls-restream-proxy
Descripción editorial construida a partir del repositorio, su documentación y sus señales de mantenimiento.
hls-restream-proxy es una herramienta diseñada para facilitar la reproducción de flujos HLS gratuitos en servidores de medios autoalojados que a menudo fallan al acceder a fuentes externas debido a restricciones de cabeceras HTTP. El proxy actúa como intermediario entre el servidor de medios y las fuentes upstream, inyectando automáticamente las cabeceras requeridas (como User-Agent y Referer) y reescribiendo las listas de reproducción m3u8 para asegurar que los segmentos .ts también pasen por él.
El proyecto incluye scripts bash para la detección automática de cabeceras necesarias mediante `detect-headers.sh` y la generación de archivos M3U estables con `refresh-m3u.sh`. Esto permite a los usuarios configurar canales sin necesidad de intervención manual constante, ya que el proxy maneja la renovación de tokens y la actualización de URLs de forma transparente. Además, ofrece soporte para declarar el ancho de banda real del flujo, evitando que servidores como Jellyfin transcodifiquen innecesariamente por estimaciones incorrectas de bitrate.
La arquitectura es minimalista, utilizando solo Python 3.8+ con librerías estándar y herramientas de línea de comandos comunes (bash, curl, grep). Esto garantiza un despliegue sencillo en entornos Docker o manualmente, sin dependencias externas complejas ni necesidad de transcodificación nativa.
- Retransmisión de flujos IPTV/HLS gratuitos que requieren cabeceras específicas (User-Agent, Referer) para evitar bloqueos 403 en servidores como Jellyfin.
- Integración con Plex y Emby mediante herramientas externas como Threadfin o xTeVe para exponer fuentes M3U como sintonizadores virtuales.
- Detección automática de cabeceras HTTP necesarias para sitios de streaming específicos sin intervención manual constante.
- Gestión transparente de tokens expirados en listas de reproducción HLS, manteniendo las URLs del M3U estables para los clientes.
- Configuración de ancho de banda real para evitar la transcodificación forzada en Jellyfin cuando el servidor no detecta el bitrate correcto.
- Arquitectura ligera basada en Python stdlib sin dependencias externas, facilitando el despliegue en entornos minimalistas.
- Detección automática de cabeceras HTTP necesarias mediante `detect-headers.sh`, ahorrando tiempo de configuración manual.
- Gestión transparente de tokens expirados, manteniendo la estabilidad de las URLs del M3U para los clientes finales.
- Soporte para múltiples servidores de medios (Jellyfin, Plex, Emby) y reproductores directos (VLC, mpv).
- Configuración flexible mediante archivo `channels.conf` con soporte para override de cabeceras y ancho de banda.
- Requiere acceso a la red del servidor de medios o configuración correcta de redes Docker (puerta de enlace) para funcionar correctamente.
- No transcoda contenido, por lo que depende de la compatibilidad de codecs del cliente final con el flujo original.
- La detección automática de cabeceras puede fallar en sitios con protección agresiva o lógica compleja de JavaScript.
- No incluye transcodificación nativa, por lo que no es adecuado para flujos incompatibles con los clientes sin un servidor de medios avanzado.
Perfil de infraestructura
Estimación inicial derivada del repositorio y de los servicios detectados.
Despliegue detectado
Qué señales reales de instalación hemos encontrado.
Usar el puerto 8089 o cambiar `HLS_PROXY_PORT` según sea necesario. Configurar correctamente `HLS_PROXY_URL` en entornos Docker, usando la IP de la puerta de enlace del contenedor si el servidor de medios está en una red bridge. Asegurar que los scripts bash (`refresh-m3u.sh`, `detect-headers.sh`) tengan permisos de ejecución y las rutas correctas a las herramientas (curl, grep). Para Plex/Emby, integrar con Threadfin o xTeVe para exponer el M3U como un sintonizador virtual.
Stack y dependencias
Componentes inferidos a partir de manifests, configuración y documentación.
Experiencia real de la comunidad
Ayuda a contrastar la estimación automática con instalaciones reales.
Todavía no hay datos comunitarios para este proyecto.