bluemountain1231/cinematic-web-promo

video-shotcraft: Creación de Videos Promocionales con Estilo Cinematográfico

Una biblioteca de capacidades autocontenida: 152 tarjetas de plano (con código de demostración funcional y una galería dinámica de muestras), una plantilla completa de video promocional ya verificada, componentes reutilizables y activos de audio, y un flujo de trabajo de seis etapas.

El enfoque actual son los videos promocionales para productos web/escritorio, pero las tarjetas de plano en sí mismas son un vocabulario universal de efectos de movimiento; también se pueden usar individualmente para crear planos concretos en cualquier tipo de video.

Determinar el modo antes de proceder

El video promocional completo tiene tres modos que no se combinan entre sí. Antes de comenzar la recopilación de materiales, el storyboard o la implementación, primero determine si el usuario ya ha elegido un modo; si ya lo ha hecho, ejecútelo directamente sin preguntar de nuevo y no lo cambie a otro modo.

1. Usar la plantilla directamente: Mantener el flujo de reemplazo original de Ink Press. Lea template/TEMPLATE.md y reemplace las capturas de pantalla, el texto y la información de la marca del producto objetivo según la estructura de planos existente.
2. Creación autónoma y libre: Lea references/pipeline.md. El agente, basándose en los requisitos del usuario y el contenido del proyecto, decide de forma autónoma la dirección visual, el mapeo de planos, el storyboard, los materiales y el audio, avanzando continuamente hasta el producto final; sin pausar para esperar la confirmación del usuario en las etapas de briefing del producto, styleframe, mapeo de planos o storyboard.
3. Creación colaborativa: Lea references/guided-free-creation.md. El agente primero presenta juicios y propuestas fundamentadas, y el usuario confirma secuencialmente el briefing del producto, las decisiones de requisitos, la dirección visual, el mapeo de planos y el storyboard final; una vez aprobado el storyboard, se procede a la etapa de recopilación final de materiales y producción según references/pipeline.md.

Cuando el usuario proporciona la ruta del proyecto, una URL, una grabación de pantalla o capturas de página pero aún no ha elegido un modo, primero realice una inspección mínima y de solo lectura del producto: comprender el posicionamiento del producto, las funciones principales, la apariencia visual de la página, el estado mostrable y los riesgos de los materiales; no modifique el proyecto de negocio, no recopile datos sensibles ni escriba código de video. Después de la inspección, presente los tres modos y explique:

• Si Ink Press es adecuado para el producto, con fundamentos concretos de por qué sí o no;
• Si la creación autónoma y libre y la creación colaborativa son adecuadas respectivamente, y qué pistas visuales del producto se conservarían;
• El modo recomendado por el agente y sus fundamentos y compensaciones.

Luego pregunte explícitamente: "Según la inspección del producto anterior, recomiendo usar el modo ××. ¿Desea continuar con este modo?"

Al mismo tiempo, informe al usuario que puede visitar https://vincentwei1021.github.io/video-shotcraft/ para explorar las muestras dinámicas y seleccionar los efectos de movimiento que desea usar en el video.

Cuando el usuario aún no haya proporcionado un proyecto o página que pueda inspeccionarse, presente brevemente los tres modos y luego pregunte; no recomiende Ink Press por defecto solo porque es una plantilla existente.

• El usuario elige la plantilla: Lea completamente template/TEMPLATE.md y ejecute según el flujo de la plantilla original.
• El usuario elige la creación autónoma y libre: Lea completamente references/pipeline.md. El agente avanza de forma autónoma sin esperar confirmación etapa por etapa.
• El usuario elige la creación colaborativa: Lea completamente references/guided-free-creation.md y colabore según los puntos de confirmación indicados.
• El usuario aún no ha decidido: Deténgase aquí y espere la selección; no elija por defecto por el usuario ni comience la producción.

Excepción 1: Cuando el usuario ya ha mencionado explícitamente la plantilla Ink Press, se considera que el modo de plantilla está seleccionado. Por ejemplo, "Usa la plantilla Ink Press para hacer un video promocional de mi producto". En este caso, no pregunte de nuevo; lea directamente y completamente template/TEMPLATE.md y ejecute según la ruta de la plantilla.

