xtream_codes_m3u_list_builder/README.md

# Xtream Codes M3U List Builder

[![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://www.docker.com/)

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
- **EPG integrado** — Descarga y filtra automáticamente la guía de programación (XMLTV)
- **Filtros avanzados** — Incluye canales por prefijo o excluye por contenido del nombre
- **Servidor HTTP integrado** — Sirve el archivo M3U y EPG directamente sin dependencias externas
- **Docker ready** — Despliegue simple con Docker Compose
- **Escritura atómica** — Actualiza archivos 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:**
   ```bash
   git clone https://github.com/tu-usuario/xtream_codes_m3u_list_builder.git
   cd xtream_codes_m3u_list_builder
   ```

2. **Crea un archivo `.env`:**
   ```env
   HOST=http://tu-servidor-iptv.com
   USERNAME=tu_usuario
   PASSWORD=tu_contraseña
   PORT=8080
   UPDATE_INTERVAL=3600
   OUTPUT_FILE=playlist.m3u
   INCLUDE_TEXT="ES:"
   EXCLUDE_TEXT=["XXX","Adultos","24/7"]
   ```

3. **Ejecuta con Docker Compose:**
   ```bash
   docker compose up -d
   ```

4. **Accede a la playlist y EPG:**
   ```
   http://localhost:8080/playlist.m3u
   http://localhost:8080/epg.xml
   ```

### Sin Docker

1. **Requisitos:**
   - Python 3.14+
   - [Poetry](https://python-poetry.org/)

2. **Instalación:**
   ```bash
   poetry install
   ```

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

4. **Ejecución:**
   ```bash
   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` |
| `INCLUDE_TEXT` | Lista JSON de prefijos. Solo canales que **empiecen** con alguno | ❌ | `[]` |
| `EXCLUDE_TEXT` | Lista JSON de textos. Excluye canales que **contengan** alguno | ❌ | `[]` |

### Filtros

- **`INCLUDE_TEXT`**: Filtra canales que **empiecen** con alguno de los textos especificados (lógica OR). Si está vacío, incluye todos los canales.
- **`EXCLUDE_TEXT`**: Excluye canales cuyo nombre **contenga** alguno de los textos (lógica OR). Se aplica después del filtro de inclusión.
- Los mismos filtros se aplican automáticamente al EPG.

Ejemplo:
```env
# Solo canales que empiecen con "ES:" o "UK:", excluyendo los que contengan "Adult"
INCLUDE_TEXT=["ES:", "UK:"]
EXCLUDE_TEXT=["Adult", "XXX"]
```

## Arquitectura

```
┌─────────────────────────────────────────────────────────┐
│                    M3U List Builder                     │
├──────────────────────┬──────────────────────────────────┤
│   Updater Thread     │         HTTP Server              │
│                      │                                  │
│  ┌────────────────┐  │  ┌────────────────────────────┐  │
│  │ Fetch API      │  │  │ ThreadingHTTPServer        │  │
│  │ (Xtream Codes) │  │  │                            │  │
│  └───────┬────────┘  │  │  GET /playlist.m3u         │  │
│          │           │  │  GET /epg.xml              │  │
│  ┌───────▼────────┐  │  └────────────────────────────┘  │
│  │ Generate M3U   │  │                                  │
│  │ + Apply Filter │──┼──────► public/playlist.m3u      │
│  └───────┬────────┘  │                                  │
│          │           │                                  │
│  ┌───────▼────────┐  │                                  │
│  │ Fetch & Filter │  │                                  │
│  │ EPG (XMLTV)    │──┼──────► public/epg.xml           │
│  └───────┬────────┘  │                                  │
│          │           │                                  │
│     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

```bash
# 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

---

<p align="center">
  <sub>Desarrollado con ❤️ para la comunidad IPTV</sub>
</p>