Metadata-Version: 2.4
Name: audio-to-text-ia
Version: 0.1.1
Summary: CLI para procesar archivos de audio/video y generar texto con IA
Project-URL: Homepage, https://github.com/bypabloc/audio-to-text-ia
Project-URL: Repository, https://github.com/bypabloc/audio-to-text-ia
Author-email: Pablo Contreras <pacg1991@gmail.com>
License: MIT
License-File: LICENSE
Keywords: audio,cli,processing,text,video,whisper
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: coloredlogs>=15.0.1
Requires-Dist: numpy>=1.20.0
Requires-Dist: openai-whisper>=1.0.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: questionary>=2.1.0
Requires-Dist: tiktoken>=0.9.0
Requires-Dist: torch>=1.10.1
Provides-Extra: dev
Requires-Dist: build>=0.10.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Audio-to-Text-IA

[![PyPI version](https://img.shields.io/pypi/v/audio-to-text-ia.svg)](https://pypi.org/project/audio-to-text-ia/)
[![Python versions](https://img.shields.io/pypi/pyversions/audio-to-text-ia.svg)](https://pypi.org/project/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`](https://ffmpeg.org/) instalado en el sistema.

```bash
# 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:

```bash
audio-to-text-ia --help
```

### Instalar `ffmpeg`

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

```bash
# 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`:

```bash
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:

```bash
# 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).

```bash
# 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

```bash
# 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:

```bash
# 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](#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

```text
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

```bash
# 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:

```python
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

```bash
# Construir distribuciones (sdist + wheel)
uv build

# Esto generará archivos en la carpeta dist/
```

## Documentación adicional

- [Guía de instalación de Python](docs/python-setup.md): Instrucciones detalladas para instalar y configurar Python.
- [Guía de configuración de Whisper](docs/whisper_setup.md): Instrucciones para instalar y configurar las dependencias necesarias para Whisper.

## Licencia

[MIT](LICENSE)

## Autor

Pablo Contreras (<pacg1991@gmail.com>)
