O que dsh-bilibili-subtitles faz?

Transforme um link de vídeo do Bilibili em um documento de legenda legível, pesquisável e pronto para entrega.

Princípio central: Primeiro, tente obter legendas prontas. Depois, considere transcrição por voz ou OCR. Não baixe vídeo/áudio para usar Whisper logo de cara; as legendas da plataforma Bilibili (incluindo as geradas por IA) geralmente têm melhor qualidade e são mais rápidas.

Quando usar

Adequado para:

O usuário fornece um link de vídeo do Bilibili, código BV, av, link de episódio/série (ep/ss) ou link curto b23.tv e pede para "extrair legendas / organizar em texto / exportar para Word/Markdown".
O usuário tem um vídeo local com legendas externas e deseja converter em lote para documentos.
O usuário precisa de um roteiro de legenda com timestamps, versão bilíngue ou mesclado por múltiplas partes (multi-P).
O usuário precisa de um relatório de qualidade das legendas para avaliar se vale a pena uma revisão manual.

Não adequado para:

Necessidade de "traduzir" legendas: esta skill apenas faz alinhamento bilíngue, não tradução automática.
Necessidade de separação precisa de falantes: a diarização automática ainda não está implementada; apenas preserva marcações [Falante] existentes nas legendas.
Necessidade de contornar restrições de login/pagamento/região do Bilibili: peça ao usuário que forneça seus próprios cookies válidos ou use arquivos locais.

Instalação e execução

Plugin: https://github.com/Chenfan2/dsh-bilibili-subtitles (no DSH desktop, vá em "Plugins → Adicionar plugin" e cole o endereço, ou use dsh plugin --profile web add github:Chenfan2/dsh-bilibili-subtitles).
Apenas skill: Copie o diretório inteiro para o diretório de skills do DSH (ou execute install.ps1).

Após a instalação, execute no diretório:

python main.py "https://www.bilibili.com/video/BV1xx411c7mD" --format md,docx

Se for uso temporário, também pode executar o main.py diretamente no diretório da skill sem instalação formal.

Um comando

python main.py "https://www.bilibili.com/video/BV1xx411c7mD" --format md,docx

A saída estará em output/:

Titulo_BV.md
Titulo_BV.docx
Titulo_BV.quality.json (relatório de qualidade)
Titulo_BV.segments.json (legendas estruturadas e limpas)
_manifest.json (resumo da execução atual)

Contrato de entrada / saída

Entrada

Tipo	Exemplo
Vídeo do Bilibili	`https://www.bilibili.com/video/BV1xx411c7mD?p=2`
Código BV / av	`BV1xx411c7mD`, `av80433022`
Série/Episódio	`https://www.bilibili.com/bangumi/play/ep123456`, `.../ss28747`
Link curto	`https://b23.tv/xxxxxx`
Vídeo local	`input.mp4`, `input.mkv`
Legenda externa	`--subtitle input.srt` (também suporta `.ass/.vtt/.json/.txt`)
Diretório/lote	`python main.py ./videos --format md,docx`

Saída

Caminhos para arquivos de documento (Markdown/Word/PDF/TXT/SRT).
Legendas estruturadas: [{start, end, text, speaker?, lang?, confidence?, translation?}].
Relatório de qualidade: fonte da legenda, idioma, cobertura, segmentos de baixa confiança, avisos, amostras de início/meio/fim.
Registro de tentativas de processamento: sucesso/falha/pulo de cada provedor com motivo.

Prioridade das fontes de legenda

A tentativa é feita na seguinte ordem, com fallback automático em caso de falha, a menos que desabilitado explicitamente:

Legenda externa do usuário (--subtitle): qualidade máxima, totalmente controlável.
Legendas da plataforma Bilibili / IA: lidas através de x/player/v2, exigem SESSDATA.
Legendas embutidas no vídeo local: ffprobe detecta + ffmpeg extrai para SRT.
OCR de legendas gráficas: apenas para vídeos locais, ativado com --ocr; experimental.
Transcrição por voz Whisper: ativado com --asr ou como fallback automático; baixa o modelo na primeira execução.

Sem login, o Bilibili geralmente não retorna a lista de legendas. Nesse caso, aparecerá LOGIN_REQUIRED com instruções para fornecer Cookie ou ativar ASR. Isso é uma limitação da plataforma, não um erro de link.

Login no Bilibili (necessário para legendas da plataforma)

A API de legendas da plataforma só retorna subtitle_url para sessões logadas. Recomenda-se usar variáveis de ambiente para evitar que apareçam no histórico de comandos:

$env:BILIBILI_SESSDATA = "seu_SESSDATA"
python main.py "https://www.bilibili.com/video/BV1xx411c7mD" --format md,docx

Como obter: Faça login no bilibili.com no navegador → Ferramentas do Desenvolvedor → Application/Aplicativo → Cookies → bilibili.com → Copie o valor de SESSDATA.

Também suporta:

python main.py URL --sessdata "valor_do_SESSDATA"
python main.py URL --cookie "SESSDATA=...; bili_jct=..."
python main.py URL --cookies cookies.txt

