tianbester-ZA/edit

/bb:edit

Objetivo

Convertir material en bruto en un video corto que un desconocido detenga, sienta algo y actúe: un máster 1080x1920 y un máster de Feed 1080x1350, ambos a aproximadamente -14 LUFS, con un plan de edición detrás que diga por qué cada corte está donde está.

Antes de todo: verificar este Mac

python3 "${CLAUDE_SKILL_DIR}/scripts/setup.py" --data "${CLAUDE_PLUGIN_DATA}"

Imprime una línea de estado por herramienta, cada una con la solución exacta, luego READY o NOT READY. Es seguro ejecutarlo de nuevo y toma segundos una vez que todo está listo. La primera ejecución construye las herramientas de Python, lo que toma unos minutos.

En NOT READY, dale a la persona las líneas de solución y detente. Si solo faltan los modelos, diles que son aproximadamente 490 MB, y si dicen que sí, añade --download-models al mismo comando. Las líneas OPCIONALES no bloquean nada.

Luego: preguntar qué estamos tratando de hacer

La persona que ejecuta esto tiene el contexto, y lo que diga aquí es lo que hace que el trabajo sea bueno. Un anuncio nuestro falló porque no preguntó nada; un reel funcionó porque alguien dio contexto real.

Mira lo que hay primero (material, guion, brief, notas) y reformúlalo, para que confirmen en lugar de volver a escribir. Pregunta en una ronda corta (AskUserQuestion cuando lo tengas, de lo contrario en el mensaje).

Pregunta primero, siempre, a menos que ya te hayan dicho:

1. ¿Qué estamos tratando de hacer y qué tipo de video es? ¿Un video de conciencia, un reel de muestra, un anuncio pagado que vende algo, UGC o un fundador hablando, detrás de escenas, algo más?

Luego solo lo que falte:

2. ¿Para quién es, y qué deberían sentir o hacer después de verlo?
3. ¿Qué estilo? ¿Qué referencia es la más cercana? Luego mostrarás opciones sobre el material real para elegir.
4. Material, sonido o música, duración y dónde se publica.

Si es un anuncio, el comprador y la etapa del guion se transfieren, o /bb:script se ejecuta primero. Una edición nunca cambia la idea o una afirmación; eso vuelve al guion.

Pon las respuestas en job/brief.md, luego trabaja hasta el final. La única otra parada son las opciones en el paso 2. Si ya lo han dado todo, o dicen simplemente 'adelante', no preguntes. Si nadie puede responder (una ejecución sin supervisión), di lo que habrías preguntado y toma la lectura sensata.

El gusto pertenece al trabajo

La pregunta 1 establece el trabajo: escríbelo en la primera línea de job/brief.md. Lo que a alguien le gustó en un video no se traslada a otro. Un reel orgánico y un anuncio son trabajos diferentes: el anuncio está destinado a vender. Así que un anuncio se juzga por para quién es, los puntos de venta del producto, la prueba y una razón para comprar, no por los chistes o la sensación de una pieza orgánica. Las lecciones de un corte orgánico no vinculan a un anuncio, y viceversa.

Por qué

Las ediciones genéricas de IA cortan en cada beat musical, dan a cada toma la misma duración, hacen zoom a todo y se detienen en el momento en que termina la última palabra. Cada una de esas ha sido rechazada aquí (ver lessons.md). Los libros de edición responden mejor a las mismas preguntas, así que las consultamos por decisión: Murch para dónde termina un pensamiento, Pearlman para el ritmo y la pregunta abierta, Block para dónde va el ojo. Los libros son preguntas y pasajes, nunca voces.

Cómo es algo bueno

