Streamliner-AI 🤖🎬

Streamliner-AI es un pipeline 100% automático y asíncrono en Python, diseñado para monitorizar streamers de Kick, detectar momentos virales de alta emoción, generar clips verticales optimizados para redes sociales y publicarlos en TikTok sin intervención manual.

Este proyecto utiliza la API oficial de Kick, autenticándose vía OAuth2 (Client Credentials) para una monitorización estable, eficiente y robusta.

📋 Tabla de Contenidos

✨ Características Principales
⚙️ Arquitectura del Sistema
🚀 Guía de Inicio Rápido
🔧 Instalación y Configuración Detallada
💻 Uso de la Aplicación
🐳 Despliegue con Docker
🛠️ Guía de Desarrollo
🧠 Profundización Técnica: El Camino a la API Oficial
📈 Mejoras Futuras

✨ Características Principales

Autenticación Oficial: Se conecta a la API de Kick usando el flujo OAuth2 Client Credentials, garantizando un acceso estable y autorizado.
Monitorización Asíncrona: Utiliza asyncio y httpx para vigilar múltiples streamers de forma concurrente y eficiente con un solo proceso.
Detección Inteligente y Eficiente:
- Analiza la energía del audio (RMS) para encontrar picos de emoción rápidamente.
- Utiliza faster-whisper para transcribir únicamente los segmentos de alta energía, ahorrando tiempo de procesamiento.
- Un sistema de puntuación personalizable combina la energía del audio y más de 200 palabras clave y jergas peruanas para identificar los mejores momentos.
Renderizado Vertical Automático: Emplea ffmpeg para crear clips en formato 9:16 con fondo desenfocado, el clip original centrado y subtítulos quemados con estilos personalizables.
Publicación en TikTok: Se integra con la API de Contenido de TikTok para subir los clips generados de forma automática.
CLI Robusta: Interfaz de Línea de Comandos basada en click para una gestión sencilla.
Listo para Producción: Incluye configuración para Docker, pruebas unitarias y un pipeline de Integración Continua (CI) con GitHub Actions.

⚙️ Arquitectura del Sistema

El sistema opera como un pipeline estable que utiliza la autenticación oficial de Kick para asegurar el acceso a los datos.

🚀 Guía de Inicio Rápido

Sigue estos pasos para poner en marcha Streamliner AI en tu sistema.

1. Requisitos Previos (¡Importante!)

Antes de instalar las dependencias de Python, asegúrate de tener lo siguiente:

Python 3.10 o superior (descárgalo de python.org).
FFmpeg (¡CRÍTICO!): FFmpeg es esencial para el procesamiento de audio y video (extracción, corte, renderizado). Sin él, la aplicación no funcionará.

Instalación de FFmpeg:
- Windows:
  1. Ve a ffmpeg.org/download.html y descarga una de las builds recomendadas (ej. gpl.zip de gyan.dev).
  2. Descomprime el archivo ZIP en una ubicación fácil de recordar (ej. C:\ffmpeg).
  3. ¡Añade la carpeta bin de FFmpeg a tu variable de entorno PATH de Windows! (ej. C:\ffmpeg\bin).
    - Busca "Editar las variables de entorno del sistema" en el menú de inicio.
    - Haz clic en "Variables de entorno...".
    - En "Variables del sistema", busca Path, selecciona "Editar".
    - Haz clic en "Nuevo" y añade la ruta completa a la carpeta bin (ej. C:\ffmpeg\bin).
    - Cierra y vuelve a abrir tu terminal (CMD/PowerShell) para que los cambios surtan efecto.
  4. Verifica la instalación abriendo una nueva terminal y escribiendo ffmpeg -version.
- macOS (usando Homebrew):
```
brew install ffmpeg
```
- Linux (ej. Debian/Ubuntu):
```
sudo apt update
sudo apt install ffmpeg
```
- Verificación (cualquier SO): Abre una nueva terminal y ejecuta:
```
ffmpeg -version
```
  Deberías ver información sobre la versión de FFmpeg instalada. Si ves un error como "command not found", algo salió mal con la instalación o la configuración del PATH.

