📋 Manual de Empleo - Generador de Subtítulos

📚 Tabla de Contenidos

Introducción
Funcionalidades Principales
Requisitos del Sistema
Instalación
Instrucciones de Uso
Ejemplos Prácticos
Configuración Avanzada
Solución de Problemas
Referencia Técnica

🎯 Introducción

Este proyecto es un generador automático de subtítulos para archivos de video desarrollado en Python. El script procesa videos de manera inteligente, extrayendo el audio, transcribiéndolo a texto y generando archivos de subtítulos en formato SRT (SubRip).

¿Qué hace exactamente?

🔊 Extracción de Audio: Usa FFmpeg para extraer audio de cualquier formato de video
📝 Transcripción: Convierte audio a texto usando modelos de IA (Whisper)
🌐 Traducción (Opcional): Traduce subtítulos a múltiples idiomas
📁 Generación SRT: Crea archivos de subtítulos compatibles con reproductores multimedia

⚡ Funcionalidades Principales

Transcripción Inteligente

Whisper Local: Usa modelos de OpenAI Whisper para transcripción de alta calidad
Ollama Integration: Soporte para modelos de IA locales vía Ollama
Formato SRT: Genera subtítulos con timestamps precisos
Procesamiento por Lotes: Procesa múltiples videos automáticamente

Traducción Multilingüe

Google Translate: Traducción automática a 10+ idiomas
Ollama Translation: Traducción usando modelos de lenguaje locales
Idiomas Soportados: Español, Inglés, Francés, Alemán, Italiano, Portugués, Ruso, Japonés, Coreano, Chino

Gestión Automática de Archivos

Carpetas Organizadas: videos_entrada/ para entrada, videos_salida/ para salida
Limpieza Automática: Elimina archivos temporales automáticamente
Sobrescritura Inteligente: Pregunta antes de sobrescribir archivos existentes

🔧 Requisitos del Sistema

Dependencias Obligatorias

Software	Propósito	Instalación
Python 3.7+	Ejecutar el script	python.org
FFmpeg	Extraer audio de videos	ffmpeg.org

Dependencias Opcionales

Software	Propósito	Comando de Instalación
OpenAI Whisper	Transcripción local de alta calidad	`pip install openai-whisper`
PyTorch	Soporte para Whisper	`pip install torch torchvision torchaudio`
Googletrans	Traducción automática	`pip install googletrans==4.0.0rc1`
Ollama	Modelos de IA locales	ollama.ai

🚀 Instalación

1. Instalar Dependencias Básicas

nito@linux:~$ sudo apt update
nito@linux:~$ sudo apt install ffmpeg python3 python3-pip

2. Instalar Dependencias de Python

nito@linux:~$ pip install openai-whisper torch torchvision torchaudio
nito@linux:~$ pip install googletrans==4.0.0rc1

3. Verificar Instalación

nito@linux:~$ python generar.py --help

📖 Instrucciones de Uso

📋 Contenido del Archivo "empleo":

1. Uso Básico (Recomendado)

python generar.py

Qué hace: Procesa todos los videos en la carpeta videos_entrada/ usando Whisper local para transcripción.

2. Transcripción y Traducción al Español

python generar.py --translate

Qué hace: Genera subtítulos y los traduce automáticamente al español usando Google Translate.

3. Traducción a Otros Idiomas

# Traducción al inglés
python generar.py --translate --target-lang en

# Traducción al francés
python generar.py --translate --target-lang fr

# Traducción al alemán
python generar.py --translate --target-lang de

4. Usar Ollama para Traducción

python generar.py --translate --translation-method ollama

Nota: Requiere tener modelos de Ollama instalados y ejecutándose.

5. Especificar Modelo de Ollama

python generar.py --translate --translation-method ollama --translation-model mistral

6. Usar Ollama para Transcripción

⚠️ Advertencia: Ollama no está optimizado para transcripción. Se recomienda usar Whisper local.

python generar.py --use-ollama

7. Combinar Opciones

python generar.py --translate --target-lang en --translation-method ollama

Combina múltiples opciones para personalizar el procesamiento.

💡 Ejemplos Prácticos

Ejemplo 1: Procesamiento Básico

nito@linux:~/GENERAR_SUBTITULOS$ ls videos_entrada/
01_Introduction.mp4 02_Chapter1.mp4

