syklayou-glitch/video-shotcraft

video-shotcraft: Creación de vídeos de producto con calidad cinematográfica

Una biblioteca de capacidades autocontenida: 152 tarjetas de recetas de tomas (con código demo y galería dinámica de ejemplos), una plantilla de vídeo promocional completa y verificada, componentes reutilizables, activos de audio y un flujo de trabajo en seis fases. El enfoque actual son los vídeos promocionales de productos web/de escritorio, pero las tarjetas de tomas son un vocabulario de efectos genérico: también se pueden usar tarjetas individuales para crear tomas sueltas en cualquier vídeo.

Determinar el modo al invocar

Hay tres modos para el vídeo promocional completo, que no se mezclan entre sí. Antes de comenzar la recopilación de material, el storyboard o la implementación, determina si el usuario ya ha elegido un modo; si ya lo ha hecho, ejecuta directamente sin preguntar de nuevo ni cambiar a otro modo.

1. Usar la plantilla directamente: Mantén el flujo de reemplazo de Ink Press. Lee template/TEMPLATE.md y sustituye las capturas de pantalla, el texto y la información de marca del producto objetivo siguiendo la estructura de tomas existente.
2. Creación autónoma y libre: Lee 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 tomas, el storyboard, los materiales y el audio, avanzando continuamente hasta el vídeo final; no se detiene para esperar la confirmación del usuario en las fases de briefing, styleframe, mapeo de tomas o storyboard.
3. Creación colaborativa: Lee 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 tomas y el storyboard final; una vez aprobado el storyboard, se pasa a la fase de recopilación final de materiales y producción de references/pipeline.md.

Cuando el usuario ha proporcionado la ruta del proyecto, una URL, una grabación de pantalla o capturas de página pero aún no ha seleccionado un modo, realiza primero una inspección mínima y de solo lectura del producto: comprende el posicionamiento del producto, las funciones principales, el aspecto visual de la página, el estado mostrable y los riesgos de los materiales; no modifiques el proyecto de negocio, no recopiles datos sensibles ni escribas código de vídeo. Después de la inspección, presenta los tres modos y explica:

• Si Ink Press es adecuado para el producto, con motivos concretos a favor y en contra;
• Si la creación autónoma y la colaborativa son adecuadas cada una, y qué pistas visuales del producto se conservarían previsiblemente;
• Qué modo recomienda el agente y sus motivos y compensaciones.

Luego pregunta explícitamente: "Según la inspección del producto, recomiendo usar el modo ××. ¿Continuamos con este modo?" También informa al usuario de que puede visitar https://vincentwei1021.github.io/video-shotcraft/ para explorar ejemplos dinámicos y seleccionar los efectos que desee usar en el vídeo.

Si el usuario aún no ha proporcionado un proyecto o página que inspeccionar, presenta brevemente los tres modos y luego pregunta; no recomiendes Ink Press por defecto solo porque sea una plantilla ya preparada.

• Si el usuario elige la plantilla: lee completamente template/TEMPLATE.md y ejecuta según el flujo original de la plantilla.
• Si el usuario elige la creación autónoma: lee completamente references/pipeline.md, el agente avanza de forma autónoma sin esperar confirmación fase por fase.
• Si el usuario elige la creación colaborativa: lee completamente references/guided-free-creation.md y colabora siguiendo los puntos de confirmación indicados.
• Si el usuario aún no ha decidido: quédate aquí esperando la elección; no elijas por defecto por el usuario ni comiences la producción.

Excepción 1: Cuando el usuario ya ha mencionado la plantilla Ink Press, se considera que el modo plantilla está seleccionado. Por ejemplo, "Haz un vídeo promocional para mi producto usando la plantilla Ink Press". En este caso, no preguntes de nuevo, lee directamente template/TEMPLATE.md y ejecuta la ruta de la plantilla.

