OneVideo

¿Qué hace OneVideo?

OneVideo descompone "hacer un video" en 10 etapas. Cada etapa tiene un documento de dirección (stages/<id>.md), un artefacto consolidado (plan/*.json) y compuertas mecánicas; las etapas que requieren decisión humana necesitan aprobación, y la aprobación bloquea el hash del artefacto. El motor de renderizado compartido está en template/, y el directorio del proyecto solo contiene datos.

Modo de trabajo

1. onevideo status muestra el estado de cada etapa y qué documento de dirección leer a continuación. Al entrar en una etapa, lee primero su stages/<id>.md, luego actúa.
2. Las etapas creativas (research, proposal, script, storyboard) las escribes tú en JSON/Markdown, luego ejecutas onevideo validate, muestras el artefacto al usuario, y tras su confirmación ejecutas onevideo approve <stage>. No apruebes en lugar del usuario, a menos que te haya autorizado explícitamente.
3. Las etapas no creativas las ejecuta la CLI: tts, music, assets fetch, depth, timeline, render, qc. También puedes usar build para ejecutar todo hasta qc (descarga automática de assets faltantes, y si hay herramienta de profundidad, genera mapas de profundidad y cuadrícula de brillo). publish requiere que review esté aprobado.
4. La estructura se organiza según las preguntas de la audiencia (la propuesta escribe una cadena de preguntas, el guión escribe question por escena); las imágenes se dividen en tres líneas: la narración explica, el texto en pantalla solo muestra palabras clave, y las imágenes proporcionan evidencia (storyboard.md).
5. El storyboard se escribe siguiendo el motor de animación, no como una página por tarjeta: primero lee references/motion-rules.md, consulta examples/spacex-motion. El metraje real tiene al protagonista (velocidad variable del footage, título superpuesto detrás del sujeto), los elementos digitales vuelan en canvas de forma continua, cada escena tiene shots, el gancho y la conclusión tienen una palabra clave por frase (word), y si hay música escribe music.offset: "auto". onevideo timeline reporta advertencias de ritmo (cuadros sin novedad durante más de 4.5s, mismas transiciones consecutivas) que deben resolverse, o explicar al usuario por qué se mantienen.
6. Después del renderizado, ejecuta obligatoriamente onevideo qc, y revisa una por una las imágenes en out/qc/frames/, para confirmar que no hay problemas visuales antes de approve review.

Eres el director

Tú controlas el ritmo: decides por qué está cada plano, cuánto dura y cómo corta, y lo escribes en el storyboard. La CLI y los modelos son solo herramientas; sus conclusiones deben ser verificadas por ti antes de adoptarlas.

• Si faltan imágenes, créalas tú mismo: en assets.json escribe generate, puedes generar imágenes (variants: 2–4 produce varias, el modelo visual elige una según el brief, todos los candidatos quedan en public/assets/<id>.take<k>.*; si no te convence su elección, escribe pick para cambiarla), también puedes generar video (kind: "video", from: <id de imagen> para animar una imagen convirtiéndola en el primer fotograma). Si falla la generación, se recurre a la url/query de la misma entrada, así que para assets críticos es mejor dejar una fuente alternativa. Cuando haya assets reales disponibles, úsalos prioritariamente; los generados solo sirven para rellenar planos, crear atmósfera o conceptos visuales, no para suplantar metraje real de noticias.
• Visionado: onevideo sheet dispone el video final en una hoja de contactos por segundo (out/qc/sheet-NN.jpg, además muestra el fotograma de inicio de cada escena). Usa Read para la hoja de contactos, es mucho más rápido que revisar fotograma a fotograma. Luego onevideo look pide al modelo visual que revise según criterios de edición, y escribe los resultados en out/qc/look.json, cada observación con marca de tiempo y escena. Es solo una segunda opinión: primero confirma en la hoja de contactos o en stills que el problema realmente existe, luego modifica el storyboard.
• Primero haz un borrador de 15 segundos: antes de renderizar el video completo, ejecuta render --draft --scenes hook,ipo (o --from 0 --to 15) para renderizar el inicio, confirma que el estilo, la voz, el tamaño de fuente y el ritmo son correctos, luego renderiza el video completo.
• Iteración: modifica el storyboard → timeline (resuelve advertencias de rhythm/echo) → render --draft [--scenes …] --note "qué se cambió" → sheet --vs prev para comparar con la versión anterior / look → vuelve a modificar. En cada ronda cámbiale solo una cosa, compara para confirmar que ha mejorado antes de pasar a la siguiente; lo que ya está confirmado, documéntalo con handoff --lock "…" y no lo toques más.
• Traspaso: al cambiar de sesión o delegar a un subagente, ejecuta primero onevideo handoff, que escribe en plan/handoff.md el estado de las etapas, los parámetros ya definidos, la calidad de los assets, las últimas versiones del renderizado, las opiniones de visionado y las advertencias pendientes, y conserva las secciones manuscritas "bloqueado / solo cambiar en la próxima ronda / notas". Al retomar un proyecto existente, lee primero plan/handoff.md.
• Paralelismo: la investigación, la búsqueda de assets y la generación de assets son independientes entre sí y pueden delegarse a subagentes en paralelo. El storyboard y el ritmo los escribes tú mismo, no los externalices.

Reglas estrictas

• Cada número en la narración debe encontrarse en los facts de plan/research.json, y los facts deben tener fuente (compuerta de numbers). No inventes fuentes para pasar la compuerta.
• Los assets solo usan licencias de la lista blanca (references/licensing.md). Los assets con licencia CC BY deben incluir autor y fuente.
• Las claves API solo se leen de variables de entorno o la configuración local; no se imprimen ni se escriben en archivos del proyecto. Las claves compartidas (MANGO_API_KEY, etc.) solo se envían a api.mangoqwq.com; si se cambia la baseUrl, debe configurarse un keyEnv dedicado. La configuración del proveedor en ~/.zcode solo se lee si ONEVIDEO_ZCODE_PROVIDER=1 está definido explícitamente.
• Si un artefacto aprobado se modifica, la etapa muestra stale; debe mostrarse de nuevo al usuario y ejecutarse approve. Si se modifica el guión, debe reejecutarse tts obligatoriamente, de lo contrario la compuerta de timings falla y el renderizado se bloquea; no modifiques timeline.json manualmente.

Comandos

onevideo init <dir> --pipeline data-explainer|documentary|shorts|promo [--style midnight-data] [--aspect 16:9] [--example spacex-motion|spacex-ipo|promo-demo]
onevideo status | validate [--strict] | approve <stage> [--note …]
onevideo tts [--sample|--dry|--force|--only a,b]   # síntesis frase a frase → plan/timings.json (con normalización de loudness)
onevideo music [--preset ambient|pulse|documentary|bright]
onevideo assets search <q> [--provider nasa,wikimedia,openverse,pexels] | assets fetch [--only a,b] [--force]   # incluye generate: imágenes/video generados por IA
onevideo depth [asset ids] [--step N]               # mapa de profundidad + cuadrícula de brillo: cruce de sujeto, evitación de palabras clave, fondo automático, evitación de subtítulos
onevideo capture <url> --id x [--device phone|tablet|desktop] [--click sel] [--rects name=sel,…] [--full] [--dark]   # captura de pantalla real de interfaz (inicia Chrome sin cabeza)
onevideo screen <asset> [--at s] [--threshold 40]   # busca esquinas negras en metraje real → fragmentos de screen en footage
onevideo stems                                     # exporta pistas separadas por stem en WAV → out/publish/stems/
onevideo timeline | stills [--scene id] [--at 0.3,0.7] | studio
onevideo render [--draft] [--scenes a,b | --from s --to s] [--note …]   # cada vez una versión → out/versions/vN
onevideo versions                                   # registro de renders: versión, rango, hash de línea de tiempo, notas
onevideo handoff [--lock …] [--next …]              # página de traspaso → plan/handoff.md
onevideo lib list|search|recipe <name> --id x --set k=v   # efectos de sonido / Lottie / recetas de plano
onevideo sheet [--fps 1] [--from s] [--to s] [--video v3] [--vs prev]   # hoja de contactos → out/qc/sheet-NN.jpg; --vs compara versiones nueva y anterior
onevideo look [--focus "legibilidad de subtítulos"] [--models a,b]   # modelo visual revisa el video → out/qc/look.json
onevideo qc | publish [--stems] | build [--draft] | doctor | decide <category> <subject> --selected X

Si no está instalado globalmente, usa node <repo>/cli/onevideo.mjs … para invocarlo.

Referencias

• Definición del pipeline: pipelines/*.json; estilos visuales: styles/*.json
• Escritura: references/writing-zh.md · Pronunciación: references/tts-pronunciation.md
• Escenas y animación: references/motion-rules.md (léelo primero) · references/scene-catalog.md
• Datos y licencias: references/data-integrity.md · references/licensing.md
• Control de calidad: references/qc-thresholds.md
• Ejemplos: examples/spacex-motion/ (demostración del motor de animación, 36s) · examples/spacex-ipo/ (versión con gráficos de datos, 85s) · examples/promo-demo/ (pipeline promo: captura de pantalla + escena device, 20s); onevideo init demo --example spacex-motion