TimeCraker/video-motion

video-motion — Superponer animaciones sobre material de video (Remotion)

Diseño como código: coordenadas / instantes / textos se declaran en src/cues.ts (contrato de datos, los campos no se modifican), los componentes FX tienen cero codificación rígida; cambiar cues y ejecutar un comando vuelve a generar el video completo. Tres capas de animación: SubtitleTrack (subtítulos) / DataBars (barras de datos) / Spotlight (focos: circle / arrow / box).

Los diagramas técnicos, capturas de procesos/datos, Lottie, 3D, mapas o la edición de parámetros en Studio se basan en las ramas correspondientes según producción visual especializada. El director proporciona el contenido y la dirección visual; los módulos de producción entregan los activos/código reales del proyecto y la evidencia de renderizado. Se priorizan los componentes, tipos e interfaces del motor actuales.

Para la coherencia de la serie, según consistencia de serie, las convenciones de la columna se aplican a los tokens, fuentes, escenas, subtítulos, portadas y pistas de audio reales del proyecto. Se reutiliza la versión de entrada real y se renderiza con el contenido actual para comparar; no se considera que cambiar un valor de tema unifica todo el video. Las demostraciones de productos utilizan material real grabado/capturado con anotaciones superpuestas; los clics del ratón o los focos posteriores deben corresponder a acciones y resultados reales.

Paso 1 · Diseño del guion (ver el material, no adivinar la imagen)

1. Extraer fotogramas del material: npx remotion still remotion/index.ts FootageOverlay <output>/f-<n>.png --frame=<n>, seleccionar fotogramas según tomas y cambios clave; usar la ruta absoluta de la imagen generada para leerla
2. Escribir el guion de animación en src/cues.ts:
   • Los subtítulos explican la imagen: dicen lo que el espectador ve en ese momento, segmentados según el significado y la velocidad de lectura
   • Los focos señalan objetos reales: circle / arrow / box apuntan a elementos que existen realmente en la imagen y merecen atención; las coordenadas se verifican primero con los fotogramas extraídos
   • Los números requieren fuente: los valores de las barras de datos provienen de fuentes reales (HUD de la imagen, panel de resultados, datos del backend); si no se pueden obtener, se indica en el subtítulo "datos de demostración"
3. Interpretar los detalles relevantes para el objetivo: HUD, chat, indicaciones y acciones pueden ser evidencia, pero solo se etiqueta el contenido necesario para la explicación; no llenar todo el video por densidad de cues.

Paso 2 · Ingeniería y especificaciones (adaptación según el material)

1. Copiar templates/remotion-app/ al directorio de trabajo, ejecutar npm install (todos los subpaquetes de Remotion deben instalarse en el mismo lote, las versiones están estrictamente vinculadas); después de la instalación, ejecutar npm run typecheck (la tolerancia de esbuild no equivale a tipos limpios, solo después de pasar tsc se revela la verdad; la plantilla incluye typescript como devDependency, listo para usar)
2. Especificaciones nativas: node scripts/probe-footage.mjs <ruta del material> usa ffprobe para generar src/footage-params.ts: la resolución de salida / frecuencia de cuadros sigue al material, no se fija; al cambiar el material, simplemente vuelve a ejecutar este script
3. El material no entra en la skill: renderizar con --public-dir <directorio de material> (staticFile lee directamente la biblioteca de material del proyecto); solo copiar el material como public/footage.mp4 cuando no sea conveniente pasar parámetros
4. Los cues se escriben asumiendo coordenadas de diseño a 1080p, FootageOverlay ya incluye transformOrigin: "top left" para escalar y adaptarse a cualquier lienzo: al cambiar la resolución no se modifican los cues, la posición de las animaciones no se desplaza.

Paso 3 · Generación (un solo comando)

Antes de renderizar, pasar primero la verificación: node scripts/verify-cues.mjs (para el deck, usa los parámetros de src/deck-cues.ts); solo cuando los errores estén en cero se procede al renderizado. Las advertencias de duración total solo informan, no bloquean.