Excepción 2: Cuando el usuario ya ha especificado claramente que desea usar o hacer referencia a ciertas tarjetas de plano, la restricción de planos ya está seleccionada. Por ejemplo, "Usa deck-deal-flyin y row-embed para este video" o "Consulta el efecto de spotlight-hero-card". En este caso, no presente la plantilla ni pregunte si desea usarla; confirme las tarjetas especificadas según las reglas de resolución de nombres de la Galería, lea completamente cada tarjeta, y localice el código de demostración exacto según la "Implementación de referencia" de la tarjeta. Los planos individuales se pueden ejecutar una vez que los materiales objetivo estén claros; para un video promocional completo, si aún no se ha indicado si se usará la creación autónoma y libre o la colaborativa, solo pregunte por estos dos modos, usando las tarjetas especificadas como restricciones de producción posteriores, sin equipararlo automáticamente a creación colaborativa.

Cuatro usos

1. Video promocional completo (ruta de plantilla): Si desea un efecto muy similar al video de la plantilla → Lea template/TEMPLATE.md y siga la "Guía de reemplazo de producto" para sustituir los materiales plano por plano.
2. Video promocional completo (creación autónoma y libre): Si desea un nuevo estilo y autoriza al agente a decidir de forma autónoma → Lea references/pipeline.md y avance continuamente desde la comprensión del producto hasta la inspección final, sin pausar etapa por etapa.
3. Video promocional completo (creación colaborativa): Si desea participar en las decisiones clave → Lea references/guided-free-creation.md, confirme el briefing del producto, las decisiones de requisitos, la dirección visual, el mapeo de planos y el storyboard final; una vez aprobado, continúe desde la recopilación final de materiales de la línea de producción.
4. Plano individual / efecto individual: Seleccione una tarjeta de references/shots/ (o deje que el usuario elija en la galería gallery/), lea el contenido completo de la tarjeta y localice el código de demostración exacto según la "Implementación de referencia", y adáptelo a los materiales objetivo.

Límite entre creación autónoma y libre y creación colaborativa

Creación autónoma y libre: Delega las decisiones creativas y de ingeniería al agente. El agente deriva dinámicamente las prioridades del producto, la dirección visual, el mapeo de planos, el storyboard, el procesamiento de materiales y el esquema de audio a partir del contenido del proyecto, registra las decisiones clave y las ejecuta directamente; a menos que falten entradas necesarias que no se puedan inferir de forma segura, no pregunta, no pausa etapa por etapa ni exige confirmación de productos intermedios. Los requisitos explícitos del usuario son siempre vinculantes y no pueden ser anulados por la elección predeterminada del agente.

Creación colaborativa: Utiliza la confirmación etapa por etapa. Por defecto, lea references/guided-free-creation.md. En cada ronda, solo haga 1–3 preguntas que más puedan reducir el retrabajo, y pause en los puntos de briefing del producto, decisiones de requisitos, dirección visual, mapeo de planos y storyboard final para esperar la confirmación del usuario. El usuario confirma la dirección comercial y creativa; el agente completa de forma autónoma los métodos de recopilación, parámetros de implementación, fijación de SFX, ingeniería de Remotion, renderizado y QA técnico.

En la creación colaborativa, si el usuario dice explícitamente "Tú decides todo" o "Salta la confirmación y hazlo directamente", cambie al modo de creación autónoma y libre y registre esta elección; no afirme estar avanzando de forma autónoma mientras sigue solicitando confirmación etapa por etapa.

El mapeo de funciones a planos es solo "qué sintaxis de movimiento usar", no un storyboard completo. Después de confirmar el mapeo en la creación colaborativa, el agente debe continuar proporcionando el orden de los planos, la duración, las imágenes específicas, el estado de la página, las fuentes de materiales, los subtítulos, las transiciones y los SFX; solo después de confirmar el storyboard completo se procede a la recopilación final de materiales. Cuando el usuario copia el nombre de un plano desde la Galería, solo necesita proporcionar el nombre de la tarjeta o "nombre de tarjeta · nombre de estilo"; el agente se encarga de leer la tarjeta de receta local y el código de demostración.

