WakaChobii/tiktok-text

Adicionar texto no estilo TikTok a um vídeo

Os arquivos desta skill estão em ${CLAUDE_PLUGIN_ROOT}/skills/add-text/:

• scripts/add_text.py: use este. Ele executa todo o trabalho em dois comandos.
• scripts/caption_match.py (detectar / ajustar / verificar) e scripts/tiktok_text.py (desenha + grava): o motor.
• scripts/setup_check.py: configuração e verificação na primeira execução.
• fonts/: TikTok Sans (código aberto, licença OFL).

Os estilos foram medidos contra TikToks reais do aplicativo. Não renderize texto de nenhuma outra forma (ffmpeg drawtext, fonte simples, etc.). Não corresponderá.

Passo 0: configuração (toda vez; leva cerca de 2 segundos depois de concluída)

Execute, com qualquer python / python3 disponível no PATH:

python "${CLAUDE_PLUGIN_ROOT}/skills/add-text/scripts/setup_check.py" "${CLAUDE_PLUGIN_DATA}"

• A primeira execução cria um ambiente Python privado na pasta de dados do plugin e instala os pacotes (cerca de 1–2 minutos). Informe o usuário sobre isso.

• A última linha é READY PY=<caminho>. Use esse <caminho> como o python para cada comando abaixo (escrito como PY).

• NOT READY: ... informa o que está faltando e a correção exata:

  • ffmpeg: pergunte ao usuário e execute o comando de instalação fornecido (winget no Windows, brew no Mac, apt no Linux). No Windows, pode ser necessário um novo terminal antes que o ffmpeg seja encontrado. Nesse caso, instrua o usuário a reiniciar o Claude Code.
  • Sem Python 3.9+: o usuário precisa instalá-lo (python.org) e reiniciar o Claude Code.

  Em seguida, execute a configuração novamente.

• Não há comando python? Tente python3, ou py no Windows.

Nos comandos abaixo, S = ${CLAUDE_PLUGIN_ROOT}/skills/add-text/scripts. Coloque cada caminho entre aspas. No PowerShell, inicie cada comando com & (ex.: & "PY" "S/add_text.py" ...).

Regras

• A saída mantém o tamanho e a taxa de quadros do vídeo de entrada (TikTok: 1080x1920). Salve a versão com texto ao lado do original como <nome> (COM TEXTO).mp4 e nunca sobrescreva o original.
• Conteúdo: o TikTok penaliza alegações enganosas. Evite alegações absolutas de resultado ("curado", "corrigido em 3 dias", "garantido"). Quando o gancho de uma referência fizer uma alegação, adapte a redação (mesmo ritmo e número de linhas) e informe ao usuário o que você mudou e por quê. Pergunte se tiver dúvidas.
• O texto digitado deve ser o que um iPhone produziria:
  • … não ...
  • aspas curvas ' " " se a referência as usar
  • emoji como caracteres reais de emoji
• Espaços iniciais e finais são importantes: o TikTok centraliza cada linha incluindo seus espaços. O fit os adiciona para você.

A. Copiando o texto de um TikTok de referência

Use uma pasta de trabalho ao lado do vídeo do usuário, ex.: text work/.

1. Iniciar: "PY" "S/add_text.py" start "REF.mp4" "WORKDIR"
   • Imprime cada legenda: início/fim (precisão de quadro, linha do tempo da referência), estilo, cor de preenchimento e caixa.
   • Escreve WORKDIR/captions.json com "text": "??" e um recorte ampliado WORKDIR/caption_<n>.png de cada uma.
   • Ignora a própria marca d'água "TikTok @user" do TikTok.
   • Precisa baixar a referência primeiro? yt-dlp funciona se estiver instalado. Caso contrário, peça ao usuário o arquivo.
2. Preencher o texto. Leia cada imagem de recorte e substitua cada "??".
   • Deixe os outros campos. Os campos com _ (_ref_t, _bbox_1080, ...) são usados pelo finish.
   • Quebras de linha são \n, e emoji são caracteres. Não se preocupe com espaços iniciais ou finais.
   • Se duas linhas tiverem cerca de duas vezes o espaçamento normal, isso é uma linha em branco: "A\n\nB".
   • Duas caixas de texto separadas em uma mesma legenda (tamanhos muito diferentes, um grande espaço ou não centralizadas no mesmo x): divida-as em duas entradas com o mesmo início/fim, _ref_t e estilo. Dê a cada uma seu próprio _bbox_1080: a união de suas linhas de _lines_1080 (o detect imprime a caixa e a altura de cada linha), para que o fit olhe para o texto correto. Exemplo: linhas 1:[346,1126,735,1167] e 2+3 → [346,1126,735,1167] e [204,1272,887,1389].
   • O style veio como custom / custom_outline? Isso é outra fonte, caixa de fundo ou outra cor que esta ferramenta não possui. Informe o usuário e escolha o estilo mais próximo. Não adivinhe silenciosamente.
   • Reajuste o tempo aqui se os cortes do usuário diferirem da referência: edite start/end (segundos, fim exclusivo). O fit e a verificação ainda olham para a referência em seu próprio tempo (_ref_t).