cd <remotion-app>
npx remotion render remotion/index.ts FootageOverlay <repositorio>/products/<nombre-proyecto>/demo.mp4 --crf=16 --public-dir <directorio material>

El producto se ubica en el repositorio products/<nombre-proyecto>/ (regla de directorio: la skill es una herramienta pura, el producto no cae dentro de la skill; al usarlo entre repositorios, cae en la raíz del proyecto output/<nombre-skill>/); --crf=16 para alta calidad. El renderizado de material grande se ejecuta en segundo plano (1440p60 × 30s aproximadamente 10 minutos), se verifica por código de salida + ffprobe, no por barra de progreso.

Paso 4 · Verificación en tres niveles (obligatorio, no se puede saltar)

① Programa: código de salida del renderizado 0; npx remotion compositions remotion/index.ts muestra que durationInFrames / ancho / alto / fps coinciden con los metadatos del material; npx remotion still selecciona fotogramas representativos según subtítulos clave, cambios de datos y transiciones: para cada subtítulo start+0.3s / end-0.3s, para barras de datos t-0.3s / t+1.5s, para focos t+0.5s / t+ttl+0.3s (convertir a número de fotograma usando el fps real de la salida de compositions).

② Inspección de imágenes: leer los PNG reales fotograma por fotograma para verificar: momento de aparición/desaparición con texto, proporción de altura de barras con etiquetas de valor, tipo y posición de focos, sin artefactos ni distorsión en el material base, sin caracteres extraños en todo el fotograma (el chino usa Microsoft YaHei como fallback). Los problemas se retroalimentan al archivo fuente correspondiente, se re-renderiza y se verifica el problema original y la continuidad adyacente; si se encuentra un bloqueo que no se puede diagnosticar o reparar, se informa claramente.

③ Reproducción continua y revisión auditiva: los fotogramas extraídos no prueban el ritmo ni la sincronización; según el método audiovisual de media-qc, verificar el clip real y la pista de audio, registrando el alcance de la revisión; el usuario final aprueba el video terminado.

Paso 5 · Entrega

Informe: ruta y tamaño del video terminado / resolución y fps (nativos del material) / conclusión de la verificación en tres niveles (incluyendo tabla de verificación de fotogramas extraídos) / ubicación de cues.ts (se puede volver a ejecutar). El producto y el mp4 no se incluyen en git.

Video página por página desde PPT (DeckVideo, segundo tipo de video)

Un mismo motor, dos tipos de video: los pasos anteriores son "superponer animaciones sobre material de video", esta sección es "página por página desde PPT" — imágenes de diapositivas pptx + narración página por página que genera directamente el video terminado. La duración de cada página sigue la longitud real de la narración, y los subtítulos aparecen según la línea de tiempo del guion segmentado.

1. pptx y guion segmentado: producto pptx de la skill ppt; escribir el guion de narración segmentado script.json, ref debe ser "page N" (N=número de página); primero pasar python skills/narration/templates/verify_narration.py <script.json> para que todo esté en verde. Cada segmento después de dividir debe tener ≤20 caracteres (el subtítulo en una sola línea se muestra directamente como texto del segmento); los segmentos múltiples dentro de una página se conectan con puntos para formar la locución de esa página.
2. Imágenes de página: python scripts/extract_pages.py <in.pptx> public/deck/pages — COM convierte a PDF y fitz renderiza a 200dpi, generando p-<N>.png (2667×1500, el lienzo se llena con contain).
3. Locución: para pruebas, ejecutar powershell -File scripts/make_deck_audio.ps1 <script.json> public/deck/audio (SAPI Huihui genera page-N.wav por página); en el flujo real, la locución se realiza manualmente página por página en Jianying (剪映), exportando el archivo page-N.wav con el mismo nombre en el mismo directorio, el flujo descendente no nota la diferencia.
4. Conexión y renderizado: node scripts/build-deck-params.mjs <script.json> public/deck genera src/deck-params.ts + src/deck-cues.ts (inicio de página / duración total / distribución de tiempo de subtítulos son todos valores derivados, no modificar manualmente) → npx remotion render remotion/index.ts DeckVideo <repositorio>/products/<nombre-proyecto>/deck.mp4 --crf=16.
5. Verificación en tres niveles: igual que el Paso 4 (programa ffprobe / conciliación de compositions + inspección de fotogramas extraídos + visualización por el usuario). Puntos clave de L2 para extracción de fotogramas: primer fotograma de cada página +0.3s para verificar el orden de página; en el punto medio de superposición, tomar inicio de la página siguiente +0.25s (el final de la superposición está en la cola de la ventana de página, 0.5s de disolución cruzada); subtítulos start+0.3s / end+0.3s para verificar texto y salida. En el primer fotograma de página +0.3s, la entrada spring no está completa, el fotograma completo es ligeramente grisáceo; es un estado intermedio de transición, no un defecto.

