¿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
- 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).
- Iniciar:
beatcut.py init <carpeta de clips> --music <archivo de música>. Imprimecreated: <carpeta>y copia la música dentro del proyecto. Si diceproject.json already exists, el proyecto existe; úsalo y no reinicies. Editaproject.jsonsi hay que cambiar tamaños,fill,fps,encoder,exclude_prefixo perfiles personalizados (profiles) (consulta las reglas más abajo). - Tiempos:
beatcut.py beats <proyecto>. Imprimeperiod,t0ybpmy los escribe enshots.json. La detección asume un tempo constante y puede equivocarse por unas centésimas de segundo ent0. Si sale con código 1 y el mensajefewer than 4 beats were detected, estableceperiodyt0a mano (period = 60 / BPM; t0 = segundo del primer tiempo). Díselos al usuario; pueden corregirlos en el selector. - 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 leeshots.json. No editesshots.jsonmientras 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.
- Selector (por defecto). Inicia
- Verificar:
beatcut.py check <proyecto>. Código 0 y mensajeok: <n> shots, <s> ssignifica que no hay errores; lee también las advertencias (stderr). Corrige todos los errores antes de renderizar. - Borrador:
beatcut.py draft <proyecto>. Imprimeencoder: ...,segment i/ny finalmente la ruta deout/<nombre_salida>_draft.mp4. - 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--outfuera de la carpeta de clips, por ejemplo una carpeta temporal. - 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": ""}conb > 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 enclips_diry coincidir conextensions.in(0 o más) yout(mayor quein): segundos en el clip de origen.beats: número entero de 1 a 512.- Opcionales, con valores por defecto:
fit(fitocut; por defectofit),interp(oflow,blend,none; déjalo fuera para automático),prof(un nombre integradoneutral,warm,cool,contrast,golden, o un nombre definido enproject.jsonprofiles; por defectoneutral),tin(cut,fade,fadewhite; por defectocut),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
beatscompases en la rejilla comenzando ent0 + period * (suma de compases anteriores). La primera toma comienza en el fotograma 0 de vídeo en su puntoin, por lo que también cubre el tiempo antes del primer compás y se lee más allá de suout. fit: velocidad =(out - in) / (beats * period). Una velocidad a menos de 0.015 de 1 cuenta como 1.checkrechaza velocidades fuera de 0.1x a 8x. Para mantener una toma a velocidad normal confit, estableceout = in + beats * period.cut: se reproduce a 1x;outno se usa para la velocidad (el selector escribeout = in + beats * period). Haz lo mismo.- La última toma se extiende
tailsegundos y la imagen se desvanece durantetail. Toda la edición no debe durar más que la música. - Cada toma necesita material de origen hasta su final (incluyendo el
taily el preámbulo de la primera toma) con 0.1 s de margen antes del final del clip. Una transiciónfadeofadewhitetoma prestada la mitad de su duración de cada vecino, por lo que la toma anterior necesita origen más allá de suouty la posterior necesita origen antes de suin. - Una transición debe ser más corta que las tomas que la rodean.
tdurse 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 (
blenden borradores,oflowen finales). No establezcasinterpa menos que el usuario lo pida. - Elige
in/outpara que el rango no se solape con un rangobad;checkavisa si lo hace.
Reglas de project.json (cuando lo cambies):
- Las claves desconocidas son un error.
musices relativa a la carpeta del proyecto, sin.., no absoluta.draftyfinalson{"width": n, "height": n}con enteros positivos pares.fpses una cadena como"25"o"30000/1001".fill:coveroblur.encoder:auto,cpuonvenc.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.
| Mensaje | Significado 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 shots | shots está vacío. Añade tomas (selector o a mano). |
shot N (clip): clip not found in the clips folder | El 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 long | El 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` later | Un 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.0x | El 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 s | Elimina 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 chain | Un perfil personalizado es incorrecto. Corrige su cadena en project.json. |
too many shots to assemble in one pass (N); split the edit | La 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 again | El 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
beatcutque creainit. Todo lo que la herramienta escribe está dentro de la carpeta del proyecto. - No borres
project.json,shots.jsonni el archivo de música. No ejecutesinitde nuevo sobre un proyecto existente. - No ejecutes
finalsin 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.1y no está protegido contra otros programas en el mismo ordenador. - No pongas cadenas de filtro en
shots.json, y no editesshots.jsonmientras 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.