daoge96/dsh-skills

Producción de video con código

Trata un video como una función pura render(t) más un pipeline por etapas y comprobable. Casi todos los modos de fallo en esta clase de tarea son errores de unidades/señal/canal/métrica que se envían silenciosamente, por lo que el flujo de trabajo a continuación está construido para hacer que cada uno sea observable.

0. Congela el contrato antes de dibujar nada

1. Una sola fuente de tiempo. Todo vive dentro de render(t); el mapeo fotograma↔tiempo (t = frame/fps) es la API pública completa. Sin animación CSS, sin temporizadores, sin estado fotograma a fotograma. Resultado: los fotogramas son paralelizables, reanudables, comparables, y un error se localiza en un rango de tiempo.
2. Determinismo. PRNG con semilla (hash(i)/mulberry32), nunca Math.random; nunca Date.now; incrusta fuentes y texturas como URIs de datos para que ninguna red/fallback de fuente pueda cambiar píxeles a mitad de ejecución.
3. Escribe la especificación como aserciones, no como prosa. Duración, fps, resolución, códec, formato de píxel, sonoridad, pico verdadero, área segura/márgenes, técnicas prohibidas, rutas de archivos, banderas de CLI, códigos de salida, forma de salida JSON. Si hay un número en el resumen, debe terminar en una comprobación.
4. Decide la política de costuras por adelantado — de una sola vez / bucle / segmentos concatenados. Para un bucle: cada oscilador es sin(2π·k·t/D) con k entero; la película converge de nuevo a su propio primer estado (no "se ve similar"); las tablas de eventos y los contadores/etiquetas en pantalla se reinician dentro de la transición final; verifica render(0) vs render(D) renders.
5. Presupuesto por fotograma. Mide render(t) antes de construir el contenido (el dibujo de un lienzo 1080p toma 2–30 ms; 3 subfotogramas × 5400 fotogramas lo multiplica). Registra el presupuesto y mantenlo.
6. Congela la interfaz, luego hashea. Tamaño del lienzo, superficie/API de la página, CLI del trabajador, rutas de salida. Todo el QC está vinculado a ese hash de revisión — un render QC contra un hash obsoleto no vale nada.
7. Registra las desviaciones deliberadas. Cada lugar donde la realidad se aparta del resumen (una oscilación de cuadrícula en líneas "limpias", microtipografía más pequeña que el mínimo indicado, una tasa de resorte fuera del rango indicado) va a una lista corta con una razón, para que un revisor pueda juzgar en lugar de descubrir.

1. Tres sondeos en el primer día

Sonda	Afirmación	Por qué
Integridad de captura	píxeles exactos, alfa == 255, rango de color, primer/último fotograma presente	la acumulación translúcida, los errores de rango/espacio de color arruinan silenciosamente toda la película
Coste	distribución de ms de render(t) por escena, memoria	los cambios de arquitectura son baratos ahora, caros después
Movimiento	serie de diferencias por fotograma en toda la duración + la racha congelada más larga	muestra los rangos de tiempo muerto inmediatamente

Reglas que surgieron de fallos reales:

• La trampa de la composición blanca. Revisar fotogramas a través de un visor que compone alfa sobre blanco oculta la translucidez; la codificación compone sobre negro. Haz que la ruta de revisión componga exactamente como la ruta de entrega, y compara un píxel entre las dos.
• Saber lo que una métrica puede ver. Después de una reducción de escala 12×, el movimiento subpíxel de una línea fina cambia la diferencia absoluta media en ~0.03/255, mientras que un cambio de brillo en todo el fotograma la mueve ~1.5/255. Si la métrica de aceptación es una media reducida, la palanca real más barata es un canal de valor global (por ejemplo, un pulso de luminancia de 2 Hz ±3 % al ritmo del beat), no una oscilación más grande.
• Verifica la métrica antes que el activo. Cuando una comprobación falla, primero vuelca la señal bruta (envolvente a 1 ms, perfil de fila de píxeles, serie de fotogramas). La mitad de "el activo está mal" resulta ser el detector.
• Haz que los detectores sean auto-descriptivos. Modela y compensa el sesgo sistemático (retardo de grupo del filtro, retardo de ventana de análisis causal); prefiere el candidato más cercano al evento sobre el más ruidoso; nunca ajustes un umbral hasta que pase.
• Afirmaciones exactas vs aproximadas. "render(0) ≡ render(D), PSNR ∞" es una prueba; "el primer vs el último fotograma codificado difieren en 2/255 (un fotograma de movimiento)" es una observación. Nunca difumines los dos en un informe.

