j-guide-video (Guia de Vídeo Ilustrado)

Vídeo Guia Ilustrado (Layout Guia)

1 passo do manual = 1 cena. Cada frase da narração aciona uma ação: pegar uma ferramenta, despejar, abrir, tocar, montar. A renderização, o áudio e a exportação são feitos inteiramente em Swift (CoreGraphics e AVFoundation). O CLI jgv gerencia roteiro, áudio, legendas, imagens estáticas e vídeo.

• <skill> é o diretório deste SKILL.md (${CLAUDE_SKILL_DIR}. Se não estiver disponível, usa ${CLAUDE_PLUGIN_ROOT}/.claude/skills/j-guide-video quando instalado via plugin, senão ~/.claude/skills/j-guide-video ou .claude/skills/j-guide-video, o que existir)
• Nos comandos abaixo, jgv refere-se a <skill>/bin/jgv. Na primeira execução e após cada atualização da skill, o jgv e o kit (DSL de desenho e componentes) são compilados em Swift, o que leva de dezenas de segundos a alguns minutos. A compilação fica em cache (~/Library/Caches/j-guide-video/). Projetos de vídeo contêm apenas os arquivos específicos (roteiro, bindings, cues, SVG de assets); o mecanismo está descrito em reference/environment.md. Se o usuário pedir para limpar o cache, execute jgv clean --stale --dry-run para mostrar o que será removido e depois jgv clean --stale; para limpar tudo, use rm -rf ~/Library/Caches/j-guide-video (a pasta será recriada na próxima compilação). Se a variável J_GUIDE_VIDEO_CACHE estiver definida, não remova a pasta inteira, apenas os subdiretórios build-*, shared-*, projects e avtts
• Argumentos e opções são exibidos com jgv help <subcomando>. Opções desconhecidas geram erro
• <library> é a biblioteca do usuário (variável J_GUIDE_VIDEO_LIBRARY, ou ~/.config/j-guide-video se não definida; se XDG_CONFIG_HOME existir, fica abaixo dela). Ferramentas e movimentos criados em vídeos anteriores (em parts/) e preferências (defaults.json) permanecem aqui, mesmo após atualizações da skill (reference/library.md)

procedure.md ─(jgv new = init・md2script --stubs・tts・timing)→ script.json・esboços de cues e bindings・áudio・timeline・legendas・tabela de tempos
visuals/bind.swift (nomes e desenhos de ferramentas/telas) + cues/<Etapa>.cue (movimentos por frase) ─(jgv check → jgv dev → jgv render → jgv overview)→ out/video.mp4

O que verificar antes de começar

Ambiente de execução

• Exclusivo para Claude Code no macOS (versão que suporta o Xcode mais recente; testado apenas em Apple Silicon, Intel Mac não verificado). Informe que não funciona em Linux, Windows (incluindo WSL2), Claude Code na web ou Claude.ai, e pare.
• Requer Xcode ou Command Line Tools mais recentes (swift, xcode-select --install; versões antigas não foram testadas). O jgv para se estiver faltando ou desatualizado; informe o método de instalação ao usuário (não execute comandos com sudo automaticamente). Apenas a primeira compilação do jgv requer rede.
• A narração padrão usa as vozes do macOS ("voice": "auto" seleciona a melhor qualidade para o idioma do roteiro. Lista: jgv voices)
• TTS para uso comercial: TTS em nuvem integrado ou command (qualquer comando externo). TTS em nuvem funciona apenas configurando chaves de ambiente: google (GOOGLE_TTS_API_KEY; para chave de conta de serviço: GOOGLE_APPLICATION_CREDENTIALS), azure (AZURE_SPEECH_KEY e AZURE_SPEECH_REGION), amazon (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION), openai (OPENAI_API_KEY; modelo previsto para encerrar em 2027-01-06, não recomendado para vídeos de longo prazo)
• Chaves e scripts são responsabilidade do usuário. O Claude não deve digitar ou exibir chaves de API, nem abrir arquivos de chave de conta de serviço (GOOGLE_APPLICATION_CREDENTIALS), e nunca chamar APIs pagas sem autorização.
• Ao lidar com projetos de vídeo que não foram criados pelo usuário (zip, repositórios de terceiros, roteiros de terceiros passados com --base), antes de executar jgv, mostre ao usuário e verifique em script.json e script.<idioma>.json (todos os roteiros passados para jgv tts etc.) o valor de tts (se engine é um TTS em nuvem pago ou o que está em command), e se os arquivos Swift em visuals/, parts/, kit/ existem. Os comandos jgv tts / timing / dev / check / snapshots / still / preview / catalog / render / build-langs (todos os que geram áudio ou compilam e desenham visuais) executam esses comandos e códigos diretamente.
• TTS em nuvem pago só é chamado após uma autorização explícita com jgv tts --allow-cloud para cada projeto e engine (o jgv tts exibe o número de linhas e caracteres e para). Adicione --allow-cloud somente após informar o usuário sobre o engine e os custos e obter seu consentimento. (jgv new --tts … e roteiros criados com jgv new usando o engine definido em defaults.json da biblioteca são autorizados automaticamente. Ao usar jgv new --base para herdar o engine em nuvem de um roteiro de terceiros, o jgv new para antes de criar qualquer coisa e pede que você escolha com --tts)
• Voz, velocidade, configurações de cada TTS, disco e mecanismo de cache estão em reference/environment.md