Conceptos centrales

1. Para recrear una página existente, se deben usar capturas de pantalla reales; la creación manual de UI se limita a escenarios no recreativos, y la calidad y claridad de expresión son requisitos estrictos. Al representar la página real del producto, el primer paso es iniciar un servidor de desarrollo local, usar un navegador sin cabeza para capturar la textura de la página completa a 2x, junto con el recorte de elementos y la tabla de coordenadas layout.json. En escenarios no recreativos (apertura abstracta, segmento de marca, componentes de exhibición independientes) se permite crear UI manualmente, pero si no alcanza una calidad de nivel profesional o el espectador no entiende lo que expresa, se debe volver a la ruta de capturas de pantalla. Los datos de la página se tratan según el riesgo: los datos de demostración pública solo se pueden conservar después de que el briefing del producto lo confirme explícitamente; los datos de clientes, personales, internos, claves, en tiempo real u otros datos sensibles deben reemplazarse con contenido ficticio o anonimizado, y congelarse antes de la recopilación.

2. El lenguaje visual de todo el video debe surgir del producto mismo, no se puede crear una "piel de video promocional" no relacionada. Antes de hacer un styleframe, primero extraiga y escriba una especificación de diseño a partir del sistema de diseño del producto/sitio web, el código fuente o los estilos computados: familias tipográficas y pesos, jerarquía de tamaños de fuente, interlineado/espaciado entre letras, cuadrícula, espaciado, alineación, densidad de información y bordes redondeados, así como colores de fondo/superficie/texto principal/énfasis/estado, degradados y materiales. Todos los títulos, subtítulos, números, tarjetas de texto, tipografía, transiciones, partículas, efectos de luz y otras combinaciones de colores de efectos de movimiento en el video deben reutilizar o extender con moderación estos tokens, al mismo tiempo que coinciden con el tono, el gusto y la textura del producto. Al seguir la ruta de la plantilla o las tarjetas de plano, solo herede su estructura de planos, sintaxis de movimiento, ritmo y parámetros ya ajustados; la tipografía, la disposición, la combinación de colores y los materiales deben reemplazarse según el producto objetivo. Si es necesario desviarse de la apariencia visual del producto por razones narrativas, en la creación colaborativa primero explique la razón y solicite la confirmación del usuario; en la creación autónoma y libre, registre la razón y la compensación en la especificación de diseño y continúe.

3. La sensación cinematográfica proviene de la coordinación de movimientos de cámara, iluminación, ritmo y sonido, no de animaciones ostentosas. Lo que ha sido repetidamente aprobado: el arco de movimiento completo de un solo protagonista (foco → acercamiento → flotación → retorno), aceleración impulsada por metáforas físicas (repartir cartas), tomas cercanas con órbita de cámara lateral, frase sonora de riser → impacto → destello. La entrada de elementos en lote se basa en el movimiento en sí mismo, no en hacer brillar cada uno; los destellos decorativos/envíos masivos de brillo son de baja calidad, pero un solo efecto de luz de alta calidad es aceptable.

4. Cada plano cuenta solo un efecto de movimiento; una vez que la información clave se establece, debe haber un respiro. Una técnica de animación (vuelo/apilamiento/volteo de página) solo es protagonista una vez en todo el video; los planos repetidos y los lemas repetidos se eliminan. La preferencia de ritmo es unidireccional: todos los comentarios históricos apuntan a "ralentizar/permanecer", nunca una vez "demasiado lento". Cuando el logotipo de la marca se establece, mantener ≥1s, dejar 0.5s de inmovilidad al final de los efectos en lote, dar 3s para la acción principal de apertura. Al planificar la línea de tiempo, reserve presupuesto de fotogramas para hold/rest.

