Add comprehensive README

2026-02-19 17:39:42 +00:00
parent 00180d0b1c
commit 57a1854a16
1 changed files with 133 additions and 170 deletions
--- a/README.md
+++ b/README.md
@@ -1,213 +1,176 @@
-# 🎬 Twitch Highlight Detector
+# Twitch Highlight Detector 🎮

-Pipeline automatizado para detectar y generar highlights de streams de Twitch y Kick.
+Sistema avanzado de detección de highlights para streams de Twitch usando VLM (Vision Language Models) y análisis de contexto.

-## ✨ Características
+## 🎯 Características

- **Descarga automática** de VODs y chat
- **Detección 2 de 3**: Chat saturado + Audio (gritos) + Colores brillantes
- **Modo Draft**: Procesa en 360p para prueba rápida
- **Modo HD**: Procesa en 1080p para calidad máxima
- **Soporte GPU**: Preparado para NVIDIA (CUDA) y AMD (ROCm)
- **CLI simple**: Un solo comando para todo el pipeline
+- **Detección de Gameplay Real**: Usa análisis visual para distinguir entre gameplay, selección de campeones y streamer hablando
+- **VLM Integration**: Compatible con Moondream, Video-LLaMA, Qwen2-VL
+- **Multi-Modal**: Combina Whisper (audio), Chat (texto), Video (visión) y Audio (picos)
+- **GPU Accelerated**: Optimizado para RTX 3050 (4GB) y RX 6800 XT (16GB)
+- **Pipeline Automatizado**: Descarga → Análisis → Generación de video en un solo comando

 ## 🚀 Uso Rápido

 ```bash
-# Modo Draft (360p) - Prueba rápida
-./pipeline.sh <video_id> <nombre> --draft
+# Detectar highlights en un stream
+python3 highlight_generator.py --video stream.mp4 --chat chat.json --output highlights.mp4

-# Modo HD (1080p) - Alta calidad  
-./pipeline.sh <video_id> <nombre> --hd
+# O usar el sistema completo con VLM
+python3 scene_detector.py  # Detecta segmentos de gameplay
+python3 extract_final.py   # Extrae highlights
+python3 generate_video.py --video stream.mp4 --highlights final_highlights.json
 ```

-### Ejemplo
-
-```bash
-# Descargar y procesar en modo draft
-./pipeline.sh 2701190361 elxokas --draft
-
-# Si te gusta, procesar en HD
-./pipeline.sh 2701190361 elxokas_hd --hd
-```
-
-## 📋 Requisitos
-
-### Sistema
-```bash
-# Arch Linux
-sudo pacman -S ffmpeg streamlink git
-
-# Ubuntu/Debian
-sudo apt install ffmpeg streamlink git
-
-# macOS
-brew install ffmpeg streamlink git
-```
-
-### Python
-```bash
-pip install moviepy opencv-python scipy numpy python-dotenv torch
-```
-
-### .NET (para TwitchDownloaderCLI)
-```bash
-# Descarga el binario desde releases o compila
-# https://github.com/lay295/TwitchDownloader/releases
-```
-
-## 📖 Documentación
+## 📁 Archivos Principales

 | Archivo | Descripción |
 |---------|-------------|
-| [README.md](README.md) | Este archivo |
-| [CONtexto.md](contexto.md) | Historia y contexto del proyecto |
-| [TODO.md](TODO.md) | Lista de tareas pendientes |
-| [HIGHLIGHT.md](HIGHLIGHT.md) | Guía de uso del pipeline |
+| `highlight_generator.py` | Detector híbrido unificado (recomendado) |
+| `scene_detector.py` | Detección de cambios de escena con FFmpeg |
+| `gpu_detector.py` | Análisis de frames en GPU |
+| `vlm_analyzer.py` | Análisis con VLM (Moondream/LLaVA) |
+| `chat_sync.py` | Sincronización de chat con video |
+| `6800xt.md` | **Guía completa para RX 6800 XT** |
+
+## 🎮 Hardware Soportado
+
+### RTX 3050 (4GB VRAM) - Configuración Actual
+- Modelo: Moondream 2B
+- Procesamiento: Frame por frame
+- Tiempo: ~20 min para 2 horas de video
+
+### RX 6800 XT (16GB VRAM) - Mejor Opción  
+- Modelo: Video-LLaMA 7B o Qwen2-VL 7B
+- Procesamiento: Batch de frames
+- Tiempo: ~5-8 min para 2 horas de video
+- Ver: `6800xt.md` para instrucciones completas
+
+## 📊 Pipeline de Trabajo
+
+```
+Video (2.3h)
+    ↓
+[Scene Detection] → Segmentos de 30s-5min
+    ↓
+[Clasificación] → GAMEPLAY / SELECT / TALKING / MENU
+    ↓
+[Filtrado] → Solo segmentos GAMEPLAY
+    ↓
+[Análisis Multi-Modal]
+    - Whisper: Transcripción + Keywords
+    - Chat: Picos de actividad
+    - Audio: Detección de gritos
+    - VLM: Confirmación visual
+    ↓
+[Extracción] → Mejores momentos de cada segmento
+    ↓
+[Generación] → Video final concatenado
+```

 ## 🔧 Instalación