Las imágenes de página y la locución residen en public/deck/ (.gitignore ya lo cubre, no entra en git); el lienzo 1920×1080@30 es una constante en la parte superior de build-deck-params.mjs, modificando dos líneas se obtiene 4K.

Proceso de calidad para la evolución de escenas v2 → v3 (scene-kit renderizado directo, tercer tipo de video)

Línea de mejora del video página por página desde PPT: el sujeto de la imagen pasa de "imagen de página PPT" a escenas animadas renderizadas directamente por componentes de Remotion (src/scene-kit/ 24 componentes); la duración de página/audio/mecanismo de subtítulos continúa usando la cadena derivada de deck-params. Para juzgar si es "simple" o "de baja calidad", consultar docs/2026-08-30-motion-grammar.md; esta sección son las reglas estrictas del proceso de calidad.

Línea base de calidad

Según el tipo de contenido de docs/2026-08-30-motion-grammar.md, seleccionar el método de aceptación. Mantener la consistencia de tokens y marca. La imagen se centra en el sujeto real y la información legible; el movimiento explica el cambio. El espacio en blanco, la quietud y la cantidad de información de apoyo por plano se juzgan según el objetivo del plano, sin aplicar cuotas fijas ni veto de PPT estático.

Primero, el content-director proporciona la fuente de los hechos, el storyboard y el briefing artístico; luego se revisan los fotogramas representativos y las muestras cortas. Los diagramas de estructura priorizan SVG; las interfaces reales usan capturas de pantalla/video; las ilustraciones, cuando sea necesario, se conectan a herramientas de generación de imágenes disponibles y se registran los activos. Los nuevos ArtLayer y más animaciones no representan automáticamente la aprobación de la calidad artística.

Método de diseño de escenas (general, sin respuestas predefinidas)

Primero consultar assets/patterns.md como biblioteca de soluciones de páginas: si hay una entrada PAT ya verificada para una situación similar, adaptar y modificar parámetros (la situación → formato → componentes → trampas → fotogramas de referencia están todos en la entrada); si no, diseñar desde cero. Para cada página, primero determinar el tipo de contenido del texto (narrativa de dolor/demostración de función/convicción de datos/explicación de proceso/concepto/llamada a la acción, seis tipos); luego, según las tres reglas "el sujeto lo determina el contenido del texto, el mismo tipo de página no repite el mismo esquema visual, la familia de fondos sirve a la emoción del contenido", determinar la forma del sujeto y la combinación de componentes. Antes de comenzar, producir una tabla de diseño (cada página: resumen del texto → tipo de contenido → forma del sujeto → familia de fondo → combinación de componentes → razón → paquete de información de imagen ítem por ítem + fuente → anotación del sujeto); la tabla de diseño se revisa previamente, solo después de aprobada se escribe código; la información de apoyo se marca ítem por ítem con su fuente (guion de locución/documento del proyecto/contenido visible del material).

Tres lecciones duras (escritas como reglas)

