twitch-highlight-detector/contexto.md

Contexto del Proyecto

Resumen Ejecutivo

Pipeline automatizado para detectar y generar highlights de streams de Twitch. El objetivo es:

1. Descargar un VOD completo de Twitch (varias horas)
2. Analizar el chat y el video para detectar momentos destacados
3. Generar un video resumen con los mejores momentos

El sistema original planeaba usar 3 métricas para detectar highlights (2 de 3 deben cumplirse):

• Chat saturado (muchos mensajes en poco tiempo)
• Picos de audio (gritos del streamer)
• Colores brillantes en pantalla (efectos visuales)

Estado actual: Solo chat implementado. Audio y color pendientes.

---

Historia y Desarrollo

Inicio

El proyecto comenzó con la carpeta clipper/ que contenía código antiguo para descargar streams de Twitch en vivo. El usuario quería actualizar el enfoque para procesar VODs completos (streams de varias horas) y detectar automáticamente los mejores momentos.

Primera Iteración (Código Viejo)

Existía código en clipper/ y analyser/ que:

• Descargaba streams en vivo
• Usaba twitchAPI para autenticación
• Tenía issues con versiones de dependencias (Python 3.14 incompatibilidades)

Limpieza y Nuevo Pipeline

Se eliminó el código viejo y se creó una estructura nueva:

downloaders/   - Módulos para descargar video/chat
detector/     - Lógica de detección de highlights  
generator/    - Creación del video resumen

Problemas Encontrados

1. Chat Downloader - Múltiples Intentos

Se probaron varios repositorios para descargar chat de VODs:

• chat-downloader (xenova): No funcionó con VODs (KeyError 'data')
• tcd (PetterKraabol): Mismo problema, API de Twitch devuelve 404
• TwitchDownloader (lay295): Este sí funcionó. Es un proyecto C#/.NET con CLI.

Solución: Compilar TwitchDownloaderCLI desde código fuente usando .NET 10 SDK.

2. Dependencias Python

Problemas de versiones:

• requests y urllib3 entraron en conflicto al instalar tcd
• Streamlink dejó de funcionar
• Solución: Reinstalar versiones correctas de requests/urllib3

3. Video de Prueba

• VOD: https://www.twitch.tv/videos/2701190361 (elxokas)
• Duración: ~5.3 horas (19GB)
• Chat: 12,942 mensajes
• El chat estaba disponible (no había sido eliminado por Twitch)

4. Detección de Highlights

Problemas con el detector:

• Formato de timestamp del chat no era reconocido
• Solución: Usar content_offset_seconds del JSON directamente

El detector actual solo usa chat saturado. Encuentra ~139 picos pero la mayoría son de 1-2 segundos (no útiles). Con filtro de duración >5s quedan solo 4 highlights.

5. Generación de Video

• Usa moviepy
• Funciona correctamente
• Genera video de ~39MB (~1 minuto)

---

Stack Tecnológico

Herramientas de Descarga

Herramienta	Uso	Estado
streamlink	Video streaming	✅ Funciona
TwitchDownloaderCLI	Chat VODs	✅ Compilado y funciona

Processing (Python)

Paquete	Uso	GPU Support
opencv-python-headless	Análisis de video/color	CPU (sin ROCm)
librosa	Análisis de audio	CPU
scipy/numpy	Procesamiento numérico	CPU
moviepy	Generación de video	CPU

GPU

• ROCm 7.1 instalado y funcionando
• PyTorch 2.10.0 instalado con soporte ROCm
• GPU detectada: AMD Radeon Graphics (6800XT)
• Pendiente: hacer que OpenCV/librosa usen GPU

---

Hardware

• GPU Principal: AMD Radeon 6800XT (16GB VRAM) con ROCm 7.1
• GPU Alternativa: NVIDIA RTX 3050 (8GB VRAM) - no configurada
• CPU: AMD Ryzen (12 cores)
• RAM: 32GB
• Almacenamiento: SSDNVMe

---

Credenciales

• Twitch Client ID: xk9gnw0wszfcwn3qq47a76wxvlz8oq
• Twitch Client Secret: 51v7mkkd86u9urwadue8410hheu754

---

Pipeline Actual (Manual)

# 1. Descargar video
bajar "https://www.twitch.tv/videos/2701190361"

# 2. Descargar chat (después de compilar TwitchDownloaderCLI)
TwitchDownloaderCLI chatdownload --id 2701190361 -o chat.json

# 3. Convertir chat a texto
python3 -c "
import json
with open('chat.json') as f:
    data = json.load(f)
with open('chat.txt', 'w') as f:
    for c in data['comments']:
        f.write(f\"[{c['created_at']}] {c['commenter']['name']}: {c['message']['body']}\n\")
"

# 4. Detectar highlights
python3 detector.py

# 5. Generar video
python3 generate_video.py

---

Resultados Obtenidos

Métrica	Valor
Video original	19GB (5.3 horas)
Mensajes de chat	12,942
Picos detectados	139
Highlights útiles (>5s)	4
Video final	39MB (~1 minuto)

Highlights Encontrados

1. ~4666s - ~4682s (16s)
2. ~4800s - ~4813s (13s)
3. ~8862s - ~8867s (5s)
4. ~11846s - ~11856s (10s)

---

Pendientes (TODO)

Alta Prioridad

1. Sistema 2 de 3: Implementar análisis de audio y color
2. GPU: Hacer que OpenCV/librosa usen la 6800XT
3. Mejor detección: Keywords, sentimiento, ranking
4. Kick: Soporte para chat (sin API pública)

Media Prioridad

5. Paralelización
6. Interfaz web (Streamlit)
7. CLI mejorada

Baja Prioridad

8. STT (reconocimiento de voz)
9. Detectar cuando streamer muestra algo en pantalla
10. Múltiples streamers

---

Archivos del Proyecto

Twitch-Highlight-Detector/
├── .env                      # Credenciales Twitch
├── .git/                     # Git repo
├── .gitignore
├── requirements.txt          # Dependencias Python
├── lower                    # Script: descargar streams
├── pipeline.sh              # Pipeline automatizado
├── detector.py              # Detección de highlights (chat)
├── generate_video.py        # Generación de video resumen
├── highlight.md             # Docs: uso del pipeline
├── contexto.md              # Este archivo
├── todo.md                  # Lista de tareas pendientes
│
├── chat.json                # Chat descargado (TwitchDownloader)
├── chat.txt                 # Chat en formato texto
├── highlights.json          # Timestamps de highlights
├── highlights.mp4           # Video final
└── 20260218_193846_twitch.mp4  # Video original de prueba

---

Notas Importantes

1. Twitch elimina el chat de VODs después de un tiempo (no hay tiempo exacto definido)
2. El threshold actual es muy sensible - detecta muchos falsos positivos de 1-2 segundos
3. El video de prueba es de elxokas, un streamer español de League of Legends
4. PyTorch con ROCm está instalado pero no se está usando todavía en el código

---

Links Relevantes

• TwitchDownloader: https://github.com/lay295/TwitchDownloader
• streamlink: https://streamlink.github.io/
• PyTorch ROCm: https://pytorch.org/
• ROCm: https://rocm.docs.amd.com/