5. En videos con música de fondo de ritmo fuerte, todas las transiciones y efectos de movimiento deben sincronizarse con el ritmo. El usuario ya ha elegido la música → antes de comenzar, realice un análisis de ritmo (ajuste de cuadrícula con librosa para obtener BPM/fase reales + detección de golpes de bombo/caja/hi-hat en tres categorías). La cuadrícula se aprueba solo después de verificar la cobertura de transientes; la línea de tiempo se escribe con notación de compás beatF(n), los acentos dispersos se fijan en transientes reales en lugar de puntos interpolados de la cuadrícula, y después del renderizado, extraiga la pista de audio del video terminado para medir el error de corte ≤3f. La metodología se encuentra en references/music-beat-sync.md. Para videos con música de fondo, el renderizado final siempre entrega dos versiones: con música de fondo y sin música de fondo (conservando SFX), utilizando el inputProp bgm desde la misma línea de tiempo, para que el usuario pueda agregar su propia música en la postproducción.

6. Para usar efectos de movimiento de tarjetas de plano, primero debe analizar el índice de la Galería y leer el código de demostración exacto. Primero use gallery/api/library.json para verificar el nombre de la tarjeta y style-key, luego localice el TSX específico según la "Implementación de referencia" del documento de la tarjeta. La tarjeta de receta proporciona semántica y tabla de parámetros; el código de demostración exacto es la verdad de los parámetros ajustados (curvas de easing, proporción de tiempo, momento de enmascaramiento, escritura para evitar errores conocidos). Se permiten adaptaciones, pero los parámetros marcados como "errores conocidos/puntos críticos" en la tarjeta no se pueden degradar; el estándar de calidad solo puede subir, no bajar. Escribir nuevo basándose solo en el nombre de la tarjeta y la comprensión = abandonar toda la acumulación de ajustes.

7. En la creación colaborativa, las confirmaciones de bajo costo se colocan al principio; en la creación autónoma y libre, los mismos juicios se registran como registros de ejecución. El orden de briefing del producto → tabla de decisiones de requisitos a ejecución → dirección textual → styleframe → mapeo de planos → storyboard no cambia; en la creación colaborativa se entrega al usuario para confirmación nivel por nivel, en la creación autónoma y libre el agente lo selecciona de forma autónoma y avanza continuamente. Ninguno de los dos modos debe entrar en la implementación plano por plano sin tener clara la dirección.

8. Revisión a lo largo de todo el proceso + revisión independiente antes de la entrega. A partir de la etapa 5, cada plano se autoinspecciona con npx remotion still para generar fotogramas fijos; después de cada ronda de modificaciones, renderice todo el video y extraiga fotogramas con ffmpeg para revisión; antes de la entrega, debe asignar un subagente con contexto limpio para realizar una revisión final independiente. La entrada de la revisión incluye el video terminado, fotogramas clave, briefing del producto, tabla de decisiones de requisitos a ejecución, dirección visual/styleframe confirmada o registrada en el modo actual, mapeo de funciones a planos, nombre/variante de la tarjeta de la Galería, TSX de demostración exacto, muestras/fotogramas de referencia de la Galería, storyboard final, tarjetas de plano seleccionadas y criterios estéticos; según references/final-review.md, verifique simultáneamente la consistencia del esquema, la integridad funcional, la fidelidad de los planos, la calidad técnica visual/audio y la seguridad de los datos, entregando un informe con evidencia de números de fotograma uno por uno. El creador tiene sesgo de confirmación sobre su propio producto; la primera revisión nunca debe ser entregada al usuario.

9. Renderizado determinista: Prohibir Date.now()/Math.random(). Toda pseudoaleatoriedad debe tener una semilla fija (mulberry32/hash, semilla derivada del índice), reproducible fotograma a fotograma.

Flujo de trabajo

La creación autónoma y libre sigue references/pipeline.md desde la etapa 0 de forma continua, sin esperar confirmación del usuario etapa por etapa. La creación colaborativa primero completa la comprensión del producto, dirección visual, mapeo de planos y confirmación del storyboard de las etapas 0–3 según references/guided-free-creation.md, luego continúa desde la etapa 4 de la línea de producción (recopilación final de materiales), sin repetir preguntas ni rediseñar. En las etapas 2–3, escanee los frontmatter de cada tarjeta en references/shots/ y seleccione planos según la curva de energía; en las etapas 5–7, realice la autoinspección continua contra references/aesthetic-rules.md; en la etapa 6, lea references/sound-design.md; para videos sincronizados con el ritmo, siga references/music-beat-sync.md en todo momento.