Excepción 2: Cuando el usuario ya ha especificado claramente que quiere usar o referenciar ciertas tarjetas de tomas, la selección de tomas ya está definida. Por ejemplo, "Usa deck-deal-flyin y row-embed para este vídeo" o "Referencia el efecto de spotlight-hero-card". En este caso, no presentes la plantilla ni preguntes si se debe usar; confirma las tomas especificadas según las reglas de resolución de nombres de la Galería, lee cada tarjeta por completo y localiza el código demo exacto según la "implementación de referencia" de la tarjeta. Las tomas individuales se pueden ejecutar una vez que el material objetivo esté claro; si aún no se ha especificado si el vídeo promocional completo se hará en modo autónomo o colaborativo, solo pregunta por estos dos modos, usando las tomas especificadas como restricciones para la producción posterior, sin que esto se considere automáticamente como creación colaborativa.

Cuatro usos

1. Vídeo promocional completo (ruta de plantilla): Para un resultado muy similar al vídeo de la plantilla → lee template/TEMPLATE.md y sigue la "guía de reemplazo de producto" para adaptar el material toma por toma.
2. Vídeo promocional completo (creación autónoma): Para un nuevo estilo y autorizar al agente a decidir de forma autónoma → lee references/pipeline.md, avanza desde la comprensión del producto hasta la revisión final sin pausas intermedias.
3. Vídeo promocional completo (creación colaborativa): Para participar en las decisiones clave → lee references/guided-free-creation.md, confirma el briefing del producto, las decisiones de requisitos, la dirección visual, el mapeo de tomas y el storyboard final; una vez aprobado, continúa desde la recopilación final de materiales en la fase 4 del pipeline.
4. Toma individual/efecto individual: Selecciona una tarjeta de references/shots/ (o deja que el usuario elija en la galería gallery/), lee la tarjeta completa y localiza el código demo exacto según la "implementación de referencia", adaptándolo al material objetivo.

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

Creación autónoma delega las decisiones creativas y de ingeniería al agente. El agente deriva dinámicamente del contenido del proyecto los puntos clave del producto, la dirección visual, el mapeo de tomas, el storyboard, el procesamiento de materiales y el esquema de audio, registra las decisiones clave y ejecuta directamente; a menos que falte información de entrada necesaria que no se pueda inferir de forma segura, no hace preguntas, no se detiene en fases intermedias ni solicita 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 fase por fase. Por defecto, lee references/guided-free-creation.md, y en cada ronda solo hace 1–3 preguntas que más reduzcan el retrabajo, deteniéndose en el briefing del producto, las decisiones de requisitos, la dirección visual, el mapeo de tomas y el storyboard final para esperar la confirmación del usuario. El usuario confirma la dirección de negocio y creativa; el agente completa de forma autónoma el método de recopilación, los parámetros de implementación, los puntos de anclaje de SFX, el proyecto de Remotion, el renderizado y el control de calidad técnico.

En la creación colaborativa, si el usuario dice explícitamente "tú decides todo" o "salta la confirmación y hazlo", cambia a modo autónomo y registra esta elección; no pretendas avanzar de forma autónoma mientras sigues solicitando confirmación fase por fase.

El mapeo de funcionalidad a toma 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 seguir proporcionando el orden de las tomas, la duración, las imágenes concretas, el estado de la página, las fuentes de material, los subtítulos, las transiciones y los SFX; solo después de confirmar el storyboard completo se pasa a la recopilación final de materiales. Cuando el usuario copia el nombre de una toma desde la Galería, solo necesita proporcionar el nombre de la tarjeta o "nombre de tarjeta · nombre de estilo", y el agente se encarga de leer la tarjeta de receta local y el código demo.

Principios fundamentales

1. Para recrear páginas existentes, deben usarse capturas de pantalla reales; la UI hecha a mano se limita a escenarios de no recreación, y la calidad y claridad de la expresión son requisitos estrictos. Para mostrar la página real de un producto, el primer paso es iniciar un servidor dev local, usar un navegador sin cabeza para capturar la textura 2x de la página completa + recortes a nivel de elemento + tabla de coordenadas layout.json. En escenarios de no recreación (apertura abstracta / segmento de marca / componentes de exhibición independiente) se permite UI hecha a mano, pero si no alcanza una calidad de nivel profesional o el espectador no entiende lo que expresa, se vuelve a la ruta de capturas de pantalla. Los datos de página se tratan según el riesgo: los datos de demostración pública solo pueden conservarse después de que el briefing del producto lo confirme explícitamente; los datos de clientes, personales, internos, de claves, en tiempo real u otros datos sensibles deben usar contenido ficticio o anonimizado, y congelarse antes de la recopilación.