2. Configuración del Entorno de Desarrollo

Clona el repositorio y configura tu entorno virtual:

# 1. Clonar el repositorio
git clone https://github.com/tu-usuario/streamliner-ai.git
cd streamliner-ai

# 2. Crear entorno virtual (ej. con Python 3.13.3)
python -m venv venv

# Activar el entorno
# En Windows/PowerShell:
.\venv\Scripts\Activate
# En Linux/macOS:
source venv/bin/activate

# 3. Instalar dependencias
pip install -r requirements.txt

# 4. Configurar
# (Obtén CLIENT_ID y CLIENT_SECRET del portal de desarrolladores de Kick)
cp .env.template .env
cp config.yaml.example config.yaml
# (Edita .env y config.yaml con tus datos)

# 5. Ejecutar una prueba con un video local
python -m src.streamliner.cli process "data/video.mp4" --streamer "test" --dry-run

# 6. Iniciar el modo de monitorización
python -m src.streamliner.cli monitor

🔧 Instalación y Configuración Detallada

Prerrequisitos

Git: Para clonar el repositorio.
Python (3.10 - 3.13): Este proyecto fue desarrollado y probado exitosamente con Python 3.13.3. Se recomienda usar una versión igual o superior a la 3.10 para asegurar la compatibilidad de las librerías.
FFmpeg: Dependencia de sistema crucial para cualquier operación de video/audio. Debe estar instalado y accesible en el PATH de tu sistema.
Cuenta de Desarrollador de Kick: Necesaria para obtener las credenciales de la API.

Pasos de Instalación

Sigue los pasos de la 🚀 Guía de Inicio Rápido. El comando python -m venv venv usará la versión de Python que tengas por defecto en tu sistema.

Configuración de la API de Kick

Crea una Aplicación: Ve al Portal de Desarrolladores de Kick y crea una nueva aplicación.
Redirect URL: Durante la creación, te pedirá una "Redirect URL". Ingresa http://localhost o http://localhost:8080. Este campo es obligatorio pero no se usa en nuestro flujo de autenticación.
Scopes: Selecciona los permisos (scopes) que necesitará tu aplicación. Para este proyecto, se recomiendan:
- channel:read (Leer información del canal) - Esencial.
- user:read (Leer información de usuario).
Obtén tus Credenciales: Una vez creada la aplicación, Kick te proporcionará un Client ID y un Client Secret.

Configuración de la API de TikTok

Para que Streamliner AI pueda publicar clips en tu cuenta de TikTok, necesitas obtener y configurar los tokens de autenticación iniciales.