Incluido: scripts/av_audit.mjs implementa la mitad de contenedor/movimiento/bucle/sonoridad/hoja de esto (solo ffmpeg, sin dependencias npm).

2. El bucle de revisión es una característica, no una sobrecarga

• Ponlo en cuadrícula: cientos de fotogramas fijos → una docena de hojas de contactos, revisadas en una sola pasada.
• Incorpora guías: cuadro de área segura, cruz central, código de tiempo, id de evento. El revisor no debería tener que mantener el diseño en la cabeza.
• Muestrea por evento, no por intervalo fijo: un fotograma en cada evento previsto y uno a mitad de movimiento.
• Mira con más atención las costuras: transiciones de escena, envoltura de bucle, límites de segmento, primer/último fotograma.
• Aísla y amplía un elemento sospechoso en un lienzo en blanco a 4–6×; la mayoría de los errores son invisibles en el fotograma completo.
• Los artefactos son desechables: un comando los regenera; nunca parches manualmente un fotograma de revisión.
• Mantén una lista de problemas (desordenado / fuera de ritmo / superpuesto / fuera del área segura / ilegible / congelado) y vuelve a revisar después de cada ronda de correcciones.

3. Artesanía de movimiento y bucle

• Ambiente ≠ acción. Cada escena necesita un canal continuo a una frecuencia diferente de la acción (deriva, onda, rotación inactiva, pulso de valor) con cruces por cero alineados con el ritmo para que las acciones sigan aterrizando limpiamente. Esto es lo que satisface "nada está nunca congelado".
• Una familia de easing. Muelle críticamente amortiguado 1-(1+x)e^-x (nunca sobrepasa) para movimientos; ease-out/in exponencial para transiciones, presiones, salidas. Haz que el aterrizaje coincida con el evento: inicio = evento − duración, y normaliza para que el progreso = 1 exactamente en el evento.
• Desenfoque de movimiento en dos lugares: dentro de la función de fotograma (2–4 muestras de obturador promediadas con un promedio móvil — alpha = 1/(k+1) — que termina completamente opaco), más denso alrededor de eventos; más una mezcla temporal del lado del codificador. Prueba la semántica de la ventana de filtro con un accesorio codificado por índice (alimenta fotogramas cuyos píxeles codifican el número de fotograma y lee qué índices se promediaron), nunca de la documentación.
• Continuidad por construcción. Lleva un modelo de geometría/estado a través de las escenas y transfórmalo (morfosis, intercambio de material, inundación de borde duro, línea de escaneo) en lugar de cortar o disolver.
• Morfosis que preservan la longitud: parametriza formas por ángulo/longitud de arco para que las mezclas crezcan en lugar de escalarse.
• Lista prohibida por defecto (elimina a menos que se solicite): partículas, resplandores, destellos de lente, vibración de cámara, división RGB, transiciones encadenadas, degradados genéricos, sobrepaso elástico.

4. Renderizado y codificación