• El fotograma 0 ya funciona como una imagen fija con el sonido apagado: el producto, un resultado o una sorpresa, no un logotipo o un saludo.
• Una pregunta se abre en el gancho y permanece abierta hasta la recompensa.
• Los cortes caen donde un pensamiento o un movimiento termina, no en una cuadrícula. Al menos una toma se mantiene junto a otras más rápidas, para que se lea como una pausa intencionada.
• Lo más brillante o en movimiento en cada toma es lo que hay que mirar. El texto se coloca debajo de la barbilla o en cielo despejado, nunca sobre una boca, y nunca apilado con otra línea que diga las mismas palabras.
• El cierre es más tranquilo que la toma anterior y la petición es clara. El final aterriza: la música termina en su propio final o en una frase real, nunca en un fundido sobre una canción que aún continúa, y nunca sobre sus propios últimos golpes.
• El sonido real está presente. Las personas en el material se escuchan sobre la música, y el momento más grande de la canción cae en el momento más grande de la imagen.
• El material se ve como fue filmado: el color natural del iPhone, encuadre estático, un suave zoom solo en el producto, sin zooms animados, sin relleno de espejo, sin barras negras.
• El 4:5 se diseña nuevamente a partir de la misma EDL, para que los subtítulos y los rostros se mantengan en el encuadre.

Comandos

Los archivos de referencia escriben estos de forma abreviada. El estado del shell no se transfiere entre comandos, así que siempre usa la forma completa, y dale la forma completa también a un agente crítico.

• PY significa "${CLAUDE_PLUGIN_DATA}/venv/bin/python", el Python que construyó setup. Ejecuta cada script de Python aquí con él.
• scripts/... significa ${CLAUDE_SKILL_DIR}/scripts/.... references/... significa ${CLAUDE_SKILL_DIR}/references/....
• search.py significa python3 "${CLAUDE_PLUGIN_ROOT}/skills/books/scripts/search.py".

Flujo de trabajo

Carpeta del trabajo: <cliente>-<trabajo>/ en la carpeta donde está la persona, o la que nombre el brief (job/). El material permanece donde está; solo se escriben los renders.

0. Leer y escuchar. Ejecuta PY scripts/listen.py clips <material> --out job/sound antes de planificar: transcribe cada clip y encuentra el habla, las risas, los gritos y los picos de nivel. Léelo todo. Las líneas fuera de cámara a menudo son la idea, y te dicen qué es realmente una toma (la toma de "aplicación" de un anuncio era un director diciendo "no tienes que aplicar nada"). Ejecuta también PY scripts/listen.py song <pista> y lee las palabras: pueden luchar contra la imagen o ayudarla. Luego, cualquier nota del cliente, lessons.md, la propia carpeta del cliente de ediciones pasadas (solo ese cliente, ver examples/README.md), el guion o el brief. Ejecuta scripts/probe.sh <material> > job/footage-log.md, luego mira los clips y añade los mejores momentos por timecode. Convierte HDR con scripts/proxies.sh antes de cualquier otra cosa. Un registro de material escrito por otra persona es una pista, no un hecho: mira un fotograma de cada selección antes de que entre en la EDL (scripts/sheet.sh <clip> <inicio> <duracion> job/sheets, para que nada se escriba junto al material). Enumera cada afirmación que el guion o el brief hace contra el momento del clip que la muestra; una afirmación que ningún clip muestra se cambia o se corta ahora, no por el crítico. Escribe la vibra en una línea, con las palabras de la persona.
1. Planificar. Carga references/plan.md, rhythm.md, eye.md, sound.md. Mide la música con PY scripts/beats.py <pista>: tempo, primer beat y el mapa de sonoridad, que muestra dónde la pista ya se está moviendo para music.start. Por beat (gancho, giro, recompensa, cierre): qué sentir, el ritmo, dónde cae el ojo, el sonido. Una búsqueda por columna. Escribe job/plan.md, cada línea con un id de pasaje.
2. Opciones. Alrededor de tres tratamientos por sección (casual, medio, extremo) como mosaicos: un fotograma y una línea cada uno. La persona elige. Si no están, o dijeron 'adelante', elige, registra el por qué en options.md, y mantén los otros visibles; ahí una tabla de opciones es suficiente.
3. Corte preliminar. Carga references/formats.md. Escribe job/edl.json, luego mix.py (el sonido) y cut.py --draft en proxies. scripts/sheet.sh en el resultado, listen.py cut en el resultado, y lee el informe y su imagen de forma de onda. Mira la hoja, la tira del gancho y el fotograma 0 tú mismo, y míralo una vez con el sonido apagado.
4. Crítico. Un agente nuevo recibe job/brief.md (para que juzgue contra el trabajo), el fotograma 0 a tamaño completo, los fotogramas, la tira, el informe de escucha, el registro de mezcla, la lista de afirmaciones, references/critic.md y el comando completo search.py. El fotograma 0 va primero, porque una miniatura puede malinterpretar. No tus notas ni este chat. Devuelve notas por beat, como máximo tres correcciones con ids de pasaje, y un veredicto.
5. Final. Corrige lo que encontró el crítico (o escribe por qué el brief gana). Apunta la EDL a archivos SDR de máxima calidad, renderiza sin --draft, luego reframe.py para el 4:5, luego check_cut.py y listen.py cut en el resultado. Corrige cada FAIL; lee cada WARN. Di claramente que nadie lo ha escuchado: el informe mide, no escucha, así que las líneas de voz y la mezcla van a los oídos de la persona. Hojas de ambos másters. README.txt y entrega como en formats.md.