-### 1. Clonar el repo
+### Requisitos
+- Python 3.10+
+- CUDA/ROCm compatible
+- FFmpeg con CUDA
+
+### Setup
 ```bash
-git clone https://tu-gitea/twitch-highlight-detector.git
-cd twitch-highlight-detector
+# Entorno Python
+python3 -m venv vlm_env
+source vlm_env/bin/activate
+
+# Dependencias base
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
+pip install transformers accelerate opencv-python pillow
+pip install openai-whisper scipy numpy
+
+# Para RTX 3050 (actual)
+./install_vlm.sh
+
+# Para RX 6800 XT (próximo)
+# Ver 6800xt.md
 ```

-### 2. Configurar credenciales
+## 📝 Configuración
+
+### Variables de Entorno
 ```bash
-cp .env.example .env
-# Edita .env con tus credenciales de Twitch
+export CUDA_VISIBLE_DEVICES=0  # Seleccionar GPU
+export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512
 ```

-### 3. Instalar dependencias
-```bash
-pip install -r requirements.txt
-```
+### Archivos de Configuración
+- `gameplay_scenes.json` - Segmentos de gameplay detectados
+- `highlights_*.json` - Timestamps de highlights
+- `transcripcion_*.json` - Transcripciones Whisper

-### 4. Instalar TwitchDownloaderCLI
-```bash
-# Descargar desde releases
-curl -L -o TwitchDownloaderCLI https://github.com/lay295/TwitchDownloader/releases/latest/download/TwitchDownloaderCLI
-chmod +x TwitchDownloaderCLI
-sudo mv TwitchDownloaderCLI /usr/local/bin/
-```
+## 🎬 Salidas

-## 🎯 Cómo Funciona
+El sistema genera:
+- `HIGHLIGHTS_FINAL.mp4` - Video de highlights (5-10 minutos)
+- `HIGHLIGHTS_FINAL.json` - Timestamps de clips
+- `gameplay_*.json` - Mapa de segmentos de gameplay

-### Pipeline (2 de 3)
+## 🔬 Metodología

-El sistema detecta highlights cuando se cumplen al menos 2 de estas 3 condiciones:
+### Detección de Gameplay
+Usa análisis multi-factor:
+1. **Variación de color** - Gameplay tiene más movimiento
+2. **Canal verde** - Mapa de LoL es predominantemente verde
+3. **Detección de bordes** - UI de LoL tiene bordes definidos
+4. **VLM** - Clasificación visual con modelo de lenguaje

-1. **Chat saturado**: Muchos mensajes en poco tiempo
-2. **Audio intenso**: Picos de volumen (gritos, momentos épicos)
-3. **Colores brillantes**: Efectos visuales, cambios de escena
+### Detección de Highlights
+Combina 4 señales:
+1. **Rage keywords** - "puta", "mierda", "me mataron"
+2. **Picos de chat** - Mensajes/segundo
+3. **Picos de audio** - Volumen/gritos
+4. **Contexto temporal** - Extensión inteligente de clips