2. El lenguaje visual de todo el vídeo debe nacer del propio producto, no de una "piel de vídeo promocional" no relacionada. Antes de hacer el styleframe, extrae y escribe la especificación de diseño del sistema de diseño del producto/sitio web, del código fuente o de los estilos calculados: familia y peso tipográfico, jerarquía de tamaños de letra, interlineado/espaciado, cuadrícula, espaciado, alineación, densidad de información y radio de esquina, y colores de fondo/superficie/cuerpo/é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 otros efectos de movimiento en el vídeo deben reutilizar o extender con moderación estos tokens, y al mismo tiempo coincidir con el tono, el gusto y la textura del producto. Al seguir la ruta de la plantilla o las tarjetas de tomas, solo hereda su estructura de tomas, sintaxis de movimiento, ritmo y parámetros ajustados; la fuente, la composición tipográfica, la paleta de colores y los materiales deben ser reemplazados para el producto objetivo. Si la narrativa requiere desviarse de la apariencia visual del producto, en la creación colaborativa explica primero el motivo y pide confirmación al usuario; en la creación autónoma, escribe el motivo y las compensaciones en la especificación de diseño y continúa.

3. La sensación cinematográfica proviene de la combinación de movimiento de cámara, iluminación, ritmo y sonido, no de animaciones llamativas. Lo que ha sido repetidamente aprobado es: arco de acción completo de un solo protagonista (foco → acercamiento → flotación → retorno), aceleración impulsada por metáforas físicas (reparto de cartas), toma en órbita con cámara en ángulo lateral, frase de sonido riser → impact → sparkle. La entrada de elementos en lote se basa en el movimiento en sí, no en brillos individuales: los destellos decorativos/envíos masivos de brillos resultan baratos; los efectos de luz de alta calidad en un solo punto son aceptables.

4. Cada toma cuenta un solo efecto; después de que la información clave se asiente, debe haber respiración. Un recurso de animación (entrada volando / apilamiento / paso de página) solo es protagonista una vez en todo el vídeo; las tomas repetidas y los taglines repetidos se eliminan. La preferencia de ritmo es unidireccional: todos los comentarios históricos apuntan a "ralentizar / permanecer", nunca una vez "demasiado lento": la marca de texto se asienta y mantiene ≥1 s, el final de los efectos en lote deja 0,5 s de reposo, el movimiento del sujeto de apertura da 3 s completos. Al diseñar la línea de tiempo, reserva presupuesto de fotogramas para las pausas/reposos.

5. En los vídeos con música de fondo de ritmo fuerte, todas las transiciones y efectos deben sincronizarse con el beat. El usuario ya ha elegido la música → antes de empezar, haz un análisis de ritmo (ajuste de cuadrícula con librosa para obtener BPM/fase reales + localización de golpes de bombo/caja/hihat en tres categorías), verifica la cuadrícula según la cobertura de transitorios antes de hacer el storyboard; escribe la línea de tiempo con la notación beatF(n), los acentos dispersos se anclan en transitorios reales en lugar de puntos de interpolación de la cuadrícula, después del renderizado extrae la pista de audio del vídeo final y verifica que el error de los puntos de corte sea ≤3 fotogramas. La sincronización con el beat se refiere al momento, no a la amplitud: los impactos de beat que afectan a toda la imagen/capa de cámara se consideran grandes slams, máximo 3 en todo el vídeo (regla estética R4); el resto de efectos en los beats solo afectan a la capa de elementos. La metodología se encuentra en references/music-beat-sync.md. Para los vídeos con música de fondo, el renderizado final entrega dos versiones: con BGM y sin BGM (conservando los SFX), renderizando desde la misma línea de tiempo usando la inputProp bgm, para que el usuario pueda añadir su propia música en la postproducción.

