Communitygithub.com

beatcut

Corta un vídeo a partir de una carpeta de clips y una pista de música, sincronizando los cortes con los tiempos de la canción. Construye o edita una edición sincronizada con el ritmo, selecciona puntos de entrada/salida y recuentos de compás, y renderiza el borrador o el vídeo final usando la herramienta beatcut en la línea de comandos.

¿Qué es beatcut?

La habilidad beatcut permite crear vídeos cuyos cortes caen exactamente en los tiempos musicales, a partir de una carpeta de clips y un archivo de música. El estado del proyecto se guarda en dos archivos: `project.json` (configuración) y `shots.json` (la línea de edición). La herramienta se usa mediante el comando `beatcut.py` en la terminal, y el flujo de trabajo incluye detectar la rejilla de tiempos, abrir un selector local para que el usuario elija las tomas directamente o editando `shots.json` a mano, verificar la edición, renderizar un borrador, inspeccionarlo con una hoja de contactos y, solo después de la aprobación del usuario, renderizar el vídeo final en mayor resolución. Es útil para editores de vídeo, músicos y creadores de contenido que necesitan sincronizar cortes de vídeo con la música de forma precisa y reproducible. La habilidad está diseñada para funcionar en Windows, aunque no ha sido probada en Linux ni macOS.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/faruk76150/beatcut/tree/main

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace beatcut?

beatcut convierte una carpeta de clips y un archivo de música en un vídeo cuyos cortes caen exactamente en los tiempos musicales (frame exacto). El estado reside en dos archivos dentro de la carpeta del proyecto: project.json (configuración) y shots.json (la edición). La herramienta de línea de comandos es beatcut.py.

Rutas

Ejecuta los comandos con el Python que tenga los requisitos instalados (pip install -r requirements.txt; ffmpeg y ffprobe deben estar en PATH). Usa la carpeta en la que está instalada esta habilidad como carpeta del repositorio:

python <carpeta de la habilidad>/beatcut.py <comando> ...

A partir de ahora, beatcut.py se refiere a esa ruta completa. Las rutas a los clips y proyectos pueden estar en cualquier lugar; ponlas entre comillas si contienen espacios. Un proyecto siempre está en <carpeta de clips>/beatcut; todos los comandos excepto init y sheet toman esa carpeta del proyecto.

Flujo de trabajo

  1. Pregunta qué falta: la carpeta de clips, el archivo de música y la forma de salida (por defecto 1920x1080 borrador, 3840x2160 final; tamaños verticales como 1080x1920 son válidos).
  2. Iniciar: beatcut.py init <carpeta de clips> --music <archivo de música>. Imprime created: <carpeta> y copia la música dentro del proyecto. Si dice project.json already exists, el proyecto existe; úsalo y no reinicies. Edita project.json si hay que cambiar tamaños, fill, fps, encoder, exclude_prefix o perfiles personalizados (profiles) (consulta las reglas más abajo).
  3. Tiempos: beatcut.py beats <proyecto>. Imprime period, t0 y bpm y los escribe en shots.json. La detección asume un tempo constante y puede equivocarse por unas centésimas de segundo en t0. Si sale con código 1 y el mensaje fewer than 4 beats were detected, establece period y t0 a mano (period = 60 / BPM; t0 = segundo del primer tiempo). Díselos al usuario; pueden corregirlos en el selector.
  4. Elegir tomas, de una de estas dos formas:
    • Selector (por defecto). Inicia beatcut.py pick <proyecto> en segundo plano (bloquea hasta que se detiene; abre el navegador a menos que añadas --no-open; puerto por defecto 8765, cámbialo con --port N). Dale al usuario la URL que imprime, http://127.0.0.1:<puerto>/, e indícale que la página se guarda automáticamente. Espera a que el usuario diga que ha terminado, luego para el servidor (Ctrl+C o termina el proceso en segundo plano) y lee shots.json. No edites shots.json mientras el selector esté abierto: la página sobrescribiría tus cambios.
    • A mano, cuando el usuario te pida construir la edición o dé horas exactas. Sigue las reglas de abajo y luego ejecuta check.
  5. Verificar: beatcut.py check <proyecto>. Código 0 y mensaje ok: <n> shots, <s> s significa que no hay errores; lee también las advertencias (stderr). Corrige todos los errores antes de renderizar.
  6. Borrador: beatcut.py draft <proyecto>. Imprime encoder: ..., segment i/n y finalmente la ruta de out/<nombre_salida>_draft.mp4.
  7. Observarlo: beatcut.py sheet <video> --out <ruta .jpg> escribe una hoja de contactos de 5 por 4; abre esa imagen y describe el resultado al usuario (orden de las tomas, color, fundidos, fotogramas negros, recortes incorrectos). Elige una ruta --out fuera de la carpeta de clips, por ejemplo una carpeta temporal.
  8. Final, solo con la aprobación del usuario: después de mostrar el borrador, pregunta si quiere renderizar el final. Ejecuta beatcut.py final <proyecto> solo después de un sí claro. El final es más lento y más grande. Informa de la ruta de salida.

