TubeScript-API/QUICKSTART_COMPLETO.md

🚀 Guía de Inicio Rápido - TubeScript API

⚡ Inicio Rápido en 3 Pasos

1️⃣ Crear Red de Docker

./docker-create-network.sh

2️⃣ Iniciar Servicios

# Opción A: Usar el gestor interactivo (Recomendado)
./docker-manager.sh

# Opción B: Iniciar con Docker Compose
docker-compose up -d

# Opción C: Iniciar servicios por separado
./docker-start-api.sh        # Solo API
./docker-start-streamlit.sh  # Solo Streamlit

3️⃣ Acceder al Panel

• Panel Web: http://localhost:8501
• API: http://localhost:8080
• Documentación API: http://localhost:8080/docs

---

🎯 ¿Qué Puedes Hacer?

✨ Funcionalidades Principales

1. 🔍 Buscar Videos en Vivo de YouTube

   • Busca por palabra clave
   • O ingresa URL directa

2. 📺 Seleccionar Video para Transmitir

   • Ve el preview con miniatura
   • Verifica que esté EN VIVO (🔴)

3. ⚙️ Configurar Plataformas de Destino

   • YouTube, Facebook, Twitch, X, Instagram, TikTok
   • Solo necesitas el Stream Key
   • RTMP URLs configuradas por defecto

4. 🎛️ Controlar Transmisiones

   • Switches individuales por plataforma
   • Iniciar/Detener todas a la vez
   • Ver estado en tiempo real

5. 📊 Monitorear en Tiempo Real

   • Semáforos de estado (🟢 🔴 ⚪)
   • PIDs de procesos FFmpeg
   • Tiempo activo de cada transmisión
   • Verificación de salud de procesos

---

🛠️ Gestión de Servicios

Gestor Interactivo (Recomendado)

./docker-manager.sh

Menú disponible:

SERVICIOS:
 1) Iniciar TODOS los servicios
 2) Iniciar solo FastAPI
 3) Iniciar solo Streamlit

CONTROL:
 4) Detener todos los servicios
 5) Reiniciar todos los servicios
 6) Reconstruir contenedores

MONITOREO:
 7) Ver logs de FastAPI
 8) Ver logs de Streamlit
 9) Ver logs de ambos
10) Ver estado de servicios

MANTENIMIENTO:
11) Actualizar yt-dlp
12) Crear red de Docker
13) Limpiar contenedores

UTILIDADES:
14) Abrir panel web
15) Abrir documentación API
16) Editar configuración

Comandos Rápidos

# Iniciar
./docker-start-api.sh          # Solo API
./docker-start-streamlit.sh    # Solo Streamlit
docker-compose up -d           # Ambos servicios

# Detener
./docker-stop-all.sh           # Detener todos
docker-compose down            # Con Docker Compose

# Ver Logs
./docker-logs-separate.sh api        # Logs de API
./docker-logs-separate.sh streamlit  # Logs de Streamlit
docker logs -f tubescript_api        # Direct Docker

# Estado
docker ps                      # Ver contenedores activos
docker stats                   # Ver uso de recursos

---

⚙️ Configuración

1. Variables de Entorno

Crea tu archivo .env (o edita el existente):

cp .env.example .env
nano .env

Configuraciones principales:

# URL del API (para Streamlit)
API_URL=http://tubescript-api:8000  # Dentro de Docker
# API_URL=http://localhost:8080     # Para desarrollo local
# API_URL=https://api.tudominio.com # Para producción

# Puertos
API_PORT=8080
STREAMLIT_PORT=8501

2. Configurar Plataformas