Condições de uso dos vídeos gerados

• Vozes do macOS (padrão apple): De acordo com a licença de uso do macOS da Apple (seção "Voices"), as vozes do sistema só podem ser usadas para criar obras originais para uso pessoal e não comercial. Os vídeos exportados são limitados a uso pessoal e não comercial, não podendo ser publicados em redes sociais/sites de vídeo, nem usados para trabalho ou em empresas (incluindo manuais internos, conforme interpretação). (Resumo; o texto original está na licença do macOS, seção "Voices")
• google / azure / amazon / openai / command: Sujeito aos termos de uso do respectivo TTS. Se o TTS permitir uso comercial, os vídeos podem ser publicados e usados profissionalmente. Se o TTS exigir créditos ou indicação de voz sintética, escreva em credit no script.json.
• Se a solicitação parecer voltada para publicação em redes sociais/sites de vídeo ou uso profissional/empresarial, antes de iniciar o trabalho, informe o usuário e mencione que é possível alternar para um TTS com licença comercial. Não tome decisões legais; oriente o usuário a verificar a licença da Apple e os termos do TTS escolhido.

0. Escolher o layout

Com base no tema, decida o layout e informe o usuário em uma frase (pergunte apenas se houver dúvida). O local onde o projeto será criado (o <dir> da etapa 2) também deve ser informado aqui.

Layout	--layout	Aparência	Temas adequados	Exemplos em examples/
Sala	guide (padrão)	Mesma pessoa em pé em uma sala, usando ferramentas. Detalhes da mão em cartão ampliado	Bebidas, tarefas domésticas, cuidados com eletrodomésticos — "pessoa usando ferramentas"	room-microwave-rice, room-mug-wash
Operação de tela	guide-screen	Sem pessoa. Tela de smartphone/navegador com toques, cliques e entradas. Nota pontual à direita; áreas não focadas escurecidas	Procedimentos de apps e serviços web	screen-alarm (smartphone)
Visão superior	guide-topdown	Bancada vista de cima com duas mãos vindo da borda inferior da tela	Culinária, artesanato, embalagem — ações com as mãos como foco	topdown-cucumber
Manual de montagem	guide-manual	Papel milimetrado branco com desenho isométrico, setas tracejadas, apertos de parafuso, lista de peças	Montagem de móveis, instalação de equipamentos, troca de peças	manual-smallbox
Vertical	Qualquer um acima + --vertical	1080×1920. No layout sala, a pessoa fica em cima e o cartão ampliado aparece sempre abaixo do balcão (verificado apenas para layout sala)	Dicas curtas de vida, receitas para visualização vertical no celular	vertical-coffee

Mesmo que sejam necessárias versões em vários idiomas, primeiro conclua em um idioma e depois adicione as demais na etapa "6. Criar versões em outros idiomas".

1. Preparar o manual

Organize o texto do usuário no seguinte formato Markdown e salve como <dir>/procedure.md (se já estiver neste formato, use-o diretamente).

# How to Brew Drip Bag Coffee
## Get ready [prepare]
Prepare a mug, a drip coffee bag and a kettle. Boil the water and let it cool to about ninety degrees Celsius.
## Open the bag [open]
Hold the bag with both hands, tear off the top strip along the marked line. Open it gently to avoid spilling the coffee.

