nicko1122/auto-subtitle

AutoSubtitle AI - Guide de Compétence pour l'Automatisation et les Agents

Cette compétence vous guide sur la façon d'automatiser l'extraction de sous-titres, la transcription parole-texte, l'alignement forcé des paroles (pipeline Luna), la relecture via LLM local et la gravure vidéo accélérée par GPU en utilisant la CLI auto-subtitle et le backend FastAPI.

---

📌 Matrice de Décision du Flux de Travail

Choisissez la commande ou le pipeline approprié en fonction des actifs d'entrée :

Scénario / Objectif	Commande Recommandée	Arguments Clés
Chant / Alignement des Paroles (Média + .txt paroles)	python src/cli/main.py luna (ou align)	<media> <lyrics.txt> --llm local/api -o <dir>
Discours / Talk / Vidéo vers Sous-titres (Aucun script)	python src/cli/main.py pipeline	<media> -d cuda -o <dir>
Extraction Audio Uniquement	python src/cli/main.py extract	<video> -o <audio.wav> --sr 16000
Correction des Fautes / Homophones (avec Edge LLM)	python src/cli/main.py proofread	<subtitles.srt> --gpu-layers -1
Graver des Sous-titres dans la Vidéo (Hardsub)	python src/cli/main.py burn	<video> <subtitles.srt> --css "..."
Gérer les Polices (Installer des polices open-source / Windows)	python src/cli/main.py fonts	list, install <id/chemin/url>, remove <nom_fichier>
Lancer le Studio Web	python src/cli/main.py serve	--host 0.0.0.0 --port 8000

---

🛠️ Référence des Commandes CLI

1. Pipeline Luna Paroles (luna / align)

Exécute le pipeline de double vérification en 5 étapes : extraction des caractéristiques acoustiques Whisper + alignement stable-ts + audit par LLM décisionnel + padding de lisibilité de +0,16s :

python src/cli/main.py luna inputclip/test_video.mp4 inputclip/audio-org.txt \
    --llm local \
    --output-dir output_luna

Livrables dans --output-dir :

• lyrics.srt : Piste de sous-titres standard SRT.
• lyrics.vtt : Format WebVTT pour les lecteurs web.
• lyrics.lrc : Format LRC amélioré avec horodatages millisecondes pour les lecteurs de musique.
• lyrics.ass : Sous-titres ASS formatés prêts pour le brûlage FFmpeg.
• cue_evidence.json : Preuve acoustique complète et métriques de confiance par ligne.
• review.csv : Rapport détaillé des lignes anormales et des décisions d'arbitrage LLM.
• run_manifest.json : Hachages d'intégrité SHA-256 des sources média et des sorties.

2. Pipeline Parole de Bout en Bout (pipeline)

Pipeline automatique pour talk-shows, podcasts et conférences :

python src/cli/main.py pipeline inputclip/test_video.mp4 \
    --device cuda \
    --prompt "繁體中文" \
    --max-chars 16 \
    --pause 0.45 \
    --output-dir output/

3. Relecture Edge LLM (proofread)

Exécute Qwen2.5-3B-Instruct GGUF local avec déchargement GPU pour corriger les erreurs de reconnaissance vocale :

python src/cli/main.py proofread output/video.srt \
    --gpu-layers -1 \
    --batch-size 8 \
    --output output/video.proofread.srt

4. Gravure Vidéo Hardsub GPU (burn)

Grave les sous-titres ASS stylisés directement dans les images vidéo avec accélération GPU NVIDIA NVENC :

# Utilisation d'une chaîne CSS en ligne (supporte l'opacité, le contour extérieur, la police, le padding box-model, les couleurs)
python src/cli/main.py burn inputclip/test_video.mp4 output/lyrics.srt \
    --css "font-family: 'Noto Sans CJK TC'; font-size: 36px; color: #FFD700; opacity: 0.85; -webkit-text-stroke: 3px #000; text-shadow: 2px 2px 3px #000; padding: 40px 40px 60px 40px;" \
    -o output/final_burned.mp4

# Ou en utilisant une feuille de style CSS externe :
python src/cli/main.py burn inputclip/test_video.mp4 output/lyrics.srt \
    --css-file styles/youtube_style.css \
    -o output/final_burned.mp4

# Ou en utilisant des indicateurs explicites :
python src/cli/main.py burn inputclip/test_video.mp4 output/lyrics.srt \
    --font "jf-openhuninn-2.0" \
    --size 38 \
    --color "#FFFFFF" \
    --opacity 0.9 \
    --outline 3.0 \
    --outline-color "#000000" \
    --direction horizontal \
    --valign bottom \
    --halign center

5. Gestion des Polices (fonts)

# Lister toutes les polices disponibles, installées et système Windows
python src/cli/main.py fonts list

# Installer des polices open-source populaires par ID prédéfini :
# Options : openhuninn (粉圓體), lxgw-wenkai (霞鶩文楷), iansui (芫荽體), win-msjhbd (微軟正黑粗體)
python src/cli/main.py fonts install openhuninn

# Installer depuis une URL ou un fichier local :
python src/cli/main.py fonts install https://example.com/font.ttf
python src/cli/main.py fonts install /path/to/custom_font.otf

---

🤖 Recettes d'Automatisation

Recette 1 : Traitement par Lots de Toutes les Vidéos d'un Répertoire (Bash)

#!/usr/bin/env bash
set -e
INPUT_DIR="./raw_videos"
OUTPUT_DIR="./dist_videos"
mkdir -p "$OUTPUT_DIR"

