minara-video-skills /minara-videoscript

/minara-videoscript — Roteiros de vídeo Minara

Apenas roteiro, sem animação. A saída é um documento de roteiro em Markdown mais uma pasta de imagens de quadros-chave estáticas. Após a aprovação do operador, ele segue para as habilidades downstream:

Tipo de vídeo	Habilidade downstream
Filme de marketing / lançamento / demonstração (imagem construída em código, a UI pode ser redesenhada)	minara-video
Tutorial de caso de uso / iniciante (UI reconstruída fielmente)	minara-usecase-video
Legendas + narração sobre a gravação de tela do próprio operador	minara-guide-video
Cortar a narração gravada e colocá-la na trilha de narração	minara-voiceover (lê as colunas de Narração e Tempo da folha de quadros-chave)
Música / efeitos sonoros	minara-music (lê a seção de música e as dicas sonoras deste documento)

Estrutura: um suplemento de cena única tem 5 a 8 quadros-chave extraídos de um source.html; um filme completo geralmente tem 6 a 10 cenas. Escreva novos roteiros apenas em inglês.

A unidade central: o quadro-chave

Um roteiro é uma sequência de quadros-chave. Um quadro-chave é uma imagem estática de um momento que o espectador precisa ver, com tudo o que acontece ao redor escrito ao lado dele. Cada quadro-chave carrega os mesmos sete campos:

Campo	O que contém
Imagem	. Tag de origem: UI code / Figma / AIGC.
Tempo	Timecode que o still representa (40.5s) e o intervalo que cobre (39.8–41.6s).
Duração	Duração desse intervalo em segundos (pausa + o movimento que leva a ele).
Imagem (Picture)	O que está na tela e o que se move, em ordem. Movimento de câmera, se houver (aproximar no cartão de fluxo de trabalho).
Narração (Voiceover)	A fala dita neste intervalo, ou —.
Texto na tela (花字)	Texto exato, estilo, posição, tempo de entrada/saída. Ou —. Regras abaixo.
Música	Energia da música para este intervalo + qualquer dica sonora com seu tempo exato.

Contagem aproximada: um quadro-chave a cada 2–4 segundos de filme, pelo menos um por cena. Escolha os quadros onde algo já aconteceu (o prompt foi digitado, o gráfico foi desenhado, a notificação chegou), não durante o borrão do movimento.

Idioma: apenas inglês (o operador, 2026-10-19)

• Tudo no documento de roteiro está em inglês: título, notas, tabela de fluxo, campos do quadro-chave, narração, texto na tela, cópia da UI, notas de música, perguntas em aberto. Nenhuma linha de tradução em chinês, nenhuma coluna "中文对照", nenhum outro idioma. O mesmo vale para qualquer texto dentro das imagens dos quadros-chave.
• A cópia da UI é citada exatamente como aparece na UI do produto em inglês.
• O operador pode fazer o briefing em chinês; traduza o significado para o roteiro em inglês. Converse com ele em chinês no chat se ele escrever em chinês. Apenas o documento é em inglês.

Tom: calmo, neutro, natural

O roteiro deve parecer que foi escrito por uma pessoa, não por um modelo. Calmo e neutro: diga o que acontece, deixe o produto falar por si.

• Leia cada linha de narração em voz alta. Se soar como um anúncio, um gerador de slogans ou um comunicado de imprensa, reescreva. Se você não diria isso a um colega, corte.
• Verbos simples, frases curtas, tempo presente. Contrações são permitidas (it's, you'll). Exemplo do registro: Just ask. / Backtest it. / Minara builds the workflow. / Then it keeps watching.
• Neutro, não empolgado: sem adjetivos de hype, sem pontos de exclamação, sem CAIXA ALTA, sem emojis.
• Palavras proibidas: exciting, powerful, seamless(ly), effortless(ly), revolutionary, game-changing, unlock, unleash, elevate, supercharge, empower, cutting-edge, next-level, robust, leverage, harness, journey, landscape, delve, transform(ative), "at your fingertips".
• Padrões de IA proibidos:
  • "Not just X, but Y" / "It's not X. It's Y."
  • Listas de três para ritmo ("faster, smarter, safer")
  • "Imagine…", "What if…", "In a world where…", "Say goodbye to…", "Meet your new…"
  • Perguntas retóricas como iscas
  • Revelações com dois pontos ou travessão ("One thing changed: everything.")
  • Orações com -ing que adicionam profundidade falsa ("…, giving you full control.")
  • Preenchimento de significado ("a pivotal moment", "redefines how…")
