youtube-downloader/README.md

# YouTube Downloader Dashboard 🎵

Una aplicación web moderna para descargar videos de YouTube en formato MP3 y MP4 con una interfaz amigable y soporte para Docker. Basada en yt-dlp con configuración optimizada para evitar restricciones de YouTube.

## ✨ Características

- 🌐 **Interfaz Web Moderna**: Dashboard responsive con Bootstrap 5
- 🎧 **Descarga MP3**: Extrae audio de alta calidad (192 kbps)
- 🎬 **Descarga MP4**: Descarga videos en alta calidad
- 📊 **Progreso en Tiempo Real**: Barra de progreso con velocidad y tiempo estimado
- 🔄 **Reintentos Automáticos**: Configuración robusta con 10 reintentos
- 🧹 **Limpieza Automática**: Elimina archivos temporales y descargas antiguas
- 🐳 **Soporte Docker**: Listo para producción 24/7
- 📱 **Responsive**: Funciona perfectamente en móviles y desktop

## 🚀 Capturas de Pantalla

### Interfaz Principal
```
┌─────────────────────────────────────────────────────────────┐
│              🎵 YouTube Downloader Dashboard               │
│     Descarga videos de YouTube en formato MP3 o MP4       │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│  URL del Video de YouTube                                 │
│  [🔗] [https://www.youtube.com/watch?v=...]               │
│                                                             │
│  Formato de Descarga                                       │
│  ○ MP3 (Audio)  ○ MP4 (Video)                             │
│                                                             │
│  [📥 Descargar]                                            │
└─────────────────────────────────────────────────────────────┘
```

### Progreso de Descarga
```
┌─────────────────────────────────────────────────────────────┐
│  📥 Descargando...                                          │
│  [████████████████████████████████████] 75%                │
│  Velocidad: 2.5 MB/s  |  Tiempo: 00:45                     │
│  Archivo: el_principe_nicolas_maquiavelo.mp3               │
└─────────────────────────────────────────────────────────────┘
```

## 📋 Requisitos

### Opción 1: Sin Docker (Desarrollo)
- Python 3.8+
- FFmpeg (requerido para conversión de audio/video)
- pip

### Opción 2: Con Docker (Producción)
- Docker
- Docker Compose

## ⚙️ Instalación y Uso

### Opción 1: Docker (Recomendado para Producción)

1. **Clona el repositorio:**
```bash
git clone https://gitea.cbcren.online/renato97/youtube-downloader.git
cd youtube-downloader
```

2. **Ejecuta el script de despliegue:**
```bash
chmod +x deploy.sh
./deploy.sh
```

3. **Accede a la aplicación:**
```
http://localhost:5000
```

### Opción 2: Sin Docker (Para Desarrollo)

1. **Clona el repositorio:**
```bash
git clone https://gitea.cbcren.online/renato97/youtube-downloader.git
cd youtube-downloader
```

2. **Crea un entorno virtual:**
```bash
python3 -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate
```

3. **Instala las dependencias:**
```bash
pip install -r requirements.txt
```

4. **Instala FFmpeg (requerido):**

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install ffmpeg
```

**CentOS/RHEL:**
```bash
sudo yum install epel-release
sudo yum install ffmpeg
```

**macOS:**
```bash
brew install ffmpeg
```

5. **Ejecuta la aplicación:**
```bash
python app.py
```

6. **Abre tu navegador en:**
```
http://localhost:5000
```

## 🎯 Cómo Usar la Aplicación

1. **Abre la aplicación** en tu navegador
2. **Pega la URL** del video de YouTube que quieres descargar
3. **Selecciona el formato:**
   - **MP3**: Para extraer solo el audio (ideal para música, podcasts)
   - **MP4**: Para descargar el video completo
4. **Haz clic en "Descargar"**
5. **Monitorea el progreso** en tiempo real
6. **Descarga el archivo** cuando esté completo

## 📂 Estructura del Proyecto

```
youtube-downloader/
├── app.py                    # Aplicación Flask principal
├── requirements.txt          # Dependencias Python
├── Dockerfile               # Configuración Docker
├── docker-compose.yml       # Orquestación Docker
├── deploy.sh               # Script de despliegue fácil
├── .dockerignore           # Archivos ignorados por Docker
├── README.md               # Esta documentación
├── templates/
│   └── index.html          # Interfaz web principal
├── static/
│   ├── css/
│   │   └── style.css       # Estilos personalizados
│   ├── js/
│   │   └── app.js          # Lógica del frontend
│   └── downloads/          # Archivos descargados
│       └── *.mp3, *.mp4    # Archivos de usuario
└── venv/                   # Entorno virtual (gitignore)
```

## 🔧 Configuración Avanzada

### Variables de Entorno

Puedes configurar las siguientes variables de entorno:

```bash
export FLASK_ENV=production          # Modo producción
export DOWNLOAD_FOLDER=/path/to/downloads  # Carpeta personalizada
export PORT=5000                     # Puerto personalizado
```

### Personalización de Calidad

Edita `app.py` para ajustar la calidad de descarga:

```python
# Para MP3 (calidad de audio)
'preferredquality': '192'  # 128, 192, 256, 320 kbps

