AutoSubtitle AI - Guia de Automação e Habilidade para Agentes

O que AutoSubtitle AI - Guia de Automação e Habilidade para Agentes faz?

Esta habilidade orienta sobre como automatizar extração de legendas, transcrição de fala para texto, alinhamento forçado de letras (pipeline Luna), revisão local por LLM e gravação de legendas hardsub com aceleração GPU usando o CLI auto-subtitle e o backend FastAPI.

---

📌 Matriz de Decisão de Fluxo de Trabalho

Escolha o comando ou pipeline apropriado com base nos ativos de entrada:

Cenário / Objetivo	Comando Recomendado	Argumentos Principais
Alinhamento de Letras (Música) (Mídia + letras .txt)	python src/cli/main.py luna (ou align)	<media> <lyrics.txt> --llm local/api -o <dir>
Fala / Palestra / Vídeo para Legendas (Sem roteiro)	python src/cli/main.py pipeline	<media> -d cuda -o <dir>
Extração Apenas de Áudio	python src/cli/main.py extract	<video> -o <audio.wav> --sr 16000
Corrigir Erros / Homófonos (com Edge LLM)	python src/cli/main.py proofread	<subtitles.srt> --gpu-layers -1
Gravar Legendas no Vídeo (Hardsub)	python src/cli/main.py burn	<video> <subtitles.srt> --css "..."
Gerenciar Fontes (Instalar fontes abertas / Windows)	python src/cli/main.py fonts	list, install <id/path/url>, remove <filename>
Iniciar Web Studio	python src/cli/main.py serve	--host 0.0.0.0 --port 8000

---

🛠️ Referência de Comandos CLI

1. Pipeline Luna de Letras (luna / align)

Executa o pipeline de verificação dupla em 5 etapas: extração de características acústicas Whisper + alinhamento stable-ts + auditoria de decisão com LLM + padding de legibilidade de +0.16s:

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

Entregáveis em --output-dir:

• lyrics.srt: Trilha de legenda SRT padrão.
• lyrics.vtt: Formato WebVTT para players web.
• lyrics.lrc: Formato LRC aprimorado com timestamps em milissegundos para players de música.
• lyrics.ass: Legendas ASS formatadas prontas para gravação com FFmpeg.
• cue_evidence.json: Evidências acústicas completas e métricas de confiança por linha.
• review.csv: Relatório detalhado de linhas anômalas e decisões de arbitragem do LLM.
• run_manifest.json: Hashes SHA-256 de integridade da mídia de origem e saídas.

2. Pipeline de Fala Ponta a Ponta (pipeline)

Pipeline automático de fala para talk shows, podcasts e palestras:

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

3. Revisão com LLM Local (proofread)

Executa o Qwen2.5-3B-Instruct GGUF local com offload GPU para corrigir erros de reconhecimento de fala:

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

4. Gravação de Legendas Hardsub com GPU (burn)

Grava legendas ASS estilizadas diretamente nos quadros do vídeo com aceleração GPU NVIDIA NVENC:

# Usando string CSS inline (Suporta opacidade, contorno externo, fonte, padding, cores)
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 usando uma folha de estilo CSS externa:
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 usando flags explícitas:
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. Gerenciamento de Fontes (fonts)

# Listar todas as fontes disponíveis, instaladas e do sistema Windows
python src/cli/main.py fonts list

# Instalar fontes open-source populares por ID predefinido:
# Opções: openhuninn (粉圓體), lxgw-wenkai (霞鶩文楷), iansui (芫荽體), win-msjhbd (微軟正黑粗體)
python src/cli/main.py fonts install openhuninn

# Instalar a partir de URL ou arquivo 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

---

🤖 Receitas de Automação