Configura tu Aplicación en TikTok Developer Center: Asegúrate de haber registrado tu aplicación en el TikTok Developer Center y haber obtenido tu Client Key y Client Secret. Es crucial también configurar un "Redirect URI" válido (por ejemplo, https://www.example.com/oauth) en la configuración de tu aplicación de TikTok.
Añade tus Credenciales Básicas al .env: Abre tu archivo .env en la raíz del proyecto y añade las siguientes líneas con tus claves obtenidas del Developer Center:
```
TIKTOK_CLIENT_KEY=tu_client_key_aqui
TIKTOK_CLIENT_SECRET=tu_client_secret_aqui
```
Ejecuta el Generador de Tokens: Abre tu terminal en la raíz del proyecto y ejecuta el script de utilidad diseñado para esto:
```
python scripts/generate_tiktok_tokens.py
```
El script te proporcionará una URL de autorización.
Autoriza la Aplicación en tu Navegador:
- Copia la URL proporcionada por el script y pégala en tu navegador web.
- Inicia sesión en TikTok con la cuenta en la que deseas que el bot publique los clips.
- Revisa y autoriza la aplicación para acceder a los scopes solicitados (user.info.basic, video.upload, video.list, etc.).
- Después de la autorización, serás redirigido a tu Redirect URI. La URL en tu navegador contendrá el code y el open_id en los parámetros de la URL (por ejemplo: https://www.example.com/oauth?code=ABC...XYZ&open_id=123...456).
Introduce los Datos en la Terminal: Copia el valor del code y el open_id de la URL de redirección y pégalos en la terminal cuando el script generate_tiktok_tokens.py te lo pida.
Tokens Guardados Automáticamente: El script procesará estos datos y guardará automáticamente el TIKTOK_ACCESS_TOKEN, TIKTOK_REFRESH_TOKEN y TIKTOK_OPEN_ID en tu archivo .env. ¡Tu bot ya estará configurado para interactuar con la API de TikTok!

Nota: El TIKTOK_ACCESS_TOKEN se refrescará automáticamente según sea necesario, por lo que no tendrás que ejecutar este script con frecuencia una vez que hayas obtenido los tokens iniciales. Para pruebas en desarrollo, asegúrate de que TIKTOK_ENVIRONMENT=sandbox esté configurado en tu .env; para producción, cámbialo a TIKTOK_ENVIRONMENT=production (una vez que tu aplicación haya sido aprobada por TikTok).

Configuración del Proyecto

Variables de Entorno (.env): Copia la plantilla cp .env.template .env y rellena los siguientes campos con tus credenciales:

KICK_CLIENT_ID="el_id_que_te_dio_kick"
KICK_CLIENT_SECRET="el_secreto_que_te_dio_kick"

# Rellena también las credenciales para TikTok y S3/R2 si los usarás.

Configuración de la Aplicación (config.yaml): Copia la plantilla cp config.yaml.example config.yaml y edita la lista de streamers: con los nombres de los canales de Kick que quieres monitorizar.

💻 Uso de la Aplicación

Asegúrate de tener siempre el entorno virtual activado (source venv/bin/activate).

Modo Monitor (Producción): Es el modo principal, diseñado para correr 24/7. Vigilará a los streamers de tu configuración y procesará sus VODs automáticamente.
```
python -m src.streamliner.cli monitor
```
Para detenerlo, presiona Ctrl + C en la terminal.

Modo de Procesamiento Manual (Pruebas): Procesa un video que ya tengas descargado.

python -m src.streamliner.cli process --file "ruta/del/video.mp4" --streamer "nombre_streamer" --dry-run

🛰️ Comandos CLI para TikTok (Sandbox y Producción)

Estos comandos permiten probar y operar la publicación de clips en TikTok desde la línea de comandos. Asegúrate de haber configurado la sección de TikTok en .env y config.yaml antes de usarlos.

upload: sube un archivo local a TikTok según la estrategia configurada.

# Subir un clip local como borrador (inbox) en SANDBOX con estrategia automática
python -m src.streamliner.cli upload \
    --file "data/clips_generados/mi_clip_rendered.mp4" \
    --streamer "test"

# Forzar estrategia específica (MULTIPART|BYTES|DIRECT_POST) y deshabilitar fallback
python -m src.streamliner.cli upload \
    --file "data/clips_generados/mi_clip_rendered.mp4" \
    --streamer "test" \
    --strategy MULTIPART \
    --no-fallback

tiktok-diagnose: imprime el estado persistente del SANDBOX para evitar reintentos fútiles.

python -m src.streamliner.cli tiktok-diagnose
# Ejemplo de salida: {"last_spam_risk_ts": 1758539474.15, "bytes_unavailable": true}

tiktok-clear-sandbox-state: limpia el estado persistente del SANDBOX.
```
python -m src.streamliner.cli tiktok-clear-sandbox-state
```

upload-when-ready: espera el cooldown/backoff y reintenta la subida automáticamente.

python -m src.streamliner.cli upload-when-ready \
    --file "data/clips_generados/mi_clip_rendered.mp4" \
    --streamer "test" \
    --max-wait-seconds 2400 \
    --poll-interval 20

Notas importantes (especialmente en SANDBOX):

En SANDBOX, la estrategia recomendada es MULTIPART. La app maneja automáticamente:
- Cálculo de chunks correcto y reintentos puntuales.
- Persistencia de backoff ante spam_risk_too_many_pending_share (evita spamear INIT).
- Confirmación/finalización “best-effort” del inbox publish.
El método BYTES suele responder 403/404 en SANDBOX si tu app no tiene acceso. Por defecto está deshabilitado vía config.yaml y el sistema persiste bytes_unavailable tras detectar este caso.
DIRECT_POST requiere el scope de producción video.publish y, típicamente, aprobación de app. En SANDBOX normalmente no está disponible.

Parámetros relevantes en config.yaml (sección de publicación):

publishing.upload_strategy: AUTO|MULTIPART|BYTES|DIRECT_POST.
publishing.upload_cooldown_seconds: espera breve antes de iniciar una subida.
publishing.sandbox_spam_backoff_seconds: backoff ante spam_risk en SANDBOX.
publishing.sandbox_allow_bytes_upload: false por defecto (BYTES deshabilitado en SANDBOX).
publishing.sandbox_allow_direct_post: false por defecto.

🐳 Despliegue con Docker

Docker simplifica el despliegue al empaquetar la aplicación con todas sus dependencias (incluyendo ffmpeg).

Construye la imagen: docker-compose build
Inicia el servicio: docker-compose up -d
Ver los logs: docker-compose logs -f
Detener el servicio: docker-compose down

🛠️ Guía de Desarrollo

Configuración de Visual Studio Code

Crea una carpeta .vscode en la raíz del proyecto con los siguientes archivos para una experiencia de desarrollo óptima.

.vscode/settings.json (habilita el formateo automático con ruff)

{
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll": true
        }
    }
}