1. El estado final permite pausas para lectura: cuando chat, gráficos o procesos necesitan mostrar cambios de estado, usar componentes existentes; los planos estáticos se juzgan por información y ritmo, no se imponen animaciones decorativas solo para pasar la revisión.
2. Los componentes envoltorios deben pasar explícitamente width: al envolver un componente antiguo con un contenedor nuevo, perder width = el elemento a nivel de bloque se expande para llenar el contenedor padre (ilustración que tapa el título, funda de móvil que se expande a 700px de ancho, dos rondas con la misma causa raíz); los contenedores envoltorios siempre deben usar style={{ width, ...style }}.
3. Las capturas largas deben verificar primero la tasa de espacio en blanco antes de decidir el enfoque: al obtener una captura larga, primero calcular la desviación estándar/proporción de espacio en blanco por fila (un script PIL); una "captura larga vacía" donde la carga perezosa no ha renderizado la imagen dentro de la captura es aire muerto al desplazarse: primero recortar el primer plano, reparar el material y luego volver al desplazamiento.

Arsenal de MG (S0-S6, munición principal para la calidad del video final)

La plantilla viene con un arsenal completo; para el catálogo de componentes y su uso por componente, consultar assets/component-catalog.md (scene-kit 24 componentes / entrance-kit nueve verbos / vendor selecciones de la comunidad / fonts). Aquí solo se anotan reglas férreas:

