README_FINAL.md

Desgrabador AI — Instrucciones finales para Hugging Face Spaces (Docker)

Checklist mínimo para subir a HF Spaces (Docker)

1. Repositorio limpio

   • Asegurate de NO subir app_cache/, app_tmp/, python_embebido/ ni speechbrain_pretrained/.
   • .dockerignore y .gitignore ya incluyen estas rutas para evitar que entren en el contexto de build y en commits futuros.

2. Dockerfile presente

   • Este repo contiene Dockerfile configurado para CPU-only y con ENTRYPOINT a scripts/entrypoint.sh.

3. Variables de entorno en la Space

   • Si quieres permitir que la Space descargue modelos en runtime, define HF_TOKEN en Settings → Secrets.
   • Alternativamente, subí modelos pre-descargados (no recomendado por tamaño).

4. Puertos y binding

   • La aplicación escucha en 0.0.0.0:7860 dentro del contenedor (requisito de HF Spaces).

5. Tamaño de imagen

   • Imagen de ejemplo construida localmente pesa ~14.3GB (sin incluir modelos). Si decidís incluir modelos, el tamaño crecerá mucho.

6. Recomendación

   • Usar runtime download con HF_TOKEN y app_cache montado para pruebas locales.

Pasos rápidos para publicar

1. Subir este repo a un nuevo Space en Hugging Face.
2. En la configuración de la Space, seleccionar "Use your own Dockerfile".
3. En Settings → Secrets, añadir HF_TOKEN (si querés permitir descargas automáticas).
4. Desplegar y verificar logs. Si algo falla, consultar ui_runtime_log.txt y los logs del contenedor.

Notas sobre seguridad

• No dejes HF_TOKEN.txt en repositorios públicos si contiene tu token.

Si querés que también elimine python_embebido/ e app_cache/ del repositorio (borrado físico y del historial git), decímelo y lo hacemos con cuidado: listaré los archivos que se eliminarán y te pediré confirmación antes del cambio destructivo.

DesgrabadorAI - Sistema Inteligente

🚀 Inicio Rápido

1. Ejecutar: Doble clic en EJECUTAR_DesgrabadorAI.bat
2. Acceder: Se abrirá automáticamente en http://127.0.0.1:7860
3. Usar: Arrastra archivos de audio y procesa

📦 ¿Es 100% Portátil?

✅ SÍ - Esta carpeta es completamente portátil después del setup:

• ✅ Python embebido: Incluido (no requiere Python instalado)
• ✅ Librerías CUDA: Todas las DLLs incluidas en PyTorch
• ✅ cuDNN: Incluido (cudnn64_9.dll + módulos)
• ✅ Cache local: Configurado para usar carpetas locales (app_cache/, app_tmp/)
• ✅ Modelos pre-descargados: WhisperX y SpeechBrain incluidos
• ✅ Fallback automático: SpeechBrain cuando no hay token HF

🎯 SOLO REQUIERE:

• GPU NVIDIA (RTX 2060+, RTX 3060+ recomendada)
• Drivers NVIDIA actualizados (versión 522+)
• Windows 10/11 x64

🔧 Setup para Distribución (Solo UNA VEZ)

Para crear un paquete 100% offline que funcione sin internet:

Paso 1: Ejecutar Setup Offline

# Doble clic en:
SETUP_OFFLINE.bat

Este script:

• ✅ Descarga modelos Whisper (large-v3, medium, base) ~3GB
• ✅ Descarga modelos de alineación (ES, EN, PT, FR)
• ✅ Configura cache local en app_cache/
• ✅ Prepara todo para funcionamiento offline

Paso 2: Configurar Token HF (Opcional)

# Crear/editar archivo:
hf_token.txt

# Agregar tu token de HuggingFace:
hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Nota: Sin token, el sistema usa automáticamente SpeechBrain (offline).

Paso 3: Crear Paquete Distribuible

# 1. Zipear TODA la carpeta DesgrabadorAI
# 2. El ZIP resultante es 100% portátil
# 3. Funciona offline en cualquier PC con GPU NVIDIA

💾 Para usar en otro PC:

1. Extraer ZIP en cualquier ubicación
2. Ejecutar EJECUTAR_DesgrabadorAI.bat
3. ¡Listo! Funciona sin internet

📋 Requisitos del Sistema

• ✅ GPU: NVIDIA RTX 3060 (12GB VRAM) - OPTIMIZADO
• ✅ Drivers: NVIDIA 522.06+
• ✅ OS: Windows 10/11 x64
• ✅ Token HuggingFace: Configurado en hf_token.txt

🎯 Características

• Transcripción: WhisperX Large-v3 (máxima precisión)
• Diarización Inteligente: Selección automática SpeechBrain/PyAnnote
• Fallback Automático: Sin token HF → usa SpeechBrain offline
• Cache Local: Sin dependencias del sistema (%TEMP%, %APPDATA%)
• Formatos: MP3, WAV, FLAC, M4A, MP4, OGG
• Exportación: DOCX con formato profesional
• Arquitectura: Subprocess optimizado para estabilidad CUDA