• Lista completa de padrões: a lista de padrões de escrita de IA (ex. Wikipedia: "Signs of AI writing"). Execute cada linha de narração e cada pedaço de texto na tela contra ela antes de entregar.
• Sem promessas de lucro ("guaranteed", "risk-free"). Se backtests ou retornos aparecerem, anote onde a linha de risco vai (ex. Past performance does not guarantee future results.).
• Fatos que não estão no material de origem recebem ⚠️ e vão para "Perguntas em aberto". Não invente.

Fluxo de trabalho

1. Coletar entradas: briefing, capturas de tela, caminho do código frontend, link do Figma, notas de funcionalidade, corte existente, referência de música, se houver. Pergunte uma vez, em uma pergunta combinada, apenas o que não pode ser inferido: duração, paisagem/retrato, plataforma (X / Discord / site), narração ou não, onde se encaixa no filme, clima musical se o operador tiver um em mente.
2. Travar as escolhas de apresentação no topo do documento para que não se desviem: o caso de exemplo, qual superfície (Desktop / App / Web), fuso horário, o que não é mostrado. Escolha o caso pelas regras de tópico abaixo.
3. Rascunhar o texto primeiro: seção 1 (o que transmitir), o fluxo do usuário e a cópia da UI, a lista de cenas com temporizações e a lista de quadros-chave (IDs, tempos, imagem, narração, texto na tela, música). Ainda sem imagens. Isso evita que o trabalho de imagem direcione a história.
4. Criar as imagens dos quadros-chave pelas rotas abaixo, em docs/keyframes/<tópico>/K1.png …. Os quadros da UI vão primeiro (são gratuitos e exatos); pergunte antes de qualquer quadro AIGC que custe créditos.
5. Escrever o documento no docs/ do projeto (NN-script-scene-N-<tópico>.md para uma cena única; NN-script-<slug>.md para um filme completo). Raiz do projeto se não houver docs/. Abra cada PNG do quadro-chave e verifique-o em relação ao campo Imagem (Picture) antes de vinculá-lo.
6. Auto-verificação com a lista de verificação abaixo. Calcule as contagens de palavras da narração e a temporização; não estime.
7. Enviar ao operador: caminho do arquivo mais 3 a 5 linhas (duração, número de cenas, número de quadros-chave por origem, palavras da narração / parcela do tempo de execução, direção musical em uma linha, número de perguntas em aberto). Eles editam o roteiro e marcam os quadros-chave, não o código. Nenhuma animação antes da aprovação. Imagens estáticas são permitidas antes da aprovação; movimento não.
8. Após a aprovação: passar o bastão. O script downstream por segundo expande a partir dos tempos dos quadros-chave deste documento; nada é reescrito. minara-music cria cues.json a partir da seção Música. Para um conselho de revisão, gere storyboard.html a partir de assets/storyboard-template.html do minara-video; os quadros-chave AIGC mapeiam para suas linhas AIGC.

Criando imagens de quadros-chave

Três rotas. Use a primeira que se encaixar; um roteiro pode misturá-las, e cada quadro-chave diz qual foi usada.

Rota A — Código da UI (padrão para qualquer coisa que seja UI do produto)

O quadro é desenhado em HTML, então a cópia é exata e o quadro pode ser reutilizado pela animação posteriormente.