• # Título, ## Nome da etapa [tag], o texto é lido como está. A tag é opcional e se torna o nome visual (open → Open). Apenas caracteres alfanuméricos, - e _ começando com letra; caso contrário, é ignorado e vira Step01 etc.
• Listas com marcadores ou numeradas: cada item = uma frase. Ênfase, links, código inline são ignorados na leitura (tags HTML, comentários e blocos de código não são lidos). Nomes de teclas como <Enter>, <URL> e colchetes angulares para substituição são mantidos. Em japonês e chinês, quebras de linha também são quebras de frase (linhas terminadas em vírgula se conectam à próxima); em inglês etc., linhas em branco separam parágrafos. Se faltar pontuação no final da frase, adicione. Tabelas (linhas com | … |) e blocos de código não são lidos (um aviso é emitido se uma tabela for omitida).
• Etapas: 4 a 8, cada uma com 1 a 3 frases. 1 frase = 1 segmento de animação; vírgulas (, 、) = segmentos ainda mais finos. Portanto, escreva frases onde "o quê → como" se divide em orações (ex.: "Spread the paper hooks, attach them to the rim of your mug.")
• Tempos de espera reais (descanso, secagem etc.) devem ser encurtados no vídeo.
• Se o texto do usuário for livre (notas, instruções), reescreva como manual seguindo os critérios em reference/rewriting.md.

2. Criar o projeto e converter em roteiro

jgv new <dir> --kicker "DAILY RITUAL / COFFEE GUIDE" --layout guide

jgv new faz tudo em uma vez: cria o projeto (jgv init), gera esboços de roteiro e cues (jgv md2script procedure.md -o script.json --stubs visuals), gera áudio e timeline (jgv tts), e exibe a tabela de tempos das cues (jgv timing; mostra linha.frase por etapa e segundos desde o início da etapa). O manual usado é <dir>/procedure.md; se estiver em outro local, passe-o com jgv new <dir> <caminho_do_manual> para copiá-lo. As opções são as mesmas de jgv md2script. Execute os comandos seguintes dentro de <dir> (cd <dir>).

• <dir>: se o usuário especificou um local, use-o. Se não, não pergunte e crie fora do diretório da skill e do repositório (ex.: ~/Movies/jgv/<tema>). Em ambos os casos, informe o caminho completo antes de criar (na etapa 0, ao informar o layout) (ex.: "Vou criar em ~/Movies/jgv/shoulder-massage. Se preferir outro local, avise."). Criar no diretório atual pode deixar artefatos out/ e .jgv/ dentro do repositório.
• --layout é o tipo escolhido na etapa 0. Para vertical, adicione --vertical. --kicker é o nome da série no canto superior esquerdo.
• Aparência da pessoa (--presenter), relação com defaults.json da biblioteca, TTS em nuvem (--tts), suprimir texto (--no-text etc.), projetos em formato antigo (jgv migrate) em reference/options.md - “Opções do jgv new”. Se defaults.json já tiver kicker/layout, só adicione --kicker/--layout se o usuário os especificar ou se o layout escolhido na etapa 0 for diferente.
• Se jgv new parar com erro, ele mesmo remove o que criou e restaura o estado anterior (arquivos já existentes permanecem). Corrija a causa e repita o mesmo jgv new (se interrompido, veja solução de problemas em reference/tips.md)

O que é gerado (já funcional do início ao fim): script.json, cues/<Visual>.cue para cada etapa (com números linha.frase e anotações no cabeçalho), visuals/<Visual>.swift (uma linha chamando a cue — não mexa), visuals/bind.swift (esboço de binding), .jgv/timeline.json, out/subtitles.srt.

Ajustar a leitura em japonês

• Em japonês, ajuste speak em cada linha de script.json para facilitar a leitura de números, letras e palavras difíceis. Escreva as correções em katakana (hiragana pode se conectar com o contexto e causar erros de segmentação ex.: "食欲やはいせつぶつ" → "や／は／いせつ…". ハイセツブツ evita o erro.)
• Use jgv yomi para ver a leitura de cada palavra e avisos; corrija leituras indesejadas. jgv yomi usa a análise do macOS independentemente do engine, portanto sirva como referência para TTS em nuvem (corrigir para katakana funciona em qualquer engine). (Tipos de aviso e correção em reference/tips.md - “Leitura em japonês”)
• Após corrigir speak, execute jgv tts (reler apenas as linhas corrigidas) → jgv timing (atualizar tabela de tempos)
• Se o usuário apontar uma leitura incorreta, após corrigir, pergunte na etapa 7 se deseja adicionar a correção em readings no defaults.json da biblioteca.

3. Definir ferramentas e telas (binding)

