Communitygithub.com

Aikoin/youtube-transcript-doc

Transforme um vídeo do YouTube em um documento de transcrição polido, bilíngue e com timestamps clicáveis para Feishu/Lark — uma skill para Mira/Claude.

O que é youtube-transcript-doc?

Esta skill permite que um agente AI (como Claude ou Mira) converta automaticamente um vídeo do YouTube em um documento de transcrição estruturado, bilíngue e de alta qualidade no Feishu (Lark). O fluxo completo abrange desde a extração do ID do vídeo e obtenção das legendas (com estratégias de fallback para sites de terceiros) até a limpeza do texto (remoção de palavras de preenchimento, correção de erros de ASR), segmentação por turnos de fala (evitando cortes no meio de frases), tradução paralela usando subagentes, e geração de um documento formatado com timestamps clicáveis e destaques visuais. A skill também oferece um passo opcional para criar um resumo visual em quadro branco editável (SVG) dentro do mesmo documento, seguindo regras rigorosas de contraste de cores para o Feishu. O resultado é uma transcrição pronta para consumo, com seções temáticas, cartões de destaque e alternância entre inglês e chinês, ideal para reuniões, palestras ou conteúdo educacional.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add Aikoin/youtube-transcript-doc

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Vídeo do YouTube → Documento de Transcrição Polido

Transforme um vídeo do YouTube (ou com legendas) em um documento de transcrição legível, clicável e preservável no Feishu.

O fluxo completo: Ler o vídeo → Obter SRT → Analisar em segmentos → Limpar + traduzir → Gerar documento no Feishu → (Opcional) Resumo visual em quadro branco.

Quando usar

O usuário envia um link de vídeo e deseja: transcrição / timeline / resumo no estilo de ata de reunião / extração de legendas / versão bilíngue / "Dá uma olhada nesse vídeo e organiza pra mim".

Fluxo

1. Obter video_id e informações básicas

Extraia o video_id de 11 caracteres da URL. Se possível, capture também o título, duração, palestrante/publicador — registre tudo no cabeçalho do documento.

2. Obter legendas (etapa mais propensa a falhas)

Acessar diretamente o YouTube para obter legendas é bloqueado pelo anti-scraping. Não insista. Siga a cadeia de fallback descrita em references/fetch-srt.md: Sites terceiros de legendas (downsub como primeira opção: abrir com remote browser → extrair o blob de download em download.subtitle.to → baixar com curl) → Extrair texto da página via browser → Pedir para o usuário exportar manualmente. Após obter, salve como transcript.srt.

3. Analisar em segmentos por falante

python scripts/parse_srt.py transcript.srt --video-id <VIDEO_ID> --out turns.json

Divida pelos marcadores de falante >> (se não houver, recorra à divisão por tamanho fixo). Este passo resolve de vez o problema de "frase cortada em dois" — antigamente a divisão por segundos fixos cortava frases no meio; agora cada segmento é uma fala completa. O script também remove segmentos isolados com apenas palavras de preenchimento.

4. Limpeza + tradução

Siga references/clean-translate.md: remova palavras de preenchimento, repetições de gagueira, corrija erros de ASR (nomes próprios, termos técnicos, nomes de empresas). Traduza segmento por segmento. Com quase cem segmentos, divida em 2–3 lotes usando subagentes paralelos, compartilhando uma tabela de correção de termos. Cada subagente gera um JSON {index:{en,zh}} que é consolidado em um único arquivo de conteúdo.

Com o conteúdo pronto, monte um content.json seguindo a estrutura do cabeçalho de scripts/build_doc.py (incluindo meta / seções temáticas / cartões de destaque / parágrafos / alternância bilíngue), depois:

python scripts/build_doc.py turns.json content.json --outdir frags/

Gera frags/intro.xml e frags/sec_0.xml … sec_N.xml.

Regras rígidas de formatação (consolidadas a partir de feedback de usuários reais, já incorporadas em build_doc.py, não altere):

  • Título simples, sem etiquetas como "bilíngue" ou similar;
  • Diferencie idiomas por cor (inglês em cinza, chinês em preto), sem escrever EN/ZH;
  • Sem destaque de bloco inteiro; destaques usam apenas ⭐, e o amarelo é reservado para cartões no topo; negrito/destaque de frases curtas fica para edição manual.

5. Publicar no Feishu

Use a skill lark-doc (docs +create para criar o documento com intro, depois docs +update --command append para adicionar seções sequencialmente). Detalhes em references/publish-lark.md. Após publicação, forneça a URL do documento ao usuário.

6. (Opcional) Gerar resumo visual em quadro branco

Frequentemente o usuário, após receber a transcrição, pede também uma imagem visual resumindo os pontos principais para inserir no mesmo documento. Siga a abordagem do beautiful-feishu-whiteboard: crie SVG manualmente (não usar layout automático do Mermaid) e converta em quadro branco editável no Feishu. O fluxo completo e as armadilhas estão em references/whiteboard-summary.md.

A regra mais importante e que mais causa problemas: ao renderizar, o quadro branco do Feishu força todo texto para cor escura. Portanto todo texto deve estar sobre fundo claro (creme/amarelo) com tinta escura, cores vibrantes apenas para bordas, faixas, marcadores ou badges. Nunca coloque texto sobre blocos de cor saturada. A cor do texto na prévia PNG local não é confiável; após escrever, use +query --output_as image para verificar a imagem real online e confirmar o contraste.

Iteração

Usuários costumam deixar comentários no documento e pedir alterações. Use +get-comments do lark-doc para puxar os comentários e atender um por um. Se houver erro de quebra de frase — volte ao passo 3 e corte novamente por turno de falante, não aplique remendos na segmentação errada.

Recursos

  • scripts/parse_srt.py — SRT → JSON com segmentos por falante
  • scripts/build_doc.py — Segmentos + tradução → fragmentos XML para Feishu (formatação embutida)
  • references/fetch-srt.md — Cadeia de fallback para obtenção de legendas (prioridade)
  • references/clean-translate.md — Normas de limpeza, tradução e formatação
  • references/publish-lark.md — Criação e atualização de documentos no lark-doc, leitura de comentários
  • references/whiteboard-summary.md — Geração de resumo visual usando beautiful-feishu-whiteboard (incluindo a armadilha "texto sempre sobre fundo claro")

Habilidades Relacionadas