haoyiyin/easy-subtitle

Cuándo usar

Usa esta habilidad cuando el usuario necesite:

• Generar subtítulos SRT a partir de un archivo de audio o vídeo (sin conexión, sin llamadas a API)
• Detectar automáticamente el idioma hablado en un archivo multimedia
• Corregir errores de transcripción de Whisper usando un guion original (texto original de la locución)
• Procesar por lotes archivos multimedia para obtener subtítulos

No usar para:

• Transcripción en tiempo real/en vivo (faster-whisper es sin conexión y por lotes)
• Formatos de salida distintos a SRT (solo se admite SRT)
• Transcripción basada en la nube (esto es solo local)

Procedimiento

1. Instalar dependencias: pip install faster-whisper. Instalar ffmpeg según tu sistema operativo:
   • macOS: brew install ffmpeg
   • Linux: sudo apt install ffmpeg (Debian/Ubuntu) o sudo dnf install ffmpeg (Fedora)
   • Windows: choco install ffmpeg (Chocolatey) o scoop install ffmpeg (Scoop), o descargar desde https://ffmpeg.org
2. Asegúrate de que el paquete easy-subtitle esté instalado: pip install -e . desde la raíz del proyecto.
3. Transcripción básica: Ejecuta easy-subtitle -i video.mp4 para generar video.srt con el idioma detectado automáticamente.
4. Especificar idioma: Ejecuta easy-subtitle -i audio.wav -l zh si conoces el idioma (más rápido y preciso que la detección automática).
5. Corregir con el guion original: Ejecuta easy-subtitle -i video.mp4 --original-text script.txt para alinear y corregir la transcripción usando el texto proporcionado.
6. Ajustar tamaño del modelo: Usa -m small para velocidad o -m large-v3 para precisión. El valor predeterminado es medium.
7. Ajustar VAD: Usa --vad-min-silence 1000 para una división por silencios más agresiva (contenido más silencioso). Usa --no-vad para desactivarlo.

Errores comunes

• La primera ejecución descarga el modelo (~1.5 GB para el nivel medio) — deja tiempo y espacio en disco adicional.
• La detección automática de idioma de Whisper puede ser poco fiable en clips muy cortos (<5 segundos) — usa -l para especificarlo manualmente.
• La alineación con el texto original funciona mejor cuando el guion coincide exactamente con el audio. Las improvisaciones, pausas e improvisaciones se dejarán como salida de Whisper.
• faster-whisper usa cuantización INT8 por defecto en CPU — es rápida pero ligeramente menos precisa que FP16 en GPU.
• ffmpeg debe instalarse por separado (no es un paquete Python).
  • macOS: brew install ffmpeg
  • Linux: sudo apt install ffmpeg
  • Windows: choco install ffmpeg o descargar desde https://ffmpeg.org

Verificación

1. Ejecuta easy-subtitle --version para confirmar la instalación.
2. Prueba la transcripción básica: easy-subtitle -i test_audio.mp3 -m tiny debería producir un archivo .srt rápidamente.
3. Verifica la salida SRT: ábrela en un reproductor de vídeo o comprueba que contenga bloques numerados con marcas de tiempo en formato HH:MM:SS,mmm --> HH:MM:SS,mmm.
4. Prueba la alineación con el texto original: proporciona un guion que coincida con el audio; la salida debe contener el texto exacto del guion, no la transcripción de Whisper.