2026-02-01 19:44:45 +00:00
1 changed files with 141 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,141 @@
+# 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
+- **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:**
+   ```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
+   ```
+
+3. **Ejecuta con Docker Compose:**
+   ```bash
+   docker compose up -d
+   ```
+
+4. **Accede a la playlist:**
+   ```
+   http://localhost:8080/playlist.m3u
+   ```
+
+### 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` |
+
+## 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
+
+```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>