for video in "$INPUT_DIR"/*.mp4; do
  [ -f "$video" ] || continue
  filename=$(basename "$video")
  stem="${filename%.*}"
  lyrics="$INPUT_DIR/$stem.txt"
  
  echo "🚀 Traitement : $filename"
  
  if [ -f "$lyrics" ]; then
    # Pipeline avec script de paroles
    python3 src/cli/main.py luna "$video" "$lyrics" --output-dir "$OUTPUT_DIR/$stem" --llm local
    sub_file="$OUTPUT_DIR/$stem/lyrics.srt"
  else
    # Pipeline parole sans script
    python3 src/cli/main.py pipeline "$video" -d cuda --output-dir "$OUTPUT_DIR/$stem"
    sub_file="$OUTPUT_DIR/$stem/$stem.srt"
  fi
  
  # Graver les hardsubs avec le style de marque
  python3 src/cli/main.py burn "$video" "$sub_file" \
    --css "font-size: 34px; color: #FFFFFF; opacity: 0.9; -webkit-text-stroke: 2.5px #000; text-shadow: 2px 2px #000;" \
    -o "$OUTPUT_DIR/${stem}_subtitled.mp4"
    
  echo "✔ Terminé : $stem"
done

Recette 2 : Script Python de Génération de Sous-titres

from pathlib import Path
from src.core.luna_pipeline import run_luna_pipeline
from src.core.video_burner import burn_subtitles_to_video
from src.schemas.subtitle import SubtitleStyle

media_file = "inputclip/test_video.mp4"
lyrics_file = "inputclip/audio-org.txt"
out_dir = Path("output_automation")

# 1. Exécuter le pipeline de double vérification Luna
track = run_luna_pipeline(
    audio_path=media_file,
    lyrics_source=lyrics_file,
    output_dir=str(out_dir),
    llm_provider="local"
)

# 2. Définir le style de sous-titre avec opacité et contour extérieur
style = SubtitleStyle.from_css(
    "font-size: 36px; color: #FFD700; opacity: 0.85; -webkit-text-stroke: 3px #000;"
)

# 3. Graver les sous-titres directement avec NVENC GPU
burned_mp4 = burn_subtitles_to_video(
    video_path=media_file,
    subtitles_source=str(out_dir / "lyrics.srt"),
    output_path=str(out_dir / "burned_output.mp4"),
    style=style,
    use_gpu=True
)
print(f"Vidéo gravée créée : {burned_mp4}")

Recette 3 : Intégration API REST (FastAPI)

Le serveur s'exécute sur http://localhost:8000 :

• Transcrire / Sans script : POST /api/ai/transcribe avec les champs de formulaire media_path=..., auto_proofread=true
• Aligner / Pipeline Luna : POST /api/ai/align avec JSON {"media_path": "...", "script_text": "...", "script_mode": "reference", "llm_provider": "local"}
• Analyser CSS : POST /api/style/parse-css avec JSON {"css": "font-size: 36px; opacity: 0.8;"}
• Graver Vidéo : POST /api/burn avec JSON {"video_path": "...", "subtitle_path": "...", "css": "..."}

---

🎨 Mapping du Box Model CSS et du Style ASS

Lors de la conception de styles de sous-titres avec --css :

Propriété CSS	Traduction au Format ASS	Notes
opacity: 0.85	Hex alpha inversé &H26FFFFFF&	Alpha = round((1 - opacity) * 255). 0=opaque, 255=transparent.
-webkit-text-stroke: 4px #000	Outline: 2.0, OutlineColour: &H00000000&	Avec paint-order: stroke fill;, le contour s'étend uniquement vers l'extérieur.
text-shadow: 2px 2px 3px #000	Shadow: 2.0, BackColour: &H80000000&	Utilise le plus grand décalage d'axe absolu ; les CSS à axes égaux font l'aller-retour sans dérive.
writing-mode: vertical-rl	Disposition en colonne verticale avec sauts \N	Retour à la ligne automatique de droite à gauche lorsque la hauteur du viewport est dépassée.
text-align: center/left/right	Mapping d'alignement en grille 九宮格 (1~9)	Bas-centre = 2, Haut-centre = 8, Milieu-centre = 5.
padding: 50px 40px 60px 40px	MarginV, MarginL, MarginR	Converti en marges ASS en pixels par rapport à la résolution PlayRes.

---

⚠️ Notes d'Implémentation Importantes

1. Accélération GPU :
   • Whisper : Toute inférence avec script, sans script ou à chronologie verrouillée utilise Whisper natif large-v3-turbo. Le modèle et le backend sont fixes ; ne transmettez pas d'options de modèle ou de type de calcul.
   • Gravure Vidéo : Par défaut use_gpu=True tente FFmpeg h264_nvenc. Utilisez --cpu en CLI pour libx264 lorsque NVENC n'est pas disponible à l'exécution.
2. Chaînes Multilignes de Paroles vs Chemins de Fichiers :
   • run_luna_pipeline accepte soit un chemin de fichier (.txt) soit une chaîne brute multiligne de paroles ; la CLI prend un chemin TXT. Les chaînes multilignes sont analysées directement sans vérification du système de fichiers.
3. Pas d'Écrasement des Sous-titres Sources :
   • Lors de la génération de .srt ou .vtt, les sorties sont écrites dans le répertoire de sortie cible ou suffixées de .generated.srt si un fichier du même nom existe.