galloforge/forge-deliver

FilmForge Entrega

Una película está terminada cuando cada versión se reproduce donde debe, mide correctamente y toda la producción reside en una carpeta con una prueba de que nada falta. Esta habilidad genera los entregables a partir de la matriz de entregables, verifica cada uno y cierra la producción con archive.py.

Rutas: scripts/, templates/ y config/ a continuación son carpetas dentro de esta habilidad (el directorio base que se muestra cuando se carga), colocadas allí por ./install.sh. Trabajando desde un clon del repositorio, son tools/, templates/ y config/ en su raíz.

Paso 1. La matriz de entregables (templates/delivery-checklist.md)

Cópiala en la producción y tacha lo que la película no tenga. Cada entregable de la película proviene de un máster, exportado desde tu editor o compositor a 3840x2160 desde la misma lista de tomas, pinturas y mezcla que la vista previa, luego codificado con ffmpeg:

Entregable	Hecho a partir de	Ajustes
Máster 4K	la exportación 4K del editor	3840x2160 a los fps de la lista de tomas; HEVC Main a través de VAAPI (hevc_vaapi) con QP constante 18, etiquetado BT.709, luego re-mux con -c copy -tag:v hvc1 para que los reproductores Apple lo acepten; sin VAAPI, H.264 (libx264, preset medium, CRF 18, yuv420p); AAC 320k; +faststart
1080p para publicación	el máster	Lanczos a 1920x1080, libx264 preset slow, CRF 16, perfil High, yuv420p; la mezcla normalizada a -14 LUFS y -1.5 dBTP mediante un loudnorm lineal de dos pasadas; AAC 320k; +faststart
Copia para teléfono	la copia de publicación	Lanczos a 1280x720 con ligera reducción de ruido (hqdn3d=1.2:1.2:3:3), libx264 a 900k (maxrate 1400k, buffer 2800k), AAC 128k; lo suficientemente pequeña para enviar en un chat
Portadas	el máster	3 o 4 de los fotogramas más fuertes a 4K, PNG, más JPG para publicación; legibles en tamaño de teléfono

Los comandos exactos de ffmpeg: references/deliverables.md. Ponlos en un solo script, para que cualquier cambio reconstruya todos los entregables.

Libros y extras, cuando la película los tenga: un libro ilustrado como videos 4K y 1080p con la música, un PDF para imprimir, un libro web interactivo que pasa las páginas con la música, ediciones localizadas (cada idioma con sus propios videos 4K, 1080p y para teléfono, cada línea reajustada y verificada por alguien que lo lea, nunca ajustada automáticamente sin revisión), y el making-of como PDF más un PDF para teléfono. Detalles: references/deliverables.md.

Paso 2. Verificar cada entregable

Mide los archivos mismos, nunca la línea de tiempo:

• Flujos: códec, tamaño, formato de píxel, velocidad de fotogramas, etiqueta de códec (hvc1 para el máster HEVC), tasa de audio y canales, duración, tamaño y tasa de bits (ffprobe).
• Sonoridad: integrada, rango y pico verdadero (EBU R128, filtro ebur128 de ffmpeg). El máster lleva la mezcla tal cual; las copias de publicación y teléfono deben mostrar aproximadamente -14 LUFS.
• Sincronía en los golpes de la historia: para cada golpe, el cambio de imagen más grande y el inicio de sonido más fuerte dentro de medio segundo, y qué tan separados están en ms. Los cambios de imagen provienen de la puntuación de escena de ffmpeg, los inicios de beatmap.py ejecutado sobre el audio de la propia película. Objetivo: un fotograma (42 ms a 24 fps) o menos dondequiera que un corte coincida con el golpe. Un golpe sin corte en él informa una brecha; compáralo con la lista de tomas.
• Extremos: el primer y último fotograma (negro, o el título, a propósito).
• Hoja de contactos de la película terminada, un fotograma cada 2 s, revisada de principio a fin.
• Visto una vez de principio a fin en la pantalla objetivo con sonido, antes de la aprobación.

Los comandos para cada uno: references/deliverables.md (Verificaciones).

Para PDFs: abrir en dos lectores, revisar cada pliego, fuentes incrustadas, imágenes a resolución de impresión.

