O que Extensão OpenCaptions faz?
Conecte legendas CWI (Caption With Intent) ao pipeline de pós-produção do Content Engine. Em vez de legendas estáticas e planas, o CWI codifica a experiência sentida da fala — o tom determina o peso da fonte, o volume determina o tamanho da fonte, a ênfase aciona animações de brilho e a identidade do locutor é mapeada para cores WCAG AA. O resultado são legendas que comunicam como algo foi dito, não apenas o que foi dito.
CWI é o padrão de legendagem vencedor do Oscar (2025), criado pela FCB Chicago e pela Chicago Hearing Society. OpenCaptions é o primeiro conjunto de ferramentas programáticas de código aberto para ele.
Ponto de Conexão no Pipeline
Etapa: Pós-Produção (Etapa 3) Posição: Após o upscale e a correção de cor, antes da exportação final.
Cadeia de Pós-Produção:
1. Upscale (Real-ESRGAN / Topaz) --> Resolução mais alta
2. Correção de Cor (LUT da marca / ffmpeg) --> Cores da marca
3. OpenCaptions (CWI) --> Legendas orientadas por intenção
4. Exportação Final (ffmpeg) --> Arquivo pronto para produção
A extensão recebe um arquivo de vídeo corrigido e produz:
- Um documento CWI (
.cwi.json) com anotações de intenção por palavra - Um fallback WebVTT (
.vtt) para plataformas que exigem legendas padrão - Um relatório de validação (JSON) com pontuações dos pilares
- Um vídeo legendado (
.mp4) renderizado via Remotion ou ffmpeg
Como Funciona
Vídeo Corrigido + Briefing da Cena
|
├── [1] Transcrição (faster-whisper) --> timestamps por palavra
├── [2] Diarização (pyannote-audio) --> atribuição de locutor
├── [3] Extração de Intenção --> tom, volume, emoção, ênfase por fala
| V1: parselmouth + FER (áudio+visão)
| V2: modelo de mundo V-JEPA2
| V3: predição neural TRIBE v2
├── [4] Mapeamento Intenção --> CWI --> peso, tamanho, ênfase, animação por palavra
| V1: RulesMapper (tom-->peso, volume-->tamanho)
| V2: LearnedMapper (treinado em dados de correção)
| V3: NeuralMapper (ativações de regiões cerebrais direcionam a estilização)
├── [5] Validação (12 regras) --> Pontuações de Atribuição + Sincronização + Entonação
└── [6] Renderização --> Sobreposição Remotion OU queima ffmpeg
Etapa 1-2: Transcrição + Diarização
O pipeline chama a CLI ou servidor MCP do OpenCaptions, que executa o faster-whisper para timestamps por palavra e o pyannote-audio para detecção de locutor. Essas etapas produzem um DiarizedTranscript com cada palavra marcada para um locutor.
Etapa 3: Extração de Intenção
O extrator de intenção analisa o áudio e o vídeo para determinar o registro sentido de cada fala:
- Sinais vocais: Tom (Hz), volume (dB), velocidade da fala (PPM), tempo de pausa
- Sinais de afeto: Valência (-1 a 1), excitação (0 a 1), emoção dominante
- Sinais semânticos: Probabilidade de sarcasmo, palavras de ênfase, figuras de linguagem
Esses sinais formam um IntentFrame para cada fala. Palavras individuais que se desviam da linha de base da fala recebem substituições WordIntent.
Etapa 4: Mapeamento de Intenção
O mapeador converte sinais de intenção em parâmetros visuais CWI:
| Sinal de Intenção | Propriedade CWI | Mapeamento (RulesMapper V1) |
|---|---|---|
| Tom (normalizado 0-1) | weight (100-900) | Interpolação linear: 100 + tom_norm * 800 |
| Volume (normalizado 0-1) | size (0.7-1.5) | Interpolação linear: 0.8 + volume_norm * 0.55 |
| Ênfase semântica + volume alto | emphasis (booleano) | Palavra em palavras_enfase OU volume > p90 |
| Identidade do locutor | color do locutor | Atribuído a partir de paleta de 12 cores WCAG AA |
| Sussurro (volume baixo) | weight < 300 | Substituição: peso fixado em 100-250 |
| Grito (volume alto) | size > 1.3 + ênfase | Substituição: tamanho 1.35-1.5, ênfase verdadeiro |
Etapa 5: Validação
O validador @opencaptions/spec verifica o documento CWI contra 12 regras em três pilares:
Atribuição (3 regras):
- ATT_001: Cada legenda tem um locutor no elenco
- ATT_002: Locutores têm cores únicas
- ATT_003: Cores atendem ao contraste WCAG AA (4.5:1 contra #1a1a1a)
Sincronização (5 regras):
- SYN_001: Todas as palavras têm timestamps
- SYN_002: Timestamps estritamente crescentes
- SYN_003: Eventos de legenda não se sobrepõem
- SYN_004: Duração da animação em 600ms conforme especificação
- FCC_001: Sem lacunas > 3s durante a fala
- FCC_002: Máximo de 42 caracteres por linha (conforme FCC)
Entonação (3 regras):
- INT_001: Peso no intervalo válido (100-900)
- INT_002: Tamanho no intervalo válido (0.7-1.5)
- INT_003: > 20% das palavras têm peso não padrão (as legendas realmente variam)
Cada pilar pontua de 0 a 100. Um documento CWI é aprovado se todos os três pilares obtiverem pontuação >= 80.
Etapa 6: Renderização
Dois caminhos de renderização:
Caminho Remotion (preferido para o Content Engine): As palavras CWI tornam-se componentes React em uma composição <CaptionOverlay>. Cada palavra aparece em seu timestamp com animação de entrada spring(), cor do locutor, peso variável da fonte e brilho de ênfase. Consulte references/cwi-remotion-bridge.md para o mapeamento completo.
Queima ffmpeg (fallback): Gera um arquivo de legenda ASS a partir do documento CWI e o queima no vídeo via ffmpeg -vf ass=legendas.ass. Perde a animação por palavra, mas preserva as cores do locutor e a variação de peso da fonte.
Uso da CLI
# Gerar legendas CWI a partir de um vídeo
npx opencaptions generate video.mp4 --output legendas.cwi.json
# Gerar com o backend neural TRIBE v2
npx opencaptions generate video.mp4 --backend tribe --output legendas.cwi.json
# Validar um documento CWI
npx opencaptions validate legendas.cwi.json
# Visualizar legendas no terminal (coloridas com ANSI)
npx opencaptions preview legendas.cwi.json
# Exportar para WebVTT
npx opencaptions export legendas.cwi.json --format webvtt
# Exportar para ExtendScript do After Effects
npx opencaptions export legendas.cwi.json --format ae-json
# Exportar para XML do Premiere Pro
npx opencaptions export legendas.cwi.json --format premiere-xml
# Verificar dependências do sistema
npx opencaptions doctor
# Instalar dependências Python
npx opencaptions setup
Uso do Servidor MCP
O servidor MCP do OpenCaptions expõe quatro ferramentas para integração com agentes:
| Ferramenta | Descrição |
|---|---|
generate_captions | Executa o pipeline completo em um arquivo de vídeo |
validate_captions | Valida um documento CWI contra 12 regras |
preview_captions | Visualização formatada no terminal em um determinado momento |
export_captions | Exporta para o formato WebVTT |
Para usar via Claude Code, adicione o servidor MCP às suas configurações:
{
"mcpServers": {
"opencaptions": {
"command": "npx",
"args": ["@opencaptions/mcp"]
}
}
}
Em seguida, invoque na conversa: "Gerar legendas CWI para video.mp4" aciona generate_captions.
Integração com compose-video.py
O compose-video.py do Content Engine aceita a flag --captions:
python3 scripts/compose-video.py storyboard.md --brand arcan-studio --captions
Quando --captions é passado, após todos os clipes serem gerados e montados, o pipeline:
- Executa
npx opencaptions generate {video-final}.mp4 --output {dir-saida}/legendas.cwi.json - Valida o documento CWI (avisa se a pontuação for < 80, mas não bloqueia)
- Se
--remotiontambém for passado, injeta o JSON CWI na composição Remotion como props<CaptionOverlay> - Caso contrário, gera WebVTT como um arquivo auxiliar junto ao vídeo final
Se o OpenCaptions não estiver instalado (npx opencaptions doctor falhar), o pipeline degrada graciosamente:
- Recai para sobreposição de texto do briefing da cena (texto estático das descrições
## Shotdo storyboard) - Registra um aviso: "OpenCaptions não disponível, usando sobreposição de texto do briefing da cena"
- Ainda produz um arquivo
.vttcom temporização derivada dos limites dos clipes
Estilos de Legenda
Três estilos de legenda pré-definidos, selecionáveis via configuração:
1. Palavra por Palavra (brainrot)
Estilo de alta retenção: cada palavra aparece individualmente, centralizada, com variação máxima de tamanho. Usado para conteúdo social/TikTok/Reels otimizado para gatilhos de dopamina.
- Uma palavra visível por vez
- Tamanho base grande (64px a 1080p)
- Variação extrema de peso (100-900 faixa completa)
- Palavras de ênfase escalam para 1.5x com brilho
- Fundo: nenhum (palavras flutuam sobre o vídeo)
- Fonte: Roboto Flex variável
2. Narrativo (editorial)
Exibição de frase completa com estilo por palavra. Usado para conteúdo de formato longo, documentários, embeds de vídeo em blogs.
- Evento de legenda completo visível, palavras estilizadas inline
- Tamanho base médio (48px a 1080p)
- Variação moderada de peso (300-700)
- Palavras de ênfase ganham aumento sutil de tamanho (1.15x)
- Fundo: pill semitransparente (rgba(0,0,0,0.6))
- Fonte: Roboto Flex variável
3. Minimalista (terço inferior)
Apresentação limpa no terço inferior. Nome do locutor + texto. Distração visual mínima. Usado para entrevistas, cabeças falantes, gravações de conferências.
- Rótulo do nome do locutor na cor do locutor, texto da legenda em branco
- Tamanho base pequeno (36px a 1080p)
- Variação de peso apenas para ênfase (400 padrão, 700 ênfase)
- Sem variação de tamanho
- Fundo: barra de gradiente (15% inferior do quadro)
- Fonte: sans-serif do sistema
Contrato de Dados
Leituras (imutáveis)
- Ativo de vídeo corrigido da etapa anterior de pós-produção
knowledge/compiled/brands/{slug_da_marca}.md-- para paleta de cores das legendas e preferências tipográficas- Briefing da cena (parâmetro em tempo de execução) -- para contexto do tom emocional pretendido
Escritas (apenas no próprio namespace)
extensions/opencaptions/output/{id_do_ativo}.cwi.json-- Documento CWIextensions/opencaptions/output/{id_do_ativo}.vtt-- Fallback WebVTTextensions/opencaptions/output/{id_do_ativo}-report.json-- Relatório de validaçãoextensions/opencaptions/output/{id_do_ativo}-captioned.mp4-- Vídeo renderizado (apenas caminho Remotion)
Configuração
opencaptions:
# Predefinição de estilo de legenda
style: "narrative" # word-by-word | narrative | minimal
# Parâmetros visuais
font_family: "Roboto Flex" # Fonte variável para eixo de peso
base_font_size: 48 # Pixels a 1080p
position: "bottom" # top | center | bottom
max_chars_per_line: 42 # Conformidade FCC
background: "pill" # pill | shadow | gradient | none
background_opacity: 0.6 # 0.0 - 1.0
# Backend do pipeline
backend: "av" # av (V1) | jepa (V2) | tribe (V3)
language: "en" # Dica ISO 639-1 para transcrição
# Substituições de locutor (opcional, auto-detectado por padrão)
speakers:
- name: "Narrador"
color: "#6B8AFF"
- name: "Convidado"
color: "#FF6B6B"
# Renderização
render_mode: "remotion" # remotion | ffmpeg | sidecar-only
output_format: "mp4" # mp4 | webm
fps: 30 # Corresponder ao vídeo de origem
# Validação
min_score: 80 # Pontuação mínima geral para prosseguir
fail_on_low_score: false # Se verdadeiro, bloqueia o pipeline em caso de pontuação baixa
# Mapeamento neural TRIBE v2 (apenas backend V3)
neural_mapping: false # Habilita a estilização baseada em resposta neural prevista
Degradação Graciosa
A extensão nunca bloqueia o pipeline do Content Engine. Escada de degradação:
| Condição | Comportamento |
|---|---|
| CLI OpenCaptions instalada + todas as dependências Python | Pipeline CWI completo (transcrição, diarização, intenção, mapeamento) |
| CLI OpenCaptions instalada, sem dependências Python | Backends simulados com legendas placeholder + validação |
| CLI OpenCaptions não instalada | Sobreposição de texto do briefing da cena como legendas estáticas nos limites dos clipes |
| Vídeo sem faixa de áudio | Pular geração de legenda, registrar mensagem informativa |
| Pontuação de validação < 80 | Avisar, mas prosseguir (a menos que fail_on_low_score: true) |
| Remotion não disponível | Recair para queima ASS ffmpeg |
| ffmpeg não disponível | Gerar apenas JSON CWI + WebVTT como arquivos auxiliares (sem vídeo renderizado) |
Relacionados
- Projeto OpenCaptions:
~/broomva/apps/opencaptions/ - Ponte CWI-Remotion:
references/cwi-remotion-bridge.md - Guia de integração:
references/integration-guide.md - SKILL.md do Content Engine:
../../SKILL.md - Framework de extensão:
../README.md