Xtream Codes M3U List Builder

Servicio Python que genera y actualiza automáticamente listas de reproducción M3U a partir de servidores Xtream Codes API. Ideal para centralizar y servir playlists IPTV de forma local.

Características

• Actualización automática — Regenera la playlist en intervalos configurables
• Servidor HTTP integrado — Sirve el archivo M3U directamente sin dependencias externas
• Docker ready — Despliegue simple con Docker Compose
• Escritura atómica — Actualiza el archivo sin interrumpir descargas activas
• Seguridad — Se ejecuta con usuario no privilegiado en contenedor
• Multi-hilo — Servidor threaded para manejar múltiples clientes simultáneos

Inicio Rápido

Con Docker (Recomendado)

1. Clona el repositorio:

   git clone https://github.com/tu-usuario/xtream_codes_m3u_list_builder.git
   cd xtream_codes_m3u_list_builder
   

2. Crea un archivo .env:

   HOST=http://tu-servidor-iptv.com
   USERNAME=tu_usuario
   PASSWORD=tu_contraseña
   PORT=8080
   UPDATE_INTERVAL=3600
   OUTPUT_FILE=playlist.m3u
   

3. Ejecuta con Docker Compose:

   docker compose up -d
   

4. Accede a la playlist:

   http://localhost:8080/playlist.m3u
   

Sin Docker

1. Requisitos:

   • Python 3.14+
   • Poetry

2. Instalación:

   poetry install
   

3. Configuración: Crea un archivo .env (ver ejemplo arriba) o exporta las variables de entorno.

4. Ejecución:

   poetry run python -m m3u_list_builder.main
   

Configuración

Variable	Descripción	Requerido	Default
HOST	URL del servidor Xtream Codes	✅	—
USERNAME	Usuario del servicio IPTV	✅	—
PASSWORD	Contraseña del servicio IPTV	✅	—
PORT	Puerto del servidor HTTP local	❌	8080
UPDATE_INTERVAL	Intervalo de actualización (segundos)	❌	3600
OUTPUT_FILE	Nombre del archivo M3U generado	❌	playlist.m3u

Arquitectura

┌─────────────────────────────────────────────────────────┐
│                    M3U List Builder                     │
├──────────────────────┬──────────────────────────────────┤
│   Updater Thread     │         HTTP Server              │
│                      │                                  │
│  ┌────────────────┐  │  ┌────────────────────────────┐  │
│  │ Fetch API      │  │  │ ThreadingHTTPServer        │  │
│  │ (Xtream Codes) │  │  │                            │  │
│  └───────┬────────┘  │  │  GET /playlist.m3u         │  │
│          │           │  │                            │  │
│  ┌───────▼────────┐  │  └────────────────────────────┘  │
│  │ Generate M3U   │  │                                  │
│  │ (Atomic Write) │──┼──────► public/playlist.m3u      │
│  └───────┬────────┘  │                                  │
│          │           │                                  │
│     sleep(interval)  │                                  │
│          ↓           │                                  │
│       [loop]         │                                  │
└──────────────────────┴──────────────────────────────────┘

Estructura del Proyecto

├── src/m3u_list_builder/
│   ├── __init__.py
│   ├── config.py        # Configuración con Pydantic Settings
│   ├── main.py          # Punto de entrada
│   ├── playlist.py      # Lógica de generación M3U
│   └── server.py        # Servidor HTTP
├── tests/               # Tests unitarios
├── public/              # Directorio servido (playlist generada)
├── Dockerfile           # Multi-stage build
├── docker-compose.yml
└── pyproject.toml       # Dependencias y configuración

Testing

# Ejecutar tests
poetry run pytest

# Con cobertura
poetry run pytest --cov

# Verificar estilo (Ruff)
poetry run ruff check src/

Desarrollo

El proyecto utiliza:

• Pydantic Settings — Validación de configuración
• Requests — Cliente HTTP
• Ruff — Linter y formatter
• Pytest — Testing framework

---

_{Desarrollado con ❤️ para la comunidad IPTV}