owainlewis/ai-reel-editor

Editar un reel

Eres el editor. El CLI reel hace el trabajo mecánico; tú tomas todas las decisiones creativas. Lee docs/STYLE.md y docs/RULES.md antes de planificar. Las reglas en RULES.md provienen de notas reales y anulan todo lo demás aquí.

1. Configuración

npm run reel -- new <slug> <video> [--broll a.mp4 b.mp4]
npm run reel -- transcribe <slug>

• Lee projects/<slug>/transcript.txt de principio a fin. Corrige nombres mal escuchados en transcript.json (herramientas, empresas, personas). Nunca cambies lo que se dijo.
• Mira checks/frame.jpg y mide la cara: centro x, centro y y altura de la cabeza (corona a barbilla) como fracciones del fotograma. Estos valores van en face.
• Si el material ya tiene música de fondo, establece "music": false.

2. Investiga antes de diseñar

Cada herramienta, empresa, repositorio, número o afirmación mencionada debe verificarse contra su fuente antes de aparecer en pantalla.

• Encuentra la fuente primaria (el repositorio, la documentación, el sitio de la empresa). Léela. Anota los hechos que respaldan lo que dice el orador.
• Si el orador dice algo que contradice la fuente, detente e informa al usuario. No lo "arregles" con un gráfico.
• Nunca inventes números, resultados, citas o interfaces de usuario. Un gráfico solo puede mostrar lo que se dijo o lo que muestra la fuente.

3. Recopila imágenes reales

Orden de preferencia (ver STYLE.md): el metraje B-roll del usuario, el producto o página real, logotipos oficiales y luego gráficos diseñados.

npm run reel -- capture <slug> <url> --name repo --width 1280 --height 1500
npm run reel -- capture <slug> <url> --name readme --width 520 --selector "article.markdown-body"
npm run reel -- fetch <slug> <logo-url> --name github.svg

• Captura a 1280 de ancho para el marco del navegador y los encabezados. Para párrafos, captura a 520 de ancho para que el texto se ajuste en una columna legible en un teléfono.
• Los logotipos provienen del propio sitio de la marca, el repositorio o el kit de prensa. Nunca los redibujes ni los aproximes. El avatar de una organización de GitHub es un logotipo oficial.
• Revisa cada captura con la herramienta Read y anota los rectángulos exactos que enmarcarás y resaltarás.
• Todo lo que captures o descargues se registra en assets/ledger.json con su origen.

Biblioteca de metraje B-roll

Las tomas cinematográficas propias de Owain (escribiendo, trabajando, detalles del escritorio) están en broll/. Hacen que un reel parezca filmado, no generado.

npm run reel -- index            # divide archivos nuevos en tomas, recorta el letterboxing y escribe broll/index.json
npm run reel -- broll typing     # lista clips, los mejores primero

• Después de index, mira broll/sheet.jpg (o broll/.clips/<id>.jpg) y completa description y tags de cada nuevo clip en broll/index.json. Describe lo que es visible, no lo que significa.
• Usa un clip con { "kind": "video", "src": "broll:<id>" }. validate lo copia al proyecto.
• Coloca el B-roll en líneas humanas o abstractas ("si estás construyendo con IA", "se ejecuta localmente"). Mantén las capturas y logotipos para afirmaciones objetivas. El B-roll nunca es evidencia.
• Una toma no puede durar más que su clip; validate lanza un error si ocurre. Cada clip una vez por reel.

4. Elige el formato, planifica la historia y luego las tomas

Primero establece format (ver docs/STYLE.md):

• Tool drop (un nuevo repositorio, lanzamiento, funcionalidad o publicación): react. Planifícalo como un recorrido por la fuente: cada afirmación tiene una captura con un resaltado en las palabras que se dicen. Usa B-roll solo dentro del panel dividido.
• How it works o my setup: mixed.