Defina os objetos (ferramentas, dispositivos, telas) exibidos em cada etapa, seu posicionamento e onde as mãos tocam. Escreva como binding em visuals/bind.swift (o esboço é criado por jgv new). Um único binding para todas as etapas. Consulte reference/cue.md - “binding” para a sintaxe.

• Antes de escrever, leia um exemplo completo do mesmo layout (escolha na lista em examples/README.md e leia visuals/bind.swift e cues/*.cue. Copie movimentos e posicionamentos semelhantes de lá)
• Ferramentas: priorize peças do kit e parts/ do projeto (peças da biblioteca). Veja a aparência em reference/props-catalog.png, lista em reference/visual-kit.md - “Ferramentas”. Argumentos e pontos de pegada (ex.: KETTLE_PARTS) são encontrados com jgv api やかん (busca por nome, nome em japonês ou descrição; jgv api sozinho lista todos os nomes; também lista parts/ do projeto). Não faça grep no código-fonte do kit.
• Ferramentas inexistentes: desenhe em visuals/props.swift seguindo as regras de reference/prop-style.md e verifique com jgv preview (usando PROPS_PREVIEW). Se o usuário tiver SVGs, coloque em assets/ e desenhe com Svg("nome") (visual-kit.md - “Materiais SVG (assets)”)
• Posição fixa e escala das ferramentas: use constantes com nome (ex.: let MW = Pt(1080, GUIDE.counterY). Para vertical: LAYOUT_PORTRAIT.counterY). Assim, ajustes futuros são feitos em um só lugar.
• Ferramentas e dispositivos que a pessoa toca com as mãos devem estar próximos à pessoa (em layout horizontal, até cerca de x 1150). (jgv check avisa se a mão estiver muito longe)
• Etapas como "Materiais necessários", "Avisos", "Antes/Depois", "Resumo" podem usar tipos de cena do kit (PrepareItems, NoteCards, BeforeAfter, SummaryList) na sintaxe do binding.
• Pontos-chave de aparência por tipo de layout em reference/implementation.md - “Pontos por tipo de layout”

4. Escrever os movimentos das etapas com cues

Para cada etapa, escreva cues/<Visual>.cue. Os números de tempo linha.frase vêm do cabeçalho do esboço (ex.: # 0.0 冷凍ごはんを、 0.1 ラップのまま、…) e da tabela de tempos de jgv new / jgv timing. A sintaxe está em reference/cue.md. Copie movimentos semelhantes dos exemplos do mesmo tipo de layout (em examples/). As cues têm de algumas a dezenas de linhas, portanto escreva todas as etapas sequencialmente no fluxo principal, sem usar subagentes para etapas individuais.

init <Load
0.0+.3 H>mw.handle~.45
0.0+.35 mw.open=0~.6
0.2+.45 P mw.start;mw.on=1~.2;mw.disp=cd 2:00 0:[email protected];timer timer 2分@1.0
1.1+.7 H>dish.gripL~.4;dish.in=0
1.1+.77 dish@PLATE~.5;steam dish.top

• Para cada frase, escreva uma linha com "o quê → como" (movimento no instante em que a frase é lida). Tempos de espera: timer de arco (timer) com anotação “O tempo de espera foi encurtado”.
• Mão (H> C> P): instante em que a mão chega. Outros: instante em que o movimento começa. Ao sincronizar valores com movimentos das mãos, ajuste o instante do valor para antes, pelo tempo de duração do movimento da mão.
• A partir da segunda etapa, comece com init <etapa_anterior (herda o estado final). Se um cartão ampliado deve permanecer aberto entre etapas, coloque card.exit=0 na etapa anterior e card.enter=0 na seguinte.
• Detalhes finos das mãos (abrir, escavar, esfregar, torcer) são mostrados no cartão ampliado (card · C>). A pessoa aponta à esquerda do cartão (H>gesture). A última etapa mostra o produto final + verificação (check) + vapor/brilho como encerramento.
• Evite telas paradas: durante a narração, mantenha algo em movimento (vapor, ondulação (wave), ondulações na água etc.).

cd <dir> && jgv check

Corrija cues e binding até que não haja mais linhas com ! (nome incorreto, mão muito longe, soltar objeto enquanto ainda o move, movimento após 0,5s do fim, sobreposição de texto ou moldura etc.). Linhas H / C exibem uma tabela de tempos das mãos (de quantos segundos a quantos segundos, de onde para onde). Linhas S1→S2 mostram valores diferentes nas fronteiras entre etapas (apenas os intencionalmente alterados devem aparecer). Se apenas cues foram corrigidas, não há recompilação, então a verificação é rápida. Leitura das linhas e correção em cue.md - “jgv check”.

Movimentos especiais que não podem ser escritos em cues podem ser implementados em Swift na parte de desenho do binding, controlados por valores nas cues (cue.md - “Quando escrever em Swift”). Também é possível usar o fluxo anterior (storyboard → implementação paralela por subagentes) para escrever a etapa inteira como um visual em Swift (reference/implementation.md).

5. Verificação geral → exportação

cd <dir> && jgv dev

jgv dev faz a verificação completa em um único comando: jgv tts (reler apenas linhas alteradas) → compilação → jgv check (se houver !, para aqui) → jgv snapshots apenas das etapas alteradas desde a última execução de jgv dev.

• Erros de compilação do binding aparecem com nome do arquivo e número da linha (ex.: visuals/bind.swift:12:5: error: …)
• A última linha, Imagens para verificar:, lista os arquivos a serem lidos. Na primeira execução, ou quando arquivos Swift, assets/, cores etc. forem alterados, ou quando todas as etapas mudarem: out/snapshots/sheet.png completo. Se apenas cues foram alteradas: out/snapshots/scene-N/sheet.png das etapas modificadas (incluindo aquelas que herdam estado com init <etapa_anterior). Alterar o roteiro geralmente muda a duração do vídeo e a barra de progresso, então normalmente gera o completo. Para refazer tudo: jgv dev --all
• Sempre abra e verifique a lista de Imagens para verificar: com o comando Read. Corrija e execute jgv dev novamente (cuidado: se apenas algumas etapas foram refeitas, o out/snapshots/sheet.png completo anterior ainda existe e pode ser confundido). Para verificar deslocamentos das mãos, use a tabela de tempos de mãos de jgv check, que é mais rápida que imagens.
• Para detalhes pequenos (linhas tracejadas, texto de anotações, posição da mão no cabo), leia as imagens quadro a quadro no mesmo diretório (metade do tamanho do vídeo; o nome do arquivo é o número da linha exibido na exportação, ex.: 03.png. Para capturar por frase: jgv snapshots --scene=N --phrases gera 02-04.png; jgv dev não tem --phrases)

O que verificar nas imagens:

• A mão está segurando o cabo da ferramenta? A ferramenta está flutuando ou sobreposta?
• O conteúdo da frase corresponde à ação na tela? (ex.: na linha "tear off", a tira está sendo rasgada?)
• O rótulo da subetapa e as anotações no cartão ampliado são legíveis? Sobreposições de texto, anotações, molduras e vazamentos para fora da tela são indicados por jgv check com linhas ! seg-segs:, então nas imagens verifique sobreposições de objetos, objetos desenhados duas vezes e se o desenho do binding não está sobreposto ao título ou à barra de legendas (isso não aparece no check). Se --no-text / --no-notes, verifique se o texto explicativo não está aparecendo.

Se não houver problemas, exporte e crie a página de visão geral:

cd <dir> && jgv render && jgv overview

out/overview.html é uma página que lista a narração, arquivos visuais, imagens estáticas e materiais SVG de cada etapa (abra no navegador). Informe os locais de out/video.mp4, out/subtitles.srt e out/overview.html; se possível, envie o vídeo. Em seguida, vá para a etapa "7. Salvar na biblioteca".

Ajustes de cores, voz, tratamento de erros e exemplos práticos em Swift (demo/ do repositório) estão em reference/tips.md.

6. Criar versões em outros idiomas

Primeiro conclua o vídeo em um idioma. Depois, siga o procedimento em reference/multilang.md para adicionar script.<idioma>.json e exporte todos de uma vez com jgv build-langs (o vídeo é o mesmo; apenas o roteiro e os textos na tela são substituídos).

7. Salvar na biblioteca

Após a exportação, liste para o usuário os itens criados que possam ser reutilizados em outros temas: ferramentas e movimentos (visuals/props.swift, shared.swift, desenhos de ferramentas no binding), configurações escolhidas como preferência (cores, voz, velocidade etc.; exclua o kicker específico do tema), e leituras corrigidas (readings) apontadas pelo usuário. Pergunte se deseja salvá-los na biblioteca (se não houver itens ou se todos já estiverem na biblioteca, não pergunte). Para salvar, siga o procedimento em reference/library.md - “Salvar após concluir o vídeo”, colocando em <library>/parts/ e <library>/defaults.json. No próximo vídeo, isso economiza o trabalho de desenhar e configurar novamente.