Paso 3. El archivo y su prueba

Todo lo que hizo la película va en una carpeta de producción: production.yaml, los archivos de historia, indicaciones, cada pintura y versión, las hojas, la partitura y su medición, el código, las mezclas, los entregables, las lecciones.

python3 scripts/archive.py build <film> --require deliverables.txt \
        --require-shotlist <film>/shotlist.yaml --paintings <film>/art/film \
        --exclude "code/.venv/=rebuilt from requirements.txt"
python3 scripts/archive.py verify <film>

build hashea cada archivo en <film>/MANIFEST.sha256 (formato sha256sum -c plano, así la prueba sobrevive a la herramienta) y escribe manifest.json: recuento de archivos, bytes, archivos por tipo, lo que se excluyó a propósito y por qué (cachés, entornos virtuales, cualquier carpeta de 4k/ upscale), los entregables requeridos y los faltantes, las tomas sin pinturas, y el resumen del manifiesto mismo. Reporta COMPLETO solo cuando cada patrón requerido coincide y cada toma pintada tiene su pintura. verify re-hashea todo después y falla en cualquier archivo faltante o modificado (y en un manifiesto editado).

La misma herramienta prueba un paquete más pequeño también. El archive-required.txt de La Polilla Linterna lista lo que debe contener su paquete de preproducción antes de gastar un crédito en pinturas, y archive.py build en la carpeta de ejemplo con --require archive-required.txt encuentra los diez patrones presentes y reporta COMPLETO.

Copias: prueba una copia de seguridad o un movimiento byte a byte: python3 scripts/archive.py compare <film> <copy>. Hace en un solo comando lo que las listas SHA-256 de cada archivo en el origen y en la copia, y un registro de copia, hacen a mano.

Escribe un breve README en el archivo: qué contiene cada carpeta, qué se excluyó a propósito, dónde está el trabajo terminado.

Paso 4. Cerrar

production.py signoff deliver --by <tú> --note "<visto el máster en la TV; verificaciones pasan>", luego advance a la retrospectiva (forge-director).

Salida

• film/ con cada entregable, nombrado <Título>_4K.mp4, <Título>_1080p.mp4, <Título>_phone.mp4, covers/
• los números de las verificaciones en el informe (tamaños, sonoridad, desplazamientos de sincronía en cada golpe)
• MANIFEST.sha256, manifest.json, el README del archivo

Lista de verificación de puerta

• Cada entregable en la matriz existe y pasó sus verificaciones
• Sincronía en cada golpe de la historia dentro de un fotograma
• Visto en la pantalla objetivo con sonido
• archive.py build: COMPLETO; archive.py verify: OK
• Cada copia verificada con archive.py compare
• Aprobado

Tabla de reparaciones

Síntoma	Solución
Los dispositivos Apple rechazan el máster HEVC	Falta etiqueta hvc1: re-mux con ffmpeg -i in.mp4 -c copy -tag:v hvc1 out.mp4
El máster HEVC no decodifica	hvc1 fue escrito durante la codificación VAAPI: codifica sin la etiqueta, luego re-mux con -c copy -tag:v hvc1
La TV se entrecorta por Wi-Fi	Tasa de bits demasiado alta (ffprobe la muestra): codifica el máster de nuevo con un QP más alto (archivo más pequeño)
Se quería HEVC pero no hay codificador VAAPI	ffmpeg -h encoder=hevc_vaapi y ls /dev/dri muestran lo que tiene la máquina; de lo contrario, entrega el máster H.264
La plataforma de publicación lo rechaza o lo recorta	No está normalizado: publica la copia de dos pasadas (-14 LUFS, -1.5 dBTP, lineal), no el máster
La copia para teléfono es demasiado grande para enviar	Reconviértela desde la copia de publicación con un -b:v más bajo (references/deliverables.md), o acórtala; conserva 720p
verify reporta CAMBIADO	Alguien editó un archivo entregado: restáuralo desde una copia verificada, o reconstruye y vuelve a aprobar
build reporta INCOMPLETO	Falta un entregable requerido o una pintura: hazlo, o elimínalo de la lista a propósito con una razón

Referencias

• references/deliverables.md: los comandos completos de ffmpeg, las verificaciones, libros, ediciones y portadas