Cuándo leer cada archivo

Momento	Leer
Inicio del proyecto y modo no definido	Inspección mínima de solo lectura, luego ofrecer tres modos de video promocional completo y recomendar
Creación autónoma y libre	pipeline.md (el agente completa las etapas 0–7 de forma autónoma, sin esperar confirmación etapa por etapa)
Creación colaborativa	guided-free-creation.md (confirmar etapas 0–3), luego continuar desde pipeline.md etapa 4
El usuario ya ha elegido música de fondo	music-beat-sync.md (analizar antes de hacer storyboard)
Ruta de plantilla	template/TEMPLATE.md completo
Diseño de storyboard	Plantillas de segmento en sequences/ (rellenar el esqueleto completo primero); todo el frontmatter en shots/; leer completamente las tarjetas seleccionadas
Implementación plano por plano	Texto completo de esa tarjeta de plano + código de demostración exacto localizado según "Implementación de referencia" + componentes correspondientes en assets/lib/
Diseño de sonido	sound-design.md + assets/audio/
Revisión	final-review.md + aesthetic-rules.md completo para pasar lista de verificación (ejecutado por un subagente independiente)

Uso de activos

• Componentes de assets/lib/: Cópielos en el nuevo proyecto y modifíquelos libremente (no importe desde esta biblioteca). Lista: PageCam (cámara de página 2.5D – la base de todos los planos de "página real"), DigitRoll, FlashCut, Caption, FlatPanel, VerticalTicker (muro de desplazamiento infinito 3D), helpers (rand/shake/camera/motion). FlatPanel y helpers/camera requieren las dependencias three + @react-three/fiber + @remotion/three; el resto solo necesita remotion.
• assets/scripts/capture-template.mjs: Copie y modifique CONFIG (BASE/ruta/selector) en la parte superior.
• assets/audio/: Use los efectos de sonido directamente copiándolos (licencia gratuita comercial, consulte audio/ATTRIBUTION.md): audio/bgm/ son opciones de música de fondo con fuerte ritmo; audio/sfx/<categoría>/ contiene 149 efectos de sonido en 16 categorías según la escena (transition impact riser camera ui text paper film light data scifi mech glass fluid crowd counter). Para buscar un sonido, primero vaya al directorio de la categoría; la lista completa está en sound-design.md. El nombre del directorio para sparkle es light/ (no sparkle/); S1 prohíbe el timbre pero no la acción – si la imagen realmente tiene un clic/interruptor, se debe agregar sonido Foley, pero la mitad de ui/ son sonidos sintéticos de retroalimentación (tone/bleep/notification) que deben escucharse uno por uno, no se puede aprobar todo el directorio (lista en sound-design sección 3.3); las muestras largas y los materiales de sonido ligero tienen listas que requieren tratamiento especial (sound-design 4.1).
• demos/: Código fuente de implementación de cada tarjeta. La mayoría son demostraciones en escala de grises autocontenidas (algunas importan componentes de escena UI falsos de demos/_fixtures/Fixtures.tsx, algunas importan texturas de página real de demos/_textures/). Cópielos en un proyecto de Remotion y ejecute. Algunas demostraciones usan @remotion/motion-blur (CameraMotionBlur), necesitan npm i @remotion/motion-blur; la lista está en demos/README.md.
• template/: Un proyecto de Remotion completamente renderizable: npm install && npx remotion render src/index.ts AiflPromo out/promo.mp4.
• gallery/: Galería estática. Dé prioridad a la versión en línea para el usuario: https://vincentwei1021.github.io/video-shotcraft/library.html . Si se ejecuta localmente, primero ejecute gallery/fetch-media.sh para descargar las muestras (mp4 no están en git), luego cd gallery && python3 -m http.server 4178. 152 tarjetas y 209 muestras dinámicas para navegar, buscar y copiar nombres de tarjetas con selección múltiple – ideal para que el usuario vea las muestras y elija planos.