talking-clip

O que talking-clip faz?

Um clipe tem quatro etapas: escrever a fala, gerar a voz, planejar a atuação, construir e renderizar. Saída: um projeto HyperFrames e um mp4 (vertical 1080x1920 por padrão).

1. linha    você escreve, na voz do personagem
2. voz      scripts/tts.py          (ElevenLabs consome créditos; say e none são gratuitos)
3. plano    você escreve plan.json     (gestos e expressões nas palavras)
4. vídeo    scripts/build_clip.py -> scripts/verify.py -> scripts/render.py

Os caminhos são relativos à raiz deste pacote: a pasta que contém .claude-plugin/, dois níveis acima deste arquivo (resolva os links simbólicos primeiro). Requer as habilidades públicas do HyperFrames (hyperframes, hyperframes-cli): leia hyperframes uma vez antes de editar qualquer composição manualmente.

0. Pré-voo (sempre primeiro)

Execute python3 scripts/setup.py doctor (adicione --json para analisar). Ele lista cada dependência, para que serve e o comando de instalação exato para esta máquina; ele sai com código 1 quando um item obrigatório está faltando.

• Obrigatório ausente (ffmpeg, Node.js 18+, as habilidades HyperFrames e a chave ElevenLabs ou say quando essa voz está configurada): informe ao usuário em uma linha para que cada um serve e proponha o comando impresso. Execute-o apenas após o usuário confirmar. Nunca digite ou peça uma chave de API: diga ao usuário para exportar ELEVENLABS_API_KEY no shell dele.
• Opcional ausente: ofereça uma vez e diga o que cada um desbloqueia. Playwright permite capturas web com caixas de zoom de elementos e capturas de página inteira, tesseract (OCR) fornece a verificação de segredos em capturas de tela, e ASR (mlx-whisper / openai-whisper) fornece a verificação de áudio e timings exatos de palavras. Pule-os se o usuário recusar; as verificações correspondentes se tornam etapas manuais de review.
• Habilidades HyperFrames (hyperframes, hyperframes-cli, hyperframes-registry, media-use): se ausentes, recomende npx hyperframes skills. Leia hyperframes (e hyperframes-cli para problemas de renderização) antes de construir ou editar qualquer composição.

Configuração (primeira execução ou quando o usuário quiser alterar algo)

Procure por uma configuração: python3 scripts/setup.py show. Se não houver nenhuma, ou o usuário pedir para alterar seu personagem, voz, renderização ou estilos, entreviste-o (uma pergunta curta de cada vez, ofereça o padrão) e depois escreva com flags:

Pergunta	Flag	Opções
Quais partes?	--features	character, explainer ou ambos
Qual personagem?	--character	o exemplo incluído (pkg:characters/host/character.json) ou um caminho para o deles (armazenado absoluto)
Idioma da narração	--language	código ISO; com say uma voz clara é selecionada (setup.py voices --lang <code> lista-as, --say-voice substitui)
Qual voz?	--voice	elevenlabs (a chave deles em ELEVENLABS_API_KEY, o --voice-id deles), say (macOS, gratuito), none
Proteções de crédito (ElevenLabs)	--max-chars, --max-seconds, --daily-credit-cap	números que eles escolherem; vazio = sem proteção
Como renderizar?	--render	local (gratuito, nesta máquina), cloud (nuvem HyperFrames, precisa de npx hyperframes auth login), preview (Studio apenas)
Tamanho	--size	1080x1920, 1920x1080, 1080x1080

python3 scripts/setup.py init --features character --voice say --render local --yes

init executa o doctor primeiro e oferece as mesmas instalações. Se uma configuração já existir, ele pergunta antes de sobrescrever, ou precisa de --force quando não interativo.

Personagem próprio: python3 scripts/setup.py new-character --name "<nome>" --out ./characters/<nome> --activate copia o exemplo e o ativa (sem segundo init). Em seguida, ajude a preencher as chaves que ele imprime: description, personality, speaking_style.rules, rig.colors (ou sprites), expressions / poses / gestures, set, voice_moods.

Nunca peça, imprima ou escreva a chave da API. Se ELEVENLABS_API_KEY estiver faltando, diga ao usuário para exportá-la no shell dele. O esquema de configuração está em config/config.schema.json; o formato do arquivo de personagem está no README ("Your own character").

Escolha um estilo para este clipe

