Práctica con PeakCut: crea tu propia herramienta de edición de videos cortos con IA

Lo que más tiempo consume al hacer videos cortos no es la edición, sino encontrar los pocos segundos que valen la pena publicar en una o dos horas de transmisión en vivo o video largo. PeakCut automatiza este flujo: ejecuta reconocimiento de voz localmente, la IA te ayuda a elegir los momentos destacados, los corta automáticamente en formato vertical 9:16 y los subtitula palabra por palabra. Lo más atractivo es que todo el proceso puede ejecutarse completamente en tu propia computadora, y los datos de video y audio no salen de tu máquina.

Su flujo de trabajo es muy directo: transcribe el audio, deja que la IA decida qué segmentos pueden retener la atención de extraños, y luego usa FFmpeg para renderizar clips verticales con subtítulos. La transcripción usa sherpa-onnx y el modelo Parakeet, que se ejecutan completamente en local; la IA solo se encarga de seleccionar segmentos y escribir títulos, y puedes usar cualquier proveedor, no importa cuál, siempre que sea compatible con la API de OpenAI.

Si no quieres usar la API oficial de ChatGPT, Defapi es una buena opción. Su precio es la mitad del oficial, y todos sus modelos son básicamente compatibles con protocolos comunes como v1/chat/completions, v1/messages, y v1beta/models/. Por lo tanto, el proveedor personalizado (Custom provider) de PeakCut puede conectarse directamente, y la configuración es exactamente la misma que se describe en el paso 3 a continuación.

Dependencias clave y entorno

Antes de comenzar, asegúrate de tener lo siguiente:

  • Python 3.10+: El entorno de ejecución del programa principal.
  • FFmpeg: Se usa para todo el procesamiento de video y audio. En Windows usa winget install Gyan.FFmpeg, en macOS brew install ffmpeg, y en Linux sudo apt install ffmpeg.
  • Red y almacenamiento: En el primer inicio se descargarán unos 480MB de modelos de voz. Los archivos de video no son pequeños, se recomienda reservar más de 20GB de espacio en disco.
  • Clave de IA (opcional): También se puede usar sin configurar, en ese caso PeakCut seleccionará segmentos basándose en el volumen, pero no generará títulos con IA.

PeakCut recomienda colocar el proyecto en una ruta fija, como C:\peakcut (Windows) o ~/peakcut (macOS/Linux). No lo pongas en un directorio temporal; en Windows, una ruta demasiado profunda puede causar errores de carga del modelo de voz.

Estructura de árbol del proyecto

peakcut/
├── studio/                  # Código principal del servidor
│   ├── server.py            # Punto de entrada de FastAPI
│   ├── ai.py                # Capa de adaptación del servicio de IA (agrega nuevos proveedores aquí)
│   ├── transcribe.py        # Transcripción de voz local
│   ├── jobs.py              # Flujo de trabajos de edición
│   ├── render.py            # Renderizado de subtítulos y composición de video
│   └── fonts/               # Archivos de fuentes de subtítulos
├── web/                     # Páginas del frontend (HTML/CSS/JS puro)
├── deploy/                  # Configuración de despliegue con Docker
├── tests/                   # Pruebas automatizadas
├── requirements.txt         # Dependencias de Python
├── .env.example             # Plantilla de variables de entorno
└── Dockerfile

Guía paso a paso

1. Clonar el repositorio e instalar dependencias

git clone https://github.com/haziqahmedqasmi/peakcut.git ~/peakcut
cd ~/peakcut
pip install -r requirements.txt

Se recomienda usar un entorno virtual para evitar contaminar los paquetes globales de Python.

2. Iniciar el servicio local

python -m studio.server

En el primer inicio, se descargará automáticamente el modelo de voz (aproximadamente 480MB), lo que tomará un tiempo. Verás una salida como Uvicorn running on http://127.0.0.1:8765 que indica que el servicio se ha levantado.

Abre tu navegador en http://127.0.0.1:8765 para acceder directamente a la consola, sin necesidad de iniciar sesión.

3. Configurar el servicio de IA

Entra a la página Settings → AI. Aquí eliges tu proveedor de servicios de IA. La IA de PeakCut se encarga de dos cosas: decidir qué segmentos vale la pena cortar y escribir títulos para los segmentos. Necesita un modelo de chat que pueda devolver JSON, no un servicio de transcripción de voz—la transcripción siempre se ejecuta en local.

En el menú desplegable selecciona Custom (OpenAI-compatible). Aparecerá un campo para la URL base (Base URL). Introduce la dirección de tu proveedor, pega tu clave de API en el campo Key, escribe manualmente el nombre de un modelo de chat que admita salida JSON, y luego haz clic en Find models para obtener la lista de modelos disponibles (si tu proveedor lo admite). Finalmente, haz clic en Save and test.

Por ejemplo, Defapi ofrece una API compatible con OpenAI a la mitad del precio oficial. La configuración es la siguiente:

  • Base URL: https://api.defapi.org/v1
  • Key: Se obtiene en la consola de la plataforma Defapi
  • Modelo: Introduce un ID de modelo de chat que admita salida JSON, como your-model-id (el ID específico depende de la lista en tu panel de cuenta)

Defapi es compatible con los protocolos comunes v1/chat/completions, v1/messages, y v1beta/models/, por lo que el proveedor personalizado de PeakCut se puede conectar directamente.

Nota: si configuraste antes los parámetros de IA a través del archivo .env, cualquier configuración guardada en la consola anulará lo que esté definido en .env. Si quieres usar .env, las variables correspondientes son:

PEAKCUT_AI_PROVIDER=custom
PEAKCUT_AI_MODELS=your-model-id
PEAKCUT_AI_KEY=your-key
PEAKCUT_AI_BASE_URL=https://api.defapi.org/v1

4. Importar videos

En la parte superior de la página principal hay un campo de pegado que admite enlaces de YouTube, Twitch y Kick, y también puedes subir archivos de video locales directamente.

En Options puedes configurar la cantidad de clips generados (1-20), la duración mínima/máxima (mínimo 5 segundos, máximo 180 segundos), el estilo de los subtítulos (Bounce/Hype/Clean), el diseño visual (desenfoque de relleno / zoom / recorte / video del juego con cámara), la resolución (720p/1080p), y también limitar el procesamiento a una parte específica del video.

Hay una opción llamada Generate captions, habilitada por defecto. Los subtítulos se resaltan palabra por palabra, lo que requiere que el modelo de voz genere resultados de reconocimiento con marcas de tiempo. El modelo predeterminado es mejor para inglés; si quieres usar otros idiomas, deberás cambiar de modelo, lo cual se cubre en la sección de solución de problemas más adelante.

Completa el enlace y haz clic en Make clips para comenzar el procesamiento.

5. Filtrar segmentos y ajustar subtítulos

Después de que el procesamiento termine, ve a la página de detalles del video para ver todos los clips generados. Con cada clip puedes:

  • Vista previa: comprueba si el resultado te satisface
  • Ajustar inicio/fin: arrastra la línea de tiempo para refinar
  • Corregir subtítulos: si hay errores de reconocimiento, edita las palabras manualmente
  • Cambiar el estilo de subtítulos: cambia entre los tres estilos libremente

PeakCut genera una imagen de portada y un título llamativo para cada clip (escrito por la IA). Si no te gusta el título, puedes cambiarlo directamente.

6. Exportar clips verticales

Cuando los clips estén bien, haz clic en Download para exportarlos. El renderizado lo hace FFmpeg, y la salida final es en formato vertical 9:16 con los subtítulos incrustados en el video.

Si has configurado la conexión de tu cuenta de YouTube, Instagram o TikTok, también puedes publicar directamente desde aquí. Para uso en una sola máquina, se recomienda descargar primero y luego subir manualmente.

Solución de problemas comunes

FFmpeg ausente
Después de iniciar, la consola te indicará que no se encuentra FFmpeg. Verifica que ffmpeg -version funcione correctamente; si no, reinstálalo y asegúrate de que esté en el PATH.

Fallo en la descarga del modelo de voz
Si la descarga del modelo se interrumpe en el primer inicio, elimina la carpeta correspondiente en data/models/ y reinicia el servicio para que lo vuelva a descargar. Si la red es inestable, puedes descargarlo manualmente desde Hugging Face y colocarlo en el directorio indicado.

La IA configurada en la consola no funciona
Revisa si la página Settings → AI muestra que la configuración se ha guardado. La configuración de la consola tiene prioridad sobre el archivo .env; si antes escribiste variables relacionadas con IA en .env, una vez que guardes en la consola, lo de .env se ignora. Para volver a usar .env, debes reseleccionar el proveedor en la consola y guardar nuevamente.

Error de formato JSON devuelto por la IA
Confirma que el ID de modelo que ingresaste sea un modelo de chat que admita salida JSON. Algunos modelos (especialmente los modelos de razonamiento puro) no garantizan devolver JSON válido; prueba con otro modelo. También puedes consultar la página AI usage, donde hay registros detallados de las solicitudes.

El idioma de los subtítulos es incorrecto
El modelo Parakeet predeterminado solo es compatible con inglés. Para videos en chino, deberás cambiar a un modelo sherpa-onnx que admita chino (cambiando ASR_MODEL_NAME en studio/config.py), o usar la transcripción en chino de YouTube (esta función está habilitada por defecto y usará preferentemente el texto de transcripción de YouTube).

Espacio en disco insuficiente
El directorio data/ almacena todos los videos y resultados generados. Antes de procesar videos largos, asegúrate de que el disco tenga suficiente espacio. Ve a Settings → Storage para ver la ruta de almacenamiento actual y el espacio restante, también puedes mover el directorio de datos a otro disco.

Lecturas adicionales / Direcciones avanzadas

PeakCut no solo puede editar videos ya grabados, sino también grabar y editar clips destacados en tiempo real durante una transmisión en vivo. Crea un workspace para cada creador, configúralo con el canal y automáticamente escuchará, generando clips durante la transmisión.

Para colaboración de múltiples usuarios o despliegue en internet, consulta DEPLOY.md: usa Docker para ejecutar la aplicación con PostgreSQL y Caddy para HTTPS automático, con registro por correo electrónico y acceso con Google. Ten en cuenta que en el despliegue público debes activar PEAKCUT_ACCOUNTS=1; de lo contrario, cualquiera que conozca la dirección podría usar tu clave de IA.

Conectar cuentas de redes sociales (YouTube/Instagram/TikTok) requiere registrar una aplicación de desarrollador en cada plataforma. Durante el período de revisión de la plataforma, los videos subidos serán privados por defecto; esto es una limitación de la plataforma, no un problema de PeakCut.

Si quieres profundizar, studio/ai.py es el único archivo que interactúa con el servicio de IA; desde ahí se añaden nuevos proveedores o se depura la lógica de solicitudes. El código también incluye un conjunto de pruebas (python tests/run.py); ejecutarlas después de hacer cambios en el código ayuda a prevenir regresiones.