En el panel web (http://localhost:8501):

1. Abre el menú lateral (⚙️ Configuración)

2. Para cada plataforma:

   • ✅ Activa "Habilitar esta plataforma"
   • 🔑 Ingresa tu Stream Key
   • 🌐 (Opcional) Personaliza RTMP URL

3. Guarda la configuración (💾 Guardar Configuración)

URLs RTMP por defecto:

• YouTube: rtmp://a.rtmp.youtube.com/live2
• Facebook: rtmps://live-api-s.facebook.com:443/rtmp/
• Twitch: rtmp://live.twitch.tv/app
• X (Twitter): rtmps://fa.contribute.live-video.net/app
• Instagram: rtmps://live-upload.instagram.com:443/rtmp/
• TikTok: rtmp://push.live.tiktok.com/live/

3. Cookies de YouTube (Opcional)

Si necesitas acceder a videos con restricciones:

# Exporta cookies de tu navegador
# Usa extensión: "Get cookies.txt"
# Guarda como cookies.txt en el directorio raíz

---

📺 Cómo Usar el Panel Web

Flujo Completo

Paso 1: Configurar (Primera vez)

⚙️ Configuración (Sidebar)
├── Activar plataformas deseadas
├── Ingresar Stream Keys
└── Guardar configuración

Paso 2: Buscar Video

🔍 Búsqueda (Tab)
├── Buscar: "noticias", "gaming", etc.
└── O pegar URL directa

Paso 3: Controlar Transmisión

🎛️ Control (Tab)
├── Ver preview del video
├── Activar switches por plataforma
└── O iniciar todas a la vez

Paso 4: Monitorear

📊 Monitor (Tab)
├── Ver estado en tiempo real
├── Verificar PIDs de procesos
├── Tiempo activo
└── Detener si es necesario

---

🔍 Ejemplo Práctico

Transmitir a YouTube y Facebook

# 1. Iniciar servicios
./docker-manager.sh
# Selecciona opción 1

# 2. Abrir panel web
# Opción 14 del menú, o:
open http://localhost:8501

# 3. En el panel:
# - Sidebar → Configurar YouTube y Facebook
# - Búsqueda → Buscar "CNN live"
# - Control → Activar switches de YouTube y Facebook
# - Monitor → Ver que ambas estén transmitiendo 🟢

# 4. Detener cuando termines
# Control → Desactivar switches
# O desde terminal: ./docker-stop-all.sh

---

🎨 Semáforos de Estado

Símbolo	Estado	Significado
🟢	TRANSMITIENDO	Activo y funcionando
⚪	LISTO	Configurado, no transmitiendo
🔴	ERROR	Problema con la transmisión
⚠️	DESHABILITADA	Configurada pero desactivada

---

🆘 Solución de Problemas

❌ "No se pudo obtener la URL del stream"

Causas:

• Video no está EN VIVO (🔴)
• Video con restricciones
• yt-dlp desactualizado

Soluciones:

# Actualizar yt-dlp
./docker-manager.sh
# Selecciona opción 11

# O manualmente:
docker exec streamlit_panel pip install --upgrade yt-dlp

# Reconstruir contenedores
./docker-manager.sh
# Selecciona opción 6

❌ "Error al descargar subtítulos"

Solución:

• El video puede no tener subtítulos disponibles
• Intenta con otro video
• Verifica que el video sea accesible públicamente

❌ "Transmisión se detuvo"

Verificar:

# Ver logs
docker logs streamlit_panel

# Verificar PIDs en el Monitor (Tab)
# Estado del proceso: ✅ Vivo / ❌ Muerto

# Verificar que video siga en vivo
# Verificar Stream Key correcta

❌ "Puerto ya en uso"

Solución:

# Ver qué usa el puerto
lsof -i :8080  # FastAPI
lsof -i :8501  # Streamlit

# Cambiar puerto en docker-compose.yml
# O detener el proceso que lo usa

---

📊 Arquitectura

┌─────────────────────────────────────────────┐
│         Panel Web Streamlit (8501)          │
│  ┌────────┬────────────┬──────────────┐    │
│  │Búsqueda│  Control   │   Monitor    │    │
│  └────────┴────────────┴──────────────┘    │
└─────────────────┬───────────────────────────┘
                  │ HTTP
┌─────────────────▼───────────────────────────┐
│        FastAPI Backend (8000/8080)          │
│  /stream/{video_id} - Obtener URL m3u8     │
│  /transcript/{video_id} - Obtener subtíts. │
└─────────────────┬───────────────────────────┘
                  │ yt-dlp
┌─────────────────▼───────────────────────────┐
│              YouTube Live                   │
│         (Extrae URL m3u8 HLS)              │
└─────────────────┬───────────────────────────┘
                  │ URL m3u8
┌─────────────────▼───────────────────────────┐
│          Procesos FFmpeg (PIDs)             │
│  ┌─────────┬──────────┬────────────────┐   │
│  │YouTube  │ Facebook │  Twitch  ...   │   │
│  │PID:1234 │PID:1235  │  PID:1236      │   │
│  └─────────┴──────────┴────────────────┘   │
└─────────────────┬───────────────────────────┘
                  │ RTMP/RTMPS
┌─────────────────▼───────────────────────────┐
│          Plataformas de Destino             │
│  YouTube │ Facebook │ Twitch │ X │ etc.    │
└─────────────────────────────────────────────┘

---

📝 Archivos de Configuración

TubeScript-API/
├── stream_config.json       # Configuración de plataformas
├── process_state.json       # Estado de procesos FFmpeg
├── streams_state.json       # Estado de transmisiones
├── cookies.txt              # Cookies de YouTube (opcional)
└── .env                     # Variables de entorno

---

🚀 Actualizar el Sistema

# 1. Detener servicios
./docker-stop-all.sh

# 2. Obtener últimos cambios (si usas Git)
git pull

# 3. Reconstruir contenedores
docker-compose build --no-cache

# 4. Iniciar servicios
docker-compose up -d

# 5. Actualizar yt-dlp
docker exec tubescript_api pip install --upgrade yt-dlp
docker exec streamlit_panel pip install --upgrade yt-dlp

O usando el gestor:

./docker-manager.sh
# Selecciona: 6) Reconstruir contenedores
# Luego: 11) Actualizar yt-dlp

---

📚 Documentación Completa

• Panel Streamlit: Guía detallada del panel web
• Comandos Docker: Comandos separados
• Docker Guide: Guía completa de Docker
• API Config: Configuración de URLs

---

🔗 Enlaces Útiles

• Panel Web: http://localhost:8501
• API FastAPI: http://localhost:8080
• API Docs: http://localhost:8080/docs
• API Redoc: http://localhost:8080/redoc

---

💡 Consejos y Trucos

Para Desarrollo

# Usar API externa en Streamlit
echo "API_URL=http://192.168.1.100:8080" > .env
./docker-start-streamlit.sh

Para Producción

# Usar dominio real
echo "API_URL=https://api.tudominio.com" > .env
docker-compose up -d

Para Debugging

# Ejecutar en modo interactivo
docker run -it --rm \
  --network tubescript-network \
  -p 8080:8000 \
  tubescript-api \
  uvicorn main:app --host 0.0.0.0 --port 8000

---

📦 Requisitos del Sistema

Mínimos:

• Docker 20.10+
• 2 GB RAM
• 5 GB Disco
• 10 Mbps Upload

Recomendados:

• Docker 24+
• 4 GB RAM
• 10 GB SSD
• 25 Mbps Upload (por transmisión)

---

🎯 Próximos Pasos

1. ✅ Configura tus plataformas
2. ✅ Prueba con un video en vivo
3. ✅ Monitorea el estado en tiempo real
4. 📖 Lee la Guía Completa del Panel
5. 🚀 ¡Comienza a transmitir!

---

📞 Soporte

¿Problemas? Revisa:

1. Los logs: docker logs -f streamlit_panel
2. El estado: docker ps
3. La documentación completa en los archivos MD

---

TubeScript API Pro © 2026
Transmite en vivo a múltiples plataformas simultáneamente 🚀