dengyie/onevideo

O que onevideo faz?

OneVideo divide "fazer um vídeo" em 10 estágios. Cada estágio tem um documento de direção (stages/<id>.md), um produto registrado (plan/*.json) e portões mecânicos; estágios que exigem aprovação humana precisam de aprovação, que bloqueia o hash do produto. O mecanismo de renderização compartilhado está em template/, e o diretório do projeto contém apenas dados.

Como funciona

1. onevideo status mostra o status de cada estágio e qual documento de direção ler em seguida. Ao entrar em um estágio, leia o stages/<id>.md correspondente antes de agir.
2. Estágios criativos (research, proposal, script, storyboard) são feitos escrevendo JSON / Markdown, depois onevideo validate, e então mostrar o produto ao usuário. Após confirmação, execute onevideo approve <stage>. Não aprove pelo usuário a menos que ele autorize explicitamente.
3. Estágios não criativos são executados via CLI: tts, music, assets fetch, depth, timeline, render, qc. Use build para executar até qc (ativos faltantes são baixados automaticamente; se houver ferramenta de profundidade, mapas de profundidade e grade de brilho são gerados automaticamente). publish exige que review esteja aprovado.
4. A estrutura é organizada pelas perguntas do público (proposal escreve uma cadeia de perguntas, script escreve question para cada cena); as imagens são divididas em três linhas: narração explica, texto na tela mostra apenas palavras-chave, e imagens fornecem evidências (storyboard.md).
5. O storyboard é escrito segundo o mecanismo de movimento: leia primeiro references/motion-rules.md, consulte examples/spacex-motion. Protagonista usa filmagem real (footage com velocidade ajustada, título posicionado atrás do sujeito), elementos digitais entram no canvas em voo contínuo. Cada cena tem shots. Ganchos e conclusão usam uma palavra-chave word por frase. Com música, escreva music.offset: "auto". onevideo timeline reporta avisos de ritmo (imagem sem novidade por mais de 4,5s, transições iguais consecutivas) que devem ser resolvidos ou justificados ao usuário.
6. Após renderizar, execute obrigatoriamente onevideo qc e veja um a um os quadros em out/qc/frames/ para confirmar que a imagem está correta antes de approve review.

Você é o diretor

O ritmo está sob seu controle: por que cada plano está ali, quanto tempo dura, como cortar — tudo é decidido por você e escrito no storyboard. CLI e modelos são apenas ferramentas; as conclusões que eles fornecem devem ser verificadas por você antes de usar.

• Se faltar imagem, crie você mesmo: em assets.json, escreva generate. Pode gerar imagens (variants: 2–4 gera múltiplas, o modelo visual escolhe uma com base no brief, todas as opções ficam em public/assets/<id>.take<k>.*; se a escolha estiver errada, escreva pick para alterar). Pode gerar vídeo (kind: "video", from: <id da imagem> faz uma imagem se mover a partir do primeiro quadro). Se a geração falhar, há fallback para url / query do mesmo item, então é melhor ter uma fonte alternativa para ativos críticos. Quando possível, use fontes reais; gerados servem apenas para preencher lacunas, criar atmosfera ou conceitos, não para se passar por filmagem jornalística.
• Ver o vídeo: onevideo sheet gera uma folha de contato do vídeo final segundo a segundo (out/qc/sheet-NN.jpg, também mostra onde cada cena começa). Use Read para ver a folha de contato, muito mais rápido do que quadro a quadro. onevideo look pede ao modelo visual para revisar o vídeo sob critérios de edição; o resultado é escrito em out/qc/look.json, com cada observação incluindo tempo e cena. É apenas uma segunda opinião: primeiro confirme o problema na folha de contato ou em stills, depois modifique o storyboard.
• Faça uma amostra de 15 segundos primeiro: antes de renderizar o vídeo completo, execute render --draft --scenes hook,ipo (ou --from 0 --to 15) para renderizar o início, confirmar estilo, narração, tamanho da fonte, ritmo, e então renderize o vídeo completo.
• Itere: modifique o storyboard → timeline (resolva avisos de rhythm / echo) → render --draft [--scenes …] --note "o que mudou" → sheet --vs prev para comparar com a versão anterior / look → modifique novamente. A cada ciclo, mude apenas uma coisa, compare para confirmar que melhorou antes de mexer em outra; após confirmado, use handoff --lock "…" para registrar e não mexa mais.
• Handoff: ao trocar de sessão ou delegar a um subagente, execute primeiro onevideo handoff. Ele escreve o estágio, parâmetros definidos, QC dos ativos, versões recentes de renderização, opiniões de revisão e avisos pendentes em plan/handoff.md, preservando as seções manuais "bloqueado / próxima iteração só muda / observações". Ao assumir um projeto existente, leia plan/handoff.md.
• Paralelismo: pesquisa, busca de ativos e geração de ativos são independentes e podem ser delegados a subagentes em paralelo. Storyboard e ritmo são escritos por você, não terceirize.

Regras rígidas

• Cada número na narração deve ser encontrado em plan/research.json nos facts, e os facts devem ter fontes (portão numbers). Não invente fontes para passar pelo portão.
• Ativos usam apenas licenças da lista branca (references/licensing.md); ativos CC BY devem creditar autor e fonte.
• Chaves de API são lidas apenas de variáveis de ambiente ou configuração local da máquina; não imprimir nem escrever em arquivos do projeto. Chaves compartilhadas (MANGO_API_KEY, etc.) são enviadas apenas para api.mangoqwq.com; se mudar o baseUrl, deve configurar um keyEnv dedicado. A configuração de provider em ~/.zcode é lida apenas quando ONEVIDEO_ZCODE_PROVIDER=1 está explicitamente definido.
• Se um produto aprovado for alterado, o estágio fica marcado como stale, e deve ser mostrado novamente ao usuário para approve. Após alterar o script, deve executar tts novamente; caso contrário, o portão timings falha e a renderização é bloqueada. Não modifique 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íntese frase por frase → plan/timings.json (com normalização de loudness)
onevideo music [--preset ambient|pulse|documentary|bright]
onevideo assets search <q> [--provider nasa,wikimedia,openverse,pexels] | assets fetch [--only a,b] [--force]   # Inclui generate: IA gera imagem / vídeo
onevideo depth [asset ids] [--step N]               # Mapa de profundidade + grade de brilho: travessia do sujeito, desvio de palavras-chave, adição automática de fundo, desvio de legenda
onevideo capture <url> --id x [--device phone|tablet|desktop] [--click sel] [--rects name=sel,…] [--full] [--dark]   # Captura de tela real de interface (inicia Chrome headless)
onevideo screen <asset> [--at s] [--threshold 40]   # Encontra cantos pretos em filmagem real → segmento footage.screen
onevideo stems                                     # Exporta trilhas separadas por stem para 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 uma versão → out/versions/vN
onevideo versions                                   # Registro de renderização: versão, intervalo, hash da timeline, observação
onevideo handoff [--lock …] [--next …]              # Página de handoff → plan/handoff.md
onevideo lib list|search|recipe <name> --id x --set k=v   # Efeitos sonoros / Lottie / receitas de plano
onevideo sheet [--fps 1] [--from s] [--to s] [--video v3] [--vs prev]   # Folha de contato → out/qc/sheet-NN.jpg; --vs comparação nova vs. antiga
onevideo look [--focus "legibilidade da legenda"] [--models a,b]   # Modelo visual revisa vídeo → out/qc/look.json
onevideo qc | publish [--stems] | build [--draft] | doctor | decide <category> <subject> --selected X

Quando não instalado globalmente, use node <repo>/cli/onevideo.mjs … para chamar.

Referências

• Definição do pipeline: pipelines/*.json; estilos visuais: styles/*.json
• Escrita: references/writing-zh.md · Pronúncia: references/tts-pronunciation.md
• Cena e movimento: references/motion-rules.md (leia primeiro) · references/scene-catalog.md
• Dados e licenciamento: references/data-integrity.md · references/licensing.md
• QC: references/qc-thresholds.md
• Exemplos: examples/spacex-motion/ (demonstração do mecanismo de movimento, 36s) · examples/spacex-ipo/ (versão com gráficos de dados, 85s) · examples/promo-demo/ (pipeline promo: captura de tela + cena device, 20s); onevideo init demo --example spacex-motion