Não há um visual padrão. Para cada clipe, escolha o estilo baseado no tópico, no público e na marca ou gosto do usuário: o cenário ({"type": "color"|"gradient"|"image", ...}), o enquadramento (close, medium, wide) e a intensidade de movimento (calm, normal, lively). Pergunte ao usuário quando a escolha for importante, por exemplo, quando o clipe for para uma marca, um canal público ou uma série. Varie o estilo entre os clipes em vez de repetir o último. Se a configuração tiver um kit de brand, seu background prevalece sobre sua escolha. Escreva em um arquivo e passe --style:

{"set": {"type": "gradient", "colors": ["#FFF4E6", "#FFD9B3"]}, "framing": "medium", "motion": "lively"}

O mesmo vale para as palavras: combine o tom com o público dentro da personalidade do personagem e não reutilize a mesma frase de abertura ou encerramento de um clipe para o outro.

1. Escrever a fala

Leia o arquivo de personagem nomeado na configuração (chave character): personality e speaking_style.rules são a voz. Siga-os; o pedido do usuário prevalece onde houver conflito.

• Duração: no máximo styles.talking_clip.max_seconds. A speaking_style.chars_per_second (cerca de 14) um clipe de 20 s tem menos de ~260 caracteres. Uma ideia, uma frase de encerramento.
• Idioma: o do usuário, a menos que ele peça o contrário.
• Modelos ElevenLabs com tags de áudio (v3 e posteriores) aceitam tags de emoção em inglês dentro de colchetes antes das palavras que colorem: [excited], [calm], [whispers], [laughs], [pause]. say e none as ignoram (são removidas); atue com gestos.

2. Gerar a voz

python3 scripts/tts.py estimate --text "<linha>" --max-seconds 20
python3 scripts/tts.py speak --text "<linha>" --out out/voice.wav [--mood excited] [--confirm]

• ElevenLabs: sempre execute estimate primeiro e informe ao usuário o custo; speak recusa sem --confirm, e recusa quando uma proteção definida pelo usuário (max chars, max seconds, daily credit cap) seria quebrada. --takes 2 cria alternativas. Os timings das palavras vão para out/voice.wav.words.json.
• --mood escolhe um humor dos voice_moods do personagem (configurações ElevenLabs + filtro ffmpeg opcional).
• say / none: gratuito. Com none não há áudio; passe --text para o construtor.

3. Planejar a atuação

python3 scripts/timings.py out/voice.wav --text "<linha>" fornece os tempos de início das palavras. Escreva plan.json:

{"expression": "neutral",
 "events": [{"t": 0.0, "gesture": "hello"},
            {"t": 2.1, "gesture": "explain", "dur": 2.5},
            {"t": 5.0, "expression": "happy"},
            {"t": 6.2, "gesture": "wink"}]}

• Os ids de gesture e expression vêm do arquivo de personagem (gestures, expressions); cada gesto tem uma descrição e uma dur típica. Leia-os antes de planejar.
• Boca, piscadas, respiração e balanço ocioso são automáticos. Você apenas coloca os beats de atuação.
• Coloque um gesto forte 0,2-0,3 s antes da palavra que o acompanha. Uma reação por beat; nunca dois gestos no mesmo segundo. Termine com um gesto calmo e sustentado (ele é mantido automaticamente até o fim).

4. Construir, verificar, renderizar

python3 scripts/build_clip.py --audio out/voice.wav --plan out/plan.json --style out/style.json --project out/clip
python3 scripts/render.py out/clip --out out/clip.mp4 --quality draft
python3 scripts/verify.py all --project out/clip --text "<linha>" --video out/clip.mp4

A verificação é obrigatória (detalhes na seção "Verificar" da habilidade explainer, mesmo loop): build deve estar limpo, render fornece uma folha de contato que você deve examinar (boca se movendo, gestos onde planejados, nada cortado), audio verifica as palavras com ASR e o limite de duração. Corrija e execute novamente a partir da etapa que falhou. Cada execução de verify.py all é uma iteração; em verify.max_iterations ele sai com código 2 e você informa ao usuário o que ainda falha em vez de enviar. render permanece review até você olhar a folha de contato e registrá-la com verify.py mark render pass|fail --project out/clip --note "...", depois execute verify.py all novamente (uma reconstrução invalida a marcação).

Em seguida, renderize o final com o backend configurado: python3 scripts/render.py out/clip --out out/clip.mp4 (render.max_mb recodifica para caber em um limite de upload). Nunca faça commit de arquivos mp4 ou wav.