Primeros pasos con SupoClip: convierte vídeos largos en clips verticales automáticamente
SupoClip resuelve un problema muy directo: dado un vídeo largo — podcast, entrevista, repetición en directo— encuentra automáticamente los 3 a 7 fragmentos con mayor potencial de difusión, los puntúa según su atractivo y los renderiza como clips verticales 9:16 con subtítulos palabra por palabra, recorte centrado en la cara y ganchos de título. Todo el proceso se ejecuta en tu propio hardware, sin marcas de agua ni bloqueo de plataforma.
La cadena técnica se divide en cinco etapas: AssemblyAI o Whisper para la transcripción y obtener marcas de tiempo palabra por palabra; el LLM selecciona los fragmentos destacados de la transcripción y les asigna una puntuación; la detección facial decide quién aparece en el centro del encuadre vertical; los subtítulos se muestran palabra por palabra según la línea de tiempo; por último, FFmpeg une y exporta. El frontend es Next.js, el backend es FastAPI, las tareas en segundo plano las ejecuta un worker ARQ que consume la cola de Redis, y PostgreSQL almacena los datos de usuarios y tareas.
Dependencias principales y entorno
Primero, asegúrate de tener los requisitos básicos:
- Git
- Docker Engine o Docker Desktop, con el plugin Compose
- Al menos 10 GB de espacio libre en disco (los archivos de vídeo, la caché de modelos y los archivos intermedios de renderizado ocupan espacio)
- La CPU es suficiente, pero las fases de transcripción y renderizado serán lentas; si tienes una GPU NVIDIA, puedes desactivar
BACKEND_CPU_ONLYpara acelerar
Dos claves obligatorias:
- Clave de API de AssemblyAI: para transcripción, ruta predeterminada
- Una clave de un proveedor de LLM: elige entre Google, OpenAI, Anthropic u OpenRouter
Si quieres ejecutarlo completamente en local, puedes cambiar la transcripción a Whisper y el modelo de selección a Ollama, de modo que no necesitarás ninguna clave de API.
Estructura del proyecto
supoclip/
├── frontend/ # Frontend Next.js, puerto 3107, autenticación y solicitudes proxy al backend
├── backend/ # Backend FastAPI, puerto 8000, incluye documentación interactiva de API en /docs
├── worker/ # Proceso de tareas en segundo plano ARQ, maneja transcripción, análisis y renderizado
├── mcp/ # Servidor MCP para que Claude/Cursor lo invoquen
├── docs/ # Documentación de configuración, ajustes, solución de problemas, etc.
├── scripts/ # Scripts de operación como reparación de base de datos
├── docker-compose.yml # Orquestación de cinco servicios: frontend/backend/worker/postgres/redis
└── .env.example # Plantilla de variables de entorno
Los datos se almacenan en volúmenes con nombre: postgres_data, redis_data, uploads, clips. Además, el backend monta dos directorios locales, backend/fonts y backend/transitions, para las fuentes de subtítulos y los recursos de transición, respectivamente.
Pasos de implementación paso a paso
1. Clona el repositorio y prepara el archivo de entorno
git clone https://github.com/FujiwaraChoki/supoclip.git
cd supoclip
cp .env.example .env
Edita .env y al menos completa estos tres campos:
ASSEMBLY_AI_API_KEY=tu_clave_assemblyai
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=tu_clave_google
2. Configura el modelo de selección de fragmentos destacados
La variable LLM determina qué modelo te ayuda a seleccionar los fragmentos. Además de los modelos en la nube como Gemini, GPT, Claude, también puedes usar el prefijo ollama: para apuntar a cualquier servicio compatible con el protocolo v1/chat/completions. Por ejemplo, usa Defapi para conectarte a un modelo local:
LLM=ollama:tu_id_de_modelo
OLLAMA_BASE_URL=https://api.defapi.org/v1
OLLAMA_API_KEY=tu_clave_defapi
El prefijo ollama: en SupoClip solo selecciona el tipo de cliente, no obliga a ejecutar Ollama localmente. En el código, OllamaProvider usa AsyncOpenAI para recibir la URL base y la clave de API, por lo que, siempre que el servicio de destino sea compatible con el protocolo de completado de chat de OpenAI, funcionará. Defapi es uno de esos servicios, con un precio de aproximadamente la mitad del canal oficial, y todos los modelos son básicamente compatibles con los tres protocolos: v1/chat/completions, v1/messages y v1beta/models/. La viabilidad de la selección se comprueba con pruebas reales; la transcripción y la edición de IA en el estudio de edición siguen siendo rutas independientes.
3. Compila e inicia
./start.sh
Si no quieres esperar al script, puedes hacerlo manualmente:
docker-compose up -d --build
La primera compilación requiere descargar imágenes e instalar dependencias; en una máquina con CPU puede tardar unos minutos. Usa el siguiente comando para monitorear el progreso:
docker-compose logs -f
Cuando veas que los cinco servicios están healthy, significa que se han iniciado correctamente:
docker-compose ps
4. Comprueba el estado de salud de los servicios
Abre estas direcciones para confirmar:
- Frontend: http://localhost:3107
- Verificación de salud del backend: http://localhost:8000/health
- Documentación interactiva de API: http://localhost:8000/docs
En la salida de docker-compose ps deberías ver cinco contenedores: supoclip-frontend, supoclip-backend, supoclip-worker, supoclip-postgres, supoclip-redis.
5. Crea una cuenta y sube un vídeo
Abre la página principal del frontend en el navegador y regístrate. La página principal admite dos tipos de entrada: pegar un enlace de YouTube/Twitch/Kick, o subir directamente un archivo de vídeo local. Ten en cuenta que el límite de carga predeterminado es de 4 GB, suficiente para un vídeo completo de 1080p con tasa de bits normal.
6. Previsualiza, edita y exporta clips verticales
Después de enviar la tarea, la página de tareas mostrará el progreso en tiempo real: el estado de las fases de transcripción, análisis de IA y renderizado se enviará. Al completarse, podrás ver la duración de cada fragmento, el extracto de transcripción, el motivo de selección de IA y la puntuación de potencial de difusión.
Al entrar al estudio de edición, podrás hacer estos ajustes:
- Arrastrar los bordes del fragmento para recortar el inicio y el final
- Dividir un fragmento largo en varios más pequeños
- Fusionar varios fragmentos
- Reescribir el texto de los subtítulos
- Cambiar el estilo de los subtítulos (fuente, animación, tamaño, color)
- Exportar con ajustes preestablecidos por plataforma: TikTok, Reels, Shorts
Al exportar, selecciona «Vertical output» y obtendrás un clip vertical 9:16 con recorte centrado en la cara y subtítulos palabra por palabra ya incrustados.
Solución de problemas comunes
La página del frontend no se abre
Verifica el puerto del host. La plantilla predeterminada usa FRONTEND_PORT=3107; si estás actualizando desde una versión anterior y .env no tiene esta variable, se revertirá a 3001. Usa docker-compose port frontend 3107 para ver el mapeo real.
Error de inicio de sesión: Invalid origin
NEXT_PUBLIC_APP_URL y BETTER_AUTH_URL deben coincidir exactamente con la dirección del navegador, incluidos el protocolo y el puerto. localhost y 127.0.0.1 son dos orígenes diferentes. Si accedes desde un dominio o puerto distinto, debes configurar BETTER_AUTH_TRUSTED_ORIGINS como una lista explícita separada por comas; no se admiten comodines.
La tarea permanece en estado 'queued'
Primero revisa los logs del worker. docker-compose logs -f worker mostrará cualquier información de error que exponga el problema. Luego verifica el latido del worker con curl -f http://localhost:8000/health/worker; si devuelve 503, significa que el worker está desconectado o no puede conectarse a Redis. El latido de ARQ caduca aproximadamente cada 31 segundos.
La transcripción se atasca al 30%
Esta fase está llamando a AssemblyAI. Revisa los logs del backend para confirmar si la clave de API es válida y si el saldo de la cuenta es suficiente. La verificación de estado tiene un presupuesto de tiempo de espera general, con un valor predeterminado de 900 segundos; si se agota, se reintentará la misma tarea de transcripción sin costo adicional. Para vídeos largos, puedes aumentar ASSEMBLY_AI_HTTP_TIMEOUT_SECONDS.
El modelo de selección da error o el formato de salida no es el correcto
El prefijo de LLM y la clave del proveedor deben coincidir: ollama: con OLLAMA_BASE_URL y OLLAMA_API_KEY, google-gla: con GOOGLE_API_KEY, y así sucesivamente. Si un modelo local devuelve JSON con estructura no válida, el agente reintentará hasta dos veces (output_retries=2). Cambiar a un modelo con mejores capacidades de seguimiento de instrucciones suele resolverlo.
Al crear la cuenta, aparece 'Failed to create account'
Probablemente el esquema de la base de datos está desactualizado respecto al código. Ejecuta el script de reparación idempotente, que solo agrega columnas sin tocar los datos existentes:
docker compose exec -T postgres psql -U supoclip -d supoclip < scripts/selfhost-schema-repair.sql
Nunca ejecutes prisma db push o prisma migrate deploy en esta base de datos; el backend maneja varias tablas que Prisma no conoce, y db push las eliminaría.
Lectura adicional / Direcciones avanzadas
- Ruta completamente local: Cambia
TRANSCRIPTION_PROVIDERawhisper, y para la selección usaLLM=ollama:...con un servicio Ollama local. Ten en cuenta que la dirección predeterminada de Ollama en Docker eshttp://host.docker.internal:11434/v1, por lo que Ollama en la máquina host debe escuchar en ese puerto. - Integración MCP: El directorio
mcp/del repositorio proporciona un servidor MCP que permite invocar las capacidades de edición de SupoClip directamente desde clientes como Claude o Cursor. - API REST: Genera una clave de API en
/settings/api-keysy llama directamente a las interfaces del backend, ideal para procesamiento por lotes mediante scripts. - Material de archivo (B-roll): Configura
PEXELS_API_KEYpara que, después de la selección de IA, se emparejen automáticamente vídeos de archivo gratuitos de Pexels como tomas ilustrativas. - Límites de licencia: La versión actual está bajo la Licencia de Código Fuente No Comercial SupoClip 1.1; el uso no comercial y la monetización de creadores individuales en redes sociales son gratuitos, pero empresas, instituciones, equipos o servicios de edición por encargo deben solicitar permiso por escrito por correo. Antes de empezar, lee el archivo
LICENSE, especialmente la definición de «Creadores Individuales».