Cliente Python para Whisper ASR Webservice Local

Este proyecto contiene un script de Python diseñado para interactuar con una instancia local del Whisper ASR Webservice (u otro compatible) corriendo en Docker. El script puede tomar un archivo de audio o video como entrada, extraer/convertir el audio a formato WAV, enviarlo al servicio para transcripción, y mostrar los resultados detallados, incluyendo el tiempo total empleado.

Descripción

El script automatiza el proceso de:

1. Tomar un archivo de entrada (probado con MP4, pero adaptable a otros formatos soportados por MoviePy/FFmpeg).
2. Convertir el audio del archivo de entrada a formato WAV (pcm_s16le), necesario o preferido por muchos sistemas ASR. Utiliza moviepy (que a su vez usa FFmpeg) para esta conversión.
3. Comunicarse con el endpoint /asr de un servicio Whisper ASR Webservice local.
4. Enviar el archivo WAV al servicio, especificando parámetros como la tarea (transcribe o translate), idioma (o autodetección), y formato de salida esperado (json).
5. Manejar la comunicación HTTP, enviando los parámetros de control en la URL (como requiere la API consultada) y estableciendo cabeceras adecuadas (Accept: application/json).
6. Interpretar la respuesta del servidor, incluso si este devuelve un Content-Type incorrecto (como text/plain) pero el cuerpo contiene JSON válido.
7. Mostrar un resumen de la comunicación (URL, estado, cabeceras, cuerpo de respuesta raw).
8. Presentar la transcripción final de forma clara, incluyendo idioma detectado, texto completo y segmentos individuales con marcas de tiempo.
9. Medir y mostrar el tiempo total de ejecución del proceso.

Características Principales

• Soporte para múltiples formatos de entrada (dependiente de FFmpeg).
• Conversión de audio a WAV estandarizado.
• Comunicación específica adaptada a la API del Webservice (parámetros en URL).
• Interpretación robusta de la respuesta JSON (incluso con Content-Type incorrecto).
• Visualización detallada de la transcripción (texto completo y segmentos).
• Medición del tiempo de conversión, llamada API y total.
• Salida informativa del proceso y la comunicación.

Requisitos Previos

1. Python: Versión 3.7 o superior (requerido por las versiones recientes de MoviePy).
2. Librerías Python:
   • requests: Para realizar las llamadas HTTP.
   • moviepy: Para la manipulación y conversión de audio/video.
3. FFmpeg: Esencial. MoviePy depende de FFmpeg para leer la mayoría de los formatos de audio/video (incluyendo MP4) y para realizar las conversiones. Debes descargar e instalar FFmpeg y asegurarte de que el ejecutable ffmpeg esté accesible en el PATH de tu sistema. Puedes verificarlo ejecutando ffmpeg -version en tu terminal.
4. Instancia de Whisper ASR Webservice: El script está diseñado para conectarse a un servicio local, típicamente corriendo en Docker. Debes tener una instancia funcionando y accesible desde la máquina donde ejecutas el script. El ejemplo usa la implementación de ahmetoner/whisper-asr-webservice, pero podría funcionar con otras APIs similares.

Instalación

1. Clona o descarga este repositorio/script.
2. Crea y activa un entorno virtual (recomendado):
   • Usando venv:

     python -m venv .venv
     # En Windows:
     .\.venv\Scripts\activate
     # En Linux/macOS:
     source .venv/bin/activate
     

   • Usando conda:

     conda create -n whisper_env python=3.9 # O la versión que prefieras >= 3.7
     conda activate whisper_env
     

3. Instala las dependencias de Python:

   pip install requests moviepy
   

4. Instala FFmpeg: Sigue las instrucciones en ffmpeg.org para tu sistema operativo. Verifica que esté en el PATH.
5. Configura y ejecuta tu contenedor Docker de Whisper ASR Webservice. Consulta la documentación de la imagen Docker que estés usando. Asegúrate de conocer la dirección IP y el puerto donde está escuchando (p. ej., 192.168.88.26:9005).