6. Para usar efectos de las tarjetas de tomas, primero se debe analizar el índice de la Galería y leer el código de implementación demo exacto. Primero usa gallery/api/library.json para validar el nombre de la tarjeta y el style-key, luego localiza el TSX específico según la "implementación de referencia" en el documento de la tarjeta. La tarjeta de receta proporciona la semántica y la tabla de parámetros; el código demo exacto es la verdad de los parámetros ajustados (curvas de easing, proporción de duración, momento de las máscaras, escritura para evitar problemas conocidos). Se permiten adaptaciones, pero los parámetros marcados como "problemas conocidos/punto débil" en la tarjeta no pueden degradarse: el estándar de calidad solo puede aumentar, no disminuir. Basarse solo en el nombre de la tarjeta y escribir algo nuevo desde cero equivale a abandonar toda la acumulación de ajustes.

7. La creación colaborativa antepone las confirmaciones de bajo coste; la creación autónoma registra las mismas decisiones como registro de ejecución. El orden de briefing del producto → tabla de decisiones de requisitos a ejecución → dirección textual → styleframe → mapeo de tomas → storyboard no cambia; en la creación colaborativa se entrega al usuario para confirmación etapa por etapa; en la creación autónoma el agente las selecciona y avanza de forma continua. Ninguno de los dos modos debe entrar en la implementación toma por toma sin haber definido la dirección.

8. Verificación continua durante todo el proceso + revisión independiente antes de la entrega. A partir de la fase 5, para cada toma usa npx remotion still para generar un fotograma fijo y autoinspeccionarse; después de cada ronda de modificaciones, renderiza el vídeo completo + extrae fotogramas con ffmpeg para revisar; antes de la entrega, un subagente con un contexto limpio debe realizar una revisión final independiente. La entrada de la revisión incluye el vídeo final, los fotogramas clave, el briefing del producto, la tabla de decisiones de requisitos a ejecución, la dirección visual/styleframe confirmada o registrada en el modo actual, el mapeo funcionalidad a toma, los nombres/variantes de las tarjetas de la Galería, el TSX demo exacto, los ejemplos de referencia/fotogramas de la Galería, el storyboard final, las tarjetas de tomas seleccionadas y las reglas estéticas; según references/final-review.md, verifica simultáneamente la coherencia del plan, la integridad funcional, la fidelidad de las tomas, la calidad técnica visual/de audio y la seguridad de los datos, generando un informe con pruebas numeradas por fotograma. El creador tiene sesgo de confirmación sobre su propio trabajo; la primera revisión nunca debe ser realizada por el usuario.

9. Renderizado determinista: Prohíbe Date.now() / Math.random(), todas las pseudoaleatoriedades deben usar una semilla fija (mulberry32/hash, la semilla se deriva del índice), reproducible fotograma a fotograma.

Flujo de trabajo

La creación autónoma sigue references/pipeline.md desde la fase 0 de forma continua, sin esperar confirmación del usuario fase por fase. La creación colaborativa primero completa las fases 0–3 de comprensión del producto, dirección visual, mapeo de tomas y confirmación del storyboard según references/guided-free-creation.md, luego continúa desde la fase 4 del pipeline (recopilación final de materiales), sin repetir preguntas ni rediseñar. En las fases 2–3, escanea los frontmatter de cada tarjeta en references/shots/ y selecciona las tomas según la curva de energía; en las fases 5–7, se autoverifica continuamente con references/aesthetic-rules.md; en la fase 6, lee references/sound-design.md; en los vídeos sincronizados al beat, sigue references/music-beat-sync.md en todo momento.

Después de la entrega del vídeo final en todos los modos, pregunta al usuario una vez si necesita exportar también el archivo de proyecto de Jianying (剪映) (donde puede modificar el contenido de los subtítulos, el tamaño de fuente, el color, la velocidad de las tomas, reordenarlas, ajustar o reemplazar el audio); si el usuario lo necesita o lo solicita explícitamente, lee references/jianying-export.md y ejecuta.

Cuándo leer cada archivo