nito@linux:~/GENERAR_SUBTITULOS$ python generar.py
=============================================
Procesando: 01_Introduction.mp4
=============================================
Extrayendo audio de videos_entrada/01_Introduction.mp4...
✓ Audio extraído correctamente
Usando Whisper local para transcripción...
✓ Modelo cargado en CPU
Transcribiendo audio...
Creando archivo SRT: videos_salida/01_Introduction.srt

✅ ¡Subtítulos generados exitosamente!
📁 Archivo: videos_salida/01_Introduction.srt

Ejemplo 2: Con Traducción

nito@linux:~/GENERAR_SUBTITULOS$ python generar.py --translate --target-lang en
=============================================
Procesando: 01_Introduction.mp4
=============================================
Extrayendo audio de videos_entrada/01_Introduction.mp4...
✓ Audio extraído correctamente
Usando Whisper local para transcripción...
Traduciendo subtítulos a en usando googletrans...
Traduciendo segmento 1/15...
Traduciendo segmento 2/15...
...
Creando archivo SRT: videos_salida/01_Introduction.srt

✅ ¡Subtítulos generados exitosamente!
🌐 Subtítulos traducidos a en usando googletrans
📁 Archivo: videos_salida/01_Introduction.srt

Ejemplo 3: Archivo Específico

python generar.py --video videos_entrada/01_Introduction.mp4

⚙️ Configuración Avanzada

Parámetros del Script

Parámetro	Descripción	Valor por Defecto
`-v, --video`	Procesar archivo específico	Todos los archivos
`-m, --model`	Modelo de Ollama para transcripción	dimavz/whisper-tiny
`--keep-audio`	Mantener archivo de audio temporal	false
`--use-ollama`	Usar Ollama para transcripción	false
`--use-whisper`	Usar Whisper local	true (por defecto)
`--translate`	Habilitar traducción	false
`--translation-method`	Método de traducción	googletrans
`--target-lang`	Idioma destino	es (español)
`--translation-model`	Modelo de Ollama para traducción	llama3.2

Estructura de Carpetas

GENERAR_SUBTITULOS/
├── generar_subtitulos.py # Script principal ├── empleo # Instrucciones de uso
├── manual.html # Este manual
├── videos_entrada/ # 📥 Colocar videos aquí
│ ├── video1.mp4
│ └── video2.mp4
└── videos_salida/ # 📤 Subtítulos generados
├── video1.srt
└── video2.srt

🔍 Solución de Problemas

Errores Comunes

❌ FFmpeg no encontrado

Error: Faltan dependencias: ffmpeg

Solución:

sudo apt install ffmpeg # Ubuntu/Debian
# o
sudo yum install ffmpeg # CentOS/RHEL
# o
brew install ffmpeg # macOS

❌ Whisper no instalado

Whisper no está instalado. Instala con: pip install openai-whisper

Solución:

pip install openai-whisper torch torchvision torchaudio

❌ Problemas con PyTorch

Error en transcripción con Whisper: [PyTorch error]

Solución:

# Para CPU only (recomendado)
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# Para GPU (si tienes CUDA)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

💡 Consejos Útiles

Usa --keep-audio para inspeccionar archivos de audio si hay problemas
Verifica que los videos estén en formato compatible (.mp4, .avi, .mkv, etc.)
Asegúrate de tener suficiente espacio en disco para archivos temporales
Para mejor rendimiento, instala PyTorch con soporte GPU

📚 Referencia Técnica

Formato SRT

Los archivos SRT (SubRip) tienen la siguiente estructura:

1
00:00:01,500 --> 00:00:04,000
Hola, bienvenidos al tutorial

2
00:00:04,500 --> 00:00:07,200
En este video aprenderemos...

Flujo de Trabajo Interno

Validación: Verifica dependencias y archivos de entrada
Extracción: FFmpeg extrae audio del video
Transcripción: Whisper convierte audio a texto con timestamps
Traducción (Opcional): Traduce segmentos usando Google Translate u Ollama
Formateo: Convierte a formato SRT con timestamps precisos
Guardado: Almacena archivo en carpeta de salida
Limpieza: Elimina archivos temporales

Códigos de Idioma

Código	Idioma	Código	Idioma
`es`	Español	`en`	Inglés
`fr`	Francés	`de`	Alemán
`it`	Italiano	`pt`	Portugués
`ru`	Ruso	`ja`	Japonés
`ko`	Coreano	`zh`	Chino