Si el usuario modifica la edición después, vuelve al paso 4. Los renderizados reutilizan segmentos en caché, así que un segundo borrador es más rápido.

Editar shots.json a mano

Mantén el archivo como JSON válido (UTF-8). check informa de cada infracción de estas reglas.

Nivel superior:

  • version: 1. period: número, mayor de 0.05 y menor de 10. t0: número, 0 o más. tail: de 0 a 30 (por defecto 1.5). shots: lista, como máximo 2000.
  • Opcionales: bad (nombre del clip a lista de {"a": s, "b": s, "note": ""} con b > a >= 0), clipnotes (nombre del clip a texto), markers ({"beat": int >= 0, "title": texto}; se muestran solo en el selector). Conserva las claves que no conozcas; las herramientas las preservan.

Cada toma:

  • clip: nombre del archivo con extensión, tal como aparece en la carpeta de clips. Sin /, \ ni :. Debe ser un archivo directamente en clips_dir y coincidir con extensions.
  • in (0 o más) y out (mayor que in): segundos en el clip de origen.
  • beats: número entero de 1 a 512.
  • Opcionales, con valores por defecto: fit (fit o cut; por defecto fit), interp (oflow, blend, none; déjalo fuera para automático), prof (un nombre integrado neutral, warm, cool, contrast, golden, o un nombre definido en project.json profiles; por defecto neutral), tin (cut, fade, fadewhite; por defecto cut), tdur (0 a 5 segundos, por defecto 0.5), note (texto, como máximo 2000 caracteres).

Cómo se usan los números:

  • Las tomas se reproducen una tras otra; la toma N ocupa beats compases en la rejilla comenzando en t0 + period * (suma de compases anteriores). La primera toma comienza en el fotograma 0 de vídeo en su punto in, por lo que también cubre el tiempo antes del primer compás y se lee más allá de su out.
  • fit: velocidad = (out - in) / (beats * period). Una velocidad a menos de 0.015 de 1 cuenta como 1. check rechaza velocidades fuera de 0.1x a 8x. Para mantener una toma a velocidad normal con fit, establece out = in + beats * period.
  • cut: se reproduce a 1x; out no se usa para la velocidad (el selector escribe out = in + beats * period). Haz lo mismo.
  • La última toma se extiende tail segundos y la imagen se desvanece durante tail. Toda la edición no debe durar más que la música.
  • Cada toma necesita material de origen hasta su final (incluyendo el tail y el preámbulo de la primera toma) con 0.1 s de margen antes del final del clip. Una transición fade o fadewhite toma prestada la mitad de su duración de cada vecino, por lo que la toma anterior necesita origen más allá de su out y la posterior necesita origen antes de su in.
  • Una transición debe ser más corta que las tomas que la rodean. tdur se redondea a un número par de fotogramas; menos de 2 fotogramas significa un corte directo.
  • Cámara lenta: la interpolación automática ocurre solo cuando la toma va más lenta que 0.97x y la velocidad de fotogramas de origen multiplicada por la velocidad está por debajo de la velocidad de fotogramas de salida (blend en borradores, oflow en finales). No establezcas interp a menos que el usuario lo pida.
  • Elige in/out para que el rango no se solape con un rango bad; check avisa si lo hace.

Reglas de project.json (cuando lo cambies):

  • Las claves desconocidas son un error. music es relativa a la carpeta del proyecto, sin .., no absoluta. draft y final son {"width": n, "height": n} con enteros positivos pares. fps es una cadena como "25" o "30000/1001". fill: cover o blur. encoder: auto, cpu o nvenc. loudness: -40 a -5.
  • profiles: nombre ([a-z0-9_-], de 1 a 32 caracteres) a una cadena de filtro ffmpeg, sin ;, [ ni ]. Las tomas se refieren a los perfiles solo por su nombre.