Responde con los dos archivos, el fotograma 0, una línea por beat sobre lo que cambió después del crítico, y una oración nombrando los libros una vez. Las citas se quedan en plan.md, nunca en el video.

Límites estrictos

• Una afirmación o idea cambiada vuelve a /bb:script. Si el material o el sonido matan la idea, detente y rehaz el diagnóstico y el guion, con el crítico; nunca intercambies una nueva línea durante el corte. Un anuncio nuestro cambió su línea en la edición y se envió sin audiencia y sin razón de existir.
• Opciones antes de un borrador, cada vez. Si no hay nadie, elige y registra; nunca lo omitas.
• Nunca ralentices o aceleres una voz. cut.py silencia el audio de una toma cuando su velocidad no es 1.
• Sin reducción de ruido, sin desenfoque, sin zooms animados, sin relleno de espejo, sin barras negras. HDR a SDR primero con avconvert. Sin corrección de color en talking heads y UGC. Un look ligero solo cuando el brief lo pida (look en la EDL), dicho en voz alta en la respuesta.
• Nunca envíes con el sonido del clip apagado y sin una razón escrita en el plan.
• Una toma nunca prueba más de lo que sucedió: si el audio dice que fue simulado, no es prueba.
• Subtítulos en el idioma hablado, cada palabra que importa, nunca sobre la boca, nunca apilados con una llamada.
• Las afirmaciones, precios y ofertas en pantalla provienen del brief o del sitio en vivo del cliente, nunca inventados.
• Nada va a un cliente, se publica o gasta dinero sin el sí de la persona. La entrega al Drive de un cliente y cualquier mensaje se redactan para ellos; ellos envían.

Conocimientos prácticos