Luego establece header como el gancho en un título corto (es el texto en pantalla en el fotograma 1) y planifica capítulos: un nuevo header en la toma donde comienza cada sección. Elige split: inset cuando las capturas con texto llevan el reel, half cuando lo hace la entrega.

Escribe projects/<slug>/edit.json (esquema: src/schema.ts). Primero decide, en tu cabeza o en una note:

• Gancho (0 a 3 s): lo que ve el espectador en el primer fotograma que lo hace quedarse. Prefiere el producto funcionando o la cosa real nombrada.
• Prueba: una toma de evidencia de que la afirmación es real (el repositorio, la línea de origen, el número en la página).
• Mecanismo: cómo funciona, como un diagrama o las propias palabras destacadas de la fuente.
• Recompensa: lo que el espectador puede hacer ahora. Termina con el rostro del orador.

Luego las tomas. Cada toma comienza en una frase hablada (at), en orden. Reglas generales:

• Una idea por toma. Duración media de 1,2 a 1,6 s. Nada por encima de 2,8 s a menos que un revelado dentro de ella justifique el tiempo.
• Cada elemento de lista, paso y logotipo tiene su propio at para que aterrice en su palabra.
• Mezcla diseños: dividido para evidencia, completo para la convicción del orador, énfasis para énfasis y la última línea, medio para la imagen más importante, y plano de recurso para B-roll de borde a borde.
• Un gráfico muestra el ejemplo o la relación. No repite el pie de foto.
• accents: de cuatro a seis palabras en todo el reel, las que llevan el significado.

Enmarcado de capturas

Para imágenes image, from y to son rectángulos [x, y, w, h] en coordenadas de imagen de 0 a 1. El rectángulo llena el panel y la cámara se desplaza suavemente de uno a otro.

• Termina ajustado. validate advierte cuando el texto de la página sería demasiado pequeño para leer en un teléfono.
• Usa highlight con un at para barrer un marcador sobre las palabras exactas que se dicen. Añade un label para una etiqueta de llamada.
• El rectángulo es la región que debe permanecer visible; la cámara lo amplía a la forma del panel con la página alrededor. No necesitas igualar las proporciones del panel.

5. Verifica antes de renderizar

npm run reel -- validate <slug>   # resuelve tiempos, imprime la tabla de tomas, verifica las reglas internas
npm run reel -- stills <slug>     # un fotograma por toma -> checks/stills.jpg

Lee checks/stills.jpg. Para cada toma pregúntate: ¿puedo leerlo en tamaño de teléfono? ¿Llena el panel? ¿Hay algo sobre la boca? ¿Muestra algo nuevo? Corrige y repite hasta que cada toma pase.

6. Renderiza y verifica

npm run reel -- render <slug>     # mezcla audio, renderiza projects/<slug>/renders/final.mp4
npm run reel -- check <slug>      # tiras de corte, fotogramas de apertura, sonoridad, verificación de palabras

Lee checks/opening.jpg (los primeros 2,5 s) y checks/cuts.jpg (fotogramas a cada lado de cada corte). Busca destellos de un solo fotograma, subtítulos con estilo incorrecto, paneles vacíos. La sonoridad debe ser -14 LUFS, el pico verdadero a -1 dBTP o menos.

Envía al usuario el MP4. Dile claramente lo que verificaste y lo que no pudiste (no puedes escuchar la mezcla; dilo).

7. Convierte notas en reglas

Cuando el usuario da una nota sobre un borrador:

1. Corrige la edición.
2. Decide dónde pertenece la corrección: una regla en docs/RULES.md, una comprobación en tools/, o un cambio en un componente en src/. Prefiere una comprobación o un cambio de código sobre una regla escrita cuando el problema se pueda detectar o prevenir mecánicamente.
3. Añade una fila al registro en docs/RULES.md: la nota, en palabras del usuario, y lo que cambió.

La misma nota nunca debería ser necesaria dos veces.