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 falantescripts/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çãoreferences/publish-lark.md— Criação e atualização de documentos no lark-doc, leitura de comentáriosreferences/whiteboard-summary.md— Geração de resumo visual usando beautiful-feishu-whiteboard (incluindo a armadilha "texto sempre sobre fundo claro")