# Para MP4 (calidad de video)
'format': 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best'
```

## 🐳 Docker Detalles

### Dockerfile
```dockerfile
FROM python:3.11-slim
# Instala FFmpeg y dependencias
# Configura la aplicación
# Expone puerto 5000
```

### Docker Compose
```yaml
version: '3.8'
services:
  youtube-downloader:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - ./static/downloads:/app/static/downloads
    restart: unless-stopped
```

## 📊 API Endpoints

La aplicación incluye una API REST:

- `POST /api/downloads` - Iniciar nueva descarga
- `GET /api/status/<download_id>` - Verificar estado
- `GET /api/downloads` - Listar todas las descargas
- `POST /api/cleanup` - Limpiar archivos temporales
- `GET /download/<filename>` - Descargar archivo específico

### Ejemplo de uso con curl:

```bash
# Iniciar descarga
curl -X POST http://localhost:5000/api/downloads \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID", "format": "mp3"}'

# Verificar estado
curl http://localhost:5000/api/status/<download_id>

# Listar descargas
curl http://localhost:5000/api/downloads
```

## 🔒 Solución de Problemas

### Error 403 de YouTube
La aplicación incluye configuración optimizada para evitar errores 403:

- User-Agent actualizado de Chrome 130
- Headers HTTP completos
- Múltiples reintentos (10)
- Timeout extendido (60s)

### Videos No Disponibles
Si un video no se puede descargar:

1. **Verifica que el video sea público**
2. **Intenta con otro video para descartar problemas de conexión**
3. **Revisa la consola del navegador para errores**
4. **Prueba la descarga directa con yt-dlp**

### Problemas con FFmpeg

**Error: `FFmpeg not found`**
```bash
# Verifica instalación
ffmpeg -version

# Instala si es necesario
sudo apt install ffmpeg  # Ubuntu/Debian
brew install ffmpeg      # macOS
```

### Problemas de Puerto

**Error: `Port 5000 is in use`**
```bash
# Cambia el puerto en app.py
app.run(host='0.0.0.0', port=5001, debug=True)
```

## 🔄 Actualización

### Actualizar la aplicación

1. **Detén la aplicación:**
```bash
docker compose down  # Si usas Docker
# o Ctrl+C si corres localmente
```

2. **Actualiza el código:**
```bash
git pull origin main
```

3. **Reconstruye y reinicia:**
```bash
docker compose build
docker compose up -d
```

### Actualizar yt-dlp

```bash
# Con Docker (reconstruye la imagen)
docker compose build --no-cache

# Sin Docker
pip install --upgrade yt-dlp
```

## 🤝 Contribuir

¡Las contribuciones son bienvenidas!

1. **Fork** el repositorio
2. **Crea una rama** para tu feature (`git checkout -b feature/AmazingFeature`)
3. **Commit** tus cambios (`git commit -m 'Add some AmazingFeature'`)
4. **Push** a la rama (`git push origin feature/AmazingFeature`)
5. **Abre un Pull Request**

## 📝 Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo `LICENSE` para más detalles.

## ⚠️ Advertencia Legal

Esta herramienta está diseñada para uso personal y educativo. Por favor:

- ✅ Descarga solo contenido que tengas derecho a descargar
- ✅ Respeta los términos de servicio de YouTube
- ✅ Usa esta herramienta de manera responsable
- ❌ No uses para contenido protegido por derechos de autor
- ❌ No redistribuyas contenido descargado

## 🆘 Soporte

Si encuentras algún problema:

1. **Revisa la sección de solución de problemas**
2. **Busca issues existentes** en el repositorio
3. **Crea un nuevo issue** con detalles del problema
4. **Incluye logs y capturas de pantalla** si es posible

## 📈 Métricas y Monitoreo

La aplicación incluye métricas básicas:

- **Cantidad de descargas** completadas
- **Tamaño total** de archivos descargados
- **Tiempo promedio** de descarga
- **Errores** y reintentos

### Ver logs en tiempo real:

```bash
# Docker
docker compose logs -f

# Local (la aplicación muestra logs en consola)
python app.py
```

---

**🎉 ¡Disfruta descargando tus videos favoritos de YouTube!**

Hecho con ❤️ usando Flask, yt-dlp y Bootstrap 5