Cookies equivalem a credenciais de conta; não os coloque em repositórios, documentos ou canais públicos.
Esta skill usa o Cookie apenas em memória; logs e relatórios são ofuscados.
Quando o Cookie expirar, basta copiar um novo.

Parâmetros comuns

Parâmetro	Função
`--format md,docx,pdf,txt,srt,json`	Formatos de saída, separados por vírgula; padrão `md`
`-o, --output PATH`	Especifica arquivo de saída para entrada única + formato único
`--out-dir DIR`	Diretório de saída, padrão `output`
`--title TEXT`	Sobrescreve o título do documento (padrão: título do vídeo/nome do arquivo)
`--subtitle PATH`	Arquivo ou diretório de legenda externa (maior prioridade)
`--language zh`	Idioma preferido para legenda/transcrição; legendas da plataforma são filtradas por idioma
`--bilingual`	Modo bilíngue; com duas faixas, alinha por tempo; com uma faixa, tenta dividir por linha
`--timestamps` / `--no-timestamps`	Exibe `[00:12]` no texto; padrão: exibe
`--merge-sentences` / `--no-merge-sentences`	Mescla frases curtas cortadas artificialmente; padrão: mescla
`--no-auto-punctuation`	Desativa pontuação automática para ASR/OCR (ativada por padrão)
`--pages auto/all/1,3-5`	Seleção de partes (multi-P); padrão: processa apenas a P do link; se não especificada, P1
`--template default/minimal/arquivo.md`	Modelo Markdown
`--quality-report PATH`	Caminho para relatório de qualidade JSON
`--no-quality`	Não gera relatório de qualidade nem anexa informações de processamento ao documento
`--glossary terms.json`	Substituição de termos, ex.: `{"DeepSeek":"Busca Profunda"}`
`--json-summary`	Saída de resumo legível por máquina no stdout (útil para agentes)
`--asr` / `--no-asr`	Permite/proíbe fallback do Whisper; padrão: automático (tenta apenas se instalado)
`--asr-model small`	`tiny/base/small/medium`; padrão `small`
`--model-dir DIR`	Diretório de cache do modelo Whisper (padrão: `./.vsub-models-cache`)
`--ocr`	Faz OCR de legendas gráficas em vídeos locais (experimental)
`--ffmpeg PATH`	Especifica caminho para ffmpeg/ffprobe
`--strict`	Retorna código de saída não zero se qualquer entrada falhar ou a qualidade for `fail`

Parâmetros completos: python main.py --help.

Fluxo de trabalho recomendado (para agentes)

Determine a entrada:
- Link BV/av do Bilibili → execute diretamente.
- Vídeo local → verifique arquivos .srt/.vtt/.ass com o mesmo nome; se existirem, use --subtitle; caso contrário, tente legendas embutidas.
- Apenas arquivo de legenda → também pode ser usado como entrada.
Execute primeiro com a saída padrão; não ative ASR sem antes verificar o relatório de qualidade:
```
python main.py "<link>" --format md,docx --out-dir output
```
Se aparecer LOGIN_REQUIRED:
- Informe ao usuário que as legendas da plataforma exigem SESSDATA e forneça as instruções de configuração; não refaça a tentativa repetidamente.
- Se o usuário não tiver Cookie, então sugira --asr (explique que baixará o modelo, levará tempo e pode gerar erros de reconhecimento).
Verifique <stem>.quality.json:
- status=ok: entregue diretamente.
- status=warn: analise os warnings, especialmente cobertura, sobreposições, baixa confiança; alerte na entrega.
- status=fail: não finja sucesso; relate a causa da falha e sugira legenda externa/ASR/OCR.
Use present para entregar o .md / .docx como arquivo final; o relatório de qualidade só deve ser anexado se o usuário solicitar.

Ambiente de execução:

Prefira usar o Python retornado por load_workspace_dependencies (que já inclui python-docx).

Exemplo de chamada no Windows PowerShell:

& "C:\...\python.exe" main.py "<link>" --format md,docx --out-dir output

Todos os arquivos de saída e temporários devem ficar dentro da área de trabalho da sessão; não use diretórios temporários do sistema (podem ser rejeitados pelo sandbox).

Campos do relatório de qualidade

{
  "status": "ok | warn | fail",
  "score": 96.5,
  "source": "bilibili",
  "language": "zh",
  "segments": 320,
  "paragraphs": 86,
  "duration": 1260.0,
  "duration_covered": 0.96,
  "coverage_span": 0.99,
  "overlaps": 0,
  "low_confidence_segments": 3,
  "duplicate_segments": 1,
  "gaps_over_10s": 2,
  "warnings": ["..."],
  "samples": {"head": [], "middle": [], "tail": []}
}

duration_covered: em relação à duração total do vídeo; anúncios de abertura/fechamento removidos podem reduzir esse valor.
coverage_span: em relação ao intervalo entre a primeira e a última legenda; reflete melhor se "a parte falada está coberta".
samples: até 5 segmentos do início, meio e fim, para inspeção manual.
Causas comuns de status=fail: nenhum segmento, cobertura abaixo de 30%, falha em todas as partes.

Falhas e fallback

Situação	Comportamento
Falha ao processar legenda externa	Registra falha, continua com legendas da plataforma/embutidas
Legenda da plataforma `LOGIN_REQUIRED`	Instrui a definir `SESSDATA`; se faster-whisper estiver instalado e ASR permitido, faz transcrição automática
Plataforma sem faixa de legenda	Notifica `NO_SUBTITLE`; pode usar `--asr` ou `--subtitle`
Legenda embutida é bitmap PGS/VobSub	Não é possível converter para SRT diretamente; sugere usar OCR ou legenda externa
ASR não instalado	Pula e sugere `pip install faster-whisper`; não falha silenciosamente
Falha em um formato de saída	Outros formatos continuam sendo gerados; registrado em `quality.warnings`; apenas `RENDER_FAILED` se todos falharem
Falha parcial em lote	Processamento bem-sucedido continua; falhas registradas em `_manifest.json` e `*.error.json`

Códigos de saída:

0 Sucesso (em lote, significa que pelo menos um teve sucesso)
2 Erro de entrada/link/API/análise
3 Nenhuma legenda, login necessário, falha de qualidade
4 Dependência ausente (ffmpeg/Whisper/docx etc.)
5 Falha na renderização do documento
1 Erro inesperado

Exemplos

# Básico: legenda da plataforma → Markdown + Word
python main.py "https://www.bilibili.com/video/BV1xx411c7mD" --format md,docx

# Apenas Word, com nome de arquivo específico
python main.py "BV1xx411c7mD" --format docx -o "Notas_de_artigo.docx"

# Múltiplas partes + timestamps + relatório de qualidade
python main.py "https://www.bilibili.com/video/BV1xx411c7mD?p=1" --pages all --format md

# Legenda externa prioritária
python main.py "input.mp4" --subtitle "input.srt" --format md,docx

# Bilíngue (quando a plataforma tem duas faixas, alinha automaticamente)
python main.py "BV1xx411c7mD" --bilingual --language zh --format md,docx

# Sem login, com fallback ASR (primeira execução baixa o modelo)
python main.py "BV1xx411c7mD" --asr --asr-model small --format md,docx

# Lote de diretório
python main.py "./videos" --format md,docx --out-dir output/lote

# OCR de legenda gráfica local (experimental)
python main.py "input.mp4" --ocr --ocr-fps 2 --format md

Limitações

A disponibilidade de legendas da plataforma depende do vídeo, da conta, da região e das configurações do UP; esta skill não pode contornar permissões.
As legendas geradas por IA podem conter erros de digitação, falhas de segmentação e desvios de sincronia; o relatório de qualidade apenas alerta, não substitui a revisão humana.
O modo bilíngue é "alinhamento temporal", não tradução; só apresenta contraste quando as duas faixas estão em idiomas diferentes.
A separação automática de falantes não foi implementada; apenas analisa marcações como [João], 【João】, João:.
OCR é apenas para vídeos locais, com área padrão de 30% inferior; para animações, vídeos verticais ou legendas com posição variável, ajuste com --ocr-crop ou --ocr-full-frame.
PDF requer LibreOffice ou reportlab; caso contrário, um erro explícito será gerado, mas não afeta md/docx.
ASR para vídeos longos pode ser lento; o modelo small tem cerca de 460MB no primeiro download.

Direitos autorais e privacidade

Processe apenas vídeos/legendas que o usuário tenha direito de usar; não utilize esta skill para baixar em massa conteúdo protegido por direitos autorais.
Os documentos de legenda manterão o título original do vídeo, o nome do UP e o link para rastreabilidade.
Cookies e URLs CDN com assinatura não serão gravados em logs/relatórios de qualidade; ainda assim, recomenda-se que o usuário não cole Cookies em locais públicos.
Arquivos temporários de áudio/quadros ficam em .vsub-tmp no diretório de saída e são limpos automaticamente ao final; use --keep-temp para mantê-los para depuração.

Estrutura de arquivos

dsh-bilibili-subtitles/
├── SKILL.md
├── README.md
├── main.py                  # Ponto de entrada CLI
├── vsub/
│   ├── bilibili.py          # URL/API/legenda/áudio
│   ├── input_adapter.py     # Adaptador de entrada
│   ├── pipeline.py          # Orquestração de 5 camadas
│   ├── providers/           # external/bilibili/embedded/ocr/asr
│   ├── parsers/             # srt/vtt/ass/bilibili-json/plain
│   ├── cleaners/            # Limpeza, mesclagem, bilíngue, glossário
│   ├── renderers/           # md/docx/pdf/txt/srt/json
│   └── quality.py           # Validação de qualidade
├── templates/
├── tests/
└── requirements.txt

dsh-bilibili-subtitles

O que é dsh-bilibili-subtitles?

Perguntar na sua IA favorita

Documentação