.vscode/launch.json (permite depurar con F5)

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Monitor Mode",
            "type": "python",
            "request": "launch",
            "module": "src.streamliner.cli",
            "args": ["monitor"],
            "console": "integratedTerminal"
        },
        {
            "name": "Process Local File (Dry Run)",
            "type": "python",
            "request": "launch",
            "module": "src.streamliner.cli",
            "args": [
                "process",
                "--file", "data/test_video.mp4", // Cambia esto a un video de prueba
                "--streamer", "teststreamer",
                "--dry-run"
            ],
            "console": "integratedTerminal"
        }
    ]
}

El repositorio está configurado para una experiencia de desarrollo fluida con VS Code y pruebas automatizadas. Consulta los archivos .vscode/settings.json, .vscode/launch.json y .github/workflows/ci.yml para más detalles.

Ejecutar chequeos de calidad localmente:

# Revisa errores lógicos
ruff check .
# Revisa y arregla el formato del código
ruff format .

Ejecutar pruebas unitarias:
```
pytest
```

🧠 Profundización Técnica:

Async-first: La elección de asyncio permite manejar múltiples operaciones de I/O (esperas de red para la API de Kick, descargas de video, subidas) de forma concurrente en un solo hilo, lo que es mucho más eficiente en recursos que un enfoque basado en hilos tradicional.
- Subprocesos No Bloqueantes: Usamos asyncio.create_subprocess_exec para llamar a ffmpeg y streamlink. Esto permite que nuestro programa principal continúe funcionando y manejando otras tareas mientras estos programas externos, que pueden tardar mucho, hacen su trabajo en segundo plano.
- Detector Optimizado: La decisión de no transcribir el VOD completo es la optimización más importante del sistema. El análisis de energía RMS es computacionalmente muy barato y actúa como un filtro de alta velocidad para reducir un VOD de horas a solo unos minutos de audio "interesante", que son los únicos que se procesan con el costoso modelo de IA.

El Camino a la API Oficial