• Formato vs objetivo: mide el rendimiento primero. Los fotogramas PNG sin pérdida son multi-MB y cargan el conducto; JPEG de alta calidad es ~1.5× más rápido. Decide una vez, luego manténlo.
• Tubería, no bobina: alimenta fotogramas a stdin de ffmpeg (-f image2pipe -framerate <fps*sub> -vcodec png -i -). Mezcla con tmix, selecciona el último fotograma del grupo, re-temporiza, -frames:v <n> para recortar.
• Paraleliza por coste, no por número de fotogramas. Mide ms por escena, luego divide en fragmentos de aproximadamente igual tiempo; los recuentos uniformes de fotogramas hacen que el trabajador más lento establezca el tiempo de pared.
• Los segmentos deben ser seguros para concatenar: repite 2 fotogramas de límite en cada extremo, parámetros de codificador y base de tiempo idénticos, verifica fotogramas/duración con ffprobe, luego concatena con -c copy.
• Escenifica el pipeline para que un fallo cueste una etapa: renderizar → mezclar → codificar → audio → multiplexar → medir; cada etapa escribe un archivo.
• Mantén un master de video sin pérdida entre etapas (-c copy en todas partes), y haz la sonoridad al final.
• Sondea un conjunto de herramientas desconocido antes de confiar en él: listas de filtros/codificadores, ejecutables del navegador, versiones; permite anulaciones $FFMPEG/$FFPROBE; prefiere binarios locales fijados sobre conjeturas de PATH. Un ffmpeg "media" despojado enviado con un navegador generalmente carece de x264/tmix/loudnorm.
• Captura la salida secundaria a través de descriptores de archivo, no de tuberías. Dentro de un espacio aislado confinado, spawn/execSync con stdio: 'pipe' puede fallar con EPERM mientras que el mismo binario se ejecuta bien desde un shell. Pasa identificadores de archivo abiertos en su lugar: spawnSync(cmd, a, { stdio: ['ignore', fdOut, fdErr] }), luego lee los archivos — y usa stdio: 'ignore' para sondeos de existencia/versión puros. Dirige stdout y stderr a archivos separados para que los datos de fotogramas binarios no se intercalen con el texto de registro.
• Termina con una reconstrucción de extremo a extremo desde la fuente, para que el archivo entregado no sea una caché afortunada.

5. Audio y multiplexación

• Misma base de tiempo y mismo determinismo que la imagen (renderizado fuera de línea, con semilla, sin dependencia en tiempo real).
• Una tabla de eventos ({t, nombre}) como la única fuente de verdad para cada evento audible/visible; los efectos de sonido viven en su propio bus, más silenciosos que la música.
• Normaliza con loudnorm de dos pasadas (print_format=json → measured_* → segunda pasada con linear=true), luego verifica con una tercera medición independiente; afirma la sonoridad integrada dentro de ±0.5 LU y el pico verdadero ≤ objetivo.
• Bucles: desvanece la cola (~40 ms) a cero exacto, primera muestra sin clic; mide la alineación del golpe percusivo con la cuadrícula e infórmala.
• Multiplexa -c:v copy -c:a aac -b:a <espec>, luego ffprobe el contenedor como una aserción, no una mirada.
• -b:a Nk es un objetivo, no un suelo para el codificador AAC nativo de ffmpeg (medido ~180–250 kbps contra una solicitud de 320k en material silencioso; -aac_coder twoloop ayuda). Lee el bit_rate declarado e informa el promedio medido en lugar de repetir el número solicitado, y dilo explícitamente cuando la especificación exija una tasa de bits.

Incluido: scripts/mux_normalize.mjs.

6. Mantén la capa de dibujo barata y determinista

• Almacena en caché todo lo invariante en el tiempo: fondos horneados, máscaras de texto, patrones, Path2D. Las claves de caché contienen cada parámetro que pueda cambiar píxeles.
• Los grupos de lienzos deben dimensionarse desde las dimensiones del lienzo fuente, no del tamaño de contenido lógico — de lo contrario, drawImage estira o recorta silenciosamente (esto produjo tipo recortado/alterado).
• Evita shadowBlur/filter en el bucle de fotogramas; prefiere geometría.
• Memoria: un lienzo 1080p es ~8 MB; limita el grupo.
• Recuerda que el recuento de subfotogramas multiplica el presupuesto de fotogramas linealmente.

7. Colaboración

• Divide autor vs verificador. El verificador posee los scripts de QC y la autoridad para fallar el entregable, y verifica independientemente dimensiones que el autor no hizo (alfa, fidelidad vs página, sonoridad, cierre de bucle). Esto es lo que captura la clase de error al que el autor es ciego.
• Ámbitos de escritura separados + una interfaz congelada para que el trabajo paralelo no pueda chocar; hashea la revisión y vuelve a ejecutar QC después de cualquier cambio.
• Fallar alto: salidas no cero, una línea PASS/FAIL por afirmación, JSON para cualquier cosa leída por máquina, sin alternativas silenciosas.