• Regla de versión: todos los @remotion/* deben tener exactamente la misma versión (ej. 4.0.533, sin ^): la discrepancia de versiones es un error duro de Remotion, no una advertencia. Al agregar un nuevo paquete, primero alinear con la versión existente (check-docs, ítem 3.7, lo supervisa; si se desvía, se pondrá rojo).
• Hechos de la API 4.0.533 (pueden diferir de la documentación/memoria; ya probados; la actualización 4.0.518→4.0.533 se verificó con still baseline PSNR todo inf, la forma de la API no cambia): evolvePath devuelve propiedades dash para path no recortado; interpolatePath(value, from, to) tres parámetros independientes; fitText solo acepta withinWidth y devuelve un objeto {fontSize}; el chino multilínea no puede usar fitTextOnNLines (divide por espacios); parseSrt acepta un objeto {input} (una cadena desnuda arroja undefined.split), devuelve {captions:[{text,startMs,endMs}]} en milisegundos.
• Trampa de envoltorios transform (doble trampa S6 confirmada): los verbos envoltorio con transform (CameraPush/SlideGroup/TextBreath/BlurTrail) no deben envolver directamente un subárbol con position:absolute: el elemento transform es el containing block de los descendientes absolute, la altura en flujo colapsa a 0, el contenido se desborda desde el borde superior. Los componentes ya son autosuficientes (CameraPush raíz inset 0, BlurTrail capa principal en flujo); al usarlos, evitar envolverlos desnudos en un padre absolute sin dimensiones.
• Semántica oficial de <Trail>/TransitionSeries: Trail raíz es AbsoluteFill (semántica de cobertura a nivel de página); los rastros a nivel de elemento usan BlurTrail de scene-kit (ya relative). TransitionSeries consume la duración de páginas adyacentes; el motor de video final usa cero transiciones por defecto (Series corte duro) + verbos dentro de la página.
• Disciplina vendor: copiar-pegar en el repositorio, no es dependencia npm; actualizar = volver a descargar y hacer intake de nuevo; cuatro reglas de disciplina en la plantilla src/vendor/README.md.
• Flujo de activos Lottie: JSON gratuito para uso comercial en assets/lottie/ (registrar tres campos en README) → al usarlo, copiar al proyecto public/ → LottieLayer src referencia. En el intake, prohibir JSON con expressions (el renderizado es incierto).
• Presupuesto de efectos complejos: ShutterBlur samples y BlurTrail layers aumentan el costo de renderizado; ThreeStage se prueba según escenario y máquina. Primero renderizar fotogramas representativos/clips cortos, luego decidir la escala; no establecer una cuota fija de planos para todo el video.

Proceso de aceptación (cuatro niveles)

L1 Programa (código de salida del renderizado, obtener el log completo, no usar pipe al final; ffprobe = conciliación de fotogramas con compositions); L2 Extracción de fotogramas (seleccionar según riesgo: entrada/panorama estable/primer plano de información/transiciones y fotogramas representativos de subtítulos, verificar la imagen real; ampliar solo para revisar detalles, no fijar cantidad por página); L2.5 Prueba en silencio (responder el punto principal de cada página a ciegas); L3 Informe (incluyendo alcance técnico, evidencia de fotogramas clave, elementos pendientes de revisión manual y, cuando sea necesario, comparación antes/después). Los componentes, tokens y formatos que se confirme que tienen valor general se retroalimentan a la plantilla/registro según reglas de retorno de activos; el contenido específico del proyecto se mantiene dentro del proyecto; si no hay nueva experiencia, no se crea un ticket adicional. El comando de renderizado es el mismo que DeckVideo (el composition se cambia al componente de escena, ej. DeckVideoV2); la portada se genera con npx remotion still (el número de fotograma still debe considerar la duración de la entrada spring).

Generación de portada (Cover, cuarto tipo de producto)

No renderizar un video, sino un solo fotograma: un comando genera un PNG de portada de 1920×1080 para acompañar el video al publicarlo.

1. Props: products/<nombre-proyecto>/cover-<nombre>.json escribe { title, subtitle?, badge?, bg?, preset }. preset ∈ photo (imagen bg cubre todo + degradado negro inferior 55% para asegurar contraste) / dark (degradado oscuro, por defecto) / clean (fondo claro + línea superior fina); bg es una ruta relativa bajo public/ de remotion-app. subtitle omitido = no renderizar; badge omitido = retroceder a la marca de esquina ASTERFORGE.
2. Renderizado: npx remotion still src/cover-index.ts Cover <output>.png --props=<ruta del archivo json> (entrada independiente que no pasa por Root.tsx, sin conflicto con DeckVideo que se desarrolla en paralelo).
3. Verificación: inspeccionar la imagen para verificar título completo sin truncar, texto legible bajo la máscara photo, sin caracteres extraños; usar ruta absoluta del producto real, verificar y confirmar la versión o hash actual. El número de líneas del título se ajusta según el tamaño del lienzo y las necesidades de lectura.

Límites y trampas

• Usar la ruta absoluta del producto real para leer la imagen, verificar y confirmar la versión del archivo o hash actual; solo convertir la ruta cuando la herramienta específica tenga restricciones de ruta.
• Consola GBK: imprimir todo en inglés.
• Chrome Headless Shell: la primera vez que npx remotion browser ensure descarga desde la fuente de Google (cientos de MB), la red en China puede exceder el tiempo de espera: falla e informa, no reintentar repetidamente la descarga de archivos grandes.
• Los medios grandes, dependencias y caché no entran en Git; las recetas de producción, portadas, subtítulos, configuraciones de publicación y metadatos de aceptación se conservan según las reglas de archivo.

Flujo actual y referencias técnicas

Usar node scripts/studio.mjs init --id <nombre> --line b para crear la plantilla; las dependencias de job.json y typecheck se pueden volver a ejecutar; los comandos de params/render/QC de este proyecto se agregan a job.json después de determinar la escena y la pista de audio real. Después del renderizado, llamar a media-qc; el informe técnico y la revisión final del usuario se registran por separado; después de pasar la verificación de archivo, limpiar el caché.

Las mejores prácticas oficiales de remotion se instalan fijamente en el caché del proyecto mediante python scripts/install-upstream-skills.py, y luego setup-skills las monta. La fuente está en references/upstream.json; es una referencia técnica, no reemplaza el flujo de trabajo de este repositorio. La referencia oficial 4.0.538 se gestiona por separado del motor actual 4.0.533; al usar una nueva API, primero verificar los tipos locales y el renderizado real, no actualizar automáticamente.