Bilibili / YouTube Áudio para Legendas
Use o ambiente Conda chamado codex para transcrever no idioma original. O modelo padrão é Qwen/Qwen3-ASR-1.7B + Qwen/Qwen3-ForcedAligner-0.6B, chamado através do kit oficial qwen-asr com return_time_stamps=True. O modelo ASR gera apenas o texto, e o ForcedAligner fornece timestamps em nível de palavra/caractere. As legendas SRT são organizadas por pontuação, pausas, aproximadamente 6 segundos e 42 caracteres, com limites derivados do alinhamento real, sem dividir igualmente a duração ou descartar texto.
--engine whisper mantém o modo nativo de áudio longo do openai/whisper-large-v3-turbo, o pipeline usa return_timestamps=True, sem passar chunk_length_s. A segmentação externa experimental do Whisher já produziu legendas de cinco minutos e repetições consecutivas, portanto não deve ser ativada por padrão. O SDK oficial do Qwen processa segmentos de até 180 segundos com limites de baixa energia para alinhamento, restaurando automaticamente o tempo global; esta é uma implementação diferente da segmentação experimental de 30 segundos do pipeline do Whisper.
O Qwen suporta timestamps para chinês, inglês, cantonês, francês, alemão, italiano, japonês, coreano, português, russo e espanhol; para outros idiomas, selecione explicitamente o Whisper, e não assuma que o suporte ao ASR implica suporte ao alinhamento. Por padrão, a detecção é automática; para idiomas conhecidos, passe --language chinese ou english; também aceita códigos comuns como zh/en.
Execução e Saída
Primeiro, registre o caminho absoluto do projeto do usuário; não use o diretório de instalação da skill como diretório do projeto. Substitua <dir-da-skill> pelo diretório onde este SKILL.md está localizado e <dir-do-projeto> pelo caminho do projeto no momento da chamada; a URL é passada como um único argumento entre aspas.
conda run --no-capture-output -n codex python "<dir-da-skill>/scripts/bilibili_audio_subtitles.py" \
'https://www.bilibili.com/video/BV1w88n6uE1X/' \
--project-dir '<dir-do-projeto>'
O mesmo comando também aceita links do YouTube, como 'https://youtu.be/jNQXAC9IVRw'. Mantenha o nome original da skill e do script; chamadas existentes usando $bilibili-audio-subtitles continuam funcionando.
O áudio do Bilibili é baixado pelo yutto, salvo como ~/Downloads/<BV-ou-av-número>-p<N>.m4a; o áudio do YouTube é baixado pelo yt-dlp, salvo como ~/Downloads/youtube-<ID-do-vídeo>.m4a. O diretório do projeto gera apenas um SRT por vez, com timestamps e texto; apenas esta legenda recomendada é entregue, sem VTT, TXT, JSON ou arquivos de comparação de modelo. Alertas de qualidade necessários são fornecidos como breves explicações para revisão, sem gerar arquivos de entrega adicionais. O texto/chunks original do modelo e o diagnóstico de reprodução são salvos em JSONs independentes em ~/.cache/bilibili-audio-subtitles/runs/; o log da execução fornece o caminho; este é um registro interno de diagnóstico, não um arquivo de legenda adicional.
Áudios existentes são reutilizados. Quando um SRT com o mesmo nome já existe, o novo resultado usa automaticamente um nome de arquivo independente contendo o modo, a versão do script e o número da execução, preservando a versão antiga; não sobrescreve nem exclui legendas antigas. Após repetições, indique claramente ao usuário qual versão SRT é recomendada, não apenas liste todos os caminhos.
Opções comuns:
--audio '/caminho/absoluto/audio.m4a': transcodifica áudio local, sem passar URL.--language chinese: especifique explicitamente para idiomas conhecidos; por padrão, detecção automática.--engine qwen|whisper: padrão Qwen; Whisper para comparação, prioridade de velocidade ou idiomas sem suporte de alinhamento do Qwen.--project-dir/--download-dir: substitui o diretório de saída do projeto ou Downloads.--device auto|cpu|cuda:0: padrão prioriza CUDA; não altere drivers do sistema automaticamente.--download-only: apenas baixa; depois use--audiopara continuar.--output-name 'nome_do_arquivo': personaliza o nome do arquivo SRT, sem caminho ou extensão.--diagnostics-dir '/caminho/absoluto': substitui o diretório interno de resultados originais e diagnóstico.--auth-file '/caminho/absoluto': apenas para arquivos de autenticação fornecidos pelo usuário para Bilibili/yutto.--cookies-file '/caminho/absoluto': apenas para arquivos de cookies Netscape do YouTube fornecidos pelo usuário; não escaneia navegadores.--max-cue-seconds 12: limite de alerta para legendas muito longas; padrão 12 segundos.--limit-seconds 30: trecho solicitado pelo usuário ou teste de fumaça; o nome do arquivo é marcado como sample, e o relatório indica explicitamente que não é uma transcrição completa.--threads 8/--batch-size 1: controla threads e tamanho do lote de inferência.--engine whisper --chunk-length-seconds 30: ative apenas com motivo claro e explicação do risco experimental; Qwen não aceita este parâmetro.
Suporta links padrão do Bilibili /video/BV…, /video/av… e números BV/av. Mantém ?p=N para seleção de parte, remove parâmetros de rastreamento. Por padrão, processa apenas uma parte; solicitações de múltiplas partes são chamadas uma a uma. Links curtos do Bilibili são resolvidos para links padrão.
YouTube suporta youtube.com/watch?v=…, youtu.be/…, shorts/…, live/… e embed/… (incluindo subdomínios www, m, music). Uniformiza para link padrão de vídeo único, remove parâmetros de rastreamento, início e listas de reprodução, e usa explicitamente --no-playlist; links que contêm apenas listas de reprodução são rejeitados diretamente. O download seleciona bestaudio, extrai via FFmpeg para M4A, sem baixar legendas da plataforma, capas ou vídeos como arquivos de entrega. Não escaneia navegadores, não imprime cookies, não expande para coleções inteiras.
Falha no Download: Priorizar Verificação de Atualizações
Esta regra se aplica a ambas as plataformas. Quando o download falha ou o downloader retorna sucesso sem áudio válido, o script primeiro consulta a versão estável compatível do pacote de download correspondente: Bilibili verifica yutto, YouTube verifica yt-dlp. Use pip index versions <pacote> --json do Python codex atual para comparar a versão local e a versão no índice de pacotes, respeitando a configuração existente do pip.
Se houver uma versão mais recente, o script atualiza apenas este pacote de download e suas dependências necessárias no ambiente, e tenta o download novamente uma vez. yt-dlp usa yt-dlp[default], mantendo a correspondência de dependências EJS do YouTube. Se não houver nova versão, a consulta falhar, a atualização falhar ou o segundo download falhar, salva o erro original e o evento de atualização e para; não repita infinitamente nem mude automaticamente para nightly/master. Após verificar a atualização do pacote, verifique rede, login, disponibilidade do vídeo, restrições geográficas e runtime JS com base no erro real.
A atualização requer acesso à rede e permissões de escrita no ambiente. Quando as permissões são limitadas, solicite as permissões necessárias para esta execução; não troque o Python do sistema, nem atualize o modelo de transcrição ou PyTorch devido a problemas de download. Falha na consulta de atualização não significa que a versão atual seja a mais recente. Áudios corrompidos existentes devem ser explicitamente relatados e preservados; não sobrescreva diretamente; áudios inválidos gerados por novas tentativas de download também preservam nomes independentes.
Verificação Estrutural e Verificação de Qualidade
Ambos os tipos de verificação devem ser relatados separadamente:
- Verificação Estrutural: duração total do áudio decodificado corresponde, legendas não vazias, timestamps finitos, ordenados, início e fim válidos e não excedem a duração da transcrição. Em caso de falha, preserve o diagnóstico original e não gere SRT.
- Verificação de Qualidade: legendas com mais de 12 segundos, mais de 120 caracteres de texto por linha, densidade de texto acima de 25 caracteres/segundo, duração contínua de pelo menos 8 segundos mas abaixo de 0,5 caracteres/segundo, repetição de palavras ou frases em uma única legenda pelo menos 5 vezes, pelo menos 3 legendas consecutivas com o mesmo texto. Timestamps que precisam de correção também são marcados para revisão. Limiares e detalhes dos alertas são escritos no diagnóstico.
Código de saída 0 indica que a estrutura passou e nenhum problema de qualidade óbvio foi encontrado; código de saída 2 indica que o SRT foi gerado, mas precisa de revisão; código de saída 1 indica falha de execução ou estrutura. Não declare um código de saída 2 como verificação bem-sucedida. As regras de qualidade são dicas heurísticas, não prova de correção do conteúdo de fala; falsos positivos devem ser julgados contra o áudio, não ajuste limiares arbitrariamente, apague texto, recorte por duração igual ou repita infinitamente para eliminar alertas.
Quando uma anomalia de qualidade é detectada, forneça a janela de tempo do alerta e o caminho do diagnóstico. Se a anomalia vier de segmentação externa explícita do Whisper, tente novamente com o modo nativo --engine whisper uma vez, mantendo ambas as saídas; se ainda anormal, indique que precisa de revisão, não alterne modelo automaticamente nem repita infinitamente. Correção de terminologia deve ser tratada separadamente; não substitua globalmente por suposição palavras como "fluxo de pedidos" ou "mouse". Mesmo sem alertas, chame-a apenas de rascunho de transcrição automática, não de legenda revisada frase por frase.
O diagnóstico JSON preserva text/chunks originais, segments normalizados, status estrutural, status de qualidade e alertas, registro de correções, status de recomendação, versão do script, modo de transcrição, parâmetros de geração, GenerationConfig e revision do modelo, versões das bibliotecas, dispositivo, duração e tempo de inferência. Também registra a plataforma de origem, versões dos pacotes de download, verificação de atualizações e eventos de repetição. Qwen adicionalmente preserva a string ASR original antes do pós-processamento do SDK, unidades completas de alinhamento, idioma detectado, contagem de unidades de duração zero, revision do modelo de alinhamento e configuração de segmentação; repetições na saída original e proximidade do limite de comprimento de geração também acionam revisão; não deixe o filtro de repetição do SDK mascarar anomalias. Quantifique timestamps: palavras com duração zero são incorporadas em legendas adjacentes com texto preservado; não forje durações de palavras; se um segmento inteiro não tiver duração válida ou o texto não corresponder, salve o resultado original e falhe. Falhas de download ou transcrição também salvam diagnósticos independentes para reprodução e comparação.
Ambiente
Verifique Python do ambiente codex, pacotes de download da plataforma correspondente, torch, transformers, accelerate, numpy, qwen-asr, e ffmpeg e ffprobe no PATH. Instale apenas dependências ausentes no ambiente:
conda run --no-capture-output -n codex python -m pip install yutto 'yt-dlp[default]' 'qwen-asr==0.0.6' numpy
O kit Qwen fixa Transformers 4.57.6 e accelerate 1.12.0, evitando atualizar para Transformers 5 ou instalar vLLM para esta tarefa. Mantenha o PyTorch CUDA existente utilizável. Ambiente verificado localmente: Python 3.12, qwen-asr 0.0.6, yutto 2.3.1, Transformers 4.57.6, PyTorch 2.14.1+cu130; no CUDA, Qwen usa bfloat16 e SDPA; não requer compilação FlashAttention. Se precisar recriar o ambiente GPU local:
conda run --no-capture-output -n codex python -m pip install 'torch==2.14.1+cu130' --index-url https://download.pytorch.org/whl/cu130
Se o shell não encontrar conda, localize seu caminho absoluto. Localmente, pode-se usar /home/leev/miniforge3/bin/conda ou /home/leev/miniforge3/envs/codex/bin/python. Se a detecção de GPU falhar em um sandbox restrito, execute novamente a detecção em um ambiente com acesso a dispositivos NVIDIA; não conclua que o driver está danificado ou mude para a versão CPU. Máquinas verdadeiramente sem GPU devem usar o PyTorch CPU correspondente.
YouTube também requer as dependências padrão EJS do yt-dlp e um runtime JS suportado. O script procura Deno, Node, Bun ou QuickJS no PATH e os passa explicitamente para yt-dlp; localmente, Node 24 e yt-dlp 2026.08.19 foram verificados. Se não encontrar o runtime ou a versão for incompatível, relate claramente; não reinstale outros pacotes repetidamente devido a falhas de download.
A primeira execução baixará o modelo para o cache padrão do Hugging Face, respeitando HF_HOME / HF_HUB_CACHE; se o cache estiver completo e a rede instável, configure HF_HUB_OFFLINE=1. Bilibili usa apenas yutto para download, desativando vídeo, danmaku, legendas da plataforma, capas e informações de capítulo; YouTube usa apenas yt-dlp para baixar áudio. Se o download falhar, processe primeiro a regra de atualização, depois relate o erro real; se a transcrição falhar, preserve o áudio. Quando as permissões são limitadas, solicite permissões de diretório e execução GPU necessárias para esta execução.
Validação de Regressão
Exemplo fixo: BV1w88n6uE1X. Execute a transcrição Qwen padrão completa com o mesmo áudio; se precisar comparar, use --engine whisper, preservando ambos os diagnósticos e chamando:
python -m unittest discover -s '<dir-da-skill>/scripts' -p 'test_*.py'
python '<dir-da-skill>/scripts/check_regression.py' \
--candidate '<novo diagnóstico JSON do cache>' --baseline '<JSON antigo>'
As janelas de tempo importantes são 00:43.240–05:46.060 e 08:10–08:33. Na prática, Qwen gerou 282 segmentos, com máximo de 5.76 segundos; Whisper nativo gerou 438 segmentos, com máximo de 5.18 segundos; ambas as janelas não tiveram alertas de comprimento excessivo ou repetição; não use o número fixo de segmentos como condição de aprovação para outros ambientes. O resultado antigo de 117 segmentos com legenda de 302.82 segundos e 23 ocorrências consecutivas de "好" deve ser marcado como precisando de revisão pela verificação de qualidade da nova versão. A regressão aprovada prova apenas que os problemas conhecidos de segmentação e repetição não se repetiram; semântica e terminologia ainda precisam ser verificadas contra o áudio.
A regressão do YouTube inclui roteamento watch/curto/Shorts, baixar apenas áudio de um único vídeo, verificar atualização prioritária em caso de falha, tentar no máximo uma vez após atualização, e parar se não houver atualização ou a consulta falhar. Na prática, o áudio de aproximadamente 19 segundos de jNQXAC9IVRw foi baixado completamente, Qwen gerou 7 segmentos SRT (Whisper 4); vídeos de teste indisponíveis também verificaram o caminho de verificação de atualização e diagnóstico de falha.
Seleção de modelo, tempo de execução prático e limitações estão em references/model-evaluation.md; leia ao comparar modelos ou reavaliar. Atualmente, o padrão favorece a qualidade de reconhecimento de terminologia chinesa; não se pode afirmar que é superior ao Whisper em todos os idiomas e áudios.
Implementação baseada em: Projeto oficial yutto, Projeto oficial yt-dlp, Projeto oficial Qwen3-ASR, Documentação do modelo Whisper.