Que fait dsh-bilibili-subtitles ?

Transformez un lien vidéo Bilibili en un document de sous‑titres lisible, consultable et livrable.

Principe fondamental : utiliser d'abord les sous‑titres existants, puis envisager la transcription vocale ou l'OCR. Ne téléchargez pas la vidéo/l'audio pour Whisper dès le départ ; les sous‑titres de la plateforme B (y compris les sous‑titres IA) sont généralement de meilleure qualité et plus rapides.

Quand l'utiliser

Adapté :

L'utilisateur fournit un lien vidéo Bilibili, un code BV, un code av, un lien d'épisode/série (ep/ss) ou un lien court b23.tv, et demande "extraire les sous‑titres / mettre en forme un document / exporter en Word/Markdown".
L'utilisateur a une vidéo locale avec des sous‑titres externes et souhaite les convertir en série de documents.
L'utilisateur a besoin de sous‑titres avec timestamps, en version bilingue, ou fusionnés entre plusieurs parties (P).
L'utilisateur a besoin d'un rapport de qualité des sous‑titres pour décider si une relecture humaine est nécessaire.

Non adapté :

Traduction des sous‑titres : cette compétence se limite à l'alignement bilingue, pas à la traduction automatique.
Séparation précise des locuteurs : la diarisation automatique n'est pas activée ; seules les mentions [Parleur] déjà présentes dans les sous‑titres sont conservées.
Contournement des restrictions de connexion/paiement/région de Bilibili : l'utilisateur doit fournir un cookie pour lequel il a les droits, ou utiliser son fichier local.

Installation et appel

Plugin : https://github.com/Chenfan2/dsh-bilibili-subtitles (dans l'interface DSH, ajouter l'URL du plugin, ou dsh plugin --profile web add github:Chenfan2/dsh-bilibili-subtitles).
Skill uniquement : copiez tout le dossier dans le répertoire skills de DSH (ou exécutez install.ps1).

Après installation, depuis le répertoire :

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

Pour un usage ponctuel, vous pouvez aussi exécuter main.py directement depuis le dossier skill sans installation.

Une seule commande

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

Sortie dans output/ :

Titre_BV.md
Titre_BV.docx
Titre_BV.quality.json (rapport de qualité)
Titre_BV.segments.json (sous‑titres structurés nettoyés)
_manifest.json (récapitulatif de la session)

Contrat d'entrée / sortie

Entrée

Type	Exemple
Vidéo Bilibili	`https://www.bilibili.com/video/BV1xx411c7mD?p=2`
Code BV / av	`BV1xx411c7mD`, `av80433022`
Série	`https://www.bilibili.com/bangumi/play/ep123456`, `.../ss28747`
Lien court	`https://b23.tv/xxxxxx`
Vidéo locale	`input.mp4`, `input.mkv`
Sous‑titres externes	`--subtitle input.srt` (supporte aussi `.ass/.vtt/.json/.txt`)
Dossier / lot	`python main.py ./videos --format md,docx`

Sortie

Chemin du fichier document (Markdown/Word/PDF/TXT/SRT).
Sous‑titres structurés : [{start, end, text, speaker?, lang?, confidence?, translation?}].
Rapport de qualité : source des sous‑titres, langue, couverture, segments à faible confiance, avertissements, échantillons début/milieu/fin.
Journal des tentatives de traitement : succès/échec/ignoré par provider, avec raison.

Priorité des sources de sous‑titres

Les tentatives se font dans l'ordre suivant ; en cas d'échec, la tâche descend automatiquement d'un niveau, sauf si explicitement désactivé :

Sous‑titres externes de l'utilisateur (--subtitle) : qualité maximale, contrôle total.
Sous‑titres plateforme Bilibili / sous‑titres IA : via l'API x/player/v2, nécessite SESSDATA.
Sous‑titres intégrés à la vidéo locale : détection par ffprobe + extraction par ffmpeg en SRT.
OCR des sous‑titres incrustés (hardcoded) : vidéo locale uniquement, avec --ocr ; expérimental.
Transcription vocale Whisper : avec --asr ou en dernier recours automatique ; le modèle est téléchargé lors du premier appel.

Sans connexion, Bilibili ne renvoie généralement pas de liste de sous‑titres. Un message LOGIN_REQUIRED s'affiche, avec une invite à fournir un cookie ou à activer l'ASR. C'est une limitation de la plateforme, pas une erreur de lien.

Connexion Bilibili (nécessaire pour les sous‑titres plateforme)

L'API des sous‑titres plateforme ne renvoie subtitle_url que pour les sessions connectées. Il est recommandé d'utiliser une variable d'environnement pour éviter que le cookie apparaisse dans l'historique des commandes :

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

Obtenez SESSDATA : connectez-vous à bilibili.com dans le navigateur → Outils développeur → Application → Cookies → bilibili.com → copiez la valeur de SESSDATA.

Alternatives :

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

Le cookie est équivalent à un identifiant de compte ; ne l'intégrez pas dans un dépôt, un document ou un canal public.
Cette compétence n'utilise le cookie qu'en mémoire ; il est masqué dans les logs et rapports.
Renouvelez le cookie après son expiration.

Paramètres courants

Paramètre	Rôle
`--format md,docx,pdf,txt,srt,json`	Formats de sortie, séparés par des virgules ; défaut `md`
`-o, --output PATH`	Pour une seule entrée et un seul format, spécifie le fichier de sortie
`--out-dir DIR`	Répertoire de sortie ; défaut `output`
`--title TEXT`	Remplace le titre du document (par défaut, titre de la vidéo/nom du fichier)
`--subtitle PATH`	Fichier ou dossier de sous‑titres externes (priorité maximale)
`--language zh`	Langue préférée pour les sous‑titres/la transcription ; les sous‑titres plateforme sont filtrés par langue
`--bilingual`	Version bilingue ; si deux pistes sont disponibles, alignement temporel ; sinon, tentative de séparation par ligne
`--timestamps` / `--no-timestamps`	Affiche ou non `[00:12]` dans le corps ; affiché par défaut
`--merge-sentences` / `--no-merge-sentences`	Fusionne ou non les phrases courtes coupées arbitrairement ; fusion par défaut
`--no-auto-punctuation`	Désactive l'ajout automatique de ponctuation pour ASR/OCR (activé par défaut)
`--pages auto/all/1,3-5`	Sélection des parties (P) ; par défaut, traite uniquement la P spécifiée dans le lien, sinon P1
`--template default/minimal/fichier.md`	Modèle Markdown
`--quality-report PATH`	Chemin du rapport de qualité JSON
`--no-quality`	Ne génère pas de rapport de qualité et n'ajoute pas d'informations de traitement au document
`--glossary terms.json`	Remplacement de termes, ex. `{"DeepSeek":"深度求索"}`
`--json-summary`	Affiche un résumé lisible par machine sur stdout (pour lecture par agent)
`--asr` / `--no-asr`	Autorise/interdit le recours à Whisper ; défaut automatique (tentative uniquement si installé)
`--asr-model small`	`tiny/base/small/medium` ; défaut `small`
`--model-dir DIR`	Répertoire de cache du modèle Whisper (défaut `./.vsub-models-cache`)
`--ocr`	Active l'OCR des sous‑titres incrustés pour les vidéos locales (expérimental)
`--ffmpeg PATH`	Spécifie le chemin de ffmpeg/ffprobe
`--strict`	Renvoie un code de sortie non nul si une entrée échoue ou si la qualité est `fail`

Paramètres complets : python main.py --help.

Workflow recommandé (agent)

Évaluez l'entrée :
- Lien Bilibili/BV/av → exécution directe.
- Vidéo locale → vérifiez la présence d'un fichier .srt/.vtt/.ass de même nom, et utilisez --subtitle si trouvé ; sinon, tentez les sous‑titres intégrés.
- Fichier de sous‑titres seul → peut aussi être utilisé comme entrée.
Exécutez d'abord la sortie par défaut, sans activer l'ASR avant d'avoir consulté le rapport de qualité :
```
python main.py "<lien>" --format md,docx --out-dir output
```
En cas d'erreur LOGIN_REQUIRED :
- Informez l'utilisateur que les sous‑titres plateforme nécessitent SESSDATA, et expliquez comment le configurer ; ne réessayez pas inutilement.
- Si l'utilisateur n'a pas de cookie, suggérez --asr (en précisant que le modèle sera téléchargé la première fois, que c'est plus long et que des erreurs de reconnaissance sont possibles).
Vérifiez <stem>.quality.json :
- status=ok → livrez directement.
- status=warn → examinez warnings, notamment couverture, chevauchements, faible confiance ; mentionnez‑les dans la note de livraison.
- status=fail → n'agissez pas comme si c'était un succès ; rapportez la cause de l'échec et suggérez des sous‑titres externes/ASR/OCR.
Utilisez present pour livrer le fichier .md / .docx comme fichier final ; le rapport de qualité n'est joint que si l'utilisateur le demande.

Environnement d'exécution :

Utilisez de préférence le Python retourné par load_workspace_dependencies (livré avec python-docx).

Exemple d'appel sous Windows PowerShell :

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

Toutes les sorties et fichiers temporaires doivent être placés dans le répertoire de travail de la session ; n'utilisez pas le répertoire temporaire système (potentiellement refusé par le bac à sable).

Champs du rapport de qualité

{
  "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 : par rapport à la durée totale de la vidéo ; peut être plus bas après nettoyage des publicités d'en‑tête/de fin.
coverage_span : par rapport à l'intervalle entre le premier et le dernier sous‑titre ; reflète mieux si les parties parlées sont couvertes.
samples : jusqu'à 5 segments en début, milieu et fin, pour un contrôle manuel rapide.
Causes fréquentes de status=fail : aucun segment, couverture inférieure à 30%, échec de toutes les parties.

Échecs et rétrogradations

Situation	Comportement
Échec d'analyse des sous‑titres externes	Enregistre l'échec, continue avec les sous‑titres plateforme/intégrés
Sous‑titres plateforme `LOGIN_REQUIRED`	Demande de définir `SESSDATA` ; si faster‑whisper est installé et que l'ASR est autorisé, transcription automatique
Pas de piste de sous‑titres sur la plateforme	Indique `NO_SUBTITLE` ; possibilité d'utiliser `--asr` ou `--subtitle`
Sous‑titres intégrés au format bitmap PGS/VobSub	Impossible de convertir directement en SRT ; suggère d'utiliser OCR ou des sous‑titres externes
ASR non installé	Saute l'étape et affiche `pip install faster-whisper` ; ne reste pas silencieux
Échec d'un format de sortie	Les autres formats sont générés ; enregistré dans `quality.warnings` ; seul un échec total déclenche `RENDER_FAILED`
Échec partiel dans un lot	Les réussites continuent ; `_manifest.json` et `*.error.json` enregistrent les échecs

Codes de sortie :

0 succès (en lot : au moins un succès)
2 erreur d'entrée/lien/API/analyse
3 pas de sous‑titres, connexion requise, échec qualité
4 dépendance manquante (ffmpeg/Whisper/docx, etc.)
5 échec du rendu du document
1 erreur inattendue

Exemples

# Basique : sous‑titres plateforme → Markdown + Word
python main.py "https://www.bilibili.com/video/BV1xx411c7mD" --format md,docx

# Word uniquement, nom de fichier personnalisé
python main.py "BV1xx411c7mD" --format docx -o "notes_papier.docx"

# Plusieurs parties + timestamps + rapport de qualité
python main.py "https://www.bilibili.com/video/BV1xx411c7mD?p=1" --pages all --format md

# Sous‑titres externes prioritaires
python main.py "input.mp4" --subtitle "input.srt" --format md,docx

# Bilingue (alignement automatique si deux pistes sur la plateforme)
python main.py "BV1xx411c7mD" --bilingual --language zh --format md,docx

# Sans connexion, avec ASR en dernier recours (premier téléchargement du modèle)
python main.py "BV1xx411c7mD" --asr --asr-model small --format md,docx

# Traitement par dossier
python main.py "./videos" --format md,docx --out-dir output/batch

# OCR de sous‑titres incrustés locaux (expérimental)
python main.py "input.mp4" --ocr --ocr-fps 2 --format md

Limites

La disponibilité des sous‑titres plateforme dépend de la vidéo, du compte, de la région et des paramètres du créateur ; cette compétence ne peut pas contourner les autorisations.
Les sous‑titres IA peuvent contenir des erreurs de caractères, des phrases manquantes ou un décalage temporel ; le rapport de qualité ne fait que signaler, il ne remplace pas une relecture humaine.
Le mode bilingue est un "alignement temporel", pas une traduction ; l'affichage bilingue n'a lieu que si les deux pistes sont dans des langues différentes.
La séparation automatique des locuteurs n'est pas implémentée ; seules les balises du type [张三], 【张三】, 张三： présentes dans les sous‑titres sont analysées.
L'OCR ne fonctionne que sur les vidéos locales, par défaut dans les 30% inférieurs de l'image ; pour les animations, vidéos verticales ou sous‑titres déplacés, ajustez --ocr-crop ou --ocr-full-frame.
Le PDF nécessite LibreOffice ou reportlab ; en cas d'absence, une erreur explicite est levée, sans affecter le MD/DOCX.
L'ASR sur de longues vidéos peut être lent ; le modèle small fait environ 460 Mo lors du premier téléchargement.

Copyright et confidentialité

Ne traitez que des vidéos/sous‑titres pour lesquels l'utilisateur a les droits ; n'utilisez pas cette compétence pour aspirer massivement du contenu protégé par des droits d'auteur.
Le document de sous‑titres conserve le titre de la vidéo, le nom du créateur et le lien, pour faciliter la traçabilité.
Le cookie et les URL CDN signées ne sont jamais écrits dans les logs ou le rapport de qualité ; il est néanmoins conseillé de ne pas coller de cookie dans un espace public.
Les fichiers audio/images temporaires sont stockés dans .vsub-tmp sous le répertoire de sortie, et sont automatiquement nettoyés en fin d'exécution ; utilisez --keep-temp pour les conserver en cas de débogage.

Structure des fichiers

dsh-bilibili-subtitles/
├── SKILL.md
├── README.md
├── main.py                  # Point d'entrée CLI
├── vsub/
│   ├── bilibili.py          # URL/API/sous‑titres/audio
│   ├── input_adapter.py     # Adaptateur d'entrée
│   ├── pipeline.py          # Orchestration des 5 niveaux
│   ├── providers/           # external/bilibili/embedded/ocr/asr
│   ├── parsers/             # srt/vtt/ass/bilibili-json/plain
│   ├── cleaners/            # Nettoyage, fusion, bilingue, glossaire
│   ├── renderers/           # md/docx/pdf/txt/srt/json
│   └── quality.py           # Validation de qualité
├── templates/
├── tests/
└── requirements.txt

dsh-bilibili-subtitles

Qu'est-ce que dsh-bilibili-subtitles ?

Demander à votre IA préférée

Documentation