8. Anti-patrones

1. Juzgar el color a través de una imagen de revisión compuesta en blanco.
2. Editar el activo para satisfacer una métrica que nunca caracterizaste.
3. Ajustar el umbral de un detector en lugar de arreglar su modelo.
4. Volver a ejecutar el renderizado completo para responder una pregunta que un sondeo de 20 segundos del lado de la página responde.
5. Fragmentación uniforme por recuento de fotogramas en escenas de coste muy diferente.
6. Una ruta de revisión que difiere de la ruta de entrega (escala, rango de color, composición).
7. "Se veía bien" en lugar de una aserción; fallos que salen con 0.
8. Cirugía de texto/activos con herramientas que alteran caracteres no ASCII (verifica la codificación después de la edición).
9. Arreglar fotogramas de revisión a mano en lugar de arreglar la fuente.
10. Ocultar una discontinuidad de estado detrás de una transición encadenada.

9. Listas de verificación

Pre-vuelo — especificación → aserciones; firma de render(t) congelada; política de costuras + álgebra de bucle; activos incrustados; tres sondas existen; presupuesto por fotograma establecido; FFMPEG/FFPROBE resuelto y probado en capacidad.

En vuelo — después de cada escena: sonda de coste, serie de movimiento, cuadrícula de revisión muestreada por eventos; lista de problemas cerrada; verificación de sintaxis/tipo más una verificación no-ASCII en fuentes editadas; hashea la revisión.

Pre-entrega — reconstruir desde la fuente; renderizado completo (ponderado por coste, fotogramas límite, concatenación verificada); sonoridad de dos pasadas + tercera verificación; script de medición independiente → PASS/FAIL; informa afirmaciones exactas vs aproximadas explícitamente; elimina scripts/capturas de pantalla temporales y documenta el comando de regeneración para cada uno.

Definición de completado — metadatos del contenedor exactos; comportamiento de costura probado; límite de ejecución congelada cumplido; sonoridad/pico verdadero cumplido; texto en pantalla coincide con el resumen al pie de la letra; un comando reconstruye desde la fuente; todo QC verde en el hash congelado.

10. Scripts incluidos

Ambos son de un solo archivo, sin dependencias (solo ffmpeg/ffprobe), resuelven sus herramientas de $FFMPEG/$FFPROBE → PATH → ubicaciones comunes, imprimen una línea PASS/FAIL por afirmación, emiten JSON con --json, y salen con código no cero en caso de error. Resuelven su directorio desde la propia ruta de esta habilidad.

# QC de un archivo terminado: contenedor vs expectativas, límite de ejecución congelada, costura de bucle,
# sonoridad/pico verdadero, hojas de contactos opcionales para revisión humana
node av_audit.mjs film.mp4 --expect-duration 30 --expect-fps 60 --expect-size 1920x1080 \
     --static-limit 0.5 --sheets ./sheets        # exit 0 = todas las comprobaciones pasaron

# Normaliza un WAV a un objetivo y lo multiplexa en un video codificado (flujo de video copiado),
# luego verifica con una tercera pasada de medición independiente
node mux_normalize.mjs silent.mp4 score.wav film.mp4 --lufs -14 --tp -1 --abr 320k

av_audit.mjs usa deliberadamente una serie MAD de baja resolución (160×90): ve cambios de valor de fotograma completo y movimiento de bloque, no movimiento subpíxel de líneas finas — combínalo con la regla de sensibilidad métrica en §1. Para un bucle, trata first_vs_last_psnr_db como una observación sobre un fotograma de movimiento y prueba la exactitud por separado comparando dos renders del propio renderizador.

Resumen de una línea — el éxito depende de tres cosas, ninguna de ellas habilidad de dibujo: la función de tiempo es pura y verificable, las métricas se entienden antes de optimizarse, y las rutas de revisión y entrega son la misma ruta.