Receita 1: Processar em Lote Todos os Vídeos em um Diretório (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 "🚀 Processando: $filename"
  
  if [ -f "$lyrics" ]; then
    # Pipeline com roteiro (letras)
    python3 src/cli/main.py luna "$video" "$lyrics" --output-dir "$OUTPUT_DIR/$stem" --llm local
    sub_file="$OUTPUT_DIR/$stem/lyrics.srt"
  else
    # Pipeline sem roteiro (fala)
    python3 src/cli/main.py pipeline "$video" -d cuda --output-dir "$OUTPUT_DIR/$stem"
    sub_file="$OUTPUT_DIR/$stem/$stem.srt"
  fi
  
  # Gravar hardsubs com estilo de marca
  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 "✔ Finalizado: $stem"
done

Receita 2: Script Python de Geração de Legendas

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. Executar Pipeline Luna de Verificação Dupla
track = run_luna_pipeline(
    audio_path=media_file,
    lyrics_source=lyrics_file,
    output_dir=str(out_dir),
    llm_provider="local"
)

# 2. Definir Estilo de Legenda com Opacidade e Contorno Externo
style = SubtitleStyle.from_css(
    "font-size: 36px; color: #FFD700; opacity: 0.85; -webkit-text-stroke: 3px #000;"
)

# 3. Gravar Legendas diretamente com GPU NVENC
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"Vídeo com legendas criado: {burned_mp4}")

Receita 3: Integração com API REST (FastAPI)

O servidor roda em http://localhost:8000:

• Transcrever / Sem Roteiro: POST /api/ai/transcribe com campos Form media_path=..., auto_proofread=true
• Alinhar / Pipeline Luna: POST /api/ai/align com JSON {"media_path": "...", "script_text": "...", "script_mode": "reference", "llm_provider": "local"}
• Analisar CSS: POST /api/style/parse-css com JSON {"css": "font-size: 36px; opacity: 0.8;"}
• Gravar Vídeo: POST /api/burn com JSON {"video_path": "...", "subtitle_path": "...", "css": "..."}

---

🎨 Mapeamento de Modelo CSS para Estilo ASS

Ao projetar estilos de legenda com --css:

Propriedade CSS	Tradução para Formato ASS	Notas
opacity: 0.85	Alfa invertido hexadecimal &H26FFFFFF&	Alfa = round((1 - opacity) * 255). 0=opaco, 255=transparente.
-webkit-text-stroke: 4px #000	Outline: 2.0, OutlineColour: &H00000000&	Com paint-order: stroke fill;, o traço cresce apenas para fora.
text-shadow: 2px 2px 3px #000	Shadow: 2.0, BackColour: &H80000000&	Usa o maior deslocamento absoluto do eixo; CSS com eixos iguais faz round-trip sem deriva.
writing-mode: vertical-rl	Layout de coluna vertical com quebras \N	Quebra automaticamente da direita para a esquerda quando excede a altura da janela.
text-align: center/left/right	Mapeamento de alinhamento em grade 3x3 (1~9)	Centro-inferior = 2, Centro-superior = 8, Centro-meio = 5.
padding: 50px 40px 60px 40px	MarginV, MarginL, MarginR	Convertido para margens ASS em pixels relativas à resolução PlayRes.

---

⚠️ Notas de Implementação Importantes

1. Aceleração GPU:
   • Whisper: Toda inferência (roteirizada, não roteirizada e timeline fixa) usa Whisper nativo large-v3-turbo. O modelo e o backend são fixos; não passe opções de modelo ou tipo de computação.
   • Gravação de Vídeo: O padrão use_gpu=True tenta FFmpeg h264_nvenc. Use o CLI --cpu para libx264 quando NVENC não estiver disponível em tempo de execução.
2. Strings Multilinha de Letras vs Caminhos de Arquivo:
   • run_luna_pipeline aceita tanto um caminho de arquivo (.txt) quanto uma string bruta multilinha de letras; o CLI aceita um caminho TXT. Strings multilinha são analisadas diretamente sem verificação de sistema de arquivos.
3. Sem Sobrescrita de Legendas de Origem:
   • Ao gerar .srt ou .vtt, as saídas são escritas no diretório de saída alvo ou sufixadas com .generated.srt se um arquivo com o mesmo nome já existir.