Mensajes y qué hacer

Las advertencias comienzan con warning: y no detienen un renderizado. Los errores comienzan con error: y van a stderr.

MensajeSignificado y acción
ffmpeg was not found on PATH; install FFmpeg and try again (código 2)ffmpeg o ffprobe no están en PATH. Pide al usuario que instale FFmpeg; no lo instales tú mismo a menos que te lo pida.
no project.json in <carpeta> (did you mean <carpeta>\beatcut?) (código 1)Pasaste la carpeta de clips. Usa la carpeta beatcut dentro de ella.
unknown key(s): ..., <field>: must be ...Un campo de project.json no es válido. Corrige ese campo.
<path>: invalid JSON (...) (<path> es la ruta completa de shots.json)Error de sintaxis en el archivo. Corrígelo; la versión anterior puede estar en shots.json.bak.
shots[i].<field>: must be ...Una toma incumple las reglas anteriores (i cuenta desde 0). Corrígela.
no shotsshots está vacío. Añade tomas (selector o a mano).
shot N (clip): clip not found in the clips folderEl nombre del archivo es incorrecto o el archivo falta o está excluido por extensions o exclude_prefix. Comprueba la ortografía; nunca crees ni copies archivos en la carpeta de clips para solucionarlo.
shot N (clip): needs source up to X s but the clip is Y s longEl rango más el preámbulo, cola o transición sobrepasa el clip. Mueve in más temprano, usa menos compases, usa fit con un out más corto, o acorta la transición.
shot N (clip): needs X s before the start of the clip; move `in` laterUn preámbulo de la primera toma o una transición alcanza antes de 0. Aumenta in o acorta la transición.
shot N (clip): shorter than its transitions; ...Transición más larga que la toma. Reduce tdur o añade compases.
shot N (clip): speed X is outside 0.1x-8.0xEl rango y el recuento de compases no encajan. Cambia beats o el rango.
the edit is X s long but the music is only Y sElimina compases o tomas, reduce tail, o usa un archivo de música más largo.
warning: shot N (clip): uses a range marked bad (...)La toma se solapa con un rango bad. Muévela, o díselo al usuario.
warning: <clip>: HDR source (...); colours will look washed out ...Clip HDR; beatcut no hace mapeo de tonos. Díselo al usuario; sugiérele clips SDR.
warning: <clip>: cannot be read (...)ffprobe no puede leer el clip. Díselo al usuario.
music file not found: <name>El archivo music falta en la carpeta del proyecto.
profile <name>: ffmpeg rejects the filter chainUn perfil personalizado es incorrecto. Corrige su cadena en project.json.
too many shots to assemble in one pass (N); split the editLa edición es demasiado larga para un solo renderizado. Díselo al usuario; divide la edición en varios proyectos o reduce el número de tomas.
another render is already running for this project (código 2)Un renderizado (quizás iniciado desde el selector) se está ejecutando. Espera a que termine; no borres work/.
cannot write <file>; close it in any player and try againEl archivo de salida está abierto en otro lugar. Pide al usuario que lo cierre.
fewer than 4 beats were detected; set period and t0 by hand (código 1)Consulta el paso 3.

Códigos de salida: 0 éxito, 1 problema con la entrada del usuario (corregir y reejecutar), 2 fallo de entorno o tiempo de ejecución.

No hacer

  • No modifiques, muevas, renombres ni borres los clips de origen, y no escribas en la carpeta de clips salvo la carpeta del proyecto beatcut que crea init. Todo lo que la herramienta escribe está dentro de la carpeta del proyecto.
  • No borres project.json, shots.json ni el archivo de música. No ejecutes init de nuevo sobre un proyecto existente.
  • No ejecutes final sin la aprobación del usuario después de que haya visto el borrador.
  • No expongas el selector a una red: nada de reenvío de puertos, túneles, proxies inversos, ni intentes enlazarlo a otra dirección. Escucha solo en 127.0.0.1 y no está protegido contra otros programas en el mismo ordenador.
  • No pongas cadenas de filtro en shots.json, y no edites shots.json mientras se ejecuta el selector.
  • No afirmes que el resultado es bueno sin mirar el borrador (hoja de contactos o el vídeo mismo).
  • No prometas funcionalidades que la herramienta no tiene: sin mapeo de tonos HDR, sin detección de caras, sin exportación a CapCut, sin efectos de sonido. Linux y macOS no han sido probados; Windows es la plataforma probada.

Skills relacionados