3. Finalizar: "PY" "S/add_text.py" finish "REF.mp4" "VIDEO.mp4" "WORKDIR"
   • Ajusta tamanho, posição e espaços no json e escreve WORKDIR/fit_<n>.png (referência em cima, nossa abaixo).
   • Encerra qualquer legenda que ultrapasse o vídeo na duração do vídeo.
   • Grava VIDEO (COM TEXTO).mp4 ao lado do vídeo (ou (sem texto) → (COM TEXTO)). Um 4º argumento escolhe outro nome de saída.
   • Verifica o resultado e escreve WORKDIR/check.jpg (referência à esquerda, nossa à direita).
   • Imprime um RESUMO: PASS ou REVISAR com os motivos.
4. Olhe para check.jpg e mostre-o ao usuário antes de dizer que está pronto.
   • Sobreposição baixa com "bordas correspondem à referência dentro de N px": tamanho e posição estão corretos. Texto comprimido dourado ou amarelo geralmente obtém 0,45–0,7 mesmo quando correto. Apenas confirme a redação visualmente.
   • Sobreposição baixa com "bordas deslocadas em N px": geralmente é um erro de digitação, uma quebra de linha perdida, o estilo errado ou um _bbox_1080 ruim após uma divisão. Corrija o json e execute o finish novamente.
   • Para manter tamanho/y/x ajustados manualmente, adicione --no-fit.

B. Novas legendas (sem referência)

Escreva um captions.json:

[{"text": "linha um\nlinha dois", "start": 0, "end": 3.5, "style": "outline", "size": 70, "y": 0.5}]

Em seguida, execute "PY" "S/add_text.py" new "VIDEO.mp4" "WORKDIR/captions.json". Ele grava o texto e escreve preview.jpg (um quadro por legenda) ao lado do json. Mostre ao usuário.

• style: classic (branco sólido), outline (branco + contorno preto), yellow (amarelo claro), yellow_gold (amarelo ouro), lilac (lilás).
• size: cerca de 50 (pequeno) a 85 (grande). Ganchos típicos estão entre 54 e 77.
• y: 0,4–0,5 = meio da tela, 0,65 = terço inferior. Mantenha-se longe dos 20% inferiores (legendas/UI do TikTok) e da borda direita (botões).
• Opcional: x (centro horizontal, padrão 0,5), weight, color ("#RRGGBB" para preenchimento personalizado).
• Quebre linhas onde uma pessoa digitando em um telefone quebraria. As linhas têm cerca de 20–28 caracteres no tamanho 70.

Olhada rápida sem renderizar um vídeo: "PY" "S/tiktok_text.py" --png "texto\nmais" out.png (estilo clássico).

Armadilhas

• Temporizações típicas: início cerca de 25 s, final 1–3 min dependendo do número de legendas (legendas com contorno ajustam mais lentamente), --no-fit cerca de 40 s.
• Emoji: cada novo é baixado uma vez (conjunto Apple, CDN emoji-data no jsDelivr), portanto, precisa de internet na primeira vez. Se um download falhar, o script gera um erro. Informe o usuário em vez de remover o emoji.
• Sem sombra, propositalmente: o texto real do TikTok não tem sombra. A aparência "mais limpa" ao lado da referência compactada é esperada e desaparece quando o TikTok recompacta o upload.
• Com apenas 2 linhas, o corretor de espaços do fit não consegue identificar qual linha está descentralizada. Se fit_<n>.png mostrar uma linha deslocada em cerca de 5 px e a sobreposição permanecer abaixo de cerca de 0,6, tente adicionar um espaço inicial ou final em cada linha manualmente e execute novamente.
• Windows: se os emoji forem impressos de forma estranha em outros trechos de Python, defina PYTHONIOENCODING=utf-8. Estes scripts lidam com isso.

Nota: Esta skill foi projetada para Claude Code, mas também pode ser usada no Cursor e Codex, desde que as dependências (Python 3.9+, ffmpeg) estejam instaladas e o caminho do plugin seja configurado corretamente.