1. Copie assets/keyframes-source-template.html para docs/keyframes/<tópico>/source.html. Uma <section class="k" id="K1"> por quadro-chave; ?k=K1 mostra esse quadro.
2. Preencha cada quadro a partir da UI real: pegue cópia, dados e estrutura do código frontend (componentes, strings i18n) ou da composição HyperFrames existente. Redesenhe grande, de acordo com as regras de vídeo: corpo ≥28px, títulos ≥48px, números-chave 80–140px, 3–5 elementos por tela, apenas Geist, paleta Minara (#F2F2F2 palco, #15171A / #222222 / #FFFFFF UI, #B0B0B0 secundária, verde #07B56A para cima/sucesso apenas, vermelho #F75D5F para baixo apenas), sem gradientes, "Illustrative data" no canto inferior direito.
3. Desenhe o texto na tela (花字) no quadro onde ele ficará, para que o operador revise o layout real.
4. Capture:

   ~/.claude/skills/minara-videoscript/scripts/shoot_keyframes.sh \
     docs/keyframes/<tópico>/source.html docs/keyframes/<tópico> landscape K1 K2 K3
   

   A saída é 2560×1440 (portrait: 1440×2560), correspondendo à entrega 2K. O script também passa #k1, então páginas de origem V2 mais antigas (selecionadas por hash) funcionam também.
5. Se a animação já existe e um quadro-chave é um momento dela: busque a composição em vez de redesenhar. Use a página de teste do projeto com ?t=<segundos> ou npm run snapshot -- <t1>,<t2>, depois copie o PNG como K<n>.png.

Rota B — Figma

Quando o design tem o quadro no Figma (novas telas ainda não em código, layouts de campanha).

1. Obtenha fileKey e nodeId do link (node-id=1-2 → 1:2). Carregue a orientação de design-para-código do Figma antes de get_design_context.
2. get_screenshot com maxDimension: 2560, depois baixe a URL com curl em docs/keyframes/<tópico>/K<n>.png.
3. Use get_design_context / get_variable_defs para pegar a cópia exata e os tokens para a tabela de cópia da UI.
4. Se o quadro do Figma for uma tela densa de desktop, é apenas referência: reconstrua-o grande através da Rota A e anote Figma → UI code como a origem.

Rota C — AIGC a partir de capturas de tela

Para quadros que não são UI do produto: uma imagem de abertura, uma metáfora, uma pessoa usando o telefone, um ambiente, um quadro de clima. Nunca para UI do produto ou qualquer coisa com texto real ou números; esses vão pela Rota A ou B.

1. Pergunte primeiro. A geração de imagens gasta créditos (o generate_image do Figma usa créditos do Figma AI; os modelos Weave precisam de um custo cotado e uma aprovação explícita). Diga quais quadros, qual modelo e o custo, depois espere.
2. Dê ao modelo a captura de tela ou um quadro da Rota A como referência, onde a ferramenta aceitar uma; caso contrário, descreva a referência no prompt.
3. Regras do prompt: 16:9 (ou 9:16), a paleta Minara em palavras (palco cinza claro, UI quase preta, branco, verde apenas para sucesso), limpo e minimalista, luz suave do dia, sem gradientes, sem roxo-rosa-laranja, sem texto, letras, números ou logotipos na imagem (os modelos os distorcem; o texto é adicionado em código), sem imagens de meme, sem semelhança com pessoas reais ou outras marcas.
4. Salve como K<n>.png, e escreva o prompt exato, modelo, imagem de referência e data em docs/keyframes/<tópico>/prompts.md para que o quadro possa ser regenerado ou entregue ao colega que faz as tomadas AIGC.
5. Abra o resultado. Rejeite qualquer coisa com texto estranho, mãos erradas, cores erradas ou que pareça arte de IA genérica; regenere ou recorra a um layout da Rota A.

Texto na tela (花字)

Texto na tela é qualquer texto colocado sobre a imagem que não faz parte da própria UI: linhas de legenda, um título, um número-chave, a CTA final.

• Permitido: (1) a linha de narração ou parte dela, como legenda ou ênfase; (2) cópia real da UI extraída e ampliada; (3) um título, número-chave ou CTA que o operador pediu. Nada mais. Sem palavras de anotação, paredes de rótulos, palavras-chave flutuantes ou tags de funcionalidade. Se um conceito precisa de explicação, mostre-o com imagem e movimento.

• As regras de narração se aplicam: calmo, simples, sem palavras proibidas, sem pontos de exclamação, letra maiúscula inicial.

• Escreva cada item como: "Just ask." · 64px / 700 · #15171A · canto superior esquerdo sobre a janela · entrada 12.4s, saída 14.0s · sobe 24px com minaraSnap.

• Estilos para escolher (mantenha um filme consistente):

  Estilo	Uso	Especificação
  Legenda (Caption)	Linha de narração mostrada como texto	40–48px / 500, centro inferior, branco sobre escuro ou #15171A sobre claro, sem caixa
  Título (Headline)	Título ou a única afirmação da cena	64–96px / 700, tracking −0.02em, alinhado à esquerda
  Número-chave (Key number)	Um número que é o ponto da tomada	120–200px / 700, números tabulares; verde/vermelho apenas se for um ganho/perda
  CTA	Cartão final	56–72px / 700 + nome do produto ou URL

• Movimento: entrada com minaraSnap (0.6–0.9s, pequena subida ou escala a partir de 0.96), saída com um fade ≤0.3s. Cada item fica pelo menos o tempo que leva para ser lido em voz alta (0.4s/palavra, mínimo 1.2s).

• Sem emojis, sem preenchimentos gradientes, sem brilho, sem texto contornado ou 3D, sem CAIXA ALTA.

Música (estilo BGM e dicas sonoras)

O documento dá ao minara-music tudo o que precisa, então a música é decidida com o roteiro, não depois.

• Brief em nível de filme (um bloco): andamento (BPM, padrão 120), tom (padrão Lá menor; Dó maior para peças brilhantes), sensação em 1 a 2 linhas simples (Soft electronic, warm pads, light plucked arpeggio, no vocals.), o que evitar (sem drops de EDM, sem hits de trailer, sem chiado lo-fi, sem chops vocais) e uma faixa de referência se o operador forneceu uma. Faixas licenciadas vêm apenas do operador.
• Energia por quadro-chave: um de silent / intro / light / build / full / breakdown / climax / outro (o vocabulário do minara-music), mais algumas palavras de clima. A energia segue a história: o nome do produto ou a afirmação de lançamento recebe climax; um momento de privacidade ou segurança recebe breakdown; o cartão final recebe outro.
• Dicas sonoras: apenas para ações visíveis, cada uma com seu tempo exato: tap 35.0s, typing 32.1–34.6s (cps 18), success 45.0s, notify 45.2s, whoosh 47.3s, thud 43.2s, bell 0.4s. Os tipos são a lista de sfx do minara-music.
• A narração abafa a música; diga duck under VO no brief quando houver narração.

Modelo de documento de roteiro

# Script | <Tópico>: <resumo de uma linha>            ← filme completo: "Script | <Nome do filme>"

> O roteiro atual único para <cena N / o filme completo>.
> Propósito: <substitui a cena N, XX–XXs / novo filme>. O corte existente permanece inalterado até que isso seja aprovado.
> Fontes: <caminho do código frontend / link do Figma / caminhos das capturas de tela / documento do produto>. Itens marcados com ⚠️ não estão na fonte e precisam de confirmação do produto.
> **Apresentação (travada)**: <caso; superfície; fuso horário; o que não é mostrado; se há uma etapa de pergunta de acompanhamento>.
> **Saída**: <2560×1440 ou 1440×2560>, 60fps. Quadros-chave: `docs/keyframes/<tópico>/` (fonte: `source.html`, prompts AIGC: `prompts.md`).

## 1. O que isso deve transmitir
1. <a primeira coisa que um espectador deve lembrar>
2. … (máx. 4; cada um mapeia para pelo menos um quadro-chave)

## 2. Fluxo do usuário e cópia da UI
| Etapa | Ação do usuário | Cópia da UI (exata) | Fonte |
(Fonte = caminho do código / nó Figma / captura de tela; prompts de demonstração são marcados como "(demo)")

## 3. Folha de quadros-chave (<total>s<, substitui XX–XXs>)
| Quadro | Tempo | Dur | Cena | Imagem (resumido) | Narração | Texto na tela | Música | Fonte da imagem |
|---|---|---|---|---|---|---|---|---|
| K1 | 0.0–2.4s | 2.4s | S1 | Avatar aterra no centro | — | — | intro · bell 0.4s | UI code |
(Uma linha por quadro-chave; intervalos contíguos e somando o total. Esta é a tabela que as habilidades downstream leem.)

## 4. Cenas e quadros-chave
### <ID da cena> | <s