Configuración del Script

Abre el archivo de script Python (.py) y modifica las variables en la sección # --- Configuración --- según tus necesidades:

• WHISPER_API_URL: ¡Importante! Cambia esto a la URL base de tu servicio Docker (p. ej., "http://TU_IP_NAS:PUERTO/asr").
• INPUT_MP4_PATH: Ruta a tu archivo de video o audio de entrada.
• TEMP_WAV_BASENAME: Nombre base para los archivos WAV temporales que se crean.
• API_LANGUAGE: Código del idioma del audio (p.ej., 'es', 'en') o déjalo como None para que Whisper intente detectarlo automáticamente.
• API_TASK: La tarea a realizar. 'transcribe' (audio a texto en el mismo idioma) o 'translate' (audio a texto en Inglés).
• API_OUTPUT_FORMAT: Formato de salida solicitado (probablemente 'json' para obtener detalles como segmentos).
• API_ENCODE: Parámetro de la API (generalmente True).

Uso

1. Asegúrate de que tu entorno virtual (si usas uno) esté activado.
2. Asegúrate de que tu contenedor Docker de Whisper ASR Webservice esté corriendo y sea accesible en la URL configurada.
3. Ejecuta el script desde la terminal:

   python tu_script.py
   

   (Reemplaza tu_script.py con el nombre real de tu archivo).

El script mostrará mensajes indicando el progreso (conversión, envío a la API), detalles de la comunicación HTTP, y finalmente el resultado de la transcripción interpretado y el tiempo total empleado.

Ejemplo de Salida (Sección Final)

Limpiando archivo temporal 'd:\Proyectos\Scripts\Whisper\from_docker\temp_audio_direct_conversion_1745613564.wav'... Limpieza completada.

--- Resultado Final Interpretado --- ¡Respuesta interpretada como JSON exitosamente!

Idioma Detectado: en

Transcripción Completa:

--- Resultado Final Interpretado --- ¡Respuesta interpretada como JSON exitosamente!

Idioma Detectado: en

Transcripción Completa:

Idioma Detectado: en

Transcripción Completa:

Transcripción Completa:

---

Listen and match. 1. Hello, my name's Max. I'm from Germany. In Germany, we hang Easter eggs in the trees. In my garden, there's a tree with eggs. Yellow, green, blue, orange, pink and purple. 2. Hi, my name's Daria. I'm from Ukraine. Easter eggs in Ukraine are lots of colors. There are patterns with triangles, circles and stars. They're beautiful. 3. Hi, my name's Adam. I'm from Hungary. In Hungary, we paint Easter eggs. We decorate the eggs with flowers. The flowers are all different colors. 4. Hi, my name's Sophia. I'm from Greece. Easter eggs in Greece are red. 5. We dye the eggs. No patterns, just red eggs.

Segmentos Detallados: [00:00:00.000 --> 00:00:22.000] Listen and match. 1. Hello, my name's Max. I'm from Germany. In Germany, we hang Easter [00:00:22.000 --> 00:00:40.000] eggs in the trees. In my garden, there's a tree with eggs. Yellow, green, blue, orange, pink and purple. [00:00:40.000 --> 00:00:51.000] 2. Hi, my name's Daria. I'm from Ukraine. Easter eggs in Ukraine are lots of colors. [00:00:51.000 --> 00:01:02.000] There are patterns with triangles, circles and stars. They're beautiful. [00:01:02.000 --> 00:01:18.000] 3. Hi, my name's Adam. I'm from Hungary. In Hungary, we paint Easter eggs. We decorate the eggs with flowers. [00:01:18.000 --> 00:01:38.000] The flowers are all different colors. 4. Hi, my name's Sophia. I'm from Greece. Easter eggs in Greece are red. [00:01:38.000 --> 00:01:46.000] 5. We dye the eggs. No patterns, just red eggs.

--- Tiempo Total Empleado: 150.62 segundos (00:02:30.623) ---