El desarrollo de este monitor fue un caso de estudio en perseverancia y depuración de sistemas anti-bots. Los intentos iniciales de acceder a los endpoints de Kick mediante httpx y Playwright (simulando ser un navegador) fueron consistentemente bloqueados con errores 403 Forbidden por una robusta política de seguridad de Cloudflare (probablemente basada en TLS/JA3 Fingerprinting).

La solución definitiva, descubierta a través de investigación y pruebas con Google Apps Script, fue abandonar los endpoints no oficiales y utilizar el flujo de autenticación client_credentials de OAuth2, que es el método oficial que Kick proporciona a los desarrolladores.

El monitor actual implementa esta estrategia:

Solicita un App Access Token al endpoint https://id.kick.com/oauth/token usando las credenciales de desarrollador.
Almacena este token en memoria y lo refresca automáticamente antes de que expire.
Utiliza el token para hacer llamadas autenticadas al endpoint público /public/v1/channels, que permite consultar el estado de múltiples streamers de forma eficiente.

Este enfoque es más estable, ligero (no requiere un navegador completo) y respetuoso con la plataforma.

📈 Mejoras Futuras

Gestión Avanzada de Tokens: Guardar el access_token y su tiempo de expiración en un archivo o una base de datos (como Redis) para que el estado persista si se reinicia el bot.
Procesamiento en Tiempo Real: Rediseñar el downloader para que trabaje con "chunks" de video, permitiendo la creación de clips a los pocos minutos de que ocurra la acción en vivo.
Dashboard de Métricas: Integrar Prometheus y Grafana para visualizar el estado de los monitores, clips generados, etc.
Scoring con Machine Learning: Entrenar un modelo más avanzado que pueda analizar no solo el audio, sino también la velocidad del chat o eventos del juego para una detección de highlights más precisa.
Soporte Multiplataforma: Abstraer los módulos para añadir soporte para Twitch, YouTube y otras plataformas de destino.

Este proyecto representa un intenso viaje de desarrollo, desde la idea inicial hasta una solución robusta y funcional. Para su construcción y depuración, conté con la asistencia de un modelo de IA avanzado, lo que me permitió explorar diferentes arquitecturas y resolver complejos desafíos técnicos, como eludir protecciones anti-bot y, finalmente, implementar la API oficial de Kick.

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
.github		.github
assets		assets
scripts		scripts
src		src
tests		tests
.env.template		.env.template
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
config.yaml		config.yaml
config.yaml.example		config.yaml.example
docker-composer.yml		docker-composer.yml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Streamliner-AI 🤖🎬

📋 Tabla de Contenidos

✨ Características Principales

⚙️ Arquitectura del Sistema

🚀 Guía de Inicio Rápido

1. Requisitos Previos (¡Importante!)

2. Configuración del Entorno de Desarrollo

🔧 Instalación y Configuración Detallada

Prerrequisitos

Pasos de Instalación

Configuración de la API de Kick

Configuración de la API de TikTok

Configuración del Proyecto

💻 Uso de la Aplicación

🛰️ Comandos CLI para TikTok (Sandbox y Producción)

🐳 Despliegue con Docker

🛠️ Guía de Desarrollo

Configuración de Visual Studio Code

🧠 Profundización Técnica:

El Camino a la API Oficial

📈 Mejoras Futuras

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Streamliner-AI 🤖🎬

📋 Tabla de Contenidos

✨ Características Principales

⚙️ Arquitectura del Sistema

🚀 Guía de Inicio Rápido

1. Requisitos Previos (¡Importante!)

2. Configuración del Entorno de Desarrollo

🔧 Instalación y Configuración Detallada

Prerrequisitos

Pasos de Instalación

Configuración de la API de Kick

Configuración de la API de TikTok

Configuración del Proyecto

💻 Uso de la Aplicación

🛰️ Comandos CLI para TikTok (Sandbox y Producción)

🐳 Despliegue con Docker

🛠️ Guía de Desarrollo

Configuración de Visual Studio Code

🧠 Profundización Técnica:

El Camino a la API Oficial

📈 Mejoras Futuras

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages