Coupe vidéo v3
Transcription Volcengine + Détection AI des erreurs + Révision web + retranscription post-coupe + Correction AI des sous-titres
Utilisation rapide
Utilisateur: Coupe-moi cette vidéo face caméra
Utilisateur: Traite cette vidéo
Utilisateur: Fais-en un pack de base
Ne plus décomposer la génération de sous-titres en skill séparé. Coupe vidéo est le point d'entrée unique pour le pack de base.
Après avoir reçu un rush vidéo, ce skill produit par défaut le pack de base directement utilisable par l'étape Production finale :
source_cut.mp4 # Vidéo face caméra coupée
subtitles.srt # Sous-titres retranscrits et corrigés par AI après coupe
assets/ # Captures d'écran, images de commentaires, page de résultats (optionnel)
La page de révision sert uniquement à faire valider "quoi couper" et à créer la nouvelle vidéo. Les sous-titres ne doivent pas être réutilisés de la vidéo originale, et la transcription brute de Volcengine ne doit pas devenir le sous-titre final ; l'Agent doit retranscrire depuis la vidéo coupée et appliquer une correction AI avant d'écrire subtitles.srt.
Structure du répertoire de sortie
output/
└── JJ-MM-AAAA_NomDeLaVideo/
├── coupe_video/
│ ├── 1_transcription/
│ │ ├── audio.mp3
│ │ ├── volcengine_result.json
│ │ └── subtitles_words.json
│ ├── 2_analyse/
│ │ ├── readable.txt
│ │ ├── auto_selected.json
│ │ └── analyse_erreurs.md
│ └── 3_revision/
│ ├── review.html
│ └── video.mp4 → vidéo source (lien symbolique)
└── sous_titres/
├── 1_transcription/
│ ├── audio.mp3
│ └── volcengine_result.json
├── subtitles_with_time.json
└── 3_sortie/
├── video.raw.srt
└── video.srt
Règle : Si le dossier existe, le réutiliser ; sinon, le créer.
Flux de travail
0. Créer les répertoires de sortie
↓
1. Extraire l'audio (ffmpeg)
↓
2. Appeler Volcengine ASR 2.0 (Seed ASR v3)
↓
3. Générer volcengine_result.json
↓
4. Générer les sous-titres au niveau mot (subtitles_words.json)
↓
5. AI analyse les erreurs/silences, génère une liste de présélection (auto_selected.json)
↓
6. Générer la page web de révision (review.html)
↓
7. Démarrer le serveur de révision, l'utilisateur confirme via le navigateur
↓
[Attente validation utilisateur] → Clic sur « Exécuter le montage »
↓
8. Le serveur génère la nouvelle vidéo coupée
↓
9. L'Agent détecte la fin de la génération de la vidéo coupée
↓
10. Retranscrire depuis la vidéo coupée, envoyer à Volcengine, générer video.raw.srt
↓
11. L'Agent corrige les sous-titres par AI en se référant au script original, écrit video.srt
↓
12. Assembler le pack de base : source_cut.mp4 + subtitles.srt + assets/ (optionnel)
Règles strictes pour les sous-titres post-coupe :
- Doivent être retranscrits depuis la vidéo coupée, pas déduits des sous-titres originaux.
- La transcription Volcengine est une ébauche, exportée dans
video.raw.srt. video.srt/subtitles.srtne peuvent contenir que les sous-titres finaux corrigés par l'Agent AI.- La correction se fait en se référant au script, au texte, aux noms propres et au contexte fournis par l'utilisateur, en corrigeant la terminologie, les homophones mal reconnus, et la ponctuation ; ne pas ajouter de paroles qui ne sont pas dans la vidéo.
Étapes d'exécution
Étape 0 : Créer les répertoires de sortie
# Définir les variables (ajuster selon la vidéo)
VIDEO_PATH="/chemin/vers/video.mp4"
VIDEO_NAME=$(basename "$VIDEO_PATH" .mp4)
DATE=$(date +%Y-%m-%d)
BASE_DIR="output/${DATE}_${VIDEO_NAME}/coupe_video"
# Créer les sous-répertoires
mkdir -p "$BASE_DIR/1_transcription" "$BASE_DIR/2_analyse" "$BASE_DIR/3_revision"
cd "$BASE_DIR"
Étapes 1-3 : Transcription
cd 1_transcription
# 1. Extraire l'audio (si le nom du fichier contient ':', ajouter le préfixe file:)
ffmpeg -i "file:$VIDEO_PATH" -vn -acodec libmp3lame -y audio.mp3
# 2. Appeler Volcengine ASR 2.0 (resource_id par défaut = volc.seedasr.auc)
SKILL_DIR="/Volumes/成峰/代码/剪辑Agent/.claude/skills/coupe_video"
"$SKILL_DIR/scripts/volcengine_transcribe.sh" audio.mp3
# Sortie : volcengine_result.json
Le script de transcription utilise par défaut Volcengine Seed ASR v3 2.0 :
POST /api/v3/auc/bigmodel/submit
POST /api/v3/auc/bigmodel/query
X-Api-Resource-Id: volc.seedasr.auc
Pour un basculement temporaire ou une comparaison avec d'autres ressources, utiliser une variable d'environnement :
VOLCENGINE_ASR_RESOURCE_ID=volc.bigasr.auc "$SKILL_DIR/scripts/volcengine_transcribe.sh" audio.mp3
Étape 4 : Générer la timeline au niveau mot
node "$SKILL_DIR/scripts/generate_subtitles.js" volcengine_result.json
# Sortie : subtitles_words.json
cd ..
Règles de timestamp :
generate_subtitles.jsdoit être compatible avecresult.utterances(v3) et l'ancienutterances.- Les jetons avec timestamp invalide dans le résultat v3 (souvent des espaces,
start_time/end_time = -1) doivent être filtrés, sinon ils créent de faux silences. - Évaluation sur un échantillon de 180 secondes au 25/06/2026 : Seed ASR 2.0 a un décalage médian de la limite mot par mot d'environ 80 ms par rapport à la fenêtre temporelle de sous-titres de référence, P90 d'environ 240 ms, max d'environ 620 ms ; peut être utilisé comme timeline de coupe par défaut, mais les longues phrases doivent être redécoupées en lignes de sous-titres en se basant sur les timestamps mot par mot.
Étape 5 : Analyser les erreurs d'élocution (script + AI)
5.1 Générer un format lisible
cd 2_analyse
node -e "
const data = require('../1_transcription/subtitles_words.json');
let output = [];
data.forEach((w, i) => {
if (w.isGap) {
const dur = (w.end - w.start).toFixed(2);
if (dur >= 0.2) output.push(i + '|[Sil' + dur + 's]|' + w.start.toFixed(2) + '-' + w.end.toFixed(2));
} else {
output.push(i + '|' + w.text + '|' + w.start.toFixed(2) + '-' + w.end.toFixed(2));
}
});
require('fs').writeFileSync('readable.txt', output.join('\n'));
"
5.2 Lire les habitudes utilisateur
Lire d'abord tous les fichiers de règles dans le répertoire habitudes_utilisateur/.
5.3 Générer une liste de phrases (étape clé)
D'abord segmenter en phrases, puis analyser. Découper en liste de phrases basée sur les silences :
node -e "
const data = require('../1_transcription/subtitles_words.json');
let sentences = [];
let curr = { text: '', startIdx: -1, endIdx: -1 };
data.forEach((w, i) => {
const isLongGap = w.isGap && (w.end - w.start) >= 0.5;
if (isLongGap) {
if (curr.text.length > 0) sentences.push({...curr});
curr = { text: '', startIdx: -1, endIdx: -1 };
} else if (!w.isGap) {
if (curr.startIdx === -1) curr.startIdx = i;
curr.text += w.text;
curr.endIdx = i;
}
});
if (curr.text.length > 0) sentences.push(curr);
sentences.forEach((s, i) => {
console.log(i + '|' + s.startIdx + '-' + s.endIdx + '|' + s.text);
});
" > sentences.txt
5.4 Marquage automatique des silences (doit être exécuté en premier)
node -e "
const words = require('../1_transcription/subtitles_words.json');
const selected = [];
words.forEach((w, i) => {
if (w.isGap && (w.end - w.start) >= 0.2) selected.push(i);
});
require('fs').writeFileSync('auto_selected.json', JSON.stringify(selected, null, 2));
console.log('Nombre de silences ≥0.2s :', selected.length);
"
→ Sortie : auto_selected.json (contient uniquement les idx des silences)
5.4b Taille début/fin (zone aveugle de transcription, obligatoire)
🚨 Volcengine ne transcrit que la parole, les bruits non transcrits / actions de fin ne sont pas dans les sous-titres, tous les détecteurs ne les voient pas. Il faut les ajouter en comparant la durée vidéo. Voir
habitudes_utilisateur/3-gestion_silences.md.
VDUR=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "file:$VIDEO_PATH")
node -e "
const fs=require('fs');
const w=require('../1_transcription/subtitles_words.json');
const auto=require('./auto_selected.json');
const VDUR=$VDUR, last=w[w.length-1];
if(VDUR - last.end > 0.3){ // fin non couverte → ajouter élément de fin et présélectionner
w.push({text:'',start:last.end,end:VDUR,isGap:true,reason:'fin non transcrite (bruit/action)'});
auto.push(w.length-1);
fs.writeFileSync('../1_transcription/subtitles_words.json',JSON.stringify(w));
fs.writeFileSync('./auto_selected.json',JSON.stringify([...new Set(auto)].sort((a,b)=>a-b),null,1));
console.log('Ajout élément de fin idx',w.length-1,'['+last.end+'→'+VDUR+']');
} else console.log('Fin déjà couverte');
if(w[0].start>0.3) console.log('⚠️ Début',w[0].start,'s non couvert, envisager d\'ajouter un élément de début');
"
5.5 Analyse AI des erreurs d'élocution (à ajouter à auto_selected.json)
🚨 Principe fondamental : supprimer la version antérieure, conserver la version postérieure. Pour toutes les répétitions / erreurs, supprimer la première occurrence, conserver la suivante.
Répartition par type de détection, exécution parallèle de plusieurs Agents :
Chaque Agent est responsable d'un seul type de détection, son prompt est plus court et plus précis, évitant les interférences entre règles.
| Agent | Entrée | Contenu détecté | Portée de suppression |
|---|---|---|---|
| A-Répétition entre phrases | sentences.txt | Phrases adjacentes / avec un écart d'une phrase ayant ≥5 caractères identiques au début | Supprimer la phrase précédente entière |
| B-Répétition interne à une phrase | sentences.txt | Motif A+intermédiaire+A dans la même phrase | Supprimer uniquement le segment précédent, pas la phrase entière |
| C-Phrase incomplète | sentences.txt | Parole interrompue + silence + reprise | Supprimer la phrase incomplète entière |
Peut être traité directement par script (pas besoin d'AI) :
- Mots de remplissage (ça ça, donc donc) → correspondance regex
- Interjections (euh, ah, eh) → marquer pour confirmation humaine
Révision (verify) – déployer selon le risque, ne pas tout couvrir (voir habitudes_utilisateur/10-stratification_risque_suppression.md) :
- Risque faible, pas de révision : silences, répétitions de sous-ensemble mot à mot (suppression du début mot à mot du contenu conservé, p. ex. supprimer « je répète la même » et garder « je répète la même phrase »), ≤3 caractères de blocage / interjection → ajouter directement à auto_selected, la vérification humaine sur la page web sert de filet de sécurité.
- Risque élevé, révision obligatoire : suppression de phrase entière, "début s'oppose à fin différente" (p. ex. « dépasse le budget » vs « dépasse la capacité de planification »), répétition de longs segments → envoyer à un relecteur contradictoire, vérifier que le contenu unique n'a pas été supprimé.
- Leçon : nous avions auparavant déployé une révision 2x sur toutes les candidates, le taux de succès n'était que de ~4/91 et tous les cas réussis étaient dans la catégorie à haut risque (voir
log/). Verify est coûteux, il faut l'utiliser là où des erreurs peuvent se produire.
Modèle de prompt Agent :
Le prompt pour chaque Agent contient :
1. Seulement la règle de détection correspondante pour cet Agent (lue depuis habitudes_utilisateur/)
2. Le contenu complet de sentences.txt
3. Exiger explicitement : retourner une liste de plages d'idx à supprimer
4. 🚨 Insister sur "supprimer la version antérieure, conserver la version postérieure" : supprimer la version précédente, conserver la version plus complète suivante
Format de retour Agent :
| Numéro de phrase | Plage d'idx | Type | Résumé du contenu | Action |
|-----------------|--------------|------|--------------------|--------|
Liste des idx à supprimer : [tous les idx à supprimer]
Fusion des résultats :
Collecter toutes les listes d'idx retournées par les Agents → les fusionner dans auto_selected.json → dédoublonner et trier
Règle de suppression par plage entière : Lors du marquage des erreurs, tous les éléments entre startIdx et endIdx (y compris les gaps intermédiaires) sont ajoutés à auto_selected. Ne pas sélectionner individuellement les idx de mots pour sauter les gaps.
🚨 Avertissement clé : numéro de ligne ≠ idx
Format readable.txt : idx|contenu|temps
↑ utiliser cette valeur
Ligne 1500 → "1568|[Sil1.02s]|..." ← idx = 1568, pas 1500 !
Format analyse_erreurs.md :
## Répétition entre phrases (Agent A)
| Numéro de phrase | Plage d'idx | Résumé du contenu | Action |
|-----------------|--------------|--------------------|--------|
| 5 | 212-233 | Répétée avec phrase 6, phrase 6 plus complète | Supprimer phrase précédente |
## Répétition interne à une phrase (Agent B)
| Numéro de phrase | Plage d'idx | Résumé du contenu | Action |
|-----------------|--------------|--------------------|--------|
| 16 | 492-510 | "Beaucoup de gens, quand ils pensent aux commandes CLI" moitié avant répétée | Supprimer le segment |
## Phrase incomplète (Agent C)
| Numéro de phrase | Plage d'idx | Résumé du contenu | Action |
|-----------------|--------------|--------------------|--------|
| 7 | 266-275 | "Pour expliquer pour répondre à cela" inachevée | Supprimer la phrase entière |
5.6 Alignement du script pour combler les lacunes (si un script est fourni)
Si l'utilisateur fournit un script / texte original (la vidéo est lue à partir d'un script), l'utiliser pour un alignement au niveau phrase pour combler les lacunes — voir habitudes_utilisateur/11-alignement_script.md.
Le script = vérité terrain sémantique (le libellé peut varier, p. ex. « deux modèles » ↔ « deux grands modèles », ne pas faire un diff mot à mot). Aligner chaque phrase transcrite à la phrase du script, pour détecter les erreurs d'élocution de phrase entière manquées par la détection de texte pur : répétition de phrase entière, phrase incomplète, ou erreur sans correspondance — en particulier le blocage sur les noms techniques (Mindverse / δ-mem / LoRA mal prononcé et repris, "Delta Mam", mot isolé "à"). Ce type de suppression de phrase entière est à haut risque → passer par la révision, confirmer que la version conservée couvre le sens du script original.
Étapes 6-7 : Révision
cd ../3_revision
# 6. Générer la page web de révision (passer le fichier vidéo, crée automatiquement un lien symbolique)
node "$SKILL_DIR/scripts/generate_review.js" ../1_transcription/subtitles_words.json ../2_analyse/auto_selected.json "$VIDEO_PATH"
# Sortie : review.html, video.mp4 (lien symbolique)
# 7. Démarrer le serveur de révision
node "$SKILL_DIR/scripts/review_server.js" 8899 "$VIDEO_PATH"
# Ouvrir http://localhost:8899
⚠️ Doit utiliser review_server.js, ne pas remplacer par
python3 -m http.server. Raison : La lecture vidéo dépend des requêtes HTTP Range (206), que le serveur simple de Python ne prend pas en charge, ce qui empêcherait la lecture vidéo / le son. L'utilisateur lambda peut laisser cette fenêtre de terminal ouverte ; Claude Code / Codex utilisent la capacité de tâche en arrière-plan disponible dans l'environnement actuel. Ne pas demander d'installer tmux.
L'utilisateur sur la page web :
- Lit la vidéo pour confirmer
- Coche/décoche les éléments à supprimer
- Clic gauche maintenu en glissant sur le texte pour marquer/supprimer en masse, prend en charge le glissement sur plusieurs lignes ; si on glisse trop loin, on peut revenir en arrière en tirant, la sélection se rétrécit en temps réel
- Clique sur « Exécuter le montage »
Étape 8 : Surveiller la vidéo coupée
Après le clic de l'utilisateur sur le bouton de la page de révision, review_server.js ne fait que créer la vidéo coupée et écrit cut_done.json dans le répertoire de révision. L'Agent doit surveiller ce fichier, confirmer que la vidéo coupée est bien générée et que sa taille est stable.
# Dans une autre tâche/terminal Agent, attendre le résultat du montage après validation utilisateur
node "$SKILL_DIR/scripts/watch_cut_done.js" "output/JJ-MM-AAAA_NomDeLaVideo/coupe_video/3_revision"
Le résultat de la surveillance retourne le chemin de la vidéo coupée :
{
"output": "output/JJ-MM-AAAA_NomDeLaVideo/coupe_video/3_revision/NomDeLaVideo_cut.mp4",
"newDuration": "123.45",
"outputSize": 12345678
}
Noter output du retour comme CUT_VIDEO ; les sous-titres suivants doivent être retranscrits à partir de cette vidéo.
Ne pas utiliser curl /api/cut ou de script pour simuler un clic, sauf autorisation explicite de l'utilisateur.
Étape 9 : Retranscrire depuis la vidéo coupée
"$SKILL_DIR/scripts/generate_srt_for_video.sh" "video_couplee.mp4" "output/JJ-MM-AAAA_NomDeLaVideo/sous_titres"
Les sous-titres doivent être retranscrits depuis la vidéo coupée, pas déduits des sous-titres originaux.
Cette étape ne produit que l'ébauche de transcription Volcengine :
output/JJ-MM-AAAA_NomDeLaVideo/sous_titres/1_transcription/volcengine_result.json
output/JJ-MM-AAAA_NomDeLaVideo/sous_titres/subtitles_with_time.json
output/JJ-MM-AAAA_NomDeLaVideo/sous_titres/3_sortie/video.raw.srt
Étape 10 : Correction AI des sous-titres
L'Agent doit lire video.raw.srt ou subtitles_with_time.json, et effectuer une correction AI en se référant au script / texte / noms propres / contexte fourni par l'utilisateur.
Règles de correction :
- Conserver la timeline originale, ne modifier de préférence que le texte des sous-titres.
- Corriger les termes techniques, noms d'outils, noms de personnes, mots anglais, homophones mal reconnus.
- Ajuster les coupures de phrases manifestement illogiques.
- Ne pas ajouter de contenu qui n'est pas prononcé dans la vidéo.
- Une fois la correction terminée, écrire dans
sous_titres/3_sortie/video.srt.
Étape 11 : Assembler le pack de base
Après la correction AI, rassembler la vidéo coupée et les sous-titres finaux dans le répertoire racine du projet :
OUTPUT_ROOT="output/JJ-MM-AAAA_NomDeLaVideo"
ln -sf "$CUT_VIDEO" "$OUTPUT_ROOT/source_cut.mp4"
ln -sf "$OUTPUT_ROOT/sous_titres/3_sortie/video.srt" "$OUTPUT_ROOT/subtitles.srt"
Le produit final comprend au moins :
output/JJ-MM-AAAA_NomDeLaVideo/sous_titres/3_sortie/video.srt
output/JJ-MM-AAAA_NomDeLaVideo/source_cut.mp4
output/JJ-MM-AAAA_NomDeLaVideo/subtitles.srt
Si l'utilisateur doit ensuite exécuter Production finale, organiser le produit sous cette forme mentale :
source_cut.mp4 = Vidéo face caméra coupée
subtitles.srt = Sous-titres SRT de la vidéo coupée, corrigés par AI
assets/ = Ressources optionnelles
source_cut.mp4 et subtitles.srt peuvent être des liens symboliques ; lors de la communication à l'utilisateur, indiquer clairement qu'ils pointent vers la vidéo coupée et les sous-titres de la vidéo coupée.
Règles strictes de révision
Jusqu'à l'étape de la page de révision, il faut s'arrêter et donner le lien à l'utilisateur.
Avant la confirmation de l'utilisateur, l'Agent ne peut faire que trois choses :
- Générer
review.html - Démarrer
review_server.js - Indiquer à l'utilisateur l'URL de la page de révision
Sauf si l'utilisateur dit explicitement "tu peux cliquer pour moi" ou "coupe directement", l'Agent n'est pas autorisé à :
- Appeler directement
/api/cut - Utiliser curl / script pour simuler un clic
- Sauter la page de révision pour générer directement la vidéo coupée
Après que l'utilisateur a cliqué sur « Exécuter le montage » sur la page de révision, le serveur ne fait que générer la vidéo coupée. L'Agent, après avoir détecté la fin de la vidéo coupée, peut entrer dans la phase de retranscription et de correction AI des sous-titres.
Format de données
subtitles_words.json
[
{"text": "大", "start": 0.12, "end": 0.2, "isGap": false},
{"text": "", "start": 6.78, "end": 7.48, "isGap": true}
]
auto_selected.json
[72, 85, 120] // Index présélectionnés générés par l'analyse Claude
Encodage du montage (règle stricte)
⚠️ Faire correspondre les paramètres de la vidéo source, ré-encoder avec une découpe image par image précise.
Méthode de travail de cut_video.sh :
- Détecter automatiquement les paramètres d'encodage de la vidéo source (codec/profile/pix_fmt/bitrate)
- Utiliser
filter_complexpour trim+concat avec une découpe image par image précise - Ré-encoder avec les mêmes paramètres :
-profile:v high -b:v {bitrate_source} -pix_fmt yuv420p
Clé : La qualité du ré-encodage dépend de la correspondance avec les paramètres de la source, pas d'une valeur CRF.
- ✅
-b:v {bitrate_source} -profile:v high -pix_fmt yuv420p→ indiscernable à l'œil nu - ❌ Uniquement spécifier
-crf Nsans spécifier profile/pix_fmt → peut introduire des écarts
Configuration
Clé API Volcengine
Si l'utilisateur n'a pas de clé API Volcengine, lui demander d'abord d'ouvrir la console Volcengine pour activer "Reconnaissance de fichier audio 2.0" et créer une clé API :
https://console.volcengine.com/speech/new/setting/activate?projectName=default
Ressource modèle par défaut actuelle :
Reconnaissance de fichier audio 2.0 / Seed ASR
resource_id = volc.seedasr.auc
Après avoir obtenu la clé, l'écrire dans le fichier .env du répertoire racine des Skills :
cd /Volumes/成峰/代码/剪辑Agent/.claude/skills
cp .env.example .env
# Éditer .env pour renseigner VOLCENGINE_API_KEY=xxx
Si installé via npm, le répertoire racine des Skills est généralement :
~/.claude/skills/chengfeng-videocut-skills
~/.codex/skills/chengfeng-videocut-skills