-### Flujo
-
-```
-1. streamlink         → Descarga video (VOD)
-2. TwitchDownloaderCLI → Descarga chat
-3. detector_gpu.py    → Analiza chat + audio + color
-4. generate_video.py  → Crea video resumen
-```
-
-## 📁 Estructura
-
-```
-├── .env                    # Credenciales (noCommit)
-├── .gitignore
-├── requirements.txt        # Dependencias Python
-├── main.py                 # Entry point
-├── pipeline.sh             # Pipeline completo
-├── detector_gpu.py         # Detector (chat + audio + color)
-├── generate_video.py       # Generador de video
-├── lower                   # Script descarga streams
-├── README.md               # Este archivo
-├── CONtexto.md             # Contexto del proyecto
-├── TODO.md                 # Tareas pendientes
-└── HIGHLIGHT.md           # Guía detallada
-```
-
-## ⚙️ Configuración
-
-### Parámetros del Detector
-
-Edita `detector_gpu.py` para ajustar:
+## 🛠️ Troubleshooting

+### Out of Memory
 ```python
--threshold        # Sensibilidad (default: 1.5)
--min-duration    # Duración mínima highlight (default: 10s)
--device          # GPU: auto/cuda/cpu
+# Reducir batch_size o usar quantization
+from transformers import BitsAndBytesConfig
+quantization_config = BitsAndBytesConfig(load_in_4bit=True)
 ```

-### Parámetros del Video
+### Lento
+- Usar CUDA Graphs
+- Reducir resolución de frames (320x180 → 160x90)
+- Procesar en batches

-Edita `generate_video.py`:
+### Precision baja
+- Aumentar umbral de detección
+- Usar modelo VLM más grande
+- Ajustar ponderaciones de scores

-```python
--padding    # Segundos extra antes/después (default: 5)
-```
+## 📚 Documentación Adicional

-## 🖥️ GPU
-
-### NVIDIA (CUDA)
-```bash
-pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
-```
-
-### AMD (ROCm)
-```bash
-pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm7.1
-```
-
-**Nota**: El procesamiento actual es CPU-bound. GPU acceleration es future work.
-
-## 🔨 Desarrollo
-
-### Tests
-```bash
-# Test detector con video existente
-python3 detector_gpu.py --video video.mp4 --chat chat.json --output highlights.json
-```
-
-### Pipeline Manual
-```bash
-# 1. Descargar video
-streamlink "https://www.twitch.tv/videos/ID" best -o video.mp4
-
-# 2. Descargar chat
-TwitchDownloaderCLI chatdownload --id ID -o chat.json
-
-# 3. Detectar highlights
-python3 detector_gpu.py --video video.mp4 --chat chat.json --output highlights.json
-
-# 4. Generar video
-python3 generate_video.py --video video.mp4 --highlights highlights.json --output final.mp4
-```
-
-## 📊 Resultados
-
-Con un stream de 5.3 horas (19GB):
- Chat: ~13,000 mensajes
- Picos detectados: ~139
- Highlights útiles (>5s): 4-10
- Video final: ~1-5 minutos
+- `6800xt.md` - Guía completa para RX 6800 XT
+- `contexto.md` - Contexto del proyecto
+- `GPU_ANALYSIS.md` - Análisis de rendimiento GPU

 ## 🤝 Contribuir

-1. Fork el repo
-2. Crea una branch (`git checkout -b feature/`)
-3. Commit tus cambios (`git commit -m 'Add feature'`)
-4. Push a la branch (`git push origin feature/`)
-5. Abre un Pull Request
+1. Fork del repositorio
+2. Crear branch: `git checkout -b feature/nueva-funcionalidad`
+3. Commit: `git commit -am 'Agregar funcionalidad X'`
+4. Push: `git push origin feature/nueva-funcionalidad`
+5. Crear Pull Request

 ## 📝 Licencia

-MIT License - Ver LICENSE para más detalles.
+MIT License - Libre para uso personal y comercial.

-## 🙏 Créditos
+## 👥 Autores

- [TwitchDownloader](https://github.com/lay295/TwitchDownloader) - Chat downloading
- [streamlink](https://streamlink.github.io/) - Video downloading
- [MoviePy](https://zulko.github.io/moviepy/) - Video processing
- [PyTorch](https://pytorch.org/) - GPU support
+- **IA Assistant** - Implementación inicial
+- **renato97** - Testing y requisitos
+
+---
+
+**Nota**: Para configuración específica de RX 6800 XT, ver archivo `6800xt.md`