Camadas Visuais (Storyboard)
Isto é uma tarefa, não uma etapa do fluxo. Execute quando o usuário solicitar; pode voltar depois de alterar a edição.
Os únicos pré-requisitos são: livro-razão e legendas já existentes (as camadas são posicionadas conforme as legendas, o tempo é calculado a partir do livro-razão).
Requer edit-list.json, transcript.json, subtitles.json
Gera visuals.json + modules/<sequencial-nome>/index.html
Após concluir, pare. Não oriente o usuário para o próximo passo.
Primeiro, leia e execute o Contrato de Fase do Skill de Negócio. As regras rígidas para escrita de módulos estão no Contrato de Módulo Visual, as regras de decisão estão em Julgamento Visual.
0. Pronto
Execute primeiro a "Verificação de Prontidão" do Skill de Verificação de Atualizações: se os skills estão
atualizados e o Runtime é compatível; a raiz do plugin também é localizada lá (substitua <raiz-do-plugin> nos comandos abaixo pelo caminho literal).
Só prossiga se o resultado for "Pronto"; se for "Nova Sessão Necessária" ou "Parar", siga as instruções (incluindo a proibição de "interfaces substitutas caseiras"). O Skill de Negócio não contém lógica de ambiente.
Se o resultado de prontidão for runtime.kind=desktop-managed, reutilize diretamente a CLI estável já instalada no aplicativo desktop e o mesmo serviço launchd/windows-task; não analise caminhos do Electron, instale dependências adicionais ou inicie um segundo Runtime.
Comandos
node "<raiz-do-plugin>/scripts/ensure-running.cjs" --json
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" visual get <projeto> --json
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" visual frame <projeto> --cues sub-0004,sub-0005 --count 12 --out <dir> --json
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" visual add <projeto> --module modules/01-xx/index.html --cues sub-0004,sub-0005 [--zoom x,y,w,h] [--id vis-0001] --json
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" visual remove <projeto> --id vis-0001 --json
ensure-running deve primeiro provar que a porta canônica 5190 pertence ao serviço gerenciado da plataforma atual; se falhar, propague e pare, não reverta para foreground ou porta alternativa.
As camadas são vinculadas à tela de legendas (--cues), o produto converte automaticamente para IDs de palavras — a camada nunca pode ser vinculada a palavras que ninguém disse; se a edição mudar, a camada se ajusta sozinha. Não armazene segundos.
Quatro Etapas, Sem Pular
① Texto define a tarefa Leia subtitles.json, segmente por semântica, responda para cada segmento:
Tutorial/Demonstração/Prova, ou Conceito/Lógica/Transição?
② Extraia quadros para ver a tela visual frame extrai 8-12 quadros, veja com os olhos.
Na prática, 2 de 12 segmentos tiveram a previsão textual refutada pela imagem — este passo não é formalidade
③ Meça a janela de movimento Faça diferença de pixels entre quadros adjacentes, encontre momentos de scroll/mudança/operação.
Camadas só cobrem janelas estáveis; o destaque sai antes de o movimento começar
④ Crie e posicione a camada Escreva módulo → visual add → verifique cada camada na pré-visualização
Regras de Decisão para a Etapa ②
A imagem mostra exatamente o que ele está falando → Destaque: circule, destaque cada palavra mencionada. Evidência real não deve ser coberta
Imagem com fraca relação / em branco → Animação preta: tela cheia branca, use o registro de estilo
Imagem por si só já é clara suficiente → Não faça nada. Esta é a resposta correta mais comum (na prática, 4 de 13 segmentos não precisaram de alteração)
O resultado da Etapa ③ são números, não sensações
Coordenadas do destaque Calcule por estatística de pixel (varredura em escala de cinza para encontrar linhas de texto), não é permitido estimar visualmente — erros visuais já chegaram a 50px
Momento de interação Diferença de pixel quadro a quadro para encontrar mudanças bruscas (na prática, um salto de 4 para 335), o destaque deve desaparecer 0,2s antes
Janela estável No início geralmente há scroll (ele está procurando conteúdo), a camada começa a vincular a partir do quadro em que a tela estabiliza
Zoom (zoom) — Pense Antes de Usar
Padrão: sem zoom. Gravação de tela 960x720 fica borrada ao ampliar, o usuário perceberá imediatamente.
Quando for indispensável ≤1,6x, a área deve ser 62,5% quadrada centralizada — composição completa > ler letras pequenas.
Letras muito pequenas para ler Use destaque para guiar o olhar; se for realmente necessário ler, a resposta é regravar em alta resolução, não ampliar.
Ciclo de Revisão
O diretório de módulos usa numeração sequencial (01-relatorio-diario, 05-anim-divisao-tarefa),
a trilha da timeline exibe o nome do diretório; o usuário informa o número e você altera aquela camada, sem mexer nas outras.
Duas regras de ouro para alterar camadas, cada uma referente a um incidente real:
Ao alterar camada, verifique o módulo Após estreitar/alongar a camada, os momentos relativos fixos no módulo não mudam —
o momento de saída do destaque pode cair após o fim da camada e nunca aparecer
Ao validar, olhe os pixels Capture a tela para ver a imagem, não verifique atributos do DOM. Um iframe com "visibilidade invertida correta"
já ficou fisicamente fora da tela — atributos todos corretos, tela toda vazia
O que NÃO Fazer
- Não pule as etapas de extração de quadros e janela de movimento (cada erro já aconteceu uma vez: cobriu evidência real, destaque flutuou sobre scroll)
- Não faça algo em todo segmento — preencher tudo não é o objetivo, não fazer nada é uma resposta comum
- Não armazene segundos, não estime coordenadas visualmente, não coloque vinheta preta em página branca
- Sem conteúdo real, não use placeholder como substituto
- O estilo deve ser selecionado do registro, não invente
- Ícones de marca usem glifos oficiais, não desenhe substitutos à mão (X já foi desenhado com duas linhas cruzadas e o usuário percebeu). Se o índice local não tiver, obtenha o glifo oficial monocromático do simple-icons (o estilo preto e branco combina bem), salve o SVG original no diretório do módulo para referência; na mesma peça, a mesma marca deve ter sempre a mesma aparência.