• Texto: ffmpeg de Homebrew no tiene drawtext ni libass, así que el texto se dibuja como PNGs por scripts/text_png.swift (CoreText, compilado una vez por cut.py) y se superpone con overlay. Las fuentes están en assets/fonts/ (Geist Black, Geist Bold, Playfair Display Italic); la propia fuente de un cliente va en el bloque styles de la EDL por ruta.
• Whisper es inglés y malinterpreta las voces fuera de cámara. listen.py usa el modelo pequeño de inglés. Verifica cualquier línea que subtitules leyendo los fotogramas; para una lectura más clara de una línea dudosa, setup.py --download-large añade un modelo más grande (1.6 GB), que listen.py clips --large usa.
• Velocidad: los renders finales se ejecutan a aproximadamente 3 a 5 fotogramas por segundo para un 1080x1920 desde fuentes 1080p mientras se ejecutan otras codificaciones; un anuncio de 30 s toma de 3 a 5 minutos. Usa --draft para el corte preliminar. Ejecuta renders largos como tareas en segundo plano.
• Cortes alineados al beat: beats.py mide bpm y offset del archivo. Mide toda la pista: verifica que sus dos mitades concuerden, y una ventana corta a través de una intro puede fijarse en el pulso incorrecto. Dale a la música un bpm y offset (segundos dentro del archivo del primer tiempo fuerte) o una lista de beats. Marca las tomas cuyo final debe caer en un beat con "snap": true; el valor predeterminado solo ajusta esas. cut.py --beats imprime la cuadrícula contra los cortes actuales. Ajusta el giro y la recompensa, no cada corte: check_cut.py advierte cuando más del 80% de los cortes están en un beat.
• Tiempo de texto: vincula el texto a una toma ("shot": 2, "at": 0.3, "dur": 1.2) en lugar de segundos absolutos, para que siga la toma cuando un ajuste de beat mueva un corte.
• Sonoridad: loudnorm de dos pasos a -14 LUFS en modo lineal, luego un limitador a 4 veces la frecuencia de muestreo; cut.py mide el archivo y recodifica con un techo más bajo si AAC lo ha superado -1 dBTP. La música se sitúa 14 dB por debajo del audio del clip por defecto cuando alguna toma mantiene su propio sonido; establece music.gain_db para cambiarlo.
• 4:5: reframe.py encuadra cada toma exactamente como la 9:16 y toma una ventana de 1350 filas por toma (y45, por defecto 285). El texto mantiene su lugar en la imagen y se desplaza 40 px hacia adentro. Mantén el texto 9:16 entre las filas 330 y 1590, y el 4:5 no necesita trabajo adicional.
• Zonas seguras (9:16): nada por encima de la fila 270 ni por debajo de 1590 excepto tarjetas de pantalla completa; el 12% inferior es el botón de Meta.
• Hojas: sheet.sh <video> [inicio] [duracion] escribe una hoja de 40 fotogramas (los tiempos en el .txt junto a ella), una tira de 10 fps del gancho (o cualquier ventana) y el fotograma 0. Los fotogramas de flash aparecen en la tira, no en la hoja.
• Finales de clip: cut.py advierte cuando el out de una toma está más allá del último fotograma de la imagen y mantiene ese fotograma, para que el máster nunca se quede corto de su audio. Retira out si un congelamiento se mostraría.
• Cámara en mano y zooms: x es un número por toma, así que un sujeto con cámara en mano a la deriva sale de la ventana, y un zoom multiplica la deriva. Mira la ventana de esa toma en movimiento (sheet.sh <render> <inicio de toma> <duracion> da una tira de 10 fps) antes de confiar en el encuadre.
• Los tiempos de las palabras se desvían: los tiempos por palabra de whisper pueden estar desviados hasta 2 s. Antes de que una línea entre, transcribe la sección por sí sola; una palabra perdida en cualquier extremo significa que el corte está mal.
• Sincronía labial: las copias de teléfono pueden llevar el audio aproximadamente 0.1 s antes. Verifica un clip antes de cortar; si la voz se adelanta, ajusta in en la imagen, nunca las palabras.
• La búsqueda en libros: search.py "<palabras literales>" --job feel|rhythm|eye --book murch|pearlman|block --k 6, luego --show <id> para leer una nota. Las palabras literales funcionan; las preguntas no.

Referencias (cargar por decisión)

• references/plan.md: el plan de cuatro beats, una línea por beat por columna, y las consultas por columna.
• references/rhythm.md: dónde cae un corte, se mantiene, el patrón cambia, la pregunta abierta.
• references/eye.md: hacia dónde va el ojo, colocación del texto, zonas seguras, la banda 4:5.
• references/sound.md: el paso de escucha, voz, música, efectos, sonoridad, el final.
• references/critic.md: la rúbrica, cargada solo por el agente crítico.
• references/formats.md: forma de la EDL, los scripts en orden, salidas, dónde van los finales.
• references/drawings.md: animación dibujada a mano sobre un corte, cuando el brief lo pide.

Lecciones

lessons.md contiene líneas fechadas de reacciones y resultados reales. Léelo en el paso 0; el crítico verifica el corte contra las últimas cinco. Esta carpeta se reemplaza en cada actualización, así que las lecciones propias de un cliente van en la carpeta de ese cliente, y una lección para todos va a través del repositorio (CONTRIBUTING.md).