Momento	Leer
Inicio del proyecto y modo no definido	Inspección mínima de solo lectura, luego ofrece tres modos de vídeo promocional completo y recomienda uno
Creación autónoma	pipeline.md (el agente completa las fases 0–7 de forma autónoma, sin esperar confirmación fase por fase)
Creación colaborativa	guided-free-creation.md (confirmación de fases 0–3), luego continúa desde la fase 4 de pipeline.md
Usuario ya ha elegido BGM	music-beat-sync.md (analizar antes de hacer el storyboard)
Ruta de plantilla	template/TEMPLATE.md completo
Diseño de storyboard	sequences/ (plantillas de segmentos: primero rellenar el esqueleto del vídeo completo); shots/ (todos los frontmatter); tarjeta seleccionada leer completa
Implementación toma por toma	Tarjeta de toma completa + código demo exacto según "implementación de referencia" + componente correspondiente en assets/lib/
Diseño de sonido	sound-design.md + assets/audio/
Verificación	final-review.md + aesthetic-rules.md (lista de verificación completa, ejecutada por subagente independiente)
Después de la entrega del vídeo (exportación a proyecto Jianying)	jianying-export.md + módulos de plataforma en jianying-export/

Cómo usar los activos

• assets/lib/: Los componentes se copian al nuevo proyecto y se modifican libremente (no importar esta biblioteca). Lista: PageCam (cámara de página 2.5D — base de todas las tomas de "página real"), ClipCard (envuelve material de vídeo mp4 externo como un "protagonista de tarjeta" que puede ser manipulado por el esqueleto de cámara de las tarjetas de tomas, con bucle de cross-fade OffthreadVideo — reproduce sin problemas si el material es más corto que la toma), DigitRoll, FlashCut, Caption, FlatPanel, VerticalTicker (muro 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: Copia y modifica la CONFIG superior (BASE/rutas/selectores).
• assets/audio/: Los efectos de sonido se copian y usan directamente (licencia comercial gratuita, ver audio/ATTRIBUTION.md): audio/bgm/ contiene opciones de BGM con ritmo fuerte; audio/sfx/<categoría>/ contiene 149 efectos de sonido en 16 categorías (transition impact riser camera ui text paper film light data scifi mech glass fluid crowd counter). Para buscar sonidos, primero entra en el directorio de la categoría; la lista completa está en sound-design.md. El nombre del directorio para el vocabulario "sparkle" es light/ (no hay sparkle/); S1 prohíbe el timbre, pero no la acción: si la imagen muestra un clic o un interruptor, debe tener el sonido foley correspondiente, pero la mitad de ui/ son sonidos de retroalimentación sintéticos (tone/bleep/notification) que deben escucharse uno por uno y no pueden aprobarse por directorio completo (lista en sound-design 3.3); las muestras largas y los sonidos ligeros tienen listas separadas que requieren tratamiento especial (sound-design 4.1).
• demos/: Código fuente de implementación de cada tarjeta. La mayoría son demos en escala de grises autocontenidas (algunas importan componentes de UI falsos de demos/_fixtures/Fixtures.tsx, algunas importan texturas de página real de demos/_textures/), se copian al proyecto Remotion y se ejecutan directamente; algunas demos usan @remotion/motion-blur (CameraMotionBlur), requiriendo npm i @remotion/motion-blur; la lista está en demos/README.md.
• template/: Proyecto renderizable completo: npm install && npx remotion render src/index.ts AiflPromo out/promo.mp4.
• jianying-export/: Módulo de exportación de proyecto Jianying: mac_draft.py (probado en Mac Jianying 11.2), windows_draft.py (implementado según la ruta de soporte ascendente, no verificado en hardware real), smoke_test.py (prueba mínima de humo para entornos nuevos). El flujo, la extracción de la línea de tiempo y los métodos de creación de pistas se encuentran en references/jianying-export.md; requiere venv + pip install pyJianYingDraft.
• gallery/: Galería estática. Da prioridad a la versión en línea: https://vincentwei1021.github.io/video-shotcraft/library.html ; para ejecutarla localmente, primero ejecuta gallery/fetch-media.sh para descargar los ejemplos (los mp4 no están en git), luego cd gallery && python3 -m http.server 4178. 209 ejemplos dinámicos de 152 tarjetas se pueden navegar/buscar/seleccionar múltiples y copiar nombres de tarjetas, ideal para que el usuario vea los ejemplos y elija las tomas.