vvai-pixel-mv · Pixel MV com Personagens de Pixel

vvai-pixel-mv · MV de Personagens de Pixel com Batida

A ordem é fixa: História → Storyboard (o usuário vê, altera, pode repetir) → Aprovação do usuário → Renderização. Sem storyboard aprovado, não há renderização.

Exemplo completo em assets/examples/: história e story.json de uma música, com 7 segmentos, 3 personagens e visual de janela de desktop.

Preparação

• PY: Python 3.10+ com librosa, faster-whisper, numpy, Pillow instalados. Veja INSTALL.md para instalação. Se o CLAUDE.md ou memória do usuário indicar um caminho do Python, use esse; caso contrário, confirme se python consegue importar esses pacotes. Se não, pergunte ao usuário.
• MV: PY -X utf8 <caminho_do_skill>/scripts/pixel_mv.py.
• Requer ffmpeg e Node. A renderização padrão usa npx --yes [email protected]; para usar outro CLI, defina a variável de ambiente HF_CLI, separando argumentos com |.

Fluxo

1. Coletar materiais. É obrigatório ter áudio, letras com timestamps (SRT ou LRC) e o nome da música.
   • Opcional: tempo de início/fim, perfil de cor (base / neon / classic / retro), intensidade (dj / standard / soft), imagem de personagem.
   • Pergunte sobre a história: o usuário tem uma trama em mente? Se não, sugira uma na etapa 3.
   • Se não houver arquivo de letra, solicite ao usuário. Não use transcrição para adivinhar. Segmentos sem vocais devem ser perguntados ao usuário, não tratados como introdução. No episódio 1, o refrão foi erroneamente tratado como introdução.
2. Criar projeto: MV new <diretório_do_projeto> --audio <áudio> --lyrics <srt/lrc> --title <nome_da_música> [--start segundos --end segundos] [--look base] [--character imagem].
   • Esta etapa corta o áudio, detecta batidas e pontos de energia, e alinha as letras palavra por palavra.
   • Também gera um rascunho story.json com transições baseadas apenas em palavras-chave, e um modelo história.md.
   • O projeto é criado no diretório especificado pelo usuário; se houver um diretório de série fixo (definido em CLAUDE.md ou memória), use esse.
3. Escrever a história. Preencha história.md seguindo o método de contar histórias: história em uma frase, personagens, tema, atos, verso por verso. Envie para aprovação do usuário.
4. Escrever story.json. Converta a história em story.json.
   • Campos conforme o formato. Ações, interações de letra e transições disponíveis estão no diretório de interações.
   • O exemplo mais rápido é assets/examples/bad-girl.story.json.
   • Após escrever, execute MV check <projeto> até não haver erros.
5. Gerar storyboard para o usuário.
   • Execute MV board <projeto> --frames: ele captura 1–3 imagens por segmento e gera storyboard.md, com visão geral, personagens por segmento, ações de trama, letras e interações, transições, câmera e pontos de batida.
   • Use SendUserFile para enviar storyboard.md e as contact sheets em storyboard/imagens/.
   • Diga ao usuário o que pode ser alterado.
6. Iterar até aprovação. O usuário solicita alterações; modifique story.json e execute board novamente.
   • O número da versão aumenta automaticamente; versões antigas ficam em storyboard/historico/.
   • Pode repetir quantas vezes necessário, sempre enviando o novo storyboard.
7. Renderizar após aprovação.
   • Somente após o usuário dizer explicitamente "pode renderizar", execute MV approve <projeto> e depois MV render <projeto> --sample 12.
   • Respostas vagas ("ok", "tudo bem") não contam como aprovação.
   • render verifica a impressão digital do story.json; se foi alterado após aprovação, recusa renderizar.
   • Se o vídeo ultrapassar 30 MB, gere uma versão _preview.mp4 para celular.
8. Entrega. Visualize o resultado em 1 quadro/segundo: a história deve ser compreensível, cenários, letras, transições e título presentes; duração igual ao áudio original, com trilha sonora.
   • Se o usuário quiser alterações após a renderização, volte ao passo 6: altere story.json → novo storyboard → nova aprovação → renderize novamente.

Regras-chave

• História antes de efeitos. Cada linha deve ter pelo menos uma ação de trama ou interação de letra; ações devem acontecer no tempo da palavra-chave; transições devem ter justificativa narrativa. Veja o método de contar histórias.
• Transições de cena: Sem exigência de história, padrão é "desktop principal + inserções de imagem", conforme as regras de storyboard. Com história, siga os atos; segmentos de reflexão ou retrospectiva usam visual de janela de desktop.
• Personagens:
  • Por padrão, o boneco Claude é "eu".
  • Outros personagens são declarados com cast (girl, rival, friend, ghost).
  • Se o usuário fornecer uma imagem, execute MV character <projeto> <imagem> para convertê-la em um sprite de 16×16 pixels.
• Sincronização com a batida:
  • O personagem aterrissa exatamente em cada batida, achatando-se no chão e emitindo ondas de água.
  • A cada batida, há um impacto de câmera e flash de cor; nas batidas fortes, separação RGB.
  • Flash branco de tela cheia apenas em transições e drops, no máximo 3 vezes por segundo.
• Reações de susto: no máximo 2 vezes por vídeo, apenas em verdadeiras reviravoltas.
• Letras:
  • Aparecem apenas na imagem e nos arquivos do projeto; nas respostas do chat e no storyboard, use apenas números de linha.
  • Os direitos autorais da música são de responsabilidade do usuário; lembre-o antes da publicação.

Comandos

Comando	Descrição
new	Criar projeto: analyze + align + draft + story
story	Gerar modelo história.md (--force recria)
check	Verificar se nomes, tempos e janelas em story.json são reconhecidos pelo motor
board [--frames]	Gerar storyboard (versão N), salva histórico
approve	Registrar versão aprovada pelo usuário; render só libera após isso
render [--sample 12] [--name nome_arquivo]	Renderizar; --force ignora aprovação, usar apenas com autorização explícita do usuário
sync	Sincronizar story.json → assets/story.js (depuração; board e render fazem isso automaticamente)
upgrade	Atualizar projeto antigo para o motor de template atual; arquivos antigos viram .before-upgrade
character	Converter imagem em personagem pixel
analyze / align / draft	Etapas individuais do new; use para reexecutar separadamente

Personalização além do template

O motor de template v2 já cobre os seguintes itens, conforme o diretório de interações:

• 27 cenários, 16 ações básicas;
• 23 ações de trama;
• 7 modos de interação com letra, 6 entradas, 9 saídas;
• 7 transições;
• Janela de desktop.

Se ainda assim não for suficiente, adicione ao assets/engine.js do projeto, sem modificar o template do skill. Consulte as técnicas do Episódio 1. Para consolidar novas ideias no template, confirme com o usuário. Ao consolidar, altere todos estes locais:

• Template engine.js;
• Listas BEAT_NAMES etc. em pixel_mv.py, e os nomes em chinês ZH_* para o storyboard;
• interactions.md.

Biblioteca de Cenários

• Dados em assets/scene-library/scenes.json.
• Para adicionar um cenário, altere ambos: registre as palavras-chave e interações em scenes.json, e adicione o método de desenho em SCENES no template engine.js.