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 de Gameplay Real**: Usa análisis visual para distinguir entre gameplay, selección de campeones y streamer hablando
- **Detección 2 de 3**: Chat saturado + Audio (gritos) + Colores brillantes
+- **VLM Integration**: Compatible con Moondream, Video-LLaMA, Qwen2-VL
- **Modo Draft**: Procesa en 360p para prueba rápida
+- **Multi-Modal**: Combina Whisper (audio), Chat (texto), Video (visión) y Audio (picos)
- **Modo HD**: Procesa en 1080p para calidad máxima
+- **GPU Accelerated**: Optimizado para RTX 3050 (4GB) y RX 6800 XT (16GB)
- **Soporte GPU**: Preparado para NVIDIA (CUDA) y AMD (ROCm)
+- **Pipeline Automatizado**: Descarga → Análisis → Generación de video en un solo comando
 - **CLI simple**: Un solo comando para todo el pipeline
 ## 🚀 Uso Rápido
 ```bash
-# Modo Draft (360p) - Prueba rápida
+# Detectar highlights en un stream
-./pipeline.sh <video_id> <nombre> --draft
+python3 highlight_generator.py --video stream.mp4 --chat chat.json --output highlights.mp4
-# Modo HD (1080p) - Alta calidad  
+# O usar el sistema completo con VLM
-./pipeline.sh <video_id> <nombre> --hd
+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
+## 📁 Archivos Principales
 ```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
 | Archivo | Descripción |
 |---------|-------------|
-| [README.md](README.md) | Este archivo |
+| `highlight_generator.py` | Detector híbrido unificado (recomendado) |
-| [CONtexto.md](contexto.md) | Historia y contexto del proyecto |
+| `scene_detector.py` | Detección de cambios de escena con FFmpeg |
-| [TODO.md](TODO.md) | Lista de tareas pendientes |
+| `gpu_detector.py` | Análisis de frames en GPU |
-| [HIGHLIGHT.md](HIGHLIGHT.md) | Guía de uso del pipeline |
+| `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
+# Entorno Python
-cd twitch-highlight-detector
+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
+export CUDA_VISIBLE_DEVICES=0  # Seleccionar GPU
-# Edita .env con tus credenciales de Twitch
+export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512
 ```
-### 3. Instalar dependencias
+### Archivos de Configuración
-```bash
+- `gameplay_scenes.json` - Segmentos de gameplay detectados
-pip install -r requirements.txt
+- `highlights_*.json` - Timestamps de highlights
-```
+- `transcripcion_*.json` - Transcripciones Whisper
-### 4. Instalar TwitchDownloaderCLI
+## 🎬 Salidas
 ```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/
 ```
-## 🎯 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
+### Detección de Highlights
-2. **Audio intenso**: Picos de volumen (gritos, momentos épicos)
+Combina 4 señales:
-3. **Colores brillantes**: Efectos visuales, cambios de escena
+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
+## 🛠️ Troubleshooting
 ```
 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:
 ### Out of Memory
 ```python
--threshold        # Sensibilidad (default: 1.5)
+# Reducir batch_size o usar quantization
--min-duration    # Duración mínima highlight (default: 10s)
+from transformers import BitsAndBytesConfig
--device          # GPU: auto/cuda/cpu
+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
+## 📚 Documentación Adicional
 --padding    # Segundos extra antes/después (default: 5)
 ```
-## 🖥️ GPU
+- `6800xt.md` - Guía completa para RX 6800 XT
-
+- `contexto.md` - Contexto del proyecto
-### NVIDIA (CUDA)
+- `GPU_ANALYSIS.md` - Análisis de rendimiento GPU
 ```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
 ## 🤝 Contribuir
-1. Fork el repo
+1. Fork del repositorio
-2. Crea una branch (`git checkout -b feature/`)
+2. Crear branch: `git checkout -b feature/nueva-funcionalidad`
-3. Commit tus cambios (`git commit -m 'Add feature'`)
+3. Commit: `git commit -am 'Agregar funcionalidad X'`
-4. Push a la branch (`git push origin feature/`)
+4. Push: `git push origin feature/nueva-funcionalidad`
-5. Abre un Pull Request
+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
+- **IA Assistant** - Implementación inicial
- [streamlink](https://streamlink.github.io/) - Video downloading
+- **renato97** - Testing y requisitos
- [MoviePy](https://zulko.github.io/moviepy/) - Video processing
+
- [PyTorch](https://pytorch.org/) - GPU support
+---
 **Nota**: Para configuración específica de RX 6800 XT, ver archivo `6800xt.md`