Audio-to-Text-IA

CLI para procesar archivos de audio/video y generar texto con IA. Esta herramienta permite convertir diferentes tipos de archivos (audio, video, texto, zip) en resúmenes o subtítulos utilizando inteligencia artificial.

Instalación

Requiere Python 3.10+ y ffmpeg instalado en el sistema.

# Recomendado (uv aísla el CLI en su propio entorno)
uv tool install audio-to-text-ia

# Alternativa con pipx
pipx install audio-to-text-ia

Después de instalar, el comando queda disponible globalmente:

audio-to-text-ia --help

Instalar ffmpeg

ffmpeg no se distribuye via pip. Instalalo con el gestor de tu sistema:

# Ubuntu/Debian/WSL
sudo apt install ffmpeg

# macOS (Homebrew)
brew install ffmpeg

# Windows (Chocolatey)
choco install ffmpeg

# Windows (Scoop)
scoop install ffmpeg

Si ffmpeg no está disponible, el CLI aborta con un mensaje indicando cómo instalarlo.

Instalar uv

Si todavía no tenés uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Características

• Procesamiento de audio a texto utilizando OpenAI Whisper
• Arquitectura modular y escalable
• Sistema de feature flags para habilitar/deshabilitar funcionalidades
• Soporte para múltiples tipos de archivos (audio, video, texto, zip)
• Diferentes opciones de generación (resúmenes, subtítulos)
• Procesamiento de exports ZIP de chats de WhatsApp con transcripción inline
• Fácil extensión para agregar nuevos comandos y tipos de archivos

Desarrollo (clonando el repo)

Si querés contribuir o correr desde el código fuente:

# 1. Clonar el repositorio
git clone https://github.com/bypabloc/audio-to-text-ia.git
cd audio-to-text-ia

# 2. Sincronizar dependencias (uv crea el venv automaticamente)
uv sync --group dev

uv lee pyproject.toml, resuelve uv.lock y crea .venv/ con la versión de Python compatible.

Uso

Modos de uso

El CLI tiene dos modos:

• Modo flags: pasás todos los argumentos por línea de comandos (ideal para scripts y repetir comandos).
• Modo interactivo: si ejecutás cli.py sin argumentos, entra en un selector con questionary que te guía paso a paso (subcomando, tipo de archivo, navegación de archivos por carpetas, modelo, idioma, fechas).

# Modo interactivo (sin argumentos)
uv run python cli.py

# Ver todos los flags disponibles
uv run python cli.py --help

# Mostrar versión y salir
uv run python cli.py --version

Si prefieres no anteponer uv run, activá el venv con source .venv/bin/activate.

Ejemplos rápidos

# Generar resumen de un archivo de audio
uv run python cli.py --generate resumen --type_file audio --file ruta/al/archivo.mp3

# Generar subtítulos de un archivo de video
uv run python cli.py --generate subtitle --type_file video --file ruta/al/video.mp4

# Especificar idioma de origen para la transcripción
uv run python cli.py --generate resumen --type_file audio --file ruta/al/archivo.mp3 --source_language es

# Traducir audio a inglés en lugar de transcribir en idioma original
uv run python cli.py --generate subtitle --type_file audio --file ruta/al/archivo.mp3 --translate

# Usar modelo más preciso (más lento, requiere más RAM/VRAM)
uv run python cli.py --generate resumen --type_file video --file ruta/al/video.mp4 --model large

# Procesar un ZIP que contiene varios archivos
uv run python cli.py --generate resumen --type_file zip --file ruta/al/archivos.zip

# Procesar export ZIP de WhatsApp transcribiendo audios/videos referenciados
uv run python cli.py --generate zip_whatsapp_chat --type_file zip --file ruta/al/chat-whatsapp.zip

# Procesar export ZIP de WhatsApp filtrando por rango de fechas
uv run python cli.py --generate zip_whatsapp_chat --type_file zip --file ruta/al/chat-whatsapp.zip \
  --fecha-inicio 01/03/2026 --fecha-fin 31/03/2026

# Mostrar al final el comando equivalente para repetirlo (útil después del modo interactivo)
uv run python cli.py --generate resumen --type_file audio --file ruta/al/archivo.mp3 --show-command

# Ejecutar sin persistir la configuración en .audio_to_text_config.json
uv run python cli.py --generate resumen --type_file audio --file ruta/al/archivo.mp3 --no-save-config

Instalación local desde el repo

Si estás trabajando sobre el código fuente y querés probar el comando instalado:

# Modo editable (cambios en el codigo se reflejan sin reinstalar)
uv pip install -e .

# O instalación global como herramienta desde el repo local
uv tool install .

# Usar el comando directamente
audio-to-text-ia --help

Para uso normal (no desarrollo), usá uv tool install audio-to-text-ia desde PyPI — ver sección Instalación.

Comandos disponibles

El CLI soporta los siguientes flags. Si invocás cli.py sin flags, entra en modo interactivo. Los flags --generate, --type_file y --file son obligatorios fuera del modo interactivo.

--generate {resumen,subtitle,zip_whatsapp_chat}

Tipo de generación a realizar:

• resumen: Genera un resumen extractivo del contenido transcrito.
• subtitle: Genera subtítulos sincronizados a partir del audio/video.
• zip_whatsapp_chat: Procesa un export ZIP de WhatsApp transcribiendo los audios/videos referenciados y reinyectando las transcripciones dentro del TXT del chat.

--type_file {audio,video,text,zip}

Tipo de archivo a procesar:

• audio: Archivos de audio (mp3, wav, ogg, opus, etc.).
• video: Archivos de video (mp4, avi, mov, etc.). Se extrae el audio con ffmpeg antes de transcribir.
• text: Archivos de texto plano.
• zip: Archivos comprimidos. Tiene dos rutas distintas según --generate:
  • Con resumen o subtitle: extrae todo y procesa cada archivo individualmente.
  • Con zip_whatsapp_chat: procesa el TXT del chat reinyectando las transcripciones de los audios/videos.

--file <path>

Ruta al archivo que se va a procesar. Acepta rutas relativas o absolutas.

--source_language <code>

Código ISO 639-1 del idioma de origen (es, en, fr, de, it, pt, ru, ja, zh, ...). Si no se especifica, Whisper detecta el idioma automáticamente. Especificarlo mejora velocidad y precisión.

--target_language <code>

Código del idioma de destino para la traducción. Whisper actualmente solo soporta traducción a en (inglés).

--translate

Flag booleano que cambia la tarea de Whisper de transcribe a translate. Por limitación del modelo, solo traduce a inglés. Se puede combinar con --source_language para indicarle el idioma de origen.

--model {tiny,tiny.en,base,base.en,small,small.en,medium,medium.en,large,turbo}

Modelo de Whisper a utilizar. Default: base. Las variantes con sufijo .en son solo inglés (más rápidas para inglés). Trade-off entre precisión, velocidad y consumo de RAM/VRAM:

Modelo	Tamaño aprox.	Velocidad	Multilingüe
tiny	~1 GB VRAM	Muy rápida	Sí
base	~1 GB VRAM	Rápida (default)	Sí
small	~2 GB VRAM	Media	Sí
medium	~5 GB VRAM	Lenta	Sí
large	~10 GB VRAM	Muy lenta	Sí
turbo	~6 GB VRAM	~8x más rápida que large	Sí

Las variantes .en (tiny.en, base.en, small.en, medium.en) están optimizadas solo para inglés.

--no-save-config

Por defecto el CLI guarda la última configuración usada en .audio_to_text_config.json en el directorio actual (modelo, archivo, idiomas, etc.) para que la próxima ejecución la sugiera. Este flag desactiva esa persistencia.

--show-command

Al finalizar la ejecución, imprime el comando completo equivalente para repetirla sin pasar por el modo interactivo. Útil cuando usás el modo interactivo y querés guardarte el comando.

--version

Imprime la versión instalada de audio-to-text-ia y sale.

--fecha-inicio DD/MM/YYYY / --fecha-fin DD/MM/YYYY

Solo aplica con --generate zip_whatsapp_chat. Filtra los mensajes del chat de WhatsApp por rango de fechas (inclusive en ambos extremos). Formato obligatorio DD/MM/YYYY. Si especificás solo una de las dos, se filtra desde/hasta esa fecha.

Desarrollo y pruebas

Estructura del proyecto

audio-to-text-ia/
├── commands/           # Comandos disponibles
├── config/             # Configuraciones
├── docs/               # Documentación detallada
├── exceptions/         # Excepciones personalizadas
├── factories/          # Factories para tipos de archivos
├── services/           # Servicios (Whisper, WhatsApp, etc.)
├── tests/              # Pruebas unitarias
├── utils/              # Utilidades (feature flags, logger, etc.)
├── cli.py              # Punto de entrada principal
├── pyproject.toml      # Metadata, dependencias y config de tests
└── uv.lock             # Lockfile de uv

Ejecución de pruebas

# Ejecutar todas las pruebas (sin coverage, rapido)
uv run pytest --no-cov

# Ejecutar pruebas con cobertura (apunta a las carpetas reales)
uv run pytest

Configuración de feature flags

Las características del CLI pueden habilitarse o deshabilitarse mediante feature flags:

from commands.generate import Generate
from factories.type_files import TypeFiles
from utils.feature_flags import FeatureFlags

# Obtener instancia de FeatureFlags
feature_flags = FeatureFlags()

# Deshabilitar un tipo de generación específico
feature_flags.disable("Generate.resumen")

# Deshabilitar un tipo de archivo específico
feature_flags.disable("TypeFiles.audio")

# Deshabilitar completamente un comando o factory
generate_command = Generate()
generate_command.is_available = False

Construcción del paquete

# Construir distribuciones (sdist + wheel)
uv build

# Esto generará archivos en la carpeta dist/

Documentación adicional

• Guía de instalación de Python: Instrucciones detalladas para instalar y configurar Python.
• Guía de configuración de Whisper: Instrucciones para instalar y configurar las dependencias necesarias para Whisper.

Licencia

MIT

Autor

Pablo Contreras (pacg1991@gmail.com)