video-captioner — Pipeline de Legendas Animadas
Transcreve áudio com Whisper e insere legendas animadas palavra por palavra em vídeos. Sem correção de cor — para aprimoramento visual, use a skill video-enhancer primeiro.
Pipeline
vídeo de entrada → transcrição Whisper → renderização de legendas pycaps → vídeo de saída com legendas
Estilos de legenda
Três opções:
- Padrão (sem flag) — estilo minimalista embutido do pycaps: texto branco simples, sem efeitos.
- Futurista (incluído) —
--css scripts/futuristic.css— legendas alternando dourado/magenta com efeito de brilho e fonte monoespaçada. Bom para conteúdo tech, gaming ou de alta energia. - Personalizado — o usuário pode fornecer qualquer caminho de arquivo CSS via
--css /path/to/custom.css.
Se o usuário não mencionou um estilo de legenda, pergunte se ele quer o visual padrão, o estilo futurista ou um arquivo CSS personalizado.
Legendas estáticas
Use --caption para adicionar texto predefinido em timestamps específicos, em vez de transcrever o áudio:
--caption "INÍCIO-FIM: TEXTO"
Formato:
- Os horários usam o formato
M:SSouMM:SS(ex.:0:05= 5 segundos,1:30= 90 segundos) - Múltiplas legendas: use
--captionvárias vezes - Se tanto legendas estáticas quanto transcrição forem fornecidas, as legendas estáticas têm precedência
Exemplo:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Olá mundo" \
--caption "0:10-0:20: Isto é uma demonstração" \
--css scripts/futuristic.css
Estilização de legendas
A estilização é gerenciada através de arquivos de configuração JSON. Ao usar legendas estáticas, a estilização é aplicada automaticamente.
Estilização padrão
Quando nenhum --style-config é especificado, config.default.json é usado:
- Fundo: branco (
#FFFFFF) - Cor do texto: azul (
#0066FF) - Fonte:
auto— usa primeiro uma fonte da marca disponível marcada comocaption, depois usa Courier New - Padding:
10px 15px - Margem:
0
Usando uma configuração de estilo
Altere estilos passando um arquivo de configuração:
# Usar estilo modo escuro
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Olá" \
--style-config config.dark-mode.json
Configurações incluídas:
config.default.json— fundo branco, texto azul, Courier New (padrão)config.dark-mode.json— fundo escuro, texto branco, fonte maior
Criando configurações de estilo personalizadas
Copie config.default.json e modifique:
{
"caption_bg_color": "#000000",
"caption_color": "#FFFFFF",
"caption_font": "auto",
"caption_font_tag": "caption",
"caption_padding": "20px 30px",
"caption_margin": "10px",
"caption_font_size": 48
}
Depois use:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Texto" \
--style-config meu-estilo-personalizado.json
Sobrescrevendo configuração com flags de CLI
Flags de CLI têm precedência sobre valores do arquivo de configuração:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Olá" \
--style-config config.dark-mode.json \
--caption-color "#00FF00" # Sobrescreve a cor do texto da configuração
Referência de configuração de estilo
| Chave | Tipo | Descrição |
|---|---|---|
caption_bg_color | string | Cor de fundo (hex ou nome de cor CSS) |
caption_color | string | Cor do texto (hex ou nome de cor CSS) |
caption_font | string | auto, família de fonte, ou caminho para arquivo .ttf, .otf, .woff, .woff2 |
caption_font_tag | string ou null | Tag de fonte da marca para preferir do brand-manager (caption, body, heading, etc.) |
caption_padding | string | Padding CSS (ex.: "10px 15px") |
caption_margin | string | Margem CSS (ex.: "0") |
caption_font_size | integer ou null | Tamanho da fonte em pixels (null = escala automática) |
Fontes disponíveis
Fontes do sistema podem ser especificadas pelo nome:
DejaVu Sans/DejaVu Sans Bold/DejaVu SerifLiberation Sans/Liberation MonoCourier NewUbuntu Mono- Qualquer caminho de arquivo TTF:
/caminho/para/fonte.ttf
Ou escolha entre fontes da marca em skills/brand-manager/brand-assets/asset-manifest.json.
Quando caption_font é auto, a skill lê o manifesto da marca (ou CLAW_BRAND_ASSETS_DIR se definido) e usa a primeira fonte disponível marcada por caption_font_tag; se não existir fonte marcada, tenta fontes da marca marcadas caption, body, heading ou bold, e depois usa Courier New. Se a fonte da marca resolvida for um caminho de arquivo, o CSS gerado inclui uma regra @font-face para que o pycaps possa renderizá-la.
Como executar
Instale as dependências (apenas na primeira execução):
cd "$SKILL_DIR" && uv sync
Nota: a primeira execução será lenta (potencialmente vários minutos) porque o pycaps baixa o modelo de reconhecimento de fala Whisper. Avise o usuário sobre isso antes de começar.
Depois processe os vídeos:
cd "$SKILL_DIR" && uv run python scripts/caption_service.py \
--input <caminho/para/entrada> \
--output <caminho/para/saída> \
[--css scripts/futuristic.css]
Invocações comuns
# Legendas minimalistas padrão (transcrição Whisper)
uv run python scripts/caption_service.py --input ./input --output ./output
# Estilo futurista
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--css scripts/futuristic.css
# CSS personalizado
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--css /caminho/para/meu.css
# Legendas estáticas com estilo padrão (fundo branco, texto azul, Courier New)
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Inscreva-se para mais" \
--caption "0:10-0:15: Siga-nos no Instagram"
# Legendas estáticas com estilo modo escuro
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Olá mundo" \
--caption "0:10-0:20: Isto é uma demonstração" \
--style-config config.dark-mode.json
# Legendas estáticas com configuração de estilo personalizada
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Texto personalizado" \
--style-config meu-estilo-personalizado.json
# Legendas estáticas com sobrescritas de CLI
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Olá" \
--style-config config.dark-mode.json \
--caption-color "#00FF00"
# Modo de observação (verifica novos vídeos a cada 10s)
uv run python scripts/caption_service.py --input ./input --output ./output --watch
Após a execução
Relate ao usuário:
- Quantos vídeos foram processados com sucesso e quantos falharam.
- O caminho completo para o diretório de saída.
- Se algum vídeo falhou, nomeie-os explicitamente.
Casos de borda
- Se
ffmpegnão estiver instalado: diga ao usuário para instalá-lo (sudo pacman -S ffmpegno Arch/CachyOS,brew install ffmpegno macOS,sudo apt install ffmpegno Ubuntu) - Se
uvnão estiver instalado: direcione para https://docs.astral.sh/uv/getting-started/installation/ - Se o diretório de entrada estiver vazio: reporte claramente em vez de sair silenciosamente
- A primeira execução baixa o modelo Whisper (~140 MB para
tiny, ~1.5 GB paralarge) — isso é feito apenas uma vez
Transcrição Remota
Esta skill agora suporta transcrição remota opcional enquanto mantém a renderização pycaps local.
- O comportamento padrão continua totalmente local: transcrição Whisper dentro do pycaps + renderização local
- O modo remoto substitui apenas a etapa de transcrição
- A renderização de legendas, modelos e manipulação de CSS permanecem locais
Provedores suportados
huggingfacereplicate
Chaves de configuração / CLI
| Chave | Padrão | Notas |
|---|---|---|
transcription_provider | null | null mantém o fluxo local Whisper-in-pycaps |
remote_model | null | Opcional: substituição do modelo de transcrição específico do provedor |
hf_token_env | HF_TOKEN | Nome da variável de ambiente de autenticação HuggingFace |
replicate_api_key_env | REPLICATE_API_TOKEN | Nome da variável de ambiente de autenticação Replicate |
remote_timeout_seconds | 300 | Timeout da chamada remota |
Exemplos
# Transcrição remota HuggingFace + renderização pycaps local
export HF_TOKEN=hf_seu_token
uv run python scripts/caption_service.py --input ./input --output ./output --transcription-provider huggingface
# Transcrição remota Replicate + renderização pycaps local
export REPLICATE_API_TOKEN=r8_seu_token
uv run python scripts/caption_service.py --input ./input --output ./output --transcription-provider replicate --remote-model <slug-do-modelo-replicate>
Notas
- Não há fallback silencioso para modo local se a autenticação/configuração remota estiver faltando
- O uso existente da CLI local permanece válido
- Se você não definir
--transcription-provider, o pycaps continuará usando seu fluxo Whisper embutido