📁 Estructura de Portabilidad

📁 DesgrabadorAI/
├── 🚀 EJECUTAR_DesgrabadorAI.bat     # ← EJECUTAR AQUÍ
├── 🔧 SETUP_OFFLINE.bat             # ← Setup para distribución
├── 🐍 desgrabador_usuario_final.py   # Aplicación principal
├── 🔄 transcriber_subprocess.py      # Transcripción optimizada
├── 🔄 alignment_subprocess.py        # Alineación optimizada
├── 🔑 hf_token.txt                   # Token HuggingFace (opcional)
├── 📁 python_embebido/               # Entorno Python completo
│   └── 📁 Lib/site-packages/torch/lib/ # ← DLLs CUDA incluidas
├── 📁 app_cache/                     # Cache local (modelos descargados)
├── 📁 app_tmp/                       # Temporales locales
├── 📁 speechbrain_pretrained/        # Modelos de diarización
└── 📁 outputs/                       # Resultados finales

⚡ Modo de Operación

🧠 Diarización Inteligente

El sistema selecciona automáticamente el mejor método:

1. Con Token HF válido:

   • 3+ speakers estimados → PyAnnote (máxima precisión)
   • 1-2 speakers → SpeechBrain (más rápido)

2. Sin Token HF:

   • Fallback automático a SpeechBrain
   • Mensaje informativo: "usando fallback offline"
   • Sin pérdida de funcionalidad

3. Configuración manual: Dropdown en UI para forzar método

⚡ Rendimiento

• Velocidad: ~2-3x tiempo real con RTX 3060
• Estabilidad: Arquitectura de subprocess para máxima confiabilidad
• Memoria: Gestión inteligente de VRAM 12GB

🛠️ Archivos Esenciales

📁 DesgrabadorAI/
├── 🚀 EJECUTAR_DesgrabadorAI.bat     # ← EJECUTAR AQUÍ
├── 🐍 desgrabador_usuario_final.py   # Aplicación principal
├── 🔄 transcriber_subprocess.py      # Transcripción optimizada
├── 🔄 alignment_subprocess.py        # Alineación optimizada
├── 🔑 hf_token.txt                   # Token HuggingFace
├── 📁 python_embebido/               # Entorno Python completo
│   └── 📁 Lib/site-packages/torch/lib/ # ← DLLs CUDA incluidas
└── 📁 speechbrain_pretrained/        # Modelos de diarización

🆘 Solución de Problemas

Si no inicia: Verificar que existe python_embebido/python.exe Si funciona lento: En CPU usa modelo base automáticamente Si falta token: Sistema usa automáticamente SpeechBrain (offline) Si hay errores CUDA: GPU NVIDIA con drivers 522.06+ requeridos

🔄 Setup Inicial (Primera Vez)

# Para máxima compatibilidad offline:
1. Ejecutar SETUP_OFFLINE.bat (descarga modelos ~3GB)
2. Opcional: Agregar token HF en hf_token.txt
3. Zipear carpeta completa
4. Distribuir ZIP (funcionará offline)

🎛️ Configuración Avanzada

Cache Local:

• app_cache/ - Modelos descargados
• app_tmp/ - Archivos temporales
• speechbrain_cache/ - Cache específico SB

Variables de Entorno (auto-configuradas):

HF_HOME=./app_cache/huggingface
TORCH_HOME=./speechbrain_cache/torch
GRADIO_TEMP_DIR=./app_tmp/gradio
TMPDIR=./app_tmp

🔊 Diarización (SpeechBrain / PyAnnote / None)

El sistema soporta tres modos con selección inteligente:

• SpeechBrain (offline, rápido, modelo ECAPA) → Recomendado por defecto
• PyAnnote (requiere token + descarga, más pesado)
• None (sin separar hablantes)

✅ Disponibilidad de SpeechBrain

Se considera disponible si puede importarse speechbrain. Si falta scikit-learn, el sistema usa un clustering interno fallback (k-means/cosine simplificado) y heurística para estimar oradores.

🧠 Flujo Interno SpeechBrain

1. Carga ECAPA (intenta LocalStrategy para evitar symlinks)
2. Si la versión no soporta LocalStrategy → fallback automático transparente
3. Segmentación → Embeddings → Estimación de N → Clustering (Spectral o fallback)

📝 Mensajes Log

• [SpeechBrain] LocalStrategy no soportada en esta versión -> fallback (...) → Informativo, no error.
• [SpeechBrain] Modelo cargado fallback (...) → Todo OK.
• 🔑 PyAnnote disponible pero token HF inválido/faltante -> usando fallback → Automático a SB.

📄 Si No Separa Voces

1. Un solo hablante real → Correcto
2. Audio ruidoso/solapado → Mejorar calidad
3. Voces muy parecidas → Requiere más duración o ajuste avanzado
4. Sin sklearn → Instalarla mejora precisión (opcional)

❌ Desactivar

Selecciona None en la interfaz.

---

DesgrabadorAI v2.1 - 100% Portátil | Cache Local | Fallback Automático